Difference between revisions of "GUI Themes/STX Syntax"

From ScummVM :: Wiki
Jump to navigation Jump to search
(→‎<font>: update "font" configuration documentation)
(Updated the properties of <widget> (local widget definition) and <layout> keys.)
 
(6 intermediate revisions by 3 users not shown)
Line 11: Line 11:
===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<render_info resolution = "320x240">
<render_info resolution = "y>399">
     ...
     ...
</render_info>
</render_info>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 23: Line 23:
===== Properties =====
===== Properties =====


* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.
* <tt>resolution [[x|y][<|>]int]</tt>: Load only on a given resolution. See resolution-dependant keys.


-----
-----
Line 35: Line 35:
===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<palette>
<palette>
     ...
     ...
</palette>
</palette>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 55: Line 55:
===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<color name = 'red'
<color name = 'red'
         rgb = '255, 0, 0'
         rgb = '255, 0, 0'
/>
/>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 82: Line 82:
===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<bitmaps>
<bitmaps>
     ...
     ...
</bitmaps>
</bitmaps>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 103: Line 103:
===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<bitmap filename = 'logo.bmp'/>
<bitmap filename = 'logo.bmp'/>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 116: Line 116:


* <tt>filename [string]</tt>: Path and filename to the bitmap file.
* <tt>filename [string]</tt>: Path and filename to the bitmap file.
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.
* <tt>resolution [[x|y][<|>]int]</tt>: Load only on a given resolution. See resolution-dependant keys.


-----
-----
Line 128: Line 128:
===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<fonts>
<fonts>
     ...
     ...
</fonts>
</fonts>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 149: Line 149:
===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<font  id = 'text_default'
<font  id = 'text_default'
         file = 'default'
         file = 'default'
/>
/>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 173: Line 173:
* <tt>id [string]</tt>: Unique font identifier.
* <tt>id [string]</tt>: Unique font identifier.
* <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).
* <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).
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.
* <tt>resolution [[x|y][<|>]int]</tt>: Load only on a given resolution. See resolution-dependant keys.
 
-----
 
==== <tt>&lt;text_color&gt;</tt> ====
 
Parent: <tt>&lt;fonts&gt;</tt><br />
Children: -<br />
Properties: <tt>id</tt> (''required''), <tt>color</tt> (''required'')
 
===== Example =====
 
<syntaxhighlight lang="xml">
<text_color id = 'color_normal'
            color = 'black'
/>
</syntaxhighlight>
 
===== Description =====
 
The GUI code allows the different draw steps to specify a color to draw the text data in. The user can specify the colors for different (currently predefined) text types via this.
 
===== Required text color identifiers =====
 
Here is a list of the currently available text color types. All need to be defined by the theme configuration file.
 
* <tt>color_normal</tt>: This should be the default color.
* <tt>color_normal_hover</tt>: The default color for hovered widgets.
* <tt>color_normal_disabled</tt>: The default color for disabled widgets.
* <tt>color_normal_inverted</tt>: The default color for inverted text, like used in the ListWidget.
* <tt>color_alternative</tt>: An alternative color, which the widgets might use.
* <tt>color_alternative_hover</tt>: The hovered version of the alternative color.
* <tt>color_alternative_disabled</tt>: The disabled version of the alternative color.
* <tt>color_alternative_inverted</tt>: The inverted version of the alternative color.
* <tt>color_button</tt>: The color to be used in button widgets.
* <tt>color_button_hover</tt>: Hovered version of the button widget text color.
* <tt>color_button_disabled</tt>: Disabled version of the button widget text color.
 
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.
 
The GUI code itself relies only on "color_normal*" and "color_alternative*" to be present. The button color is there to allow different text colors of the button text's, like used in the modern theme of ScummVM.
 
===== Properties =====
 
* <tt>id [string]</tt>: Unique color identifier.
* <tt>color [int, int, int|string]</tt>: Color to draw the text with.


-----
-----
Line 185: Line 230:
===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<defaults fill = 'gradient' fg_color = 'white' bevel_color = '237, 169, 72'/>
<defaults fill = 'gradient' fg_color = 'white' bevel_color = '237, 169, 72'/>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 206: Line 251:
===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<cursor file = 'cursor.bmp' hotspot = '0, 0' scale = '3'/>
<cursor file = 'cursor.bmp' hotspot = '0, 0' scale = '3'/>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 221: Line 266:
* <tt>hotspot [int, int]</tt>: Coordinates for the point in the bitmap which will be used for click calculations.
* <tt>hotspot [int, int]</tt>: Coordinates for the point in the bitmap which will be used for click calculations.
* <tt>scale [int]</tt>: Scale at which this cursor is supposed to be used.
* <tt>scale [int]</tt>: Scale at which this cursor is supposed to be used.
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.
* <tt>resolution [[x|y][<|>]int]</tt>: Load only on a given resolution. See resolution-dependant keys.


