GUIWidgetDefinitionWML

Widget definition

This page describes the definition of all widgets in the toolkit. Every widget has some parts in common, first of all; every definition has the following fields.

key	type	default	description
id	string	mandatory	Unique id for this gui (theme).
description	t_string	mandatory	Unique translatable name for this gui.
resolution	section	mandatory	The definitions of the widget in various resolutions.

Button

A button is a control that can be pushed to start an action or close a dialog.

The following states exist:

• state_enabled, the button is enabled.
• state_disabled, the button is disabled.
• state_pressed, the left mouse button is down.
• state_focussed, the mouse is over the button.

Drawing

A drawing is widget with a fixed size and gives access to the canvas of the widget in the window instance. This allows special display only widgets.

The definition of a drawing. The widget normally has no event interaction so only one state is defined.

The following states exist:

• state_enabled, the drawing is enabled. The state is a dummy since the things really drawn are placed in the window instance.

Horizontal listbox

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. The definition of a horizontal listbox is the same as for a normal listbox.

Image

An image shows a static image.

The definition of an image. The label field of the widget is used as the name of file to show. The widget normally has no event interaction so only one state is defined.

The following states exist:

• state_enabled, the image is enabled.

Label

A label displays a text, the text can be wrapped but no scrollbars are provided.

Although the label itself has no event interaction it still has two states. The reason is that labels are often used as visual indication of the state of the widget it labels.

Note: The above is outdated, if "link_aware" is enabled then there is interaction.

The following states exist:

• state_enabled, the label is enabled.
• state_disabled, the label is disabled.

key	type	default	description
link_color	string	#ffff00	The color to render links with. This string will be used verbatim in pango markup for each link.

Listbox

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.

The definition of a listbox contains the definition of its scrollbar.

The resolution for a listbox also contains the following keys:

key	type	default	description
scrollbar	section	mandatory	A grid containing the widgets for the scrollbar. The scrollbar has some special widgets so it can make default behavior for certain widgets.

ID (return value)	Type	Mandatory	Description
_begin	clickable	no	Moves the position to the beginning of the list.
_line_up	clickable	no	Move the position one item up. (NOTE if too many items to move per item it might be more items.)
_half_page_up	clickable	no	Move the position half the number of the visible items up. (See note at _line_up.)
_page_up	clickable	no	Move the position the number of visible items up. (See note at _line_up.)
_end	clickable	no	Moves the position to the end of the list.
_line_down	clickable	no	Move the position one item down.(See note at _line_up.)
_half_page_down	clickable	no	Move the position half the number of the visible items down. (See note at _line_up.)
_page_down	clickable	no	Move the position the number of visible items down. (See note at _line_up.)
_scrollbar	vertical_scrollbar	yes	This is the scrollbar so the user can scroll through the list.

A clickable is one of:

• button
• repeating_button

@{allow}{link}{name="gui/window/resolution/grid/row/column/button"} @{allow}{link}{name="gui/window/resolution/grid/row/column/repeating_button"} The following states exist:

• state_enabled, the listbox is enabled.
• state_disabled, the listbox is disabled.

Minimap

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.

The following states exist:

• state_enabled, the minimap is enabled.

Multi page

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.

key	type	default	description
grid	grid	mandatory	A grid containing the widgets for main widget.

A multipage has no states.

Panel

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.

A panel is always enabled and can't be disabled. Instead it uses the states as layers to draw on.

The resolution for a panel also contains the following keys:

key	type	default	description
top_border	unsigned	0	The size which isn't used for the client area.
bottom_border	unsigned	0	The size which isn't used for the client area.
left_border	unsigned	0	The size which isn't used for the client area.
right_border	unsigned	0	The size which isn't used for the client area.

The following layers exist:

• background, the background of the panel.
• foreground, the foreground of the panel.

Progress bar

A progress bar shows the progress of a certain object.

The definition of a progress bar. This object shows the progress of a certain action, or the value state of a certain item.

The following states exist:

• state_enabled, the progress bar is enabled.

Repeating button

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.

The following states exist:

• state_enabled, the repeating_button is enabled.
• state_disabled, the repeating_button is disabled.
• state_pressed, the left mouse repeating_button is down.
• state_focussed, the mouse is over the repeating_button.

Scroll label

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.

This widget is slower as a normal label widget so only use this widget when the scrollbar is required (or expected to become required).

key	type	default	description
grid	grid	mandatory	A grid containing the widgets for main widget.

TODO we need one definition for a vertical scrollbar since this is the second time we use it.

ID (return value)	Type	Mandatory	Description
_content_grid	grid	yes	A grid which should only contain one label widget.
_scrollbar_grid	grid	yes	A grid for the scrollbar (Merge with listbox info.)

The following states exist:

• state_enabled, the scroll label is enabled.
• state_disabled, the scroll label is disabled.

Scrollbar panel

The definition of a panel with scrollbars. A panel is a container holding other elements in its grid. A panel is always enabled and can't be disabled. Instead it uses the states as layers to draw on.

key	type	default	description
grid	grid	mandatory	A grid containing the widgets for main widget.

The following layers exist:

• background, the background of the panel.
• foreground, the foreground of the panel.

Slider

A slider is a control that can select a value by moving a grip on a groove.

