Creating a Theme

Looking to create a custom theme for the Blamite Editing Kit? This is the place to look!

Preparing a Theme Folder#

The first step in creating a theme is to create a new folder within the Editing Kit theme directory. For user-generated themes, this would be under %AppData%/Elaztek Studios/Blamite/editor_themes/. For the purposes of this tutorial, we'll be using a folder named example_theme.

Creating a Theme Definition File#

Once you've got your folder created, the next step is to create a file named theme.xml within it. For convenience, we've provided a skeleton theme.xml file below:

<?xml version="1.0" encoding="utf-8"?>
<hek_skin>
    <name>Example Theme</name>
    <author>Elaztek Studios</author>
    <description>An example theme for the theme creation tutorial.</description>
    <version>1.0.0</version>
    <base_qt_style>windowsvista</base_qt_style>
    <stylesheets>
        <stylesheet>css/base.css</stylesheet>
    </stylesheets>
    <variants>
        <variant name="Default">
            <property name="accentColor">#00b4ff</property>
            <property name="accentForeground">#ffffff</property>
        </variant>
        <variant name="Gold">
            <property name="accentColor">#ffdd15</property>
            <property name="accentForeground">#000000</property>
        </variant>
    </variants>
    <resource_groups>
        <hek_resources group_id="shared">
            <resource id="mdi_background">img/mdi_background.png</resource>
        </hek_resources>
    </resource_groups>
</hek_skin>

Let's go through each of these properties one by one.

name - This is the display name of your theme.
author - This is the author of the theme. It can be your name, username, or anything you want, really.
description - This is a brief description of your theme.
version - This is the version of the theme.
base_qt_style - This is the base Qt style that the theme will use by default. In most cases, this can be left as windowsvista, but windows and fusion may also be used (on Windows 7).

Now, we'll start going through the next few sections of the theme.

Stylesheets#

This is where most of the magic happens. Within the stylesheets section, you can have any number of stylesheets referenced. When the theme is loaded, these are all loaded as a single stylesheet and applied to the application.

All stylesheet paths are relative to the theme directory. So, given our theme being example_theme, and having a stylesheet entry set to css/base.css, the file path for the stylesheet would be:

{Editing Kit Root}/editor_themes/user/example_theme/css/base.css

Stylesheets are a feature of Qt, which is the GUI framework that is used by most of the Editing Kit. You can find a few guides on creating stylesheets for Qt applications below.

Referencing Assets#

If you need to reference an asset on disk, such as an image or icon, place the file within the theme folder. From there, you can use relative paths to any assets - but you must start all paths with {theme_root}. This placeholder is replaced with the file path to the theme directory at runtime.

For example, if you have an icon named chevron_down.svg located within an img folder within the theme directory, then in the stylesheet, you'd reference that image with {theme_root}/img/chevron_down.svg.

Referencing Resources#

Resources are documented further below under the Resource Overrides section.

An alternative way to reference certain files on disk is to use resource placeholders. This may be desirable if you wish to reference a resource that is either already overridden in your theme, or is already part of the Editing Kit resources directory - without having to include a copy. This also means that as long as the resource ID and group ID are not changed, you don't have to worry about using specific file paths.

To reference a resource in a theme's stylesheet, use the following syntax, replacing GROUP_ID and RESOURCE_ID accordingly:

{resource group="GROUP_ID" id="RESOURCE_ID"}

Testing Stylesheets in Real-Time#

To test stylesheets in real-time, open the Settings dialog for any of the Editing Kit programs (Foundry, Sapien, Guerilla) and go to the theme change section. From there, you'll find two buttons:

Open Theme Editor - This will open the Style Editor, with a blank stylesheet input. You can write any Qt stylesheet code in here and apply it in real-time.
Edit Current - This will open the Style Editor with Qt's current stylesheet pre-loaded.

A few notes about using the Style Editor:

Variant and theme directory placeholders are not evaluated - You cannot use these when using the Style Editor. When loading the current theme within the editor, these values are already evaluated.
The active theme is still applied within the Style Editor - If you wish to create a new theme, you should select the appropriate default Qt theme before using the editor. Otherwise, the selected theme's styles may conflict with yours.
Applying styles globally will override any active theme - If you have a theme applied and you apply a custom stylesheet to the entire application, the selected theme will be overwritten with your stylesheet until a different theme is selected, or the application is restarted.

Variants#

Variants are used to allow for simple modifications to a theme without creating an entirely new theme. This could be used for virtually anything, though in this example, we'll be using it to allow for a customizable accent color.

The usage of theme variants is optional. If you wish to disable variant support, simply remove the entire <variants> group. If you choose to add variants to your theme, you must have a variant named Default, and it must contain all properties you wish to allow to be tweaked through variants.

Using Variant Properties#

Once you've created your variants, you can use them within the stylesheet. For example, let's consider the property named accentColor. In any place where you want a color to be controlled by the user's chosen variant, then instead of a normal color value (ie, #cecece), you would instead simply use {accentColor}. That's it. The placeholder is replaced in realtime whenever the theme is applied.

Resource Overrides (`resource_groups`)#

The various editing tools will utilize a variety of resources within their UI. Anywhere you see an icon or image, you can bet that it's usually one of these. These resources can be overridden on a per-theme basis, if you like. As with variants, these are optional. If you wish to not override any resources, simply remove the <resource_groups> group from the file.

If you wish to override any resources, you should first take a look at the default resource group files. You can find these under {Editing Kit Root}/content/editor/. In that folder, you'll find a series of subfolders, each containing a variety of resources and a file named resources.xml.

The syntax for overriding these resources is the same as what is found within each resources.xml. Let's take a look at Guerilla's resource file:

<hek_resources group_id="guerilla">
    <resource id="main_icon">main_icon/guerilla_icon_v2_gradient.png</resource>

    <resource id="ws_preview_mdi_left">workspace_preview/mdi_left.png</resource>
    <resource id="ws_preview_mdi_right">workspace_preview/mdi_right.png</resource>
    <resource id="ws_preview_mdi_top">workspace_preview/mdi_top.png</resource>
    <resource id="ws_preview_mdi_bottom">workspace_preview/mdi_bottom.png</resource>
    <resource id="ws_preview_tabs_left">workspace_preview/tabs_left.png</resource>
    <resource id="ws_preview_tabs_right">workspace_preview/tabs_right.png</resource>
    <resource id="ws_preview_tabs_top">workspace_preview/tabs_top.png</resource>
    <resource id="ws_preview_tabs_bottom">workspace_preview/tabs_bottom.png</resource>
</hek_resources>

Each resource group has a unique group_id. This is the same ID that you'll want to specify in any groups that you're overriding. Each resource id is unique within a given resource group. For instance, multiple groups can contain a resource named main_icon - but they can only contain one resource named main_icon.

When overriding resources, you only need to include the <resource> nodes for resources that you intend to override. Any others can be excluded, and the default resources will be used instead. Once you've selected the resources you wish to override, all you need to do is specify the new path to the resource. Just like stylesheets, these should be relative to the current theme directory.

Using your Theme#

Once you've created your theme, you can apply it just as you would any other theme. Open your desired program and apply the theme from the Settings dialog.

If you wish to share your theme, you can add it to a ZIP (or other archive format) and upload it to the Elaztek website by visiting this page.