GUIToolkitWML

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.

In WML, the gui class is represented by the toplevel `[gui]` tag, which supports the following keys,

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
Button (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.
Repeating button (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.
Toggle button (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.