Difference between revisions of "GUI Themes/STX Syntax"

From ScummVM :: Wiki
Jump to navigation Jump to search
(→‎<font>: update "font" configuration documentation)
(→‎STX Syntax Keys: add documentation for "text_color".)
Line 174: Line 174:
 
* <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 [int x 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 =====
 +
 +
<syntax type="xml">
 +
<text_color id = 'color_normal'
 +
            color = 'black'
 +
/>
 +
</syntax>
 +
 +
===== 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.
  
 
-----
 
-----

Revision as of 15:02, 10 August 2009

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.

Contents

STX Syntax Keys

<render_info>

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

Example

<syntax type="xml"> <render_info resolution = "320x240">

   ...

</render_info> </syntax>

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 [int x int]: Load only on a given resolution. See resolution-dependant keys.

<palette>

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

Example

<syntax type="xml"> <palette>

   ...

</palette> </syntax>

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

<syntax type="xml"> <color name = 'red'

       rgb = '255, 0, 0'

/> </syntax>

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

<syntax type="xml"> <bitmaps>

   ...

</bitmaps> </syntax>

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

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

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 [int x int]: Load only on a given resolution. See resolution-dependant keys.

<fonts>

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

Example

<syntax type="xml"> <fonts>

   ...

</fonts> </syntax>

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

<syntax type="xml"> </syntax>

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 [int x int]: Load only on a given resolution. See resolution-dependant keys.

<text_color>

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

Example

<syntax type="xml"> <text_color id = 'color_normal'

           color = 'black'

/> </syntax>

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

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

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

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

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 [int x 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

<syntax type="xml"> <drawdata id = 'mainmenu_bg' cache = false>

   <drawstep   ...
   />

</drawdata> </syntax>

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 [int x int]: Load only on a given resolution. See resolution-dependant keys.

<drawstep>

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

Example

<syntax type="xml"> <drawstep func = 'roundedsq'

           radius = '6'
           stroke = 1
           fill = 'gradient'
           shadow = 0
           fg_color = 'shadowcolor'
           gradient_start = 'brightred'
           gradient_end = 'darkred'
           bevel = 1

/> </syntax>

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), vertical_align (required), horizontal_align (required)

Example

<syntax type="xml"> <text font = 'text_button'

       vertical_align = 'center'
       horizontal_align = 'center'

/> </syntax>

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.
  • 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

<syntax type="xml"> <layout_info resolution = '320xY'>

   ...

</layout_info> </syntax>

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 [int x int]: Load only on a given resolution. See resolution-dependant keys.

<globals>

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

Example

<syntax type="xml"> <globals>

   ...

</globals> </syntax>

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

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

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 [int x 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

<syntax type="xml"> <widget name = 'SmallButton'

       size = '128, 18'

/> </syntax>

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

<syntax type="xml"> <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> </syntax>

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 [int x 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

<syntax type="xml"> <dialog name = 'Launcher' overlays = 'screen'>

   ...

</dialog>

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

   ...

</dialog> </syntax>

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 [int x int]: Load only on a given resolution. See resolution-dependant keys.

<layout>

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

Example

<syntax type="xml"> <layout type = 'vertical' center = 'true' padding = '23, 23, 8, 23'>

   ...

</layout> </syntax>

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.
  • center [bool]: Sets whether children widgets inside this layout will be automatically centered.
  • direction [string]: Sets the positioning direction of the children widgets:
    • right2left: Children widgets will be placed starting on the right, as they are parsed.
    • bottom2top: Children widgets will be placed starting on the bottom, as they are parsed.
  • 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

<syntax type="xml"> <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> </syntax>

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

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

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.

<syntax type="xml"> <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> </syntax>

Properties
  • size [int]: Size of the space.

<widget> (local widget definition)

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

Example

<syntax type="xml"> <widget name = 'AddGameButton'

       width = '95'
       height = 'Globals.Button.Height' 

> <widget name = 'AboutButton'

       type = 'Button' 

/> </syntax>

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.
  • enabled [bool]: Sets whether this widget is enabled. Defaults always to true. May be used to disable widgets on certain resolutions.
  • textalign [string]: Sets horizontal alignment of text on this widget. Allowed values are left, right and center. Default value is left.