Difference between revisions of "GUIToolkitWML"

From The Battle for Wesnoth Wiki
(GUI: mention tag)
Line 18: Line 18:
 
test it.
 
test it.
  
The gui has the following data:
+
In WML, the gui class is represented by the toplevel `[gui]` tag, which supports the following keys,
 
{| border="1"
 
{| border="1"
 
!key
 
!key

Revision as of 04:40, 27 August 2024

GUI

The gui class contains the definitions of all widgets and windows used in the game. This can be seen as a skin and it allows the user to define the visual aspect of the various items. The visual aspect can be determined depending on the size of the game window.

Widgets have a definition and an instance, the definition contains the general info/looks of a widget and the instance the actual looks. Eg the where the button text is placed is the same for every button, but the text of every button might differ.

The default gui has the id default and must exist, in the default gui there must a definition of every widget with the id default and every window needs to be defined. If the definition of a widget with a certain id doesn't exist it will fall back to default in the current gui, if it's not defined there either it will fall back to the default widget in the default theme. That way it's possible to slowly create your own gui and test it.

In WML, the gui class is represented by the toplevel `[gui]` tag, which supports the following keys,

key type default description
id string mandatory Unique id for this gui (theme).
description t_string mandatory Unique translatable name for this gui.
widget_definitions section mandatory The definitions of all widgets.
window section mandatory The definitions of all windows.
settings section mandatory The settings for the gui.

List of available widgets:

Section Description
Button (definition, instantiation) A button is a control that can be pushed to start an action or close a dialog.
Image (definition, instantiation) An image shows a static image.
Horizontal listbox (definition, instantiation) 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.
Horizontal scrollbar (definition, instantiation) 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.
Label (definition, instantiation) A label displays a text, the text can be wrapped but no scrollbars are provided.
Listbox (definition, instantiation) 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.
Minimap (definition, instantiation) 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.
Multi page (definition, instantiation) 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.
Panel (definition, instantiation) 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.
Password box (definition, instantiation) A text box masking it's content by asterisks.
Repeating button (definition, instantiation) 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.
Scroll label (definition, instantiation) 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.
Slider (definition, instantiation) A slider is a control that can select a value by moving a grip on a groove.
Spacer (definition, instantiation) A spacer is a dummy item to either fill in a widget since no empty items are allowed or to reserve a fixed space.
Stacked widget (definition, instantiation) A stacked widget is a control several widgets can be stacked on top of each other in the same space. This is mainly intended for over- and underlays. (The widget is still experimental.)
Text box (definition, instantiation) A single line text box.
Tree view (definition, instantiation) 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.
Toggle button (definition, instantiation) A kind of button with two 'states' normal and selected. This is a more generic widget which is used for eg checkboxes and radioboxes.
Toggle panel (definition, instantiation) Like a toggle button but then as panel so can hold multiple items in a grid.
Tooltip (definition, instantiation) A small tooltip with help.
Tree view (definition, instantiation) A tree view widget.
Vertical scrollbar (definition, instantiation) A vertical scrollbar.
Window (definition, instantiation) A window.

List of available windows:

Section Description
Addon connect (definition) The dialog to connect to the addon server and maintain locally installed addons.
Addon list (definition) Shows the list of the addons to install or update.
Campaign selection (definition) Shows the list of campaigns, to select one to play.
Language selection (definition) The dialog to select the primary language.
WML message left (definition) The ingame message dialog with a portrait on the left side. (Used for the WML messages.)
WML message right (definition) The ingame message dialog with a portrait on the right side. (Used for the WML messages.)
Message (definition) A generic message dialog.
MP connect (definition) The dialog to connect to the MP server.
MP method selection (definition) The dialog to select the kind of MP game to play. Official server, local etc.
MP server list (definition) List of the 'official' MP servers.
MP login (definition) The dialog to provide a password for registered usernames, request a password reminder or choose a different username.
MP cmd wrapper (definition) Perform various actions on the selected user (e.g. whispering or kicking).
MP create game (definition) The dialog to select and create an MP game.
Title screen (definition) The title screen.
Editor new map (definition) Creates a new map in the editor.
Editor generate map (definition) Generates a random map in the editor.
Editor resize map (definition) Resizes a map in the editor.
Editor custom tod (definition) Creates new ToD schedules for the editor.

A setting section has the following variables:

key type default description
popup_show_delay unsigned 0 The time it take before the popup shows if the mouse moves over the widget. 0 means show directly.
popup_show_time unsigned 0 The time a shown popup remains visible. 0 means until the mouse leaves the widget.
help_show_time unsigned 0 The time a shown help remains visible. 0 means until the mouse leaves the widget.
double_click_time unsigned mandatory The time between two clicks to still be a double click.
repeat_button_repeat_time unsigned 0 The time a repeating button waits before the next event is issued if the button is still pressed down.
sound_button_click string "" The sound played if a button is clicked.
sound_toggle_button_click string "" The sound played if a toggle button is clicked.
sound_toggle_panel_click string "" The sound played if a toggle panel is clicked. Normally the toggle panels are the items in a listbox. If a toggle button is in the listbox it's sound is played.
sound_slider_adjust string "" The sound played if a slider is adjusted.
has_helptip_message t_string mandatory The string used to append the tooltip if there is also a helptip. The WML variable $hotkey can be used to get show the name of the hotkey for the help.

Resolution

Depending on the resolution a widget can look different. Resolutions are evaluated in order of appearance. The window_width and window_height are the upper limit this resolution is valid for. When one of the sizes gets above the limit, the next resolution is selected. There's one special case where both values are 0. This resolution always matches. (Resolution definitions behind that one will never be picked.) This resolution can be used as upper limit or if there's only one resolution.

The default (and also minimum) size of a button is determined by two items, the wanted default size and the size needed for the text. The size of the text differs per used widget so needs to be determined per button.

Container widgets like panels and windows have other rules for their sizes. Their sizes are based on the size of their children (and the border they need themselves). It's wise to set all sizes to 0 for these kind of widgets.

key type default description
window_width unsigned 0 Width of the application window.
window_height unsigned 0 Height of the application window.
min_width unsigned 0 The minimum width of the widget.
min_height unsigned 0 The minimum height of the widget.
default_width unsigned 0 The default width of the widget.
default_height unsigned 0 The default height of the widget.
max_width unsigned 0 The maximum width of the widget.
max_height unsigned 0 The maximum height of the widget.
text_extra_width unsigned 0 The extra width needed to determine the minimal size for the text.
text_extra_height unsigned 0 The extra height needed to determine the minimal size for the text.
text_font_family font_family "" The font family, needed to determine the minimal size for the text.
text_font_size unsigned 0 The font size, which needs to be used to determine the minimal size for the text.
text_font_style font_style "" The font style, which needs to be used to determine the minimal size for the text.
state section mandatory Every widget has one or more state sections. Note they aren't called state but state_xxx the exact names are listed per widget.


State

A state contains the info what to do in a state. At the moment this is rather focussed on the drawing part, might change later. Keys: Keys:

key type default description
draw section mandatory Section with drawing directions for a canvas.

Window definition

A window defines how a window looks in the game.

key type default description
id string mandatory Unique id for this window.
description t_string mandatory Unique translatable name for this window.
resolution section mandatory The definitions of the window in various resolutions.

Resolution

key type default description
window_width unsigned 0 Width of the application window.
window_height unsigned 0 Height of the application window.
automatic_placement bool true Automatically calculate the best size for the window and place it. If automatically placed vertical_placement and horizontal_placement can be used to modify the final placement. If not automatically placed the width and height are mandatory.
x f_unsigned 0 X coordinate of the window to show.
y f_unsigned 0 Y coordinate of the window to show.
width f_unsigned 0 Width of the window to show.
height f_unsigned 0 Height of the window to show.
reevaluate_best_size f_bool false The foo
functions function "" The function definitions s available for the formula fields in window.
vertical_placement v_align "" The vertical placement of the window.
horizontal_placement h_align "" The horizontal placement of the window.
maximum_width unsigned 0 The maximum width of the window (only used for automatic placement).
maximum_height unsigned 0 The maximum height of the window (only used for automatic placement).
click_dismiss bool false Does the window need click dismiss behavior? Click dismiss behavior means that any mouse click will close the dialog. Note certain widgets will automatically disable this behavior since they need to process the clicks as well, for example buttons do need a click and a misclick on button shouldn't close the dialog. NOTE with some widgets this behavior depends on their contents (like scrolling labels) so the behavior might get changed depending on the data in the dialog. NOTE the default behavior might be changed since it will be disabled when can't be used due to widgets which use the mouse, including buttons, so it might be wise to set the behavior explicitly when not wanted and no mouse using widgets are available. This means enter, escape or an external source needs to be used to close the dialog (which is valid).
definition string "default" Definition of the window which we want to show.
linked_group sections [] A group of linked widget sections.
tooltip section mandatory Information regarding the tooltip for this window.
helptip section mandatory Information regarding the helptip for this window.
grid grid mandatory The grid with the widgets to show.

A linked_group section has the following fields:

key type default description
id string mandatory The unique id of the group (unique in this window).
fixed_width bool false Should widget in this group have the same width.
fixed_height bool false Should widget in this group have the same height.

A linked group needs to have at least one size fixed.

A tooltip and helptip section have the following field:

key type default description
id string The id of the tip to show.

Note more fields will probably be added later on.

Cell

key type default description
id string "" A grid is a widget and can have an id. This isn't used that often, but is allowed.
linked_group string 0

Every grid cell has some cell configuration values and one widget in the grid cell. Here we describe the what is available more information about the usage can be found here GUILayout.

Row values

For every row the following variables are available:

key type default description
grow_factor unsigned 0 The grow factor for a row.

Cell values

For every column the following variables are available:

key type default description
grow_factor unsigned 0 The grow factor for a column, this value is only read for the first row.
border_size unsigned 0 The border size for this grid cell.
border border "" Where to place the border in this grid cell.
vertical_alignment v_align "" The vertical alignment of the widget in the grid cell. (This value is ignored if vertical_grow is true.)
horizontal_alignment h_align "" The horizontal alignment of the widget in the grid cell.(This value is ignored if horizontal_grow is true.)
vertical_grow bool false Does the widget grow in vertical direction when the grid cell grows in the vertical direction. This is used if the grid cell is wider as the best width for the widget.
horizontal_grow bool false Does the widget grow in horizontal direction when the grid cell grows in the horizontal direction. This is used if the grid cell is higher as the best width for the widget.

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 has no special fields.

Stacked widget

A stacked widget is a set of widget stacked on top of each other. The widgets are drawn in the layers, in the order defined in the the instance config. By default the last drawn item is also the 'active' layer for the event handling.

Toggle button

key type default description
icon f_string "" The name of the icon file to show.
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.

List if the id's that have generate a return value:

  • ok confirms the dialog.
  • cancel cancels the dialog.