Difference between revisions of "GUIWidgetDefinitionWML"

From The Battle for Wesnoth Wiki
(→‎Multimenu: update entry)
 
(64 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
== Widget definition ==
 
== Widget definition ==
−
 
 
This page describes the definition of all widgets in the toolkit. Every
 
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
 
widget has some parts in common, first of all; every definition has the
 
following fields.
 
following fields.
−
 
  
 
{| border="1"
 
{| border="1"
Line 28: Line 26:
 
|}
 
|}
  
 +
== Viewport ==
 +
A viewport is an special widget used to view only a part of the widget it 'holds'.
 +
 +
== Combobox ==
 +
The definition of an editable combobox.
 +
 +
The resolution for a combobox also contains the following keys:
 +
 +
{| class="wikitable"
 +
!key !!type !!default !!description
 +
|-
 +
| text_x_offset || [[GUIVariable#f_unsigned|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 || [[GUIVariable#f_unsigned|f_unsigned]] || "" || The y offset of the text in the text box.
 +
|}
 +
 +
The following states exist:
 +
* '''state_enabled''' : the combobox is enabled.
 +
* '''state_disabled''' : the combobox is disabled.
 +
* '''state_focussed''' : the combobox has the focus of the keyboard.
 +
 +
== Multiline Text ==
 +
Base class for a multiline text area.
 +
 +
The resolution for a text box also contains the following keys:
 +
{| border="1"
 +
!key
 +
!type
 +
!default
 +
!description
 +
|-
 +
| text_x_offset
 +
| [[GUIVariable#f_unsigned|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
 +
| [[GUIVariable#f_unsigned|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.
 +
 +
== Scroll Text ==
 +
Scrollable text area
  
−
== Button ==
+
A multiline text area that shows a scrollbar if the text gets too long.
 +
 
 +
{| border="1"
 +
!key
 +
!type
 +
!default
 +
!description
 +
|-
 +
| grid
 +
| [[GUIVariable#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.
 +
 
 +
{| border="1"
 +
!key
 +
!type
 +
!default
 +
!description
 +
|-
 +
| _content_grid
 +
| [[GUIVariable#grid|grid]]
 +
| mandatory
 +
| A grid which should only contain one multiline_text widget.
 +
|-
 +
| _scrollbar_grid
 +
| [[GUIVariable#grid|grid]]
 +
| mandatory
 +
| A grid for the scrollbar (Merge with listbox info.)
 +
|}
 +
 
 +
Description of necessary widgets contained inside _content_grid:
  
−
A button is a control that can be pushed to start an action or close a dialog.
+
{| border="1"
 +
!key
 +
!type
 +
!default
 +
!description
 +
|-
 +
| _text
 +
| [[GUIVariable#text_box|text_box]]
 +
| mandatory
 +
| The text_box that shows the value.
 +
|}
  
 
The following states exist:
 
The following states exist:
−
* state_enabled, the button is enabled.
+
* state_enabled - the scroll text is enabled.
−
* state_disabled, the button is disabled.
+
* state_disabled - the scroll text is disabled.
−
* state_pressed, the left mouse button is down.
+
 
−
* state_focussed, the mouse is over the button.
+
== Size Lock ==
 +
A fixed-size widget that wraps an arbitrary widget and forces it to the given size.
 +
 
 +
A size lock contains one child widget and forces it to have the specified size. This can be used, for example, when there are two list boxes in different rows of the same grid and it's desired that only one list box changes size when its contents change.
 +
 
 +
A size lock has no states.
 +
 
 +
{| border="1"
 +
!key
 +
!type
 +
!default
 +
!description
 +
|-
 +
| widget
 +
| [[GUIVariable#section|section]]
 +
| mandatory
 +
| The widget.
 +
|-
 +
| width
 +
| [[GUIVariable#f_unsigned|f_unsigned]]
 +
| mandatory
 +
| The width of the widget.
 +
|-
 +
| height
 +
| [[GUIVariable#f_unsigned|f_unsigned]]
 +
| mandatory
 +
| The height of the widget.
 +
|}
 +
 
 +
== Styled Widget ==
 +
Base class for all visible items.
 +
 
 +
All widgets placed in a cell of a grid have some values in common:
 +
{| border="1"
 +
!key
 +
!type
 +
!default
 +
!description
 +
|-
 +
| id
 +
| [[GUIVariable#string|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
 +
| [[GUIVariable#string|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
 +
| [[GUIVariable#string|string]]
 +
| ""
 +
| The linked group the control belongs to.
 +
|-
 +
| label
 +
| [[GUIVariable#t_string|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
 +
| [[GUIVariable#t_string|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
 +
| [[GUIVariable#t_string|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
 +
| [[GUIVariable#bool|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
 +
| [[GUIVariable#unsigned|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:<ul><li>0 - no border</li><li>1 - 1 pixel border</li><li>2 - floodfill the widget area</li></ul>
 +
|-
 +
| debug_border_color
 +
| [[GUIVariable#color|color]]
 +
| ""
 +
| The color of the debug border.
 +
|-
 +
| size_text
 +
| [[GUIVariable#t_string|t_string]]
 +
| ""
 +
| Sets the minimum width of the widget depending on the text in it. (Note: not implemented yet.)
 +
|}
  
 +
== Matrix ==
  
 +
== Scroll Label ==
 +
This version shows a scrollbar if the text gets too long and has some scrolling features. In general this widget is slower as the normal label so the normal label should be preferred.
  
 +
{| border="1"
 +
!key
 +
!type
 +
!default
 +
!description
 +
|-
 +
| grid
 +
| [[GUIVariable#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.
  
 +
{| border="1"
 +
!key
 +
!type
 +
!default
 +
!description
 +
|-
 +
| _content_grid
 +
| [[GUIVariable#grid|grid]]
 +
| mandatory
 +
| A grid which should only contain one label widget.
 +
|-
 +
| _scrollbar_grid
 +
| [[GUIVariable#grid|grid]]
 +
| mandatory
 +
| A grid for the scrollbar (Merge with listbox info.)
 +
|}
  
 +
The following states exist:
 +
* state_enabled - the menu_button is enabled.
 +
* state_disabled - the menu_button is disabled.
  
 +
== Menu Button ==
 +
A menu_button is a styled_widget to choose an element from a list of elements.
  
 +
When a menu_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 menu_button. The return value has a higher precedence as the one defined by the id. (Of course it's weird to give a menu_button an id and then override its return value.)
  
 +
When the menu_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.
  
 +
The following states exist:
 +
* state_enabled - the menu_button is enabled.
 +
* state_disabled - the menu_button is disabled.
 +
* state_pressed - the left mouse menu_button is down.
 +
* state_focused - the mouse is over the menu_button.
  
 +
== Password Box ==
 +
{| border="1"
 +
!key
 +
!type
 +
!default
 +
!description
 +
|-
 +
| label
 +
| [[GUIVariable#t_string|t_string]]
 +
| ""
 +
| The initial text of the password box.
 +
|}
  
 +
== Spinner ==
 +
A widget with a text_box and two button (named _prev and _next) that allows user to increase or decrease the numeric value inside the text_box. Non-numeric values are considered as zero.
  
 +
{| border="1"
 +
!key
 +
!type
 +
!default
 +
!description
 +
|-
 +
| grid
 +
| [[GUIVariable#grid|grid]]
 +
| mandatory
 +
| A grid containing the widgets for main widget.
 +
|}
  
−
== Drawing ==
+
TODO: we need one definition for a vertical scrollbar since this is the second time we use it.
  
−
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.
+
{| border="1"
 +
!key
 +
!type
 +
!default
 +
!description
 +
|-
 +
| _content_grid
 +
| [[GUIVariable#grid|grid]]
 +
| mandatory
 +
| A grid which should contain a text_box and two buttons.
 +
|}
  
−
The definition of a drawing. The widget normally has no event interaction
+
Description of necessary widgets contained inside _content_grid :
−
so only one state is defined.
+
{| border="1"
 +
!key
 +
!type
 +
!default
 +
!description
 +
|-
 +
| _text
 +
| [[GUIVariable#text_box|text_box]]
 +
| mandatory
 +
| The text_box that shows the value.
 +
|-
 +
| _prev
 +
| [[GUIVariable#button|button]]
 +
| mandatory
 +
| The previous button, clicking on it decreases value by 1.
 +
|-
 +
| _next
 +
| [[GUIVariable#button|button]]
 +
| mandatory
 +
| The next button, clicking on it increases value by 1.
 +
|}
  
 
The following states exist:
 
The following states exist:
−
* state_enabled
+
* state_enabled - the spinner is enabled.
−
    the drawing is enabled. The state is a dummy since the
+
* state_disabled - the spinner is disabled.
−
    things really drawn are placed in the window instance.
+
 
 +
== Scrollbar Panel ==
 +
Visible container to hold multiple widgets.
 +
 
 +
This widget can draw items beyond the widgets it holds and in front of them. A panel is always active so these functions return dummy values.
 +
 
 +
A panel is a container holding other elements in its grid. It uses the states as layers to draw on.
 +
 
 +
The following layers exist:
 +
* background - the background of the panel.
 +
* foreground - the foreground of the panel.
 +
 
 +
{| border="1"
 +
!key
 +
!type
 +
!default
 +
!description
 +
|-
 +
| grid
 +
| [[GUIVariable#grid|grid]]
 +
| mandatory
 +
| A grid containing the widgets for main widget.
 +
|}
  
  
 +
{| 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.
 +
|-
 +
| definition
 +
| [[GUIVariable#section|section]]
 +
| mandatory
 +
| This defines how a scrollbar_panel item looks. It must contain the grid definition for 1 row of the list.
 +
|}
  
 +
== Multimenu Button ==
 +
A multimenu button is a widget to choose one or more elements from a list of elements.
  
 +
When a multimenu 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 multimenu button. The return value has a higher precedence as the one defined by the id. (Of course it's weird to give a multimenu button an id and then override its return value.)
  
 +
When the multimenu 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.
  
 +
The following states exist:
 +
* '''state_enabled''': the multimenu_button is enabled.
 +
* '''state_disabled''': the multimenu_button is disabled.
 +
* '''state_pressed''': the left mouse multimenu_button is down.
 +
* '''state_focussed''': the mouse is over the multimenu_button.
  
 +
== Button ==
 +
A button is a control that can be pushed to start an action or close a dialog.
 +
 +
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.
  
−
== Horizontal listbox ==
+
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.
  
 +
If either the width or the height is not zero the drawing functions as a fixed size drawing. The variables available are the same as for the window resolution.
  
 +
== 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.
 
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.
 
The definition of a horizontal listbox is the same as for a normal listbox.
 +
 +
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)
 +
* toggle_button
 +
* toggle_panel
 +
 +
== Grid Listbox ==
 +
A grid listbox is a styled_widget that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version lays them out in a text-like flow instead.
 +
 +
In order to force widgets to be the same size inside a grid listbox, the widgets need to be inside a linked_group. In particular, to make the listbox actually be a grid, the linked group must synchronize both height and width. Inside the list section there are only the following widgets allowed:
 +
* grid (to nest)
 +
* toggle_button
 +
* toggle_panel
 +
 
== Image ==
 
== Image ==
−
 
 
An image shows a static image.
 
An image shows a static image.
  
Line 88: Line 448:
 
The following states exist:
 
The following states exist:
 
* state_enabled, the image is enabled.
 
* state_enabled, the image is enabled.
−
 
−
 
−
 
−
 
−
 
−
 
−
 
  
 
== Label ==
 
== Label ==
−
 
 
A label displays a text, the text can be wrapped but no scrollbars are provided.
 
A label displays a text, the text can be wrapped but no scrollbars are provided.
  
Line 105: Line 457:
  
 
Note: The above is outdated, if "link_aware" is enabled then there is interaction.
 
Note: The above is outdated, if "link_aware" is enabled then there is interaction.
−
 
  
 
The following states exist:
 
The following states exist:
 
* state_enabled, the label is enabled.
 
* state_enabled, the label is enabled.
 
* state_disabled, the label is disabled.
 
* state_disabled, the label is disabled.
−
 
−
 
  
 
{| border="1"
 
{| border="1"
Line 118: Line 467:
 
!default
 
!default
 
!description
 
!description
−
|-
 
−
| link_aware
 
−
| [[GUIVariable#f_bool|f_bool]]
 
−
| false
 
−
| Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
 
 
|-
 
|-
 
| link_color
 
| link_color
Line 129: Line 473:
 
| The color to render links with. This string will be used verbatim in pango markup for each link.
 
| The color to render links with. This string will be used verbatim in pango markup for each link.
 
|}
 
|}
−
 
−
 
−
 
−
 
−
 
−
 
−
 
  
 
== Listbox ==
 
== 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.
 
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.
  
Line 210: Line 546:
 
* button
 
* button
 
* repeating_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:
 
The following states exist:
 
* state_enabled, the listbox is enabled.
 
* state_enabled, the listbox is enabled.
 
* state_disabled, the listbox is disabled.
 
* state_disabled, the listbox is disabled.
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
== Listbox ==
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
  
 
== Minimap ==
 
== 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 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:
 
The following states exist:
 
* state_enabled, the minimap is enabled.
 
* state_enabled, the minimap is enabled.
−
 
−
 
−
 
−
 
−
 
−
 
−
 
  
 
== Multi page ==
 
== 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.
 
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.
−
 
  
 
{| border="1"
 
{| border="1"
Line 271: Line 572:
 
|}
 
|}
  
 +
A multipage has no states.
  
−
 
−
 
−
A multipage has no states.
 
 
== Panel ==
 
== 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 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
 
A panel is always enabled and can't be disabled. Instead it uses the
Line 315: Line 611:
 
* background, the background of the panel.
 
* background, the background of the panel.
 
* foreground, the foreground of the panel.
 
* foreground, the foreground of the panel.
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
  
 
== Progress bar ==
 
== Progress bar ==
−
 
 
A progress bar shows the progress of a certain object.
 
A progress bar shows the progress of a certain object.
  
Line 333: Line 620:
 
The following states exist:
 
The following states exist:
 
* state_enabled, the progress bar is enabled.
 
* state_enabled, the progress bar is enabled.
−
 
−
 
−
 
−
 
−
 
−
 
−
 
  
 
== 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.
  
Line 350: Line 629:
 
* state_pressed, the left mouse repeating_button is down.
 
* state_pressed, the left mouse repeating_button is down.
 
* state_focussed, the mouse is over the repeating_button.
 
* state_focussed, the mouse is over the repeating_button.
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
  
 
== Scroll label ==
 
== 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.
 
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
 
This widget is slower as a normal label widget so only use this widget
 
when the scrollbar is required (or expected to become required).
 
when the scrollbar is required (or expected to become required).
−
 
  
 
{| border="1"
 
{| border="1"
Line 404: Line 667:
 
| A grid for the scrollbar (Merge with listbox info.)
 
| A grid for the scrollbar (Merge with listbox info.)
 
|}
 
|}
−
 
−
 
−
 
  
 
The following states exist:
 
The following states exist:
 
* state_enabled, the scroll label is enabled.
 
* state_enabled, the scroll label is enabled.
 
* state_disabled, the scroll label is disabled.
 
* state_disabled, the scroll label is disabled.
−
 
−
 
−
 
−
 
−
 
−
 
  
 
== Scrollbar panel ==
 
== Scrollbar panel ==
−
 
−
 
−
 
−
 
 
The definition of a panel with scrollbars. A panel is a container holding
 
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
 
other elements in its grid. A panel is always enabled and can't be
Line 441: Line 691:
 
* background, the background of the panel.
 
* background, the background of the panel.
 
* foreground, the foreground of the panel.
 
* foreground, the foreground of the panel.
−
 
−
 
−
 
  
 
== Slider ==
 
== Slider ==
−
 
 
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"
 
{| border="1"
Line 482: Line 725:
 
* state_enabled, the slider is enabled.
 
* state_enabled, the slider is enabled.
 
* state_disabled, the slider is disabled.
 
* state_disabled, the slider is disabled.
−
* state_pressed, the left mouse button is down on the positioner of the
+
* state_pressed, the left mouse button is down on the positioner of the slider.
−
  slider.
 
 
* state_focussed, the mouse is over the positioner of the slider.
 
* state_focussed, the mouse is over the positioner of the slider.
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
  
 
== Spacer ==
 
== Spacer ==
 +
An empty widget to either fill in a widget since no empty items are allowed or to reserve a fixed space. Since we're a kind of dummy class we're always active, our drawing does nothing.
  
−
A spacer is a dummy item to either fill in a widget since no empty items are allowed or to reserve a fixed space.
+
Since every grid cell needs a widget this is a blank widget. This widget can also be used to 'force' sizes - if either the width or the height is non-zero the spacer functions as a fixed size spacer.
−
 
 
−
A spacer has no states so nothing to load.
 
−
 
 
−
 
 
  
 +
{| border="1"
 +
!key
 +
!type
 +
!default
 +
!description
 +
|-
 +
| width
 +
| [[GUIVariable#f_unsigned|f_unsigned]]
 +
| 0
 +
| The width of the spacer.
 +
|-
 +
| height
 +
| [[GUIVariable#f_unsigned|f_unsigned]]
 +
| 0
 +
| The height of the spacer.
 +
|}
  
 
== Stacked widget ==
 
== Stacked widget ==
−
 
 
A stacked widget holds several widgets on top of each other. This can be used
 
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
 
for various effects; add an optional overlay to an image, stack it with a
Line 514: Line 758:
 
A stacked widget has no states.
 
A stacked widget has no states.
  
 +
== Tab Container ==
 +
A tabbed container that holds multiple pages, called tabs. The user can show any of those pages by clicking on a list containing names (optionally images) of the available tabs.
  
−
 
+
A tab container has no states.
−
 
 
−
 
 
−
 
 
  
 
== Text box ==
 
== Text box ==
−
 
 
The definition of a text box.
 
The definition of a text box.
−
 
−
 
  
 
The resolution for a text box also contains the following keys:
 
The resolution for a text box also contains the following keys:
Line 549: Line 789:
 
* state_disabled, the text box is disabled.
 
* state_disabled, the text box is disabled.
 
* state_focussed, the text box has the focus of the keyboard.
 
* state_focussed, the text box has the focus of the keyboard.
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
  
 
== Toggle button ==
 
== Toggle button ==
 +
The definition of a 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:
 
The following states exist:
−
* state_enabled, the button is enabled and not selected.
+
* state_enabled, the panel is enabled and not selected.
−
* state_disabled, the button is disabled and not selected.
+
* state_disabled, the panel is disabled and not selected.
−
* state_focussed, the mouse is over the button and not selected.
+
* state_focussed, the mouse is over the panel and not selected.
−
 
 
−
* state_enabled_selected, the button is enabled and selected.
 
−
* state_disabled_selected, the button is disabled and selected.
 
−
* state_focussed_selected, the mouse is over the button and 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.
  
 
== Toggle panel ==
 
== 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 definition of a toggle panel. A toggle panel is like a toggle button, but
+
The difference between a grid and a panel is that it's possible to define how a panel looks.
−
instead of being a button it's a panel. This means it can hold multiple child
+
A grid in an invisible container to just hold the items.
−
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:
 
The resolution for a toggle panel also contains the following keys:
Line 633: Line 852:
 
* state_disabled_selected, the panel is disabled and selected.
 
* state_disabled_selected, the panel is disabled and selected.
 
* state_focussed_selected, the mouse is over the panel and selected.
 
* state_focussed_selected, the mouse is over the panel and selected.
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
  
 
== Tree view ==
 
== 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.
 
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:
 
The following states exist:
 
* state_enabled, the listbox is enabled.
 
* state_enabled, the listbox is enabled.
 
* state_disabled, the listbox is disabled.
 
* state_disabled, the listbox is disabled.
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
  
 
== Horizontal scrollbar ==
 
== Horizontal scrollbar ==
−
 
 
A horizontal scrollbar is a widget that shows a horizontal scrollbar. This widget is most of the time used in a container to control the scrolling of its contents.
 
A horizontal scrollbar 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:
 
The resolution for a horizontal scrollbar also contains the following keys:
Line 705: Line 895:
 
* state_enabled, the horizontal scrollbar is enabled.
 
* state_enabled, the horizontal scrollbar is enabled.
 
* state_disabled, the horizontal scrollbar is disabled.
 
* state_disabled, the horizontal scrollbar is disabled.
−
* state_pressed, the left mouse button is down on the positioner of the
+
* state_pressed, the left mouse button is down on the positioner of the horizontal scrollbar.
−
  horizontal scrollbar.
+
* state_focussed, the mouse is over the positioner of the horizontal scrollbar.
−
* state_focussed, the mouse is over the positioner of the horizontal
 
−
  scrollbar.
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
  
 
== Vertical scrollbar ==
 
== Vertical scrollbar ==
−
 
 
The definition of a vertical scrollbar. This class is most of the time not
 
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.
 
used directly. Instead it's used to build other items with scrollbars.
−
 
−
 
  
 
The resolution for a vertical scrollbar also contains the following keys:
 
The resolution for a vertical scrollbar also contains the following keys:
Line 758: Line 933:
 
* state_enabled, the vertical scrollbar is enabled.
 
* state_enabled, the vertical scrollbar is enabled.
 
* state_disabled, the vertical scrollbar is disabled.
 
* state_disabled, the vertical scrollbar is disabled.
−
* state_pressed, the left mouse button is down on the positioner of the
+
* state_pressed, the left mouse button is down on the positioner of the vertical scrollbar.
−
  vertical scrollbar.
 
 
* state_focussed, the mouse is over the positioner of the vertical scrollbar.
 
* state_focussed, the mouse is over the positioner of the vertical scrollbar.
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
−
 
  
 
== Window ==
 
== Window ==
−
 
+
Base class of top level items, the only item which needs to store the final canvases to draw on. The definition of a window. A window is a kind of panel see the panel for which fields exist
−
The definition of a window. A window is a kind of panel see the panel for
 
−
which fields exist
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
−
 
 
  
 
[[Category: WML Reference]]
 
[[Category: WML Reference]]
 
[[Category: GUI WML Reference]]
 
[[Category: GUI WML Reference]]

Latest revision as of 09:59, 7 May 2024

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.

Viewport

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

Combobox

The definition of an editable combobox.

The resolution for a combobox 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 combobox is enabled.
  • state_disabled : the combobox is disabled.
  • state_focussed : the combobox has the focus of the keyboard.

Multiline Text

Base class for a multiline text area.

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.

Scroll Text

Scrollable text area

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

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.

key type default description
_content_grid grid mandatory A grid which should only contain one multiline_text widget.
_scrollbar_grid grid mandatory A grid for the scrollbar (Merge with listbox info.)

Description of necessary widgets contained inside _content_grid:

key type default description
_text text_box mandatory The text_box that shows the value.

The following states exist:

  • state_enabled - the scroll text is enabled.
  • state_disabled - the scroll text is disabled.

Size Lock

A fixed-size widget that wraps an arbitrary widget and forces it to the given size.

A size lock contains one child widget and forces it to have the specified size. This can be used, for example, when there are two list boxes in different rows of the same grid and it's desired that only one list box changes size when its contents change.

A size lock has no states.

key type default description
widget section mandatory The widget.
width f_unsigned mandatory The width of the widget.
height f_unsigned mandatory The height of the widget.

Styled Widget

Base class for all visible items.

All widgets placed in a cell of a grid 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.)

Matrix

Scroll Label

This version shows a scrollbar if the text gets too long and has some scrolling features. In general this widget is slower as the normal label so the normal label should be preferred.

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.

key type default description
_content_grid grid mandatory A grid which should only contain one label widget.
_scrollbar_grid grid mandatory A grid for the scrollbar (Merge with listbox info.)

The following states exist:

  • state_enabled - the menu_button is enabled.
  • state_disabled - the menu_button is disabled.

Menu Button

A menu_button is a styled_widget to choose an element from a list of elements.

When a menu_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 menu_button. The return value has a higher precedence as the one defined by the id. (Of course it's weird to give a menu_button an id and then override its return value.)

When the menu_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.

The following states exist:

  • state_enabled - the menu_button is enabled.
  • state_disabled - the menu_button is disabled.
  • state_pressed - the left mouse menu_button is down.
  • state_focused - the mouse is over the menu_button.

Password Box

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

Spinner

A widget with a text_box and two button (named _prev and _next) that allows user to increase or decrease the numeric value inside the text_box. Non-numeric values are considered as zero.

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.

key type default description
_content_grid grid mandatory A grid which should contain a text_box and two buttons.

Description of necessary widgets contained inside _content_grid :

key type default description
_text text_box mandatory The text_box that shows the value.
_prev button mandatory The previous button, clicking on it decreases value by 1.
_next button mandatory The next button, clicking on it increases value by 1.

The following states exist:

  • state_enabled - the spinner is enabled.
  • state_disabled - the spinner is disabled.

Scrollbar Panel

Visible container to hold multiple widgets.

This widget can draw items beyond the widgets it holds and in front of them. A panel is always active so these functions return dummy values.

A panel is a container holding other elements in its grid. It uses the states as layers to draw on.

The following layers exist:

  • background - the background of the panel.
  • foreground - the foreground of the panel.
key type default description
grid grid mandatory A grid containing the widgets for main widget.


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.

Multimenu Button

A multimenu button is a widget to choose one or more elements from a list of elements.

When a multimenu 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 multimenu button. The return value has a higher precedence as the one defined by the id. (Of course it's weird to give a multimenu button an id and then override its return value.)

When the multimenu 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.

The following states exist:

  • state_enabled: the multimenu_button is enabled.
  • state_disabled: the multimenu_button is disabled.
  • state_pressed: the left mouse multimenu_button is down.
  • state_focussed: the mouse is over the multimenu_button.

Button

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

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.

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.

If either the width or the height is not zero the drawing functions as a fixed size drawing. The variables available are the same as for the window resolution.

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.

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)
  • toggle_button
  • toggle_panel

Grid Listbox

A grid listbox is a styled_widget that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version lays them out in a text-like flow instead.

In order to force widgets to be the same size inside a grid listbox, the widgets need to be inside a linked_group. In particular, to make the listbox actually be a grid, the linked group must synchronize both height and width. Inside the list section there are only the following widgets allowed:

  • grid (to nest)
  • toggle_button
  • toggle_panel

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

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

An empty widget to either fill in a widget since no empty items are allowed or to reserve a fixed space. Since we're a kind of dummy class we're always active, our drawing does nothing.

Since every grid cell needs a widget this is a blank widget. This widget can also be used to 'force' sizes - 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.

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.

Tab Container

A tabbed container that holds multiple pages, called tabs. The user can show any of those pages by clicking on a list containing names (optionally images) of the available tabs.

A tab container 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.

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.

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 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

Base class of top level items, the only item which needs to store the final canvases to draw on. The definition of a window. A window is a kind of panel see the panel for which fields exist

Retrieved from "https://wiki.wesnoth.org/index.php?title=GUIWidgetDefinitionWML&oldid=73009"
This page was last edited on 7 May 2024, at 09:59.