LuaAPI/gui

Functions

gui.show_menu

gui.show_menu(items, [initial], [markup]) → index

Shows a popup menu onscreen at the current mouse location. This could be used for example to produce a sort of submenu in a [set_menu_item]. The items are specified as a Lua array of tables, each of which supports the following keys:

icon: An icon to display in the leftmost column of the menu.
image: An image to display in the main column of the menu. If this is present, label is ignored.
label: A label to display in the main column of the menu.
details: A secondary label to display in the right column of the menu.
tooltip: Text to display when mousing over this option.

The initial argument must be a valid index into the items array, or 0 to indicate that no element is initially selected (which is the default but typically not what you want).

The markup argument specifies whether Pango markup will be parsed in the menuitems. It defaults to false.

The initial and markup arguments can be passed in either order; the game will understand which is meant based on the type of the argument.

This function returns the index of the selected item. If the user cancelled by clicking outside the menu's boundary, 0 is returned.

gui.show_narration

gui.show_narration(attributes, [options, [text_input_attributes]]) → result_code, [entered_text]

Shows a message dialog, of the type used by the [message] ActionWML tag. Unlike the [message] tag, this is unsynced; if you need it synced, you must do it yourself. The first argument is a table describing the dialog with the following keys:

title - The title to show on the message. For example, the speaker's name.
message - The message content.
portrait - An image to show along with the message. By default, no image is shown.
left_side - The default is true; set to false to show the image on the right.
mirror - If true, the image will be flipped horizontally.

