GUIToolkitWML
Contents
GUI
The gui class contains the definitions of all widgets and windows used in the game. This can be seen as a skin and it allows the user to define the visual aspect of the various items. The visual aspect can be determined depending on the size of the game window.
Widgets have a definition and an instance, the definition contains the general info/looks of a widget and the instance the actual looks. Eg the where the button text is placed is the same for every button, but the text of every button might differ.
The default gui has the id default and must exist, in the default gui there must a definition of every widget with the id default and every window needs to be defined. If the definition of a widget with a certain id doesn't exist it will fall back to default in the current gui, if it's not defined there either it will fall back to the default widget in the default theme. That way it's possible to slowly create your own gui and test it.
The gui has the following data:
| key | type | default | description |
|---|---|---|---|
| id | string | mandatory | Unique id for this gui (theme). |
| description | t_string | mandatory | Unique translatable name for this gui. |
| widget_definitions | section | mandatory | The definitions of all widgets. |
| window | section | mandatory | The definitions of all windows. |
| settings | section | mandatory | The settings for the gui. |
List of available widgets:
| Section | Description |
|---|---|
| (definition, instantiation) | A button is a control that can be pushed to start an action or close a dialog. |
| Image (definition, instantiation) | An image shows a static image. |
| Horizontal listbox (definition, instantiation) | A horizontal listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version orders them in columns instead. |
| Horizontal scrollbar (definition, instantiation) | A horizontal scrollbar is a widget that shows a horizontal scrollbar. This widget is most of the time used in a container to control the scrolling of its contents. |
| Label (definition, instantiation) | A label displays a text, the text can be wrapped but no scrollbars are provided. |
| Listbox (definition, instantiation) | A listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version might allow more options for ordering the items in the future. |
| Minimap (definition, instantiation) | A minimap to show the gamemap, this only shows the map and has no interaction options. This version is used for map previews, there will be a another version which allows interaction. |
| Multi page (definition, instantiation) | A multi page is a control that contains several 'pages' of which only one is visible. The pages can contain the same widgets containing the same 'kind' of data or look completely different. |
| Panel (definition, instantiation) | A panel is an item which can hold other items. The difference between a grid and a panel is that it's possible to define how a panel looks. A grid in an invisible container to just hold the items. |
| Password box (definition, instantiation) | A text box masking it's content by asterisks. |
| (definition, instantiation) | A repeating_button is a control that can be pushed down and repeat a certain action. Once the button is down every x milliseconds it is down a new down event is triggered. |
| Scroll label (definition, instantiation) | A scroll label is a label that wraps its text and also has a vertical scrollbar. This way a text can't be too long to be shown for this widget. |
| Slider (definition, instantiation) | A slider is a control that can select a value by moving a grip on a groove. |
| Spacer (definition, instantiation) | A spacer is a dummy item to either fill in a widget since no empty items are allowed or to reserve a fixed space. |
| Stacked widget (definition, instantiation) | A stacked widget is a control several widgets can be stacked on top of each other in the same space. This is mainly intended for over- and underlays. (The widget is still experimental.) |
| Text box (definition, instantiation) | A single line text box. |
| Tree view (definition, instantiation) | A tree view is a control that holds several items of the same or different types. The items shown are called tree view nodes and when a node has children, these can be shown or hidden. Nodes that contain children need to provide a clickable button in order to fold or unfold the children. |
| (definition, instantiation) | A kind of button with two 'states' normal and selected. This is a more generic widget which is used for eg checkboxes and radioboxes. |
| Toggle panel (definition, instantiation) | Like a toggle button but then as panel so can hold multiple items in a grid. |
| Tooltip (definition, instantiation) | A small tooltip with help. |
| Tree view (definition, instantiation) | A tree view widget. |
| Vertical scrollbar (definition, instantiation) | A vertical scrollbar. |
| Window (definition, instantiation) | A window. |
List of available windows:
| Section | Description |
|---|---|
| Addon connect (definition) | The dialog to connect to the addon server and maintain locally installed addons. |
| Addon list (definition) | Shows the list of the addons to install or update. |
| Campaign selection (definition) | Shows the list of campaigns, to select one to play. |
| Language selection (definition) | The dialog to select the primary language. |
| WML message left (definition) | The ingame message dialog with a portrait on the left side. (Used for the WML messages.) |
| WML message right (definition) | The ingame message dialog with a portrait on the right side. (Used for the WML messages.) |
| Message (definition) | A generic message dialog. |
| MP connect (definition) | The dialog to connect to the MP server. |
| MP method selection (definition) | The dialog to select the kind of MP game to play. Official server, local etc. |
| MP server list (definition) | List of the 'official' MP servers. |
| MP login (definition) | The dialog to provide a password for registered usernames, request a password reminder or choose a different username. |
| MP cmd wrapper (definition) | Perform various actions on the selected user (e.g. whispering or kicking). |
| MP create game (definition) | The dialog to select and create an MP game. |
| Title screen (definition) | The title screen. |
| Editor new map (definition) | Creates a new map in the editor. |
| Editor generate map (definition) | Generates a random map in the editor. |
| Editor resize map (definition) | Resizes a map in the editor. |
| Editor custom tod (definition) | Creates new ToD schedules for the editor. |
A setting section has the following variables:
| key | type | default | description |
|---|---|---|---|
| popup_show_delay | unsigned | 0 | The time it take before the popup shows if the mouse moves over the widget. 0 means show directly. |
| popup_show_time | unsigned | 0 | The time a shown popup remains visible. 0 means until the mouse leaves the widget. |
| help_show_time | unsigned | 0 | The time a shown help remains visible. 0 means until the mouse leaves the widget. |
| double_click_time | unsigned | mandatory | The time between two clicks to still be a double click. |
| repeat_button_repeat_time | unsigned | 0 | The time a repeating button waits before the next event is issued if the button is still pressed down. |
| sound_button_click | string | "" | The sound played if a button is clicked. |
| sound_toggle_button_click | string | "" | The sound played if a toggle button is clicked. |
| sound_toggle_panel_click | string | "" | The sound played if a toggle panel is clicked. Normally the toggle panels are the items in a listbox. If a toggle button is in the listbox it's sound is played. |
| sound_slider_adjust | string | "" | The sound played if a slider is adjusted. |
| has_helptip_message | t_string | mandatory | The string used to append the tooltip if there is also a helptip. The WML variable $hotkey can be used to get show the name of the hotkey for the help. |
Resolution
Depending on the resolution a widget can look different. Resolutions are evaluated in order of appearance. The window_width and window_height are the upper limit this resolution is valid for. When one of the sizes gets above the limit, the next resolution is selected. There's one special case where both values are 0. This resolution always matches. (Resolution definitions behind that one will never be picked.) This resolution can be used as upper limit or if there's only one resolution.
The default (and also minimum) size of a button is determined by two items, the wanted default size and the size needed for the text. The size of the text differs per used widget so needs to be determined per button.
Container widgets like panels and windows have other rules for their sizes. Their sizes are based on the size of their children (and the border they need themselves). It's wise to set all sizes to 0 for these kind of widgets.
| key | type | default | description |
|---|---|---|---|
| window_width | unsigned | 0 | Width of the application window. |
| window_height | unsigned | 0 | Height of the application window. |
| min_width | unsigned | 0 | The minimum width of the widget. |
| min_height | unsigned | 0 | The minimum height of the widget. |
| default_width | unsigned | 0 | The default width of the widget. |
| default_height | unsigned | 0 | The default height of the widget. |
| max_width | unsigned | 0 | The maximum width of the widget. |
| max_height | unsigned | 0 | The maximum height of the widget. |
| text_extra_width | unsigned | 0 | The extra width needed to determine the minimal size for the text. |
| text_extra_height | unsigned | 0 | The extra height needed to determine the minimal size for the text. |
| text_font_family | font_family | "" | The font family, needed to determine the minimal size for the text. |
| text_font_size | unsigned | 0 | The font size, which needs to be used to determine the minimal size for the text. |
| text_font_style | font_style | "" | The font style, which needs to be used to determine the minimal size for the text. |
| state | section | mandatory | Every widget has one or more state sections. Note they aren't called state but state_xxx the exact names are listed per widget. |
State
A state contains the info what to do in a state. At the moment this is rather focussed on the drawing part, might change later. Keys: Keys:
| key | type | default | description |
|---|---|---|---|
| draw | section | mandatory | Section with drawing directions for a canvas. |
Window definition
A window defines how a window looks in the game.
| key | type | default | description |
|---|---|---|---|
| id | string | mandatory | Unique id for this window. |
| description | t_string | mandatory | Unique translatable name for this window. |
| resolution | section | mandatory | The definitions of the window in various resolutions. |
Resolution
| key | type | default | description |
|---|---|---|---|
| window_width | unsigned | 0 | Width of the application window. |
| window_height | unsigned | 0 | Height of the application window. |
| automatic_placement | bool | true | Automatically calculate the best size for the window and place it. If automatically placed vertical_placement and horizontal_placement can be used to modify the final placement. If not automatically placed the width and height are mandatory. |
| x | f_unsigned | 0 | X coordinate of the window to show. |
| y | f_unsigned | 0 | Y coordinate of the window to show. |
| width | f_unsigned | 0 | Width of the window to show. |
| height | f_unsigned | 0 | Height of the window to show. |
| reevaluate_best_size | f_bool | false | The foo |
| functions | function | "" | The function definitions s available for the formula fields in window. |
| vertical_placement | v_align | "" | The vertical placement of the window. |
| horizontal_placement | h_align | "" | The horizontal placement of the window. |
| maximum_width | unsigned | 0 | The maximum width of the window (only used for automatic placement). |
| maximum_height | unsigned | 0 | The maximum height of the window (only used for automatic placement). |
| click_dismiss | bool | false | Does the window need click dismiss behavior? Click dismiss behavior means that any mouse click will close the dialog. Note certain widgets will automatically disable this behavior since they need to process the clicks as well, for example buttons do need a click and a misclick on button shouldn't close the dialog. NOTE with some widgets this behavior depends on their contents (like scrolling labels) so the behavior might get changed depending on the data in the dialog. NOTE the default behavior might be changed since it will be disabled when can't be used due to widgets which use the mouse, including buttons, so it might be wise to set the behavior explicitly when not wanted and no mouse using widgets are available. This means enter, escape or an external source needs to be used to close the dialog (which is valid). |
| definition | string | "default" | Definition of the window which we want to show. |
| linked_group | sections | [] | A group of linked widget sections. |
| tooltip | section | mandatory | Information regarding the tooltip for this window. |
| helptip | section | mandatory | Information regarding the helptip for this window. |
| grid | grid | mandatory | The grid with the widgets to show. |
A linked_group section has the following fields:
| key | type | default | description |
|---|---|---|---|
| id | string | mandatory | The unique id of the group (unique in this window). |
| fixed_width | bool | false | Should widget in this group have the same width. |
| fixed_height | bool | false | Should widget in this group have the same height. |
A linked group needs to have at least one size fixed.
A tooltip and helptip section have the following field:
| key | type | default | description |
|---|---|---|---|
| id | string | The id of the tip to show. |
Note more fields will probably be added later on.
Cell
| key | type | default | description |
|---|---|---|---|
| id | string | "" | A grid is a widget and can have an id. This isn't used that often, but is allowed. |
| linked_group | string | 0 |
Every grid cell has some cell configuration values and one widget in the grid cell. Here we describe the what is available more information about the usage can be found here GUILayout.
Row values
For every row the following variables are available:
| key | type | default | description |
|---|---|---|---|
| grow_factor | unsigned | 0 | The grow factor for a row. |
Cell values
For every column the following variables are available:
| key | type | default | description |
|---|---|---|---|
| grow_factor | unsigned | 0 | The grow factor for a column, this value is only read for the first row. |
| border_size | unsigned | 0 | The border size for this grid cell. |
| border | border | "" | Where to place the border in this grid cell. |
| vertical_alignment | v_align | "" | The vertical alignment of the widget in the grid cell. (This value is ignored if vertical_grow is true.) |
| horizontal_alignment | h_align | "" | The horizontal alignment of the widget in the grid cell.(This value is ignored if horizontal_grow is true.) |
| vertical_grow | bool | false | Does the widget grow in vertical direction when the grid cell grows in the vertical direction. This is used if the grid cell is wider as the best width for the widget. |
| horizontal_grow | bool | false | Does the widget grow in horizontal direction when the grid cell grows in the horizontal direction. This is used if the grid cell is higher as the best width for the widget. |
Horizontal scrollbar
A horizontal scrollbar is a widget that shows a horizontal scrollbar. This widget is most of the time used in a container to control the scrolling of its contents.
A horizontal scrollbar has no special fields.
Stacked widget
A stacked widget is a set of widget stacked on top of each other. The widgets are drawn in the layers, in the order defined in the the instance config. By default the last drawn item is also the 'active' layer for the event handling.
Toggle button
| key | type | default | description |
|---|---|---|---|
| icon | f_string | "" | The name of the icon file to show. |
| return_value_id | string | "" | The return value id, see GUIToolkitWML#Button for more information. |
| return_value | int | 0 | The return value, see GUIToolkitWML#Button for more information. |
List if the id's that have generate a return value:
- ok confirms the dialog.
- cancel cancels the dialog.