-----
-----
Line 233: Line 278:
===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<drawdata id = 'mainmenu_bg' cache = false>
<drawdata id = 'mainmenu_bg' cache = false>
     <drawstep  ...
     <drawstep  ...
     />
     />
</drawdata>
</drawdata>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 272: Line 317:
* <tt>id [string]</tt>: Unique identifier for the drawing asset.
* <tt>id [string]</tt>: Unique identifier for the drawing asset.
* <tt>cache [bool]</tt>: Lets the renderer know that this drawing asset may be cached for performance.
* <tt>cache [bool]</tt>: Lets the renderer know that this drawing asset may be cached for performance.
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.
* <tt>resolution [[x|y][<|>]int]</tt>: Load only on a given resolution. See resolution-dependant keys.


-----
-----
Line 284: Line 329:
===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<drawstep  func = 'roundedsq'
<drawstep  func = 'roundedsq'
             radius = '6'
             radius = '6'
Line 295: Line 340:
             bevel = 1
             bevel = 1
/>
/>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 365: Line 410:
Parent: <tt>&lt;drawdata&gt;</tt><br />
Parent: <tt>&lt;drawdata&gt;</tt><br />
Children: -<br />
Children: -<br />
Properties: <tt>font</tt> (''required''), <tt>vertical_align</tt> (''required''), <tt>horizontal_align</tt> (''required'')
Properties: <tt>font</tt> (''required''), <tt>text_color</tt> (''required''), <tt>vertical_align</tt> (''required''), <tt>horizontal_align</tt> (''required'')


===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<text  font = 'text_button'
<text  font = 'text_button'
        text_color = 'color_button'
         vertical_align = 'center'
         vertical_align = 'center'
         horizontal_align = 'center'
         horizontal_align = 'center'
/>
/>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 396: Line 442:


* <tt>font [string]</tt>: Font identifier from a previously created <tt>font</tt> key. This font will be used to draw the text.
* <tt>font [string]</tt>: Font identifier from a previously created <tt>font</tt> key. This font will be used to draw the text.
* <tt>text_color [string]</tt>: Color to use. This entry has to match a identifier defined via the <tt>text_color</tt> key.
* <tt>vertical_alignment [string]</tt>: Vertical (Y axis) alignment of the text. Possible values:
* <tt>vertical_alignment [string]</tt>: Vertical (Y axis) alignment of the text. Possible values:
** <tt>top</tt>
** <tt>top</tt>
Line 415: Line 462:
===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<layout_info resolution = '320xY'>
<layout_info resolution = 'y>399'>
     ...
     ...
</layout_info>
</layout_info>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 427: Line 474:
===== Properties =====
===== Properties =====


* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.
* <tt>resolution [[x|y][<|>]int]</tt>: Load only on a given resolution. See resolution-dependant keys.


-----
-----
Line 439: Line 486:
===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<globals>
<globals>
     ...
     ...
</globals>
</globals>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 460: Line 507:
===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<def var = 'WidgetSize' value = 'kBigWidgetSize' />
<def var = 'WidgetSize' value = 'kBigWidgetSize' />
<def resolution = '320xY' var = 'WidgetSize' value = 'kNormalWidgetSize' />
<def resolution = 'y>399' var = 'WidgetSize' value = 'kNormalWidgetSize' />
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 499: Line 546:
** kNormalWidgetSize
** kNormalWidgetSize
** kBigWidgetSize
** kBigWidgetSize
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.
* <tt>resolution [[x|y][<|>]int]</tt>: Load only on a given resolution. See resolution-dependant keys.


-----
-----
Line 510: Line 557:
===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<widget name = 'SmallButton'
<widget name = 'SmallButton'
         size = '128, 18'
         size = '128, 18'
/>
/>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 520: Line 567:
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'').
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'').


<syntax type="xml">
<syntaxhighlight lang="xml">
<dialog name = 'SampleDialog' overlays = 'screen'>
<dialog name = 'SampleDialog' overlays = 'screen'>
     <layout type = 'vertical' ...>
     <layout type = 'vertical' ...>
Line 536: Line 583:
     </layout>
     </layout>
</dialog>
</dialog>
</syntax>
</syntaxhighlight>


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:
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:
Line 553: Line 600:
* <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.
* <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.
* <tt>padding [int, int, int, int]</tt>: Pixel padding for Left, Right, Top and Bottom sides, respectively.
* <tt>padding [int, int, int, int]</tt>: Pixel padding for Left, Right, Top and Bottom sides, respectively.
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.
* <tt>resolution [[x|y][<|>]int]</tt>: Load only on a given resolution. See resolution-dependant keys.