The second argument is a list of options as a Lua array. Each option is either a (possibly-translatable) string or a config with DescriptionWML keys. The array itself can also have an optional default key which if present should be the index of the initially selected option (useful if you don't need full DescriptionWML but want to set a default). If present it overrides any defaults set in individual options.

The third argument is a table describing the text input field with the following keys:

label - A label to show to the left of the text field.
text - Initial contents of the text field.
max_length - Maximum input length in characters (defaults to 256).

You need at least one key for the text input to be shown. Both the second and third arguments are optional, but if you want text input with no options, you must pass nil for the second parameter.

This function returns one or two values. The first value returned is the numeric result of the dialog:

If there are no options and no text input, the result is -2 if the user pressed Escape, or -1 if they closed by clicking or pressing Space.
If there are options, the result is the index of the option chosen (starting from 1).
If there is text input but no options, the first return value is 0.

The second value returned is the text entered, if there was text input. Otherwise there is no second value (it is nil).

Example:

gui.show_narration({
    title = "Make your choice:",
    message = "Select an option and enter some text.",
    portrait = "wesnoth-icon.png",
}, {
    "The first choice is always the best!",
    "Pick me! Second choices are better!",
    "You know you want the third option!",
}, {
    label = "Text:",
    text = "?",
    max_length = 16
})

(You don't have to format it like that, of course.)

gui.get_user_choice

gui.get_user_choice(attributes, options)

Shows a message dialog (like the one used by the [message] tag) with a series of options and returns the index (1-based) of the chosen option, which can be stored as a Lua variable.

IMPORTANT NOTE: this function is broken in Wesnoth 1.16.0 and 1.16.1. If you wish to use it, you should also use wesnoth.current_version to check that your code is being run on Wesnoth 1.16.2 or higher. Alternatively, you may try using gui.show_narration instead, which has a similar function but a wider range of features.

The first argument is a table of attributes which are directly passed to the underlying [message] tag.

The second argument is a table of options, which are used to construct a series of underlying [option] tags. Most Lua data types are supported, but a few aren't:

If the option is a table or a WML table, these fields are supported:
- image: icon shown in the first column;
- label: text shown in the second column;
- description: text shown in the third column (message is also supported as an alias);
- default: whether this is option is the one selected when the dialog is shown (boolean).
If the option can be cast to a string (strings, translatable strings, numbers, booleans), it is used for the content of the description field, which means that the first two columns will be empty.
Otherwise, it raises an "invalid data type" error.

Example taken from the test scenario (if not used in an event then change the speaker):

local result = gui.get_user_choice(
    { speaker = "unit", message = "Pick your poison" },
    { { image = "items/potion-red.png",
        label = "Something red",
        description = "Take a sip and enjoy" },
      { image = "items/potion-blue.png",
        label = "Nice blue",
        description = "Surely you’ll like that one",
        default = true },
      { image = "items/potion-yellow.png",
        label = "<span color='yellow'>Oh noes yellow</span>",
        description = "Oh I’m sure you’ll love that one" },
      { image = "scenery/well.png",
        label = "A nice well",
        description = "Grab a bucket and fetch some water" },
      { image = "items/holy-water.png",
        label = "Oh nice bottle",
        description = "Feel the divinity" },
      -- Should have an empty first column and a second column on two lines.
      { label = "Well a nice and black drink.\nToo dark too see?",
        description = "Take a sip and pass the bottle along" }
    })
wesnoth.interface.add_chat_message(string.format("User selected choice %d.", result))

gui.show_popup

gui.show_popup(title, message, [image])

Shows a simple popup dialog in the centre of the screen. Takes three arguments, which in order are:

A title string for the dialog
The message content for the dialog.
An image to show.

Both the title and the message support Pango markup. The image is optional.

gui.show_prompt

gui.show_prompt(title, message, [button], [markup]) → result
gui.confirm([title,] message) → result
gui.alert([title], message)

Shows a standard message box onscreen (similar to the quit confirmation message, for example). The button can be any arbitrary potentially-translatable string (in which case, there will be one button with that label), or it can be one of the following special string values:

ok or nil: A single OK button; this is the default
cancel: A single Cancel button
close: A single Close button
ok_cancel: Two buttons labelled OK and Cancel
yes_no: Two buttons labelled Yes and No
an empty string: No buttons; the dialog automatically closes after a few seconds

The alert and confirm functions are simpler wrappers for this function, using a single OK button and a pair of Yes/No buttons, respectively. Both confirm and show_prompt return false if No or Cancel was clicked, and true otherwise. The alert function returns nothing.

gui.show_story

gui.show_story(story_config, default_title)

Shows the storyscreen. The passed config is identical to the contents of [story]. The second parameter is the default title used if a part does not specify one — unlike intro storyscreens, a Lua-invoked one does not default to the scenario name.

gui.show_dialog

gui.show_dialog(dialog definition, preshow, postshow) → retval

Displays a dialog box described by a WML table and returns an integer

if the dialog was dismissed by a button click, the integer value associated to the button via the return_value keyword.
if the dialog was closed with the enter key, -1.
if the dialog was closed with the escape key, -2.

The dialog box is equivalent to the [resolution] section of a GUI window as described in GUIToolkitWML and must therefore contain at least the following children: [tooltip], [helptip], and [grid]. The [grid] must contain nested [row], [column] and [grid] tags which describe the layout of the window. (More information can be found in GUIToolkit page's Layout section and GUILayout; suffice to say that the basic structure is grid -> row -> column -> widget, where the widget is considered to be in a cell defined by the row and column of the grid. A list of widgets can be found at GUIWidgetInstanceWML.) For an overview of the GUI system, see GUIToolkit.

Two optional functions can be passed as second and third arguments; the function passed as preshow argument is called just before the dialog is shown; the second function (argument postshow) is called once the dialog is closed. These functions are helpful in setting the initial values of the fields and in recovering the final user values. These functions take a single parameter, which is the widget userdata representing the window.

For in-game dialogs that offer the player a choice and/or can change the game state, this function should be called in conjunction with wesnoth.sync.evaluate_single, in order to ensure that only one client displays the dialog and that the other ones recover the same input values from this single client. Though this is especially important in multiplayer scenarios, failing to do it in a single-player scenario will cause the replay to break, so it should be done in either case.

See here for a fully-working example of a custom dialog.

gui.add_widget_definition

gui.add_widget_definition(widget_type, definition_id, wml_content)

Creates a new WML widget definition for the specified widget type, which can be referenced from dialog WML in the definition key.

gui.widget

A submodule containing functions for working with widgets in custom dialogs.

gui.show_help

gui.show_help([topic])

Show the in-game help, optionally opening a specified topic directly.

gui.show_inspector

♟ gui.show_inspector()

Show the gamestate inspector.

gui.show_lua_console

gui.show_lua_console()

Shows the Lua console. This works even if debug mode is not enabled.

gui.switch_theme

gui.switch_theme(theme_id)

Switch to the GUI2 theme with id theme_id. Can only be used inside a scenario and does not replace the UI Theme selected by Preferences. The UI reverts to the theme selected in Preferences after exiting the in-game window, for example, by using the menu or by winning or losing a campaign.