GUIWidgetInstanceWML

Widget instance

Inside a grid (which is inside all container widgets) a widget is instantiated. With this instantiation some more variables of a widget can be tuned. This page will describe what can be tuned.

Widget

All widgets placed in the cell have some values in common:

key	type	default	description
id	string	""	This value is used for the engine to identify 'special' items. This means that for example a text_box can get the proper initial value. This value should be unique or empty. Those special values are documented at the window definition that uses them. NOTE items starting with an underscore are used for composed widgets and these should be unique per composed widget.
definition	string	"default"	The id of the widget definition to use. This way it's possible to select a specific version of the widget e.g. a title label when the label is used as title.
linked_group	string	""	The linked group the control belongs to.
label	t_string	""	Most widgets have some text associated with them, this field contain the value of that text. Some widgets use this value for other purposes, this is documented at the widget. E.g. an image uses the filename in this field.
tooltip	t_string	""	If you hover over a widget a while (the time it takes can differ per widget) a short help can show up.This defines the text of that message. This field may not be empty when 'help' is set.
help	t_string	""	If you hover over a widget and press F10 (or the key the user defined for the help tip) a help message can show up. This help message might be the same as the tooltip but in general (if used) this message should show more help. This defines the text of that message.
use_tooltip_on_label_overflow	bool	true	If the text on the label is truncated and the tooltip is empty the label can be used for the tooltip. If this variable is set to true this will happen.
debug_border_mode	unsigned	0	The mode for showing the debug border. This border shows the area reserved for a widget. This function is only meant for debugging and might not be available in all Wesnoth binaries. Available modes: 0: no border. 1: 1 pixel border. 2: floodfill the widget area.
debug_border_color	color	""	The color of the debug border.
size_text	t_string	""	Sets the minimum width of the widget depending on the text in it. (Note not implemented yet.)

Button

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