-----
-----
Line 565: Line 612:
===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<dialog name = 'Launcher' overlays = 'screen'>
<dialog name = 'Launcher' overlays = 'screen'>
     ...
     ...
Line 573: Line 620:
     ...
     ...
</dialog>
</dialog>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 624: Line 671:
* <tt>enabled [bool]</tt>: Sets whether this dialog is enabled. Defaults always to true. May be used to disable dialogs on certain resolutions.
* <tt>enabled [bool]</tt>: Sets whether this dialog is enabled. Defaults always to true. May be used to disable dialogs on certain resolutions.
* <tt>inset [int]</tt>: Sets the inset value for Screen and Dialog overlays (the amount by which the new dialog is contracted).
* <tt>inset [int]</tt>: Sets the inset value for Screen and Dialog overlays (the amount by which the new dialog is contracted).
* <tt>resolution [int x int]</tt>: Load only on a given resolution. See resolution-dependant keys.
* <tt>resolution [[x|y][<|>]int]</tt>: Load only on a given resolution. See resolution-dependant keys.


-----
-----
Line 632: Line 679:
Parent: <tt>&lt;dialog&gt;</tt>, <tt>&lt;layout&gt;</tt><br />
Parent: <tt>&lt;dialog&gt;</tt>, <tt>&lt;layout&gt;</tt><br />
Children: <tt>&lt;import&gt;</tt>, <tt>&lt;widget&gt;</tt>, <tt>&lt;space&gt;</tt>, <tt>&lt;layout&gt;</tt><br />
Children: <tt>&lt;import&gt;</tt>, <tt>&lt;widget&gt;</tt>, <tt>&lt;space&gt;</tt>, <tt>&lt;layout&gt;</tt><br />
Properties: <tt>type</tt> (''required''), <tt>center</tt>, <tt>direction</tt>, <tt>padding</tt>, <tt>spacing</tt>
Properties: <tt>type</tt> (''required''), <tt>align</tt>, <tt>padding</tt>, <tt>spacing</tt>


===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<layout type = 'vertical' center = 'true' padding = '23, 23, 8, 23'>
<layout type = 'vertical' align = 'center' padding = '23, 23, 8, 23'>
     ...
     ...
</layout>
</layout>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 653: Line 700:


* <tt>type [string]</tt>: Sets whether the layout is <tt>vertical</tt> or <tt>horizontal</tt>.
* <tt>type [string]</tt>: Sets whether the layout is <tt>vertical</tt> or <tt>horizontal</tt>.
* <tt>center [bool]</tt>: Sets whether children widgets inside this layout will be automatically centered.
* <tt>align [string]</tt>: Sets the alignment of the children widgets. Allowed values are <tt>start</tt>, <tt>center</tt>, <tt>end</tt>, and <tt>stretch</tt>. Default is <tt>start</tt>.
* <tt>direction [string]</tt>: Sets the positioning direction of the children widgets:
** <tt>right2left</tt>: Children widgets will be placed starting on the right, as they are parsed.
** <tt>bottom2top</tt>: Children widgets will be placed starting on the bottom, as they are parsed.
* <tt>padding [int, int, int, int]</tt>: Sets the inner padding for the children widgets inside the layout.
* <tt>padding [int, int, int, int]</tt>: Sets the inner padding for the children widgets inside the layout.
* <tt>spacing [int]</tt>: Sets the spacing between two children widgets inside the layout.
* <tt>spacing [int]</tt>: Sets the spacing between two children widgets inside the layout.
Line 670: Line 714:
===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<dialog name = 'GameOptions_Audio' overlays = 'Dialog.GlobalOptions.TabWidget'>
<dialog name = 'GameOptions_Audio' overlays = 'Dialog.GlobalOptions.TabWidget'>
     <layout type = 'vertical' padding = '16, 16, 16, 16' spacing = '8'>
     <layout type = 'vertical' padding = '16, 16, 16, 16' spacing = '8'>
Line 677: Line 721:
     </layout>
     </layout>
</dialog>
</dialog>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 699: Line 743:
===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<widget name = 'StartButton' type = 'Button'/>
<widget name = 'StartButton' type = 'Button'/>
<space size = '16' />
<space size = '16' />
<widget name = 'AddGameButton' type = 'Button' />
<widget name = 'AddGameButton' type = 'Button' />
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 713: Line 757:
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.
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.


<syntax type="xml">
<syntaxhighlight lang="xml">
<layout type = 'horizontal' ...>
<layout type = 'horizontal' ...>
     /** Add a button on the left */
     /** Add a button on the left */
