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.

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

  • "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).

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

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

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

set_cursor_fixed_height(h)

Set the slider cursor’s height.

Parameters

h (int) – Height in pixels.

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.

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.

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

open()

Open this dropdown menu.

highlight_item(index)

Parameters

index (integer) – the index of the item to highlight, starting from 1

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

New in version 1.2.

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.

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 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. Only allowed for dropdowns with supported datatypes.

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. Only allowed for dropdowns with supported datatypes.

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

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.

add(label, value

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

Changed in version 1.3: Added enable parameter.

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

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

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.

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 = ""])

New in version 1.2.

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.

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.

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.

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