Instance of a button. When a button has a return value it sets the return value for the window. Normally this closes the window and returns this value to the caller. The return value can either be defined by the user or determined from the id of the button. The return value has a higher precedence as the one defined by the id. (Of course it's weird to give a button an id and then override its return value.)

When the button doesn't have a standard id, but you still want to use the return value of that id, use return_value_id instead. This has a higher precedence as return_value.

List with the button specific variables:

key	type	default	description
return_value_id	string	""	The return value id.
return_value	int	0	The return value.

Supported values for return_value_id:

string	value	description
"ok"	-1	Equivalent to closing the dialog by pressing the Enter key
"cancel"	-2	Equivalent to closing the dialog by pressing the Esc key
"quit"	-2	An alias for cancel
""	N/A	Clears any previously set return_value_id

Combobox

A Combobox with its list open

A widget with a text box and a dropdown list. Selecting an element from the list sets the value of the text box to that item of the list. The user can also manually enter a value in the text box.

key	type	default	description
label	string	""	The text of the combobox
max_input_length	int	0	Maximum length of text in characters that can be entered into the combobox
hint_text	string	""	Text that is shown in the background when there is no input
hint_image	string	""	Image that is shown in the background when there is no input

Subtag [option]

Specifies the initial list of options to be shown in the combobox.

key	type	default	description
label	t_string	""	Name of the option.
tooltip	t_string	""	Tooltip that is shown when the mouse hovers above this option.
icon	string	""	WML path to the icon to be shown alongside the text in this option, if any.
details	t_string	""	Short description about this option.

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.

If either the width or the height is not zero the drawing functions as a fixed size drawing.

key	type	default	description
width	f_unsigned	0	The width of the drawing.
height	f_unsigned	0	The height of the drawing.
draw	config	mandatory	The config containing the drawing.

The variable available are the same as for the window resolution see http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of items.

Grid Listbox

List with the listbox specific variables:

ID (return value)	Type	Mandatory	Description
vertical_scrollbar_mode	scrollbar_mode	initial_auto	Determines whether or not to show the scrollbar.
horizontal_scrollbar_mode	scrollbar_mode	initial_auto	Determines whether or not to show the scrollbar.
header	grid	[]	Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
footer	grid	[]	Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
list_definition	section	mandatory	This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
list_data	section	[]	A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
has_minimum	bool	true	If false, less than one row can be selected.
has_maximum	bool	true	If false, more than one row can be selected.

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.

List with the horizontal listbox specific variables:

ID (return value)	Type	Mandatory	Description
vertical_scrollbar_mode	scrollbar_mode	initial_auto	Determines whether or not to show the scrollbar.
horizontal_scrollbar_mode	scrollbar_mode	initial_auto	Determines whether or not to show the scrollbar.
header	grid	[]	Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
footer	grid	[]	Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
list_definition	section	mandatory	This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
list_data	section	[]	A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
has_minimum	bool	true	If false, less than one row can be selected.
has_maximum	bool	true	If false, more than one row can be selected.

In order to force widgets to be the same size inside a horizontal listbox, the widgets need to be inside a linked_group.

Inside the list section there are only the following widgets allowed

• grid (to nest)
• selectable widgets which are
  • toggle_button
  • toggle_panel

Image

An image shows a static image whose path is specified by its label key. Unlike other widgets, the label key here is not translatable since it specifies a path. The path is a standard WML path, i.e., label="units/konrad.png" or label="~add-ons/MyAddon/image/test.png".

It has no other extra fields.

Label

A label displays text provided via the label key that can be wrapped but no scrollbars are provided. For a version with scrollbars, see the Scroll Label widget.

A Label with definition "title"

List with the label specific variables:

key	type	default	description
wrap	bool	false	Is wrapping enabled for the label.
characters_per_line	unsigned	0	Sets the maximum number of characters per line. This is only an approximate means of limiting the line's length, since the width of a character differs. E.g. iii is smaller than MMM. When the value is non-zero it also implies wrap is true. When having long strings, wrapping them can increase readability. A rule of thumb is 66 characters per line is considered the optimum for a one column text.
text_alignment	h_align	left	The way the text is aligned inside the canvas.
can_shrink	bool	false	Whether the label can shrink past its optimal size.
link_aware	bool	false	Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.

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.

List with the listbox specific variables:

key	type	default	description
vertical_scrollbar_mode	scrollbar_mode	initial_auto	Determines whether or not to show the scrollbar.
horizontal_scrollbar_mode	scrollbar_mode	initial_auto	Determines whether or not to show the scrollbar.
header	grid	[]	Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
footer	grid	[]	Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
list_definition	section	mandatory	This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
list_data	section	[]	A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
has_minimum	bool	true	If false, less than one row can be selected.
has_maximum	bool	true	If false, more than one row can be selected.

In order to force widgets to be the same size inside a listbox, the widgets need to be inside a linked_group.

Inside the list section there are only the following widgets allowed

• grid (to nest)
• selectable widgets which are
  • toggle_button
  • toggle_panel

Matrix

List with the matrix specific variables:

key	type	default	description
vertical_scrollbar_mode	scrollbar_mode	initial_auto	Determines whether or not to show the scrollbar.
horizontal_scrollbar_mode	scrollbar_mode	initial_auto	Determines whether or not to show the scrollbar.

Menu Button

A Menu Button with it's list open.

A button that shows a dropdown list when clicked. The user can select any one of the predefined options.

key	type	default	description
return_value_id	string	""	The return value id.
return_value	int	0	The return value.

Subtag [option]

Specifies the initial list of options to be shown in the menu_button.

key	type	default	description
label	t_string	""	Name of the option.
tooltip	t_string	""	Tooltip that is shown when the mouse hovers above this option.
icon	string	""	WML path to the icon to be shown alongside the text in this option, if any.
details	t_string	""	Short description about this option.

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.

A minimap has no extra fields.

Multiline Text

Base class for a multiline text area. Not to be used directly in a GUI, use the scroll_text widget instead.

The following variables exist:

key	type	default	description
label	t_string	""	The initial text of the text box.
history	string	""	The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
editable	bool	"true"	If the contents of the text box can be edited.

Multimenu Button

A Multimenu Button with its list open

A widget clicking on which shows a list from which one or more options can be selected.

List with the multimenu_button specific variables:

key	type	default	description
return_value_id	string	""	The return value id.
return_value	int	0	The return value.
maximum_shown	int	-1	The maximum number of currently selected values to list on the button.

Subtag [option]

Specifies the initial list of options to be shown in the multimenu_button.

key	type	default	description
label	t_string	""	Name of the option.
tooltip	t_string	""	Tooltip that is shown when the mouse hovers above this option.
checkbox	bool	""	Whether the checkbox alongside this option is selected or not.
details	t_string	""	Short description about this option.

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.

List with the multi page specific variables:

key	type	default	description
page_definition	section	mandatory	This defines how a multi page item looks. It must contain the grid definition for at least one page.
page_data	section	[]	A grid alike section which stores the initial data for the multi page. Every row must have the same number of columns as the 'page_definition'.

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.

key	type	default	description
grid	grid	mandatory	Defines the grid with the widgets to place on the panel.

Password box

key	type	default	description
label	t_string	""	The initial text of the password box.

Progress bar

A progress bar shows the progress of a certain object.

A progress bar has no extra fields.

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.

Rich Label

A label that shows formatted text marked up with Help markup. It can show embedded images, links and tables inside text.

key	type	default	description
text_alignment	h_align	left	The way the text is aligned inside the canvas.
width	int	500	Width of its internal formatted content. Text will wrap beyond this width.
link_aware	bool	false	Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.

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.

List with the scroll label specific variables:

key	type	default	description
vertical_scrollbar_mode	scrollbar_mode	initial_auto	Determines whether or not to show the scrollbar.
horizontal_scrollbar_mode	scrollbar_mode	initial_auto	Determines whether or not to show the scrollbar.

Scrollbar panel

Instance of a scrollbar_panel.

List with the scrollbar_panel specific variables:

key	type	default	description
vertical_scrollbar_mode	scrollbar_mode	initial_auto	Determines whether or not to show the scrollbar.
horizontal_scrollbar_mode	scrollbar_mode	initial_auto	Determines whether or not to show the scrollbar.
definition	section	mandatory	This defines how a scrollbar_panel item looks. It must contain the grid definition for 1 row of the list.

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.

If either the width or the height is non-zero the spacer functions as a fixed size spacer.

key	type	default	description
width	f_unsigned	0	The width of the spacer.
height	f_unsigned	0	The height of the spacer.

The variable available are the same as for the window resolution see http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of items.

Tab Container

A container widget that can show its contents separated into various pages, each of which are accessible.

It can contain one or more [tab] tags inside it, each defining a tab's name, image (if any) and the contents of the tag, specified by the [data] tag inside the [tab] tag.

Subtag [tab]

key	type	default	description
name	t_string	""	Name of the tab
image	string	""	Image for the tab to be shown alongside the name, if any
[data]	grid	empty grid	This subtag contains a grid that defines the contents for this tab.

Text box

A single line text entry widget.

A Text Box

key	type	default	description
label	t_string	""	The initial text of the text box.
history	string	""	The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
max_input_length	int	0	Maximum length of text in characters that can be entered into the combobox
hint_text	string	""	Text that is shown in the background when there is no input
hint_image	string	""	Image that is shown in the background when there is no input
editable	bool	"true"	If the contents of the text box can be edited.

Toggle panel

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

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, see GUIToolkitWML#Button for more information.
return_value	int	0	The return value, see GUIToolkitWML#Button for more information.

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.

List with the tree view specific variables:

key	type	default	description
vertical_scrollbar_mode	scrollbar_mode	initial_auto	Determines whether or not to show the scrollbar.
horizontal_scrollbar_mode	scrollbar_mode	initial_auto	Determines whether or not to show the scrollbar.
indention_step_size	unsigned	0	The number of pixels every level of nodes is indented from the previous level.
node	unsigned	mandatory	The tree view can contain multiple node sections. This part needs more documentation.
id	unsigned	""	.
return_value_id	unsigned	""	.

NOTE more documentation and examples are needed.

Viewport

A viewport is an special widget used to view only a part of the widget it `holds'.

List with the viewport specific variables:

key	type	default	description
grow_direction	grow_direction	mandatory	The direction in which new items grow.
parallel_items	unsigned	mandatory	The number of items that are growing in parallel.
item_definition	section	mandatory	The definition of a new item.

Scroll Text

A multiline text area that shows a scrollbar if the text gets too long.

List with the scrollbar container specific variables:

key	type	default	description
vertical_scrollbar_mode	scrollbar_mode	initial_auto	Determines whether or not to show the scrollbar.
horizontal_scrollbar_mode	scrollbar_mode	initial_auto	Determines whether or not to show the scrollbar.
editable	bool	"true"	If the contents of this scroll_text can be edited.

Slider

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

key	type	default	description
best_slider_length	unsigned	0	The best length for the sliding part.
minimum_value	int	0	The minimum value the slider can have.
maximum_value	int	0	The maximum value the slider can have.
step_size	unsigned	0	The number of items the slider's value increases with one step.
value	int	0	The value of the slider.
minimum_value_label	t_string	""	If the minimum value is chosen there might be the need for a special value (eg off). When this key has a value that value will be shown if the minimum is selected.
maximum_value_label	t_string	""	If the maximum value is chosen there might be the need for a special value (eg unlimited)). When this key has a value that value will be shown if the maximum is selected.

Toggle button

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.