TrustedUser
2,147
edits
Difference between revisions of "GUI Themes/STX Syntax"
Jump to navigation
Jump to search
m
Text replacement - "</source>" to "</syntaxhighlight>"
(→<font>: update "font" configuration documentation) |
m (Text replacement - "</source>" to "</syntaxhighlight>") |
||
| (5 intermediate revisions by 3 users not shown) | |||
| Line 11: | Line 11: | ||
===== Example ===== | ===== Example ===== | ||
< | <syntaxhighlight lang="xml"> | ||
<render_info resolution = " | <render_info resolution = "y>399"> | ||
... | ... | ||
</render_info> | </render_info> | ||
</ | </syntaxhighlight> | ||
===== Description ===== | ===== Description ===== | ||
| Line 23: | Line 23: | ||
===== Properties ===== | ===== Properties ===== | ||
* <tt>resolution [ | * <tt>resolution [[x|y][<|>]int]</tt>: Load only on a given resolution. See resolution-dependant keys. | ||
----- | ----- | ||
| Line 35: | Line 35: | ||
===== Example ===== | ===== Example ===== | ||
< | <syntaxhighlight lang="xml"> | ||
<palette> | <palette> | ||
... | ... | ||
</palette> | </palette> | ||
</ | </syntaxhighlight> | ||
===== Description ===== | ===== Description ===== | ||
| Line 55: | Line 55: | ||
===== Example ===== | ===== Example ===== | ||
< | <syntaxhighlight lang="xml"> | ||
<color name = 'red' | <color name = 'red' | ||
rgb = '255, 0, 0' | rgb = '255, 0, 0' | ||
/> | /> | ||
</ | </syntaxhighlight> | ||
===== Description ===== | ===== Description ===== | ||
| Line 82: | Line 82: | ||
===== Example ===== | ===== Example ===== | ||
< | <syntaxhighlight lang="xml"> | ||
<bitmaps> | <bitmaps> | ||
... | ... | ||
</bitmaps> | </bitmaps> | ||
</ | </syntaxhighlight> | ||
===== Description ===== | ===== Description ===== | ||
| Line 103: | Line 103: | ||
===== Example ===== | ===== Example ===== | ||
< | <syntaxhighlight lang="xml"> | ||
<bitmap filename = 'logo.bmp'/> | <bitmap filename = 'logo.bmp'/> | ||
</ | </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 [ | * <tt>resolution [[x|y][<|>]int]</tt>: Load only on a given resolution. See resolution-dependant keys. | ||
----- | ----- | ||
| Line 128: | Line 128: | ||
===== Example ===== | ===== Example ===== | ||
< | <syntaxhighlight lang="xml"> | ||
<fonts> | <fonts> | ||
... | ... | ||
</fonts> | </fonts> | ||
</ | </syntaxhighlight> | ||
===== Description ===== | ===== Description ===== | ||
| Line 149: | Line 149: | ||
===== Example ===== | ===== Example ===== | ||
< | <syntaxhighlight lang="xml"> | ||
<font id = 'text_default' | <font id = 'text_default' | ||
file = 'default' | file = 'default' | ||
/> | /> | ||
</ | </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 "default" 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 "default" to let the renderer choose the most appropriate default font based on the active resolution (usually an builtin one). | ||
* <tt>resolution [ | * <tt>resolution [[x|y][<|>]int]</tt>: Load only on a given resolution. See resolution-dependant keys. | ||
----- | |||
==== <tt><text_color></tt> ==== | |||
Parent: <tt><fonts></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 ===== | ||
< | <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'/> | ||
</ | </syntaxhighlight> | ||
===== Description ===== | ===== Description ===== | ||
| Line 206: | Line 251: | ||
===== Example ===== | ===== Example ===== | ||
< | <syntaxhighlight lang="xml"> | ||
<cursor file = 'cursor.bmp' hotspot = '0, 0' scale = '3'/> | <cursor file = 'cursor.bmp' hotspot = '0, 0' scale = '3'/> | ||
</ | </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 [ | * <tt>resolution [[x|y][<|>]int]</tt>: Load only on a given resolution. See resolution-dependant keys. | ||
----- | ----- | ||
| Line 233: | Line 278: | ||
===== Example ===== | ===== Example ===== | ||
< | <syntaxhighlight lang="xml"> | ||
<drawdata id = 'mainmenu_bg' cache = false> | <drawdata id = 'mainmenu_bg' cache = false> | ||
<drawstep ... | <drawstep ... | ||
/> | /> | ||
</drawdata> | </drawdata> | ||
</ | </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 [ | * <tt>resolution [[x|y][<|>]int]</tt>: Load only on a given resolution. See resolution-dependant keys. | ||
----- | ----- | ||
| Line 284: | Line 329: | ||
===== Example ===== | ===== Example ===== | ||
< | <syntaxhighlight lang="xml"> | ||
<drawstep func = 'roundedsq' | <drawstep func = 'roundedsq' | ||
radius = '6' | radius = '6' | ||
| Line 295: | Line 340: | ||
bevel = 1 | bevel = 1 | ||
/> | /> | ||
</ | </syntaxhighlight> | ||
===== Description ===== | ===== Description ===== | ||
| Line 365: | Line 410: | ||
Parent: <tt><drawdata></tt><br /> | Parent: <tt><drawdata></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 ===== | ||
< | <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' | ||
/> | /> | ||
</ | </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 ===== | ||
< | <syntaxhighlight lang="xml"> | ||
<layout_info resolution = ' | <layout_info resolution = 'y>399'> | ||
... | ... | ||
</layout_info> | </layout_info> | ||
</ | </syntaxhighlight> | ||
===== Description ===== | ===== Description ===== | ||
| Line 427: | Line 474: | ||
===== Properties ===== | ===== Properties ===== | ||
* <tt>resolution [ | * <tt>resolution [[x|y][<|>]int]</tt>: Load only on a given resolution. See resolution-dependant keys. | ||
----- | ----- | ||
| Line 439: | Line 486: | ||
===== Example ===== | ===== Example ===== | ||
< | <syntaxhighlight lang="xml"> | ||
<globals> | <globals> | ||
... | ... | ||
</globals> | </globals> | ||
</ | </syntaxhighlight> | ||
===== Description ===== | ===== Description ===== | ||
| Line 460: | Line 507: | ||
===== Example ===== | ===== Example ===== | ||
< | <syntaxhighlight lang="xml"> | ||
<def var = 'WidgetSize' value = 'kBigWidgetSize' /> | <def var = 'WidgetSize' value = 'kBigWidgetSize' /> | ||
<def resolution = ' | <def resolution = 'y>399' var = 'WidgetSize' value = 'kNormalWidgetSize' /> | ||
</ | </syntaxhighlight> | ||
===== Description ===== | ===== Description ===== | ||
| Line 499: | Line 546: | ||
** kNormalWidgetSize | ** kNormalWidgetSize | ||
** kBigWidgetSize | ** kBigWidgetSize | ||
* <tt>resolution [ | * <tt>resolution [[x|y][<|>]int]</tt>: Load only on a given resolution. See resolution-dependant keys. | ||
----- | ----- | ||
| Line 510: | Line 557: | ||
===== Example ===== | ===== Example ===== | ||
< | <syntaxhighlight lang="xml"> | ||
<widget name = 'SmallButton' | <widget name = 'SmallButton' | ||
size = '128, 18' | size = '128, 18' | ||
/> | /> | ||
</ | </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><widget></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><widget></tt> (''local widget definition''). | ||
< | <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> | ||
</ | </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 [ | * <tt>resolution [[x|y][<|>]int]</tt>: Load only on a given resolution. See resolution-dependant keys. | ||
----- | ----- | ||
| Line 565: | Line 612: | ||
===== Example ===== | ===== Example ===== | ||
< | <syntaxhighlight lang="xml"> | ||
<dialog name = 'Launcher' overlays = 'screen'> | <dialog name = 'Launcher' overlays = 'screen'> | ||
... | ... | ||
| Line 573: | Line 620: | ||
... | ... | ||
</dialog> | </dialog> | ||
</ | </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 [ | * <tt>resolution [[x|y][<|>]int]</tt>: Load only on a given resolution. See resolution-dependant keys. | ||
----- | ----- | ||
| Line 636: | Line 683: | ||
===== Example ===== | ===== Example ===== | ||
< | <syntaxhighlight lang="xml"> | ||
<layout type = 'vertical' center = 'true' padding = '23, 23, 8, 23'> | <layout type = 'vertical' center = 'true' padding = '23, 23, 8, 23'> | ||
... | ... | ||
</layout> | </layout> | ||
</ | </syntaxhighlight> | ||
===== Description ===== | ===== Description ===== | ||
| Line 670: | Line 717: | ||
===== Example ===== | ===== Example ===== | ||
< | <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 724: | ||
</layout> | </layout> | ||
</dialog> | </dialog> | ||
</ | </syntaxhighlight> | ||
===== Description ===== | ===== Description ===== | ||
| Line 699: | Line 746: | ||
===== Example ===== | ===== Example ===== | ||
< | <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' /> | ||
</ | </syntaxhighlight> | ||
===== Description ===== | ===== Description ===== | ||
| Line 713: | Line 760: | ||
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. | ||
< | <syntaxhighlight lang="xml"> | ||
<layout type = 'horizontal' ...> | <layout type = 'horizontal' ...> | ||
/** Add a button on the left */ | /** Add a button on the left */ | ||
| Line 726: | Line 773: | ||
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> | ||
</ | </syntaxhighlight> | ||
===== Properties ===== | ===== Properties ===== | ||
| Line 742: | Line 789: | ||
===== Example ===== | ===== Example ===== | ||
< | <syntaxhighlight lang="xml"> | ||
<widget name = 'AddGameButton' | <widget name = 'AddGameButton' | ||
width = '95' | width = '95' | ||
| Line 750: | Line 797: | ||
type = 'Button' | type = 'Button' | ||
/> | /> | ||
</ | </syntaxhighlight> | ||
===== Description ===== | ===== Description ===== | ||