`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 Functions¶

wl.ui.set_user_input_allowed(b)¶

Allow or disallow user input. Be warned, setting this will make that mouse movements and keyboard presses are completely ignored. Only scripted stuff will still happen.

Parameters: b (boolean) – true or false

wl.ui.get_user_input_allowed()¶

Return the current state of this flag.

Returns: true or false
Return type: boolean

wl.ui.get_shortcut(name)¶

Returns the keyboard shortcut with the given name.

Returns: The human-readable and localized shortcut.
Return type: string

wl.ui.shortcut_exists(internal_name)¶

New in version 1.3.

Check whether the given name belongs to a known keyboard shortcut.

Parameters: internal_name (string) – The internal name of the keyboard shortcut.
Returns: Whether the named shortcut exists.
Return type: boolean

wl.ui.get_all_keyboard_shortcut_names()¶

New in version 1.3.

List the internal names of all known keyboard shortcuts.

Returns: The names.
Return type: array of string

wl.ui.get_ingame_shortcut_help()¶

New in version 1.2.

Returns the list of current in-game keyboard shortcuts formatted as richtext.

Returns: The richtext formatted list of shortcuts
Return type: string

wl.ui.get_fastplace_help()¶

New in version 1.2.

Returns the list of current fastplace shortcuts for the current player formatted as richtext.

Returns: The richtext formatted list of shortcuts
Return type: string

wl.ui.get_editor_shortcut_help()¶

New in version 1.2.

Returns the list of current map editor keyboard shortcuts formatted as richtext.

Returns: The richtext formatted list of shortcuts
Return type: string

wl.ui.show_messagebox(title, text[, cancel_button = true])¶

New in version 1.2.

Show the user a modal message box with an OK button and optionally a cancel button.

You can use richtext to style the text. Don’t forget to wrap it in an rt tag in this case.

Parameters

title (string) – The caption of the window
text (string) – The message to show
cancel_button (boolean) – Whether to include a Cancel button

Returns

Whether the user clicked OK.

Return type

boolean

wl.ui.is_rtl()¶

New in version 1.3.

Returns whether the current locale uses right-to-left text.

Returns: Whether the text flow is right-to-left.
Return type: boolean

wl.ui.get_clipboard()¶

New in version 1.3.

Returns the current content of the system-wide clipboard.

This may be empty if the clipboard is currently empty or does not contain text data.

Returns: The clipboard content.
Return type: string

wl.ui.set_clipboard(text)¶

New in version 1.3.

Set the content of the system-wide clipboard.

Parameters: text (string) – Text to set.

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.

parent¶: New in version 1.3.

(RO) The direct parent panel of this panel, or nil for a top-level 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.

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

layout()¶: New in version 1.3.

Force this panel and all its descendants to recompute their layout now.

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 when
the 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-level MapView. 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 the font 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".

"button": A clickable button. A button must have either a title or an icon, but not both. Properties:

"title": Optional. The text on the button.

"icon": Optional. The file path of the button’s icon.

"style": Optional. The button’s style. One of:

"primary"

"secondary" (default)

"menu"

"visual": Optional. The button’s appearance. One of:

"raised" (default)

"permpressed"

"flat"

"repeating": Optional. Whether pressing and holding the button generates repeated events. Default: false.

"on_click": Optional. Callback code to run when the button is clicked. To associate actions with a button press, prefer this over the on_panel_clicked event.

"checkbox": A toggleable checkbox. A checkbox must have either a title or an icon, but not both. Properties:

"title": Optional. The text on the button.

"icon": Optional. The file path of the button’s icon.

"state": Optional. Whether the checkbox is initially checked.

"on_changed": Optional. Callback code to run when the checkbox’s state changes.

"radiogroup": A group of pictorial buttons of which at most one can be selected at the same time. Properties:

"buttons": Mandatory. An array of tables, each of which defines a radiobutton with the following properties:

"name": Mandatory. The internal name of the button.

"icon": Mandatory. The file path of the radiobutton’s icon.

"tooltip": Optional. The radiobutton’s tooltip.

"x": Optional. The radiobutton’s x position.

"y": Optional. The radiobutton’s y position.

"state": Optional. The ID of the initially active radiobutton (0-based; -1 for none).

"on_changed": Optional. Callback code to run when the radiogroup’s active button changes.

This widget does not use the sizing and positioning properties and has no tooltip.

"progressbar": A partially filled bar that indicates the progress of an operation. Properties:

"orientation": Mandatory. The progress bar’s direction: "vertical" or "horizontal". The shorthands "vert", "v", "horz", and "h" may be used.

"total": Mandatory. The progress bar’s maximum value.

"state": Mandatory. The progress bar’s initial value.

"percent": Optional. Whether to show a percentage instead of absolute values. Default: true.

"spinbox": A box with buttons to increase or decrease a numerical value. There are two kinds of spinboxes by their value ranges: normal spinboxes that can have any integer value within a range, and spinboxes that can only use values from a value list. Some properties are only used by one kind of spinbox and forbidden for the other kind.

Common Properties:

"unit_w": Mandatory. The total width of the buttons and value display.

"value": Mandatory. The spinbox’s initial value. When "values" is used, this is a 0 based index within the value list.

"label": Optional. Text to display next to the spinbox.

"units": Optional. The unit for the spinbox’s value. One of:

"none" (default)

"pixels"

"percent"

"fields"

"minutes"

"weeks"

"replacements": Optional. An array of tables with keys "value" and "replacement". When the spinbox’s value is equal to any replaced value, the replacement string is displayed instead of the value.

"on_changed": Optional. Callback code to run when the spinbox’s value changes.

Properties for normal spinboxes:

"min": Mandatory for normal spinboxes. The spinbox’s minimum value.

"max": Mandatory for normal spinboxes. The spinbox’s maximum value.

"step_size_small": Optional. The amount by which the value changes on each button click.

"step_size_big": Optional. If set, the spinbox additionally shows buttons to change the value by this larger amount.

Properties for value list spinboxes:

"values": Mandatory to set the type to value list. An array of integers. The spinbox can only switch between the values in this array.

The properties for normal spinboxes above cannot be used when "values" is used.

This widget can not have a custom tooltip.

"slider": A button that can be slid along a line to change a value. Properties:

"orientation": Mandatory. The slider’s direction: "vertical" or "horizontal". The shorthands "vert", "v", "horz", and "h" may be used.

"value": Mandatory. The slider’s initial value.

"min": Mandatory. The slider’s minimum value.

"max": Mandatory. The slider’s maximum value.

"cursor_size": Optional. The size of the slider button in pixels (default 20).

"dark": Optional. Ignored in the main menu. Draw the slider darker instead of lighter (default false).

"on_changed": Optional. Callback code to run when the slider’s value changes.

"discrete_slider": A button that can be slid along a horizontal line to change a value between several predefined points. Properties:

"labels": Mandatory. Array of strings. Each string defines one slider point.

"value": Mandatory. The initially selected value.

"cursor_size": Optional. The size of the slider button in pixels (default 20).

"dark": Optional. Ignored in the main menu. Draw the slider darker instead of lighter (default false).

"on_changed": Optional. Callback code to run when the slider’s value changes.

"multilineeditbox": A multi-line field where the user can enter text. Properties:

"text": Optional. The initial text in the field.

"password": Optional. Whether the editbox’s content will be hidden.

"warning": Optional. Whether the editbox will be highlighted as having errors.

"on_changed": Optional. Callback code to run whenever the content changes.

"on_cancel": Optional. Callback code to run whenever the user presses Escape.

"editbox": A single-line field where the user can enter text. Has all the properties of multilineeditbox and the following additional property:

"on_ok": Optional. Callback code to run whenever the user presses Return.

"dropdown": A dropdown that allows the user to select an entry from a popup list. Properties:

"label": Mandatory. The text on the dropdown.

"max_list_items": Mandatory. Maximum number of items to show in the list.

"button_dimension": Mandatory. Size of the button in pixels.

"button_style": Mandatory. The style for the button. See: Button widgets.

"type": Mandatory. The behaviour of the dropdown. One of:

"textual": Shows the name of the selected entry and a push button.

"textual_narrow": Only shows the name of the selected entry.

"pictorial": Only shows the icon of the selected entry.

"pictorial_menu": The shown icon remains always unchanged.

"textual_menu": The shown text remains always unchanged.

"datatype": Mandatory. The data type of the dropdown’s entries. Currently only "string" is supported.

"icon": Optional. The icon filepath for the dropdown’s button, if any. If an icon is set, the label or selected value are not displayed on the button and only shown as a tooltip.

"entries": Optional. The entries in the dropdown. An array of tables with the following keys:

"label": Mandatory. The text for this entry.

"value": Mandatory. The internal value of this entry.

"icon": Mandatory for dropdowns of type "pictorial", optional for other types. The icon filepath for the entry.

"tooltip": Optional. The entry’s tooltip.

"select": Optional. Whether to select this entry (default false).

"hotkey": Optional. New in version 1.3.
The internal name of the hotkey for this entry.

"on_selected": Optional. Callback code to run when the user selects an entry.

"listselect": A list of entries from which the user may choose. Properties:

"type": Optional. The highlighting mode for the selected entry. One of:

"plain": Highlight the selection’s background (default).

"check": Draw a check mark before the selected item.

"dropdown": Select entries as soon as the mouse hovers over them.

"datatype": Mandatory. The data type of the listselect’s entries. Currently only "string" is supported.

"entries": Optional. The entries in the listselect. An array of tables with the following keys:

"label": Mandatory. The text for this entry.

"value": Mandatory. The internal value of this entry.

"icon": Optional. The icon filepath for the entry.

"tooltip": Optional. The entry’s tooltip.

"select": Optional. Whether to select this entry (default false).

"indent": Optional. How many levels to indent the item (default 0).

"enable": Optional. New in version 1.3. Whether to enable this entry (default true).

"hotkey": Optional. New in version 1.3.
The internal name of the hotkey for this entry.

"on_selected": Optional. Callback code to run when the user selects an entry.

"on_double_clicked": Optional. Callback code to run when the user double-clicks on an entry.

This widget can not have a custom tooltip.

"table": A table with multiple rows and columns. Properties:

"datatype": Mandatory. The data type of the table’s entries. Currently only "int" is supported.

"multiselect": Optional. Whether the user can select multiple rows (default false).

"sort_column": Optional. The index of the column by which the table is sorted (default 0).

"sort_descending": Optional. Whether the sorting order is inverted (default false).

"columns": Optional. The columns in the table. An array of tables with the following keys:

"w": Mandatory. The width of the column in pixels.

"title": Mandatory. The title of the column.

"tooltip": Optional. The tooltip in pixels.

"flexible": Optional. Whether the column width adapts automatically (default false). A table must not have multiple flexible columns.

"align": Optional. The alignment of the column content. Valid values are "center" (the default), "left", and "right".

"rows": Optional. The rows in the table. An array of tables with the following keys:

"value": Mandatory. The internal value associated with the row.

"select": Optional. Whether to select this row (default false).

"disable": Optional. Whether to disable this row (default false).

For each column i (indices are zero-based):

"text_<i>": Optional. The text to show in the cell.

"icon_<i>": Optional. The icon filepath in the cell.

"on_cancel": Optional. Callback code to run when the user presses Escape.

"on_selected": Optional. Callback code to run when the user selects a row.

"on_double_clicked": Optional. Callback code to run when the user double-clicks on an entry.

This widget can not have a custom tooltip.

"tabpanel": A panel that allows switching between multiple tabs.

"dark": Optional. Ignored in the main menu. Whether to use dark appearance (default false).

"active": Optional. The name or index of the initially active tab.

"tabs": Optional. The tabs in the tab panel. An array of tables with the following keys:

"name": Mandatory. The name of the tab.

"panel": Mandatory. The descriptor table for the panel wrapped in this tab.

"title": Optional. The title of the tab. If set, "icon" must be nil.

"icon": Optional. The icon filepath for the tab. If set, "title" must be nil.

"tooltip": Optional. The tooltip for the tab.

"on_clicked": Optional. Callback code to run when the user selects a tab.

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

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.

Parameters

action (string) – The Lua code to run when the user selects the entry.
icon (string) – Icon filepath for the entry.
name (string) – Label for the entry.
tooltip (string) – Tooltip for the entry.
hotkey (string) – The internal name of the hotkey for this entry.

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 to false, the game will be aborted with no error handling instead.

See also

set_keyboard_shortcut_release()

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 to false, the game will be aborted with no error handling instead.

See also

set_keyboard_shortcut()

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 to false, the game will be aborted with no error handling instead.

MainMenu¶

class wl.ui.MainMenu¶

Child of: Panel

New in version 1.3.

The main menu screen is the main widget and the root of all panels.

This class may not 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 main menu.

set_keyboard_shortcut(internal_name, action[, failsafe=true])¶

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 to false, the game will be aborted with no error handling instead.

See also

set_keyboard_shortcut_release()

set_keyboard_shortcut_release(internal_name, action[, failsafe=true])¶

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 to false, the game will be aborted with no error handling instead.

See also

set_keyboard_shortcut()

add_plugin_timer(action, interval[, failsafe=true])¶

Register a piece of code that will be run periodically as long as the main menu is running and its Lua context is not reset.

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 to false, the game will be aborted with no error handling instead.

Box¶

class wl.ui.Box¶

Child of: Panel

New in version 1.3.

This represents a box that dynamically layouts its child components.

orientation¶: (RO) The box’s layouting direction: "vertical" or "horizontal".

no_of_items¶

(RO) The number of items currently layouted by this box.

An item can be either a panel which is a direct child of the box, or a space. A child of the box is not necessarily represented by an item.

scrolling¶: (RW) Whether the box may scroll when its content is larger than the box.

force_scrolling¶: (RW) Whether the box will always show a scrollbar even if its content fits in the box.

inner_spacing¶: (RW) The spacing between items.

min_desired_breadth¶: (RW) The minimum size of the box in the direction orthogonal to the primary layouting direction.

max_width¶: (RW) The maximum width of the box.

max_height¶: (RW) The maximum height of the box.

clear()¶: Remove all items from the box’s layouting. This does not delete the child items.

get_index(panel)¶

Return the index of the given panel in the box, or nil if the box does not layout this panel.

Parameters: index (Panel) – The panel to query.
Returns: The item’s index, starting from 1.
Return type: integer

is_space(index)¶

Check whether the item at the given index is a spacer or a child panel.

Parameters: index (integer) – The index to query, starting from 1.
Returns: Whether the item is a space.
Return type: boolean

get_resizing(index)¶

Get the resizing strategy for the item at the given index.

The result is one of "align", "fullsize", "fillspace", and "expandboth". For fixed-size spaces, this is always "align". For infinite spaces, this is always "fillspace".

Parameters: index (integer) – The index to query, starting from 1.
Returns: The resizing strategy.
Return type: string

get_align(index)¶

Get the alignment for the item at the given index.

The result is one of "left", "center", and "right". This function may not be called for spacers.

Parameters: index (integer) – The index to query, starting from 1.
Returns: The item alignment.
Return type: string

Textarea¶

class wl.ui.Textarea¶

Child of: Panel

New in version 1.2.

A static text area with a single line of text that can not be modified by the user.

text¶: (RW) The text currently shown by this area.

MultilineTextarea¶

class wl.ui.MultilineTextarea¶

Child of: Panel

New in version 1.2.

A static text area with multiple lines that can not be modified by the user.

text¶: (RW) The text currently shown by this area.

Button¶

class wl.ui.Button¶

Child of: Panel

This represents a simple push button.

title¶: New in version 1.2.

(RW) The text shown on the button.

enabled¶: New in version 1.2.

(RW) Whether the user may interact with the button.

press()¶

Press and hold this button. This is mainly to visualize a pressing event in tutorials.

Holding a button does not generate a Clicked event. Use click() to release the button.

click()¶: Click this button just as if the user would have moused over and clicked it.

set_repeating(b)¶

New in version 1.2.

Set whether holding the button will generate repeated clicked events.

Parameters: b (boolean) – true or false

set_perm_pressed(b)¶

New in version 1.2.

Set whether the button will be styled as if permanently pressed.

Parameters: b (boolean) – true or false

toggle()¶: New in version 1.2.

Toggle whether the button will be styled as if permanently pressed.

Checkbox¶

class wl.ui.Checkbox¶

Child of: Panel

New in version 1.2.

A tick box that can be toggled on or off by the user.

state¶: (RW) Whether the checkbox is currently checked.

set_enabled(b)¶

Set whether the user can change the state of this checkbox.

Parameters: b (boolean) – true or false

RadioButton¶

class wl.ui.RadioButton¶

Child of: Panel

New in version 1.2.

One of the buttons in a radio group. In each radio group, at most one button can be active at the same time.

Note that each button in the group also acts as a representation of the group itself.

state¶: (RW) The index of the radio group’s currently active button (0-based; -1 for none).

set_enabled(b)¶

Set whether the user can change the state of the radio group.

Parameters: b (boolean) – true or false

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, or nil 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 always nil.

linked_dropdown¶: New in version 1.3.

(RO) If this listselect represents the list component of a dropdown, this links to the Dropdown. Otherwise this is nil.

select(index)¶

New in version 1.3.

Select the item with the given index.

Parameters: index (int) – The index to select, starting from 1.

clear()¶: New in version 1.3.

Remove all entries from the listselect.

add(label, value

[, icon = nil, tooltip = "", select = false, indent = 0, enable = true, hotkey = nil])

Changed in version 1.3: Added enable and hotkey parameters.

Add an entry to the list. Only allowed for lists with supported datatypes.

Parameters

label (string) – The label to display for the entry.
value (This list’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.
indent (int) – By how many levels to indent this entry.
enable (boolean) – Whether to enable 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 lists with supported datatypes.

Parameters: index (integer) – The index to query, starting from 1.
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 from 1.
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 from 1.
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 from 1.
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 from 1.
Returns: The entry’s indentation.
Return type: integer

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

set_cursor_fixed_height(h)¶

Set the slider cursor’s height.

Parameters: h (int) – Height in pixels.

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.

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, or nil 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 to nil 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 of table) – 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¶

class wl.ui.Tab¶

Child of: Panel

A tab button.

active¶: (RO) Is this the currently active tab in this window?

click()¶: Click this tab making it the active one.

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.

`wl.ui`¶

Module Functions¶

Module Classes¶

Panel¶

Window¶

MapView¶

MainMenu¶

Box¶

Textarea¶

MultilineTextarea¶

Button¶

Checkbox¶

RadioButton¶

Listselect¶

SpinBox¶

Slider¶

TextInputPanel¶

Table¶

TabPanel¶

Tab¶

ProgressBar¶

Table of Contents

Previous topic

Next topic

This Page

wl.ui¶

Module Functions¶

Module Classes¶

Panel¶

Window¶

MapView¶

MainMenu¶

Box¶

Textarea¶

MultilineTextarea¶

Button¶

Checkbox¶

RadioButton¶

Dropdown¶

Listselect¶

SpinBox¶

Slider¶

TextInputPanel¶

Table¶

TabPanel¶

Tab¶

ProgressBar¶

`wl.ui`¶