Line 726: Line 770:
         space by the button's width; hence Button2 is now aligned to the right */
         space by the button's width; hence Button2 is now aligned to the right */
</layout>
</layout>
</syntax>
</syntaxhighlight>


===== Properties =====
===== Properties =====
Line 738: Line 782:
Parent: <tt>&lt;layout&gt;</tt><br />
Parent: <tt>&lt;layout&gt;</tt><br />
Children: -<br />
Children: -<br />
Properties: <tt>name</tt> (''required''), <tt>width</tt>, <tt>height</tt>, <tt>type</tt>, <tt>enabled</tt>, <tt>textalign</tt>
Properties: <tt>name</tt> (''required''), <tt>width</tt>, <tt>height</tt>, <tt>type</tt>, <tt>textalign</tt>, <tt>rtl</tt>


===== Example =====
===== Example =====


<syntax type="xml">
<syntaxhighlight lang="xml">
<widget name = 'AddGameButton'  
<widget name = 'AddGameButton'  
         width = '95'
         width = '95'
Line 750: Line 794:
         type = 'Button'  
         type = 'Button'  
/>
/>
</syntax>
</syntaxhighlight>


===== Description =====
===== Description =====
Line 768: Line 812:
* <tt>height [int]</tt>: Height of the widget.
* <tt>height [int]</tt>: Height of the widget.
* <tt>type [string]</tt>: Global Widget Definition from which this widget will inherit its properties.
* <tt>type [string]</tt>: Global Widget Definition from which this widget will inherit its properties.
* <tt>enabled [bool]</tt>: Sets whether this widget is enabled. Defaults always to true. May be used to disable widgets on certain resolutions.
* <tt>textalign [string]</tt>: Sets horizontal alignment of text on this widget. Allowed values are <tt>start</tt>, <tt>end</tt>, <tt>left</tt>, <tt>right</tt> and <tt>center</tt>. <tt>start</tt> and <tt>end</tt> adapt alignment to GUI's RTL or LTR orientation. Default value is <tt>start</tt>.
* <tt>textalign [string]</tt>: Sets horizontal alignment of text on this widget. Allowed values are <tt>left</tt>, <tt>right</tt> and <tt>center</tt>. Default value is <tt>left</tt>.
*<tt>rtl [bool]</tt>: Sets whether this widget respects RTL orientation when GUI is set to use an RTL language. Defaults always to true. May be used to keep widgets in LTR orientation on both RTL and LTR languages.

Latest revision as of 13:40, 22 June 2021

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.

STX Syntax Keys

<render_info>

Parent: root
Children: <palette>, <fonts>, <bitmaps>, <cursor>, <defaults>, <drawdata>
Properties: resolution

Example
<render_info resolution = "y>399">
    ...
</render_info>
Description

The render_info key specifies that all children keys contain information regarding the looks of the theme, i.e. the actual Drawing Specifications.

Properties
  • resolution [[x|y][<|>]int]: Load only on a given resolution. See resolution-dependant keys.

<palette>

Parent: <render_info>
Children: <color>
Properties: -

Example
<palette>
    ...
</palette>
Description

The palette key is a simple wrapper; it contains all the color definitions for the theme.



<color>

Parent: <palette>
Children: - Properties: name (required), rgb (required)

Example
<color name = 'red'
        rgb = '255, 0, 0'
/>
Description

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.

Color aliases are exclusive to the parser engine, they are replaced by their actual RGB values when loaded into the Theme Renderer.

Properties
  • name [string]: Name/alias of the color.
  • rgb [int, int, int]: RGB (red/green/blue) values for the color, comma separated.

<bitmaps>

Parent: <render_info>
Children: <bitmap>
Properties: -

Example
<bitmaps>
    ...
</bitmaps>
Description

The bitmaps key is a simple wrapper; it contains all the bitmap keys for the theme.



<bitmap>

Parent: <bitmaps>
Children: -
Properties: filename (required), resolution

Example
<bitmap filename = 'logo.bmp'/>
Description

A bitmap 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.

Once a bitmap file has been loaded, it may be referenced by its filename in the STX file where required:

Properties
  • filename [string]: Path and filename to the bitmap file.
  • resolution [[x|y][<|>]int]: Load only on a given resolution. See resolution-dependant keys.

<fonts>

Parent: <render_info>
Children: <font>
Properties: -

Example
<fonts>
    ...
</fonts>
Description

The fonts key is a simple wrapper; it contains all the font keys for the theme.



<font>

Parent: <fonts>
Children: -
Properties: id (required), file (required), resolution

Example
<font   id = 'text_default'
        file = 'default'
/>
Description

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.