key	type	default	description
minimum_positioner_length	unsigned	mandatory	The minimum size the positioner is allowed to be. The engine needs to know this in order to calculate the best size for the positioner.
maximum_positioner_length	unsigned	0	The maximum size the positioner is allowed to be. If minimum and maximum are the same value the positioner is fixed size. If the maximum is 0 (and the minimum not) there's no maximum.
left_offset	unsigned	0	The number of pixels at the left side which can't be used by the positioner.
right_offset	unsigned	0	The number of pixels at the right side which can't be used by the positioner.

The following states exist:

• state_enabled, the slider is enabled.
• state_disabled, the slider is disabled.
• state_pressed, the left mouse button is down on the positioner of the slider.
• state_focussed, the mouse is over the positioner of the slider.

Spacer

A spacer is a dummy item to either fill in a widget since no empty items are allowed or to reserve a fixed space.

A spacer has no states so nothing to load.

Stacked widget

A stacked widget holds several widgets on top of each other. This can be used for various effects; add an optional overlay to an image, stack it with a spacer to force a minimum size of a widget. The latter is handy to avoid making a separate definition for a single instance with a fixed size.

A stacked widget has no states.

Text box

The definition of a text box.

The resolution for a text box also contains the following keys:

key	type	default	description
text_x_offset	f_unsigned	""	The x offset of the text in the text box. This is needed for the code to determine where in the text the mouse clicks, so it can set the cursor properly.
text_y_offset	f_unsigned	""	The y offset of the text in the text box.

The following states exist:

• state_enabled, the text box is enabled.
• state_disabled, the text box is disabled.
• state_focussed, the text box has the focus of the keyboard.

Toggle button

The definition of a toggle button.

A toggle button is a button with two states 'up' and 'down' or 'selected' and 'deselected'. When the mouse is pressed on it the state changes.

The following states exist:

• state_enabled, the panel is enabled and not selected.
• state_disabled, the panel is disabled and not selected.
• state_focussed, the mouse is over the panel and not selected.

• state_enabled_selected, the panel is enabled and selected.
• state_disabled_selected, the panel is disabled and selected.
• state_focussed_selected, the mouse is over the panel and selected.

Variables:

key	type	default	description
grid	grid	mandatory	Defines the grid with the widgets to place on the panel.
return_value_id	string	""	The return value id.
return_value	int	0	The return value.

Toggle panel

The definition of a toggle panel.

Quite some code looks like toggle_button maybe we should inherit from that but let's test first. the problem is that the toggle_button has an icon we don't want, but maybe look at refactoring later. but maybe we should also ditch the icon, not sure however since it's handy for checkboxes...

A toggle panel is an item which can hold multiple 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. The toggle panel is a combination of the panel and a toggle button, it allows a toggle button with its own grid.

The resolution for a toggle panel also contains the following keys:

key	type	default	description
top_border	unsigned	0	The size which isn't used for the client area.
bottom_border	unsigned	0	The size which isn't used for the client area.
left_border	unsigned	0	The size which isn't used for the client area.
right_border	unsigned	0	The size which isn't used for the client area.

The following states exist:

• state_enabled, the panel is enabled and not selected.
• state_disabled, the panel is disabled and not selected.
• state_focussed, the mouse is over the panel and not selected.

• state_enabled_selected, the panel is enabled and selected.
• state_disabled_selected, the panel is disabled and selected.
• state_focussed_selected, the mouse is over the panel and selected.

Variables:

key	type	default	description
grid	grid	mandatory	Defines the grid with the widgets to place on the panel.
return_value_id	string	""	The return value id.
return_value	int	0	The return value.

Tree view

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.

The documentation is not written yet.

The following states exist:

• state_enabled, the listbox is enabled.
• state_disabled, the listbox is disabled.

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.

The resolution for a horizontal scrollbar also contains the following keys:

key	type	default	description
minimum_positioner_length	unsigned	mandatory	The minimum size the positioner is allowed to be. The engine needs to know this in order to calculate the best size for the positioner.
maximum_positioner_length	unsigned	0	The maximum size the positioner is allowed to be. If minimum and maximum are the same value the positioner is fixed size. If the maximum is 0 (and the minimum not) there's no maximum.
left_offset	unsigned	0	The number of pixels at the left which can't be used by the positioner.
right_offset	unsigned	0	The number of pixels at the right which can't be used by the positioner.

The following states exist:

• state_enabled, the horizontal scrollbar is enabled.
• state_disabled, the horizontal scrollbar is disabled.
• state_pressed, the left mouse button is down on the positioner of the horizontal scrollbar.
• state_focussed, the mouse is over the positioner of the horizontal scrollbar.

Vertical scrollbar

The definition of a vertical scrollbar. This class is most of the time not used directly. Instead it's used to build other items with scrollbars.

The resolution for a vertical scrollbar also contains the following keys:

key	type	default	description
minimum_positioner_length	unsigned	mandatory	The minimum size the positioner is allowed to be. The engine needs to know this in order to calculate the best size for the positioner.
maximum_positioner_length	unsigned	0	The maximum size the positioner is allowed to be. If minimum and maximum are the same value the positioner is fixed size. If the maximum is 0 (and the minimum not) there's no maximum.
top_offset	unsigned	0	The number of pixels at the top which can't be used by the positioner.
bottom_offset	unsigned	0	The number of pixels at the bottom which can't be used by the positioner.

The following states exist:

• state_enabled, the vertical scrollbar is enabled.
• state_disabled, the vertical scrollbar is disabled.
• state_pressed, the left mouse button is down on the positioner of the vertical scrollbar.
• state_focussed, the mouse is over the positioner of the vertical scrollbar.

Window

The definition of a window. A window is a kind of panel see the panel for which fields exist