LuaAPI/gui

(Version 1.15.0 and later only)

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

1. A title string for the dialog
2. The message content for the dialog.
3. 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 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 [[1]].)

Two optional functions can be passed as second and third arguments; the first one is called once the dialog is created and before it is shown; the second one 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 can change the game state, this function should be called in conjunction with wesnoth.synchronize_choice, 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.

gui.widget

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