Difference between revisions of "GUIWidgetInstanceWML"

From The Battle for Wesnoth Wiki
(Button - add description of valid values for return_value_id)
(Image: explalin how label key is used.)
Line 288: Line 288:
  
 
== Image ==
 
== Image ==
An image shows a static image.
+
An image shows a static image whose path is specified by its '''[[GUIWidgetInstanceWML#Widget|label]]''' key. Unlike other widgets, the '''label''' key here is not translatable since it specifies a path.
  
An image has no extra fields.
+
It has no other extra fields.
  
 
== Label ==
 
== Label ==

Revision as of 09:07, 26 September 2024

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.

It has no other extra fields.

Label

A label displays text that can be wrapped but no scrollbars are provided.

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. The amount is an approximate since the width of a character differs. E.g. iii is smaller than MMM. When the value is non-zero it also implies can_wrap is true. When having long strings wrapping them can increase readability, often 66 characters per line is considered the optimum for a one column text. text_alignment & h_align & "left" & How is the text aligned in the label.
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.

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.

Vertical scrollbar

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.