Difference between revisions of "GUI Themes/Specs"

From ScummVM :: Wiki
Jump to navigation Jump to search
(Initial content)
 
(→‎Resolution-dependent keys and layouts: >= and <= are now supported)
 
(93 intermediate revisions by 13 users not shown)
Line 1: Line 1:
== GUI Themes config file format ==
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.


=== Overview ===
=== Theme Packages ===


We always have a built-in theme. It is used when there is no external .ini file. For simplicity it uses exactly same format as external .ini but is defined in Theme::_defaultConfigINI string in gui/theme-config.cpp file.
A theme file in the new version of the ScummVM GUI is a compressed ZIP file which contains all the required information


Config file consists of at least one section. These sections can override one another. This is used to make a slight alteration of base theme possible without duplicating all element whose position is not changed.
* One or more STX (ScummVM Theme XML) files.
* Any external Bitmap fonts.
* Any external Bitmap images.
* A <tt>THEMERC</tt> file.
===== The STX Files =====


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


=== Section names ===
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.
They are defined with this regexp: (X|[0-9]+)x(Y|[0-9+]+). I.e. possible names are:
* [XxY] -- universal one which can be used for any resolution
* [640xY] -- could be used for 640x400 and 640x480
* [640x480] -- could be used for 640x480 only


=== Sections precedence ===
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.
Sections loading order is always the same. For resolution 640x480 it is:


# Built-in theme
Any <tt>*.stx</tt> 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.
## [XxY]
## [640xY]
## [640x480]
# Custom theme
## [XxY]
## [640xY]
## [640x480]


Only present sections are loaded. If section is not defined, no error message is generated
===== The external resources =====


=== Expressions ===
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.
To add most flexibility arbitrary arithmetic expressions can be used for specifying any element. Allowed operations are '(', ')', '+', '-', '*', '/'. unary '+' and unary '-'. Atoms are either number or symbolic names.


=== Built-in Constants ===
Packaged resources will then be accessible from the STX syntax (check the <tt>font</tt> and <tt>bitmap</tt> keys in the STX documentation).
Currently there are these built-in constants defined:


* kButtonWidth
===== The <tt>THEMERC</tt> file =====
* kButtonHeight
* kSliderWidth
* kSliderHeight
* kBigButtonWidth
* kBigButtonHeight
* kBigSliderWidth
* kBigSliderHeight


These correspond to constants defined in gui/widget.h file. There is no restriction on constants names.
ScummVM themes '''must''' also contain a simple <tt>THEMERC</tt> file stating the theme's version, name and author. The <tt>THEMERC</tt> file is a simple text file with the following syntax:


=== Built-in Variables ===
<pre>[SCUMMVM_STX0.2:Name of the ScummVM Theme:Name of the Author]</pre>
Built-in variables are symbolic names for ScummVM variables whose value is determined at run-time. These are:
The <tt>SCUMMVM_STX0.2</tt> 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 <tt>THEMERC</tt> 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.


* w -- current GUI width
===== Building theme packages =====
* h -- current GUI height


=== Defining widget positions ===
Building a ScummVM Theme Package is as easy as dragging your STX files, bitmaps, resources and <tt>THEMERC</tt> files into your favorite archiver application and creating a zip file. However, to make the development process easier, a Python script called <tt>scummtheme.py</tt> has been included in the <tt>gui/themes/</tt> folder of the Git repository.
Widgets are specified by following construction:


  widget_name=X Y [W H]
When ran with the <tt>makeall</tt> 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 <tt>make [themename]</tt> argument, where <tt>[themename]</tt> is the name of the folder containing the theme to be built.


X, Y, W and H are whitespace-delimited expressions.
This Python script is totally standalone and doesn't require external ZIP utilities, only a standard Python distribution.
W and H are optional.


This construct effectively defines
===== Building the built-in theme =====


* widget_name.x
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 <tt>scummtheme.py</tt> script, by passing it the <tt>default [themename]</tt> argument.
* widget_name.y
* widget_name.w
* widget_name.h


If W and H are present, also these get defined:
The Python script will then parse the supplied theme's STX files into a single <tt>*.inc</tt> 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.


* widget_name.x2 = widget_name.x + widget_name.w
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.
* widget_name.y2 = widget_name.y + widget_name.h


Example:
By default, the <tt>ScummVM Classic Theme</tt> is the built-in theme.


  chooser_headline=10 6 (w - 2 * 16) (kLineHeight)
=== Drawing specifications ===


=== Widget properties ===
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.
Above mentioned constructions with dots are called widget properties.


Example:
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.


  chooser_list.x
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 <tt>&quot;gui/ThemeEngine.h&quot;</tt> file, in the <tt>DrawData</tt> enumeration.


=== Special variables ===
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.
Special variable is:


* self
=== Theme Layout specifications ===


It is reference to current widget special variables, i.e. .x, .y, .w and .h
The actual positioning and layout of widgets and dialogs on the graphical user interface is defined from the <tt>Layout</tt> 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.


