wl.ui
¶
Note
The objects inside this module can not be persisted. That is if the player tries to save the game while any of these objects are assigned to variables, the game will crash. So when using these, make sure that you only create objects for a short amount of time where the user can’t take control to do something else.
Module Classes¶
Panel¶
- class wl.ui.Panel¶
The Panel is the most basic ui class. Each UI element is a panel.
- name¶
New in version 1.2.
(RO) The name of this panel.
- children¶
New in version 1.2.
(RO) An
array
of all direct children of this panel.The array also contains invisible children. It does not contain indirect descendants.
- buttons¶
(RO) An
array
of all visible buttons inside this Panel.
- dropdowns¶
(RO) An
array
of all visible dropdowns inside this Panel.
- tabs¶
(RO) An
array
of all visible tabs inside this Panel.
- windows¶
- (RO) A
array
of all currently open windows that are children of this Panel.
- (RO) A
- width, height
(RW) The dimensions of this panel in pixels
- position_x, position_y
(RO) The top left pixel of the our inner canvas relative to the parent’s element inner canvas.
- visible¶
New in version 1.2.
(RW) Whether this panel is visible to the user.
- get_descendant_position(child)¶
Get the child position relative to the inner canvas of this Panel in pixels. Throws an error if child is not really a child.
- Parameters
child (
Panel
) – children to get position for- Returns
x, y
- Return type
both are
integers
- die()¶
New in version 1.2.
Delete this panel in the next frame.
- force_redraw()¶
New in version 1.2.
Force the screen to redraw immediately.
Warning
Only call this during a blocking operation from a plugin, otherwise it will interfere with the regular redrawing and may result in glitches or crashes.
- get_child(name[, recursive=true])¶
New in version 1.2.
Get a panel by name that is a descendant of this panel.
If the optional parameter is
false
, only direct children of this panel are considered.- Parameters
name – Name of the descendant to look for.
recursive – Also consider non-direct descendants.
- Returns
The child upcasted to the correct class, or
nil
if the child does not exist.
- create_child(table)¶
New in version 1.2.
Create a UI widget as a child of this panel as specified by the provided table.
A UI descriptor table contains multiple keys of type
string
. Common properties are:"widget"
: Mandatory. The type of widget to create. See below for allowed values."name"
: Mandatory. The internal name of the panel."x"
: Optional. The horizontal offset inside the parent from the left. Default: 0."y"
: Optional. The vertical offset inside the parent from the top. Default: 0."w"
: Optional. The widget’s width. Default: automatic."h"
: Optional. The widget’s height. Default: automatic."tooltip"
: Optional. The widget’s tooltip.
"resizing"
: Optional. If the parent component is a Box, the Resizing strategy to use for layouting. Valid values are:"align"
: Use the widget’s desired size. This is the default."fullsize"
: Use the widget’s desired depth and the full available breadth."fillspace"
: Use the widget’s desired breadth and the full available depth."expandboth"
: Use the full available space.
A box’s depth is its primary layout direction, and the breadth is the direction orthogonal to it. See: Box widgets
"align"
: Optional. If the parent component is a Box, the Alignment strategy to use for layouting. Valid values are"center"
(the default,)"left"
/"top"
, and"right"
/"bottom"
."on_panel_clicked"
: Optional. Callback code to run when the user clicks anywhere inside the widget."on_position_changed"
: Optional. Callback code to run when the widget’s position changes."on_hyperlink"
: Optional. New in version 1.3. Callback code to run whenthe panel is the target of a hyperlink clicked by the user. The hyperlink’s action argument will be stored in a global variable called
HYPERLINK_ACTION
.
"children"
: Optional. An array of widget descriptor tables.
Keys that are not supported by the widget type are silently ignored.
Currently supported types of widgets are:
"window"
: A window. Windows can only be added to the top-levelMapView
. Properties:"title"
: Mandatory. The title bar text."content"
: Optional. The main panel descriptor table. The window will resize itself to accommodate this widget perfectly.
"unique_window"
: A window of which only one instance can exist. If a unique window with the same registry as the provided one is already open, this function does nothing. Unique windows have all attributes of non-unique windows and the following additional property:"registry"
: Mandatory. The window’s unique registry identifier.
"box"
: A wrapper around other components with intelligent layouting. It is strongly recommended to layout all your components exclusively with Boxes. Properties:"orientation"
: Mandatory. The box’s layouting direction:"vertical"
or"horizontal"
. The shorthands"vert"
,"v"
,"horz"
, and"h"
may be used.The size of a child component along this direction is called its depth, and the size of a child component along the direction orthogonal to it is called its breadth.
See also: The “resizing” property
"max_x"
: Optional. The maximum horizontal size. Default: unlimited."max_y"
: Optional. The maximum vertical size. Default: unlimited."spacing"
: Optional. The inner spacing between items. Default: 0."scrolling"
: Optional. Whether the box may scroll if its content is too large. Default: false.
"inf_space"
: Only valid as the direct child of a Box. A flexible spacer.Takes no properties.
"space"
: Only valid as the direct child of a Box. A fixed-size spacer.Only accepted property:
"value"
: Mandatory. The size of the space.
"panel"
: A plain panel that can act as a spacer or as a container for other widgets."textarea"
: A static text area with a single line of text. Properties:"text"
: Mandatory. The text to display."font"
: Mandatory. The font style to use. See fonts"text_align"
: Optional. The alignment of the text. Valid values are"center"
(the default),"left"
, and"right"
."fixed_width"
: Optional. If set, the text area’s width is fixed instead of resizing to accomodate the text or the parent. Default: not set.
"multilinetextarea"
: A static text area displaying multiple lines of text. Properties:"text"
: Mandatory. The text to display. The text can be formatted with richtext (see richtext.lua), in which case thefont
attribute will have no effect."scroll_mode"
: Mandatory. The text area’s scrolling behaviour. One of:"none"
: The text area expands to accommodate its content instead of scrolling."normal"
: Explicit scrolling only."normal_force"
: Explicit and forced scrolling."log"
: Follow the bottom of the log."log_force"
: Follow the bottom of the log with forced scrolling.
"font"
: Optional. The font style to use. See fonts"text_align"
: Optional. The alignment of the text. Valid values are"center"
(the default),"left"
, and"right"
.
It is strongly recommended to use box layouting for all widgets. All widgets that are the child of a Box widget are layouted automatically by the Box. Their x and y positions will be ignored, and their width and/or height may be changed in accordance with their resizing strategy in order to optimally layout all components.
If a widget appears to be missing, usually its width and/or height has been determined as zero. In this case, setting a minimum width and height or using a more dynamic resizing strategy will fix the widget’s layout.
Note that event callbacks functions must be provided as raw code in string form. During the lifetime of a toolbar widget, the Lua Interface used by the game may be reset. Therefore, any callbacks attached to such widgets must not use any functions or variables defined at an arbitrary earlier time by your script - they may have been deleted by the time the callback is invoked.
Similarly, in the main menu, a plugin’s init script may be called multiple times without resetting the user interface in the mean time. Therefore, the script needs to check whether the elements it intends to add already exist from an earlier invocation using a different Lua context.
Example:
push_textdomain("yes_no.wad", true) local mv = wl.ui.MapView() -- Create a toolbar button mv.toolbar:create_child({ widget = "button", name = "yes_no_toolbar_button", w = styles.get_size("toolbar_button_size"), h = styles.get_size("toolbar_button_size"), tooltip = _("Yes or No"), icon = "images/ui_basic/different.png", -- Callback code to run when the user presses the button on_click = [[ push_textdomain("yes_no.wad", true) -- Open a new window wl.ui.MapView():create_child({ widget = "window", name = "yes_or_no_window", title = _("Yes or No"), x = wl.ui.MapView().width // 2, y = wl.ui.MapView().height // 2, -- The window's content content = { -- The window's central panel: A box with three children widget = "box", orientation = "vert", name = "main_box", children = { { widget = "textarea", font = "wui_info_panel_paragraph", text = _("Click Yes or No"), name = "label_yes_no", }, { -- Space between the text and the buttons is also created like a widget widget = "space", value = 10, }, { -- Place the buttons side by side in a horizontal box widget = "box", orientation = "horz", name = "buttons_box", children = { { widget = "button", name = "no", title = _("No"), on_click = [=[ wl.ui.show_messagebox(_("Hello"), _("You clicked no!"), false) ]=], }, { widget = "space", value = 10, }, { widget = "button", name = "yes", title = _("Yes"), on_click = [=[ wl.ui.show_messagebox(_("Hello"), _("You clicked yes!")) ]=], }, }, }, } } }) pop_textdomain() ]] }) mv:update_toolbar() pop_textdomain()
Checkbox¶
ProgressBar¶
- class wl.ui.ProgressBar¶
Child of:
Panel
New in version 1.2.
A partially filled bar that indicates the progress of an operation.
- state¶
(RW) The current progress value.
Note
When using a progress bar to visualize the progress of a blocking script, you may need to call
force_redraw()
after changing this property to ensure the change becomes visible to the user immediately.
- total¶
(RW) The maximum progress value.
- show_percent¶
(RW) Whether the progress bar label displays the absolute progress or the percentage completed.
SpinBox¶
- class wl.ui.SpinBox¶
Child of:
Panel
New in version 1.2.
A box with buttons to increase or decrease a numerical value.
- value¶
(RW) The currently selected value.
- set_unit_width(w)¶
Set the width of the spinbox’s buttons and content.
- Parameters
w – Width in pixels.
- set_interval(min, max)¶
Set the minimum and maximum value of the spinbox.
- Parameters
min (
int
) – Minimum value.max (
int
) – Maximum value.
- add_replacement(value, label)¶
Replacement string to display instead of a specific value when that value is selected.
- Parameters
value (
int
) – Value to replace.label (
string
) – Replacement text.
Slider¶
- class wl.ui.Slider¶
Child of:
Panel
New in version 1.2.
A button that can be slid along a line to change a value.
- value¶
(RW) The currently selected value.
- min_value¶
(RW) The lowest selectable value.
- max_value¶
(RW) The highest selectable value.
- set_enabled(b)¶
Set whether the user can move this slider.
- Parameters
b (
boolean
) –true
orfalse
- set_cursor_fixed_height(h)¶
Set the slider cursor’s height.
- Parameters
h (
int
) – Height in pixels.
MultilineTextarea¶
Textarea¶
TextInputPanel¶
- class wl.ui.TextInputPanel¶
Child of:
Panel
New in version 1.2.
This represents a box containing arbitrary text that can be edited by the user.
- text¶
(RW) The text currently held in this box.
- selected_text¶
(RO) The text currently selected by the user (may be empty).
- password¶
(RW) Whether the actual text is displayed with asterisks for password boxes.
- warning¶
(RW) Whether the box is highlighted to indicate an error.
- caret_pos¶
(RW) The position of the caret in the text.
- multiline¶
(RO) Whether this editbox has multiple lines or just one line.
Dropdown¶
- class wl.ui.Dropdown¶
Child of:
Panel
This represents a dropdown menu.
Some attributes and functions are available only for dropdowns with a data type supported by the Lua interface. See
datatype
.- datatype¶
New in version 1.2.
(RO) The dropdown’s datatype as
string
if supported, ornil
for dropdowns with unsupported datatype.Currently only
"string"
is supported.
- expanded¶
(RO) True if the dropdown’s list is currently expanded.
- no_of_items¶
(RO) The number of items this dropdown has.
- selection¶
New in version 1.2.
(RO) The currently selected entry or
nil
if none is selected. For dropdowns with unsupported datatype, this is alwaysnil
.
- open()¶
Open this dropdown menu.
- highlight_item(index)¶
- Parameters
index (
integer
) – the index of the item to highlight, starting from1
Highlights an item in this dropdown without triggering a selection.
- select()¶
Selects the currently highlighted item in this dropdown.
- add(label, value[, icon = nil, tooltip = "", select = false, hotkey = nil])¶
New in version 1.2.
Changed in version 1.3: Added parameter
hotkey
.Add an entry to the dropdown. Only allowed for dropdowns with supported datatypes.
- Parameters
label (
string
) – The label to display for the entry.value (This dropdown’s
datatype
) – The internal value of the entry.icon (
string
) – The icon filepath for the entry (nil
for no icon).tooltip (
string
) – The entry’s tooltip text.select (
boolean
) – Whether to select this entry.hotkey (
string
) – The internal name of the hotkey for this entry.
- get_value_at(index)¶
New in version 1.3.
Get the internal value of the item at the specified position. Only allowed for dropdowns with supported datatypes.
- Parameters
index (
integer
) – The index to query, starting from1
.- Returns
The entry’s internal value.
- Return type
This list’s
datatype
- get_label_at(index)¶
New in version 1.3.
Get the user-facing name of the item at the specified position. Only allowed for dropdowns with supported datatypes.
- Parameters
index (
integer
) – The index to query, starting from1
.- Returns
The entry’s display name.
- Return type
string
- get_tooltip_at(index)¶
New in version 1.3.
Get the tooltip of the item at the specified position. Only allowed for dropdowns with supported datatypes.
- Parameters
index (
integer
) – The index to query, starting from1
.- Returns
The entry’s tooltip (may be empty if the item has no tooltip).
- Return type
string
Listselect¶
- class wl.ui.Listselect¶
Child of:
Panel
New in version 1.2.
This represents a selection list.
Some attributes and functions are available only for listselects with a data type supported by the Lua interface. See
datatype
.- datatype¶
(RO) The listselect’s datatype as
string
if supported, ornil
for listselects with unsupported datatype.Currently only
"string"
is supported.
- no_of_items¶
(RO) The number of items this listselect has.
- selection¶
(RO) The currently selected entry or
nil
if none is selected. For listselects with unsupported datatype, this is alwaysnil
.
- add(label, value
- [, icon = nil, tooltip = "", select = false, indent = 0, enable = true, hotkey = nil])
Changed in version 1.3: Added
enable
andhotkey
parameters.Add an entry to the list. Only allowed for lists with supported datatypes.
- arg label
The label to display for the entry.
- type label
string
- arg value
The internal value of the entry.
- type value
This list’s
datatype
- arg icon
The icon filepath for the entry (
nil
for no icon).- type icon
string
- arg tooltip
The entry’s tooltip text.
- type tooltip
string
- arg select
Whether to select this entry.
- type select
boolean
- arg indent
By how many levels to indent this entry.
- type indent
int
- arg enable
Whether to enable this entry.
- type enable
boolean
- arg hotkey
The internal name of the hotkey for this entry.
- type hotkey
string
- get_value_at(index)¶
New in version 1.3.
Get the internal value of the item at the specified position. Only allowed for lists with supported datatypes.
- Parameters
index (
integer
) – The index to query, starting from1
.- Returns
The entry’s internal value.
- Return type
This list’s
datatype
- get_label_at(index)¶
New in version 1.3.
Get the user-facing name of the item at the specified position.
- Parameters
index (
integer
) – The index to query, starting from1
.- Returns
The entry’s display name.
- Return type
string
- get_tooltip_at(index)¶
New in version 1.3.
Get the tooltip of the item at the specified position.
- Parameters
index (
integer
) – The index to query, starting from1
.- Returns
The entry’s tooltip (may be empty if the item has no tooltip).
- Return type
string
- get_enable_at(index)¶
New in version 1.3.
Get the enable/disable display state of the item at the specified position.
- Parameters
index (
integer
) – The index to query, starting from1
.- Returns
Whether the entry is marked as enabled.
- Return type
boolean
- get_indent_at(index)¶
New in version 1.3.
Get the indentation level of the item at the specified position.
- Parameters
index (
integer
) – The index to query, starting from1
.- Returns
The entry’s indentation.
- Return type
integer
Table¶
- class wl.ui.Table¶
Child of:
Panel
New in version 1.2.
This represents a table.
Some attributes and functions are available only for tables with a data type supported by the Lua interface. See
datatype
.- datatype¶
(RO) The table’s datatype as
string
if supported, ornil
for tables with unsupported datatype.Currently only
"int"
is supported.
- no_of_rows¶
(RO) The number of rows this table has.
- selection_index¶
(RW) The index of the currently selected row or
nil
if none is selected. Setting this tonil
clears the selection.
- selections¶
(RO) An
array
with all currently selected row indices (may be empty).
- sort_column¶
(RW) The index of the column by which the table is sorted.
- sort_descending¶
(RW) Whether the table is sorted in reverse order.
- get(row)¶
Lookup the internal value associated with a given row index. Only allowed for tables with supported datatypes.
- Parameters
row (
int
) – The row index to look up.- Returns
The row’s internal value.
- Return type
int
- add(value, select, disable, columns)¶
Add a row to the table. Only allowed for tables with supported datatypes.
The named arguments are followed by an array of as many entries as the table has columns. Each array entry is a
table
describing the content of one table cell. Valid keys are:"text"
: Optional. The text to show in the cell."icon"
: Optional. The icon filepath in the cell.
- Parameters
value (This table’s
datatype
) – The internal value of the entry.select (
boolean
) – Whether to select this entry.disable (
boolean
) – Whether to disable this row.columns (
array
oftable
) – The cell descriptors.
- remove_row(row)¶
Delete the row at the specified index from the table.
- Parameters
row (
int
) – The row index to delete.
- remove_entry(entry)¶
Delete the row with the specified internal value from the table. Only allowed for tables with supported datatypes.
- Parameters
entry (
int
) – The entry value to delete.
TabPanel¶
- class wl.ui.TabPanel¶
Child of:
Panel
New in version 1.2.
This represents a panel that allows switching between multiple tabs.
- no_of_tabs¶
(RO) The number of tabs this tab panel has.
- active¶
(RW) The index of the currently active tab. When assigning this property, it is also allowed to activate a tab by name instead of index.
- remove_last_tab(name)¶
Remove the last tab in the panel.
As a precaution against accidental removal of tabs, the name of the tab that will be removed has to be specified.
- Parameters
name (
string
) – The name of the last tab.- Returns
Whether the tab was removed.
- Return type
boolean
Tab¶
Window¶
- class wl.ui.Window¶
Child of:
Panel
This represents a Window.
- title¶
New in version 1.2.
(RW) The title shown in the window’s title bar.
- pinned¶
New in version 1.2.
(RW) Whether the window is pinned so it can’t be closed accidentally.
- minimal¶
New in version 1.2.
(RW) Whether the window is minimized and only the title bar visible.
- close()¶
Closes this window. This invalidates this Object, do not use it any longer.
MapView¶
- class wl.ui.MapView¶
Child of:
Panel
The map view is the main widget and the root of all panels. It is the big view of the map that is visible at all times while playing.
This class may only be accessed in a game or the editor. You can construct as many instances of it as you like, and they will all refer to the same map view.
- toolbar¶
New in version 1.2.
(RO) The main toolbar.
- average_fps¶
(RO) The average frames per second that the user interface is being drawn at.
- center_map_pixel¶
(RO) The map position (in pixels) that the center pixel of this map view currently sees. This is a table containing ‘x’, ‘y’.
- buildhelp¶
(RW) True if the buildhelp is show, false otherwise.
- census¶
(RW) True if the census strings are shown on buildings, false otherwise
- statistics¶
(RW) True if the statistics strings are shown on buildings, false otherwise
- is_building_road¶
(RO) Is the player currently in road/waterway building mode?
- auto_roadbuild_mode¶
(RO) Is the player using automatic road building mode?
- is_animating¶
(RO) True if this MapView is currently panning or zooming.
- click(field)¶
Jumps the mouse onto a field and clicks it just like the user would have.
- Parameters
field (
wl.map.Field
) – the field to click on
- start_road_building(flag[, waterway = false])¶
Enters the road building mode as if the player has clicked the flag and chosen build road. It will also warp the mouse to the given starting node. Throws an error if we are already in road building mode.
- Parameters
flag –
wl.map.Flag
object to start building from.waterway – if true, start building a waterway rather than a road
- abort_road_building()¶
If the player is currently in road building mode, this will cancel it. If he wasn’t, this will do nothing.
- close()¶
Closes the MapView. Note that this is the equivalent as clicking on the exit button in the game; that is the game will be exited.
This is especially useful for automated testing of features and is for example used in the widelands Lua test suite.
- scroll_to_map_pixel(x, y)¶
Starts an animation to center the view on top of the pixel (x, y) in map pixel space. Use is_animating to check if the animation is still going on.
- Parameters
x (number) – x coordinate of the pixel
y (number) – y coordinate of the pixel
- scroll_to_field(field)¶
Starts an animation to center the view on top of the ‘field’. Use is_animating to check if the animation is still going on.
- Parameters
field (
wl.map.Field
) – the field to center on
- is_visible(field)¶
Returns true if field is currently visible in the map view.
- Parameters
field (
wl.map.Field
) – the field
- mouse_to_pixel(x, y)¶
Starts an animation to move the mouse onto the pixel (x, y) of this panel. Use is_animating to check if the animation is still going on.
- Parameters
x (number) – x coordinate of the pixel
y (number) – y coordinate of the pixel
- mouse_to_field(field)¶
Starts an animation to move the mouse onto the ‘field’. If ‘field’ is not visible on the screen currently, does nothing. Use is_animating to check if the animation is still going on.
- Parameters
field (
wl.map.Field
) – the field
- update_toolbar()¶
New in version 1.2.
Recompute the size and position of the toolbar. Call this after you have modified the toolbar in any way.
- add_toolbar_plugin(action, icon, name[, tooltip = "", hotkey = nil])¶
New in version 1.2.
Changed in version 1.3: Added
hotkey
parameter.Add an entry to the main toolbar’s Plugin dropdown. This makes the plugin dropdown visible if it was hidden.
- arg action
The Lua code to run when the user selects the entry.
- type action
string
- arg icon
Icon filepath for the entry.
- type icon
string
- arg name
Label for the entry.
- type name
string
- arg tooltip
Tooltip for the entry.
- type tooltip
string
- arg hotkey
The internal name of the hotkey for this entry.
- type hotkey
string
- set_keyboard_shortcut(internal_name, action[, failsafe=true])¶
New in version 1.3.
Associate a named keyboard shortcut with a piece of code to run when the shortcut is pressed. This replaces any existing action associated with pressing the shortcut.
- Parameters
internal_name (
string
) – The internal name of the keyboard shortcut.action (
string
) – The Lua code to run.failsafe (
boolean
) – In event of an error, an error message is shown and the shortcut binding is removed. If this is set tofalse
, the game will be aborted with no error handling instead.
- See also
- set_keyboard_shortcut_release(internal_name, action[, failsafe=true])¶
New in version 1.3.
Associate a named keyboard shortcut with a piece of code to run when the shortcut is released after having been previously pressed. This replaces any existing action associated with releasing the shortcut.
You don’t need this in normal cases. When in doubt, use only meth:set_keyboard_shortcut.
- Parameters
internal_name (
string
) – The internal name of the keyboard shortcut.action (
string
) – The Lua code to run.failsafe (
boolean
) – In event of an error, an error message is shown and the shortcut binding is removed. If this is set tofalse
, the game will be aborted with no error handling instead.
- See also
- add_plugin_timer(action, interval[, failsafe=true])¶
New in version 1.2.
Register a piece of code that will be run periodically as long as the game/editor is running.
- Parameters
action (
string
) – The Lua code to run.interval (
int
) – The interval in milliseconds realtime in which the code will be invoked.failsafe (
boolean
) – In event of an error, an error message is shown and the timer is removed. If this is set tofalse
, the game will be aborted with no error handling instead.