https://wiki.scummvm.org/api.php?action=feedcontributions&user=Tanoku&feedformat=atomScummVM :: Wiki - User contributions [en]2024-03-28T14:20:56ZUser contributionsMediaWiki 1.36.0https://wiki.scummvm.org/index.php?title=GUI_Themes/Specs&diff=9490GUI Themes/Specs2008-10-15T13:35:22Z<p>Tanoku: /* The <tt>THEMERC</tt> file */</p>
<hr />
<div>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.<br />
<br />
=== Theme Packages ===<br />
<br />
A theme file in the new version of the ScummVM GUI is a compressed ZIP file which contains all the required information<br />
<br />
* One or more STX (ScummVM Theme XML) files.<br />
* Any external Bitmap fonts.<br />
* Any external Bitmap images.<br />
* A <tt>THEMERC</tt> file.<br />
===== The STX Files =====<br />
<br />
STX (ScummVM Theme XML) is the new format for theme descriptions on the Graphical User Interface of ScummVM.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===== The external resources =====<br />
<br />
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.<br />
<br />
Packaged resources will then be accessible from the STX syntax (check the <tt>font</tt> and <tt>bitmap</tt> keys in the STX documentation).<br />
<br />
===== The <tt>THEMERC</tt> file =====<br />
<br />
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:<br />
<br />
<pre>[SCUMMVM_STX0.2:Name of the ScummVM Theme:Name of the Author]</pre><br />
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.<br />
<br />
===== Building theme packages =====<br />
<br />
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 SVN repository.<br />
<br />
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.<br />
<br />
This Python script is totally standalone and doesn't require external ZIP utilities, only a standard Python distribution.<br />
<br />
===== Building the built-in theme =====<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
By default, the <tt>ScummVM Classic Theme</tt> is the built-in theme.<br />
<br />
=== Drawing specifications ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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/ThemeRenderer.h&quot;</tt> file, in the <tt>DrawData</tt> enumeration inside the <tt>ThemeRenderer</tt> class.<br />
<br />
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.<br />
<br />
=== Theme Layout specifications ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== Syntax overview ===<br />
<br />
A full STX theme description is composed of:<br />
<br />
* A root <tt>&lt;render_info&gt;</tt> key, containing all the information regarding the looks of the theme.<br />
** An optional <tt>&lt;palette&gt;</tt> key, containing color definitions.<br />
** An optional <tt>&lt;bitmaps&gt;</tt> key, containing all the loaded bitmaps which will be used on the GUI.<br />
** A <tt>&lt;fonts&gt;</tt> key, specifying the fonts used to draw text on the GUI.<br />
** A <tt>&lt;drawdata&gt;</tt> key for ''each'' DrawData identifier of the Theme Engine, specifying how is each individual widget drawn.<br />
* A root &lt;layout_info&gt; key, containing all the information regarding the layout of the theme.<br />
** A <tt>&lt;globals&gt;</tt> key, containing the global variables to use on the layout design.<br />
** 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.<br />
Here's a schematic overview of the layout of keys in a STX file:<br />
<br />
<syntax type="xml"><br />
<render_info><br />
<palette><br />
...<br />
</palette><br />
<br />
<bitmaps><br />
...<br />
</bitmaps><br />
<br />
<fonts><br />
...<br />
</fonts><br />
<br />
<drawdata><br />
...<br />
</drawdata><br />
<br />
...<br />
</render_info><br />
<br />
<layout_info><br />
<globals><br />
...<br />
</globals><br />
<br />
<dialog><br />
...<br />
</dialog><br />
<br />
...<br />
</layout_info><br />
</syntax><br />
<br />
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 Subversion repository, while consulting the following documentation for each specific key:<br />
<br />
=== Detailed STX documentation ===<br />
<br />
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]].<br />
<br />
=== Resolution-dependent keys and layouts ===<br />
<br />
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.<br />
<br />
The resolution property must contain one or more resolutions, comma separated, for which the given key is supposed to be loaded. Resolutions preceded by the minus sign will block the key from being loaded in that resolution, while resolutions without any modifiers will force the theme to be loaded in all resolutions. Here are a few examples:<br />
<br />
<syntax type="xml"><br />
/* Key will be loaded in all resolutions */<br />
<render_info><br />
<br />
/* Key will ONLY be loaded in resolutions with 320 width */<br />
<render_info resolution = '320xY'><br />
<br />
/* Key will ONLY be loaded in resolutions with 240 height and in the 320x200 resolution */<br />
<render_info resolution = 'Xx240, 320x200'><br />
<br />
/* Key will be loaded on ALL resolutions except for 320x200 */<br />
<render_info resolution = '-320x200'><br />
<br />
/* Key will ONLY be loaded in resolutions with 320 width; the -240xY is superfluous. */<br />
<render_info resolution = '320xY, -240xY'><br />
</syntax><br />
<br />
Note that the Theme Parser does not assert on repeated keys or values, it just replaces them accordingly. For instance, the following variable definition:<br />
<br />
<syntax type="xml"><br />
<def var = 'TestVar' value = '100'/><br />
<def var = 'TestVar' value = '200' resolution = '320xY'/><br />
</syntax><br />
<br />
won't fail to parse. What will happen when loading the theme using a resolution with 320 width 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 ''without'' a with of 320, the <tt>ThemeVal</tt> will be assigned the <tt>100</tt> value and the second key will be plain ignored.<br />
<br />
The &quot;proper&quot; way to do that multi-resolution assignment would obviously be:<br />
<br />
<syntax type="xml"><br />
<def var = 'TestVar' value = '100' resolution = '-320xY'/><br />
<def var = 'TestVar' value = '200' resolution = '320xY'/><br />
</syntax><br />
<br />
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>-320xY</tt> resolution tags, and instead write a layout that works on all resolutions and overwrite parts of it with the '320xY' tag.</div>Tanokuhttps://wiki.scummvm.org/index.php?title=GUI_Themes/STX_Syntax&diff=9487GUI Themes/STX Syntax2008-10-15T12:17:23Z<p>Tanoku: </p>
<hr />
<div>This page contains a detailed overview of all the possible XML key values in a STX file. See [[GUI Themes/Specs|wiki page]] for the general information of the new Theme Format.<br />
<br />
=== STX Syntax Keys ===<br />
<br />
==== <tt>&lt;render_info&gt;</tt> ====<br />
<br />
Parent: root<br /><br />
Children: <tt>&lt;palette&gt;</tt>, <tt>&lt;fonts&gt;</tt>, <tt>&lt;bitmaps&gt;</tt>, <tt>&lt;cursor&gt;</tt>, <tt>&lt;defaults&gt;</tt>, <tt>&lt;drawdata&gt;</tt><br /><br />
Properties: <tt>resolution</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;render_info resolution = &quot;320x240&quot;&gt;<br />
...<br />
&lt;/render_info&gt;</pre><br />
===== Description =====<br />
<br />
The <tt>render_info</tt> key specifies that all children keys contain information regarding the looks of the theme, i.e. the actual Drawing Specifications.<br />
<br />
===== Properties =====<br />
<br />
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.<br />
<br />
-----<br />
<br />
==== <tt>&lt;palette&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;render_info&gt;</tt><br /><br />
Children: <tt>&lt;color&gt;</tt><br /><br />
Properties: -<br />
<br />
===== Example =====<br />
<br />
<pre>&lt;palette&gt;<br />
...<br />
&lt;/palette&gt;</pre><br />
===== Description =====<br />
<br />
The <tt>palette</tt> key is a simple wrapper; it contains all the <tt>color</tt> definitions for the theme.<br />
<br />
<br />
-----<br />
<br />
==== <tt>&lt;color&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;palette&gt;</tt><br /><br />
Children: - Properties: <tt>name</tt> (''required''), <tt>rgb</tt> (''required'')<br />
<br />
===== Example =====<br />
<br />
<pre>&lt;color name = 'red'<br />
rgb = '255, 0, 0'<br />
/&gt;</pre><br />
===== Description =====<br />
<br />
Color keys define aliases for commonly used colors on the theme. Once you define a color name and its RGB equivalent, any key properties which are expecting a RGB color definition will accept such alias.<br />
<br />
Color aliases are exclusive to the parser engine, they are replaced by their actual RGB values when loaded into the Theme Renderer.<br />
<br />
===== Properties =====<br />
<br />
* <tt>name [string]</tt>: Name/alias of the color.<br />
* <tt>rgb [int, int, int]</tt>: RGB (red/green/blue) values for the color, comma separated.<br />
<br />
-----<br />
<br />
==== <tt>&lt;bitmaps&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;render_info&gt;</tt><br /><br />
Children: <tt>&lt;bitmap&gt;</tt><br /><br />
Properties: -<br />
<br />
===== Example =====<br />
<br />
<pre>&lt;bitmaps&gt;<br />
...<br />
&lt;/bitmaps&gt;</pre><br />
===== Description =====<br />
<br />
The <tt>bitmaps</tt> key is a simple wrapper; it contains all the <tt>bitmap</tt> keys for the theme.<br />
<br />
<br />
-----<br />
<br />
==== <tt>&lt;bitmap&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;bitmaps&gt;</tt><br /><br />
Children: -<br /><br />
Properties: <tt>filename</tt> (''required''), <tt>resolution</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;bitmap filename = 'logo.bmp'/&gt;</pre><br />
===== Description =====<br />
<br />
A <tt>bitmap</tt> key specifies a bitmap file to be loaded by the theme renderer. You may load as many bitmaps as you desire; they are expected to be 24 bit standard Windows bitmaps, and to packed together with the STX file.<br />
<br />
Once a bitmap file has been loaded, it may be referenced by its filename in the STX file where required:<br />
<br />
===== Properties =====<br />
<br />
* <tt>filename [string]</tt>: Path and filename to the bitmap file.<br />
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.<br />
<br />
-----<br />
<br />
==== <tt>&lt;fonts&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;render_info&gt;</tt><br /><br />
Children: <tt>&lt;font&gt;</tt><br /><br />
Properties: -<br />
<br />
===== Example =====<br />
<br />
<pre>&lt;fonts&gt;<br />
...<br />
&lt;/fonts&gt;</pre><br />
===== Description =====<br />
<br />
The <tt>fonts</tt> key is a simple wrapper; it contains all the <tt>font</tt> keys for the theme.<br />
<br />
<br />
-----<br />
<br />
==== <tt>&lt;font&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;fonts&gt;</tt><br /><br />
Children: -<br /><br />
Properties: <tt>id</tt> (''required''), <tt>file</tt> (''required''), <tt>color</tt> (''required''), <tt>resolution</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;font id = 'text_default'<br />
file = 'default'<br />
color = 'black'<br />
/&gt;</pre><br />
===== Description =====<br />
<br />
Text drawing on the new GUI is based on Font structures. The renderer expects several font definitions, used internally for text drawing; you can see Font definitions as the text equivalent of a Drawing Step on the Vector Renderer.<br />
<br />
===== Required Font identifiers =====<br />
<br />
This is the list of all the required font identifiers; these identifiers are used internally by the renderer (i.e. when writing static text on the GUI) and may also be referenced on any DrawStep to define the specific font which will be used to draw such widget.<br />
<br />
* <tt>text_default</tt>: Core font for the engine, used to draw all the static text and most of the text in widgets.<br />
* <tt>text_hover</tt>: Used for text which is currently being highlighted / hovered by the mouse.<br />
* <tt>text_disabled</tt>: Used for text on disabled widgets.<br />
* <tt>text_inverted</tt>: Text which is currently selected and has a special selection background.<br />
* <tt>text_button</tt>: Default text for Button widgets.<br />
* <tt>text_button_hover</tt>: Default text for highlighted button widgets.<br />
* <tt>text_normal</tt>: ''Normal'', smaller text (i.e. non bold) used sparsely (editable text widgets, about dialog, etc).<br />
For performance reasons, these identifiers are unique and limited (i.e. the parser doesn't expect any other custom identifiers). Future versions of the Theme Format may allow for custom Fonts specific to certain widgets.<br />
<br />
===== Properties =====<br />
<br />
* <tt>id [string]</tt>: Unique font identifier.<br />
* <tt>file [string]</tt>: External Font file to load. Use &quot;default&quot; to let the renderer choose the most appropriate default font based on the active resolution (usually an builtin one).<br />
* <tt>color [int, int, int|string]</tt>: Color to draw the text with.<br />
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.<br />
<br />
-----<br />
<br />
==== <tt>&lt;defaults&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;render_info&gt;</tt>, <tt>&lt;drawdata&gt;</tt><br /><br />
Children: -<br /><br />
Properties: See DrawStep properties.<br />
<br />
===== Example =====<br />
<br />
<pre>&lt;defaults fill = 'gradient' fg_color = 'white' bevel_color = '237, 169, 72'/&gt;</pre><br />
===== Description =====<br />
<br />
The <tt>defaults</tt> key may be used to specify default values to be used on ''all'' DrawSteps in order to avoid code repetition. You may set default values for any drawing properties which is shared by all DrawSteps: Check the DrawStep specification for a detailed list.<br />
<br />
If found on the <tt>&lt;render_info&gt;</tt> scope, these defaults will be applied to all DrawSteps found inside any of the DrawData definitions. Optionally, you may use the defaults key inside a <tt>&lt;drawdata&gt;</tt> key to temporarily override the global defaults for all the DrawSteps inside that DrawData key.<br />
<br />
<br />
-----<br />
<br />
==== <tt>&lt;cursor&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;render_info&gt;</tt><br /><br />
Children: -<br /><br />
Properties: <tt>file</tt> (''required''), <tt>hotspot</tt> (''required''), <tt>scale</tt> (''required''), <tt>resolution</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;cursor file = 'cursor.bmp' hotspot = '0, 0' scale = '3'/&gt;</pre><br />
===== Description =====<br />
<br />
If the parser finds a <tt>cursor</tt> key in the <tt>render_info</tt> scope, it will try to load a custom bitmap cursor to use in the Graphical User Interface. If no <tt>cursor</tt> key is found, the GUI will default to the built-in cross cursor.<br />
<br />
Because of bitmap scaling issues, make sure to specify several different cursor definitions, one for each significant resolution.<br />
<br />
===== Properties =====<br />
<br />
* <tt>file [string]</tt>: Filename for the bitmap with the cursor shape (must have been loaded previously).<br />
* <tt>hotspot [int, int]</tt>: Coordinates for the point in the bitmap which will be used for click calculations.<br />
* <tt>scale [int]</tt>: Scale at which this cursor is supposed to be used.<br />
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.<br />
<br />
-----<br />
<br />
==== <tt>&lt;drawdata&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;render_info&gt;</tt><br /><br />
Children: <tt>&lt;defaults&gt;</tt>, <tt>&lt;drawstep&gt;</tt>, <tt>&lt;text&gt;</tt><br /><br />
Properties: <tt>id</tt> (''required''), <tt>cache</tt>, <tt>resolution</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;drawdata id = 'mainmenu_bg' cache = false&gt;<br />
&lt;drawstep ...<br />
/&gt;<br />
&lt;/drawdata&gt;</pre><br />
===== Description =====<br />
<br />
DrawData keys are the core of the rendering engine. They specifiy via their own DrawStep children the looks of all the UI elements for each possible state.<br />
<br />
The Theme Renderer is expecting a specific set of DrawData items for each possible widget state with unique identifiers. The list of DD identifiers is as follows:<br />
<br />
===== Required DrawData identifiers =====<br />
<br />
* <tt>mainmenu_bg</tt>, <tt>special_bg</tt>, <tt>plain_bg</tt>, <tt>default_bg</tt>: Backgrounds for the different dialogs.<br />
* <tt>text_selection</tt>: Background for selected (inverted) text.<br />
* <tt>widget_default</tt>, <tt>widget_small</tt>: Default backgrounds for widgets.<br />
* <tt>widget_textedit</tt>: Background for the Text Edit widget.<br />
* <tt>widget_slider</tt>: Background for the (empty) slider widget.<br />
* <tt>button_idle</tt>, <tt>button_hover</tt>, <tt>button_disabled</tt>: States for the Button widget.<br />
* <tt>slider_full</tt>, <tt>slider_hover</tt>, <tt>slider_disabled</tt>: States for the Slider widget.<br />
* <tt>checkbox_default</tt>, <tt>checkbox_disabled</tt>, <tt>checkbox_selected</tt>: States for the Checkbox widget.<br />
* <tt>tab_active</tt>, <tt>tab_inactive</tt>: States for the selected/deselected tab.<br />
* <tt>tab_background</tt>: Background behind the tab list.<br />
* <tt>scrollbar_base</tt>: Background for the scrollbar widget.<br />
* <tt>scrollbar_button_idle</tt>, <tt>scrollbar_button_hover</tt>: States for the scrollbar up/down buttons.<br />
* <tt>scrollbar_handle_idle</tt>, <tt>scrollbar_handle_hover</tt>: States for the scrolling handle of the scrollbar.<br />
* <tt>popup_idle</tt>, <tt>popup_hover</tt>: States for the popup selection widget.<br />
* <tt>caret</tt>: Text edition caret.<br />
* <tt>separator</tt>: Basic horizontal separator.<br />
Remember that although all these identifiers don't need to be implemented for the theme parsing to be successful, the parser will complain on any missing assets and the GUI will obviously be lacking widget graphics.<br />
<br />
Also, note that each DrawData key ''must'' contain at least a child DrawStep, since it actually defines the graphic drawing for the widget/state.<br />
<br />
===== Properties =====<br />
<br />
* <tt>id [string]</tt>: Unique identifier for the drawing asset.<br />
* <tt>cache [bool]</tt>: Lets the renderer know that this drawing asset may be cached for performance.<br />
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.<br />
<br />
-----<br />
<br />
==== <tt>&lt;drawstep&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;drawdata&gt;</tt><br /><br />
Children: -<br /><br />
Properties: <tt>func</tt> (''required''), ...<br />
<br />
===== Example =====<br />
<br />
<pre>&lt;drawstep func = 'roundedsq'<br />
radius = '6'<br />
stroke = 1<br />
fill = 'gradient'<br />
shadow = 0<br />
fg_color = 'shadowcolor'<br />
gradient_start = 'brightred'<br />
gradient_end = 'darkred'<br />
bevel = 1<br />
/&gt;</pre><br />
===== Description =====<br />
<br />
DrawSteps are the core of the GUI drawing engine; in order to draw a Widget state to screen (e.g. a selected button), this drawing process is split into several simpler drawing functions, called DrawSteps.<br />
<br />
Each <tt>drawdata</tt> key must contain one or more DrawSteps. These steps are parsed from top to bottom and their drawing information is stored and later drawn in that same exact order: That means that the last DrawStep inside a DrawData set will appear on top.<br />
<br />
The most important property of a DrawStep is the <tt>func</tt> (or function) of the step, the primitive drawing function that will be used. All other properties are optional parameters to that drawing function, such as the foreground and background colors, the stroke used, and a long etc.<br />
<br />
Take a look at the full list of properties to see which properties are required by each function.<br />
<br />
===== Required properties =====<br />
<br />
* <tt>func [string]</tt>: Specifies the drawing function used on the step from one of the following:<br />
** <tt>circle</tt>: Draws a primitive circle.<br />
** <tt>square</tt>: Draws a primitive square/rectangle.<br />
** <tt>roundedsq</tt>: Draws a rounded square/rectangle (that is, a rectangle with rounded corners).<br />
** <tt>bevelsq</tt>: Draws a square/rectangle with beveled borders. This square ignores the active fill mode, as it is never filled. It's used to reproduce the old Classic GUI Theme.<br />
** <tt>line</tt>: Draws a straight line.<br />
** <tt>triangle</tt>: Draws a triangle. Triangles are always isosceles, meaning they are drawn inside the square defined by the position and size values, with the given width as the base of the triangle and the given height as the height of the triangle.<br />
** <tt>fill</tt>: This drawing function ignores position and size parameters, as it completely fills the active drawing surface taken into account the active fill mode and colors.<br />
** <tt>bitmap</tt>: Ignores all drawing information and blits the given Bitmap into the surface.<br />
===== Common (optional) properties =====<br />
<br />
* <tt>fill [string]</tt>: Specifies the fill mode for the drawn shape. Possible values:<br />
** <tt>none</tt>: Disables filling so only the stroke is shown.<br />
** <tt>foreground</tt> (''default''): Fills the whole shape with the active foreground color.<br />
** <tt>background</tt>: Fills the whole shape with the active background color.<br />
** <tt>gradient</tt>: Fills the whole shape with the active gradient.<br /><br />
<br />
* <tt>gradient_start [int, int, int|string]</tt>: Sets the gradient start color; has no default value.<br /><br />
<br />
* <tt>gradient_end [int, int, int|string]</tt>: Sets the gradient end color; has no default value.<br /><br />
<br />
* <tt>fg_color [int, int, int|string]</tt>: Sets the foreground fill color; has no default value.<br /><br />
<br />
* <tt>bg_color [int, int, int|string]</tt>: Sets the background fill color; has no default value.<br /><br />
<br />
* <tt>stroke [int]</tt> (''default'' = <tt>0</tt>): Sets the active stroke width; strokes may be disabled by setting this value to 0. All shapes are automatically stroked with the given width and the active foreground color.<br /><br />
<br />
* <tt>shadow [int]</tt> (''default'' = <tt>0</tt>): Sets the shadow offset. In the rendering engines that support it, drawn shapes will have a soft shadow offseted the given amount on their bottom-right corner.<br /><br />
<br />
* <tt>factor [int]</tt> (''default'' = <tt>1</tt>): The factor value specifies the displacement of the active gradient, i.e. its zoom level. It is only taken into account if the active fill mode is set to gradient.<br /><br />
<br />
* <tt>bevel [int]</tt> (''default'' = <tt>0</tt>): Amount of fake bevel for all the drawn shapes. Currently only supported in squares and rounded squares; adding bevel to other shapes causes no effect.<br />
* <tt>width [int|string]</tt> (''default'' = <tt>auto</tt>): Width for the shape. Defaults to <tt>auto</tt> (automatically fill the whole drawing surface). Width may be specified as a pixel value or with the <tt>height</tt> keyword, which will give the shape the same width as its height.<br />
* <tt>height [int|string]</tt> (''default'' = <tt>auto</tt>): Height for the shape. Defaults to <tt>auto</tt> (automatically fill the whole drawing surface). Height may be specified as a pixel value or with the <tt>width</tt> keyword, which will give the shape the same height as its width.<br />
* <tt>xpos [int|string]</tt> (''required when <tt>width</tt> is not auto''): Sets the X position of the shape; only taken into account when its width is not set to automatically fill the drawing area. Position may be specified either as a relative pixel value or as an alignment:<br />
** <tt>center</tt><br />
** <tt>left</tt><br />
** <tt>right</tt><br />
* <tt>ypos [int|string]</tt> (''required when <tt>height</tt> is not auto''): Sets the Y position of the shape; only taken into account when its height is not set to automatically fill the drawing area. Position may be specified either as a relative pixel value or as an alignment:<br />
** <tt>center</tt><br />
** <tt>top</tt><br />
** <tt>bottom</tt><br />
===== Function-specific properties =====<br />
<br />
* <tt>radius [int]</tt> (''required for func'' = <tt>circle, roundedsq</tt>): Defines the radius of a drawn circle or of the rounded corners of a square.<br />
* <tt>orientation [string]</tt> (''required for func'' = <tt>triangle</tt>): Defines the orientation of the drawn triangle; possible values are:<br />
** <tt>top</tt>: The triangle has its vertex on the top and its base on the bottom.<br />
** <tt>bottom</tt>: The triangle has its vertex on the bottom and its base on the top.<br />
* <tt>file [string]</tt> (''required for func'' = <tt>bitmap</tt>): Defines the previously loaded bitmap file that must be blit into the screen.<br />
<br />
-----<br />
<br />
==== <tt>&lt;text&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;drawdata&gt;</tt><br /><br />
Children: -<br /><br />
Properties: <tt>font</tt> (''required''), <tt>vertical_align</tt> (''required''), <tt>horizontal_align</tt> (''required'')<br />
<br />
===== Example =====<br />
<br />
<pre>&lt;text font = 'text_button'<br />
vertical_align = 'center'<br />
horizontal_align = 'center'<br />
/&gt;</pre><br />
===== Description =====<br />
<br />
The <tt>text</tt> key is required on those widgets which contain a text string; it specifies the way in which the text is drawn on the screen for that single widget. All the widgets which contain text should have a <tt>text</tt> key in their DrawData definition.<br />
<br />
===== List of Widgets which require <tt>text</tt> keys =====<br />
<br />
* <tt>button_idle</tt><br />
* <tt>button_disabled</tt><br />
* <tt>checkbox_disabled</tt><br />
* <tt>checkbox_selected</tt><br />
* <tt>checkbox_default</tt><br />
* <tt>tab_active</tt><br />
* <tt>tab_inactive</tt><br />
* <tt>popup_idle</tt><br />
* <tt>popup_hover</tt><br />
Note that the text key is not really required by the parser, but any widget that wishes to display text must contain one. Adding <tt>text</tt> keys to widgets who don't natively display text (i.e. those not on the previous list) has no effect.<br />
<br />
===== Properties =====<br />
<br />
* <tt>font [string]</tt>: Font identifier from a previously created <tt>font</tt> key. This font will be used to draw the text.<br />
* <tt>vertical_alignment [string]</tt>: Vertical (Y axis) alignment of the text. Possible values:<br />
** <tt>top</tt><br />
** <tt>bottom</tt><br />
** <tt>center</tt><br />
* <tt>horizontal_alignment [string]</tt>: Horizontal (X axis) alignment of the text. Possible values:<br />
** <tt>left</tt><br />
** <tt>right</tt><br />
** <tt>center</tt><br />
<br />
-----<br />
<br />
==== <tt>&lt;layout_info&gt;</tt> ====<br />
<br />
Parent: root<br /><br />
Children: <tt>&lt;globals&gt;</tt>, <tt>&lt;dialog&gt;</tt><br /><br />
Properties: <tt>resolution</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;layout_info resolution = '320xY'&gt;<br />
...<br />
&lt;/layout_info&gt;</pre><br />
===== Description =====<br />
<br />
The <tt>layout_info</tt> key is the other root-level key of the renderer; all information contained inside it refers to the actual layout and positioning of the elements on the Graphical User Interface.<br />
<br />
===== Properties =====<br />
<br />
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.<br />
<br />
-----<br />
<br />
==== <tt>&lt;globals&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;layout_info&gt;</tt><br /><br />
Children: <tt>&lt;def&gt;</tt>, <tt>&lt;widget&gt;</tt><br /><br />
Properties: -<br />
<br />
===== Example =====<br />
<br />
<pre>&lt;globals&gt;<br />
...<br />
&lt;/globals&gt;</pre><br />
===== Description =====<br />
<br />
The <tt>globals</tt> key is a simple wrapper for all the common variables used in the design of the GUI layout (e.g. the size of a button or the padding of a specific widget.)<br />
<br />
<br />
-----<br />
<br />
==== <tt>&lt;def&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;globals&gt;</tt><br /><br />
Children: -<br /><br />
Properties: <tt>var</tt> (''required''), <tt>value</tt> (''required''), <tt>resolution</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;def var = 'WidgetSize' value = 'kBigWidgetSize' /&gt;<br />
&lt;def resolution = '320xY' var = 'WidgetSize' value = 'kNormalWidgetSize' /&gt;</pre><br />
===== Description =====<br />
<br />
A <tt>def</tt> or ''definition'' key defines a global variable to be used on the parser by giving it a name (<tt>var</tt>) and an integer value (<tt>value</tt>). Note that the <tt>value</tt> field may also contain a string representing a builtin constant value. You can find a list of such values on the description of the <tt>value</tt> parameter.<br />
<br />
Variable definitions work as aliases for commonly used values on the layouts, but some reserved variable names are also polled by the GUI system to load internal data.<br />
<br />
===== Reserved variable names =====<br />
<br />
* <tt>WidgetSize</tt>: The global size of all GUI elements.<br />
* <tt>Line.Height</tt>: The height of a line of text.<br />
* <tt>Font.Height</tt>: The height of the default font.<br />
* <tt>TabLabelWidth</tt>: The width of the label in a Tab Popup.<br />
* <tt>About.OuterBorder</tt>: Space between the edges of the screen in the About dialog.<br />
* <tt>ShowLauncherLogo</tt>: Set to <tt>1</tt> if the ScummVM should be shown on the main Launcher screen.<br />
All these values are required; failure to define them will cause the parsing of a theme layout to complain.<br />
<br />
===== Properties =====<br />
<br />
* <tt>var [string]</tt>: Identifier name for the variable.<br />
* <tt>value [int|string]</tt>: Value of the variable, represented by an integer or by a builtin constant from this list:<br />
** kThumbnailWidth<br />
** kThumbnailHeight1<br />
** kThumbnailHeight2<br />
** kButtonWidth<br />
** kButtonHeight<br />
** kSliderWidth<br />
** kSliderHeight<br />
** kBigButtonWidth<br />
** kBigButtonHeight<br />
** kBigSliderWidth<br />
** kBigSliderWidth<br />
** kBigSliderHeight<br />
** kNormalWidgetSize<br />
** kBigWidgetSize<br />
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.<br />
<br />
-----<br />
<br />
==== <tt>&lt;widget&gt;</tt> (global widget definition) ====<br />
<br />
Parent: <tt>&lt;globals&gt;</tt><br /><br />
Children: <tt>&lt;child&gt;</tt> Properties: <tt>name</tt> (''required''), <tt>size</tt>, <tt>padding</tt>, <tt>resolution</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;widget name = 'SmallButton'<br />
size = '128, 18'<br />
/&gt;</pre><br />
===== Description =====<br />
<br />
A global widget definition is a parser-exclusive alias for the layout properties of a specific widget. For instance, the definition of a global widget named <tt>Slider</tt> with certain size properties will allow you to specify <tt>Slider</tt> as a Widget type when adding widgets to a Dialog, and that widget will inherit the size properties defined in this global definition. For more information, please check the documentation on <tt>&lt;widget&gt;</tt> (''local widget definition'').<br />
<br />
<pre>&lt;dialog name = 'SampleDialog' overlays = 'screen'&gt;<br />
&lt;layout type = 'vertical' ...&gt;<br />
<br />
/* <br />
Adding a new widget; instead of specifying its size, we set<br />
its type to the previously defined 'SmallButton', hence it<br />
automaticall inherits its size<br />
*/<br />
&lt;widget name = 'A.Sample.Button'<br />
type = 'SmallButton'<br />
/&gt;<br />
<br />
...<br />
&lt;/layout&gt;<br />
&lt;/dialog&gt;</pre><br />
Because of this, there are no unique identifiers for Widget names. You may give them any alias (since these aliases are only queried by your own layout definition, inside the parser). However, for added customization, the Theme Renderer will also poll a few unique Global Widget names for their layout information:<br />
<br />
* <tt>ListWidget</tt>: Optionally loads its padding information.<br />
* <tt>PopUpWidget</tt>: Optionally loads its padding information.<br />
* <tt>EditTextWidget</tt>: Optionally loads its padding information.<br />
* <tt>Console</tt>: Optionally loads its padding information.<br />
* <tt>TabWidget.Tab</tt>: Loads size and padding information.<br />
* <tt>TabWidget.NavButton</tt>: Loads size and padding information.<br />
These values, as stated, are just for added customization; perfectly working padding defaults are built in the engine, hence they aren't required by the parser. In the case of the <tt>TabWidget</tt> sizes, their builtin default values aren't assured to work on all resolutions: Double check them and define them yourself if required.<br />
<br />
===== Properties =====<br />
<br />
* <tt>name [string]</tt>: Identifier for the widget.<br />
* <tt>size [int, int]</tt>: Width and height of the widget. You may use previously declared <tt>def</tt>s or builtin constants instead of integers.<br />
* <tt>padding [int, int, int, int]</tt>: Pixel padding for Left, Right, Top and Bottom sides, respectively.<br />
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.<br />
<br />
-----<br />
<br />
==== <tt>&lt;dialog&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;layout_info&gt;</tt><br /><br />
Children: <tt>&lt;layout&gt;</tt><br /><br />
Properties: <tt>name</tt> (''required''), <tt>overlays</tt> (''required''), <tt>shading</tt>, <tt>enabled</tt>, <tt>inset</tt>, <tt>resolution</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;dialog name = 'Launcher' overlays = 'screen'&gt;<br />
...<br />
&lt;/dialog&gt;<br />
<br />
&lt;dialog name = 'GameOptions_Graphics' overlays = 'Dialog.GlobalOptions.TabWidget'&gt;<br />
...<br />
&lt;/dialog&gt;</pre><br />
===== Description =====<br />
<br />
Dialog keys are the core of layout definitions; a <tt>dialog</tt> key is required for each dialog shown ingame, and they are distinguished by using the <tt>name</tt> property as an unique identifier.<br />
<br />
Inside of a <tt>dialog</tt> key, the actual layout of the dialog is defined by the use of <tt>layout</tt>, <tt>space</tt> and <tt>widget</tt> subkeys; see the sample definition of a GUI layout section.<br />
<br />
Note however that the first key inside a <tt>dialog</tt> must always be a <tt>layout</tt> -you cannot add widgets before defining its positioning layout.<br />
<br />
===== List of GUI Dialogs =====<br />
<br />
These are all the core dialogs of the GUI which must be implemented in order for the parsing to be successful. Remember that in order to properly define the layout of a dialog, one must add its <tt>dialog</tt> key for the given dialog ''and'' inside of it, all the dialog's own widgets must be defined.<br />
<br />
* <tt>Launcher</tt>: Global launcher menu (main dialog of the GUI).<br />
* <tt>Browser</tt>: File browser, used for add game menus, theme selections, etc.<br />
* <tt>GlobalOptions</tt>: Global options dialog.<br />
* <tt>GlobalOptions_Graphics</tt>: Graphics section of the Global Options dialog.<br />
* <tt>GlobalOptions_Audio</tt>: Audio section of the Global Options dialog.<br />
* <tt>GlobalOptions_Volume</tt>: Volume section of the Global Options dialog.<br />
* <tt>GlobalOptions_MIDI</tt>: MIDI section of the Global Options dialog.<br />
* <tt>GlobalOptions_Paths</tt>: Paths section of the Global Options dialog.<br />
* <tt>GlobalOptions_Misc</tt>: Last section of the Global Options dialog (contains theme loading, etc).<br />
* <tt>GameOptions</tt>: Game options menu (edits the options of a game).<br />
* <tt>GameOptions_Graphics</tt>: Graphics section of the Game Options dialog.<br />
* <tt>GameOptions_Audio</tt>: Audio section of the Game Options dialog.<br />
* <tt>GameOptions_Volume</tt>: Volume section of the Game Options dialog.<br />
* <tt>GameOptions_MIDI</tt>: MIDI section of the Game Options dialog.<br />
* <tt>GameOptions_Game</tt>: Actual game settings section of the Game Options dialog.<br />
* <tt>GameOptions_Paths</tt>: Paths section of the Game Options dialog.<br /><br />
<br />
* <tt>ScummMain</tt>: Main ingame menu for SCUMM based games.<br />
* <tt>ScummConfig</tt>: Options menu for SCUMM based games.<br />
* <tt>ScummSaveLoad</tt>: Save/Load menu for SCUMM based games.<br />
* <tt>ScummHelp</tt>: Help menu for SCUMM based games.<br />
===== Properties =====<br />
<br />
* <tt>name [string]</tt>: Unique name identifying the Dialog (from the above list).<br />
* <tt>overlays [string]</tt>: Position of the dialog on screen. Possible values:<br />
** <tt>screen</tt>: Dialog fills the whole screen.<br />
** <tt>screen_center</tt>: Dialog is centered in the middle of the screen.<br />
** ''Local Widget Identifier'': Dialog occupies the same space than the given Widget of another dialog. See example.<br />
* <tt>shading [string]</tt>: Sets whether all other backgrounds dialog should receive special shading when opening this dialog. Possible values:<br />
** <tt>none</tt>: No special shading.<br />
** <tt>luminance</tt>: Background dialogs are drawn in black &amp; white.<br />
** <tt>dim</tt>: Background dialogs are darkened slightly.<br />
* <tt>enabled [bool]</tt>: Sets whether this dialog is enabled. Defaults always to true. May be used to disable dialogs on certain resolutions.<br />
* <tt>inset [int]</tt>: Sets the inset value for Screen and Dialog overlays (the amount by which the new dialog is contracted).<br />
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.<br />
<br />
-----<br />
<br />
==== <tt>&lt;layout&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;dialog&gt;</tt>, <tt>&lt;layout&gt;</tt><br /><br />
Children: <tt>&lt;import&gt;</tt>, <tt>&lt;widget&gt;</tt>, <tt>&lt;space&gt;</tt>, <tt>&lt;layout&gt;</tt><br /><br />
Properties: <tt>type</tt> (''required''), <tt>center</tt>, <tt>direction</tt>, <tt>padding</tt>, <tt>spacing</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;layout type = 'vertical' center = 'true' padding = '23, 23, 8, 23'&gt;<br />
...<br />
&lt;/layout&gt;</pre><br />
===== Description =====<br />
<br />
Layout keys are the basic containers for the GUI widgets. All widgets on a dialog must be contained inside a Layout, which can be of 2 types:<br />
<br />
* Vertical Layout: Widgets inside the layout will be placed vertically, from top to bottom.<br />
* Horizontal Layout: Widgets inside the layout will be placed horizontally, from left to right.<br />
Note that you can also nest other <tt>layout</tt> keys inside a <tt>layout</tt> key to design complex GUI dialogs. You can see a detailed system on how does the Layout system work on the Example Theme Layout Definition section.<br />
<br />
===== Properties =====<br />
<br />
* <tt>type [string]</tt>: Sets whether the layout is <tt>vertical</tt> or <tt>horizontal</tt>.<br />
* <tt>center [bool]</tt>: Sets whether children widgets inside this layout will be automatically centered.<br />
* <tt>direction [string]</tt>: Sets the positioning direction of the children widgets:<br />
** <tt>right2left</tt>: Children widgets will be placed starting on the right, as they are parsed.<br />
** <tt>bottom2top</tt>: Children widgets will be placed starting on the bottom, as they are parsed.<br />
* <tt>padding [int, int, int, int]</tt>: Sets the inner padding for the children widgets inside the layout.<br />
* <tt>spacing [int]</tt>: Sets the spacing between two children widgets inside the layout.<br />
<br />
-----<br />
<br />
==== <tt>&lt;import&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;layout&gt;</tt><br /><br />
Children: -<br /><br />
Properties: <tt>layout</tt> (''required'')<br />
<br />
===== Example =====<br />
<br />
<pre>&lt;dialog name = 'GameOptions_Audio' overlays = 'Dialog.GlobalOptions.TabWidget'&gt;<br />
&lt;layout type = 'vertical' padding = '16, 16, 16, 16' spacing = '8'&gt;<br />
&lt;widget name = 'EnableTabCheckbox' type = 'Checkbox' /&gt;<br />
&lt;import layout = 'Dialog.GlobalOptions_Audio' /&gt;<br />
&lt;/layout&gt;<br />
&lt;/dialog&gt;</pre><br />
===== Description =====<br />
<br />
This powerful key allows to ''import'' (insert) the layout of a previously defined Dialog inside another layout, keeping all its properties. As you can see on the example, this comes specially in handy for the Game Options menus, since they are almost identical to the Global Options menus, except for the global ''Disable'' checkbox on top of the dialog.<br />
<br />
Note that imported Layouts work as any other child Layout or Widget: They are placed accordingly inside the current Layout, taking into account padding and spacing, and can be followed by other child widgets or other layouts, independently of their complexity.<br />
<br />
===== Properties =====<br />
<br />
* <tt>layout [string]</tt>: Identifier of a previously defined Dialog, whose layout will be imported.<br />
<br />
-----<br />
<br />
==== <tt>&lt;space&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;layout&gt;</tt><br /><br />
Children: -<br /><br />
Properties: <tt>size</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;widget name = 'StartButton' type = 'Button'/&gt;<br />
&lt;space size = '16' /&gt;<br />
&lt;widget name = 'AddGameButton' type = 'Button' /&gt;</pre><br />
===== Description =====<br />
<br />
The <tt>space</tt> key works like any other children widget, but appears obviously as a blank space. They are used when designing layouts, to separate groups of widgets.<br />
<br />
Spaces don't have width or height; they have a single <tt>size</tt> property: If the <tt>space</tt> is found inside a vertical layout, it will separate the two widgets that surround it by the given value, and same thing applies for horizontal layouts.<br />
<br />
Space keys may be optionally left without a <tt>size</tt> property: The space will automatically expand itself to fill all the remaining space inside the layout. This may be used to align widgets on the further side of a layout.<br />
<br />
<pre>&lt;layout type = 'horizontal' ...&gt;<br />
/** Add a button on the left */<br />
&lt;widget name = 'Button1' type = 'Button'/&gt;<br />
<br />
/** The space without size value will expand to fill all the layout */<br />
&lt;space/&gt;<br />
<br />
/** Add another button: */<br />
&lt;widget name = 'Button2' type = 'Button'/&gt;<br />
/** Since the space had filled the layout, this new button shrinks the<br />
space by the button's width; hence Button2 is now aligned to the right */<br />
&lt;/layout&gt;</pre><br />
===== Properties =====<br />
<br />
* <tt>size [int]</tt>: Size of the space.<br />
<br />
-----<br />
<br />
==== <tt>&lt;widget&gt;</tt> (local widget definition) ====<br />
<br />
Parent: <tt>&lt;layout&gt;</tt><br /><br />
Children: -<br /><br />
Properties: <tt>name</tt> (''required''), <tt>width</tt>, <tt>height</tt>, <tt>type</tt>, <tt>enabled</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;widget name = 'AddGameButton' <br />
width = '95'<br />
height = 'Globals.Button.Height' <br />
/&gt;<br />
&lt;widget name = 'AboutButton' <br />
type = 'Button' <br />
/&gt;</pre><br />
===== Description =====<br />
<br />
If both the <tt>width</tt> and <tt>height</tt> properties are absent, and if the <tt>type</tt> property is lacking too, or the given type doesn't define size properties, the Layout engine will automatically expand the widget to fill as much space as it has available inside its parent layout.<br />
<br />
If only one of the properties is missing, the Layout engine will expand the widget in that direction. E.g. if a widget has a specific width but no height, the widget will grow vertically to occupy as much space as possible while keeping the fixed width that has been given.<br />
<br />
===== GUI Widget Distribution =====<br />
<br />
This is a list of all the Widget definitions which are expected by the Theme engine, inside each of the Dialogs of the GUI:<br />
<br />
* <tt>Dialog.Launcher</tt>:<br />
** <tt>Dialog.Launcher.Version</tt><br />
** <tt>Dialog.Launcher.Logo</tt><br />
** <tt>Dialog.Launcher.GameList</tt><br />
** <tt>Dialog.Launcher.StartButton</tt><br />
** <tt>Dialog.Launcher.AddGameButton</tt><br />
** <tt>Dialog.Launcher.EditGameButton</tt><br />
** <tt>Dialog.Launcher.RemoveGameButton</tt><br />
** <tt>Dialog.Launcher.OptionsButton</tt><br />
** <tt>Dialog.Launcher.AboutButton</tt><br />
** <tt>Dialog.Launcher.QuitButton</tt><br />
* <tt>Dialog.Browser</tt>:<br />
** <tt>Dialog.Browser.Choose</tt><br />
** <tt>Dialog.Browser.Cancel</tt><br />
** <tt>Dialog.Browser.Up</tt><br />
** <tt>Dialog.Browser.List</tt><br />
** <tt>Dialog.Browser.Path</tt><br />
** <tt>Dialog.Browser.Headline</tt><br />
* <tt>Dialog.GlobalOptions</tt>:<br />
** <tt>Dialog.GlobalOptions.Ok</tt><br />
** <tt>Dialog.GlobalOptions.Cancel</tt><br />
** <tt>Dialog.GlobalOptions.TabWidget</tt><br />
* <tt>Dialog.GlobalOptions_Graphics</tt>:<br />
** <tt>Dialog.GlobalOptions_Graphics.grModePopup</tt><br />
** <tt>Dialog.GlobalOptions_Graphics.grRenderPopup</tt><br />
** <tt>Dialog.GlobalOptions_Graphics.grAspectCheckbox</tt><br />
** <tt>Dialog.GlobalOptions_Graphics.grFullScreenCheckbox</tt><br />
* <tt>Dialog.GlobalOptions_Audio</tt>:<tt>-</tt>Dialog.GlobalOptions_Audio.auMidiPopup<tt>-</tt>Dialog.GlobalOptions_Audio.auSampleRatePopup<tt>-</tt>Dialog.GlobalOptions_Audio.subToggleDesc<tt>-</tt>Dialog.GlobalOptions_Audio.subToggleButton<tt>-</tt>Dialog.GlobalOptions_Audio.subSubtitleSpeedSlider<tt>-</tt>Dialog.GlobalOptions_Audio.subSubtitleSpeedDesc<tt>-</tt>Dialog.GlobalOptions_Audio.subSubtitleSpeedLabel`<br />
* <tt>Dialog.GlobalOptions_Volume</tt>:<br />
** <tt>Dialog.GlobalOptions_Volume.vcMusicText</tt><br />
** <tt>Dialog.GlobalOptions_Volume.vcMusicSlider</tt><br />
** <tt>Dialog.GlobalOptions_Volume.vcMusicLabel</tt><br />
** <tt>Dialog.GlobalOptions_Volume.vcSfxText</tt><br />
** <tt>Dialog.GlobalOptions_Volume.vcSfxSlider</tt><br />
** <tt>Dialog.GlobalOptions_Volume.vcSfxLabel</tt><br />
** <tt>Dialog.GlobalOptions_Volume.vcSpeechText</tt><br />
** <tt>Dialog.GlobalOptions_Volume.vcSpeechLabel</tt><br />
** <tt>Dialog.GlobalOptions_Volume.vcSpeechSlider</tt><br />
* <tt>Dialog.GlobalOptions_MIDI</tt>:<br />
** <tt>Dialog.GlobalOptions_MIDI.mcFontButton</tt><br />
** <tt>Dialog.GlobalOptions_MIDI.mcFontClearButton</tt><br />
** <tt>Dialog.GlobalOptions_MIDI.mcFontPath</tt><br />
** <tt>Dialog.GlobalOptions_MIDI.mcMixedCheckbox</tt><br />
** <tt>Dialog.GlobalOptions_MIDI.mcMt32Checkbox</tt><br />
** <tt>Dialog.GlobalOptions_MIDI.mcGSCheckbox</tt><br />
** <tt>Dialog.GlobalOptions_MIDI.mcMidiGainText</tt><br />
** <tt>Dialog.GlobalOptions_MIDI.mcMidiGainSlider</tt><br />
** <tt>Dialog.GlobalOptions_MIDI.mcMidiGainLabel</tt><br />
* <tt>Dialog.GlobalOptions_Paths</tt>:<br />
** <tt>Dialog.GlobalOptions_Paths.SaveButton</tt><br />
** <tt>Dialog.GlobalOptions_Paths.SavePath</tt><br />
** <tt>Dialog.GlobalOptions_Paths.ThemeButton</tt><br />
** <tt>Dialog.GlobalOptions_Paths.ThemePath</tt><br />
** <tt>Dialog.GlobalOptions_Paths.ExtraButton</tt><br />
** <tt>Dialog.GlobalOptions_Paths.ExtraPath</tt><br />
* <tt>Dialog.GlobalOptions_Misc</tt>:<br />
** <tt>Dialog.GlobalOptions_Misc.ThemeButton</tt><br />
** <tt>Dialog.GlobalOptions_Misc.CurTheme</tt><br />
** <tt>Dialog.GlobalOptions_Misc.AutosavePeriod</tt><br />
* <tt>Dialog.GameOptions</tt>:<br />
** <tt>Dialog.GameOptions.Ok</tt><br />
** <tt>Dialog.GameOptions.Cancel</tt><br />
** <tt>Dialog.GameOptions.TabWidget</tt><br />
* <tt>Dialog.GameOptions_Graphics</tt>:<br />
** <tt>Dialog.GameOptions_Graphics.EnableTabCheckbox</tt><br />
** ''All widgets from'' <tt>Dialog.GlobalOptions_Graphics</tt><br />
* <tt>Dialog.GameOptions_Audio</tt>:<br />
** <tt>Dialog.GameOptions_Graphics.EnableTabCheckbox</tt><br />
** ''All widgets from'' <tt>Dialog.GlobalOptions_Audio</tt><br />
* <tt>Dialog.GameOptions_Volume</tt>:<br />
** <tt>Dialog.GameOptions_Graphics.EnableTabCheckbox</tt><br />
** ''All widgets from'' <tt>Dialog.GlobalOptions_Volume</tt><br />
* <tt>Dialog.GameOptions_MIDI</tt>:<br />
** <tt>Dialog.GameOptions_Graphics.EnableTabCheckbox</tt><br />
** ''All widgets from'' <tt>Dialog.GlobalOptions_MIDI</tt><br />
* <tt>Dialog.GameOptions_Game</tt>:<br />
** <tt>Dialog.GameOptions_Game.Id</tt><br />
** <tt>Dialog.GameOptions_Game.Domain</tt><br />
** <tt>Dialog.GameOptions_Game.Name</tt><br />
** <tt>Dialog.GameOptions_Game.Desc</tt><br />
** <tt>Dialog.GameOptions_Game.Lang</tt><br />
** <tt>Dialog.GameOptions_Game.Platform</tt><br />
* <tt>Dialog.GameOptions_Paths</tt>:<br />
** <tt>Dialog.GameOptions_Paths.Savepath</tt><br />
** <tt>Dialog.GameOptions_Paths.SavepathText</tt><br />
** <tt>Dialog.GameOptions_Paths.Extrapath</tt><br />
** <tt>Dialog.GameOptions_Paths.ExtrapathText</tt><br />
** <tt>Dialog.GameOptions_Paths.Gamepath</tt><br />
** <tt>Dialog.GameOptions_Paths.GamepathText</tt><br />
* <tt>Dialog.ScummMain</tt>:<br />
** <tt>Dialog.ScummMain.Resume</tt><br />
** <tt>Dialog.ScummMain.Save</tt><br />
** <tt>Dialog.ScummMain.Options</tt><br />
** <tt>Dialog.ScummMain.Help</tt><br />
** <tt>Dialog.ScummMain.About</tt><br />
** <tt>Dialog.ScummMain.Quit</tt><br />
* <tt>Dialog.ScummConfig</tt>:<br />
** <tt>Dialog.ScummConfig.Cancel</tt><br />
** <tt>Dialog.ScummConfig.Ok</tt><br />
** <tt>Dialog.ScummConfig.subSubtitleSpeedDesc</tt><br />
** <tt>Dialog.ScummConfig.subSubtitleSpeedSlider</tt><br />
** <tt>Dialog.ScummConfig.subSubtitleSpeedLabel</tt><br />
** <tt>Dialog.ScummConfig.subToggleDesc</tt><br />
** <tt>Dialog.ScummConfig.subToggleButton</tt><br />
** <tt>Dialog.ScummConfig.vcSpeechText</tt><br />
** <tt>Dialog.ScummConfig.vcSpeechSlider</tt><br />
** <tt>Dialog.ScummConfig.vcSpeechLabel</tt><br />
** <tt>Dialog.ScummConfig.vcSfxText</tt><br />
** <tt>Dialog.ScummConfig.vcSfxSlider</tt><br />
** <tt>Dialog.ScummConfig.vcSfxLabel</tt><br />
** <tt>Dialog.ScummConfig.vcMusicText</tt><br />
** <tt>Dialog.ScummConfig.vcMusicSlider</tt><br />
** <tt>Dialog.ScummConfig.vcMusicLabel</tt><br />
* <tt>Dialog.ScummSaveLoad</tt>:<br />
** <tt>Dialog.ScummSaveLoad.Choose</tt><br />
** <tt>Dialog.ScummSaveLoad.Cancel</tt><br />
** <tt>Dialog.ScummSaveLoad.Thumbnail</tt><br />
** <tt>Dialog.ScummSaveLoad.List</tt><br />
* <tt>Dialog.ScummHelp</tt>:<br />
** <tt>Dialog.ScummHelp.Prev</tt><br />
** <tt>Dialog.ScummHelp.Next</tt><br />
** <tt>Dialog.ScummHelp.Close</tt><br />
** <tt>Dialog.ScummHelp.HelpText</tt><br />
** <tt>Dialog.ScummHelp.Title</tt><br />
Note that this list uses the full, internal names of each Widget, for reference reasons. When defining the widget called <tt>Dialog.ScummConfig.vcSfxLabel</tt>, the value of the <tt>name</tt> key must be <tt>vcSfxLabel</tt>, but such key must obviously be contained inside the <tt>ScummConfig</tt> dialog.<br />
<br />
===== Properties =====<br />
<br />
* <tt>name [string]</tt>: Unique identifier for this widget (as seen on the GUI Widget distribution list).<br />
* <tt>width [int]</tt>: Width of the widget.<br />
* <tt>height [int]</tt>: Height of the widget.<br />
* <tt>type [string]</tt>: Global Widget Definition from which this widget will inherit its properties.<br />
* <tt>enabled [bool]</tt>: Sets whether this widget is enabled. Defaults always to true. May be used to disable widgets on certain resolutions.</div>Tanokuhttps://wiki.scummvm.org/index.php?title=GUI_Themes/Specs&diff=9486GUI Themes/Specs2008-10-15T12:16:25Z<p>Tanoku: </p>
<hr />
<div>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.<br />
<br />
=== Theme Packages ===<br />
<br />
A theme file in the new version of the ScummVM GUI is a compressed ZIP file which contains all the required information<br />
<br />
* One or more STX (ScummVM Theme XML) files.<br />
* Any external Bitmap fonts.<br />
* Any external Bitmap images.<br />
* A <tt>THEMERC</tt> file.<br />
===== The STX Files =====<br />
<br />
STX (ScummVM Theme XML) is the new format for theme descriptions on the Graphical User Interface of ScummVM.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===== The external resources =====<br />
<br />
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.<br />
<br />
Packaged resources will then be accessible from the STX syntax (check the <tt>font</tt> and <tt>bitmap</tt> keys in the STX documentation).<br />
<br />
===== The <tt>THEMERC</tt> file =====<br />
<br />
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:<br />
<br />
<pre>[SCUMMVM_THEME_V23:Name of the ScummVM Theme:Name of the Author]</pre><br />
The <tt>SCUMMVM_THEME_V23</tt> is just a simple check to make sure that the theme was developed to be used on the proper version of the GUI. 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.<br />
<br />
===== Building theme packages =====<br />
<br />
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 SVN repository.<br />
<br />
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.<br />
<br />
This Python script is totally standalone and doesn't require external ZIP utilities, only a standard Python distribution.<br />
<br />
===== Building the built-in theme =====<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
By default, the <tt>ScummVM Classic Theme</tt> is the built-in theme.<br />
<br />
=== Drawing specifications ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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/ThemeRenderer.h&quot;</tt> file, in the <tt>DrawData</tt> enumeration inside the <tt>ThemeRenderer</tt> class.<br />
<br />
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.<br />
<br />
=== Theme Layout specifications ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== Syntax overview ===<br />
<br />
A full STX theme description is composed of:<br />
<br />
* A root <tt>&lt;render_info&gt;</tt> key, containing all the information regarding the looks of the theme.<br />
** An optional <tt>&lt;palette&gt;</tt> key, containing color definitions.<br />
** An optional <tt>&lt;bitmaps&gt;</tt> key, containing all the loaded bitmaps which will be used on the GUI.<br />
** A <tt>&lt;fonts&gt;</tt> key, specifying the fonts used to draw text on the GUI.<br />
** A <tt>&lt;drawdata&gt;</tt> key for ''each'' DrawData identifier of the Theme Engine, specifying how is each individual widget drawn.<br />
* A root &lt;layout_info&gt; key, containing all the information regarding the layout of the theme.<br />
** A <tt>&lt;globals&gt;</tt> key, containing the global variables to use on the layout design.<br />
** 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.<br />
Here's a schematic overview of the layout of keys in a STX file:<br />
<br />
<pre>&lt;render_info&gt;<br />
&lt;palette&gt;<br />
...<br />
&lt;/palette&gt;<br />
<br />
&lt;bitmaps&gt;<br />
...<br />
&lt;/bitmaps&gt;<br />
<br />
&lt;fonts&gt;<br />
...<br />
&lt;/fonts&gt;<br />
<br />
&lt;drawdata&gt;<br />
...<br />
&lt;/drawdata&gt;<br />
<br />
...<br />
&lt;/render_info&gt;<br />
<br />
&lt;layout_info&gt;<br />
&lt;globals&gt;<br />
...<br />
&lt;/globals&gt;<br />
<br />
&lt;dialog&gt;<br />
...<br />
&lt;/dialog&gt;<br />
<br />
...<br />
&lt;/layout_info&gt;</pre><br />
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 Subversion repository, while consulting the following documentation for each specific key:<br />
<br />
=== Detailed STX documentation ===<br />
<br />
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]].<br />
<br />
=== Resolution-dependent keys and layouts ===<br />
<br />
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.<br />
<br />
The resolution property must contain one or more resolutions, comma separated, for which the given key is supposed to be loaded. Resolutions preceded by the minus sign will block the key from being loaded in that resolution, while resolutions without any modifiers will force the theme to be loaded in all resolutions. Here are a few examples:<br />
<br />
<pre>/* Key will be loaded in all resolutions */<br />
&lt;render_info&gt;<br />
<br />
/* Key will ONLY be loaded in resolutions with 320 width */<br />
&lt;render_info resolution = '320xY'&gt;<br />
<br />
/* Key will ONLY be loaded in resolutions with 240 height and in the 320x200 resolution */<br />
&lt;render_info resolution = 'Xx240, 320x200'&gt;<br />
<br />
/* Key will be loaded on ALL resolutions except for 320x200 */<br />
&lt;render_info resolution = '-320x200'&gt;<br />
<br />
/* Key will ONLY be loaded in resolutions with 320 width; the -240xY is superfluous. */<br />
&lt;render_info resolution = '320xY, -240xY'&gt;</pre><br />
Note that the Theme Parser does not assert on repeated keys or values, it just replaces them accordingly. For instance, the following variable definition:<br />
<br />
<pre>&lt;def var = 'TestVar' value = '100'/&gt;<br />
&lt;def var = 'TestVar' value = '200' resolution = '320xY'/&gt;</pre><br />
won't fail to parse. What will happen when loading the theme using a resolution with 320 width 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 ''without'' a with of 320, the <tt>ThemeVal</tt> will be assigned the <tt>100</tt> value and the second key will be plain ignored.<br />
<br />
The &quot;proper&quot; way to do that multi-resolution assignment would obviously be:<br />
<br />
<pre>&lt;def var = 'TestVar' value = '100' resolution = '-320xY'/&gt;<br />
&lt;def var = 'TestVar' value = '200' resolution = '320xY'/&gt;</pre><br />
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>-320xY</tt> resolution tags, and instead write a layout that works on all resolutions and overwrite parts of it with the '320xY' tag.</div>Tanokuhttps://wiki.scummvm.org/index.php?title=GUI_Themes/STX_Syntax&diff=9485GUI Themes/STX Syntax2008-10-15T12:16:21Z<p>Tanoku: New page: This page contains a detailed overview of all the possible XML key values in a STX file. See wiki page for the general information of the new Theme Format. ==== <tt>&...</p>
<hr />
<div>This page contains a detailed overview of all the possible XML key values in a STX file. See [[GUI Themes/Specs|wiki page]] for the general information of the new Theme Format.<br />
<br />
==== <tt>&lt;render_info&gt;</tt> ====<br />
<br />
Parent: root<br /><br />
Children: <tt>&lt;palette&gt;</tt>, <tt>&lt;fonts&gt;</tt>, <tt>&lt;bitmaps&gt;</tt>, <tt>&lt;cursor&gt;</tt>, <tt>&lt;defaults&gt;</tt>, <tt>&lt;drawdata&gt;</tt><br /><br />
Properties: <tt>resolution</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;render_info resolution = &quot;320x240&quot;&gt;<br />
...<br />
&lt;/render_info&gt;</pre><br />
===== Description =====<br />
<br />
The <tt>render_info</tt> key specifies that all children keys contain information regarding the looks of the theme, i.e. the actual Drawing Specifications.<br />
<br />
===== Properties =====<br />
<br />
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.<br />
<br />
-----<br />
<br />
==== <tt>&lt;palette&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;render_info&gt;</tt><br /><br />
Children: <tt>&lt;color&gt;</tt><br /><br />
Properties: -<br />
<br />
===== Example =====<br />
<br />
<pre>&lt;palette&gt;<br />
...<br />
&lt;/palette&gt;</pre><br />
===== Description =====<br />
<br />
The <tt>palette</tt> key is a simple wrapper; it contains all the <tt>color</tt> definitions for the theme.<br />
<br />
<br />
-----<br />
<br />
==== <tt>&lt;color&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;palette&gt;</tt><br /><br />
Children: - Properties: <tt>name</tt> (''required''), <tt>rgb</tt> (''required'')<br />
<br />
===== Example =====<br />
<br />
<pre>&lt;color name = 'red'<br />
rgb = '255, 0, 0'<br />
/&gt;</pre><br />
===== Description =====<br />
<br />
Color keys define aliases for commonly used colors on the theme. Once you define a color name and its RGB equivalent, any key properties which are expecting a RGB color definition will accept such alias.<br />
<br />
Color aliases are exclusive to the parser engine, they are replaced by their actual RGB values when loaded into the Theme Renderer.<br />
<br />
===== Properties =====<br />
<br />
* <tt>name [string]</tt>: Name/alias of the color.<br />
* <tt>rgb [int, int, int]</tt>: RGB (red/green/blue) values for the color, comma separated.<br />
<br />
-----<br />
<br />
==== <tt>&lt;bitmaps&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;render_info&gt;</tt><br /><br />
Children: <tt>&lt;bitmap&gt;</tt><br /><br />
Properties: -<br />
<br />
===== Example =====<br />
<br />
<pre>&lt;bitmaps&gt;<br />
...<br />
&lt;/bitmaps&gt;</pre><br />
===== Description =====<br />
<br />
The <tt>bitmaps</tt> key is a simple wrapper; it contains all the <tt>bitmap</tt> keys for the theme.<br />
<br />
<br />
-----<br />
<br />
==== <tt>&lt;bitmap&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;bitmaps&gt;</tt><br /><br />
Children: -<br /><br />
Properties: <tt>filename</tt> (''required''), <tt>resolution</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;bitmap filename = 'logo.bmp'/&gt;</pre><br />
===== Description =====<br />
<br />
A <tt>bitmap</tt> key specifies a bitmap file to be loaded by the theme renderer. You may load as many bitmaps as you desire; they are expected to be 24 bit standard Windows bitmaps, and to packed together with the STX file.<br />
<br />
Once a bitmap file has been loaded, it may be referenced by its filename in the STX file where required:<br />
<br />
===== Properties =====<br />
<br />
* <tt>filename [string]</tt>: Path and filename to the bitmap file.<br />
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.<br />
<br />
-----<br />
<br />
==== <tt>&lt;fonts&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;render_info&gt;</tt><br /><br />
Children: <tt>&lt;font&gt;</tt><br /><br />
Properties: -<br />
<br />
===== Example =====<br />
<br />
<pre>&lt;fonts&gt;<br />
...<br />
&lt;/fonts&gt;</pre><br />
===== Description =====<br />
<br />
The <tt>fonts</tt> key is a simple wrapper; it contains all the <tt>font</tt> keys for the theme.<br />
<br />
<br />
-----<br />
<br />
==== <tt>&lt;font&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;fonts&gt;</tt><br /><br />
Children: -<br /><br />
Properties: <tt>id</tt> (''required''), <tt>file</tt> (''required''), <tt>color</tt> (''required''), <tt>resolution</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;font id = 'text_default'<br />
file = 'default'<br />
color = 'black'<br />
/&gt;</pre><br />
===== Description =====<br />
<br />
Text drawing on the new GUI is based on Font structures. The renderer expects several font definitions, used internally for text drawing; you can see Font definitions as the text equivalent of a Drawing Step on the Vector Renderer.<br />
<br />
===== Required Font identifiers =====<br />
<br />
This is the list of all the required font identifiers; these identifiers are used internally by the renderer (i.e. when writing static text on the GUI) and may also be referenced on any DrawStep to define the specific font which will be used to draw such widget.<br />
<br />
* <tt>text_default</tt>: Core font for the engine, used to draw all the static text and most of the text in widgets.<br />
* <tt>text_hover</tt>: Used for text which is currently being highlighted / hovered by the mouse.<br />
* <tt>text_disabled</tt>: Used for text on disabled widgets.<br />
* <tt>text_inverted</tt>: Text which is currently selected and has a special selection background.<br />
* <tt>text_button</tt>: Default text for Button widgets.<br />
* <tt>text_button_hover</tt>: Default text for highlighted button widgets.<br />
* <tt>text_normal</tt>: ''Normal'', smaller text (i.e. non bold) used sparsely (editable text widgets, about dialog, etc).<br />
For performance reasons, these identifiers are unique and limited (i.e. the parser doesn't expect any other custom identifiers). Future versions of the Theme Format may allow for custom Fonts specific to certain widgets.<br />
<br />
===== Properties =====<br />
<br />
* <tt>id [string]</tt>: Unique font identifier.<br />
* <tt>file [string]</tt>: External Font file to load. Use &quot;default&quot; to let the renderer choose the most appropriate default font based on the active resolution (usually an builtin one).<br />
* <tt>color [int, int, int|string]</tt>: Color to draw the text with.<br />
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.<br />
<br />
-----<br />
<br />
==== <tt>&lt;defaults&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;render_info&gt;</tt>, <tt>&lt;drawdata&gt;</tt><br /><br />
Children: -<br /><br />
Properties: See DrawStep properties.<br />
<br />
===== Example =====<br />
<br />
<pre>&lt;defaults fill = 'gradient' fg_color = 'white' bevel_color = '237, 169, 72'/&gt;</pre><br />
===== Description =====<br />
<br />
The <tt>defaults</tt> key may be used to specify default values to be used on ''all'' DrawSteps in order to avoid code repetition. You may set default values for any drawing properties which is shared by all DrawSteps: Check the DrawStep specification for a detailed list.<br />
<br />
If found on the <tt>&lt;render_info&gt;</tt> scope, these defaults will be applied to all DrawSteps found inside any of the DrawData definitions. Optionally, you may use the defaults key inside a <tt>&lt;drawdata&gt;</tt> key to temporarily override the global defaults for all the DrawSteps inside that DrawData key.<br />
<br />
<br />
-----<br />
<br />
==== <tt>&lt;cursor&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;render_info&gt;</tt><br /><br />
Children: -<br /><br />
Properties: <tt>file</tt> (''required''), <tt>hotspot</tt> (''required''), <tt>scale</tt> (''required''), <tt>resolution</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;cursor file = 'cursor.bmp' hotspot = '0, 0' scale = '3'/&gt;</pre><br />
===== Description =====<br />
<br />
If the parser finds a <tt>cursor</tt> key in the <tt>render_info</tt> scope, it will try to load a custom bitmap cursor to use in the Graphical User Interface. If no <tt>cursor</tt> key is found, the GUI will default to the built-in cross cursor.<br />
<br />
Because of bitmap scaling issues, make sure to specify several different cursor definitions, one for each significant resolution.<br />
<br />
===== Properties =====<br />
<br />
* <tt>file [string]</tt>: Filename for the bitmap with the cursor shape (must have been loaded previously).<br />
* <tt>hotspot [int, int]</tt>: Coordinates for the point in the bitmap which will be used for click calculations.<br />
* <tt>scale [int]</tt>: Scale at which this cursor is supposed to be used.<br />
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.<br />
<br />
-----<br />
<br />
==== <tt>&lt;drawdata&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;render_info&gt;</tt><br /><br />
Children: <tt>&lt;defaults&gt;</tt>, <tt>&lt;drawstep&gt;</tt>, <tt>&lt;text&gt;</tt><br /><br />
Properties: <tt>id</tt> (''required''), <tt>cache</tt>, <tt>resolution</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;drawdata id = 'mainmenu_bg' cache = false&gt;<br />
&lt;drawstep ...<br />
/&gt;<br />
&lt;/drawdata&gt;</pre><br />
===== Description =====<br />
<br />
DrawData keys are the core of the rendering engine. They specifiy via their own DrawStep children the looks of all the UI elements for each possible state.<br />
<br />
The Theme Renderer is expecting a specific set of DrawData items for each possible widget state with unique identifiers. The list of DD identifiers is as follows:<br />
<br />
===== Required DrawData identifiers =====<br />
<br />
* <tt>mainmenu_bg</tt>, <tt>special_bg</tt>, <tt>plain_bg</tt>, <tt>default_bg</tt>: Backgrounds for the different dialogs.<br />
* <tt>text_selection</tt>: Background for selected (inverted) text.<br />
* <tt>widget_default</tt>, <tt>widget_small</tt>: Default backgrounds for widgets.<br />
* <tt>widget_textedit</tt>: Background for the Text Edit widget.<br />
* <tt>widget_slider</tt>: Background for the (empty) slider widget.<br />
* <tt>button_idle</tt>, <tt>button_hover</tt>, <tt>button_disabled</tt>: States for the Button widget.<br />
* <tt>slider_full</tt>, <tt>slider_hover</tt>, <tt>slider_disabled</tt>: States for the Slider widget.<br />
* <tt>checkbox_default</tt>, <tt>checkbox_disabled</tt>, <tt>checkbox_selected</tt>: States for the Checkbox widget.<br />
* <tt>tab_active</tt>, <tt>tab_inactive</tt>: States for the selected/deselected tab.<br />
* <tt>tab_background</tt>: Background behind the tab list.<br />
* <tt>scrollbar_base</tt>: Background for the scrollbar widget.<br />
* <tt>scrollbar_button_idle</tt>, <tt>scrollbar_button_hover</tt>: States for the scrollbar up/down buttons.<br />
* <tt>scrollbar_handle_idle</tt>, <tt>scrollbar_handle_hover</tt>: States for the scrolling handle of the scrollbar.<br />
* <tt>popup_idle</tt>, <tt>popup_hover</tt>: States for the popup selection widget.<br />
* <tt>caret</tt>: Text edition caret.<br />
* <tt>separator</tt>: Basic horizontal separator.<br />
Remember that although all these identifiers don't need to be implemented for the theme parsing to be successful, the parser will complain on any missing assets and the GUI will obviously be lacking widget graphics.<br />
<br />
Also, note that each DrawData key ''must'' contain at least a child DrawStep, since it actually defines the graphic drawing for the widget/state.<br />
<br />
===== Properties =====<br />
<br />
* <tt>id [string]</tt>: Unique identifier for the drawing asset.<br />
* <tt>cache [bool]</tt>: Lets the renderer know that this drawing asset may be cached for performance.<br />
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.<br />
<br />
-----<br />
<br />
==== <tt>&lt;drawstep&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;drawdata&gt;</tt><br /><br />
Children: -<br /><br />
Properties: <tt>func</tt> (''required''), ...<br />
<br />
===== Example =====<br />
<br />
<pre>&lt;drawstep func = 'roundedsq'<br />
radius = '6'<br />
stroke = 1<br />
fill = 'gradient'<br />
shadow = 0<br />
fg_color = 'shadowcolor'<br />
gradient_start = 'brightred'<br />
gradient_end = 'darkred'<br />
bevel = 1<br />
/&gt;</pre><br />
===== Description =====<br />
<br />
DrawSteps are the core of the GUI drawing engine; in order to draw a Widget state to screen (e.g. a selected button), this drawing process is split into several simpler drawing functions, called DrawSteps.<br />
<br />
Each <tt>drawdata</tt> key must contain one or more DrawSteps. These steps are parsed from top to bottom and their drawing information is stored and later drawn in that same exact order: That means that the last DrawStep inside a DrawData set will appear on top.<br />
<br />
The most important property of a DrawStep is the <tt>func</tt> (or function) of the step, the primitive drawing function that will be used. All other properties are optional parameters to that drawing function, such as the foreground and background colors, the stroke used, and a long etc.<br />
<br />
Take a look at the full list of properties to see which properties are required by each function.<br />
<br />
===== Required properties =====<br />
<br />
* <tt>func [string]</tt>: Specifies the drawing function used on the step from one of the following:<br />
** <tt>circle</tt>: Draws a primitive circle.<br />
** <tt>square</tt>: Draws a primitive square/rectangle.<br />
** <tt>roundedsq</tt>: Draws a rounded square/rectangle (that is, a rectangle with rounded corners).<br />
** <tt>bevelsq</tt>: Draws a square/rectangle with beveled borders. This square ignores the active fill mode, as it is never filled. It's used to reproduce the old Classic GUI Theme.<br />
** <tt>line</tt>: Draws a straight line.<br />
** <tt>triangle</tt>: Draws a triangle. Triangles are always isosceles, meaning they are drawn inside the square defined by the position and size values, with the given width as the base of the triangle and the given height as the height of the triangle.<br />
** <tt>fill</tt>: This drawing function ignores position and size parameters, as it completely fills the active drawing surface taken into account the active fill mode and colors.<br />
** <tt>bitmap</tt>: Ignores all drawing information and blits the given Bitmap into the surface.<br />
===== Common (optional) properties =====<br />
<br />
* <tt>fill [string]</tt>: Specifies the fill mode for the drawn shape. Possible values:<br />
** <tt>none</tt>: Disables filling so only the stroke is shown.<br />
** <tt>foreground</tt> (''default''): Fills the whole shape with the active foreground color.<br />
** <tt>background</tt>: Fills the whole shape with the active background color.<br />
** <tt>gradient</tt>: Fills the whole shape with the active gradient.<br /><br />
<br />
* <tt>gradient_start [int, int, int|string]</tt>: Sets the gradient start color; has no default value.<br /><br />
<br />
* <tt>gradient_end [int, int, int|string]</tt>: Sets the gradient end color; has no default value.<br /><br />
<br />
* <tt>fg_color [int, int, int|string]</tt>: Sets the foreground fill color; has no default value.<br /><br />
<br />
* <tt>bg_color [int, int, int|string]</tt>: Sets the background fill color; has no default value.<br /><br />
<br />
* <tt>stroke [int]</tt> (''default'' = <tt>0</tt>): Sets the active stroke width; strokes may be disabled by setting this value to 0. All shapes are automatically stroked with the given width and the active foreground color.<br /><br />
<br />
* <tt>shadow [int]</tt> (''default'' = <tt>0</tt>): Sets the shadow offset. In the rendering engines that support it, drawn shapes will have a soft shadow offseted the given amount on their bottom-right corner.<br /><br />
<br />
* <tt>factor [int]</tt> (''default'' = <tt>1</tt>): The factor value specifies the displacement of the active gradient, i.e. its zoom level. It is only taken into account if the active fill mode is set to gradient.<br /><br />
<br />
* <tt>bevel [int]</tt> (''default'' = <tt>0</tt>): Amount of fake bevel for all the drawn shapes. Currently only supported in squares and rounded squares; adding bevel to other shapes causes no effect.<br />
* <tt>width [int|string]</tt> (''default'' = <tt>auto</tt>): Width for the shape. Defaults to <tt>auto</tt> (automatically fill the whole drawing surface). Width may be specified as a pixel value or with the <tt>height</tt> keyword, which will give the shape the same width as its height.<br />
* <tt>height [int|string]</tt> (''default'' = <tt>auto</tt>): Height for the shape. Defaults to <tt>auto</tt> (automatically fill the whole drawing surface). Height may be specified as a pixel value or with the <tt>width</tt> keyword, which will give the shape the same height as its width.<br />
* <tt>xpos [int|string]</tt> (''required when <tt>width</tt> is not auto''): Sets the X position of the shape; only taken into account when its width is not set to automatically fill the drawing area. Position may be specified either as a relative pixel value or as an alignment:<br />
** <tt>center</tt><br />
** <tt>left</tt><br />
** <tt>right</tt><br />
* <tt>ypos [int|string]</tt> (''required when <tt>height</tt> is not auto''): Sets the Y position of the shape; only taken into account when its height is not set to automatically fill the drawing area. Position may be specified either as a relative pixel value or as an alignment:<br />
** <tt>center</tt><br />
** <tt>top</tt><br />
** <tt>bottom</tt><br />
===== Function-specific properties =====<br />
<br />
* <tt>radius [int]</tt> (''required for func'' = <tt>circle, roundedsq</tt>): Defines the radius of a drawn circle or of the rounded corners of a square.<br />
* <tt>orientation [string]</tt> (''required for func'' = <tt>triangle</tt>): Defines the orientation of the drawn triangle; possible values are:<br />
** <tt>top</tt>: The triangle has its vertex on the top and its base on the bottom.<br />
** <tt>bottom</tt>: The triangle has its vertex on the bottom and its base on the top.<br />
* <tt>file [string]</tt> (''required for func'' = <tt>bitmap</tt>): Defines the previously loaded bitmap file that must be blit into the screen.<br />
<br />
-----<br />
<br />
==== <tt>&lt;text&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;drawdata&gt;</tt><br /><br />
Children: -<br /><br />
Properties: <tt>font</tt> (''required''), <tt>vertical_align</tt> (''required''), <tt>horizontal_align</tt> (''required'')<br />
<br />
===== Example =====<br />
<br />
<pre>&lt;text font = 'text_button'<br />
vertical_align = 'center'<br />
horizontal_align = 'center'<br />
/&gt;</pre><br />
===== Description =====<br />
<br />
The <tt>text</tt> key is required on those widgets which contain a text string; it specifies the way in which the text is drawn on the screen for that single widget. All the widgets which contain text should have a <tt>text</tt> key in their DrawData definition.<br />
<br />
===== List of Widgets which require <tt>text</tt> keys =====<br />
<br />
* <tt>button_idle</tt><br />
* <tt>button_disabled</tt><br />
* <tt>checkbox_disabled</tt><br />
* <tt>checkbox_selected</tt><br />
* <tt>checkbox_default</tt><br />
* <tt>tab_active</tt><br />
* <tt>tab_inactive</tt><br />
* <tt>popup_idle</tt><br />
* <tt>popup_hover</tt><br />
Note that the text key is not really required by the parser, but any widget that wishes to display text must contain one. Adding <tt>text</tt> keys to widgets who don't natively display text (i.e. those not on the previous list) has no effect.<br />
<br />
===== Properties =====<br />
<br />
* <tt>font [string]</tt>: Font identifier from a previously created <tt>font</tt> key. This font will be used to draw the text.<br />
* <tt>vertical_alignment [string]</tt>: Vertical (Y axis) alignment of the text. Possible values:<br />
** <tt>top</tt><br />
** <tt>bottom</tt><br />
** <tt>center</tt><br />
* <tt>horizontal_alignment [string]</tt>: Horizontal (X axis) alignment of the text. Possible values:<br />
** <tt>left</tt><br />
** <tt>right</tt><br />
** <tt>center</tt><br />
<br />
-----<br />
<br />
==== <tt>&lt;layout_info&gt;</tt> ====<br />
<br />
Parent: root<br /><br />
Children: <tt>&lt;globals&gt;</tt>, <tt>&lt;dialog&gt;</tt><br /><br />
Properties: <tt>resolution</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;layout_info resolution = '320xY'&gt;<br />
...<br />
&lt;/layout_info&gt;</pre><br />
===== Description =====<br />
<br />
The <tt>layout_info</tt> key is the other root-level key of the renderer; all information contained inside it refers to the actual layout and positioning of the elements on the Graphical User Interface.<br />
<br />
===== Properties =====<br />
<br />
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.<br />
<br />
-----<br />
<br />
==== <tt>&lt;globals&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;layout_info&gt;</tt><br /><br />
Children: <tt>&lt;def&gt;</tt>, <tt>&lt;widget&gt;</tt><br /><br />
Properties: -<br />
<br />
===== Example =====<br />
<br />
<pre>&lt;globals&gt;<br />
...<br />
&lt;/globals&gt;</pre><br />
===== Description =====<br />
<br />
The <tt>globals</tt> key is a simple wrapper for all the common variables used in the design of the GUI layout (e.g. the size of a button or the padding of a specific widget.)<br />
<br />
<br />
-----<br />
<br />
==== <tt>&lt;def&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;globals&gt;</tt><br /><br />
Children: -<br /><br />
Properties: <tt>var</tt> (''required''), <tt>value</tt> (''required''), <tt>resolution</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;def var = 'WidgetSize' value = 'kBigWidgetSize' /&gt;<br />
&lt;def resolution = '320xY' var = 'WidgetSize' value = 'kNormalWidgetSize' /&gt;</pre><br />
===== Description =====<br />
<br />
A <tt>def</tt> or ''definition'' key defines a global variable to be used on the parser by giving it a name (<tt>var</tt>) and an integer value (<tt>value</tt>). Note that the <tt>value</tt> field may also contain a string representing a builtin constant value. You can find a list of such values on the description of the <tt>value</tt> parameter.<br />
<br />
Variable definitions work as aliases for commonly used values on the layouts, but some reserved variable names are also polled by the GUI system to load internal data.<br />
<br />
===== Reserved variable names =====<br />
<br />
* <tt>WidgetSize</tt>: The global size of all GUI elements.<br />
* <tt>Line.Height</tt>: The height of a line of text.<br />
* <tt>Font.Height</tt>: The height of the default font.<br />
* <tt>TabLabelWidth</tt>: The width of the label in a Tab Popup.<br />
* <tt>About.OuterBorder</tt>: Space between the edges of the screen in the About dialog.<br />
* <tt>ShowLauncherLogo</tt>: Set to <tt>1</tt> if the ScummVM should be shown on the main Launcher screen.<br />
All these values are required; failure to define them will cause the parsing of a theme layout to complain.<br />
<br />
===== Properties =====<br />
<br />
* <tt>var [string]</tt>: Identifier name for the variable.<br />
* <tt>value [int|string]</tt>: Value of the variable, represented by an integer or by a builtin constant from this list:<br />
** kThumbnailWidth<br />
** kThumbnailHeight1<br />
** kThumbnailHeight2<br />
** kButtonWidth<br />
** kButtonHeight<br />
** kSliderWidth<br />
** kSliderHeight<br />
** kBigButtonWidth<br />
** kBigButtonHeight<br />
** kBigSliderWidth<br />
** kBigSliderWidth<br />
** kBigSliderHeight<br />
** kNormalWidgetSize<br />
** kBigWidgetSize<br />
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.<br />
<br />
-----<br />
<br />
==== <tt>&lt;widget&gt;</tt> (global widget definition) ====<br />
<br />
Parent: <tt>&lt;globals&gt;</tt><br /><br />
Children: <tt>&lt;child&gt;</tt> Properties: <tt>name</tt> (''required''), <tt>size</tt>, <tt>padding</tt>, <tt>resolution</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;widget name = 'SmallButton'<br />
size = '128, 18'<br />
/&gt;</pre><br />
===== Description =====<br />
<br />
A global widget definition is a parser-exclusive alias for the layout properties of a specific widget. For instance, the definition of a global widget named <tt>Slider</tt> with certain size properties will allow you to specify <tt>Slider</tt> as a Widget type when adding widgets to a Dialog, and that widget will inherit the size properties defined in this global definition. For more information, please check the documentation on <tt>&lt;widget&gt;</tt> (''local widget definition'').<br />
<br />
<pre>&lt;dialog name = 'SampleDialog' overlays = 'screen'&gt;<br />
&lt;layout type = 'vertical' ...&gt;<br />
<br />
/* <br />
Adding a new widget; instead of specifying its size, we set<br />
its type to the previously defined 'SmallButton', hence it<br />
automaticall inherits its size<br />
*/<br />
&lt;widget name = 'A.Sample.Button'<br />
type = 'SmallButton'<br />
/&gt;<br />
<br />
...<br />
&lt;/layout&gt;<br />
&lt;/dialog&gt;</pre><br />
Because of this, there are no unique identifiers for Widget names. You may give them any alias (since these aliases are only queried by your own layout definition, inside the parser). However, for added customization, the Theme Renderer will also poll a few unique Global Widget names for their layout information:<br />
<br />
* <tt>ListWidget</tt>: Optionally loads its padding information.<br />
* <tt>PopUpWidget</tt>: Optionally loads its padding information.<br />
* <tt>EditTextWidget</tt>: Optionally loads its padding information.<br />
* <tt>Console</tt>: Optionally loads its padding information.<br />
* <tt>TabWidget.Tab</tt>: Loads size and padding information.<br />
* <tt>TabWidget.NavButton</tt>: Loads size and padding information.<br />
These values, as stated, are just for added customization; perfectly working padding defaults are built in the engine, hence they aren't required by the parser. In the case of the <tt>TabWidget</tt> sizes, their builtin default values aren't assured to work on all resolutions: Double check them and define them yourself if required.<br />
<br />
===== Properties =====<br />
<br />
* <tt>name [string]</tt>: Identifier for the widget.<br />
* <tt>size [int, int]</tt>: Width and height of the widget. You may use previously declared <tt>def</tt>s or builtin constants instead of integers.<br />
* <tt>padding [int, int, int, int]</tt>: Pixel padding for Left, Right, Top and Bottom sides, respectively.<br />
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.<br />
<br />
-----<br />
<br />
==== <tt>&lt;dialog&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;layout_info&gt;</tt><br /><br />
Children: <tt>&lt;layout&gt;</tt><br /><br />
Properties: <tt>name</tt> (''required''), <tt>overlays</tt> (''required''), <tt>shading</tt>, <tt>enabled</tt>, <tt>inset</tt>, <tt>resolution</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;dialog name = 'Launcher' overlays = 'screen'&gt;<br />
...<br />
&lt;/dialog&gt;<br />
<br />
&lt;dialog name = 'GameOptions_Graphics' overlays = 'Dialog.GlobalOptions.TabWidget'&gt;<br />
...<br />
&lt;/dialog&gt;</pre><br />
===== Description =====<br />
<br />
Dialog keys are the core of layout definitions; a <tt>dialog</tt> key is required for each dialog shown ingame, and they are distinguished by using the <tt>name</tt> property as an unique identifier.<br />
<br />
Inside of a <tt>dialog</tt> key, the actual layout of the dialog is defined by the use of <tt>layout</tt>, <tt>space</tt> and <tt>widget</tt> subkeys; see the sample definition of a GUI layout section.<br />
<br />
Note however that the first key inside a <tt>dialog</tt> must always be a <tt>layout</tt> -you cannot add widgets before defining its positioning layout.<br />
<br />
===== List of GUI Dialogs =====<br />
<br />
These are all the core dialogs of the GUI which must be implemented in order for the parsing to be successful. Remember that in order to properly define the layout of a dialog, one must add its <tt>dialog</tt> key for the given dialog ''and'' inside of it, all the dialog's own widgets must be defined.<br />
<br />
* <tt>Launcher</tt>: Global launcher menu (main dialog of the GUI).<br />
* <tt>Browser</tt>: File browser, used for add game menus, theme selections, etc.<br />
* <tt>GlobalOptions</tt>: Global options dialog.<br />
* <tt>GlobalOptions_Graphics</tt>: Graphics section of the Global Options dialog.<br />
* <tt>GlobalOptions_Audio</tt>: Audio section of the Global Options dialog.<br />
* <tt>GlobalOptions_Volume</tt>: Volume section of the Global Options dialog.<br />
* <tt>GlobalOptions_MIDI</tt>: MIDI section of the Global Options dialog.<br />
* <tt>GlobalOptions_Paths</tt>: Paths section of the Global Options dialog.<br />
* <tt>GlobalOptions_Misc</tt>: Last section of the Global Options dialog (contains theme loading, etc).<br />
* <tt>GameOptions</tt>: Game options menu (edits the options of a game).<br />
* <tt>GameOptions_Graphics</tt>: Graphics section of the Game Options dialog.<br />
* <tt>GameOptions_Audio</tt>: Audio section of the Game Options dialog.<br />
* <tt>GameOptions_Volume</tt>: Volume section of the Game Options dialog.<br />
* <tt>GameOptions_MIDI</tt>: MIDI section of the Game Options dialog.<br />
* <tt>GameOptions_Game</tt>: Actual game settings section of the Game Options dialog.<br />
* <tt>GameOptions_Paths</tt>: Paths section of the Game Options dialog.<br /><br />
<br />
* <tt>ScummMain</tt>: Main ingame menu for SCUMM based games.<br />
* <tt>ScummConfig</tt>: Options menu for SCUMM based games.<br />
* <tt>ScummSaveLoad</tt>: Save/Load menu for SCUMM based games.<br />
* <tt>ScummHelp</tt>: Help menu for SCUMM based games.<br />
===== Properties =====<br />
<br />
* <tt>name [string]</tt>: Unique name identifying the Dialog (from the above list).<br />
* <tt>overlays [string]</tt>: Position of the dialog on screen. Possible values:<br />
** <tt>screen</tt>: Dialog fills the whole screen.<br />
** <tt>screen_center</tt>: Dialog is centered in the middle of the screen.<br />
** ''Local Widget Identifier'': Dialog occupies the same space than the given Widget of another dialog. See example.<br />
* <tt>shading [string]</tt>: Sets whether all other backgrounds dialog should receive special shading when opening this dialog. Possible values:<br />
** <tt>none</tt>: No special shading.<br />
** <tt>luminance</tt>: Background dialogs are drawn in black &amp; white.<br />
** <tt>dim</tt>: Background dialogs are darkened slightly.<br />
* <tt>enabled [bool]</tt>: Sets whether this dialog is enabled. Defaults always to true. May be used to disable dialogs on certain resolutions.<br />
* <tt>inset [int]</tt>: Sets the inset value for Screen and Dialog overlays (the amount by which the new dialog is contracted).<br />
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.<br />
<br />
-----<br />
<br />
==== <tt>&lt;layout&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;dialog&gt;</tt>, <tt>&lt;layout&gt;</tt><br /><br />
Children: <tt>&lt;import&gt;</tt>, <tt>&lt;widget&gt;</tt>, <tt>&lt;space&gt;</tt>, <tt>&lt;layout&gt;</tt><br /><br />
Properties: <tt>type</tt> (''required''), <tt>center</tt>, <tt>direction</tt>, <tt>padding</tt>, <tt>spacing</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;layout type = 'vertical' center = 'true' padding = '23, 23, 8, 23'&gt;<br />
...<br />
&lt;/layout&gt;</pre><br />
===== Description =====<br />
<br />
Layout keys are the basic containers for the GUI widgets. All widgets on a dialog must be contained inside a Layout, which can be of 2 types:<br />
<br />
* Vertical Layout: Widgets inside the layout will be placed vertically, from top to bottom.<br />
* Horizontal Layout: Widgets inside the layout will be placed horizontally, from left to right.<br />
Note that you can also nest other <tt>layout</tt> keys inside a <tt>layout</tt> key to design complex GUI dialogs. You can see a detailed system on how does the Layout system work on the Example Theme Layout Definition section.<br />
<br />
===== Properties =====<br />
<br />
* <tt>type [string]</tt>: Sets whether the layout is <tt>vertical</tt> or <tt>horizontal</tt>.<br />
* <tt>center [bool]</tt>: Sets whether children widgets inside this layout will be automatically centered.<br />
* <tt>direction [string]</tt>: Sets the positioning direction of the children widgets:<br />
** <tt>right2left</tt>: Children widgets will be placed starting on the right, as they are parsed.<br />
** <tt>bottom2top</tt>: Children widgets will be placed starting on the bottom, as they are parsed.<br />
* <tt>padding [int, int, int, int]</tt>: Sets the inner padding for the children widgets inside the layout.<br />
* <tt>spacing [int]</tt>: Sets the spacing between two children widgets inside the layout.<br />
<br />
-----<br />
<br />
==== <tt>&lt;import&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;layout&gt;</tt><br /><br />
Children: -<br /><br />
Properties: <tt>layout</tt> (''required'')<br />
<br />
===== Example =====<br />
<br />
<pre>&lt;dialog name = 'GameOptions_Audio' overlays = 'Dialog.GlobalOptions.TabWidget'&gt;<br />
&lt;layout type = 'vertical' padding = '16, 16, 16, 16' spacing = '8'&gt;<br />
&lt;widget name = 'EnableTabCheckbox' type = 'Checkbox' /&gt;<br />
&lt;import layout = 'Dialog.GlobalOptions_Audio' /&gt;<br />
&lt;/layout&gt;<br />
&lt;/dialog&gt;</pre><br />
===== Description =====<br />
<br />
This powerful key allows to ''import'' (insert) the layout of a previously defined Dialog inside another layout, keeping all its properties. As you can see on the example, this comes specially in handy for the Game Options menus, since they are almost identical to the Global Options menus, except for the global ''Disable'' checkbox on top of the dialog.<br />
<br />
Note that imported Layouts work as any other child Layout or Widget: They are placed accordingly inside the current Layout, taking into account padding and spacing, and can be followed by other child widgets or other layouts, independently of their complexity.<br />
<br />
===== Properties =====<br />
<br />
* <tt>layout [string]</tt>: Identifier of a previously defined Dialog, whose layout will be imported.<br />
<br />
-----<br />
<br />
==== <tt>&lt;space&gt;</tt> ====<br />
<br />
Parent: <tt>&lt;layout&gt;</tt><br /><br />
Children: -<br /><br />
Properties: <tt>size</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;widget name = 'StartButton' type = 'Button'/&gt;<br />
&lt;space size = '16' /&gt;<br />
&lt;widget name = 'AddGameButton' type = 'Button' /&gt;</pre><br />
===== Description =====<br />
<br />
The <tt>space</tt> key works like any other children widget, but appears obviously as a blank space. They are used when designing layouts, to separate groups of widgets.<br />
<br />
Spaces don't have width or height; they have a single <tt>size</tt> property: If the <tt>space</tt> is found inside a vertical layout, it will separate the two widgets that surround it by the given value, and same thing applies for horizontal layouts.<br />
<br />
Space keys may be optionally left without a <tt>size</tt> property: The space will automatically expand itself to fill all the remaining space inside the layout. This may be used to align widgets on the further side of a layout.<br />
<br />
<pre>&lt;layout type = 'horizontal' ...&gt;<br />
/** Add a button on the left */<br />
&lt;widget name = 'Button1' type = 'Button'/&gt;<br />
<br />
/** The space without size value will expand to fill all the layout */<br />
&lt;space/&gt;<br />
<br />
/** Add another button: */<br />
&lt;widget name = 'Button2' type = 'Button'/&gt;<br />
/** Since the space had filled the layout, this new button shrinks the<br />
space by the button's width; hence Button2 is now aligned to the right */<br />
&lt;/layout&gt;</pre><br />
===== Properties =====<br />
<br />
* <tt>size [int]</tt>: Size of the space.<br />
<br />
-----<br />
<br />
==== <tt>&lt;widget&gt;</tt> (local widget definition) ====<br />
<br />
Parent: <tt>&lt;layout&gt;</tt><br /><br />
Children: -<br /><br />
Properties: <tt>name</tt> (''required''), <tt>width</tt>, <tt>height</tt>, <tt>type</tt>, <tt>enabled</tt><br />
<br />
===== Example =====<br />
<br />
<pre>&lt;widget name = 'AddGameButton' <br />
width = '95'<br />
height = 'Globals.Button.Height' <br />
/&gt;<br />
&lt;widget name = 'AboutButton' <br />
type = 'Button' <br />
/&gt;</pre><br />
===== Description =====<br />
<br />
If both the <tt>width</tt> and <tt>height</tt> properties are absent, and if the <tt>type</tt> property is lacking too, or the given type doesn't define size properties, the Layout engine will automatically expand the widget to fill as much space as it has available inside its parent layout.<br />
<br />
If only one of the properties is missing, the Layout engine will expand the widget in that direction. E.g. if a widget has a specific width but no height, the widget will grow vertically to occupy as much space as possible while keeping the fixed width that has been given.<br />
<br />
===== GUI Widget Distribution =====<br />
<br />
This is a list of all the Widget definitions which are expected by the Theme engine, inside each of the Dialogs of the GUI:<br />
<br />
* <tt>Dialog.Launcher</tt>:<br />
** <tt>Dialog.Launcher.Version</tt><br />
** <tt>Dialog.Launcher.Logo</tt><br />
** <tt>Dialog.Launcher.GameList</tt><br />
** <tt>Dialog.Launcher.StartButton</tt><br />
** <tt>Dialog.Launcher.AddGameButton</tt><br />
** <tt>Dialog.Launcher.EditGameButton</tt><br />
** <tt>Dialog.Launcher.RemoveGameButton</tt><br />
** <tt>Dialog.Launcher.OptionsButton</tt><br />
** <tt>Dialog.Launcher.AboutButton</tt><br />
** <tt>Dialog.Launcher.QuitButton</tt><br />
* <tt>Dialog.Browser</tt>:<br />
** <tt>Dialog.Browser.Choose</tt><br />
** <tt>Dialog.Browser.Cancel</tt><br />
** <tt>Dialog.Browser.Up</tt><br />
** <tt>Dialog.Browser.List</tt><br />
** <tt>Dialog.Browser.Path</tt><br />
** <tt>Dialog.Browser.Headline</tt><br />
* <tt>Dialog.GlobalOptions</tt>:<br />
** <tt>Dialog.GlobalOptions.Ok</tt><br />
** <tt>Dialog.GlobalOptions.Cancel</tt><br />
** <tt>Dialog.GlobalOptions.TabWidget</tt><br />
* <tt>Dialog.GlobalOptions_Graphics</tt>:<br />
** <tt>Dialog.GlobalOptions_Graphics.grModePopup</tt><br />
** <tt>Dialog.GlobalOptions_Graphics.grRenderPopup</tt><br />
** <tt>Dialog.GlobalOptions_Graphics.grAspectCheckbox</tt><br />
** <tt>Dialog.GlobalOptions_Graphics.grFullScreenCheckbox</tt><br />
* <tt>Dialog.GlobalOptions_Audio</tt>:<tt>-</tt>Dialog.GlobalOptions_Audio.auMidiPopup<tt>-</tt>Dialog.GlobalOptions_Audio.auSampleRatePopup<tt>-</tt>Dialog.GlobalOptions_Audio.subToggleDesc<tt>-</tt>Dialog.GlobalOptions_Audio.subToggleButton<tt>-</tt>Dialog.GlobalOptions_Audio.subSubtitleSpeedSlider<tt>-</tt>Dialog.GlobalOptions_Audio.subSubtitleSpeedDesc<tt>-</tt>Dialog.GlobalOptions_Audio.subSubtitleSpeedLabel`<br />
* <tt>Dialog.GlobalOptions_Volume</tt>:<br />
** <tt>Dialog.GlobalOptions_Volume.vcMusicText</tt><br />
** <tt>Dialog.GlobalOptions_Volume.vcMusicSlider</tt><br />
** <tt>Dialog.GlobalOptions_Volume.vcMusicLabel</tt><br />
** <tt>Dialog.GlobalOptions_Volume.vcSfxText</tt><br />
** <tt>Dialog.GlobalOptions_Volume.vcSfxSlider</tt><br />
** <tt>Dialog.GlobalOptions_Volume.vcSfxLabel</tt><br />
** <tt>Dialog.GlobalOptions_Volume.vcSpeechText</tt><br />
** <tt>Dialog.GlobalOptions_Volume.vcSpeechLabel</tt><br />
** <tt>Dialog.GlobalOptions_Volume.vcSpeechSlider</tt><br />
* <tt>Dialog.GlobalOptions_MIDI</tt>:<br />
** <tt>Dialog.GlobalOptions_MIDI.mcFontButton</tt><br />
** <tt>Dialog.GlobalOptions_MIDI.mcFontClearButton</tt><br />
** <tt>Dialog.GlobalOptions_MIDI.mcFontPath</tt><br />
** <tt>Dialog.GlobalOptions_MIDI.mcMixedCheckbox</tt><br />
** <tt>Dialog.GlobalOptions_MIDI.mcMt32Checkbox</tt><br />
** <tt>Dialog.GlobalOptions_MIDI.mcGSCheckbox</tt><br />
** <tt>Dialog.GlobalOptions_MIDI.mcMidiGainText</tt><br />
** <tt>Dialog.GlobalOptions_MIDI.mcMidiGainSlider</tt><br />
** <tt>Dialog.GlobalOptions_MIDI.mcMidiGainLabel</tt><br />
* <tt>Dialog.GlobalOptions_Paths</tt>:<br />
** <tt>Dialog.GlobalOptions_Paths.SaveButton</tt><br />
** <tt>Dialog.GlobalOptions_Paths.SavePath</tt><br />
** <tt>Dialog.GlobalOptions_Paths.ThemeButton</tt><br />
** <tt>Dialog.GlobalOptions_Paths.ThemePath</tt><br />
** <tt>Dialog.GlobalOptions_Paths.ExtraButton</tt><br />
** <tt>Dialog.GlobalOptions_Paths.ExtraPath</tt><br />
* <tt>Dialog.GlobalOptions_Misc</tt>:<br />
** <tt>Dialog.GlobalOptions_Misc.ThemeButton</tt><br />
** <tt>Dialog.GlobalOptions_Misc.CurTheme</tt><br />
** <tt>Dialog.GlobalOptions_Misc.AutosavePeriod</tt><br />
* <tt>Dialog.GameOptions</tt>:<br />
** <tt>Dialog.GameOptions.Ok</tt><br />
** <tt>Dialog.GameOptions.Cancel</tt><br />
** <tt>Dialog.GameOptions.TabWidget</tt><br />
* <tt>Dialog.GameOptions_Graphics</tt>:<br />
** <tt>Dialog.GameOptions_Graphics.EnableTabCheckbox</tt><br />
** ''All widgets from'' <tt>Dialog.GlobalOptions_Graphics</tt><br />
* <tt>Dialog.GameOptions_Audio</tt>:<br />
** <tt>Dialog.GameOptions_Graphics.EnableTabCheckbox</tt><br />
** ''All widgets from'' <tt>Dialog.GlobalOptions_Audio</tt><br />
* <tt>Dialog.GameOptions_Volume</tt>:<br />
** <tt>Dialog.GameOptions_Graphics.EnableTabCheckbox</tt><br />
** ''All widgets from'' <tt>Dialog.GlobalOptions_Volume</tt><br />
* <tt>Dialog.GameOptions_MIDI</tt>:<br />
** <tt>Dialog.GameOptions_Graphics.EnableTabCheckbox</tt><br />
** ''All widgets from'' <tt>Dialog.GlobalOptions_MIDI</tt><br />
* <tt>Dialog.GameOptions_Game</tt>:<br />
** <tt>Dialog.GameOptions_Game.Id</tt><br />
** <tt>Dialog.GameOptions_Game.Domain</tt><br />
** <tt>Dialog.GameOptions_Game.Name</tt><br />
** <tt>Dialog.GameOptions_Game.Desc</tt><br />
** <tt>Dialog.GameOptions_Game.Lang</tt><br />
** <tt>Dialog.GameOptions_Game.Platform</tt><br />
* <tt>Dialog.GameOptions_Paths</tt>:<br />
** <tt>Dialog.GameOptions_Paths.Savepath</tt><br />
** <tt>Dialog.GameOptions_Paths.SavepathText</tt><br />
** <tt>Dialog.GameOptions_Paths.Extrapath</tt><br />
** <tt>Dialog.GameOptions_Paths.ExtrapathText</tt><br />
** <tt>Dialog.GameOptions_Paths.Gamepath</tt><br />
** <tt>Dialog.GameOptions_Paths.GamepathText</tt><br />
* <tt>Dialog.ScummMain</tt>:<br />
** <tt>Dialog.ScummMain.Resume</tt><br />
** <tt>Dialog.ScummMain.Save</tt><br />
** <tt>Dialog.ScummMain.Options</tt><br />
** <tt>Dialog.ScummMain.Help</tt><br />
** <tt>Dialog.ScummMain.About</tt><br />
** <tt>Dialog.ScummMain.Quit</tt><br />
* <tt>Dialog.ScummConfig</tt>:<br />
** <tt>Dialog.ScummConfig.Cancel</tt><br />
** <tt>Dialog.ScummConfig.Ok</tt><br />
** <tt>Dialog.ScummConfig.subSubtitleSpeedDesc</tt><br />
** <tt>Dialog.ScummConfig.subSubtitleSpeedSlider</tt><br />
** <tt>Dialog.ScummConfig.subSubtitleSpeedLabel</tt><br />
** <tt>Dialog.ScummConfig.subToggleDesc</tt><br />
** <tt>Dialog.ScummConfig.subToggleButton</tt><br />
** <tt>Dialog.ScummConfig.vcSpeechText</tt><br />
** <tt>Dialog.ScummConfig.vcSpeechSlider</tt><br />
** <tt>Dialog.ScummConfig.vcSpeechLabel</tt><br />
** <tt>Dialog.ScummConfig.vcSfxText</tt><br />
** <tt>Dialog.ScummConfig.vcSfxSlider</tt><br />
** <tt>Dialog.ScummConfig.vcSfxLabel</tt><br />
** <tt>Dialog.ScummConfig.vcMusicText</tt><br />
** <tt>Dialog.ScummConfig.vcMusicSlider</tt><br />
** <tt>Dialog.ScummConfig.vcMusicLabel</tt><br />
* <tt>Dialog.ScummSaveLoad</tt>:<br />
** <tt>Dialog.ScummSaveLoad.Choose</tt><br />
** <tt>Dialog.ScummSaveLoad.Cancel</tt><br />
** <tt>Dialog.ScummSaveLoad.Thumbnail</tt><br />
** <tt>Dialog.ScummSaveLoad.List</tt><br />
* <tt>Dialog.ScummHelp</tt>:<br />
** <tt>Dialog.ScummHelp.Prev</tt><br />
** <tt>Dialog.ScummHelp.Next</tt><br />
** <tt>Dialog.ScummHelp.Close</tt><br />
** <tt>Dialog.ScummHelp.HelpText</tt><br />
** <tt>Dialog.ScummHelp.Title</tt><br />
Note that this list uses the full, internal names of each Widget, for reference reasons. When defining the widget called <tt>Dialog.ScummConfig.vcSfxLabel</tt>, the value of the <tt>name</tt> key must be <tt>vcSfxLabel</tt>, but such key must obviously be contained inside the <tt>ScummConfig</tt> dialog.<br />
<br />
===== Properties =====<br />
<br />
* <tt>name [string]</tt>: Unique identifier for this widget (as seen on the GUI Widget distribution list).<br />
* <tt>width [int]</tt>: Width of the widget.<br />
* <tt>height [int]</tt>: Height of the widget.<br />
* <tt>type [string]</tt>: Global Widget Definition from which this widget will inherit its properties.<br />
* <tt>enabled [bool]</tt>: Sets whether this widget is enabled. Defaults always to true. May be used to disable widgets on certain resolutions.</div>Tanokuhttps://wiki.scummvm.org/index.php?title=GUI_Themes/Specs&diff=9484GUI Themes/Specs2008-10-15T12:07:11Z<p>Tanoku: </p>
<hr />
<div>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.<br />
<br />
=== Theme Packages ===<br />
<br />
A theme file in the new version of the ScummVM GUI is a compressed ZIP file which contains all the required information<br />
<br />
* One or more STX (ScummVM Theme XML) files.<br />
* Any external Bitmap fonts.<br />
* Any external Bitmap images.<br />
* A <tt>THEMERC</tt> file.<br />
===== The STX Files =====<br />
<br />
STX (ScummVM Theme XML) is the new format for theme descriptions on the Graphical User Interface of ScummVM.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===== The external resources =====<br />
<br />
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.<br />
<br />
Packaged resources will then be accessible from the STX syntax (check the <tt>font</tt> and <tt>bitmap</tt> keys in the STX documentation).<br />
<br />
===== The <tt>THEMERC</tt> file =====<br />
<br />
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:<br />
<br />
<pre>[SCUMMVM_THEME_V23:Name of the ScummVM Theme:Name of the Author]</pre><br />
The <tt>SCUMMVM_THEME_V23</tt> is just a simple check to make sure that the theme was developed to be used on the proper version of the GUI. 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.<br />
<br />
===== Building theme packages =====<br />
<br />
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 SVN repository.<br />
<br />
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.<br />
<br />
This Python script is totally standalone and doesn't require external ZIP utilities, only a standard Python distribution.<br />
<br />
===== Building the built-in theme =====<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
By default, the <tt>ScummVM Classic Theme</tt> is the built-in theme.<br />
<br />
=== Drawing specifications ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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/ThemeRenderer.h&quot;</tt> file, in the <tt>DrawData</tt> enumeration inside the <tt>ThemeRenderer</tt> class.<br />
<br />
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.<br />
<br />
=== Theme Layout specifications ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== Syntax overview ===<br />
<br />
A full STX theme description is composed of:<br />
<br />
* A root <tt>&lt;render_info&gt;</tt> key, containing all the information regarding the looks of the theme.<br />
** An optional <tt>&lt;palette&gt;</tt> key, containing color definitions.<br />
** An optional <tt>&lt;bitmaps&gt;</tt> key, containing all the loaded bitmaps which will be used on the GUI.<br />
** A <tt>&lt;fonts&gt;</tt> key, specifying the fonts used to draw text on the GUI.<br />
** A <tt>&lt;drawdata&gt;</tt> key for ''each'' DrawData identifier of the Theme Engine, specifying how is each individual widget drawn.<br />
* A root &lt;layout_info&gt; key, containing all the information regarding the layout of the theme.<br />
** A <tt>&lt;globals&gt;</tt> key, containing the global variables to use on the layout design.<br />
** 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.<br />
Here's a schematic overview of the layout of keys in a STX file:<br />
<br />
<pre>&lt;render_info&gt;<br />
&lt;palette&gt;<br />
...<br />
&lt;/palette&gt;<br />
<br />
&lt;bitmaps&gt;<br />
...<br />
&lt;/bitmaps&gt;<br />
<br />
&lt;fonts&gt;<br />
...<br />
&lt;/fonts&gt;<br />
<br />
&lt;drawdata&gt;<br />
...<br />
&lt;/drawdata&gt;<br />
<br />
...<br />
&lt;/render_info&gt;<br />
<br />
&lt;layout_info&gt;<br />
&lt;globals&gt;<br />
...<br />
&lt;/globals&gt;<br />
<br />
&lt;dialog&gt;<br />
...<br />
&lt;/dialog&gt;<br />
<br />
...<br />
&lt;/layout_info&gt;</pre><br />
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 Subversion repository, while consulting the following documentation for each specific key:<br />
<br />
=== Detailed STX documentation ===<br />
<br />
The full documentation of the XML syntax used in the new Graphical User Interface can be found on its own [[GUI Themes/STX|wiki page]].<br />
<br />
=== Resolution-dependent keys and layouts ===<br />
<br />
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.<br />
<br />
The resolution property must contain one or more resolutions, comma separated, for which the given key is supposed to be loaded. Resolutions preceded by the minus sign will block the key from being loaded in that resolution, while resolutions without any modifiers will force the theme to be loaded in all resolutions. Here are a few examples:<br />
<br />
<pre>/* Key will be loaded in all resolutions */<br />
&lt;render_info&gt;<br />
<br />
/* Key will ONLY be loaded in resolutions with 320 width */<br />
&lt;render_info resolution = '320xY'&gt;<br />
<br />
/* Key will ONLY be loaded in resolutions with 240 height and in the 320x200 resolution */<br />
&lt;render_info resolution = 'Xx240, 320x200'&gt;<br />
<br />
/* Key will be loaded on ALL resolutions except for 320x200 */<br />
&lt;render_info resolution = '-320x200'&gt;<br />
<br />
/* Key will ONLY be loaded in resolutions with 320 width; the -240xY is superfluous. */<br />
&lt;render_info resolution = '320xY, -240xY'&gt;</pre><br />
Note that the Theme Parser does not assert on repeated keys or values, it just replaces them accordingly. For instance, the following variable definition:<br />
<br />
<pre>&lt;def var = 'TestVar' value = '100'/&gt;<br />
&lt;def var = 'TestVar' value = '200' resolution = '320xY'/&gt;</pre><br />
won't fail to parse. What will happen when loading the theme using a resolution with 320 width 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 ''without'' a with of 320, the <tt>ThemeVal</tt> will be assigned the <tt>100</tt> value and the second key will be plain ignored.<br />
<br />
The &quot;proper&quot; way to do that multi-resolution assignment would obviously be:<br />
<br />
<pre>&lt;def var = 'TestVar' value = '100' resolution = '-320xY'/&gt;<br />
&lt;def var = 'TestVar' value = '200' resolution = '320xY'/&gt;</pre><br />
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>-320xY</tt> resolution tags, and instead write a layout that works on all resolutions and overwrite parts of it with the '320xY' tag.</div>Tanokuhttps://wiki.scummvm.org/index.php?title=GUI_Themes&diff=9483GUI Themes2008-10-15T11:34:58Z<p>Tanoku: </p>
<hr />
<div>= Warning =<br />
<br />
Since the merge of the new Graphical User Interface into the code trunk, the following themes are no longed supported/working in the current Subversion build of ScummVM. Because of the massive overhaul on the theme description files, they will not work again unless their authors decide to port them to the new format.<br />
<br />
= Downloads =<br />
See [[GUI Themes/Specs|here]] for theme specifications and [[GUI Themes/TODO|here]] for the TODO page.<br />
<br />
{|border="1" cellpadding="2" width=100%<br />
|- style="background:#efefef"<br />
|Theme||Author<br />
|-<br />
|[http://wiki.scummvm.org/images/a/a0/Dark.zip Dark-Theme]||[[User:LordHoto|LordHoto]]<br />
|-<br />
|[http://wiki.scummvm.org/images/c/c7/Modern_ice.zip Ice-Theme]||WNivek<br />
|-<br />
|[http://wiki.scummvm.org/images/c/c3/JavacatVM.zip JavacatVM Theme]||[[User:Clone2727|Clone2727]]<br />
|-<br />
|[http://wiki.scummvm.org/images/9/98/Modern_blue.zip Modern Theme (Blue)]||[[User:Md5|Md5]]<br />
|}<br />
<br />
The themes have their ini files in the zip archives, so they can just be placed in your theme folder. Note that the files may not work after renaming, so keep the filename. Also note that some of these themes could be outdated, so please wait for the author to update them, if they aren't working.<br />
<br />
= Screenshots =<br />
<br />
{|<br />
|-<br />
|[[image:Modern dark.png|frame|thumb|300px|Modern Dark Theme]]<br />
|}<br />
<br />
{|<br />
|-<br />
|[[image:Modern_ice.png|frame|thumb|300px|Modern Ice Theme]]<br />
|}<br />
<br />
{|<br />
|-<br />
|[[image:JavacatVM.png|frame|thumb|300px|JavacatVM Theme]]<br />
|}<br />
<br />
{|<br />
|-<br />
|[[image:Modern_blue.png|frame|thumb|300px|Modern Blue Theme]]<br />
|}</div>Tanoku