TrustedUser
2,147
edits
Difference between revisions of "GUI Themes/Specs"
Jump to navigation
Jump to search
m
Text replacement - "<source lang=" to "<syntaxhighlight lang="
(adapt to recent theme parser changes) |
m (Text replacement - "<source lang=" to "<syntaxhighlight lang=") |
||
| (7 intermediate revisions by 3 users not shown) | |||
| Line 34: | Line 34: | ||
===== Building theme packages ===== | ===== Building theme packages ===== | ||
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 | 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. | ||
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. | 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. | ||
| Line 56: | Line 56: | ||
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. | 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 <tt>"gui/ | 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>"gui/ThemeEngine.h"</tt> file, in the <tt>DrawData</tt> 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. | 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. | ||
| Line 80: | Line 80: | ||
Here's a schematic overview of the layout of keys in a STX file: | Here's a schematic overview of the layout of keys in a STX file: | ||
< | <syntaxhighlight lang="xml"> | ||
<render_info> | <render_info> | ||
<palette> | <palette> | ||
| Line 112: | Line 112: | ||
... | ... | ||
</layout_info> | </layout_info> | ||
</ | </syntaxhighlight> | ||
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 | 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: | ||
=== Detailed STX documentation === | === Detailed STX documentation === | ||
| Line 126: | Line 126: | ||
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: | 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: | ||
< | <syntaxhighlight lang="xml"> | ||
/* Key will be loaded in all resolutions */ | /* Key will be loaded in all resolutions */ | ||
<render_info> | <render_info> | ||
| Line 135: | Line 135: | ||
/* Key will ONLY be loaded in resolutions with less than 400 height */ | /* Key will ONLY be loaded in resolutions with less than 400 height */ | ||
<render_info resolution = 'y<400'> | <render_info resolution = 'y<400'> | ||
</ | </syntaxhighlight> | ||
Note that the Theme Parser does not assert on repeated keys or values, it just replaces them accordingly. For instance, the following variable definition: | Note that the Theme Parser does not assert on repeated keys or values, it just replaces them accordingly. For instance, the following variable definition: | ||
< | <syntaxhighlight lang="xml"> | ||
<def var = 'TestVar' value = '100'/> | <def var = 'TestVar' value = '100'/> | ||
<def var = 'TestVar' value = '200' resolution = 'y>399'/> | <def var = 'TestVar' value = '200' resolution = 'y>399'/> | ||
</ | </syntaxhighlight> | ||
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. | 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. | ||
| Line 148: | Line 148: | ||
The "proper" way to do that multi-resolution assignment would obviously be: | The "proper" way to do that multi-resolution assignment would obviously be: | ||
< | <syntaxhighlight lang="xml"> | ||
<def var = 'TestVar' value = '100' resolution = 'y<400'/> | <def var = 'TestVar' value = '100' resolution = 'y<400'/> | ||
<def var = 'TestVar' value = '200' resolution = 'y>399'/> | <def var = 'TestVar' value = '200' resolution = 'y>399'/> | ||
</ | </syntaxhighlight> | ||
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. | 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. | ||