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

(RO) The name of this panel

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.

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

Button

class wl.ui.Button

Child of: Panel

This represents a simple push button.

press()

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

click()

Click this button just as if the user would have moused over and clicked it.

Dropdown

class wl.ui.Dropdown

Child of: Panel

This represents a dropdown menu.

expanded

(RO) True if the dropdown’s list is currently expanded.

no_of_items

(RO) The number of items his dropdown has.

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.

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.

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.

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

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