Required Font identifiers

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.

  • text_default: Core font for the engine, used to draw all the static text and most of the text in widgets.
  • text_button: Text for Button widgets.
  • text_normal: Normal, smaller text (i.e. non bold) used sparsely (editable text widgets, about dialog, etc).

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.

Properties
  • id [string]: Unique font identifier.
  • file [string]: External Font file to load. Use "default" to let the renderer choose the most appropriate default font based on the active resolution (usually an builtin one).
  • resolution [[x|y][<|>]int]: Load only on a given resolution. See resolution-dependant keys.

<text_color>

Parent: <fonts>
Children: -
Properties: id (required), color (required)

Example
<text_color id = 'color_normal'
            color = 'black'
/>
Description

The GUI code allows the different draw steps to specify a color to draw the text data in. The user can specify the colors for different (currently predefined) text types via this.

Required text color identifiers

Here is a list of the currently available text color types. All need to be defined by the theme configuration file.

  • color_normal: This should be the default color.
  • color_normal_hover: The default color for hovered widgets.
  • color_normal_disabled: The default color for disabled widgets.
  • color_normal_inverted: The default color for inverted text, like used in the ListWidget.
  • color_alternative: An alternative color, which the widgets might use.
  • color_alternative_hover: The hovered version of the alternative color.
  • color_alternative_disabled: The disabled version of the alternative color.
  • color_alternative_inverted: The inverted version of the alternative color.
  • color_button: The color to be used in button widgets.
  • color_button_hover: Hovered version of the button widget text color.
  • color_button_disabled: Disabled version of the button widget text color.

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.

The GUI code itself relies only on "color_normal*" and "color_alternative*" to be present. The button color is there to allow different text colors of the button text's, like used in the modern theme of ScummVM.

Properties
  • id [string]: Unique color identifier.
  • color [int, int, int|string]: Color to draw the text with.

<defaults>

Parent: <render_info>, <drawdata>
Children: -
Properties: See DrawStep properties.

Example
<defaults fill = 'gradient' fg_color = 'white' bevel_color = '237, 169, 72'/>
Description

The defaults 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.

If found on the <render_info> 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 <drawdata> key to temporarily override the global defaults for all the DrawSteps inside that DrawData key.



<cursor>

Parent: <render_info>
Children: -
Properties: file (required), hotspot (required), scale (required), resolution

Example
<cursor file = 'cursor.bmp' hotspot = '0, 0' scale = '3'/>
Description

If the parser finds a cursor key in the render_info scope, it will try to load a custom bitmap cursor to use in the Graphical User Interface. If no cursor key is found, the GUI will default to the built-in cross cursor.

Because of bitmap scaling issues, make sure to specify several different cursor definitions, one for each significant resolution.

Properties
  • file [string]: Filename for the bitmap with the cursor shape (must have been loaded previously).
  • hotspot [int, int]: Coordinates for the point in the bitmap which will be used for click calculations.
  • scale [int]: Scale at which this cursor is supposed to be used.
  • resolution [[x|y][<|>]int]: Load only on a given resolution. See resolution-dependant keys.

<drawdata>

Parent: <render_info>
Children: <defaults>, <drawstep>, <text>
Properties: id (required), cache, resolution

Example
<drawdata id = 'mainmenu_bg' cache = false>
    <drawstep   ...
    />
</drawdata>
Description

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.

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:

Required DrawData identifiers
  • mainmenu_bg, special_bg, plain_bg, default_bg: Backgrounds for the different dialogs.
  • text_selection: Background for selected (inverted) text.
  • widget_default, widget_small: Default backgrounds for widgets.
  • widget_textedit: Background for the Text Edit widget.
  • widget_slider: Background for the (empty) slider widget.
  • button_idle, button_hover, button_disabled: States for the Button widget.
  • slider_full, slider_hover, slider_disabled: States for the Slider widget.
  • checkbox_default, checkbox_disabled, checkbox_selected: States for the Checkbox widget.
  • tab_active, tab_inactive: States for the selected/deselected tab.
  • tab_background: Background behind the tab list.
  • scrollbar_base: Background for the scrollbar widget.
  • scrollbar_button_idle, scrollbar_button_hover: States for the scrollbar up/down buttons.
  • scrollbar_handle_idle, scrollbar_handle_hover: States for the scrolling handle of the scrollbar.
  • popup_idle, popup_hover: States for the popup selection widget.
  • caret: Text edition caret.
  • separator: Basic horizontal separator.

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.

Also, note that each DrawData key must contain at least a child DrawStep, since it actually defines the graphic drawing for the widget/state.

Properties
  • id [string]: Unique identifier for the drawing asset.
  • cache [bool]: Lets the renderer know that this drawing asset may be cached for performance.
  • resolution [[x|y][<|>]int]: Load only on a given resolution. See resolution-dependant keys.