Example:
The best way to learn about the new Layout system is to read the documentation on the <tt>layout</tt> 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.


  chooser_list=10 (6 + kLineHeight + 2) (w - 2 * 16) (h - self.y - buttonHeight - 12)
=== Syntax overview ===


Denote self.y which equals to computed value of (6 + kLineHeight + 2).
A full STX theme description is composed of:


You cannot use these references forward, i.e. refer to .w in .x. They get defined from left to right.
* A root <tt>&lt;render_info&gt;</tt> key, containing all the information regarding the looks of the theme.
** An optional <tt>&lt;palette&gt;</tt> key, containing color definitions.
** An optional <tt>&lt;bitmaps&gt;</tt> key, containing all the loaded bitmaps which will be used on the GUI.
** A <tt>&lt;fonts&gt;</tt> key, specifying the fonts used to draw text on the GUI.
** A <tt>&lt;drawdata&gt;</tt> key for ''each'' DrawData identifier of the Theme Engine, specifying how is each individual widget drawn.
* A root &lt;layout_info&gt; key, containing all the information regarding the layout of the theme.
** A <tt>&lt;globals&gt;</tt> key, containing the global variables to use on the layout design.
** A <tt>&lt;dialog&gt;</tt> 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:


=== Defining variables ===
<syntaxhighlight lang="xml">
<render_info>
    <palette>
        ...
    </palette>


Example:
    <bitmaps>
        ...
    </bitmaps>


  def_kLineHeight=16 * 2
    <fonts>
  OneThirdWidth=w / 3
        ...
    </fonts>


variable kLineHeight gets value 32. OneThirdWidth will be GUI width divided by 3. Definitions with 'def_' prefix have a special meaning and get skipped with USE keyword (see below).
    <drawdata>
        ...
    </drawdata>


=== Defining aliases ===
    ...
You can define alias to any symbolic atom, i.e. constants, variables and widget properties.
</render_info>


Example:
<layout_info>
    <globals>
        ...
    </globals>


  set_headerBottomX=headline.x2
    <dialog>
        ...
    </dialog>


Now you can use headerBottomX everywhere.
    ...
</layout_info>
</syntaxhighlight>


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


  def_parent=chooser_list
=== Detailed STX documentation ===


It sets 6 aliases for each widget property, i.e.
The full documentation of the XML syntax used in the new Graphical User Interface can be found on its own [[GUI Themes/STX_Syntax|wiki page]].


* parent.x = chooser_list.x
=== Resolution-dependent keys and layouts ===
* parent.y = chooser_list.y


etc for .w, .h, .x2 and .y2
Several keys in the STX syntax support the <tt>resolution</tt> property, which allows to load or skip the key and all its children when loading the theme on a given resolution dimension limit.


=== USE keyword ===
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:
You can request loading of some particular section at any time within another section. But all variable definitions with def_ prefix get skipped. If you want to define a variable, use plain VAR=VAl construction.


Example:
<syntaxhighlight lang="xml">
/* Key will be loaded in all resolutions */
<render_info>


  [640xY]
/* Key will ONLY be loaded in resolutions with 400 width or more */
  def_buttonHeight=kBigButtonHeight
<render_info resolution = 'y>=400'>
  def_kLineHeight=16
  listW=(w - 2 * 16)
  chooser_headline=10 6 listW (kLineHeight)
  chooser_list=10 (6 + kLineHeight + 2) listW (h - self.y - buttonHeight - 12)
 
  [320xY]
  def_buttonHeight=kButtonHeight
  def_kLineHeight=9
  use=640xY


In this example for 320xY resolution chooser_headline and chooser_list will be loaded from [640xY] section, though buttonHeight and kLineHeight will be different. listW will get the value.
/* Key will ONLY be loaded in resolutions with less than 400 height */
<render_info resolution = 'y<400'>
</syntaxhighlight>


== Evaluation precedence ==
Note that the Theme Parser does not assert on repeated keys or values, it just replaces them accordingly. For instance, the following variable definition:
Everything is computed left to right down to top within one single section. No forward references are allowed. Only exception is aliases which can refer to not yet defined variables and widget properties, but at time of useage those variables should be defined, otherwise you will get an error.


Currently any error in evaluation will lead to error() and ScummVM will be closed. So be careful, especially with built-in theme.
<syntaxhighlight lang="xml">
<def var = 'TestVar' value = '100'/>
<def var = 'TestVar' value = '200' resolution = 'y>=400'/>
</syntaxhighlight>


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


Widget names are in form:
The &quot;proper&quot; way to do that multi-resolution assignment would obviously be:


  dialog_widget
<syntaxhighlight lang="xml">
<def var = 'TestVar' value = '100' resolution = 'y<400'/>
<def var = 'TestVar' value = '200' resolution = 'y>399'/>
</syntaxhighlight>


where dialog_ is dialog name, and widget is a distinguishable name within that dialog. Be discreet and give meaningful names.
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 <tt>y<400</tt> resolution tags, and instead write a layout that works on all resolutions and overwrite parts of it with the <tt>y>399<tt> tag.
 
Example:
 
  chooser_headline
  chooser_list

Latest revision as of 12:45, 16 March 2023

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.