GUI Themes/Specs

Since the merge of the new GUI into the ScummVM trunk, all documentation regarding the legacy GUI is now obsolete. Hence, this page has been updated with the details of the new Theme format.

Theme Packages

A theme file in the new version of the ScummVM GUI is a compressed ZIP file which contains all the required information

One or more STX (ScummVM Theme XML) files.
Any external Bitmap fonts.
Any external Bitmap images.
A THEMERC file.

The STX Files

STX (ScummVM Theme XML) is the new format for theme descriptions on the Graphical User Interface of ScummVM.

The chosen syntax of this format is a basic subset of XML, the one which the embedded XML parser supports. Please refer to the parser documentation for its technical specifications.

Throughout the STX files, every single property of the theme's appearance and layout is defined: Although all this information can easily be stored in a single file, the theme engine conveniently allows to split the different sections of the Theme Description in one or more files.

Any *.stx files contained inside the theme package will be automatically loaded and parsed. The content of such files must obviously adhere to the STX syntax which you can find in this document.

The external resources

Together with the STX files, external resources for the theme may be optionally bundled. The most usual resources are bitmaps to use in the Graphical User Interface and Bitmap fonts.

Packaged resources will then be accessible from the STX syntax (check the font and bitmap keys in the STX documentation).

The `THEMERC` file

ScummVM themes must also contain a simple THEMERC file stating the theme's version, name and author. The THEMERC file is a simple text file with the following syntax:

[SCUMMVM_STX0.2:Name of the ScummVM Theme:Name of the Author]

The SCUMMVM_STX0.2 is just a simple check to make sure that the theme was developed to be used on the proper version of the GUI; 0.2 is the latest version of the ScummVM STX format. Note that the THEMERC file is not optional, as it is used by the Theme engine to check that the Theme package is indeed valid and specifies the Name and Author fields that will be shown on the GUI.

Building theme packages

Building a ScummVM Theme Package is as easy as dragging your STX files, bitmaps, resources and THEMERC files into your favorite archiver application and creating a zip file. However, to make the development process easier, a Python script called scummtheme.py has been included in the gui/themes/ folder of the Git repository.

When ran with the makeall argument, the script will automatically parse all the theme folders in the Theme directory and build their ZIP files. It can be also used to build a single theme by passing it the make [themename] argument, where [themename] is the name of the folder containing the theme to be built.

This Python script is totally standalone and doesn't require external ZIP utilities, only a standard Python distribution.

Building the built-in theme

The Graphical User Interface must contain a built-in theme to use a fall-back when no other custom themes can be loaded. The built-in theme must be built manually with the scummtheme.py script, by passing it the default [themename] argument.

The Python script will then parse the supplied theme's STX files into a single *.inc file; this file is automatically built together with the ScummVM executable file when building the ScummVM source code, and will be used as the default built-in theme.

Note that because only STX files are embedded in the source code, the theme which is converted into a built-in theme cannot contain Bitmaps or any other external resources.

By default, the ScummVM Classic Theme is the built-in theme.

Drawing specifications

The process of rendering a widget on the screen is discretized into several phases called drawing steps. A set of such steps, which generate a basic widget shape on screen is called a Draw Data set. The GUI Engine loads all the different data sets for a given widget and takes care of rendering it into the screen based on its current state.

For example, the basic Button widget may be composed of several sets of data: Drawing data for the button's idle state, drawing data for when the button is hovered and drawing data for when the button is pressed.

The functionality of each set of Drawing Data is hard-coded into the Graphical User Interface; the most up to date version of all the drawing sets may be found extensively commented in the "gui/ThemeEngine.h" file, in the DrawData enumeration.

In order to successfully parse and load a custom theme definition, the whole list of Draw Data sets is not required to be defined in a theme description, but failing to declare all of them will make the parser complain and obviously several GUI elements will be missing.

Theme Layout specifications

The actual positioning and layout of widgets and dialogs on the graphical user interface is defined from the Layout section of the STX file. This new Graphical User Interface using a Flowing Layouts system which greatly differs from the old coordinate and arithmetic based implementation.

The best way to learn about the new Layout system is to read the documentation on the layout key and its children, and to read the example Layout Design section, which provides a detailed overview into the steps required to design the layout of a dialog.

Syntax overview

A full STX theme description is composed of:

A root <render_info> key, containing all the information regarding the looks of the theme.
- An optional <palette> key, containing color definitions.
- An optional <bitmaps> key, containing all the loaded bitmaps which will be used on the GUI.
- A <fonts> key, specifying the fonts used to draw text on the GUI.
- A <drawdata> key for each DrawData identifier of the Theme Engine, specifying how is each individual widget drawn.
A root <layout_info> key, containing all the information regarding the layout of the theme.
- A <globals> key, containing the global variables to use on the layout design.
- A <dialog> key for each dialog in the GUI, specifying the layout and position of the dialog and all its children widgets.

Here's a schematic overview of the layout of keys in a STX file:

<render_info>
    <palette>
        ...
    </palette>

    <bitmaps>
        ...
    </bitmaps>

    <fonts>
        ...
    </fonts>

    <drawdata>
        ...
    </drawdata>

    ...
</render_info>

<layout_info>
    <globals>
        ...
    </globals>

    <dialog>
        ...
    </dialog>

    ...
</layout_info>

The best place to start writing a full theme description is taking a look at the already written themes in the gui/themes/ directory of the source code repository, while consulting the following documentation for each specific key:

Detailed STX documentation

The full documentation of the XML syntax used in the new Graphical User Interface can be found on its own wiki page.

Resolution-dependent keys and layouts

Several keys in the STX syntax support the resolution property, which allows to load or skip the key and all its children when loading the theme on a given resolution dimension limit.

The resolution property must contain one or more resolution dimension limits, comma separated, for which the given key is supposed to be loaded. Resolutions without any modifiers will force the theme to be loaded in all resolutions. Here are a few examples:

/* Key will be loaded in all resolutions */
<render_info>

/* Key will ONLY be loaded in resolutions with 400 width or more */
<render_info resolution = 'y>=400'>

/* Key will ONLY be loaded in resolutions with less than 400 height */
<render_info resolution = 'y<400'>

Note that the Theme Parser does not assert on repeated keys or values, it just replaces them accordingly. For instance, the following variable definition:

<def var = 'TestVar' value = '100'/>
<def var = 'TestVar' value = '200' resolution = 'y>=400'/>

won't fail to parse. What will happen when loading the theme using a resolution with 400 height or mire is that TestVal first will be assigned the 100 value, and then it will be overwritten with the 200 value. On the other hand, when loading the theme using a resolution with less than 400 height, the ThemeVal will be assigned the 100 value and the second key will be plain ignored.

The "proper" way to do that multi-resolution assignment would obviously be:

<def var = 'TestVar' value = '100' resolution = 'y<400'/>
<def var = 'TestVar' value = '200' resolution = 'y>399'/>

This way keys are only parsed on the resolution they are used in, but the result will be exactly the same: Most of the time it's just cleaner to avoid using y<400 resolution tags, and instead write a layout that works on all resolutions and overwrite parts of it with the y>399 tag.