<drawstep>

Parent: <drawdata>
Children: -
Properties: func (required), ...

Example
<drawstep   func = 'roundedsq'
            radius = '6'
            stroke = 1
            fill = 'gradient'
            shadow = 0
            fg_color = 'shadowcolor'
            gradient_start = 'brightred'
            gradient_end = 'darkred'
            bevel = 1
/>
Description

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.

Each drawdata 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.

The most important property of a DrawStep is the func (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.

Take a look at the full list of properties to see which properties are required by each function.

Required properties
  • func [string]: Specifies the drawing function used on the step from one of the following:
    • circle: Draws a primitive circle.
    • square: Draws a primitive square/rectangle.
    • roundedsq: Draws a rounded square/rectangle (that is, a rectangle with rounded corners).
    • bevelsq: 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.
    • line: Draws a straight line.
    • triangle: 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.
    • fill: 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.
    • bitmap: Ignores all drawing information and blits the given Bitmap into the surface.
Common (optional) properties
  • fill [string]: Specifies the fill mode for the drawn shape. Possible values:
    • none: Disables filling so only the stroke is shown.
    • foreground (default): Fills the whole shape with the active foreground color.
    • background: Fills the whole shape with the active background color.
    • gradient: Fills the whole shape with the active gradient.
  • gradient_start [int, int, int|string]: Sets the gradient start color; has no default value.
  • gradient_end [int, int, int|string]: Sets the gradient end color; has no default value.
  • fg_color [int, int, int|string]: Sets the foreground fill color; has no default value.
  • bg_color [int, int, int|string]: Sets the background fill color; has no default value.
  • stroke [int] (default = 0): 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.
  • shadow [int] (default = 0): 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.
  • factor [int] (default = 1): 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.
  • bevel [int] (default = 0): 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.
  • width [int|string] (default = auto): Width for the shape. Defaults to auto (automatically fill the whole drawing surface). Width may be specified as a pixel value or with the height keyword, which will give the shape the same width as its height.
  • height [int|string] (default = auto): Height for the shape. Defaults to auto (automatically fill the whole drawing surface). Height may be specified as a pixel value or with the width keyword, which will give the shape the same height as its width.
  • xpos [int|string] (required when width 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:
    • center
    • left
    • right
  • ypos [int|string] (required when height 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:
    • center
    • top
    • bottom
Function-specific properties
  • radius [int] (required for func = circle, roundedsq): Defines the radius of a drawn circle or of the rounded corners of a square.
  • orientation [string] (required for func = triangle): Defines the orientation of the drawn triangle; possible values are:
    • top: The triangle has its vertex on the top and its base on the bottom.
    • bottom: The triangle has its vertex on the bottom and its base on the top.
  • file [string] (required for func = bitmap): Defines the previously loaded bitmap file that must be blit into the screen.

<text>

Parent: <drawdata>
Children: -
Properties: font (required), text_color (required), vertical_align (required), horizontal_align (required)

Example
<text   font = 'text_button'
        text_color = 'color_button'
        vertical_align = 'center'
        horizontal_align = 'center'
/>
Description

The text 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 text key in their DrawData definition.

List of Widgets which require text keys
  • button_idle
  • button_disabled
  • checkbox_disabled
  • checkbox_selected
  • checkbox_default
  • tab_active
  • tab_inactive
  • popup_idle
  • popup_hover

Note that the text key is not really required by the parser, but any widget that wishes to display text must contain one. Adding text keys to widgets who don't natively display text (i.e. those not on the previous list) has no effect.

Properties
  • font [string]: Font identifier from a previously created font key. This font will be used to draw the text.
  • text_color [string]: Color to use. This entry has to match a identifier defined via the text_color key.
  • vertical_alignment [string]: Vertical (Y axis) alignment of the text. Possible values:
    • top
    • bottom
    • center
  • horizontal_alignment [string]: Horizontal (X axis) alignment of the text. Possible values:
    • left
    • right
    • center

<layout_info>

Parent: root
Children: <globals>, <dialog>
Properties: resolution

Example
<layout_info resolution = 'y>399'>
    ...
</layout_info>
Description

The layout_info 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.

Properties
  • resolution [[x|y][<|>]int]: Load only on a given resolution. See resolution-dependant keys.

<globals>

Parent: <layout_info>
Children: <def>, <widget>
Properties: -

Example
<globals>
    ...
</globals>
Description

The globals 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.)



<def>

Parent: <globals>
Children: -
Properties: var (required), value (required), resolution

Example
<def var = 'WidgetSize' value = 'kBigWidgetSize' />
<def resolution = 'y>399' var = 'WidgetSize' value = 'kNormalWidgetSize' />
Description

A def or definition key defines a global variable to be used on the parser by giving it a name (var) and an integer value (value). Note that the value field may also contain a string representing a builtin constant value. You can find a list of such values on the description of the value parameter.

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.

Reserved variable names
  • WidgetSize: The global size of all GUI elements.
  • Line.Height: The height of a line of text.
  • Font.Height: The height of the default font.
  • TabLabelWidth: The width of the label in a Tab Popup.
  • About.OuterBorder: Space between the edges of the screen in the About dialog.
  • ShowLauncherLogo: Set to 1 if the ScummVM should be shown on the main Launcher screen.

All these values are required; failure to define them will cause the parsing of a theme layout to complain.

Properties
  • var [string]: Identifier name for the variable.
  • value [int|string]: Value of the variable, represented by an integer or by a builtin constant from this list:
    • kThumbnailWidth
    • kThumbnailHeight1
    • kThumbnailHeight2
    • kButtonWidth
    • kButtonHeight
    • kSliderWidth
    • kSliderHeight
    • kBigButtonWidth
    • kBigButtonHeight
    • kBigSliderWidth
    • kBigSliderWidth
    • kBigSliderHeight
    • kNormalWidgetSize
    • kBigWidgetSize
  • resolution [[x|y][<|>]int]: Load only on a given resolution. See resolution-dependant keys.

<widget> (global widget definition)

Parent: <globals>
Children: <child> Properties: name (required), size, padding, resolution

Example
<widget name = 'SmallButton'
        size = '128, 18'
/>
Description

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 Slider with certain size properties will allow you to specify Slider 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 <widget> (local widget definition).

<dialog name = 'SampleDialog' overlays = 'screen'>
    <layout type = 'vertical' ...>

    /*  
        Adding a new widget; instead of specifying its size, we set
        its type to the previously defined 'SmallButton', hence it
        automaticall inherits its size
    */
        <widget name = 'A.Sample.Button'
                type = 'SmallButton'
        />

        ...
    </layout>
</dialog>

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:

  • ListWidget: Optionally loads its padding information.
  • PopUpWidget: Optionally loads its padding information.
  • EditTextWidget: Optionally loads its padding information.
  • Console: Optionally loads its padding information.
  • TabWidget.Tab: Loads size and padding information.
  • TabWidget.NavButton: Loads size and padding information.

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 TabWidget sizes, their builtin default values aren't assured to work on all resolutions: Double check them and define them yourself if required.

Properties
  • name [string]: Identifier for the widget.
  • size [int, int]: Width and height of the widget. You may use previously declared defs or builtin constants instead of integers.
  • padding [int, int, int, int]: Pixel padding for Left, Right, Top and Bottom sides, respectively.
  • resolution [[x|y][<|>]int]: Load only on a given resolution. See resolution-dependant keys.

<dialog>

Parent: <layout_info>
Children: <layout>
Properties: name (required), overlays (required), shading, enabled, inset, resolution

Example
<dialog name = 'Launcher' overlays = 'screen'>
    ...
</dialog>

<dialog name = 'GameOptions_Graphics' overlays = 'Dialog.GlobalOptions.TabWidget'>
    ...
</dialog>
Description

Dialog keys are the core of layout definitions; a dialog key is required for each dialog shown ingame, and they are distinguished by using the name property as an unique identifier.

Inside of a dialog key, the actual layout of the dialog is defined by the use of layout, space and widget subkeys; see the sample definition of a GUI layout section.

Note however that the first key inside a dialog must always be a layout -you cannot add widgets before defining its positioning layout.

List of GUI Dialogs

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 dialog key for the given dialog and inside of it, all the dialog's own widgets must be defined.

  • Launcher: Global launcher menu (main dialog of the GUI).
  • Browser: File browser, used for add game menus, theme selections, etc.
  • GlobalOptions: Global options dialog.
  • GlobalOptions_Graphics: Graphics section of the Global Options dialog.
  • GlobalOptions_Audio: Audio section of the Global Options dialog.
  • GlobalOptions_Volume: Volume section of the Global Options dialog.
  • GlobalOptions_MIDI: MIDI section of the Global Options dialog.
  • GlobalOptions_Paths: Paths section of the Global Options dialog.
  • GlobalOptions_Misc: Last section of the Global Options dialog (contains theme loading, etc).
  • GameOptions: Game options menu (edits the options of a game).
  • GameOptions_Graphics: Graphics section of the Game Options dialog.
  • GameOptions_Audio: Audio section of the Game Options dialog.
  • GameOptions_Volume: Volume section of the Game Options dialog.
  • GameOptions_MIDI: MIDI section of the Game Options dialog.
  • GameOptions_Game: Actual game settings section of the Game Options dialog.
  • GameOptions_Paths: Paths section of the Game Options dialog.
  • ScummMain: Main ingame menu for SCUMM based games.
  • ScummConfig: Options menu for SCUMM based games.
  • ScummSaveLoad: Save/Load menu for SCUMM based games.
  • ScummHelp: Help menu for SCUMM based games.
  • KeyMapper: Dialog for mapping keys.
Properties
  • name [string]: Unique name identifying the Dialog (from the above list).
  • overlays [string]: Position of the dialog on screen. Possible values:
    • screen: Dialog fills the whole screen.
    • screen_center: Dialog is centered in the middle of the screen.
    • Local Widget Identifier: Dialog occupies the same space than the given Widget of another dialog. See example.
  • shading [string]: Sets whether all other backgrounds dialog should receive special shading when opening this dialog. Possible values:
    • none: No special shading.
    • luminance: Background dialogs are drawn in black & white.
    • dim: Background dialogs are darkened slightly.
  • enabled [bool]: Sets whether this dialog is enabled. Defaults always to true. May be used to disable dialogs on certain resolutions.
  • inset [int]: Sets the inset value for Screen and Dialog overlays (the amount by which the new dialog is contracted).
  • resolution [[x|y][<|>]int]: Load only on a given resolution. See resolution-dependant keys.

<layout>

Parent: <dialog>, <layout>
Children: <import>, <widget>, <space>, <layout>
Properties: type (required), align, padding, spacing

Example
<layout type = 'vertical' align = 'center' padding = '23, 23, 8, 23'>
    ...
</layout>
Description

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:

  • Vertical Layout: Widgets inside the layout will be placed vertically, from top to bottom.
  • Horizontal Layout: Widgets inside the layout will be placed horizontally, from left to right.

Note that you can also nest other layout keys inside a layout 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.

Properties
  • type [string]: Sets whether the layout is vertical or horizontal.
  • align [string]: Sets the alignment of the children widgets. Allowed values are start, center, end, and stretch. Default is start.
  • padding [int, int, int, int]: Sets the inner padding for the children widgets inside the layout.
  • spacing [int]: Sets the spacing between two children widgets inside the layout.

<import>

Parent: <layout>
Children: -
Properties: layout (required)

Example
<dialog name = 'GameOptions_Audio' overlays = 'Dialog.GlobalOptions.TabWidget'>
    <layout type = 'vertical' padding = '16, 16, 16, 16' spacing = '8'>
        <widget name = 'EnableTabCheckbox' type = 'Checkbox' />
        <import layout = 'Dialog.GlobalOptions_Audio' />
    </layout>
</dialog>
Description

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.

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.

Properties
  • layout [string]: Identifier of a previously defined Dialog, whose layout will be imported.

<space>

Parent: <layout>
Children: -
Properties: size

Example
<widget name = 'StartButton' type = 'Button'/>
<space size = '16' />
<widget name = 'AddGameButton' type = 'Button' />
Description

The space 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.

Spaces don't have width or height; they have a single size property: If the space 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.

Space keys may be optionally left without a size 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.

<layout type = 'horizontal' ...>
    /** Add a button on the left */
    <widget name = 'Button1' type = 'Button'/>

    /** The space without size value will expand to fill all the layout */
    <space/>

    /** Add another button: */
    <widget name = 'Button2' type = 'Button'/>
    /** Since the space had filled the layout, this new button shrinks the
        space by the button's width; hence Button2 is now aligned to the right */
</layout>
Properties
  • size [int]: Size of the space.

<widget> (local widget definition)

Parent: <layout>
Children: -
Properties: name (required), width, height, type, textalign, rtl

Example
<widget name = 'AddGameButton' 
        width = '95'
        height = 'Globals.Button.Height' 
>
<widget name = 'AboutButton' 
        type = 'Button' 
/>
Description

If both the width and height properties are absent, and if the type 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.

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.

GUI Widget Distribution

For a complete list of all the Widget definitions which are expected by the Theme engine, see scummmodern_layout.stx file in scummmodern theme.

Properties
  • name [string]: Unique identifier for this widget (as seen on the GUI Widget distribution list).
  • width [int]: Width of the widget.
  • height [int]: Height of the widget.
  • type [string]: Global Widget Definition from which this widget will inherit its properties.
  • textalign [string]: Sets horizontal alignment of text on this widget. Allowed values are start, end, left, right and center. start and end adapt alignment to GUI's RTL or LTR orientation. Default value is start.
  • rtl [bool]: Sets whether this widget respects RTL orientation when GUI is set to use an RTL language. Defaults always to true. May be used to keep widgets in LTR orientation on both RTL and LTR languages.