LuaWML/Display
This page describes the LuaWML functions and helpers for interfacing with the user.
Contents
wesnoth.message
Displays a string in the chat window and dumps it to the lua/info log domain (--log-info=scripting/lua on the command-line).
wesnoth.message "Hello World!"
The chat line header is "<Lua>" by default, but it can be changed by passing a string before the message.
wesnoth.message("Big Brother", "I'm watching you.") -- will result in "<Big Brother> I'm watching you."
See also helper.wml_error for displaying error messages.
wesnoth.textdomain
Creates a function proxy for lazily translating strings from the given domain.
-- #textdomain "my-campaign"
-- the comment above ensures the subsequent strings will be extracted to the proper domain
_ = wesnoth.textdomain "my-campaign"
wesnoth.set_variable("my_unit.description", _ "the unit formerly known as Hero")
The metatable of the function proxy appears as "message domain". The metatable of the translatable strings (results of the proxy) appears as "translatable string".
The translatable strings can be appended to other strings/numbers with the standard .. operator. Translation can be forced with the standard tostring operator in order to get a plain string.
wesnoth.message(string.format(tostring(_ "You gain %d gold."), amount))
wesnoth.float_label
Pops some text above a map tile.
wesnoth.float_label(unit.x, unit.y, "<span color='#ff0000'>Ouch</span>")
wesnoth.scroll_to_tile
Scrolls the map to the given location. If true is passed as the third parameter, scrolling is disabled if the tile is hidden under the fog.
local u = wesnoth.get_units({ id = "hero" })[1]
wesnoth.scroll_to_tile(u.x, u.y)
wesnoth.set_music
Sets the given table as an entry into the music list. See MusicListWML for the recognized attributes.
wesnoth.set_music { name = "traveling_minstrels.ogg" }
Passing no argument forces the engine to take into account all the recent changes to the music list. (Note: this is done automatically when sequences of WML commands end, so it is useful only for long events.)
wesnoth.show_dialog
Displays a dialog box described by a WML table and returns the integer value associated to the button pressed by the user. The content of the WML table is described at GUIWidgetInstanceWML; it should at least contain a [grid] child.
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 can call the #wesnoth.set_dialog_value, #wesnoth.get_dialog_value, and #wesnoth.set_dialog_callback functions for this purpose.
The example below defines a dialog with a list and two buttons on the left, and a big image on the right. The preshow function fills the list and defines a callback on it. This select callback changes the displayed image whenever a new list item is selected. The postshow function recovers the selected item before the dialog is destroyed.
local helper = wesnoth.require "lua/helper.lua"
local T = helper.set_wml_tag_metatable {}
local _ = wesnoth.textdomain "wesnoth"
local dialog = {
T.grid { T.row {
T.column { T.grid {
T.row { T.column { horizontal_grow = true, T.listbox { id = "the_list",
T.list_definition { T.row { T.column { horizontal_grow = true,
T.toggle_panel { T.grid { T.row {
T.column { horizontal_alignment = "left", T.label { id = "the_label" } },
T.column { T.image { id = "the_icon" } }
} } }
} } }
} } },
T.row { T.column { T.grid { T.row {
T.column { T.button { id = "ok", label = _"OK" } },
T.column { T.button { id = "cancel", label = _"Cancel" } }
} } } }
} },
T.column { T.image { id = "the_image" } }
} }
}
local function preshow()
local t = { "Ancient Lich", "Ancient Wose", "Elvish Avenger" }
local function select()
local i = wesnoth.get_dialog_value "the_list"
local ut = wesnoth.unit_types[t[i]].__cfg
wesnoth.set_dialog_value(string.gsub(ut.profile, "([^/]+)$", "transparent/%1"), "the_image")
end
wesnoth.set_dialog_callback(select, "the_list")
for i,v in ipairs(t) do
local ut = wesnoth.unit_types[v].__cfg
wesnoth.set_dialog_value(ut.name, "the_list", i, "the_label")
wesnoth.set_dialog_value(ut.image, "the_list", i, "the_icon")
end
wesnoth.set_dialog_value(2, "the_list")
select()
end
local li = 0
local function postshow()
li = wesnoth.get_dialog_value "the_list"
end
local r = wesnoth.show_dialog(dialog, preshow, postshow)
wesnoth.message(string.format("Button %d pressed. Item %d selected.", r, li))
wesnoth.set_dialog_value
Sets the value of a widget on the current dialog. The value is given by the first argument; its semantic depends on the type of widget it is applied to. The last argument is the id of the widget. If it does not point to a unique widget in the dialog, some discriminating parents should be given on its left, making a path that is read from left to right by the engine. The row of a list is specified by giving the id' of the list as a first argument and the 1-based row number as the next argument.
-- sets the value of a widget "bar" in the 7th row of the list "foo" wesnoth.set_value(_"Hello world", "foo", 7, "bar")
Notes: When the row of a list does not exist, it is created. The value associated to a list is the selected row.
wesnoth.get_dialog_value
Gets the value of a widget on the current dialog. The arguments described the path for reaching the widget (see #wesnoth.set_dialog_value).
wesnoth.set_dialog_callback
Sets the first argument as a callback function for the widget obtained by following the path of the other arguments (see #wesnoth.set_dialog_value). This function will be called whenever the user modifies something on the dialog so that the dialog can react to it.
helper.get_user_choice
Displays a WML message box querying a choice from the user. Attributes and options are taken from given tables (see [message]). The index of the selected option is returned.
local result = helper.get_user_choice({ speaker = "narrator" }, { "Choice 1", "Choice 2" })