Difference between revisions of "GUIWidgetInstanceWML"

From The Battle for Wesnoth Wiki
(→‎Label: The previous wording made it sound like the line length would be limited to "approximately" the specified number of characters, which is not true at all.)
 
(39 intermediate revisions by 5 users not shown)
Line 6: Line 6:
 
== Widget ==
 
== Widget ==
 
All widgets placed in the cell have some values in common:
 
All widgets placed in the cell have some values in common:
−
{| border="1"
+
{| class="wikitable"
 
!key
 
!key
 
!type
 
!type
Line 51: Line 51:
 
| 0
 
| 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:  
 
| 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.  
+
* '''0:''' no border.  
−
* 1 1 pixel border.  
+
* '''1:''' 1 pixel border.  
−
* 2 floodfill the widget area.
+
* '''2:''' floodfill the widget area.
 
|-
 
|-
 
| debug_border_color
 
| debug_border_color
Line 66: Line 66:
 
|}
 
|}
  
−
== Toggle button ==
+
== Button ==
−
Variables:
+
A button is a control that can be pushed to start an action or close a dialog.
−
{| border="1"
+
 
 +
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:
 +
{| class="wikitable"
 
!key
 
!key
 
!type
 
!type
 
!default
 
!default
 
!description
 
!description
−
|-
 
−
| grid
 
−
| [[GUIVariable#grid|grid]]
 
−
| mandatory
 
−
| Defines the grid with the widgets to place on the panel.
 
 
|-
 
|-
 
| return_value_id
 
| return_value_id
Line 90: Line 98:
 
|}
 
|}
  
−
 
+
Supported values for return_value_id:
−
== Grid Listbox ==
+
{| class="wikitable"
−
List with the listbox specific variables:
+
!string
−
{| border="1"
+
!value
−
!ID (return value)
+
!description
−
!Type
 
−
!Mandatory
 
−
!Description
 
−
|-
 
−
| vertical_scrollbar_mode
 
−
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
 
−
| initial_auto
 
−
| Determines whether or not to show the scrollbar.
 
−
|-
 
−
| horizontal_scrollbar_mode
 
−
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
 
−
| initial_auto
 
−
| Determines whether or not to show the scrollbar.
 
−
|-
 
−
| header
 
−
| [[GUIToolkitWML#grid|grid]]
 
−
| []
 
−
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
 
−
|-
 
−
| footer
 
−
| [[GUIToolkitWML#grid|grid]]
 
−
| []
 
−
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
 
 
|-
 
|-
−
| list_definition
+
|"ok"||-1||Equivalent to closing the dialog by pressing the Enter key
−
| [[GUIToolkitWML#section|section]]
 
−
| mandatory
 
−
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
 
 
|-
 
|-
−
| list_data
+
|"cancel"||-2||Equivalent to closing the dialog by pressing the Esc key
−
| [[GUIToolkitWML#section|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
+
|"quit"||-2||An alias for cancel
−
| [[GUIToolkitWML#bool|bool]]
 
−
| true
 
−
| If false, less than one row can be selected.
 
 
|-
 
|-
−
| has_maximum
+
|""||N/A||Clears any previously set return_value_id
−
| [[GUIToolkitWML#bool|bool]]
 
−
| true
 
−
| If false, more than one row can be selected.
 
 
|}
 
|}
  
 +
== Combobox ==
 +
[[File:Combobox.png|frame|right|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.
  
−
== Multimenu ==
+
{| class="wikitable"
−
List with the multimenu_button specific variables:
 
−
{| border="1"
 
−
!key
 
−
!type
 
−
!default
 
−
!description
 
 
|-
 
|-
−
| return_value_id
+
! key !! type !! default !! description
−
| [[GUIVariable#string|string]]
 
−
| ""
 
−
| The return value id.
 
 
|-
 
|-
−
| return_value
+
| label || [[GUIVariable#string|string]] || "" || The text of the combobox
−
| [[GUIVariable#int|int]]
 
−
| 0
 
−
| The return value.
 
 
|-
 
|-
−
| maximum_shown
+
| max_input_length || [[GUIVariable#int|int]] || 0 || Maximum length of text in characters that can be entered into the combobox
−
| [[GUIVariable#int|int]]
 
−
| -1
 
−
| The maximum number of currently selected values to list on the button.
 
−
|}
 
−
 
 
−
== Menu Button ==
 
−
List with the menu_button specific variables:
 
−
{| border="1"
 
−
!key
 
−
!type
 
−
!default
 
−
!description
 
 
|-
 
|-
−
| return_value_id
+
| hint_text || [[GUIVariable#string|string]] || "" || Text that is shown in the background when there is no input
−
| [[GUIVariable#string|string]]
 
−
| ""
 
−
| The return value id.
 
 
|-
 
|-
−
| return_value
+
| hint_image || [[GUIVariable#string|string]] || "" || Image that is shown in the background when there is no input
−
| [[GUIVariable#int|int]]
 
−
| 0
 
−
| The return value.
 
−
|}
 
−
 
 
−
== Scroll Text ==
 
−
Scrollable text area
 
−
 
 
−
A multiline text area that shows a scrollbar if the text gets too long.
 
  
−
List with the scrollbar container specific variables:
 
−
{| border="1"
 
−
!key
 
−
!type
 
−
!default
 
−
!description
 
−
|-
 
−
| vertical_scrollbar_mode
 
−
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
 
−
| initial_auto
 
−
| Determines whether or not to show the scrollbar.
 
−
|-
 
−
| horizontal_scrollbar_mode
 
−
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
 
−
| initial_auto
 
−
| Determines whether or not to show the scrollbar.
 
−
|-
 
−
| editable
 
−
| [[GUIVariable#bool|bool]]
 
−
| "true"
 
−
| If the contents of included multiline_text can be edited.
 
 
|}
 
|}
  
−
== Multiline Text ==
+
=== Subtag [option] ===
−
Base class for a multiline text area.
+
Specifies the initial list of options to be shown in the <code>combobox</code>.
  
−
The following variables exist:
+
{| class = "wikitable"
−
{| border="1"
+
!key !!type !!default !!description
−
!key
 
−
!type
 
−
!default
 
−
!description
 
 
|-
 
|-
−
| label
+
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
−
| [[GUIVariable#t_string|t_string]]
 
−
| ""
 
−
| The initial text of the text box.
 
 
|-
 
|-
−
| history
+
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
−
| [[GUIVariable#string|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
 
−
| [[GUIVariable#bool|bool]]
 
−
| "true"
 
−
| If the contents of the text box can be edited.
 
−
|}
 
−
 
 
−
== 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:
 
−
{| border="1"
 
−
!key
 
−
!type
 
−
!default
 
−
!description
 
 
|-
 
|-
−
| return_value_id
+
| icon || [[GUIVariable#string|string]] || "" || WML path to the icon to be shown alongside the text in this option, if any.
−
| [[GUIVariable#string|string]]
 
−
| ""
 
−
| The return value id.
 
 
|-
 
|-
−
| return_value
+
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
−
| [[GUIVariable#int|int]]
 
−
| 0
 
−
| The return value.
 
 
|}
 
|}
  
−
== Spacer ==
+
== 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.
 
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.
  
Line 276: Line 152:
 
fixed size drawing.
 
fixed size drawing.
  
−
{| border="1"
+
{| class="wikitable"
 
!key
 
!key
 
!type
 
!type
Line 301: Line 177:
 
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
 
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
 
items.
 
items.
 +
 +
== Grid Listbox ==
 +
List with the listbox specific variables:
 +
{| class="wikitable"
 +
!ID (return value)
 +
!Type
 +
!Mandatory
 +
!Description
 +
|-
 +
| vertical_scrollbar_mode
 +
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
 +
| initial_auto
 +
| Determines whether or not to show the scrollbar.
 +
|-
 +
| horizontal_scrollbar_mode
 +
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
 +
| initial_auto
 +
| Determines whether or not to show the scrollbar.
 +
|-
 +
| header
 +
| [[GUIToolkitWML#grid|grid]]
 +
| []
 +
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
 +
|-
 +
| footer
 +
| [[GUIToolkitWML#grid|grid]]
 +
| []
 +
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
 +
|-
 +
| list_definition
 +
| [[GUIToolkitWML#section|section]]
 +
| mandatory
 +
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
 +
|-
 +
| list_data
 +
| [[GUIToolkitWML#section|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
 +
| [[GUIToolkitWML#bool|bool]]
 +
| true
 +
| If false, less than one row can be selected.
 +
|-
 +
| has_maximum
 +
| [[GUIToolkitWML#bool|bool]]
 +
| true
 +
| If false, more than one row can be selected.
 +
|}
  
 
== Horizontal listbox ==
 
== Horizontal listbox ==
Line 306: Line 231:
  
 
List with the horizontal listbox specific variables:
 
List with the horizontal listbox specific variables:
−
{| border="1"
+
{| class="wikitable"
 
!ID (return value)
 
!ID (return value)
 
!Type
 
!Type
Line 363: 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. The path is a standard WML path, i.e., <code>label="units/konrad.png"</code> or <code>label="~add-ons/MyAddon/image/test.png"</code>.
  
−
An image has no extra fields.
+
It has no other extra fields.
  
 
== Label ==
 
== Label ==
−
A label displays a text, the text can be wrapped but no scrollbars are provided.
+
A label displays text provided via the '''[[GUIWidgetInstanceWML#Widget|label]]''' key that can be wrapped but no scrollbars are provided. For a version with scrollbars, see the [[GUIWidgetInstanceWML#Scroll_Label|Scroll Label]] widget.
 +
 
 +
[[File:Title Label.png|frame|right|A Label with definition "title"]]
  
 
List with the label specific variables:
 
List with the label specific variables:
−
{| border="1"
+
{| class="wikitable"
−
!key
+
!key !!type !!default !!description
−
!type
 
−
!default
 
−
!description
 
 
|-
 
|-
−
| wrap
+
| wrap || [[GUIVariable#bool|bool]] || false || Is wrapping enabled for the label.
−
| [[GUIVariable#bool|bool]]
 
−
| false
 
−
| Is wrapping enabled for the label.
 
 
|-
 
|-
−
| characters_per_line
+
| characters_per_line || [[GUIVariable#unsigned|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.  
−
| [[GUIVariable#unsigned|unsigned]]
+
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.
−
| 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
+
| text_alignment || [[GUIVariable#h_align|h_align]] || left || The way the text is aligned inside the canvas.
−
| [[GUIVariable#h_align|h_align]]
 
−
| left
 
−
| The way the text is aligned inside the canvas.
 
 
|-
 
|-
−
| can_shrink
+
| can_shrink || [[GUIVariable#bool|bool]] || false || Whether the label can shrink past its optimal size.
−
| [[GUIVariable#bool|bool]]
 
−
| false
 
−
| Whether the label can shrink past its optimal size.
 
 
|-
 
|-
−
| link_aware
+
| link_aware || [[GUIVariable#bool|bool]] || false || Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
−
| [[GUIVariable#bool|bool]]
 
−
| false
 
−
| Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
 
 
|}
 
|}
  
Line 407: Line 317:
  
 
List with the listbox specific variables:
 
List with the listbox specific variables:
−
{| border="1"
+
{| class="wikitable"
 
!key
 
!key
 
!type
 
!type
Line 465: Line 375:
 
== Matrix ==
 
== Matrix ==
 
List with the matrix specific variables:
 
List with the matrix specific variables:
−
{| border="1"
+
{| class="wikitable"
 
!key
 
!key
 
!type
 
!type
Line 480: Line 390:
 
| initial_auto
 
| initial_auto
 
| Determines whether or not to show the scrollbar.
 
| Determines whether or not to show the scrollbar.
 +
|}
 +
 +
== Menu Button ==
 +
[[File:Menu Button.png|thumb|left|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.
 +
{| class="wikitable"
 +
!key
 +
!type
 +
!default
 +
!description
 +
|-
 +
| return_value_id
 +
| [[GUIVariable#string|string]]
 +
| ""
 +
| The return value id.
 +
|-
 +
| return_value
 +
| [[GUIVariable#int|int]]
 +
| 0
 +
| The return value.
 +
|}
 +
 +
=== Subtag [option] ===
 +
Specifies the initial list of options to be shown in the <code>menu_button</code>.
 +
 +
{| class = "wikitable"
 +
!key !!type !!default !!description
 +
|-
 +
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
 +
|-
 +
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
 +
|-
 +
| icon || [[GUIVariable#string|string]] || "" || WML path to the icon to be shown alongside the text in this option, if any.
 +
|-
 +
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
 
|}
 
|}
  
Line 486: Line 431:
  
 
A minimap has no extra fields.
 
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 [[GUIWidgetInstanceWML#Scroll_Text|scroll_text]] widget instead.
 +
 +
The following variables exist:
 +
{| class="wikitable"
 +
!key
 +
!type
 +
!default
 +
!description
 +
|-
 +
| label
 +
| [[GUIVariable#t_string|t_string]]
 +
| ""
 +
| The initial text of the text box.
 +
|-
 +
| history
 +
| [[GUIVariable#string|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
 +
| [[GUIVariable#bool|bool]]
 +
| "true"
 +
| If the contents of the text box can be edited.
 +
|}
 +
 +
== Multimenu Button ==
 +
[[File:Multimenu Button.png|thumb|right|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:
 +
{| class="wikitable"
 +
!key !!type !!default !!description
 +
|-
 +
| return_value_id || [[GUIVariable#string|string]] || "" || The return value id.
 +
|-
 +
| return_value || [[GUIVariable#int|int]] || 0 || The return value.
 +
|-
 +
| maximum_shown || [[GUIVariable#int|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 <code>multimenu_button</code>.
 +
 +
{| class = "wikitable"
 +
!key !!type !!default !!description
 +
|-
 +
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
 +
|-
 +
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
 +
|-
 +
| checkbox || [[GUIVariable#bool|bool]] || "" || Whether the checkbox alongside this option is selected or not.
 +
|-
 +
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
 +
|}
  
 
== Multi page ==
 
== Multi page ==
Line 491: Line 492:
  
 
List with the multi page specific variables:
 
List with the multi page specific variables:
−
{| border="1"
+
{| class="wikitable"
 
!key
 
!key
 
!type
 
!type
Line 511: Line 512:
 
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 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.
  
−
{| border="1"
+
{| class="wikitable"
 
!key
 
!key
 
!type
 
!type
Line 524: Line 525:
  
 
== Password box ==
 
== Password box ==
−
{| border="1"
+
{| class="wikitable"
 
!key
 
!key
 
!type
 
!type
Line 543: Line 544:
 
== Repeating button ==
 
== 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.
 
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.
 +
 +
{| class="wikitable"
 +
!key !!type !!default !!description
 +
|-
 +
| text_alignment || [[GUIVariable#h_align|h_align]] || left || The way the text is aligned inside the canvas.
 +
|-
 +
| width || [[GUIVariable#int|int]] || 500 || Width of its internal formatted content. Text will wrap beyond this width.
 +
|-
 +
| link_aware || [[GUIVariable#bool|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 ==
 
== Scroll label ==
Line 548: Line 562:
  
 
List with the scroll label specific variables:
 
List with the scroll label specific variables:
−
{| border="1"
+
{| class="wikitable"
 
!key
 
!key
 
!type
 
!type
Line 569: Line 583:
  
 
List with the scrollbar_panel specific variables:
 
List with the scrollbar_panel specific variables:
−
{| border="1"
+
{| class="wikitable"
 
!key
 
!key
 
!type
 
!type
Line 597: Line 611:
 
fixed size spacer.
 
fixed size spacer.
  
−
{| border="1"
+
{| class="wikitable"
−
!key
+
!key !!type !!default !!description
−
!type
 
−
!default
 
−
!description
 
 
|-
 
|-
−
| width
+
| width || [[GUIVariable#f_unsigned|f_unsigned]] || 0 || The width of the spacer.
−
| [[GUIVariable#f_unsigned|f_unsigned]]
 
−
| 0
 
−
| The width of the spacer.
 
 
|-
 
|-
−
| height
+
| height || [[GUIVariable#f_unsigned|f_unsigned]] || 0 || The height of the spacer.
−
| [[GUIVariable#f_unsigned|f_unsigned]]
 
−
| 0
 
−
| The height of the spacer.
 
 
|}
 
|}
  
Line 617: Line 622:
 
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
 
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
 
items.
 
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 <code>[tab]</code> tags inside it, each defining a tab's name, image (if any) and the contents of the tag, specified by the <code>[data]</code> tag inside the <code>[tab]</code> tag.
 +
 +
=== Subtag [tab] ===
 +
 +
{| class = "wikitable"
 +
!key !!type !!default !!description
 +
|-
 +
| name || [[GUIVariable#t_string|t_string]] || "" || Name of the tab
 +
|-
 +
| image || [[GUIVariable#string|string]] || "" || Image for the tab to be shown alongside the name, if any
 +
|-
 +
| [data] || [[GUIVariable#grid|grid]] || empty grid || This subtag contains a grid that defines the contents for this tab.
 +
|}
  
 
== Text box ==
 
== Text box ==
−
{| border="1"
+
A single line text entry widget.
−
!key
+
 
−
!type
+
[[File:Text Box.png|frame|right|A Text Box]]
−
!default
+
 
−
!description
+
{| class = "wikitable"
 +
!key !!type !!default !!description
 +
|-
 +
| label || [[GUIVariable#t_string|t_string]] || "" || The initial text of the text box.
 +
|-
 +
| history || [[GUIVariable#string|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 || [[GUIVariable#int|int]] || 0 || Maximum length of text in characters that can be entered into the combobox
 +
|-
 +
| hint_text || [[GUIVariable#string|string]] || "" || Text that is shown in the background when there is no input
 
|-
 
|-
−
| label
+
| hint_image || [[GUIVariable#string|string]] || "" || Image that is shown in the background when there is no input
−
| [[GUIVariable#t_string|t_string]]
 
−
| ""
 
−
| The initial text of the text box.
 
 
|-
 
|-
−
| history
+
| editable || [[GUIVariable#bool|bool]] || "true" || If the contents of the text box can be edited.
−
| [[GUIVariable#string|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.
 
 
|}
 
|}
  
Line 643: Line 669:
 
its own grid.
 
its own grid.
  
−
{| border="1"
+
Variables:
 +
{| class="wikitable"
 
!key
 
!key
 
!type
 
!type
Line 669: Line 696:
  
 
List with the tree view specific variables:
 
List with the tree view specific variables:
−
{| border="1"
+
{| class="wikitable"
 
!key
 
!key
 
!type
 
!type
Line 691: Line 718:
 
|-
 
|-
 
| node
 
| node
−
| [[GUIVariable#section|section]]
+
| [[GUIVariable#unsigned|unsigned]]
 
| mandatory
 
| mandatory
 
| The tree view can contain multiple node sections. This part needs more documentation.
 
| The tree view can contain multiple node sections. This part needs more documentation.
−
|}
 
−
 
−
{| border="1"
 
−
!key
 
−
!type
 
−
!default
 
−
!description
 
 
|-
 
|-
 
| id
 
| id
−
| [[GUIVariable#string|string]]
+
| [[GUIVariable#unsigned|unsigned]]
 
| ""
 
| ""
−
|
+
| .
−
|}
 
−
 
 
−
{| border="1"
 
−
!key
 
−
!type
 
−
!default
 
−
!description
 
 
|-
 
|-
 
| return_value_id
 
| return_value_id
−
| [[GUIVariable#string|string]]
+
| [[GUIVariable#unsigned|unsigned]]
 
| ""
 
| ""
−
|
+
| .
 
|}
 
|}
  
Line 729: Line 742:
  
 
List with the viewport specific variables:
 
List with the viewport specific variables:
−
{| border="1"
+
{| class="wikitable"
 
!key
 
!key
 
!type
 
!type
Line 750: Line 763:
 
| The definition of a new item.
 
| 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:
 +
{| class="wikitable"
 +
!key
 +
!type
 +
!default
 +
!description
 +
|-
 +
| vertical_scrollbar_mode
 +
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
 +
| initial_auto
 +
| Determines whether or not to show the scrollbar.
 +
|-
 +
| horizontal_scrollbar_mode
 +
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
 +
| initial_auto
 +
| Determines whether or not to show the scrollbar.
 +
|-
 +
| editable
 +
| [[GUIVariable#bool|bool]]
 +
| "true"
 +
| If the contents of this scroll_text can be edited.
 +
|}
 +
  
 
== Slider ==
 
== Slider ==
Line 755: Line 795:
 
A slider is a control that can select a value by moving a grip on a groove.
 
A slider is a control that can select a value by moving a grip on a groove.
  
−
{| border="1"
+
{| class="wikitable"
 
!key
 
!key
 
!type
 
!type
Line 796: Line 836:
 
| 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.
 
| 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:
 +
{| class="wikitable"
 +
!key
 +
!type
 +
!default
 +
!description
 +
|-
 +
| grid
 +
| [[GUIVariable#grid|grid]]
 +
| mandatory
 +
| Defines the grid with the widgets to place on the panel.
 +
|-
 +
| return_value_id
 +
| [[GUIVariable#string|string]]
 +
| ""
 +
| The return value id.
 +
|-
 +
| return_value
 +
| [[GUIVariable#int|int]]
 +
| 0
 +
| The return value.
 +
|}
 +
  
 
[[Category: WML Reference]]
 
[[Category: WML Reference]]
 
[[Category: GUI WML Reference]]
 
[[Category: GUI WML Reference]]

Latest revision as of 05:23, 12 November 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. 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.

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.
Retrieved from "https://wiki.wesnoth.org/index.php?title=GUIWidgetInstanceWML&oldid=73980"
This page was last edited on 12 November 2024, at 05:23.