LuaAPI/gui

From The Battle for Wesnoth Wiki
< LuaAPI
Revision as of 03:22, 29 November 2018 by Celtic Minstrel (talk | contribs) (Add category)

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.
  • second_label: 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
  • wesnoth.confirm([title,] message) → result
  • wesnoth.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.