The Battle for Wesnoth  1.15.10+dev
Classes
GUIWidgetWML

In various parts of the GUI there are several variables types in use. More...

Classes

class  gui2::drawing
 A drawing is widget with a fixed size and gives access to the canvas of the widget in the window instance. More...
 
class  gui2::horizontal_scrollbar
 A horizontal scrollbar is a widget that shows a horizontal scrollbar. More...
 
class  gui2::image
 An image shows a static image. More...
 
class  gui2::label
 A label displays a text, the text can be wrapped but no scrollbars are provided. More...
 
struct  gui2::implementation::builder_listbox
 A listbox is a control that holds several items of the same type. More...
 
struct  gui2::implementation::builder_horizontal_listbox
 A horizontal listbox is a control that holds several items of the same type. More...
 
struct  gui2::implementation::builder_grid_listbox
 A grid listbox is a styled_widget that holds several items of the same type. More...
 
class  gui2::matrix
 List with the matrix specific variables:

Key Type Default Description
vertical_scrollbar_mode scrollbar_modeinitial_autoDetermines whether or not to show the scrollbar.
More...
 
class  gui2::menu_button
 A menu_button is a styled_widget to choose an element from a list of elements. More...
 
class  gui2::minimap
 The basic minimap class. More...
 
class  gui2::multi_page
 A multi page is a control that contains several 'pages' of which only one is visible. More...
 
class  gui2::multimenu_button
 A multimenu_button is a styled_widget to choose an element from a list of elements. More...
 
class  gui2::pane
 A pane is a container where new members can be added and removed during run-time. More...
 
class  gui2::panel
 A panel is a visible container to hold multiple widgets. More...
 
class  gui2::password_box
 
Key Type Default Description
label t_string"" The initial text of the password box.
More...
 
class  gui2::progress_bar
 This object shows the progress of a certain action, or the value state of a certain item. More...
 
class  gui2::repeating_button
 A repeating_button is a control that can be pushed down and repeat a certain action. More...
 
class  gui2::scroll_label
 Label showing a text. More...
 
class  gui2::scrollbar_panel
 Visible container to hold multiple widgets. More...
 
class  gui2::size_lock
 A fixed-size widget that wraps an arbitrary widget and forces it to the given size. More...
 
class  gui2::slider
 A slider is a control that can select a value by moving a grip on a groove. More...
 
class  gui2::spacer
 An empty widget to either fill in a widget since no empty items are allowed or to reserve a fixed space. More...
 
class  gui2::stacked_widget
 A stacked widget holds several widgets on top of each other. More...
 
class  gui2::styled_widget
 Base class for all visible items. More...
 
class  gui2::text_box
 Class for a single line text area. More...
 
class  gui2::toggle_button
 Class for a toggle button. More...
 
class  gui2::toggle_panel
 Class for a toggle button. More...
 
class  gui2::tree_view
 A tree view is a control that holds several items of the same or different types. More...
 
class  gui2::vertical_scrollbar
 The definition of a vertical scrollbar. More...
 
class  gui2::viewport
 A viewport is an special widget used to view only a part of the widget it 'holds'. More...
 
class  gui2::window
 base class of top level items, the only item which needs to store the final canvases to draw on. More...
 
class  gui::button
 A button is a control that can be pushed to start an action or close a dialog. More...
 

Detailed Description

In various parts of the GUI there are several variables types in use.

This section describes them.

Below are the simple types which have one value or a short list of options:

Variable description
unsigned Unsigned number (positive whole numbers and zero).
f_unsigned Unsigned number or formula returning an unsigned number.
int Signed number (whole numbers).
f_int Signed number or formula returning an signed number.
bool A boolean value accepts the normal values as the rest of the game.
f_bool Boolean value or a formula returning a boolean value.
string A text.
t_string A translatable string.
f_tstring Formula returning a translatable string.
function A string containing a set of function definition for the formula language.
color A string which contains the color, this a group of 4 numbers between 0 and 255 separated by a comma. The numbers are red component, green component, blue component and alpha. A color of 0 is not available. An alpha of 255 is fully transparent. Omitted values are set to 0.
font_style A string which contains the style of the font:
  • normal
  • bold
  • italic
  • underlined
Since SDL has problems combining these styles only one can be picked. Once SDL will allow multiple options, this type will be transformed to a comma separated list. If empty we default to the normal style. Since the render engine is replaced by Pango markup this field will change later on. Note widgets that allow marked up text can use markup to change the font style.
v_align Vertical alignment; how an item is aligned vertically in the available space. Possible values:
  • top
  • bottom
  • center
When nothing is set or an another value as in the list the item is centered.
h_align Horizontal alignment; how an item is aligned horizontal in the available space. Possible values:
  • left
  • right
  • center
f_h_align A horizontal alignment or a formula returning a horizontal alignment.
border Comma separated list of borders to use. Possible values:
  • left
  • right
  • top
  • bottom
  • all alias for "left, right, top, bottom"
scrollbar_modeHow to show the scrollbar of a widget. Possible values:
  • always - The scrollbar is always shown, regardless whether it's required or not.
  • never - The scrollbar is never shown, even not when needed. (Note when setting this mode dialogs might not properly fit anymore).
  • auto - Shows the scrollbar when needed. The widget will reserve space for the scrollbar, but only show when needed.
  • initial_auto - Like auto, but when the scrollbar is not needed the space is not reserved.
Use auto when the list can be changed dynamically eg the game list in the lobby. For optimization you can also use auto when you really expect a scrollbar, but don't want it to be shown when not needed eg the language list will need a scrollbar on most screens.
resize_mode Determines how an image is resized. Possible values:
  • scale - The image is scaled.
  • stretch - The first row or column of pixels is copied over the entire image. (Can only be used to scale resize in one direction, else falls back to scale.)
  • tile - The image is placed several times until the entire surface is filled. The last images are truncated.
grow_directionDetermines how an image is resized. Possible values:
  • scale - The image is scaled.
  • stretch - The first row or column of pixels is copied over the entire image. (Can only be used to scale resize in one direction, else falls back to scale.)
  • tile - The image is placed several times until the entire surface is filled. The last images are truncated.

For more complex parts, there are sections. Sections contain of several lines of WML and can have sub sections. For example a grid has sub sections which contain various widgets. Here's the list of sections:

Variable description
section A generic section. The documentation about the section should describe the section in further detail.
grid A grid contains several widgets.
config .

Every widget has some parts in common. First of all, every definition has the following fields:

Key Type Default Description
id string mandatoryUnique id for this gui (theme).
description t_stringmandatoryUnique translatable name for this gui.
resolution section mandatoryThe definitions of the widget in various resolutions.

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.