The Battle for Wesnoth Wiki - User contributions [en]

LuaAPI/wesnoth/map

2024-11-23T18:31:45Z

White haired uncle: /* wesnoth.map.get_cubic */ minor typo

<div class="tright"> __TOC__ </div>

{{DevFeature1.15|11}}

This module contains functions for working with the game map. Some of the functions can be called as methods of the map itself. In 1.15.11, there exists only one map in the game context, which can be accessed as [[LuaAPI/types/map|'''wesnoth.current.map''']], while in the map generation context, a map can be created with [[#wesnoth.map.create]] or [[#wesnoth.map.generate]]. In future, it may become possible to create maps on the fly or read them from disk.

== Functions ==

=== wesnoth.map.find ===

* {{LuaGameOnly}} '''wesnoth.map.find'''(''filter config'') → ''list of hex references''
* {{LuaGameOnly}} '''wesnoth.map.find'''(''filter config'', [''reference_unit'']) → ''list of hex references''
* {{LuaMapOnly}} '''wesnoth.map.find'''(''map'', ''filter userdata'', [''list of locations'']) → ''list of locations''
* {{LuaMapOnly}} '''wesnoth.map.find_in_radius'''(''map'', ''center'', ''radius'', ''filter userdata'') → ''list of locations''

Returns a table containing all the locations matching the given filter. Locations are stored as a ''hex reference'' which has x and y keys along with a variety of other functions. See [[StandardLocationFilter]] for details about location filters. If a unit is passed, it can be referenced from the filter via the $teleport_unit variable, as well as in WFL formulas used in the filter.

'''Note:''' In older versions of Wesnoth, locations returned from a filter were stored as simple pairs, <syntaxhighlight lang=lua inline>{x,y}</syntaxhighlight>. For compatibility purposes, accessing a location this way (as <syntaxhighlight lang=lua inline>loc[1]</syntaxhighlight> and <syntaxhighlight lang=lua inline>loc[2]</syntaxhighlight>) is still supported.

<syntaxhighlight lang=lua>
-- replace all grass terrains by roads
for i,loc in ipairs(wesnoth.map.find{terrain = "Gg"}) do
wesnoth.current.map[loc] = "Rr"
end
</syntaxhighlight>

The mapgen form of this function uses a different format for the filter which is somewhat experimental. An example of its use:

<syntaxhighlight lang=lua>
local map = wesnoth.map.create(18,18,"Gg")

-- Assume there is some generation code here, so the map is no longer just grass

local F, f = wesnoth.map.filter, wesnoth.map.filter_tags

-- Find all elvish villages
local elf_villages = map:find(F(f.terrain('*^Ve')))

-- Find all great trees within 7 tiles of an elvish keep
local elf_keeps = map:find(F(f.terrain('Kv')))
local nearby_trees = map:find_in_radius(elf_keeps, 7, F(f.terrain('*^Fet')))
</syntaxhighlight>

Possible filter tags for this function are: terrain, all, any, none, notall, adjacent, find_in, radius, x, y, is_loc, formula.

=== wesnoth.map.get ===

* {{LuaGameOnly}} '''wesnoth.map.get'''(''location'') → ''hex reference''

Constructs a [[LuaAPI/types/hex|''hex reference'']] for the specified location.

=== wesnoth.map.matches ===

* {{LuaGameOnly}} '''wesnoth.map.matches'''(''location'', ''filter config'', [''reference_unit'']) → ''boolean''
* {{LuaGameOnly}} ''hex'':'''matches'''(''filter config'', [''reference_unit'']) → ''boolean''
* {{LuaMapOnly}} ''map'':'''matches'''(''location'', ''filter userdata'') → ''boolean''

Returns true if the given location passes the filter. The location can be passed either as two separate x and y parameters or as an object with x and y keys (such as a hex reference or a unit). If a ''reference_unit'' is passed, it can be referenced from the filter via the $teleport_unit variable, as well as in WFL formulas used in the filter.

<syntaxhighlight lang=lua>
local b = wesnoth.map.matches(x, y, {
terrain = "Ww",
wml.tag.filter_adjacent_location{terrain = "Ds,*^Bw*"}
})
</syntaxhighlight>

=== wesnoth.map.on_board ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wesnoth.map.on_board'''(''map'', ''location'', [''include border?'']) → ''boolean''
* {{LuaGameOnly}}{{LuaMapOnly}} ''map'':'''on_board'''(''location'', [''include border?'']) → ''boolean''

Tests if the specified location is on the map. The final parameter determines whether to count the inaccessible map border tiles as being on the map. It defaults to false.

=== wesnoth.map.on_border ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wesnoth.map.on_border'''(''map'', ''location'') → ''boolean''
* {{LuaGameOnly}}{{LuaMapOnly}} ''map'':'''on_border'''(''location'') → ''boolean''

Tests if the specified location is on the map's border.

=== wesnoth.map.iter ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wesnoth.map.iter'''(''map'', [''include border?'']) → ''iterator'' ⇒ ''x'', ''y'', ''terrain code''
* {{LuaGameOnly}}{{LuaMapOnly}} ''map'':'''iter'''([''include border?'') → ''iterator'' ⇒ ''x'', ''y'', ''terrain code''

Iterate over the entire map, possibly excluding the border tiles. For example:

<syntaxhighlight lang=lua>
for x, y in wesnoth.current.map:iter() do
wesnoth.map.add_label{x=x, y=y, text=string.format("%d,%d", x, y)}
end
</syntaxhighlight>

=== wesnoth.map.iter_adjacent ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wesnoth.map.iter_adjacent'''(''map'', ''location'', [''include border?'']) → ''iterator'' ⇒ ''x'', ''y''
* {{LuaGameOnly}}{{LuaMapOnly}} ''map'':'''iter_adjacent'''(''location'', [''include border?'']) → ''iterator'' ⇒ ''x'', ''y''

Iterate over the hexes adjacent to the location, excluding border tiles (unless explicitly enabled).

=== wesnoth.map.read_location ===

* '''wesnoth.read_location'''(...) → ''location or nil'', ''number of arguments processed''

Extracts a location from the front of a variadic parameter list. The purpose of this is to make it easy for custom user-defined functions to handle locations in the same way as the built-in API functions do. It returns the location (if it was able to find one) and the number of arguments processed, which can be:

* 0 if nothing resembling a location was found.
* 1 if a location-like object was found. A location-like object can be either an array of two integers ''or'' an object that has numeric x and y keys. Note that a unit userdata satisfies the second criteria, so if a unit is found, its location will be returned.
* 2 if the first two arguments in the list were integers. In this case, they will be taken as the x and y coordinates.

==== Usage example ====

Imagine a function foo with the following signature:

* '''foo'''(''bar : string'', [''home : location''], ''mode : string'', [''target : location''], ''moo : boolean'') → ''boolean''

Using read_location it could be implemented as follows:

<syntaxhighlight lang=lua>
function foo(...)
-- First argument goes in bar
local bar = ...
-- Read location starting at the second argument
local home, n = wesnoth.map.read_location(select(2, ...))
-- note: n will be 0 if a location wasn't found at that position
-- This could be an error, or it could be handled as an optional parameter
-- Next argument after that goes in mode
local mode = select(n + 2, ...)
-- Then read a location into target
local target, m = wesnoth.map.read_location(select(n + 2, ...))
-- Finally, read a parameter into moo
local moo = select(m + n + 2, ...)
-- Do stuff with all these parameters
return true
end
</syntaxhighlight>

With that code, all the following invocations of foo work:

<syntaxhighlight lang=lua>
foo('a', 'b', true) -- both optional locations omitted
foo('a', 1, 2, 'q', 5, 6, false) -- locations given as separate integer parameters
foo('a', 'm', {1, 7}, true) -- first location omitted, second given as 2-element array
foo('a', some_unit, 'z', {x = 5, y = 10}, false) -- a unit also functions as a location
foo('a', 7, 12, 'q', my_leader, true) -- mixing different forms also works
</syntaxhighlight>

=== wesnoth.map.split_terrain_code ===

* '''wesnoth.map.split_terrain_code'''(''code'') → ''base'', ''overlay''

Splits a terrain code into a base and an overlay. If the terrain code did not contain a <tt>^</tt>, then the ''overlay'' will be nil. The returned ''overlay'' or ''base'' can be an empty string if the code begins or ends with a <tt>^</tt>, respectively. Splitting the string <tt>'^'</tt> will result in two empty strings.

=== wesnoth.map.make_bitmap ===

* {{LuaGameOnly}} '''wesnoth.map.make_bitmap'''(''array of locations'') → ''shroud data bitmap''

Constructs a shroud data string such that the locations in the array are unshrouded and all other locations are shrouded. The string will be the minimum size required to fit all the locations.

=== wesnoth.map.parse_bitmap ===

* {{LuaGameOnly}} '''wesnoth.map.parse_bitmap'''(''shroud data bitmap'') → ''array of locations''

Parses a shroud data string and returns a list of the locations that are unshrouded.

=== wesnoth.map.terrain_mask ===

* {{LuaGameOnly}}{{LuaMapOnly}} '''wesnoth.map.terrain_mask'''(''map'', ''pivot'', ''mask'', [''options''])
* {{LuaGameOnly}}{{LuaMapOnly}} ''map'':'''terrain_mask'''(''pivot'', ''mask'', [''options''])

Overlays a terrain mask on the map. Possible options:

* ''is_odd'' - if true, then the mask is interpreted as if it was cut out from an odd map location.
* ''ignore_special_locations'' - if true, then special locations on the mask won't be added to the map.
* ''rules'' - an array of rules. See [[TerrainMaskWML]] for the rule format. This is an array of tables, each of which has the content of a [rule] tag.

=== wesnoth.map.add_label ===

* {{LuaGameOnly}} '''wesnoth.map.add_label'''(''options'')

Adds a label to the map. Takes the same options as the [[InterfaceActionsWML#.5Blabel.5D|[label]]] WML tag.

=== wesnoth.map.remove_label ===

* {{LuaGameOnly}} '''wesnoth.map.remove_label'''(''location'')

Removes a label from the map. Normally this removes a global label, but you can also remove team labels with an extra '''team_name''' parameter, for example:

<syntaxhighlight lang=lua>
-- Removes the label on (3,12) owned by team 'rebels'
wesnoth.map.remove_label{x = 3, y = 12, team_name = 'rebels'}
</syntaxhighlight>

=== wesnoth.map.get_label ===

* {{LuaGameOnly}} '''wesnoth.map.get_label'''(''location'', [''side or team_name'']) → ''label info''

Get the full label info for a label on the specified location. With one argument, it returns a global label; otherwise, it returns a label belonging to the specified team. Passing a side (either a side number or a side userdata) uses that side's team. The returned table contains all the possible options that can be passed to '''add_label'''.

=== wesnoth.map.place_area ===

* {{LuaGameOnly}} '''wesnoth.map.place_area'''(''filter'')

Add a new named area to the map. The filter is a [[StandardLocationFilter]], but it can also contain an '''id''' key and '''[time]''' tags. In order to remove the area later, an '''id''' must be provided. An area with no '''[time]''' tags does not affect the schedule.

=== wesnoth.map.remove_area ===

* {{LuaGameOnly}} '''wesnoth.map.remove_area'''(''id'')

Remove the area with the given ID.

=== wesnoth.map.get_area ===

* {{LuaGameOnly}} '''wesnoth.map.get_area'''(''id or location'') → ''area schedule''

Get the named area with the specified ID, or the area that is active on the specified location (if any). This will return nil if no area is found in either case.

The returned object is a userdata object similar to [[LuaAPI/wesnoth#wesnoth.current|wesnoth.current.schedule]], with the following differences:

* ''schedule''.'''liminal_bonus''' → nil

This key is not supported on area schedules.

* ''schedule''.'''id''' ↔ ''id''

Check or alter the ID of the named area.

* ''schedule''.'''hexes''' ↔ ''array of locations''

Get the list of locations the area affects, or assign a new list of locations. The list may be empty, in which case the area has no effect on time of day and cannot be matched by a location filter.

=== wesnoth.map.set_owner ===

* {{LuaGameOnly}} '''wesnoth.map.set_owner'''(''location'', ''side number'')

Set the owner of a village hex. If the specified hex is not a village, this has no effect. Set the owner to 0 to leave it owned by no-one.

=== wesnoth.map.get_owner ===

* {{LuaGameOnly}} '''wesnoth.map.get_owner'''(''location'') → ''side number''

Get the owner of a village hex. If the specified hex is not a village, or if it is an unclaimed village, this returns 0.

=== wesnoth.map.create ===

* {{LuaMapOnly}} '''wesnoth.map.create'''(''width'', ''height'', ''terrain'') → ''map''
* {{LuaMapOnly}} '''wesnoth.map.create'''(''map data string'') → ''map''

Create a new map, either filled with a given terrain or read from a string.

=== wesnoth.map.generate ===

* {{LuaMapOnly}} '''wesnoth.map.generate'''(''width'', ''height'', ''options'') → ''map''

Generate a map using the [[MapGeneratorWML#The_Default_Generator|default generator]]. The following options are supported:

* '''nplayers'''
* '''nvillages'''
* '''iterations'''
* '''hill_size'''
* '''castle_size'''
* '''island_size'''
* '''island_off_center'''
* '''max_lakes'''
* '''link_castles'''
* '''seed'''

=== wesnoth.map.generate_height_map ===

* {{LuaMapOnly}} '''wesnoth.map.generate_height_map'''(''width'', ''height'', ''options'') → ''array of heights''

Generates a height map such as that used by the [[MapGeneratorWML#The_Default_Generator|default generator]]. The following options are supported:

* '''iterations'''
* '''hill_size'''
* '''island_size'''
* '''center_x'''
* '''center_y'''
* '''flip_format'''
* '''seed'''

=== wesnoth.map.get_direction ===

* '''wesnoth.map.get_direction'''(''from'', ''dir'', [''steps'']) → ''location''

Calculates the hex reached by travelling in the specified direction, which should be a string such as "ne" or "s". It will also honor direction modifiers (the prefix <tt>-</tt> and postfix <tt>:cw</tt> or <tt>:ccw</tt>). The optional third parameter ''steps'' is number of steps to travel in specified direction. Negative ''steps'' is supported to travel in the opposite direction.

=== wesnoth.map.get_relative_dir ===

* '''wesnoth.map.get_relative_dir'''(''from'', ''to'') → ''direction''

Calculates the direction from one hex to another. Possible returns are strings "n", "ne", "nw", "s", "se", "sw" or "". The empty string means no direction, which happens if ''from'' and ''to'' are same.

=== wesnoth.map.rotate_right_around_center ===

* '''wesnoth.map.rotate_right_around_center'''(''loc'', ''center'', ''angle'') → ''location''

Calculates the hex obtained from rotating the specified location around the specified center by the specified angle. The angle is an integer in the range 1..6.

=== wesnoth.map.get_adjacent_hexes ===

* '''wesnoth.map.get_adjacent_hexes'''(''loc'') → ''n'', ''ne'', ''se'', ''s'', ''sw'', ''nw''

Return all hexes adjacent to the specified hex, as six separate return values. This doesn't check whether the hexes are on the map.

<syntaxhighlight lang=lua>
local a, b, c, d, e, f = wesnoth.map.get_adjacent_hexes(3, 3)
local a_x = a[1]
local a_y = a[2]
</syntaxhighlight>

=== wesnoth.map.get_hexes_in_radius ===

* '''wesnoth.map.get_hexes_in_radius'''(''center'', ''radius'') → ''list of locations''

Return all hexes within the given radius, as an array of pairs. This doesn't check whether the hexes are on the map.

=== wesnoth.map.get_hexes_at_radius ===

{{DevFeature1.19|4}}

* '''wesnoth.map.get_hexes_at_radius'''(''center'', ''radius'') → ''list of locations''

Returns all hexes at exactly the given radius from the center, as an array of pairs. This doesn't check whether the hexes are on the map.

=== wesnoth.map.are_hexes_adjacent ===

* '''wesnoth.map.are_hexes_adjacent'''(''loc1'', ''loc2'') → ''boolean''

Tests if two hexes are adjacent.

=== wesnoth.map.distance_between ===

* '''wesnoth.map.distance_between'''(''loc1'', ''loc2'') → ''integer''

Calculates the distance between two hexes. The distance is the number of hexes you would need to travel across to get from the start point to the end point.

<syntaxhighlight lang=lua>
local my_distance = wesnoth.map.distance_between({10, 10}, {20, 20})
</syntaxhighlight>

=== wesnoth.map.hex_vector_sum ===

{{DevFeature1.19|4}}

* '''wesnoth.map.hex_vector_sum'''(''loc1'', ''loc2'') → ''new loc''

Treats the two locations as position vectors on the hexagonal map and adds them together.

=== wesnoth.map.hex_vector_diff ===

{{DevFeature1.19|4}}

* '''wesnoth.map.hex_vector_diff'''(''loc1'', ''loc2'') → ''new loc''

Treats the two locations as position vectors on the hexagonal map and takes the difference.

=== wesnoth.map.hex_vector_negation ===

{{DevFeature1.19|4}}

* '''wesnoth.map.hex_vector_negation'''(''loc'') → ''new loc''

Treats the location as a position vector on the hexagonal map and reverses the direction.

=== wesnoth.map.get_cubic ===

{{DevFeature1.19|4}}

* '''wesnoth.map.get_cubic'''(''loc'') → ''cubic loc''

Converts hex grid coordinates to [https://www.redblobgames.com/grids/hexagons/#coordinates-cube cubic hex coordinates]. This may make some algorithms easier.

=== wesnoth.map.from_cubic ===

{{DevFeature1.19|4}}

* '''wesnoth.map.from_cubic'''(''cubic loc'') → ''loc''

Converts cubic hex coordinates back to hex grid coordinates.

[[Category:Lua Reference]]

DirectActionsWML

2024-11-13T20:44:16Z

White haired uncle: /* [modify_unit] */ - correct description of hitpoints example

{{WML Tags}}
== Direct actions ==

Direct actions are actions that have a direct effect on gameplay. They can be used inside of [[EventWML|events]].

The following tags are actions:

=== [endlevel] ===
Ends the scenario.
* '''result''': before the scenario is over, all events with ''name=result'' are triggered. If ''result=victory'', the player progresses to the next level (i.e., the next scenario in single player); if ''result=defeat'', the game returns to the main menu.

When the result is "victory" the following keys can be used:
* '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes. {{DevFeature1.13|2}} Alternatively, a number, defining the bonus multiple (1.0 meaning full).
* '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.
* '''save''': whether a start-of-scenario save should be created for the next scenario, the default is save=yes. Do not confuse this with saving of replays for the current scenario.
* '''replay_save''': whether a replay save for the current scenario is allowed, the default is replay_save=yes. If yes, the player's settings in preferences will be used to determine if a replay is saved. If no, will override and not save a replay.
* '''linger_mode''': If ...=yes, the screen is greyed out and there's the possibility to save before advancing to the next scenario, the default is linger_mode=yes.
* '''reveal_map''': (Multiplayer only) (Default is 'yes') If 'no', shroud doesn't disappear when game ended.
* '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
* '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
* '''carryover_add''': if yes the gold will be added to the starting gold the next scenario, if no the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is no.
* '''music''': (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.
* '''end_credits''': Whether to display the credits screen at the end of a single-player campaign. Defaults to ''yes''. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* <strike>'''[next_scenario_settings]''': Any tags or attribute children of this optional argument to [endlevel] are merged into the scenario/multiplayer tag of the *next* scenario. This allows you to e.g. reconfigure the [side] tags or settings, just before load. </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* <strike>'''[next_scenario_append]''': Any tags of this optional argument are appended at high level to the next scenario. This is most appropriate for [event] tags, although you may find other uses. Example test scenario for these features: https://gna.org/support/download.php?file_id=20119 </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* '''[result]''' {{DevFeature1.13|0}} Allows specification of a side specific result, this is for competitive multiplayer scenarios/campaigns where it might happen that one player wins but another player loses. The following attributes are accepted and have the same effect as in '''[endlevel]''':
** '''result'''
** '''bonus'''
** '''carryover_percentage'''
** '''carryover_add'''

And there is also
** '''side''' The number of the side for which these results should apply.

=== [unit] ===
Creates a unit (either on the map, on a recall list, or into a variable for later use.) For syntax see [[SingleUnitWML]].
* {{Short Note:Predefined Macro|GENERIC_UNIT}}

This tag can also recall an existing unit, which happens when:
* the '''id=''' attribute is used
* a unit with that '''id=''' already exists
* (might be unnecessary) the existing unit is on the side's recall list
in this case, the unit is recalled at the '''x,y=''' or '''location_id=''' given, and any other data in the tag is ignored.

Campaign authors: a usual way to recall plot-necessary heroes is to use a macro with the data for creating that hero. This helps during debugging, because you can skip to scenarios and the recall-or-create functionality means that any units which are normally met in a previous scenario are automatically created (otherwise some scenarios may be an instant loss). This can only be used for units that must survive the previous scenarios, as it would recreate units if they died in a previous scenario.
For example,
[https://github.com/wesnoth/wesnoth/blob/1.14.7/data/campaigns/Heir_To_The_Throne/utils/httt_utils.cfg#L685 HttT's NEED_DELFADOR macro].

=== [recall] ===
Recalls a unit taking into account any [[SingleUnitWML|filter_recall]] of the leader. The unit is recalled free of charge, and is placed near its leader, e.g., if multiple leaders are present, near the first found which would be able to normally recall it.

If neither a valid map location is provided nor a leader on the map would be able to recall it, the tag is ignored.

* [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored. Do not use a [filter] tag. If a comma separated list is given, every unit currently considered for recall is checked against all the types (not each single one of the types against all units).
* '''x,y''': the unit is placed here instead of next to the leader.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to recall to. Used instead of '''x,y'''.
* '''show''': yes/no, default yes: whether the unit is animated (faded in) or instantly displayed
* '''fire_event''': boolean yes|no (default no); whether any according prerecall or recall events shall be fired.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit (a nearby passable hex is chosen).
* '''[secondary_unit]''': {{DevFeature1.13|?}} If present and show=yes, a matching unit will be chosen and their recruiting animation played.

=== [teleport] ===
Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
* '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.
* '''x,y''': the hex to teleport to. If that hex is occupied, the closest unoccupied hex will be used instead.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to teleport to. Used instead of '''x,y'''.
* '''clear_shroud''': should shroud be cleared on arrival
* '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)
* '''check_passability''': (boolean yes|no, default yes): normally, units will not be teleported into terrain that is impassable for them. Setting this attribute to "no" permits it.

(Note: There is also a ability named teleport, see [[AbilitiesWML]].)

=== [terrain_mask] ===
Changes the terrain on the map. See [[TerrainMaskWML]].

=== [terrain] ===
Changes the terrain on the map.
* '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
* [[StandardLocationFilter]]. This [[StandardLocationFilter]]'s terrain= key is used for the new terrain, filtering by terrain can be done with a nested [[StandardLocationFilter]]: [and]terrain=terrain_string_to_be_filtered_for.
* '''layer''': (overlay|base|both, default=both) only change the specified layer.
* '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.
* '''location_id''': This key sets a string as a way to mark the hex or hexes for later reference. It is very similar to the leader starting position, and can also be set that way in the map editor.

If you want to remove the overlays from a terrain and leave only the base, use:
layer=overlay
terrain="^"

Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages is that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [gold] ===
Gives sides gold.
* '''amount''': the amount of gold to give.
* '''side''': (default=1) the number of the side to give the gold to. Can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [unstore_unit] ===
Creates a unit from a game variable, and activates it on the playing field or recall list. This must be a specific variable describing a unit, and may not be an array (if it is, only the first unit will be unstored).

This may be useful in different contexts:
* To update a unit on the map after having edited its WML. This usage is common, but discouraged - if possible, you should use [[#.5Bmodify_unit.5B|[modify_unit]]] or [[#.5Bobject.5B|[object]]] instead.
* To place a previously-defined unit into the scenario, if it was directly defined in a WML variable, using [unit] with the key '''to_variable'''. This usage is rather uncommon.
* To place a unit back into the game that was removed earlier, for example a hero that leaves the party for awhile and then comes back.

The variable is not cleared. To unstore units from an array variable, iterate over the array. See [[VariablesWML]] and [[VariablesWML/How to use variables]] for more information about variable usage. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML|For]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].

The tag takes the following keys:
* '''variable''': This is required to indicate the name of the variable to read the unit from.
* '''Placement keys''':
** '''x''' ,'''y''': By default, the unit will be placed at the location specified in the variable, but if these keys are present, the unit will be placed at that location instead. To place the unit on the recall list of its side, use '''x,y=recall,recall'''. (If you want to change the said, you need to first update ''$unit.side'' in the variable before unstoring.)
** '''location_id''': {{DevFeature1.15|0}} The name of a special map location to unstore to. Used instead of '''x,y'''.
** '''find_vacant''' (yes|no, default no): Whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no' (default), then any unit on the same tile as the unit being unstored will be destroyed.
** '''check_passability''' (yes|no, default yes): Only relevant if '''find_vacant=yes'''. In that case, this determines whether game will try to find a passable tile for the unit. If set to no, the unit may be placed on an impassable tile. Note that if both '''find_vacant''' and '''check_passability''' are set, then the unit's position may be shifted even if there is not a unit on the target space, if that space is not passable for the unit.
* '''Animation keys''' (these determine the visual effect of how the unit is placed or updated):
** '''text''': (translatable) A floating text to display above the unit, such as a damage amount.
** '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
** '''red''', '''green''', '''blue''': (default=0,0,0) the color of the text. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
** '''animate''': (boolean yes|no, default yes) Determines whether to play any animations associated with the unstore. Currently this only affects the advancement animation ("levelout" and "levelin", defaulting to a fade to white and back) if the unit ends up advancing.
* '''Side-effect keys''' (these directly modify the behaviour of the action):
** '''advance''': (default=yes) if yes the unit is advanced if it has enough XP. When modifying XP, make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors, especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.
** '''fire_event''' (yes|no, default no): Whether any advance/post advance events shall be fired if an advancement takes place. This also affects whether the unit placed event is fired.

Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit—and killed—in combat.) The details of the unusual behavior are subject to change between stable releases without warning.

=== [allow_recruit] ===
Allows a side to recruit units it couldn't previously recruit. Any leader on this side will now be able to recruit the new units.
* '''type''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is being allowed to recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [allow_extra_recruit] ===
Allows a leader to recruit units it couldn't previously recruit.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[allow_recruit]'''.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [disallow_recruit] ===
Prevents a side from recruiting units it could previously recruit. No leader on this side will be able to recruit the specified units anymore, unless that leader has the same unit in their personal '''extra_recruit''' list.
* '''type''': the types of units that the side can no longer recruit. {{DevFeature1.13|0}} If omitted, all recruits for matching sides will be disallowed.
* '''side''': (default=1) the number of the side that may no longer recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [disallow_extra_recruit] ===
Prevents a leader from recruiting units it could previously recruit. This won't prevent the leader from recruiting that unit if the unit is in the '''[side]recruit=''' list – you must use '''[disallow_recruit]''' in that case.
* '''extra_recruit''': the types of units that the leader can no longer recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [set_recruit] ===
Sets the units a side can recruit. Any leader on this side will now be able to recruit these units.
* '''recruit''': the types of units that the side can now recruit.
* '''side''': The number of the side that is having its recruitment set. This can be a comma-separated list.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [set_extra_recruit] ===
Sets the units a leader can recruit.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[set_recruit]'''.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [modify_side] ===
Modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'''
* '''side''': (default=1) the number of the side that is to be changed. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* '''income''': the income given at the begining of each turn.
* '''recruit''': a list of unit types, replacing the side's current recruitment list.
* '''team_name''': the team in which the side plays the scenario.
* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
* '''side_name''': {{DevFeature1.13|?}} a translatable string representing the side leader's description.
* '''gold''': the amount of gold the side owns.
* '''village_gold''': the income setting per village for the side.
* '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag. warning: in multiplayer, changing the controller of a side might result in OOS during some events like, for example 'side_turn_end'; see [https://github.com/wesnoth/wesnoth/issues/2563 issue #2563].
* '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
* '''shroud''': a boolean string describing the status of Shroud for the side.
* '''hidden''': a boolean string specifying whether side is shown in status table.
* '''color''': a team color range specification, name (e.g. "red", "blue"), or number (e.g. "1", "2") for this side. The default color range names, numbers, and definitions can be found in data/core/team_colors.cfg.
* '''[ai]''': sets/changes AI parameters for the side. Only parameters that are specified in the tag are changed, this does not reset others to their default values. Uses the same syntax as described in [[AiWML]]. Note that [modify_side][ai] works for all simple AI parameters and some, but not all, of the composite ones. If in doubt, use [[AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag|[modify_ai]]]] instead, which always works. {{DevFeature1.13|?}} If this contains an '''ai_algorithm''', the AI parameters will be reset to those of the indicated AI before adding any additional parameters included in the tag. In other words, this allows replacing the AI config rather than appending to it.
* '''switch_ai''': replaces a side ai with a new AI from specified file(ignoring those AI parameters above). Path to file follows the usual WML convention.
* '''reset_maps''': If set to "yes", then the shroud is spread to all hexes, covering the parts of the map that had already been explored by the side, including hexes currently seen. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if shroud is on, but this is evaluated after shroud= (and before shroud_data=).
* '''reset_view''': If set to "yes", then the fog of war is spread to all hexes, covering the parts of the map that had already been seen this turn by the side, including hexes currently seen, excluding hexes affected by multi-turn {{tag|DirectActionsWML|lift_fog}}. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if fog is on, but this is evaluated after fog=.
* '''share_maps''': change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally
* '''share_view''': change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally
* '''share_vision''': change both the above at the same time
* '''shroud_data''': changes to the side's shroud, using the same format as when defining the [side].
* '''suppress_end_turn_confirmation''': Boolean value controlling whether or not a player is asked for confirmation when skipping a turn.
* '''scroll_to_leader''': Boolean value controlling whether or not the game view scrolls to the side leader at the start of their turn when present.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]).
* '''flag_icon''': Flag icon used for this side in the status bar (see [[SideWML|[side]]]).
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.
* '''defeat_condition''' {{DevFeature1.13|0}}: When the side is considered defeated (see [[SideWML|[side]]]).
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the side; uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* '''[variables]''' {{DevFeature1.15|3}} The contents of this tag is merged into the side's variables.

=== [modify_turns] ===
Modifies the turn limit in the middle of a scenario.
* '''value''': the new turn limit.
* '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
* '''current''': changes the current turn number after applying turn limit modifications, if any. It is not possible to change the turn number to exceed the turn limit (1 <= current turns <= max turns).

=== [allow_end_turn] ===
Allows human players to end their turn through the user interface if they were previously affected by the '''[disallow_end_turn]''' action. This action doesn't take any arguments.

=== [disallow_end_turn] ===
Disallows human players to end their turn through the user interface. This action doesn't require arguments.
* '''reason''' (translatable): {{DevFeature1.15|0}} Allows to optionally specify a reason.

=== [capture_village] ===
Changes the ownership of a village.
* [[StandardLocationFilter]]: all village locations matching the filter are affected.
* '''side''': the side that takes control of the village. This side needs to have a leader (canrecruit=yes). If the side key is not given, the village will become neutral (unless [filter_side] is present, in which case that side fiter decides, see below).
* '''[filter_side]''' with [[StandardSideFilter]] tags and keys as arguments; if both this tag and inline side= are present it's an error. Otherwise, the first matching side gets ownership (or the village becomes neutral if none match).
* '''fire_event''' (boolean yes|no, default: no): Whether any capture events shall be fired.

=== [kill] ===
Removes all units (including units in a recall list) that match the filter from the game.
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.
* '''animate''' (default 'no'): if 'yes', displays the unit dying (fading away). {{DevFeature1.13|8}} If '''[secondary_unit]''' is given, also plays the victory animation of that unit.
* '''fire_event''' (default 'no'): if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that events are only fired for killed units that have been on the map (as opposed to recall list).
* '''[secondary_unit]''' with a [[StandardUnitFilter]] as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes ({{DevFeature1.13|8}} or if it has a victory animation and animate=yes). The first on-map unit matching the filter becomes second_unit in any fired die and last breath events. If an on-map unit matches and if there are several units killed with a single [kill] tag, second_unit is this same unit for all of them. If no on-map unit matches or [secondary_unit] isn't present, the variable second_unit in each of the die and last breath events is always the same as the variable unit (the dying unit).
* '''[primary_attack]''' {{DevFeature1.13|8}} The attacker's weapon to use for matching the animation. Useful for example on the wose, whose death animation depends on the damage type it was killed by. If a secondary unit is specified, this is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the unit. However, if there is no secondary unit specified, it is instead treated as an [[UnitTypeWML#Attacks|weapon definition]], and the animation will be run as if an imaginary unit possessing that weapon was the attacker.
* '''[secondary_attack]''' {{DevFeature1.13|8}} Similar to the above, but for the defender's weapon. This is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the dying unit.

=== [move_unit] ===
Moves a unit along a path on the map. The path can be specified exactly, or as a series of waypoints that the unit will pass through.
* [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free location is chosen.
* '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.
* '''dir''' (string): {{DevFeature1.15|0}} Performs a relative movement instead of an absolute movement. For example, dir=n,n,nw will move two spaces north and then one space to the northwest. This is used instead of '''to_x''' and '''to_y'''.
* '''to_location''': {{DevFeature1.15|0}} Moves matching units to locations placed in the map editor with the "New Location" button. Can be a comma-separated list. This is used instead of '''to_x''' and '''to_y'''.
* '''check_passability''' (boolean yes|no, default yes): Whether the terrain the unit is moved to should be checked for suiting the unit. (If it does not, a nearby suitable hex is chosen.)
* '''force_scroll''': Whether to scroll the map or not even when [[InterfaceActionsWML#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to using [[InterfaceActionsWML#.5Bmove_unit_fake.5D|[move_unit_fake]]]'s default value.
* '''clear_shroud''': {{DevFeature1.15|0}} (boolean yes|no, default no) Whether to remove shroud and fog after the unit was moved, but before events are fired. It will not clear all alongside the path, only around the target destination.
* '''fire_event''' (boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.

=== [modify_ai] ===
Changes AI objects (aspects, goals, candidate actions or stages) for a specified side. See [[Modifying_AI_Components#The_.5Bmodify_ai.5D_Tag|Modifying AI Components]] for full description.

* '''action''' (string): Takes values 'add', 'change', 'delete' or 'try_delete' to do just that for the AI object.
* '''path''' (string): Describes which AI object is to be modified.
* '''[facet]''', '''[goal]''', '''[candidate_action]''' or '''[stage]''': Details about the AI object to be modified.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [modify_unit] ===
works similar to the MODIFY_UNIT macro.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.
* '''[object]''', '''[trait]''', {{DevFeature1.13|5}} '''[advancement]''' - The given modifications will be immediately applied to all units matching the filter. ([object] is described further [[#.5Bobject.5D|below]])
** '''delayed_variable_substitution''' {{DevFeature1.13|5}} (boolean yes|no, default no): If set to "yes", the wml block contained in this [object], [trait], or [advancement] is not variable-substituted at execution time of the event containing this [modify_unit]. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
** Do not use a '''[modifications]''' tag, as this may skip some of the special-case handling for newly added objects, traits and advancements, and will potentially overwrite existing modifications.
* '''[effect]''' {{DevFeature1.13|6}} Applies the effect directly to the unit. See [[EffectWML]].
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the unit (saved inside the unit's [variables] tag); uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the [[CommandMode|inspect command]]. Cannot remove things or add/alter unit animations. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify. Note that keys will be processed in arbitrary order, which may cause problems if you use formulas that depend on other formulas. To work around this you may need to use the tag twice with the same filter.
example usage (see also the test scenario):
<syntaxhighlight lang='wml'>
[modify_unit]
[filter]
x,y=38,6
[/filter]
hitpoints=10
{TRAIT_HEALTHY}
[/modify_unit]
</syntaxhighlight>

The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = "$($this_unit.hitpoints / 2)" to set the hitpoints of all units to half of their current value. This this_unit variable is independent from the this_unit variable available in the SUF used to determine which units to modify (first all matching units are gathered, and then all those are modified).

Modifying a unit ''may'' trigger an advancement event if the experience is set higher than the max_experience. However, this behaviour should not be relied upon to happen under all circumstances; if it's desired, the event should be triggered separately, for example with '''[transform_unit]'''.

'''Note:''' Some some properties of the units are reset sometimes (for example when the unit advances or when [remove_object] is called), so it's usually better to change them with [object] ([object] inside [modify_unit]) than to change those properties directly via [modify_unit]. The following properties are _not_ reset in [remove_object] and are thus safe to use directly in [modify_unit]:
* '''side'''
* '''gender'''
* '''name'''
* '''canrecruit'''
* '''unrenamable'''
* '''extra_recruit'''
* '''[variables]'''
* '''facing'''
* '''x, y'''
* '''goto_x, goto_y'''
* '''hitpoints'''
* '''experience'''
* '''moves'''
* '''[status]'''
* '''attacks_left'''
* '''role'''

=== [transform_unit] ===
Transforms every unit on the map matching the filter to the given unit type. Keeps intact hit points, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned. Hit points will be changed if necessary to respect the transformed unit's maximum hit points. Regardless of anything else, the unit will be rebuilt. Thus, transforming a unit to its current type is a way to force a rebuild, for example after manually removing a modification.
* [[StandardUnitFilter]]: do not use a [filter] tag.
* '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.

=== [petrify] ===

* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are petrified. Recall list units are included.

=== [unpetrify] ===
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are unpetrified. Recall list units are included.

=== [object] ===
Gives some unit an object which modifies their stats in some way. This tag can also be used in places that don't support ActionWML, such as [[#.5Bmodify_unit.5D|[modify_unit]]] or [[SingleUnitWML|[unit][modifications]]]. The following is supported in all these places:
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
* '''duration''':
**if 'scenario', effects only last until the end of the scenario.
**if 'forever' or not set, effects never wear off.
** if 'turn', effects only last until the start of the unit's next turn (when the unit refreshes movement and attacks). (Like other start-of-turn behavior, objects with a duration of "turn" won't expire before turn 2.)
** {{DevFeature1.13|1}} if 'turn end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* Other keys, such as '''id''', may be used to remove the object later, but are not used by the engine. An '''[object]''' tag can contain any arbitrary data that may be helpful to identify the object to remove later using a [[FilterWML#Filtering_on_WML_data|WML filter]].

The following is supported only when using '''[object]''' as ActionWML:
* '''id''': (Optional) By default, an object with a defined ID can only be picked up once per scenario, even if it is removed later or first_time_only=no is set for the event. You can remove this restriction by setting take_only_once=no. For filtering objects, it might be simpler to use a custom key such as item_id. The id string can contain only letters, numbers and underscores. The ID is also commonly used to manually remove the object later, for example with [[#.5Bremove_object.5D|[remove_object]]].
* '''take_only_once''': (default yes) {{DevFeature1.13|6}} If set to "no", the object's ID does not prevent it from being taken more than once.
* '''delayed_variable_substitution''' (boolean yes|no, default no): If set to "yes", the wml block contained in this [object] is not variable-substituted at execution time of the event where this [object] is within. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it tries to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed). Note that units on the recall list will not be checked. To add an [object] to a unit on the recall list you have to use '''[modify_unit][object]'''.
* '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[remove_item]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.
* '''silent''': whether or not messages should be suppressed. Default is "no". {{DevFeature1.13|2}} If no description is provided, this defaults to yes, but can still be overridden.
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.
* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.

=== [remove_object] ===
{{DevFeature1.13|6}}

Removes an object from matching units.

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching objects removed. Use no [filter] tag.
* '''object_id''': The id of the object to be removed.

Note that some unit properties are not restored ideally, e.g. current unit's health reversion might not work as expected (max_hitpoints will though). {{DevFeature1.15|0}} This was fixed.

Note that [remove_object] works the following way:

# Remove the object from the unit
# Rebuild the unit to make the changes effective.

Step 2 implies that changes done for example via [modify_unit] (or via the [store_unit] + [set_variable] + [unstore_unit] technique) will be reset if those changes change a property that is a property of the unit type. See the note under [[#.5Bmodify_unit.5D|[modify_unit]]] to get a list of properties that can safely be changed via [modify_unit].

=== [remove_trait] ===
{{DevFeature1.15|2}}

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching traits removed. Use no [filter] tag.
* '''trait_id''': The id of the trait to be removed. See [[UnitsWML#.5Btrait.5D|[trait]]].

=== [remove_shroud] ===
Removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to remove shroud. This can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles for which shroud should be removed

=== [place_shroud] ===
Places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to place shroud. This can be a comma-separated list. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles on which shroud should be placed

=== [lift_fog] ===
Lifts the fog of war from parts of the map for a certain side (only relevant for sides that have fog=yes), allowing a player to witness what occurs there even if that player has no units within vision range.
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the tiles from which fog should be lifted.
* '''multiturn''': ''yes/no, default:no''. The default (not multiturn) causes fog to be removed in the same way that normal vision works; the cleared tiles will remain cleared until fog is recalculated (which normally happens when a side ends its turn). When multiturn is set to "yes", the cleared tiles remain clear until {{tag||reset_fog}} cancels the clearing. This allows tiles to remain clear for multiple turns, or to be refogged before the end of the current turn (without also refogging all tiles). Multiturn lifted fog is not shared with allies (even when share_vision=all).

=== [reset_fog] ===
The primary use of this tag is to remove multiturn lifted fog (created by {{tag||lift_fog}}), which causes the fog to reset to what it would have been had WML not interfered. (That is, hexes that a side's units could not see at any point this turn will be re-fogged, while seen hexes remain defogged.)
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the fog reset will be restricted to these tiles.
* '''reset_view''': ''yes/no, default: no'' If set to "yes", then in addition to removing multiturn fog, the side's current view is canceled (independent of the SLF). This means that all hexes will become fogged for the side unless multiturn fog exists outside the tiles selected by the SLF. Normally, one would want the currently seen hexes to become clear of fog; this is done automatically at the end of many events, and it can be done manually with {{tag|InterfaceActionsWML|redraw}}.
Omitting both the SSF and the SLF would cancel all earlier uses of [lift_fog].
Additionally setting reset_view="yes" would cause the side's entire map to be fogged (unless an ally keeps hexes clear by sharing its view).

=== [allow_undo] ===
Normally when an event with a handler fires, the player's undo stack is cleared, preventing all actions performed so far from being undone. Including this tag in the event handler prevents the stack from being cleared for this reason, allowing the player to undo actions. (However, the stack might still be cleared for other reasons, such as fog being cleared or combat occurring.) In the common cases, this means '''[allow_undo]''' allows the current action to be undone even though an event was handled. There is a less common case, though — specifically when handling a menu item, where there is no current action — and in this case, '''[allow_undo]''' means merely that earlier actions can still be undone.
* Using this tag in a menu item has an additional side effect in 1.11. Starting with version 1.11.1, executing a WML menu item normally counts as doing something as far as the "you have not started your turn yet" dialog is concerned. However, a menu item whose handler includes '''[allow_undo]''' will not count.

The types of actions that can be undone are movement, recalling, and dismissing a unit from the recall list. If an action is undone, only the position (or existence) of the involved unit will be restored; any altered variables or changes to the game will remain changed after the action is undone. It is up to the scenario designer to avoid abusing this command.
* Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the action the first time.
* Although recalling can be undone, recruitment can not be undone; this seems to apply even when the recruit's traits are not randomly-generated (tested on 1.12.6 and 1.14.4+dev).

If an '''[event]''' uses both '''[allow_undo]''' and [[InternalActionsWML#.5Bfire_event.5D|'''[fire_event]''']] then the '''[allow_undo]''' must be after the '''[fire_event]'''.

Due to a bug in 1.12 ([http://web.archive.org/web/20170330000414/http://gna.org/bugs/?23323 https://gna.org/bugs/?23323]) '''[allow_undo]''' should not be used in events that use one of the following things because it might cause OOS:
* [message] with [option]s
* [get_global_variable]
* wesnoth.synchronize_choice

While in 1.13 using '''[allow_undo]''' together with those things won't give you a guaranteed OOS, there are some non-obvious situations where it will, for example assume the following event:

[event]
name="moveto"
[message]
message = "message"
[option]
label = "option 1"
[command]
[/command]
[/option]
[option]
label = "option 2"
[command]
[/command]
[/option]
[/message]
[allow_undo]
[/allow_undo]
[/event]

It will cause OOS when the message is undone: since the event is already executed (erased) on one client only , the clients will disagree about how many choices happen during the next moveto action.

=== [on_undo] ===
{{DevFeature1.13|2}}
Contains commands to execute when the player undoes the action which triggered the parent event.
*'''delayed_variable_substitution''' {{DevFeature1.13|5}}: ''yes/no, default no (always no before 1.13.5)'' As in [[EventWML]], specifies whether to perform variable substitution when the parent event is run, or when the contents are run. If delayed substitution is used, [[VariablesWML#Automatically_Stored_Variables|automatically stored variables]] from the parent event context are available, but may occasionally have unexpected values. (In particular, $unit.x and $unit.y may not have the expected value when undoing a move event, though $x1 and $y1 should be correct.)

Note:
It is not clear where whether the actionwml in [on_undo] in executed before or after the action is undone. Also, specially for enter/leave_hex events the units position when executing the [on_undo] code is usually different than when executing the original event. The recommended way to work around these issues is to refer to the unit by id instead of position and store all other needed information variables as 'upvalues'. You can also move the actual undo code to an external event. For example
[event]
name="undo_blah"
first_time_only=no
[store_unit]
id="$moved_unit_id"
[/store_unit]
... do undo stuff stuff
[/event]

...
... in some other event
[on_undo]
# store ''upvalues
{VARIABLE moved_unit_id $unit.id}
# call actual undo handler
[fire_event]
name = "undo_blah"
[/fire_event]
[on_undo]

=== [on_redo] ===
{{DevFeature1.13|2}}
Same as [on_undo], except executes the commands on redo. Note that the parent event is not triggered again on a redo.

{{DevFeature1.13|8}} [on_redo] is deprecated and has no effect anymore.

Note that [on_redo] is not guaranteed to be called when redoing an action, the engine might also decide to just fire the original events again.

=== [cancel_action] ===
Although Wesnoth 1.12 does not have this tag, it is the default behavior of '''enter_hex'''/'''exit_hex''' [event] in that version.

{{DevFeature1.13|9}} In this version, [cancel_action] is recognised, but has no effect (a bug).

{{DevFeature1.13|11}}
In an '''enter_hex'''/'''exit_hex''' [event], interrupt the movement, leaving the unit where it is. This is intended to be used with an event that gives the player new information, to let the player choose whether to change their plans. For example, if the player has commanded a unit to move from (1,1) to (3,3) and attack a unit on (4,4); then a [cancel_action] inside an '''enter_hex''' [event] on (2,2) would make the unit stop on (2,2). A [cancel_action] inside an enter_hex [event] on (3,3) would let the player choose whether to attack.

{{DevFeature1.15|0}}
In a '''capture'''/'''moveto''' [event], interrupt the attack.

=== [heal_unit] ===
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be less than the parameter '''amount''' if the unit is fully healed). $heal_amount contains only the number of hitpoints the first unit that was found got healed. When the variable is not needed, use {CLEAR_VARIABLE heal_amount} after this tag.

{{DevFeature1.17|0}} The '''$heal_amount''' variable is no longer set. Use the '''variable''' key instead.
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.
* '''[filter_second]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to yes) for each of the units healed.
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. This can't be used to set the unit's hitpoints below 1 or above the unit's maximum hitpoints. If "full", it fully heals the unit.
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)
* '''moves''': (integer, default 0) The maximum current movement points the units will be "healed". Can't set below 0 or above max_moves. If "full", sets moves to max_moves.
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable.
* '''variable''': {{DevFeature1.17|0}} creates an array with the given name; each item of the array has two fields, ''id='' (the ID of the unit being healed) and ''heal_amount='' (the amount of HPs the unit has been healed by).

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount. When harming multiple units, the special variable '''$this_unit''' can be used to access the current unit being harmed. This obviously does not work inside the filters though, as they give '''$this_unit''' a different meaning.
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.
* '''amount''': the amount of damage that will be done (required).
* '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.
* '''kill''': (default yes) if yes, when a harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.
* '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired. If yes, also the corresponding advance and post advance events are fired.
* '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense (or attack, if it's the harmer) and death animations. Special values supported, other than the usual yes and no, are "attacker", that means only the harmer will be animated, and "defender", that means only the harmed units will be animated. If the supplied value is yes, attacker or defender also advancement animations are played.
* '''[primary_attack], [secondary_attack]''': these set the weapon against which the harmed units will defend, and that the harming unit will use to attack, respectively (notice this is the opposite of '''[filter]''' and '''[filter_second]''' above). This allows for playing specific defense and attack animations. Both tags are expected to contain a [[FilterWML#Filtering_Weapons|Standard Weapon Filter]].
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.
* '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the ''harm_amount='' key. {{DevFeature1.17|0}} Each item of the array also has an ''id='' key, which contains the ID of the unit being harmed.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': (default yes) If there is a harmer, experience will be attributed similar to regular combat. Can take list of values. When any value is provided, all unspecified experience types default to not giving experience. Supported values: {{DevFeature1.17|25}} until that version only experience=yes and experience=no are supported
** no - none of involved units get any experience (this value only works if it is the only value in list)
** kill - the harming unit receives experience based on level of harmed unit in attack which kills harmed unit
** attack - the harming unit receives experience based on level of harmed unit in attack which does not kill harmed unit, or in attack which kills harmed unit while kill experience is disabled
** defend - the unit being harmed receives experience based on level of harming unit in attack which does not kill harmed unit
** fight - short form of experience=attack,defend
** yes - short form of experience=kill,attack,defend
* '''resistance_multiplier''': the harmed unit's resistance is multiplied by the supplied value; this means that a value lower than 1 increases it, and a value greater than 1 decreases it. Default value is 1, that means no modification.

=== [time_area] ===
How a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] tags in the [scenario] tag.
* [[StandardLocationFilter]]: the locations to affect. ''note: only for [event][time_area]s - at scenario toplevel [time_area] does not support [[StandardLocationFilter]], only location ranges''
* '''[time]''': one or more tags describing the new schedule, see [[TimeWML]].
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later or reference it from a location filter elsewhere. Can be a comma-separated list when removing time_areas, see below.
* '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.
* '''current_time''': The time slot number (starting with zero) active at the creation of the area.

''Example:'' (caves in parts of a map)
<syntaxhighlight lang=wml>
[time_area]
id = cave_area
x = 1-2,4-5
y = 1-2,1-2
{UNDERGROUND}
[/time_area]
</syntaxhighlight>

Specifying an id allows the area to be referenced from location filters. Example:
<syntaxhighlight lang=wml>
[time_area]
id = glyphs
x = 9,14
y = 11,3
[/time_area]
[event]
name = moveto
first_time_only=no
[filter]
side = 1
[filter_location]
area = glyphs
[/filter_location]
[/filter]
# Do something, for example healing the unit
[/event]
</syntaxhighlight>

=== [remove_time_area] ===

{{DevFeature1.13|2}}

This is a syntactic shortcut for [time_area] remove=.
* '''id''': Comma-separated list of time area ids to remove.

=== [end_turn] ===
End the current side's turn. The current event is finished before the turn is ended. Also, if the current event (where the tag appears) has been fired by another event, that event (and the complete stack of other possible parent events) is ended before [end_turn] comes into affect. Also, events following the event stack that fired [end_turn] are not omitted (e.g. [end_turn] is used by a side turn event and a turn refresh event does something afterwards).

=== [replace_map] ===

Replaces the entire map.
* '''map_data''': Content of a wesnoth map file. (This key used to be just '''map='''.) Example:
map_data="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"
* '''map_file''': {{DevFeature1.13|?}} Path to a Wesnoth map file; can be used instead of '''map'''. The file will be loaded when the tag is executed, rather than being embedded wholesale in the preprocessed WML. Example:
map_file=campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map
{{DevFeature1.15|3}} If the file is not found directly, it will be searched for in the [[BinaryPathWML|[binary_path]]]. Assuming a standard campaign or add-on layout, the example above can be replaced by:
map_file=01_The_Elves_Besieged.map
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.
* '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.
Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.
* '''current_time''': The time slot number (starting with zero) active at schedule replacement. ('''NB''': due to https://github.com/wesnoth/wesnoth/issues/5757 this attribute is ignored in versions 1.16.*. The fix was delivered in 1.17.* but wasn't backported due to backward-compatibility requirements)

=== [tunnel] ===

Create a tunnel between some locations, later usable by units to move from source hex to target hex (using the movement cost of unit on the target terrain).

'''Behavior Change as of Wesnoth 1.13.6:''' Vision is now possible (and enabled by default) through tunnels and allied units on the exit hex do not block a tunnel by default any more. This is done in order for moves through tunnels to be consistent with other moves. The previous behavior can still be accomplished by using the new optional keys listed below.

* '''[filter]''': (required) [[StandardUnitFilter]] the units which can use the tunnel. Leave empty for "all units".
* '''[source]''': (required) [[StandardLocationFilter]] the source hex(es). Use $teleport_unit to filter on unit being teleported.
* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es). Use $teleport_unit to filter on unit being teleported.
* '''id''': (optional) identifier for the tunnel, to allow removing.
* '''remove''': (boolean, default: no) If yes, removes all defined tunnels with the same ID (then only id= is necessary).
* '''bidirectional''': (boolean, default: yes) If yes, creates also a tunnel in the other direction.
* '''always_visible''': (boolean, default: no) If yes, the possible movement of enemies under fog can be seen.
* '''allow_vision''': (boolean, default: yes) {{DevFeature1.13|6}} If no, vision through a tunnel is not possible. Note that in that case the tunnel cannot be used if the tunnel exit is under shroud (which previously was ''always'' the case).
* '''pass_allied_units''': (boolean, default: yes) {{DevFeature1.13|6}} If no, allied (including own) units on the exit hex block a tunnel.
* '''delayed_variable_substitution''' (boolean, default: yes): If yes, the WML block contained in this [tunnel] is not variable-substituted at execution time of the event where this [tunnel] is within. Instead, variables are substituted when the tunnel is used by a unit. See [[EventWML#Nested_Events]]

(Note: The tunnel tag can also be used inside the [[AbilitiesWML|[teleport]]] ability, without remove= and id=).

=== [do_command] ===

{{DevFeature1.13|0}}

Executes a command, specified using the same syntax as a [command] tag in [[ReplayWML]]. Not all [command]'s are valid: only these are accepted

* [attack]
* [move]
* [recruit]
* [recall]
* [disband]
* [fire_event]
* [lua_ai] {{DevFeature1.13|12}} This has been removed and is replaced with [custom_command]

The tags corresponding to player actions generally use the same codepath as if a player had ordered it. That means for example that only moves that player would be allowed to do are possible, and movement is interrupted when sighting enemy unit.

One purpose of this tag is to allow scripting of noninteractive scenarios -- without a tag like this, this might require elaborate mechanisms to coerce ais in order to test these code paths.

This command should be replay safe if it is either invoked in a synced context, ''or'' invoked in code that is never synced, like AI code, a select event, or a menu item with `synced = false`. However, if you use desynchronized logic ''during'' an event that is otherwise synced, invoking [do_command] based on that desynchronized logic will result in out-of-sync errors during the replay; in this case, you must explicitly synchronize which command to do using something like the lua function wesnoth.sync.evaluate_single.

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

Puts a unit to the recall list of its side.
* '''[[StandardUnitFilter]]''': the unit(s) to get put to the recall list.
* '''heal''': (default=no) Whether the unit should be refreshed, similar to the unit moving to the recall list at the end of a scenario.

=== [set_achievement] ===

{{DevFeature1.17|13}}

Sets the specified achievement as completed and shows a popup stating it's been completed. The popup is not shown if the achievement has already been achieved.

* '''content_for''': The [[AchievementsWML#.5Bachievement_group.5D|[achievement_group]]] that this achievement is part of.
* '''id''': The id of the achievement.

=== [set_sub_achievement] ===

{{DevFeature1.17|17}}

Sets the specified sub-achievement as completed.

* '''content_for''': The [[AchievementsWML#.5Bachievement_group.5D|[achievement_group]]] that this achievement is part of.
* '''id''': The id of the achievement.
* '''sub_id''': The id of the sub-achievement.

=== [progress_achievement] ===

{{DevFeature1.17|13}}

Progress an achievement by the specified amount, with an optional limit for how far the achievement can be progressed.

* '''content_for''': The [[AchievementsWML#.5Bachievement_group.5D|[achievement_group]]] that this achievement is part of.
* '''id''': The id of the achievement.
* '''amount''': The amount to increment the achievement.
* '''limit''': (optional) Using this attribute will prevent achievements from progressing past this value.

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [https://www.wesnoth.org/macro-reference.html here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

LuaAPI/wesnoth

2024-11-06T23:38:20Z

White haired uncle: /* wesnoth.simulate_combat */ - Document weapon evaluation table values

<div class="tright"> __TOC__ </div>

The <tt>wesnoth</tt> module contains most of the core Wesnoth API. It is always loaded and available.

== Functions ==

=== wesnoth.dofile ===

* '''wesnoth.dofile'''(''file_path'', [...]) → ...

Loads and executes a file. The rules for locating the files are the same as for WML files, except that they require a ''.lua'' extension instead of ''.cfg.'' Any extra parameters to '''dofile''' are forwarded to the script (which can access them via the special <tt>...</tt> variable), and '''dofile''' returns all the values returned by the script.

=== wesnoth.require ===

* '''wesnoth.require'''(''module'') → ''module_contents''

Returns the contents of the specified module, loading it if necessary. The module can either be a simple name or a file path similar to that used by '''wesnoth.dofile'''. In addition, the ''.lua'' extension will automatically be appended if necessary. The module script is invoked with no arguments, and '''wesnoth.require''' then passes back its first return value, discarding any additional ones. If the module is a directory, then all lua files are loaded, and a table containing the resulting modules is returned, with the keys being the filenames minus the ''.lua'' extension.

'''wesnoth.require''' returns nil on failure, for example if it could not locate the module. If it did locate the module, but the module did not return anything (or returned nil), then '''wesnoth.require''' returns an empty table with a metatable that raises an error on any attempt to access it.

=== wesnoth.textdomain ===

* '''wesnoth.textdomain'''(''domain'') → ''textdomain_constructor''

Returns a callable userdata that can be used to construct translatable strings. A typical use is:

<syntaxhighlight lang=lua>
local _ = wesnoth.textdomain "example"
wesnoth.alert(_ "This is an example translated string!")
</syntaxhighlight>

The full syntax for using the result of this function is:

* ''textdomain_constructor''(''string'', [''string_plural'', ''number'']) → ''translatable_string''

By passing the optional arguments, you can vary the string based on a number that will be substituted into it. As with all Lua functions, the parentheses are optional when passing a single string argument, as in the above example. This plural syntax returns a form of the string that's grammatically suitable for the indicated number, but doesn't actually substitute the number in – you need to do that yourself with either '''string.format''' or '''stringx.vformat'''.

The returned translatable string can be treated in many ways like a regular string. Translatable strings can be compared with other translatable strings or concatenated with each other or with regular strings or integers. The length operator also works, though it should be noted that its value may change if the language is changed. If you need to pass a translatable string to a function that doesn't understand them, it can be converted to a regular string with tostring.

=== wesnoth.log ===

* '''wesnoth.log'''([''logger''], ''message'', ''in_chat'')

Logs a message to the console. These messages are normally not visible unless Wesnoth is run from the command-line or (in Windows) with the --wconsole switch. The in_chat argument, however, can be set to true to also echo the message to the in-game chat area.

''logger'' is the log level.

In any context, ''logger'' can be the standard log levels of '''info''', '''debug''', '''warning''', or '''error'''. Various abbreviations of the standard four are also recognised. The default logger is '''info'''.

In the game context, you can also set the ''logger'' to '''wml'''. The '''wml''' log level is special and is intended for WML errors; it always goes to chat, so the in_chat argument is ignored and can be omitted.

The logdomain to enable these logs depends on the context. In the game context, they are written to the '''wml''' logdomain. In other contexts, the logdomain is '''scripting/lua/user'''.

=== wesnoth.as_text ===

{{DevFeature1.15|10}}

* {{LuaGameOnly}} '''wesnoth.as_text'''(''value1'', ''value2'', ...)

Accept one or more values as arguments and returns them as a string. This is intended for use as an easy way to view the contents of lua tables. Using the returned string for any other purpose is not supported.

{{DevFeature1.17|0}} This is now available in all contexts.

=== wesnoth.simulate_combat ===

* {{LuaGameOnly}} '''wesnoth.simulate_combat'''(''attacker'', [''attacker_weapon_index''], ''defender'', [''defender_weapon_index'']) → ''attacker stats evaluation'', ''defender stats evaluation'', ''attacker weapon evaluation'', ''defender weapon evaluation''

Computes the hitpoint distribution and status chance after a combat between two units. The first unit is the attacker. The attacker does not have to be on the map, but its location should be meaningful - that is, it can be a private-to-Lua clone of a unit with the '''x''' and '''y''' values changed, but whatever it is it has to have '''x''' and '''y''' values that allow attacking the defender (with '''max_range''' of the attack set appropriately it's possible to simulate attacking non-adjacent units). The second unit is the defender; it has to be on the map.

Optional integers can be passed after each unit to select a particular weapon, otherwise the "best" one is selected. When giving the weapon, the parameter is the weapon number (integer, starting at 1) and not the attack definition.

The function returns four tables describing the evaluation of the combat. The first two contain an evaluation of the combatant's stats over the course of the fight, while the second two contains more detailed information on their weapons.

The stats evaluation tables contain the following keys:

* ''stats''.'''poisoned''' → ''probability''
* ''stats''.'''slowed''' → ''probability''
* ''stats''.'''untouched''' → ''probability''

The probability that the unit will be poisoned or slowed, or that it will survive with no damage taken. (A scenario where the unit's hitpoints increase counts as untouched.)

* ''stats''.'''average_hp''' → ''number''

The expected value of the unit's hitpoints after the fight.

* ''stats''.'''hp_chance''' → ''mapping of hp to probability''

The probability that the unit's hitpoints will be at a specific value after the fight. Though it looks almost like an array, it begins at index 0 unlike a typical Lua array. Thus, it's better understood as an associated mapping from the resulting hitpoints value to the probability of ending the combat with that value. Therefore, the value at index 0 represents the chance that the unit will die.

The weapon evaluation tables contain the following keys:

{| class="wikitable"
!Key !!Description
|-
|attack_num
| DEPRECATED (use '''number'''). Attack number (0 based, -1 for no attack).
|-
|chance_to_hit
|Effective chance to hit as a percentage (all factors accounted for).
|-
|damage
|Effective damage of the weapon (all factors accounted for).
|-
|drains
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|drains]] opponent when it hits.
|-
|drain_constant
|Base HP drained regardless of damage dealt.
|-
|drain_percent
|Percentage of damage recovered as health.
|-
|firststrike
|Attack has [[AbilitiesWML#The_.5Bspecials.5D_tag|firststrike]] special.
|-
|name
|Name (not description) of the attack.
|-
|number
|Attack number (1 based, 0 for no attack).
|-
|num_blows
|Effective number of blows (takes [[AbilitiesWML#The_.5Bspecials.5D_tag|swarm]] into account).
|-
|petrifies
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|petrifies]] opponent when it hits.
|-
|plagues
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|turns opponent into a zombie]] when fatal.
|-
|plague_type
|The [[AbilitiesWML#Extra_keys_used_by_the_.5Bplague.5D_special|plague type]] used by the attack, if any.
|-
|poisons
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|poisons]] opponent when it hits.
|-
|rounds
|[[AbilitiesWML#The_.5Bspecials.5D_tag|Berserk]] special can force us to fight more than one round.
|-
|slows
|Attack [[AbilitiesWML#The_.5Bspecials.5D_tag|slows]] opponent when it hits.
|}

<syntaxhighlight lang='lua'>
local function display_stats(n, t)
wesnoth.interface.add_chat_message(string.format(
"Chance for the %s\n to be slowed: %f,\n to be poisoned: %f,\n to die: %f.\nAverage HP: %f.",
n, t.slowed, t.poisoned, t.hp_chance[0], t.average_hp))
end
local att_stats, def_stats = wesnoth.simulate_combat(att, att_weapon, def, def_weapon)
display_stats("attacker", att_stats)
display_stats("defender", def_stats)

local att_stats, def_stats, att_weapon, def_weapon = wesnoth.simulate_combat(attacker, att_weapon_number, defender)
wesnoth.interface.add_chat_message(string.format(
"The attack %s should be countered with %s, which does %d damage, has %d%% chance to hit and forces %d attack rounds due to its berserk ability.",
att_weapon.name, def_weapon.name or "no weapon", def_weapon.damage, def_weapon.chance_to_hit, def_weapon.rounds))
</syntaxhighlight>

=== wesnoth.name_generator ===

* '''wesnoth.name_generator'''('''"markov"''', ''definition'', [''chain_size'', [''max_length'']]) → ''generator function''
* '''wesnoth.name_generator'''('''"cfg"''', ''definition'') → ''generator function''
* ''generator function''() → ''random name''

Constructs a name generator for use in generating names using either the Markov chain algorithm used in older versions of Wesnoth or the context-free grammar generator used since 1.13.5. The type parameter indicates which algorithm to use (either markov or cfg). The definition can be a string, just like it would be in a config file, or it can be formatted as a table. Additional parameters may be passed, depending on the type of generator. The function returns a callable userdata, which will return a new name each time it is called (with no parameters).

* '''Markov chain''': A Markov chain generator works by analyzing a list of input names and noticing tendencies in the way the letters are strung together. It can then apply those tendencies to produce new similar names that were not in the original list. Longer lists give better results. The definition is a list of names, formatted either as a comma-separated string or as an array-like table. The Markov generator can take two additional parameters.
** ''chain_size'': A value greater than 1 for the ''chain_size'' causes the analyzer to consider the words in chunks, which is similar to analyzing them syllable by syllable instead of letter by letter. The default chain size is 2, meaning that the analyzer treats words as consisting of 2-character syllables.
** ''max_length'': Places a cap on the total length of the name. The default value is 12 characters.
<syntaxhighlight lang=lua>
local markov_names = wesnoth.name_generator('markov', {'Kaasa', 'Kayya', 'Keyya', 'Kiira', 'Korra'}, 1)
print(markov_names(), markov_names(), markov_names())
</syntaxhighlight>
* '''Context-free grammar''': A [[context-free grammar]] is a way of specifying how strings can be constructed. The definition may be specified as a multi-line string, just as described in the preceding link, or it can be formatted as a table where the keys are non-terminals and the values are what they expand to. The expansion of each non-terminal can be formatted either as a |-separated list as described in the preceding link, or as an array-like table. (Mixing the two forms is permissible too.) The context-free generator has no additional parameters.
<syntaxhighlight lang=lua>
local cfg_names = wesnoth.name_generator('cfg', {
main = {'{prefix}{suffix}', '{prefix}{centre}{suffix}'},
prefix = 'Kaa|Ka|Ke|Kuu|Ko',
suffix = 'sa|yya|ra|rra',
centre = 'err|aash|eez|azz'
})
print(cfg_names(), cfg_names(), cfg_names())
</syntaxhighlight>

'''Note''': If you want to generate a name using any of the default generators, you can use the predefined generators in the [[LuaAPI/types#race|race]] instead of constructing one with this function.

=== wesnoth.compile_formula ===

* '''wesnoth.compile_formula'''(''formula'') → ''compiled formula''

Compiles a [[Wesnoth Formula Language]] formula into a Lua callable userdata. A compiled formula can be converted back to valid code using the built-in <code>tostring</code> function.

=== wesnoth.eval_formula ===

* '''wesnoth.eval_formula'''(''formula'', [''variables'']) → ''result''
* ''compiled formula''([''variables'']) → ''result''

Evaluate a [[Wesnoth Formula Language]] formula and return the result it computed (which can be '''nil''').

The passed in variables can be an arbitrary Lua table, which defines variables available to the formula. Unlike with WML tables, there is no restriction on the format of this table. The formula can access the variables as a list using the special WFL variable '''__list''', or as a map using the special WFL variable '''__map'''. Directly accessing keys on the table is also possible.

It is also possible to pass a unit proxy as the variables, which evaluates the formula in that unit's context just as if it had been used in a [[StandardUnitFilter]].

When calling '''wesnoth.eval_formula''', the first argument may either be an already-compiled formula or a string, in which case it will be automatically compiled on the fly.

<syntaxhighlight lang=lua>
local f = wesnoth.compile_formula('if(x > y, x - y, x + y)')

print(f{x=1,y=2}) -- prints 3.0
print(f{x=1,y=3}) -- prints 4.0
print(f{x=2,y=3}) -- prints 5.0
print(f{x=1,y=1}) -- prints 2.0
print(f{x=3,y=1}) -- prints 2.0
print(f{x=3,y=2}) -- prints 1.0
</syntaxhighlight>

=== wesnoth.version ===

* '''wesnoth.version'''(''version string'') → ''version''
* '''wesnoth.version'''(''major'', [''minor'', [''patch'']], [''suffix'')) → ''version''

Creates a version object, either by parsing a string or by building it from its component parts. The resulting version object can be compared with other version objects using the standard Lua comparison operators, which follows the same rules as the [[PreprocessorRef#.23ifver_and_.23ifnver|#ifver]] preprocessor statement. It can also be decomposed by accessing the following keys on the object:

* ''integer'': Grab any integer version component by index. A non-canonical version may have more than three components.
* '''major''': The major version number (index 1).
* '''minor''': The minor version number (index 2).
* '''revision''': The patch revision number (index 3).
* '''is_canonical''': True if the version has at most three components (plus an optional suffix).
* '''sep''': The character that separates the version components from the suffix (usually either + or nil).
* '''special''': The version suffix, for example the "dev" in "1.15.14+dev".

The version can be converted to a string using the built-in '''tostring''' function.

<syntaxhighlight lang=lua>
local function version_is_sufficient(required)
return wesnoth.current_version() >= required
end
local required = wesnoth.version "1.9.6"
if not version_is_sufficient(required) then
gui.alert(string.format("Your BfW version is insufficient, please get BfW %s or greater!", tostring(required)))
end
</syntaxhighlight>

=== wesnoth.current_version ===

* '''wesnoth.current_version'''() → ''current version''

Returns the current version of Wesnoth as a version object.

=== wesnoth.ms_since_init ===

* '''wesnoth.ms_since_init'''() → ''milliseconds''

This function returns the amount of milliseconds that have passed since Wesnoth started up the current session. Its only use is to track the passage of real time.

'''WARNING:''' this function uses the same code as [set_variable] time=stamp, and so it is MP-unsafe. It is provided only for benchmark purposes and AI development, although it should work inside wesnoth.synchronize_choice() as well.

=== wesnoth.deprecated_message ===

* '''wesnoth.deprecated_message'''(''element_name'', ''level'', ''version'', ''detail_message'')

Displays a deprecation warning in the Lua console. The level is an integer from 1 to 4 inclusive (see [[CompatibilityStandards#Deprecation_levels_-_When_to_remove_deprecated_features|deprecation levels]]), and the version can be left nil for levels 1 and 4. Otherwise it must be a version ''string'' (not a version object from [[#wesnoth.version|wesnoth.version]]).

=== wesnoth.deprecate_api ===

* '''wesnoth.deprecate_api'''(''original_name'', ''new_name'', ''level'', ''version'', ''element'', ''detail_message'') → ''deprecated wrapper''

Creates a deprecated wrapper for a function or table. A deprecated function will raise the deprecated message the first time it's called, and then suppress it thereafter. A deprecated table will raise the deprecated message the first time a key is read or assigned, and then suppress it thereafter.

The ''element'' is the function or table to wrap. It can be the original function or the new function (which may happen if the function was renamed without any interface changes), or a wrapper function that calls the new function while providing the interface of the old function. The ''level'' and ''version'' are as in [[#wesnoth.deprecated_message|wesnoth.deprecated_message]].

If ''level'' is 4, then the ''element'' is ignored (you can pass '''nil''') and a generic deprecated wrapper is returned that does nothing but raises the deprecated message the first time you call it, assign a key, or read a key, and suppresses it thereafter. This is intended for a function that was removed without deprecation, to leave behind a more informative message if someone still attempts to use it.

If Wesnoth is run with the <tt>--strict-lua</tt> command-line option, this function will return '''nil''' instead of the deprecated wrapper. Since the normal use-case of this function is to assign the deprecated wrapper to the original name, this has the effect of erasing any deprecated functions from the API.

The result of this function always contains a '''__deprecated''' attribute set to true, which can allow identifying if something is deprecated.

=== wesnoth.type ===

{{DevFeature1.17|?}}

* '''wesnoth.type'''(''value'') → ''type name''

Returns a string describing the value's type. This is the same as the built-in type function, except that it returns a more specific string in the case of userdata or tables, based on the metatable. For example, it would return 'unit' if called on a unit.

=== wesnoth.named_tuple ===

{{DevFeature1.17|?}}

* '''wesnoth.named_tuple'''(''array'', ''names'') → ''named tuple''

Decorates a numeric based array so that the indices can be accessed by name instead of by index. This function is used internally for a number of things, most notably map locations and WML tags. Most end-users will not need to use it, but it could be useful if you wish to build a Lua API that returns locations (or similar data) in the engine-standard format.

For example:

<syntaxhighlight lang=lua>
local t = wesnoth.named_tuple({42,21,36}, {'x', 'y', 'z'})

print(t[1]) -- prints 42
print(t[2]) -- prints 21
print(t[3]) -- prints 36
print(t.x) -- prints 42
print(t.y) -- prints 21
print(t.z) -- prints 36
</syntaxhighlight>

=== wesnoth.get_language ===

* '''wesnoth.get_language'''() → ''string''

Gets the language the UI is currently set to. Note that this may return an empty string if using the system default language.

=== wesnoth.print_attributes ===

* '''wesnoth.print_attributes'''(''object'', [''function''])

Prints out a list of attributes that can be accessed on the object, excluding deprecated functionality. The function defaults to '''print''', and receives a formatted line usually containing multiple attributes. They are annotated by type – &fnof; for a function, &dagger; for a table, ! if there was an error attempting to determine the type (which includes write-only attributes). Other types are unannotated.

For tables, by default this iterates the table using '''pairs''' to discover the attributes available, walking the metatable hierarchy if there is an '''__index''' table and filtering out anything that contains a '''__deprecated''' attribute set to '''true'''. However, if finds a function as the '''__index''', and the table's metatable also has a member '''__dir''', it will be used instead. The '''__dir''' can either be an array of strings, or a function that returns an array of strings. It will automatically be sorted and have any duplicates filtered out.

For custom objects defined by the engine, there is special handling so that this function shows the correct result. For example, if used on a GUI2 widget object, it will show the attributes available for that type of widget, as well as the IDs of any sub-widgets that can be accessed by name.

In the Lua console only, this function can also be referenced by a shorter alias, '''dir'''.

== Hooks ==

=== wesnoth.persistent_tags ===

* {{LuaGameOnly}} '''wesnoth.persistent_tags'''.''action''.'''read''' ↔ '''function'''(''wml content'')
* {{LuaGameOnly}} '''wesnoth.persistent_tags'''.''action''.'''write''' ↔ '''function'''(''add_tag_function'')

This is an associative table defining tags that should be persisted in saved games. Each tag is itself a table containing two functions, read and write. The write function is called in <tt>on_load</tt> and passed a function as a parameter which takes a WML table and adds it to the saved game under the specified tag; the read function is called once per matching tag found in the saved game, and is passed a WML table of its contents. Note the asymmetry here: if you're saving an array, the write function is responsible for saving the entire array (and is only called once), while the read function is only responsible for loading one item (and is called several times).

Example:

<syntaxhighlight lang=lua>
local inventory = {}

function wesnoth.persistent_tags.inventory.read(cfg)
inventory[cfg.side] = cfg
end

function wesnoth.persistent_tags.inventory.write(add)
for i = 1, #wesnoth.sides do
add(inventory[i])
end
end
</syntaxhighlight>

Notice that you don't need to create <tt>wesnoth.persistent_tags.inventory</tt> as an empty table first; you can simply define the read and write functions.

=== wesnoth.wml_actions ===

* {{LuaGameOnly}} '''wesnoth.wml_actions'''.''action'' ↔ '''function'''(''wml parameters table'')

This is a hook table that exposes and defines WML actions. Each function in this table corresponds to a single ActionWML tag, allowing you to invoke tags, define custom tags, and even modify the behavior of built-in tags. The single argument to these functions is a WML table, the content of the tag.

<syntaxhighlight lang=lua>
function wesnoth.wml_actions.freeze_unit(cfg)
local unit_id = cfg.id or wml.error "[freeze_unit] expects an id= attribute."
local unit = wesnoth.units.get(unit_id)
if unit then unit.moves = 0 end
wesnoth.units.modify({ id = unit_id }, { moves = 0 })
end
</syntaxhighlight>

The new tag can now be used in plain WML code.

<syntaxhighlight lang=wml>
[freeze_unit]
id=Delfador
[/freeze_unit]
</syntaxhighlight>

You can override functions already assigned to the table. This is useful if you need to extend functionality of core tags. For instance, the following script overrides the [[InterfaceActionsWML#Other interface tags|[print]]] tag so that messages are displayed with a bigger font.

<syntaxhighlight lang=lua>
function wesnoth.wml_actions.print(cfg)
local modified_cfg = setmetatable({}, {__index = cfg})
modified_cfg.size = (cfg.size or 12) + 10
wesnoth.wml_actions.print(modified_cfg)
end
</syntaxhighlight>

An action handler should be able to handle being called with either a WML table or a WML vconfig userdata. It is recommended to pass the argument through ''wml.tovconfig'' before doing anything with it, both in the action's definition and when calling it directly (in case its definition did not do that). The engine always passes a vconfig when calling a WML action.

=== wesnoth.wml_conditionals ===

* {{LuaGameOnly}} '''wesnoth.wml_conditionals'''.''action'' ↔ '''function'''(''wml parameters table'') → ''boolean result''

This is a hook table like wesnoth.wml_actions. You can use it to define new ConditionalWML tags that will be recognized in WML when using [if], [show_if], [while], etc., or more generally when [[../wml#wml.eval_conditional|'''wml.eval_conditional''']] is run.

Use it like this:

<syntaxhighlight lang=lua>
function wesnoth.wml_conditionals.foo(cfg)
local bar = cfg.bar or wml.error("[foo] tag did not have 'bar' attribute")

return (bar == "baz")
end
</syntaxhighlight>

If this lua code is executed, it would make the following syntax be valid WML in your add-on:

<syntaxhighlight lang=wml>
[if]
[foo]
bar = $X
[/foo]
[then]
[message]
# ...
[/message]
[/then]
[/if]
</syntaxhighlight>

Note that the basic logic tags of ConditionalWML (true, false, and, or, not) do not pass through this table and cannot be overridden.

=== wesnoth.effects ===

* {{LuaGameOnly}} '''wesnoth.effects'''.''name'' ↔ '''function'''(''unit'', ''wml table'')
* {{LuaGameOnly}} '''wesnoth.effects'''.''name''.'''__descr''' ↔ ''description''
* {{LuaGameOnly}} '''wesnoth.effects'''.''name''.'''__descr''' ↔ '''function'''(''unit'', ''wml table'') → ''description''

This table contains the implementation of [[EffectWML|[effect]]]s. Each value is a callable value that takes a unit and the effect config. It can be a function or a callable table. If it is a callable table, its metatable may have a '''__descr''' field which is either a string or a function. Built-in effects are present in this table, and you may register your own custom effects too.

<syntaxhighlight lang='lua'>
function wesnoth.effects.min_resistance(u, cfg)
local resistance_new = {}
local resistance_old = wml.parsed(wml.get_child(cfg, "resistance"))
for k,v in pairs(resistance_old) do
if type(k) == "string" and type(v) == "number" and u:resistance_to(k) >= v then
resistance_new[k] = v
end
end
wesnoth.effects.resistance(u, {
apply_to = "resistance",
replace = true,
T.resistance (resistance_new),
})
end
</syntaxhighlight>

The code above adds a new <code>min_resistance</code> effect that will set the resistances to specific values if they are currently below that value. It can then be used like this (for example, in [[DirectActionsWML#.5Bobject.5D|[object]]]):

<syntaxhighlight lang='wml'>
[effect]
apply_to=min_resistance
[resistance]
cold=50
[/resistance]
[/effect]
</syntaxhighlight>

Note that in order work properly, effects must be registered before any units are created. This means it must be placed into a global or scenario level [lua] tag. In particular, the preload event is too late.

You can also specify description modifiers, which will be used if a custom effect is placed in a <code>[trait]</code> tag. Instead of setting a function as the effect, you set a table with a <code>__call</code> metafunction which does what the function would have done. The table can then have an additional <code>__descr</code> metafunction which updates descriptions as necessary. The built-in effects all use this structure. This metafunction takes the same arguments as the regular effect function, but should not modify the unit. Instead, it returns a string to be appended to the trait's effect description.

=== wesnoth.micro_ais ===

* {{LuaGameOnly}} '''wesnoth.micro_ais'''.''ai_name'' ↔ ''function''(''cfg'') → ''required'', ''optional'', ''ca_params''

Registers a new [[Micro_AIs#Custom_Micro_AIs|MicroAI]] with '''ai_type'''=''ai_name''. The function will be called by the [micro_ai] tag to set up the AI. See the link for more details on how this works.

=== wesnoth.custom_synced_commands ===

* {{LuaGameOnly}} '''wesnoth.custom_synced_commands'''.''command_name'' ↔ ''function''(''cfg'')

Registers a custom synced command, which can be invoked by AI to enable unusual behaviour. The command can do basically anything, and is guaranteed to run on all clients. The WML table passed to the callback is the same table passed to [[LuaAPI/wesnoth/sync#wesnoth.sync.invoke_command|wesnoth.sync.invoke_command]].

== Data ==

Access to most of the game data is available via various tables in the <tt>wesnoth</tt> module.

=== wesnoth.colors ===

{{DevFeature1.15|4}}

* {{LuaGameOnly}} '''wesnoth.colors'''.''color_name'' → ''color info''

Access defined [[GameConfigWML#Color_Palettes|color ranges]]. This can be used to translate the color name available from '''wesnoth.sides[n].color''' to RGB values.

Each color info table contains the following keys:

* '''mid''' - average shade for recoloring with the team color
* '''min''' - minimum shade for recoloring with the team color (this is likely to be black)
* '''max''' - maximum shade for recoloring with the team color (this is likely to be almost white)
* '''minimap''' - representative color to use on the mini-map
* '''pango_color''' - {{DevFeature1.15|13}} a hex string such as '''#ff0000''' suitable for use in formatted text

Each of '''mid''', '''min''', '''max''' and '''minimap''' have the following keys:

* '''r''' - red component of that color
* '''g''' - green component of that color
* '''b''' - blue component of that color
* '''a''' - alpha component of that color (probably fully opaque)

Reference usage in mainline: see data/multiplayer/eras.lua

=== wesnoth.current ===

Contains various information about the current game and event state.

* {{LuaGameOnly}} '''wesnoth.current.side''' → ''side number''

The number of the currently active side.

* {{LuaGameOnly}} '''wesnoth.current.turn''' → ''turn number''

The current turn number.

* {{LuaGameOnly}} '''wesnoth.current.synced_state''' → ''state''

Allows you to determine whether the current code runs in a synced context. Returns one of the following strings:

:* '''synced''' - The current code runs on all mp clients. This is the normal context, in which all gamestate changing actions should take place.
:* '''unsynced''' - The current code runs only on the local machine, so changing the gamestate here will cause out-of-sync errors. For example, during '''select''' events or during the calculation of a [[LuaAPI/wesnoth/interface#wesnoth.interface.game_display|game_display]] hook. Typical things to do here are UI related things, or entering the synced state via '''[do_command]'''.
:* '''local_choice''' - The current code was invoked by [[#wesnoth.synchronize_choice|synchronize_choice]] and runs only on one local client to calculate the return value for the choice. You cannot enter the synced context with '''[do_command]''' now.
:* '''preload''' - We are currently running a preload event or an even earlier event. This behaves similar to '''local_choice'''.

* {{LuaGameOnly}} '''wesnoth.current.user_can_invoke_commands''' → ''boolean''

Indicates whether the player is currently able to take actions in the game.

* {{LuaGameOnly}} '''wesnoth.current.map''' → ''map userdata''

The current active game map. See [[LuaAPI/types/map]] and [[LuaAPI/wesnoth/map]] for information on how this data can be used.

* {{LuaGameOnly}} '''wesnoth.current.schedule''' → ''schedule userdata''

The current global time schedule. This is a special object with the following properties:

:* #''schedule''
:The Lua length operator will return the number of turns in the schedule.

:* ''schedule''[''index''] ↔ ''time of day info''
:Get the information for a particular time of day, or replace it with new info.

:* ''schedule''.'''time_of_day''' ↔ ''id''
:Get the ID of the current active time of day, or switch to a new one. If the time of day occurs more than once in the schedule, the time will be set to the first occurrence.

:* ''schedule''.'''liminal_bonus''' ↔ ''bonus''
:Get the maximum bonus for liminal units in the current schedule. You can also override the default by assigning a different value, or revert to the default by assigning nil.

* {{LuaGameOnly}} '''wesnoth.current.event_context''' → ''WML table''

Contains information on the current active event. Returns a table with the following keys:

:* '''name''' - The event name. This is the actual event that fired, not the name in the [event] tag, so it never contains commas or variables.
:* '''id''' - The event's unique ID, if it has one.
:* '''weapon''' - The first weapon relevant to the event, if any.
:* '''second_weapon''' - The second weapon relevant to the event, if any.
:* '''damage_inflicted''' - The damage inflicted in the event, if applicable.
:* '''x1''', '''y1''' - The first location relevant to the event, if any.
:* '''x2''', '''y2''' - The second location relevant to the event, if any.
:* '''unit_x''', '''unit_y''' - The location of the first unit relevant to the event, if any. This is the same as '''x1''', '''y1''' in most cases. Currently the only exceptions are enter and exit hex events.
:* '''data''' - {{DevFeature1.17|6}} The event data. Can contain anything at all if the event was fired by [[LuaAPI/wesnoth/game_events#wesnoth.game_events.fire|wesnoth.game_events.fire]]. In a village capture event, '''owner_side''' will contain the former owner of the village.

=== wesnoth.game_config ===

Contains static global information about the game. Some of this information can also be modified on the fly, but only in the game context, not in the plugin or map generator context.

* '''wesnoth.game_config.base_income''' ↔ ''integer''
* '''wesnoth.game_config.village_income''' ↔ ''integer''
* '''wesnoth.game_config.village_support''' ↔ ''integer''
* '''wesnoth.game_config.poison_amount''' ↔ ''integer''
* '''wesnoth.game_config.rest_heal_amount''' ↔ ''integer'
* '''wesnoth.game_config.recall_cost''' ↔ ''integer''
* '''wesnoth.game_config.combat_experience''' ↔ ''integer''
* '''wesnoth.game_config.kill_experience''' ↔ ''integer''

Values of various game settings.

* '''wesnoth.game_config.global_traits'''[''trait id''] →

A table with named fields (trait id strings) holding the wml tables defining the traits. This contains all global traits the engine knows about, but race-specific traits are not included. The known fields and subtags of each element are the ones which were given in the wml definition of the [[SingleUnitWML|trait]].

<syntaxhighlight lang=lua>
print(wesnoth.game_config.global_traits.strong.male_name)
</syntaxhighlight>

* {{LuaGameOnly}} '''wesnoth.game_config.do_healing''' ↔ ''boolean''

Whether healing will occur at the beginning of each side's turn.

* {{LuaGameOnly}} '''wesnoth.game_config.theme''' ↔ ''theme id''

The currently active in-game theme.

* '''wesnoth.game_config.debug''' → ''boolean''

Whether debug mode is currently active. Debug mode is activated by the --debug command-line parameter or the :debug in-game command.

* '''wesnoth.game_config.debug_lua''' → ''boolean''

Whether Lua debug is enabled. Lua debug is activated by the --debug-lua command-line parameter. This does not seem to do anything by default.

* '''wesnoth.game_config.mp_debug''' → ''boolean''

Whether MP debug is enabled. MP debug is activated in the same way as debug mode, but is only active in multiplayer games.

* '''wesnoth.game_config.strict_lua''' → ''boolean''

Whether strict Lua mode is enabled. Strict Lua mode is activated by the --strict-lua command-line parameter and causes all deprecated Lua APIs to be completely removed from the engine.

* {{DevFeature1.19|4}} '''wesnoth.game_config.palettes'''.''palette'' → ''list of colors''

Returns the color palette with the given name, as defined by a '''[color_palette]''' tag in the [[GameConfigWML#Color_Palettes|game config]].

* {{DevFeature1.19|4}} '''wesnoth.game_config.red_green_scale''' → ''list of colors''

Returns the gradient used for health bars.

* {{DevFeature1.19|4}} '''wesnoth.game_config.red_green_scale_text''' → ''list of colors''

Returns the gradient used for health numbers.

* {{DevFeature1.19|4}} '''wesnoth.game_config.blue_white_scale''' → ''list of colors''

Returns the gradient used for experience bars.

* {{DevFeature1.19|4}} '''wesnoth.game_config.blue_white_scale_text''' → ''list of colors''

Returns the gradient used for experience numbers.

=== wesnoth.races ===

* {{LuaGameOnly}} '''wesnoth.races'''.''id'' → ''race info''

Access defined [[UnitsWML#.5Brace.5D|races]]. Returns a [[LuaAPI/types#Race|race userdata]].

=== wesnoth.scenario ===

Contains information about the current scenario

* {{LuaGameOnly}} '''wesnoth.scenario.turns''' ↔ ''turn limit''

The current turn limit of the scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.next''' ↔ ''scenario id''

The ID of the scenario to transition to when this scenario ends.

* {{LuaGameOnly}} '''wesnoth.scenario.id''' → ''scenario id''

The ID of the current scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.name''' →

The name of the current scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.defeat_music''' ↔ ''list of music tracks''

The music to play if you lose this scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.victory_music''' ↔ ''list of music tracks''

The music to play if you win this scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.show_credits''' ↔ ''boolean''

Whether credits should be shown when this scenario ends. Only relevant if '''wesnoth.scenario.next''' is nil.

* {{LuaGameOnly}} '''wesnoth.scenario.end_text''' ↔ ''text''

The end text to show when the scenario ends. Only relevant if '''wesnoth.scenario.next''' is nil.

* {{LuaGameOnly}} '''wesnoth.scenario.end_text_duration''' ↔ ''duration''

How long to show the end text for when the scenario ends. Only relevant if '''wesnoth.scenario.next''' is nil.

* {{LuaGameOnly}} '''wesnoth.scenario.difficulty''' → ''difficult''

The difficulty level this scenario is being played on.

* {{LuaGameOnly}} '''wesnoth.scenario.type''' → ''tag name''

The type of this scenario. One of the strings '''scenario''', '''multiplayer''', or '''test'''.

* {{LuaGameOnly}} '''wesnoth.scenario.era''' → ''era tag''

The [era] tag active in this scenario. Accessing this will throw an error in single-player games.

* {{LuaGameOnly}} '''wesnoth.scenario.campaign''' → ''campaign tag''

The [campaign] tag active in this scenario. Accessing this will throw an error in multiplayer or test games, so be sure to check '''wesnoth.scenario.type''' first in generic code.

* {{LuaGameOnly}} '''wesnoth.scenario.resources''' → ''list of resource tags''

A list of [resource] tags active in this scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.modifications''' → ''list of modification tags''

A list of [modification] tags active in this scenario.

* {{LuaGameOnly}} '''wesnoth.scenario.mp_settings''' → ''table''

In a multiplayer game, this is a proxy table which gives read only access to all MP-only configuration options which appear as attributes of [multiplayer] tag in a save game file. This allows accessing basically everything that can be set in the create game screen. The following keys exist in the returned table:

* '''active_mods''' - A list of all active modification IDs
* '''hash''' - A hash of mp data
* '''mp_campaign''' - Name of mp campaign
* '''mp_scenario''' - ID of this mp scenario
* '''mp_scenario_name''' - Name of this mp scenario
* '''scenario''' - MP lobby title
* '''difficulty_define''' - The campaign difficulty string for an mp campaign
* '''mp_village_gold'''
* '''mp_village_support'''
* '''mp_num_turns'''
* '''mp_era''' - The id of the chosen era
* '''mp_eras''' - A list of all era ids
* '''mp_fog'''
* '''mp_shroud'''
* '''mp_random_start_time'''
* '''experience_modifier'''
* '''mp_use_map_settings'''
* '''mp_countdown''' - Whether the timer is enabled
* '''mp_countdown_action_bonus'''
* '''mp_countdown_init_time'''
* '''mp_countdown_reservoir_time'''
* '''mp_countdown_turn_bonus'''
* '''observer'''
* '''shuffle_sides'''
* '''savegame''' - Whether this is a reloaded game
* '''side_users''' - List of how sides are assigned to users (at game start)

=== wesnoth.terrain_types ===

{{DevFeature1.15|12}}

* {{LuaGameOnly}} '''wesnoth.terrain_types'''[''code''] → ''terrain info''

Access defined [[TerrainWML|terrain types]] by their terrain code. Returns a table with the following keys:

* '''id'''
* '''name'''
* '''editor_name'''
* '''description'''
* '''icon'''
* '''editor_image'''
* '''light'''
* '''village'''
* '''castle'''
* '''keep'''
* '''healing'''

=== wesnoth.unit_types ===

* {{LuaGameOnly}} '''wesnoth.unit_types'''[''id''] → ''unit type info''

Access defined [[UnitTypeWML|unit types]] by their ID. Returns a [[LuaAPI/types#Unit_Type|unit type userdata]].

== Submodules ==

The <tt>wesnoth</tt> module also contains a number of submodules for working with particular aspects of the game.

=== wesnoth.audio ===

A [[LuaAPI/wesnoth/audio|submodule]] containing functions for playing music and sound effects.

=== wesnoth.achievements ===

A [[LuaAPI/wesnoth/achievements|submodule]] containing functions for working with in-game achievements.

=== wesnoth.game_events ===

A [[LuaAPI/wesnoth/game_events|submodule]] containing functions for working with event handlers.

=== wesnoth.map ===

{{DevFeature1.15|11}}

A [[LuaAPI/wesnoth/map|submodule]] containing functions for querying and manipulating the game map.

=== wesnoth.interface ===

{{DevFeature1.15|0}}

A [[LuaAPI/wesnoth/interface|submodule]] containing functions pertaining to the in-game UI.

=== wesnoth.paths ===

{{DevFeature1.15|0}}

A [[LuaAPI/wesnoth/paths|submodule]] containing functions related to pathfinding.

=== wesnoth.schedule ===

{{DevFeature1.15|14}}

A [[LuaAPI/wesnoth/schedule|submodule]] containing functions to manipulate the time of day schedule.

=== wesnoth.sides ===

{{DevFeature1.15|3}}

A [[LuaAPI/wesnoth/sides|submodule]] containing functions for manipulating the sides of a scenario.

=== wesnoth.sync ===

{{DevFeature1.15|14}}

A [[LuaAPI/wesnoth/sync|submodule]] containing functions to deal with multiplayer synchronization.

=== wesnoth.units ===

{{DevFeature1.15|0}}

A [[LuaAPI/wesnoth/units|submodule]] containing functions to manipulate units on the map.

[[Category: Lua Reference]]

== Unsupported Functions ==

The following functions exist in the '''wesnoth''' module but are not intended to be used:

* wesnoth.allow_undo
* wesnoth.cancel_action
* wesnoth.clear_menu_item
* wesnoth.set_menu_item
* wesnoth.kernel_type
* wesnoth.log_replay
* wesnoth.print
* wesnoth.redraw
* wesnoth.add_known_unit
* wesnoth.get_era
* wesnoth.get_resource

Some of these have WML equivalents, so if you need the functionality you should call the WML action directly (via [[#wesnoth.wml_actions|wml_actions]] or [[LuaAPI/wml#wml.fire|wml.fire]]). Others are internal functionality used in core Lua scripts, which are not intended for general use. These functions ''may'' be removed or changed without warning or going through a deprecation cycle.

Examination of the '''wesnoth''' module will also reveal two additional subtables - the '''package''' table, which is where packages loaded by [[#wesnoth.require|wesnoth.require]] persist (meaning you can force '''wesnoth.require''' to reload a file by nulling out its entry in this table), and the '''experimental''' module, which contains functions that are available for use but without warranty - they may change without warning or going through a deprecation cycle. Use of both of these tables is unsupported.

GUIWidgetInstanceWML

2024-11-06T14:03:24Z

White haired uncle: /* Label */

== Widget instance ==
Inside a grid (which is inside all container widgets) a widget is
instantiated. With this instantiation some more variables of a widget can
be tuned. This page will describe what can be tuned.

== Widget ==
All widgets placed in the cell have some values in common:
{| class="wikitable"
!key
!type
!default
!description
|-
| id
| [[GUIVariable#string|string]]
| ""
| This value is used for the engine to identify 'special' items. This means that for example a text_box can get the proper initial value. This value should be unique or empty. Those special values are documented at the window definition that uses them. NOTE items starting with an underscore are used for composed widgets and these should be unique per composed widget.
|-
| definition
| [[GUIVariable#string|string]]
| "default"
| The id of the widget definition to use. This way it's possible to select a specific version of the widget e.g. a title label when the label is used as title.
|-
| linked_group
| [[GUIVariable#string|string]]
| ""
| The linked group the control belongs to.
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| Most widgets have some text associated with them, this field contain the value of that text. Some widgets use this value for other purposes, this is documented at the widget. E.g. an image uses the filename in this field.
|-
| tooltip
| [[GUIVariable#t_string|t_string]]
| ""
| If you hover over a widget a while (the time it takes can differ per widget) a short help can show up.This defines the text of that message. This field may not be empty when 'help' is set.
|-
| help
| [[GUIVariable#t_string|t_string]]
| ""
| If you hover over a widget and press F10 (or the key the user defined for the help tip) a help message can show up. This help message might be the same as the tooltip but in general (if used) this message should show more help. This defines the text of that message.
|-
| use_tooltip_on_label_overflow
| [[GUIVariable#bool|bool]]
| true
| If the text on the label is truncated and the tooltip is empty the label can be used for the tooltip. If this variable is set to true this will happen.
|-
| debug_border_mode
| [[GUIVariable#unsigned|unsigned]]
| 0
| The mode for showing the debug border. This border shows the area reserved for a widget. This function is only meant for debugging and might not be available in all Wesnoth binaries. Available modes:
* '''0:''' no border.
* '''1:''' 1 pixel border.
* '''2:''' floodfill the widget area.
|-
| debug_border_color
| [[GUIVariable#color|color]]
| ""
| The color of the debug border.
|-
| size_text
| [[GUIVariable#t_string|t_string]]
| ""
| Sets the minimum width of the widget depending on the text in it. (Note not implemented yet.)
|}

== Button ==
A button is a control that can be pushed to start an action or close a dialog.

Instance of a button. When a button has a return value it sets the
return value for the window. Normally this closes the window and returns
this value to the caller. The return value can either be defined by the
user or determined from the id of the button. The return value has a
higher precedence as the one defined by the id. (Of course it's weird to
give a button an id and then override its return value.)

When the button doesn't have a standard id, but you still want to use the
return value of that id, use return_value_id instead. This has a higher
precedence as return_value.

List with the button specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

Supported values for return_value_id:
{| class="wikitable"
!string
!value
!description
|-
|"ok"||-1||Equivalent to closing the dialog by pressing the Enter key
|-
|"cancel"||-2||Equivalent to closing the dialog by pressing the Esc key
|-
|"quit"||-2||An alias for cancel
|-
|""||N/A||Clears any previously set return_value_id
|}

== Combobox ==
[[File:Combobox.png|frame|right|A Combobox with its list open]]
A widget with a text box and a dropdown list. Selecting an element from the list sets the value of the text box to that item of the list. The user can also manually enter a value in the text box.

{| class="wikitable"
|-
! key !! type !! default !! description
|-
| label || [[GUIVariable#string|string]] || "" || The text of the combobox
|-
| max_input_length || [[GUIVariable#int|int]] || 0 || Maximum length of text in characters that can be entered into the combobox
|-
| hint_text || [[GUIVariable#string|string]] || "" || Text that is shown in the background when there is no input
|-
| hint_image || [[GUIVariable#string|string]] || "" || Image that is shown in the background when there is no input

|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>combobox</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| icon || [[GUIVariable#string|string]] || "" || WML path to the icon to be shown alongside the text in this option, if any.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Drawing ==
A drawing is widget with a fixed size and gives access to the canvas of the widget in the window instance. This allows special display only widgets.

If either the width or the height is not zero the drawing functions as a
fixed size drawing.

{| class="wikitable"
!key
!type
!default
!description
|-
| width
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the drawing.
|-
| height
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the drawing.
|-
| draw
| [[GUIVariable#config|config]]
| mandatory
| The config containing the drawing.
|}

The variable available are the same as for the window resolution see
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
items.

== Grid Listbox ==
List with the listbox specific variables:
{| class="wikitable"
!ID (return value)
!Type
!Mandatory
!Description
|-
| vertical_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIToolkitWML#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIToolkitWML#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, more than one row can be selected.
|}

== Horizontal listbox ==
A horizontal listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version orders them in columns instead.

List with the horizontal listbox specific variables:
{| class="wikitable"
!ID (return value)
!Type
!Mandatory
!Description
|-
| vertical_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIToolkitWML#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIToolkitWML#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, more than one row can be selected.
|}

In order to force widgets to be the same size inside a horizontal listbox,
the widgets need to be inside a linked_group.

Inside the list section there are only the following widgets allowed
* grid (to nest)
* selectable widgets which are
** toggle_button
** toggle_panel

== Image ==
An image shows a static image whose path is specified by its '''[[GUIWidgetInstanceWML#Widget|label]]''' key. Unlike other widgets, the '''label''' key here is not translatable since it specifies a path. The path is a standard WML path, i.e., <code>label="units/konrad.png"</code> or <code>label="~add-ons/MyAddon/image/test.png"</code>.

It has no other extra fields.

== Label ==
A label displays text provided via the '''[[GUIWidgetInstanceWML#Widget|label]]''' key that can be wrapped but no scrollbars are provided. For a version with scrollbars, see the [[GUIWidgetInstanceWML#Scroll_Label|Scroll Label]] widget.

[[File:Title Label.png|frame|right|A Label with definition "title"]]

List with the label specific variables:
{| class="wikitable"
!key !!type !!default !!description
|-
| wrap || [[GUIVariable#bool|bool]] || false || Is wrapping enabled for the label.
|-
| characters_per_line || [[GUIVariable#unsigned|unsigned]] || 0 || Sets the maximum number of characters per line. The amount is an approximation since the width of a character differs. E.g. iii is smaller than MMM. When the value is non-zero it also implies '''wrap''' is true.
When having long strings, wrapping them can increase readability. A rule of thumb is 66 characters per line is considered the optimum for a one column text.
|-
| text_alignment || [[GUIVariable#h_align|h_align]] || left || The way the text is aligned inside the canvas.
|-
| can_shrink || [[GUIVariable#bool|bool]] || false || Whether the label can shrink past its optimal size.
|-
| link_aware || [[GUIVariable#bool|bool]] || false || Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
|}

== Listbox ==
A listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version might allow more options for ordering the items in the future.

List with the listbox specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIVariable#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIVariable#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIVariable#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIVariable#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIVariable#bool|bool]]
| true
| If false, more than one row can be selected.
|}

In order to force widgets to be the same size inside a listbox, the widgets
need to be inside a linked_group.

Inside the list section there are only the following widgets allowed
* grid (to nest)
* selectable widgets which are
** toggle_button
** toggle_panel

== Matrix ==
List with the matrix specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|}

== Menu Button ==
[[File:Menu Button.png|thumb|left|A Menu Button with it's list open.]]
A button that shows a dropdown list when clicked. The user can select any one of the predefined options.
{| class="wikitable"
!key
!type
!default
!description
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>menu_button</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| icon || [[GUIVariable#string|string]] || "" || WML path to the icon to be shown alongside the text in this option, if any.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Minimap ==
A minimap to show the gamemap, this only shows the map and has no interaction options. This version is used for map previews, there will be a another version which allows interaction.

A minimap has no extra fields.

== Multiline Text ==
Base class for a multiline text area. Not to be used directly in a GUI, use the [[GUIWidgetInstanceWML#Scroll_Text|scroll_text]] widget instead.

The following variables exist:
{| class="wikitable"
!key
!type
!default
!description
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| The initial text of the text box.
|-
| history
| [[GUIVariable#string|string]]
| ""
| The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
|-
| editable
| [[GUIVariable#bool|bool]]
| "true"
| If the contents of the text box can be edited.
|}

== Multimenu Button ==
[[File:Multimenu Button.png|thumb|right|A Multimenu Button with its list open]]
A widget clicking on which shows a list from which one or more options can be selected.

List with the multimenu_button specific variables:
{| class="wikitable"
!key !!type !!default !!description
|-
| return_value_id || [[GUIVariable#string|string]] || "" || The return value id.
|-
| return_value || [[GUIVariable#int|int]] || 0 || The return value.
|-
| maximum_shown || [[GUIVariable#int|int]] || -1 || The maximum number of currently selected values to list on the button.
|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>multimenu_button</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| checkbox || [[GUIVariable#bool|bool]] || "" || Whether the checkbox alongside this option is selected or not.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Multi page ==
A multi page is a control that contains several 'pages' of which only one is visible. The pages can contain the same widgets containing the same 'kind' of data or look completely different.

List with the multi page specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| page_definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a multi page item looks. It must contain the grid definition for at least one page.
|-
| page_data
| [[GUIVariable#section|section]]
| []
| A grid alike section which stores the initial data for the multi page. Every row must have the same number of columns as the 'page_definition'.
|}

== Panel ==
A panel is an item which can hold other items. The difference between a grid and a panel is that it's possible to define how a panel looks. A grid in an invisible container to just hold the items.

{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|}

== Password box ==
{| class="wikitable"
!key
!type
!default
!description
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| The initial text of the password box.
|}

== Progress bar ==
A progress bar shows the progress of a certain object.

A progress bar has no extra fields.

== Repeating button ==
A repeating_button is a control that can be pushed down and repeat a certain action. Once the button is down every x milliseconds it is down a new down event is triggered.

== Rich Label ==
A label that shows formatted text marked up with [[Help markup]]. It can show embedded images, links and tables inside text.

{| class="wikitable"
!key !!type !!default !!description
|-
| text_alignment || [[GUIVariable#h_align|h_align]] || left || The way the text is aligned inside the canvas.
|-
| width || [[GUIVariable#int|int]] || 500 || Width of its internal formatted content. Text will wrap beyond this width.
|-
| link_aware || [[GUIVariable#bool|bool]] || false || Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
|}

== Scroll label ==
A scroll label is a label that wraps its text and also has a vertical scrollbar. This way a text can't be too long to be shown for this widget.

List with the scroll label specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|}

== Scrollbar panel ==
Instance of a scrollbar_panel.

List with the scrollbar_panel specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a scrollbar_panel item looks. It must contain the grid definition for 1 row of the list.
|}

== Spacer ==
A spacer is a dummy item to either fill in a widget since no empty items are allowed or to reserve a fixed space.

If either the width or the height is non-zero the spacer functions as a
fixed size spacer.

{| class="wikitable"
!key !!type !!default !!description
|-
| width || [[GUIVariable#f_unsigned|f_unsigned]] || 0 || The width of the spacer.
|-
| height || [[GUIVariable#f_unsigned|f_unsigned]] || 0 || The height of the spacer.
|}

The variable available are the same as for the window resolution see
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
items.

== Tab Container ==

A container widget that can show its contents separated into various pages, each of which are accessible.

It can contain one or more <code>[tab]</code> tags inside it, each defining a tab's name, image (if any) and the contents of the tag, specified by the <code>[data]</code> tag inside the <code>[tab]</code> tag.

=== Subtag [tab] ===

{| class = "wikitable"
!key !!type !!default !!description
|-
| name || [[GUIVariable#t_string|t_string]] || "" || Name of the tab
|-
| image || [[GUIVariable#string|string]] || "" || Image for the tab to be shown alongside the name, if any
|-
| [data] || [[GUIVariable#grid|grid]] || empty grid || This subtag contains a grid that defines the contents for this tab.
|}

== Text box ==
A single line text entry widget.

[[File:Text Box.png|frame|right|A Text Box]]

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || The initial text of the text box.
|-
| history || [[GUIVariable#string|string]] || "" || The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
|-
| max_input_length || [[GUIVariable#int|int]] || 0 || Maximum length of text in characters that can be entered into the combobox
|-
| hint_text || [[GUIVariable#string|string]] || "" || Text that is shown in the background when there is no input
|-
| hint_image || [[GUIVariable#string|string]] || "" || Image that is shown in the background when there is no input
|-
| editable || [[GUIVariable#bool|bool]] || "true" || If the contents of the text box can be edited.
|}

== Toggle panel ==
A toggle panel is an item which can hold other items. The difference between
a grid and a panel is that it's possible to define how a panel looks. A grid
in an invisible container to just hold the items. The toggle panel is a
combination of the panel and a toggle button, it allows a toggle button with
its own grid.

Variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id, see [[GUIToolkitWML#Button]] for more information.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value, see [[GUIToolkitWML#Button]] for more information.
|}

== Tree view ==
A tree view is a control that holds several items of the same or different types. The items shown are called tree view nodes and when a node has children, these can be shown or hidden. Nodes that contain children need to provide a clickable button in order to fold or unfold the children.

List with the tree view specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| indention_step_size
| [[GUIVariable#unsigned|unsigned]]
| 0
| The number of pixels every level of nodes is indented from the previous level.
|-
| node
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The tree view can contain multiple node sections. This part needs more documentation.
|-
| id
| [[GUIVariable#unsigned|unsigned]]
| ""
| .
|-
| return_value_id
| [[GUIVariable#unsigned|unsigned]]
| ""
| .
|}

NOTE more documentation and examples are needed.

== Vertical scrollbar ==

== Viewport ==
A viewport is an special widget used to view only a part of the widget it `holds'.

List with the viewport specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grow_direction
| [[GUIVariable#grow_direction|grow_direction]]
| mandatory
| The direction in which new items grow.
|-
| parallel_items
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The number of items that are growing in parallel.
|-
| item_definition
| [[GUIVariable#section|section]]
| mandatory
| The definition of a new item.
|}

== Scroll Text ==
A multiline text area that shows a scrollbar if the text gets too long.

List with the scrollbar container specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| editable
| [[GUIVariable#bool|bool]]
| "true"
| If the contents of this scroll_text can be edited.
|}

== Slider ==

A slider is a control that can select a value by moving a grip on a groove.

{| class="wikitable"
!key
!type
!default
!description
|-
| best_slider_length
| [[GUIVariable#unsigned|unsigned]]
| 0
| The best length for the sliding part.
|-
| minimum_value
| [[GUIVariable#int|int]]
| 0
| The minimum value the slider can have.
|-
| maximum_value
| [[GUIVariable#int|int]]
| 0
| The maximum value the slider can have.
|-
| step_size
| [[GUIVariable#unsigned|unsigned]]
| 0
| The number of items the slider's value increases with one step.
|-
| value
| [[GUIVariable#int|int]]
| 0
| The value of the slider.
|-
| minimum_value_label
| [[GUIVariable#t_string|t_string]]
| ""
| If the minimum value is chosen there might be the need for a special value (eg off). When this key has a value that value will be shown if the minimum is selected.
|-
| maximum_value_label
| [[GUIVariable#t_string|t_string]]
| ""
| If the maximum value is chosen there might be the need for a special value (eg unlimited)). When this key has a value that value will be shown if the maximum is selected.
|}

== Toggle button ==
Variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

LuaAPI/types/widget

2024-11-05T16:24:27Z

White haired uncle: /* Widget methods */ - typo

<div class="tright"> __TOC__ </div>

The '''widget''' userdata offers access to a widget of a GUI2 dialog. While there is only one type of widget userdata that covers all widgets including the window itself, the properties of a widget userdata are different for each type of widget. Indexing a widget's userdata can either be used to access a child widget or to set or get a property of a widget. Some properties are read-only or write-only; the properties depend on the type of the widget.

An example of accessing a child widget:

<syntaxhighlight lang=lua>
function preshow(dialog)
local okay_button = dialog.okay_button
-- okay_button is now a handle to the the widget's child with the id 'okay_button'
end
</syntaxhighlight>

== Widget Attributes ==

=== selected ===

* ''widget''.'''selected''' ↔ ''boolean''
* Available on: '''[toggle_button]''', '''[toggle_panel]'''

Whether the item is selected or not. Note that this should only be used for widgets that have only 2 states. In particular, there exist 3-State toggle_buttons (for example in listbox headers). For those, selected_index must be used instead.

=== selected_index ===

* ''widget''.'''selected_index''' ↔ ''index''
* Available on: '''[listbox]''', '''[multi_page]''', '''[stacked_widget]''', '''[menu_button]''', '''[toggle_button]''', '''[toggle_panel]'''

The selected index of the item. For '''[toggle_button]''' and '''[toggle_panel]''', this is the same as '''selected''' only encoded as a number (1 for false or 2 for true) instead of a boolean.

For a '''[listbox]'''with '''has_maximum=false''' and more than one item selected, reading '''selected_index''' will return the first selected index.

For a '''[stacked_widget]''', only the layer specified by '''selected_index''' will be displayed and receive events (callbacks will only be triggered on the selected layer).
A '''selected_index''' of 0 represents all layers being selected, with events only being received by the layer with the highest index. Note that term ''selected'' for the ''layer'' of a stacked_widget is not the same as the '''selected''' ''widget'' attribute.

=== text ===

* ''widget''.'''text''' ↔ ''text''
* Available on: '''[text_box]'''

The text of the textbox.

=== value ===

* ''widget''.'''value''' ↔ ''position''
* Available on: '''[slider]'''

The current position of the slider.

=== percentage ===

* ''widget''.'''percentage''' ↔ ''position''
* Available on: '''[progress_bar]'''

The current position of the progress bar, between 0 and 100.

=== selected_item_path ===

* ''widget''.'''selected_item_path''' → ''array of indices''
* Available on: '''[tree_view]'''

A table describing the currently selected node. If for example, in the following treeview, Item 9 is selected, the result will be {2,1,3}.

+Section1
+Subsection11
*Item1
*Item2
*Item3
+Subsection12
*Item4
*Item5
*Item6
+Section2
+Subsection21
*Item7
*Item8
*Item9
+Subsection22
*Item10
*Item11
*Item12

=== path ===

* ''widget''.'''path''' → ''array of indices''
* Available on: '''[tree_view_node]'''

A table describing this node in the overall treeview. See [[#selected_item_path|selected_item_path]] for the meaning of the table..

=== unfolded ===

* ''widget''.'''unfolded''' ← ''boolean''
* Available on: '''[tree_view_node]'''

Control whether a tree node is currently expanded or not.

=== unit ===

* ''widget''.'''unit''' ← ''unit or unit type''
* Available on: '''[unit_preview_pane]'''

Change the displayed unit or unit type in the preview pane.

=== item_count ===

* ''widget''.'''item_count''' → ''number of items''
* Available on: '''[multi_page]''', '''[listbox]'''

The number of items in the container widget.

=== use_markup ===

* ''widget''.'''use_markup''' → ''boolean''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Sets whether the widget's label will parse [[Pango formatting]].

=== label ===

* ''widget''.'''label''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]''', '''[image]'''

The widget's label. Technically this is a special string used in the widget's wml definition. It usually does what one would expect, but also sets the image for '''image''' widgets. For '''[text_box]''', use '''text''' for initial values.

=== marked_up_text ===

* ''widget''.'''marked_up_text''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Shortcut for setting label and use_markup=yes.

=== enabled ===

* ''widget''.'''enabled''' ← ''boolean''
* Available on: Most widgets

=== tooltip ===

* ''widget''.'''tooltip''' ← ''text''
* Available on: Most widgets

=== visible ===

* ''widget''.'''visible''' ← ''visibility string''
* Available on: Most widgets

Determines whether the widget is visible onscreen. The following visibility statuses are recognized:
{| clasS="wikitable"
! String value !! Boolean shorthand !! Meaning
|-
| visible || true || The widget is visible and handles events.
|-
| hidden || || The widget is not visible, doesn't handle events, but still takes up space on the dialog grid.
|-
| invisible || false || The widget is not visible, doesn't handle events, and does not take up space on the dialog grid.
|}

=== type ===

* ''widget''.'''type''' → ''string''
* Available on: All widgets

Returns a string specifying the type of the widget.

== Widget callbacks ==

=== on_modified ===

* ''widget''.'''on_modified''' ← '''function'''()
* Available on: Most widgets, in particular '''[slider]''', '''[toggle_button]''', '''[listbox]''', '''[menu_button]''', '''[text_box]'''

Triggers when the user changes the value of the widget.

=== on_left_click ===

* ''widget''.'''on_left_click''' ← '''function'''()
* Available on: All widgets

Triggers when the user clicks on the widget.

=== on_button_click ===

* ''widget''.'''on_button_click''' ← '''function'''()
* Available on: '''[button]''', '''[repeating_button]'''

Triggers when the user clicks on the button. This can differ from '''on_left_click''', depending on the type of widget. For example, on a '''[repeating_button]''' it will fire multiple times if the user holds the mouse button down.

== Widget methods ==

Any function defined in the [[LuaAPI/gui/widget|gui.widget]] module and taking a widget as its first parameter can be called as a method of a widget. This includes any functions that are added to the module by user code. Note that these methods are available even if the widget itself doesn't support that function, so in some cases it may be necessary to check '''widget.type''' before calling the method.

[[Category:Lua Reference]]

LuaAPI/types/widget

2024-11-05T14:13:18Z

White haired uncle: /* selected_index */ - clarify stacked_widget

GUICanvasWML

2024-11-05T06:04:28Z

White haired uncle: /* Text */

== Canvas ==
A canvas is a blank drawing area on which the user can draw several shapes.
The drawing is done by adding WML structures to the canvas.

== Global Variables ==
These variables are available to all shapes inside the canvas, in addition to any local variables they may posess, if any.
{| border="1"
!Variable
!type
!description
|-
| width
| [[GUIVariable#unsigned|unsigned]]
| The width of the canvas.
|-
| height
| [[GUIVariable#unsigned|unsigned]]
| The height of the canvas.
|-
| text
| [[GUIVariable#tstring|tstring]]
| The text to render on the widget.
|-
| text_maximum_width
| [[GUIVariable#unsigned|unsigned]]
| The maximum width available for the text on the widget.
|-
| text_maximum_height
| [[GUIVariable#unsigned|unsigned]]
| The maximum height available for the text on the widget.
|-
| text_wrap_mode
| [[GUIVariable#int|int]]
| When the text doesn't fit in the available width there are several ways to fix that. This sets which method is used and possible values are the same as [https://docs.gtk.org/Pango/enum.EllipsizeMode.html here], that is, '''0''' (No elllipsization, wrap text instead), '''1''' (ellipsize start of text), '''2''' (ellipsize end of text), '''3''' (ellipsize at the middle). More details (slightly technical) are found at the Pango docs [https://docs.gtk.org/Pango/method.Layout.set_ellipsize.html here].
|-
| text_alignment
| [[GUIVariable#h_align|h_align]]
| The way the text is aligned inside the canvas.
|}

The size variables are copied to the window and will be determined at
runtime. This is needed since the main window can be resized and the dialog
needs to resize accordingly. The following variables are available:
{| border="1"
!Variable
!type
!description
|-
| screen_width
| [[GUIVariable#unsigned|unsigned]]
| The usable width of the Wesnoth main window.
|-
| screen_height
| [[GUIVariable#unsigned|unsigned]]
| The usable height of the Wesnoth main window.
|-
| gamemapx_offset
| [[GUIVariable#unsigned|unsigned]]
| The distance between left edge of the screen and the game map.
|-
| gamemap_width
| [[GUIVariable#unsigned|unsigned]]
| The usable width of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_width.
|-
| gamemap_height
| [[GUIVariable#unsigned|unsigned]]
| The usable height of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_height.
|-
| mouse_x
| [[GUIVariable#unsigned|unsigned]]
| The x coordinate of the mouse pointer.
|-
| mouse_y
| [[GUIVariable#unsigned|unsigned]]
| The y coordinate of the mouse pointer.
|-
| window_width
| [[GUIVariable#unsigned|unsigned]]
| The window width. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum width. If no maximum is wanted it should be set to the '"(screen_width)"'. - When not equal to 0 its value is the best width for the window. When the size should remain unchanged it should be set to '"(window_width)"'.
|-
| window_height
| [[GUIVariable#unsigned|unsigned]]
| The window height. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum height. If no maximum is wanted it should be set to the '"(screen_height)"'. - When not equal to 0 its value is the best height for the window. When the size should remain unchanged it should be set to '"(window_height)"'.
|}

Note when drawing the valid coordinates are: 
0 -> width - 1 
0 -> height -1

Drawing outside this area will result in unpredictable results including
crashing. (That should be fixed, when encountered.)

== Pre commit ==
This section contains the pre commit functions. These functions will be
executed before the drawn canvas is applied on top of the normal
background. There should only be one pre commit section and its order
regarding the other shapes doesn't matter. The function has effect on the
entire canvas, it's not possible to affect only a small part of the canvas.

The section can have one of the following subsections.

=== Blur ===
Blurs the background before applying the canvas. This doesn't make sense
if the widget isn't semi-transparent.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| depth
| [[GUIVariable#unsigned|unsigned]]
| 0
| The depth to blur.
|}

== Line ==
Definition of a line. When drawing a line it doesn't get blended on the
surface but replaces the pixels instead.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x1
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the startpoint.
|-
| y1
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the startpoint.
|-
| x2
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the endpoint.
|-
| y2
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the endpoint.
|-
| color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the line.
|-
| thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the line if 0 nothing is drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

== Bounded Shape ==
Common attributes of rectangles, round rectangles and text:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the rectangle.
|}

== Rectangle ==
Definition of a rectangle. When drawing a rectangle it doesn't get blended on
the surface but replaces the pixels instead. A blitting flag might be added
later if needed.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the rectangle.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the border if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the interior if omitted it's not drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

== Rounded Rectangle ==
Definition of a rounded rectangle shape.

When drawing a rounded rectangle it doesn't get blended on the surface but replaces the pixels instead. A blitting flag might be added later if needed.

{| border="1"
!key
!type
!default
!description
|-
| corner_radius
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The radius of the rectangle's corners.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border; if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the border; if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the interior; if omitted it's not drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation; this message is not stored.
|}

== Circle ==
Definition of a circle. When drawing a circle it doesn't get blended on
the surface but replaces the pixels instead. A blitting flag might be
added later if needed.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the center.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the center.
|-
| radius
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The radius of the circle if 0 nothing is drawn.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 1
| The thickness of the border; if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the border; if empty it's white.
|-
| fill_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the interior; if omitted it's not drawn.|-
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

Drawing outside the area will result in unpredictable results including
crashing. (That should be fixed, when encountered.)

== Image ==
Definition of an image.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the image, if not zero the image will be scaled to the desired width.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the image, if not zero the image will be scaled to the desired height.
|-
| resize_mode
| [[GUIVariable#resize_mode|resize_mode]]
| scale
| Determines how an image is scaled to fit the wanted size.
|-
| vertical_mirror
| [[GUIVariable#f_bool|f_bool]]
| false
| Mirror the image over the vertical axis. Deprecated, replaced by mirror.
|-
| mirror
| [[GUIVariable#f_bool|f_bool]]
| false
| Mirror the image over the vertical axis.
|-
| name
| [[GUIVariable#f_string|f_string]]
| ""
| The name of the image.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

Local Variables:
{| border="1"
!Variable
!type
!description
|-
| image_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the image, either the requested width or the natural width of the image. This value can be used to set the x (or y) value of the image. (This means x and y are evaluated after the width and height.)
|-
| image_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the image, either the requested height or the natural height of the image. This value can be used to set the y (or x) value of the image. (This means x and y are evaluated after the width and height.)
|-
| image_original_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the image as stored on disk, can be used to set x or w (also y and h can be set).
|-
| image_original_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the image as stored on disk, can be used to set y or h (also x and y can be set).
|}

== Text ==
Definition of text.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the text's bounding rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the text's bounding rectangle.
|-
| font_family
| [[GUIVariable#font_family|font_family]]
| "sans"
| The font family used for the text.
|-
| font_size
| [[GUIVariable#f_unsigned|f_unsigned]]
| mandatory
| The size of the text font.
|-
| font_style
| [[GUIVariable#font_style|font_style]]
| ""
| The style of the text.
|-
| text_alignment
| [[GUIVariable#f_h_align|f_h_align]]
| "left"
| The alignment of the text.
|-
| color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the text.
|-
| text
| [[GUIVariable#f_tstring|f_tstring]]
| ""
| The text to draw (translatable).
|-
| text_markup
| [[GUIVariable#f_bool|f_bool]]
| false
| Can the text have mark-up?
|-
| text_link_aware
| [[GUIVariable#f_bool|f_bool]]
| false
| Is the text link aware?
|-
| text_link_color
| [[GUIVariable#f_color|f_color]]
| "#ffff00"
| The color of links in the text
|-
| maximum_width
| [[GUIVariable#f_int|f_int]]
| -1
| The maximum width the text is allowed to be.
|-
| maximum_height
| [[GUIVariable#f_int|f_int]]
| -1
| The maximum height the text is allowed to be.
|-
| actions
| [[GUIVariable#string|string]]
| ""
| WFL code that will be executed when this shape is drawn. In particular, [[FormulaAI_Functions#.27set_var.27_function|set_var]] can be used here to store any variables mentioned in the variables section for global use inside the canvas.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

NOTE alignment could only be done with the formulas, but now with the
text_alignment flag as well, older widgets might still use the formulas and
not all widgets may expose the text alignment yet and when exposed not use
it yet.

Local Variables:
{| border="1"
!Variable
!type
!description
|-
| text_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the rendered text.
|-
| text_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the rendered text.
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

GUICanvasWML

2024-11-05T06:03:56Z

White haired uncle: /* Text */

== Canvas ==
A canvas is a blank drawing area on which the user can draw several shapes.
The drawing is done by adding WML structures to the canvas.

== Global Variables ==
These variables are available to all shapes inside the canvas, in addition to any local variables they may posess, if any.
{| border="1"
!Variable
!type
!description
|-
| width
| [[GUIVariable#unsigned|unsigned]]
| The width of the canvas.
|-
| height
| [[GUIVariable#unsigned|unsigned]]
| The height of the canvas.
|-
| text
| [[GUIVariable#tstring|tstring]]
| The text to render on the widget.
|-
| text_maximum_width
| [[GUIVariable#unsigned|unsigned]]
| The maximum width available for the text on the widget.
|-
| text_maximum_height
| [[GUIVariable#unsigned|unsigned]]
| The maximum height available for the text on the widget.
|-
| text_wrap_mode
| [[GUIVariable#int|int]]
| When the text doesn't fit in the available width there are several ways to fix that. This sets which method is used and possible values are the same as [https://docs.gtk.org/Pango/enum.EllipsizeMode.html here], that is, '''0''' (No elllipsization, wrap text instead), '''1''' (ellipsize start of text), '''2''' (ellipsize end of text), '''3''' (ellipsize at the middle). More details (slightly technical) are found at the Pango docs [https://docs.gtk.org/Pango/method.Layout.set_ellipsize.html here].
|-
| text_alignment
| [[GUIVariable#h_align|h_align]]
| The way the text is aligned inside the canvas.
|}

The size variables are copied to the window and will be determined at
runtime. This is needed since the main window can be resized and the dialog
needs to resize accordingly. The following variables are available:
{| border="1"
!Variable
!type
!description
|-
| screen_width
| [[GUIVariable#unsigned|unsigned]]
| The usable width of the Wesnoth main window.
|-
| screen_height
| [[GUIVariable#unsigned|unsigned]]
| The usable height of the Wesnoth main window.
|-
| gamemapx_offset
| [[GUIVariable#unsigned|unsigned]]
| The distance between left edge of the screen and the game map.
|-
| gamemap_width
| [[GUIVariable#unsigned|unsigned]]
| The usable width of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_width.
|-
| gamemap_height
| [[GUIVariable#unsigned|unsigned]]
| The usable height of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_height.
|-
| mouse_x
| [[GUIVariable#unsigned|unsigned]]
| The x coordinate of the mouse pointer.
|-
| mouse_y
| [[GUIVariable#unsigned|unsigned]]
| The y coordinate of the mouse pointer.
|-
| window_width
| [[GUIVariable#unsigned|unsigned]]
| The window width. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum width. If no maximum is wanted it should be set to the '"(screen_width)"'. - When not equal to 0 its value is the best width for the window. When the size should remain unchanged it should be set to '"(window_width)"'.
|-
| window_height
| [[GUIVariable#unsigned|unsigned]]
| The window height. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum height. If no maximum is wanted it should be set to the '"(screen_height)"'. - When not equal to 0 its value is the best height for the window. When the size should remain unchanged it should be set to '"(window_height)"'.
|}

Note when drawing the valid coordinates are: 
0 -> width - 1 
0 -> height -1

Drawing outside this area will result in unpredictable results including
crashing. (That should be fixed, when encountered.)

== Pre commit ==
This section contains the pre commit functions. These functions will be
executed before the drawn canvas is applied on top of the normal
background. There should only be one pre commit section and its order
regarding the other shapes doesn't matter. The function has effect on the
entire canvas, it's not possible to affect only a small part of the canvas.

The section can have one of the following subsections.

=== Blur ===
Blurs the background before applying the canvas. This doesn't make sense
if the widget isn't semi-transparent.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| depth
| [[GUIVariable#unsigned|unsigned]]
| 0
| The depth to blur.
|}

== Line ==
Definition of a line. When drawing a line it doesn't get blended on the
surface but replaces the pixels instead.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x1
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the startpoint.
|-
| y1
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the startpoint.
|-
| x2
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the endpoint.
|-
| y2
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the endpoint.
|-
| color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the line.
|-
| thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the line if 0 nothing is drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

== Bounded Shape ==
Common attributes of rectangles, round rectangles and text:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the rectangle.
|}

== Rectangle ==
Definition of a rectangle. When drawing a rectangle it doesn't get blended on
the surface but replaces the pixels instead. A blitting flag might be added
later if needed.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the rectangle.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the border if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the interior if omitted it's not drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

== Rounded Rectangle ==
Definition of a rounded rectangle shape.

When drawing a rounded rectangle it doesn't get blended on the surface but replaces the pixels instead. A blitting flag might be added later if needed.

{| border="1"
!key
!type
!default
!description
|-
| corner_radius
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The radius of the rectangle's corners.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border; if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the border; if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the interior; if omitted it's not drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation; this message is not stored.
|}

== Circle ==
Definition of a circle. When drawing a circle it doesn't get blended on
the surface but replaces the pixels instead. A blitting flag might be
added later if needed.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the center.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the center.
|-
| radius
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The radius of the circle if 0 nothing is drawn.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 1
| The thickness of the border; if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the border; if empty it's white.
|-
| fill_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the interior; if omitted it's not drawn.|-
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

Drawing outside the area will result in unpredictable results including
crashing. (That should be fixed, when encountered.)

== Image ==
Definition of an image.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the image, if not zero the image will be scaled to the desired width.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the image, if not zero the image will be scaled to the desired height.
|-
| resize_mode
| [[GUIVariable#resize_mode|resize_mode]]
| scale
| Determines how an image is scaled to fit the wanted size.
|-
| vertical_mirror
| [[GUIVariable#f_bool|f_bool]]
| false
| Mirror the image over the vertical axis. Deprecated, replaced by mirror.
|-
| mirror
| [[GUIVariable#f_bool|f_bool]]
| false
| Mirror the image over the vertical axis.
|-
| name
| [[GUIVariable#f_string|f_string]]
| ""
| The name of the image.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

Local Variables:
{| border="1"
!Variable
!type
!description
|-
| image_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the image, either the requested width or the natural width of the image. This value can be used to set the x (or y) value of the image. (This means x and y are evaluated after the width and height.)
|-
| image_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the image, either the requested height or the natural height of the image. This value can be used to set the y (or x) value of the image. (This means x and y are evaluated after the width and height.)
|-
| image_original_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the image as stored on disk, can be used to set x or w (also y and h can be set).
|-
| image_original_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the image as stored on disk, can be used to set y or h (also x and y can be set).
|}

== Text ==
Definition of text.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the text's bounding rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the text's bounding rectangle.
|-
| font_family
| [[GUIVariable#font_family|font_family]]
| "sans"
| The font family used for the text.
|-
| font_size
| [[GUIVariable#f_unsigned|f_unsigned]]
| mandatory
| The size of the text font.
|-
| font_style
| [[GUIVariable#font_style|font_style]]
| ""
| The style of the text.
|-
| text_alignment
| [[GUIVariable#f_h_align|f_h_align]]
| "left"
| The alignment of the text.
|-
| color
| [[GUIVariable#color|color]]
| ""
| The color of the text.
|-
| text
| [[GUIVariable#f_tstring|f_tstring]]
| ""
| The text to draw (translatable).
|-
| text_markup
| [[GUIVariable#f_bool|f_bool]]
| false
| Can the text have mark-up?
|-
| text_link_aware
| [[GUIVariable#f_bool|f_bool]]
| false
| Is the text link aware?
|-
| text_link_color
| [[GUIVariable#f_color|f_color]]
| "#ffff00"
| The color of links in the text
|-
| maximum_width
| [[GUIVariable#f_int|f_int]]
| -1
| The maximum width the text is allowed to be.
|-
| maximum_height
| [[GUIVariable#f_int|f_int]]
| -1
| The maximum height the text is allowed to be.
|-
| actions
| [[GUIVariable#string|string]]
| ""
| WFL code that will be executed when this shape is drawn. In particular, [[FormulaAI_Functions#.27set_var.27_function|set_var]] can be used here to store any variables mentioned in the variables section for global use inside the canvas.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

NOTE alignment could only be done with the formulas, but now with the
text_alignment flag as well, older widgets might still use the formulas and
not all widgets may expose the text alignment yet and when exposed not use
it yet.

Local Variables:
{| border="1"
!Variable
!type
!description
|-
| text_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the rendered text.
|-
| text_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the rendered text.
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

GUICanvasWML

2024-11-05T05:54:49Z

White haired uncle: /* Image */ - vertical_mirror depr

== Canvas ==
A canvas is a blank drawing area on which the user can draw several shapes.
The drawing is done by adding WML structures to the canvas.

== Global Variables ==
These variables are available to all shapes inside the canvas, in addition to any local variables they may posess, if any.
{| border="1"
!Variable
!type
!description
|-
| width
| [[GUIVariable#unsigned|unsigned]]
| The width of the canvas.
|-
| height
| [[GUIVariable#unsigned|unsigned]]
| The height of the canvas.
|-
| text
| [[GUIVariable#tstring|tstring]]
| The text to render on the widget.
|-
| text_maximum_width
| [[GUIVariable#unsigned|unsigned]]
| The maximum width available for the text on the widget.
|-
| text_maximum_height
| [[GUIVariable#unsigned|unsigned]]
| The maximum height available for the text on the widget.
|-
| text_wrap_mode
| [[GUIVariable#int|int]]
| When the text doesn't fit in the available width there are several ways to fix that. This sets which method is used and possible values are the same as [https://docs.gtk.org/Pango/enum.EllipsizeMode.html here], that is, '''0''' (No elllipsization, wrap text instead), '''1''' (ellipsize start of text), '''2''' (ellipsize end of text), '''3''' (ellipsize at the middle). More details (slightly technical) are found at the Pango docs [https://docs.gtk.org/Pango/method.Layout.set_ellipsize.html here].
|-
| text_alignment
| [[GUIVariable#h_align|h_align]]
| The way the text is aligned inside the canvas.
|}

The size variables are copied to the window and will be determined at
runtime. This is needed since the main window can be resized and the dialog
needs to resize accordingly. The following variables are available:
{| border="1"
!Variable
!type
!description
|-
| screen_width
| [[GUIVariable#unsigned|unsigned]]
| The usable width of the Wesnoth main window.
|-
| screen_height
| [[GUIVariable#unsigned|unsigned]]
| The usable height of the Wesnoth main window.
|-
| gamemapx_offset
| [[GUIVariable#unsigned|unsigned]]
| The distance between left edge of the screen and the game map.
|-
| gamemap_width
| [[GUIVariable#unsigned|unsigned]]
| The usable width of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_width.
|-
| gamemap_height
| [[GUIVariable#unsigned|unsigned]]
| The usable height of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_height.
|-
| mouse_x
| [[GUIVariable#unsigned|unsigned]]
| The x coordinate of the mouse pointer.
|-
| mouse_y
| [[GUIVariable#unsigned|unsigned]]
| The y coordinate of the mouse pointer.
|-
| window_width
| [[GUIVariable#unsigned|unsigned]]
| The window width. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum width. If no maximum is wanted it should be set to the '"(screen_width)"'. - When not equal to 0 its value is the best width for the window. When the size should remain unchanged it should be set to '"(window_width)"'.
|-
| window_height
| [[GUIVariable#unsigned|unsigned]]
| The window height. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum height. If no maximum is wanted it should be set to the '"(screen_height)"'. - When not equal to 0 its value is the best height for the window. When the size should remain unchanged it should be set to '"(window_height)"'.
|}

Note when drawing the valid coordinates are: 
0 -> width - 1 
0 -> height -1

Drawing outside this area will result in unpredictable results including
crashing. (That should be fixed, when encountered.)

== Pre commit ==
This section contains the pre commit functions. These functions will be
executed before the drawn canvas is applied on top of the normal
background. There should only be one pre commit section and its order
regarding the other shapes doesn't matter. The function has effect on the
entire canvas, it's not possible to affect only a small part of the canvas.

The section can have one of the following subsections.

=== Blur ===
Blurs the background before applying the canvas. This doesn't make sense
if the widget isn't semi-transparent.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| depth
| [[GUIVariable#unsigned|unsigned]]
| 0
| The depth to blur.
|}

== Line ==
Definition of a line. When drawing a line it doesn't get blended on the
surface but replaces the pixels instead.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x1
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the startpoint.
|-
| y1
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the startpoint.
|-
| x2
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the endpoint.
|-
| y2
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the endpoint.
|-
| color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the line.
|-
| thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the line if 0 nothing is drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

== Bounded Shape ==
Common attributes of rectangles, round rectangles and text:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the rectangle.
|}

== Rectangle ==
Definition of a rectangle. When drawing a rectangle it doesn't get blended on
the surface but replaces the pixels instead. A blitting flag might be added
later if needed.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the rectangle.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the border if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the interior if omitted it's not drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

== Rounded Rectangle ==
Definition of a rounded rectangle shape.

When drawing a rounded rectangle it doesn't get blended on the surface but replaces the pixels instead. A blitting flag might be added later if needed.

{| border="1"
!key
!type
!default
!description
|-
| corner_radius
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The radius of the rectangle's corners.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border; if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the border; if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the interior; if omitted it's not drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation; this message is not stored.
|}

== Circle ==
Definition of a circle. When drawing a circle it doesn't get blended on
the surface but replaces the pixels instead. A blitting flag might be
added later if needed.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the center.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the center.
|-
| radius
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The radius of the circle if 0 nothing is drawn.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 1
| The thickness of the border; if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the border; if empty it's white.
|-
| fill_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the interior; if omitted it's not drawn.|-
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

Drawing outside the area will result in unpredictable results including
crashing. (That should be fixed, when encountered.)

== Image ==
Definition of an image.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the image, if not zero the image will be scaled to the desired width.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the image, if not zero the image will be scaled to the desired height.
|-
| resize_mode
| [[GUIVariable#resize_mode|resize_mode]]
| scale
| Determines how an image is scaled to fit the wanted size.
|-
| vertical_mirror
| [[GUIVariable#f_bool|f_bool]]
| false
| Mirror the image over the vertical axis. Deprecated, replaced by mirror.
|-
| mirror
| [[GUIVariable#f_bool|f_bool]]
| false
| Mirror the image over the vertical axis.
|-
| name
| [[GUIVariable#f_string|f_string]]
| ""
| The name of the image.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

Local Variables:
{| border="1"
!Variable
!type
!description
|-
| image_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the image, either the requested width or the natural width of the image. This value can be used to set the x (or y) value of the image. (This means x and y are evaluated after the width and height.)
|-
| image_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the image, either the requested height or the natural height of the image. This value can be used to set the y (or x) value of the image. (This means x and y are evaluated after the width and height.)
|-
| image_original_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the image as stored on disk, can be used to set x or w (also y and h can be set).
|-
| image_original_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the image as stored on disk, can be used to set y or h (also x and y can be set).
|}

== Text ==
Definition of text.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the text's bounding rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the text's bounding rectangle.
|-
| font_family
| [[GUIVariable#font_family|font_family]]
| "sans"
| The font family used for the text.
|-
| font_size
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The size of the text font.
|-
| font_style
| [[GUIVariable#font_style|font_style]]
| ""
| The style of the text.
|-
| text_alignment
| [[GUIVariable#f_h_align|f_h_align]]
| "left"
| The alignment of the text.
|-
| color
| [[GUIVariable#color|color]]
| ""
| The color of the text.
|-
| text
| [[GUIVariable#f_tstring|f_tstring]]
| ""
| The text to draw (translatable).
|-
| text_markup
| [[GUIVariable#f_bool|f_bool]]
| false
| Can the text have mark-up?
|-
| text_link_aware
| [[GUIVariable#f_bool|f_bool]]
| false
| Is the text link aware?
|-
| text_link_color
| [[GUIVariable#f_string|f_string]]
| "#ffff00"
| The color of links in the text
|-
| maximum_width
| [[GUIVariable#f_int|f_int]]
| -1
| The maximum width the text is allowed to be.
|-
| maximum_height
| [[GUIVariable#f_int|f_int]]
| -1
| The maximum height the text is allowed to be.
|-
| actions
| [[GUIVariable#string|string]]
| ""
| WFL code that will be executed when this shape is drawn. In particular, [[FormulaAI_Functions#.27set_var.27_function|set_var]] can be used here to store any variables mentioned in the variables section for global use inside the canvas.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

NOTE alignment could only be done with the formulas, but now with the
text_alignment flag as well, older widgets might still use the formulas and
not all widgets may expose the text alignment yet and when exposed not use
it yet.

Local Variables:
{| border="1"
!Variable
!type
!description
|-
| text_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the rendered text.
|-
| text_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the rendered text.
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

GUICanvasWML

2024-11-05T05:49:16Z

White haired uncle: /* Rounded Rectangle */ - color > f_color

== Canvas ==
A canvas is a blank drawing area on which the user can draw several shapes.
The drawing is done by adding WML structures to the canvas.

== Global Variables ==
These variables are available to all shapes inside the canvas, in addition to any local variables they may posess, if any.
{| border="1"
!Variable
!type
!description
|-
| width
| [[GUIVariable#unsigned|unsigned]]
| The width of the canvas.
|-
| height
| [[GUIVariable#unsigned|unsigned]]
| The height of the canvas.
|-
| text
| [[GUIVariable#tstring|tstring]]
| The text to render on the widget.
|-
| text_maximum_width
| [[GUIVariable#unsigned|unsigned]]
| The maximum width available for the text on the widget.
|-
| text_maximum_height
| [[GUIVariable#unsigned|unsigned]]
| The maximum height available for the text on the widget.
|-
| text_wrap_mode
| [[GUIVariable#int|int]]
| When the text doesn't fit in the available width there are several ways to fix that. This sets which method is used and possible values are the same as [https://docs.gtk.org/Pango/enum.EllipsizeMode.html here], that is, '''0''' (No elllipsization, wrap text instead), '''1''' (ellipsize start of text), '''2''' (ellipsize end of text), '''3''' (ellipsize at the middle). More details (slightly technical) are found at the Pango docs [https://docs.gtk.org/Pango/method.Layout.set_ellipsize.html here].
|-
| text_alignment
| [[GUIVariable#h_align|h_align]]
| The way the text is aligned inside the canvas.
|}

The size variables are copied to the window and will be determined at
runtime. This is needed since the main window can be resized and the dialog
needs to resize accordingly. The following variables are available:
{| border="1"
!Variable
!type
!description
|-
| screen_width
| [[GUIVariable#unsigned|unsigned]]
| The usable width of the Wesnoth main window.
|-
| screen_height
| [[GUIVariable#unsigned|unsigned]]
| The usable height of the Wesnoth main window.
|-
| gamemapx_offset
| [[GUIVariable#unsigned|unsigned]]
| The distance between left edge of the screen and the game map.
|-
| gamemap_width
| [[GUIVariable#unsigned|unsigned]]
| The usable width of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_width.
|-
| gamemap_height
| [[GUIVariable#unsigned|unsigned]]
| The usable height of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_height.
|-
| mouse_x
| [[GUIVariable#unsigned|unsigned]]
| The x coordinate of the mouse pointer.
|-
| mouse_y
| [[GUIVariable#unsigned|unsigned]]
| The y coordinate of the mouse pointer.
|-
| window_width
| [[GUIVariable#unsigned|unsigned]]
| The window width. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum width. If no maximum is wanted it should be set to the '"(screen_width)"'. - When not equal to 0 its value is the best width for the window. When the size should remain unchanged it should be set to '"(window_width)"'.
|-
| window_height
| [[GUIVariable#unsigned|unsigned]]
| The window height. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum height. If no maximum is wanted it should be set to the '"(screen_height)"'. - When not equal to 0 its value is the best height for the window. When the size should remain unchanged it should be set to '"(window_height)"'.
|}

Note when drawing the valid coordinates are: 
0 -> width - 1 
0 -> height -1

Drawing outside this area will result in unpredictable results including
crashing. (That should be fixed, when encountered.)

== Pre commit ==
This section contains the pre commit functions. These functions will be
executed before the drawn canvas is applied on top of the normal
background. There should only be one pre commit section and its order
regarding the other shapes doesn't matter. The function has effect on the
entire canvas, it's not possible to affect only a small part of the canvas.

The section can have one of the following subsections.

=== Blur ===
Blurs the background before applying the canvas. This doesn't make sense
if the widget isn't semi-transparent.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| depth
| [[GUIVariable#unsigned|unsigned]]
| 0
| The depth to blur.
|}

== Line ==
Definition of a line. When drawing a line it doesn't get blended on the
surface but replaces the pixels instead.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x1
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the startpoint.
|-
| y1
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the startpoint.
|-
| x2
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the endpoint.
|-
| y2
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the endpoint.
|-
| color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the line.
|-
| thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the line if 0 nothing is drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

== Bounded Shape ==
Common attributes of rectangles, round rectangles and text:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the rectangle.
|}

== Rectangle ==
Definition of a rectangle. When drawing a rectangle it doesn't get blended on
the surface but replaces the pixels instead. A blitting flag might be added
later if needed.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the rectangle.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the border if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the interior if omitted it's not drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

== Rounded Rectangle ==
Definition of a rounded rectangle shape.

When drawing a rounded rectangle it doesn't get blended on the surface but replaces the pixels instead. A blitting flag might be added later if needed.

{| border="1"
!key
!type
!default
!description
|-
| corner_radius
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The radius of the rectangle's corners.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border; if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the border; if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the interior; if omitted it's not drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation; this message is not stored.
|}

== Circle ==
Definition of a circle. When drawing a circle it doesn't get blended on
the surface but replaces the pixels instead. A blitting flag might be
added later if needed.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the center.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the center.
|-
| radius
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The radius of the circle if 0 nothing is drawn.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 1
| The thickness of the border; if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the border; if empty it's white.
|-
| fill_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the interior; if omitted it's not drawn.|-
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

Drawing outside the area will result in unpredictable results including
crashing. (That should be fixed, when encountered.)

== Image ==
Definition of an image.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the image, if not zero the image will be scaled to the desired width.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the image, if not zero the image will be scaled to the desired height.
|-
| resize_mode
| [[GUIVariable#resize_mode|resize_mode]]
| scale
| Determines how an image is scaled to fit the wanted size.
|-
| vertical_mirror
| [[GUIVariable#f_bool|f_bool]]
| false
| Mirror the image over the vertical axis.
|-
| name
| [[GUIVariable#f_string|f_string]]
| ""
| The name of the image.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

Local Variables:
{| border="1"
!Variable
!type
!description
|-
| image_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the image, either the requested width or the natural width of the image. This value can be used to set the x (or y) value of the image. (This means x and y are evaluated after the width and height.)
|-
| image_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the image, either the requested height or the natural height of the image. This value can be used to set the y (or x) value of the image. (This means x and y are evaluated after the width and height.)
|-
| image_original_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the image as stored on disk, can be used to set x or w (also y and h can be set).
|-
| image_original_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the image as stored on disk, can be used to set y or h (also x and y can be set).
|}

== Text ==
Definition of text.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the text's bounding rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the text's bounding rectangle.
|-
| font_family
| [[GUIVariable#font_family|font_family]]
| "sans"
| The font family used for the text.
|-
| font_size
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The size of the text font.
|-
| font_style
| [[GUIVariable#font_style|font_style]]
| ""
| The style of the text.
|-
| text_alignment
| [[GUIVariable#f_h_align|f_h_align]]
| "left"
| The alignment of the text.
|-
| color
| [[GUIVariable#color|color]]
| ""
| The color of the text.
|-
| text
| [[GUIVariable#f_tstring|f_tstring]]
| ""
| The text to draw (translatable).
|-
| text_markup
| [[GUIVariable#f_bool|f_bool]]
| false
| Can the text have mark-up?
|-
| text_link_aware
| [[GUIVariable#f_bool|f_bool]]
| false
| Is the text link aware?
|-
| text_link_color
| [[GUIVariable#f_string|f_string]]
| "#ffff00"
| The color of links in the text
|-
| maximum_width
| [[GUIVariable#f_int|f_int]]
| -1
| The maximum width the text is allowed to be.
|-
| maximum_height
| [[GUIVariable#f_int|f_int]]
| -1
| The maximum height the text is allowed to be.
|-
| actions
| [[GUIVariable#string|string]]
| ""
| WFL code that will be executed when this shape is drawn. In particular, [[FormulaAI_Functions#.27set_var.27_function|set_var]] can be used here to store any variables mentioned in the variables section for global use inside the canvas.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

NOTE alignment could only be done with the formulas, but now with the
text_alignment flag as well, older widgets might still use the formulas and
not all widgets may expose the text alignment yet and when exposed not use
it yet.

Local Variables:
{| border="1"
!Variable
!type
!description
|-
| text_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the rendered text.
|-
| text_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the rendered text.
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

GUICanvasWML

2024-11-05T05:46:04Z

White haired uncle: /* Rectangle */ - color -> f_color

== Canvas ==
A canvas is a blank drawing area on which the user can draw several shapes.
The drawing is done by adding WML structures to the canvas.

== Global Variables ==
These variables are available to all shapes inside the canvas, in addition to any local variables they may posess, if any.
{| border="1"
!Variable
!type
!description
|-
| width
| [[GUIVariable#unsigned|unsigned]]
| The width of the canvas.
|-
| height
| [[GUIVariable#unsigned|unsigned]]
| The height of the canvas.
|-
| text
| [[GUIVariable#tstring|tstring]]
| The text to render on the widget.
|-
| text_maximum_width
| [[GUIVariable#unsigned|unsigned]]
| The maximum width available for the text on the widget.
|-
| text_maximum_height
| [[GUIVariable#unsigned|unsigned]]
| The maximum height available for the text on the widget.
|-
| text_wrap_mode
| [[GUIVariable#int|int]]
| When the text doesn't fit in the available width there are several ways to fix that. This sets which method is used and possible values are the same as [https://docs.gtk.org/Pango/enum.EllipsizeMode.html here], that is, '''0''' (No elllipsization, wrap text instead), '''1''' (ellipsize start of text), '''2''' (ellipsize end of text), '''3''' (ellipsize at the middle). More details (slightly technical) are found at the Pango docs [https://docs.gtk.org/Pango/method.Layout.set_ellipsize.html here].
|-
| text_alignment
| [[GUIVariable#h_align|h_align]]
| The way the text is aligned inside the canvas.
|}

The size variables are copied to the window and will be determined at
runtime. This is needed since the main window can be resized and the dialog
needs to resize accordingly. The following variables are available:
{| border="1"
!Variable
!type
!description
|-
| screen_width
| [[GUIVariable#unsigned|unsigned]]
| The usable width of the Wesnoth main window.
|-
| screen_height
| [[GUIVariable#unsigned|unsigned]]
| The usable height of the Wesnoth main window.
|-
| gamemapx_offset
| [[GUIVariable#unsigned|unsigned]]
| The distance between left edge of the screen and the game map.
|-
| gamemap_width
| [[GUIVariable#unsigned|unsigned]]
| The usable width of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_width.
|-
| gamemap_height
| [[GUIVariable#unsigned|unsigned]]
| The usable height of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_height.
|-
| mouse_x
| [[GUIVariable#unsigned|unsigned]]
| The x coordinate of the mouse pointer.
|-
| mouse_y
| [[GUIVariable#unsigned|unsigned]]
| The y coordinate of the mouse pointer.
|-
| window_width
| [[GUIVariable#unsigned|unsigned]]
| The window width. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum width. If no maximum is wanted it should be set to the '"(screen_width)"'. - When not equal to 0 its value is the best width for the window. When the size should remain unchanged it should be set to '"(window_width)"'.
|-
| window_height
| [[GUIVariable#unsigned|unsigned]]
| The window height. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum height. If no maximum is wanted it should be set to the '"(screen_height)"'. - When not equal to 0 its value is the best height for the window. When the size should remain unchanged it should be set to '"(window_height)"'.
|}

Note when drawing the valid coordinates are: 
0 -> width - 1 
0 -> height -1

Drawing outside this area will result in unpredictable results including
crashing. (That should be fixed, when encountered.)

== Pre commit ==
This section contains the pre commit functions. These functions will be
executed before the drawn canvas is applied on top of the normal
background. There should only be one pre commit section and its order
regarding the other shapes doesn't matter. The function has effect on the
entire canvas, it's not possible to affect only a small part of the canvas.

The section can have one of the following subsections.

=== Blur ===
Blurs the background before applying the canvas. This doesn't make sense
if the widget isn't semi-transparent.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| depth
| [[GUIVariable#unsigned|unsigned]]
| 0
| The depth to blur.
|}

== Line ==
Definition of a line. When drawing a line it doesn't get blended on the
surface but replaces the pixels instead.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x1
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the startpoint.
|-
| y1
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the startpoint.
|-
| x2
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the endpoint.
|-
| y2
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the endpoint.
|-
| color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the line.
|-
| thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the line if 0 nothing is drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

== Bounded Shape ==
Common attributes of rectangles, round rectangles and text:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the rectangle.
|}

== Rectangle ==
Definition of a rectangle. When drawing a rectangle it doesn't get blended on
the surface but replaces the pixels instead. A blitting flag might be added
later if needed.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the rectangle.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the border if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the interior if omitted it's not drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

== Rounded Rectangle ==
Definition of a rounded rectangle shape.

When drawing a rounded rectangle it doesn't get blended on the surface but replaces the pixels instead. A blitting flag might be added later if needed.

{| border="1"
!key
!type
!default
!description
|-
| corner_radius
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The radius of the rectangle's corners.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border; if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#color|color]]
| ""
| The color of the border; if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#color|color]]
| ""
| The color of the interior; if omitted it's not drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation; this message is not stored.
|}

== Circle ==
Definition of a circle. When drawing a circle it doesn't get blended on
the surface but replaces the pixels instead. A blitting flag might be
added later if needed.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the center.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the center.
|-
| radius
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The radius of the circle if 0 nothing is drawn.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 1
| The thickness of the border; if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the border; if empty it's white.
|-
| fill_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the interior; if omitted it's not drawn.|-
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

Drawing outside the area will result in unpredictable results including
crashing. (That should be fixed, when encountered.)

== Image ==
Definition of an image.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the image, if not zero the image will be scaled to the desired width.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the image, if not zero the image will be scaled to the desired height.
|-
| resize_mode
| [[GUIVariable#resize_mode|resize_mode]]
| scale
| Determines how an image is scaled to fit the wanted size.
|-
| vertical_mirror
| [[GUIVariable#f_bool|f_bool]]
| false
| Mirror the image over the vertical axis.
|-
| name
| [[GUIVariable#f_string|f_string]]
| ""
| The name of the image.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

Local Variables:
{| border="1"
!Variable
!type
!description
|-
| image_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the image, either the requested width or the natural width of the image. This value can be used to set the x (or y) value of the image. (This means x and y are evaluated after the width and height.)
|-
| image_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the image, either the requested height or the natural height of the image. This value can be used to set the y (or x) value of the image. (This means x and y are evaluated after the width and height.)
|-
| image_original_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the image as stored on disk, can be used to set x or w (also y and h can be set).
|-
| image_original_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the image as stored on disk, can be used to set y or h (also x and y can be set).
|}

== Text ==
Definition of text.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the text's bounding rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the text's bounding rectangle.
|-
| font_family
| [[GUIVariable#font_family|font_family]]
| "sans"
| The font family used for the text.
|-
| font_size
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The size of the text font.
|-
| font_style
| [[GUIVariable#font_style|font_style]]
| ""
| The style of the text.
|-
| text_alignment
| [[GUIVariable#f_h_align|f_h_align]]
| "left"
| The alignment of the text.
|-
| color
| [[GUIVariable#color|color]]
| ""
| The color of the text.
|-
| text
| [[GUIVariable#f_tstring|f_tstring]]
| ""
| The text to draw (translatable).
|-
| text_markup
| [[GUIVariable#f_bool|f_bool]]
| false
| Can the text have mark-up?
|-
| text_link_aware
| [[GUIVariable#f_bool|f_bool]]
| false
| Is the text link aware?
|-
| text_link_color
| [[GUIVariable#f_string|f_string]]
| "#ffff00"
| The color of links in the text
|-
| maximum_width
| [[GUIVariable#f_int|f_int]]
| -1
| The maximum width the text is allowed to be.
|-
| maximum_height
| [[GUIVariable#f_int|f_int]]
| -1
| The maximum height the text is allowed to be.
|-
| actions
| [[GUIVariable#string|string]]
| ""
| WFL code that will be executed when this shape is drawn. In particular, [[FormulaAI_Functions#.27set_var.27_function|set_var]] can be used here to store any variables mentioned in the variables section for global use inside the canvas.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

NOTE alignment could only be done with the formulas, but now with the
text_alignment flag as well, older widgets might still use the formulas and
not all widgets may expose the text alignment yet and when exposed not use
it yet.

Local Variables:
{| border="1"
!Variable
!type
!description
|-
| text_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the rendered text.
|-
| text_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the rendered text.
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

GUICanvasWML

2024-11-05T05:44:39Z

White haired uncle: /* Line */

== Canvas ==
A canvas is a blank drawing area on which the user can draw several shapes.
The drawing is done by adding WML structures to the canvas.

== Global Variables ==
These variables are available to all shapes inside the canvas, in addition to any local variables they may posess, if any.
{| border="1"
!Variable
!type
!description
|-
| width
| [[GUIVariable#unsigned|unsigned]]
| The width of the canvas.
|-
| height
| [[GUIVariable#unsigned|unsigned]]
| The height of the canvas.
|-
| text
| [[GUIVariable#tstring|tstring]]
| The text to render on the widget.
|-
| text_maximum_width
| [[GUIVariable#unsigned|unsigned]]
| The maximum width available for the text on the widget.
|-
| text_maximum_height
| [[GUIVariable#unsigned|unsigned]]
| The maximum height available for the text on the widget.
|-
| text_wrap_mode
| [[GUIVariable#int|int]]
| When the text doesn't fit in the available width there are several ways to fix that. This sets which method is used and possible values are the same as [https://docs.gtk.org/Pango/enum.EllipsizeMode.html here], that is, '''0''' (No elllipsization, wrap text instead), '''1''' (ellipsize start of text), '''2''' (ellipsize end of text), '''3''' (ellipsize at the middle). More details (slightly technical) are found at the Pango docs [https://docs.gtk.org/Pango/method.Layout.set_ellipsize.html here].
|-
| text_alignment
| [[GUIVariable#h_align|h_align]]
| The way the text is aligned inside the canvas.
|}

The size variables are copied to the window and will be determined at
runtime. This is needed since the main window can be resized and the dialog
needs to resize accordingly. The following variables are available:
{| border="1"
!Variable
!type
!description
|-
| screen_width
| [[GUIVariable#unsigned|unsigned]]
| The usable width of the Wesnoth main window.
|-
| screen_height
| [[GUIVariable#unsigned|unsigned]]
| The usable height of the Wesnoth main window.
|-
| gamemapx_offset
| [[GUIVariable#unsigned|unsigned]]
| The distance between left edge of the screen and the game map.
|-
| gamemap_width
| [[GUIVariable#unsigned|unsigned]]
| The usable width of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_width.
|-
| gamemap_height
| [[GUIVariable#unsigned|unsigned]]
| The usable height of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_height.
|-
| mouse_x
| [[GUIVariable#unsigned|unsigned]]
| The x coordinate of the mouse pointer.
|-
| mouse_y
| [[GUIVariable#unsigned|unsigned]]
| The y coordinate of the mouse pointer.
|-
| window_width
| [[GUIVariable#unsigned|unsigned]]
| The window width. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum width. If no maximum is wanted it should be set to the '"(screen_width)"'. - When not equal to 0 its value is the best width for the window. When the size should remain unchanged it should be set to '"(window_width)"'.
|-
| window_height
| [[GUIVariable#unsigned|unsigned]]
| The window height. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum height. If no maximum is wanted it should be set to the '"(screen_height)"'. - When not equal to 0 its value is the best height for the window. When the size should remain unchanged it should be set to '"(window_height)"'.
|}

Note when drawing the valid coordinates are: 
0 -> width - 1 
0 -> height -1

Drawing outside this area will result in unpredictable results including
crashing. (That should be fixed, when encountered.)

== Pre commit ==
This section contains the pre commit functions. These functions will be
executed before the drawn canvas is applied on top of the normal
background. There should only be one pre commit section and its order
regarding the other shapes doesn't matter. The function has effect on the
entire canvas, it's not possible to affect only a small part of the canvas.

The section can have one of the following subsections.

=== Blur ===
Blurs the background before applying the canvas. This doesn't make sense
if the widget isn't semi-transparent.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| depth
| [[GUIVariable#unsigned|unsigned]]
| 0
| The depth to blur.
|}

== Line ==
Definition of a line. When drawing a line it doesn't get blended on the
surface but replaces the pixels instead.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x1
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the startpoint.
|-
| y1
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the startpoint.
|-
| x2
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the endpoint.
|-
| y2
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the endpoint.
|-
| color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the line.
|-
| thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the line if 0 nothing is drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

== Bounded Shape ==
Common attributes of rectangles, round rectangles and text:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the rectangle.
|}

== Rectangle ==
Definition of a rectangle. When drawing a rectangle it doesn't get blended on
the surface but replaces the pixels instead. A blitting flag might be added
later if needed.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the rectangle.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#color|color]]
| ""
| The color of the border if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#color|color]]
| ""
| The color of the interior if omitted it's not drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

== Rounded Rectangle ==
Definition of a rounded rectangle shape.

When drawing a rounded rectangle it doesn't get blended on the surface but replaces the pixels instead. A blitting flag might be added later if needed.

{| border="1"
!key
!type
!default
!description
|-
| corner_radius
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The radius of the rectangle's corners.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border; if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#color|color]]
| ""
| The color of the border; if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#color|color]]
| ""
| The color of the interior; if omitted it's not drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation; this message is not stored.
|}

== Circle ==
Definition of a circle. When drawing a circle it doesn't get blended on
the surface but replaces the pixels instead. A blitting flag might be
added later if needed.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the center.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the center.
|-
| radius
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The radius of the circle if 0 nothing is drawn.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 1
| The thickness of the border; if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the border; if empty it's white.
|-
| fill_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the interior; if omitted it's not drawn.|-
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

Drawing outside the area will result in unpredictable results including
crashing. (That should be fixed, when encountered.)

== Image ==
Definition of an image.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the image, if not zero the image will be scaled to the desired width.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the image, if not zero the image will be scaled to the desired height.
|-
| resize_mode
| [[GUIVariable#resize_mode|resize_mode]]
| scale
| Determines how an image is scaled to fit the wanted size.
|-
| vertical_mirror
| [[GUIVariable#f_bool|f_bool]]
| false
| Mirror the image over the vertical axis.
|-
| name
| [[GUIVariable#f_string|f_string]]
| ""
| The name of the image.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

Local Variables:
{| border="1"
!Variable
!type
!description
|-
| image_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the image, either the requested width or the natural width of the image. This value can be used to set the x (or y) value of the image. (This means x and y are evaluated after the width and height.)
|-
| image_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the image, either the requested height or the natural height of the image. This value can be used to set the y (or x) value of the image. (This means x and y are evaluated after the width and height.)
|-
| image_original_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the image as stored on disk, can be used to set x or w (also y and h can be set).
|-
| image_original_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the image as stored on disk, can be used to set y or h (also x and y can be set).
|}

== Text ==
Definition of text.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the text's bounding rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the text's bounding rectangle.
|-
| font_family
| [[GUIVariable#font_family|font_family]]
| "sans"
| The font family used for the text.
|-
| font_size
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The size of the text font.
|-
| font_style
| [[GUIVariable#font_style|font_style]]
| ""
| The style of the text.
|-
| text_alignment
| [[GUIVariable#f_h_align|f_h_align]]
| "left"
| The alignment of the text.
|-
| color
| [[GUIVariable#color|color]]
| ""
| The color of the text.
|-
| text
| [[GUIVariable#f_tstring|f_tstring]]
| ""
| The text to draw (translatable).
|-
| text_markup
| [[GUIVariable#f_bool|f_bool]]
| false
| Can the text have mark-up?
|-
| text_link_aware
| [[GUIVariable#f_bool|f_bool]]
| false
| Is the text link aware?
|-
| text_link_color
| [[GUIVariable#f_string|f_string]]
| "#ffff00"
| The color of links in the text
|-
| maximum_width
| [[GUIVariable#f_int|f_int]]
| -1
| The maximum width the text is allowed to be.
|-
| maximum_height
| [[GUIVariable#f_int|f_int]]
| -1
| The maximum height the text is allowed to be.
|-
| actions
| [[GUIVariable#string|string]]
| ""
| WFL code that will be executed when this shape is drawn. In particular, [[FormulaAI_Functions#.27set_var.27_function|set_var]] can be used here to store any variables mentioned in the variables section for global use inside the canvas.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

NOTE alignment could only be done with the formulas, but now with the
text_alignment flag as well, older widgets might still use the formulas and
not all widgets may expose the text alignment yet and when exposed not use
it yet.

Local Variables:
{| border="1"
!Variable
!type
!description
|-
| text_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the rendered text.
|-
| text_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the rendered text.
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

Talk:GUIVariable

2024-11-05T05:40:42Z

White haired uncle:

resize_mode lists three values - perhaps they are the only ones actually used?

<syntaxhighlight lang="cpp">
enum class resize_mode {
scale,
scale_sharp,
stretch,
tile,
tile_center,
tile_highres,
};
</syntaxhighlight>

grow_direction looks like it was just copied from resize_mode. Would that be this?
<syntaxhighlight lang="cpp">
struct grow_direction_defines
{
static constexpr const char* const horizontal = "horizontal";
static constexpr const char* const vertical = "vertical";

ENUM_AND_ARRAY(horizontal, vertical)
};
using grow_direction = string_enums::enum_base<grow_direction_defines>;
</syntaxhighlight>

[[User:White haired uncle|White haired uncle]] ([[User talk:White haired uncle|talk]]) 05:36, 5 November 2024 (UTC)

GUICanvasWML

2024-11-05T05:38:36Z

White haired uncle: /* Circle */ - color > f_color

== Canvas ==
A canvas is a blank drawing area on which the user can draw several shapes.
The drawing is done by adding WML structures to the canvas.

== Global Variables ==
These variables are available to all shapes inside the canvas, in addition to any local variables they may posess, if any.
{| border="1"
!Variable
!type
!description
|-
| width
| [[GUIVariable#unsigned|unsigned]]
| The width of the canvas.
|-
| height
| [[GUIVariable#unsigned|unsigned]]
| The height of the canvas.
|-
| text
| [[GUIVariable#tstring|tstring]]
| The text to render on the widget.
|-
| text_maximum_width
| [[GUIVariable#unsigned|unsigned]]
| The maximum width available for the text on the widget.
|-
| text_maximum_height
| [[GUIVariable#unsigned|unsigned]]
| The maximum height available for the text on the widget.
|-
| text_wrap_mode
| [[GUIVariable#int|int]]
| When the text doesn't fit in the available width there are several ways to fix that. This sets which method is used and possible values are the same as [https://docs.gtk.org/Pango/enum.EllipsizeMode.html here], that is, '''0''' (No elllipsization, wrap text instead), '''1''' (ellipsize start of text), '''2''' (ellipsize end of text), '''3''' (ellipsize at the middle). More details (slightly technical) are found at the Pango docs [https://docs.gtk.org/Pango/method.Layout.set_ellipsize.html here].
|-
| text_alignment
| [[GUIVariable#h_align|h_align]]
| The way the text is aligned inside the canvas.
|}

The size variables are copied to the window and will be determined at
runtime. This is needed since the main window can be resized and the dialog
needs to resize accordingly. The following variables are available:
{| border="1"
!Variable
!type
!description
|-
| screen_width
| [[GUIVariable#unsigned|unsigned]]
| The usable width of the Wesnoth main window.
|-
| screen_height
| [[GUIVariable#unsigned|unsigned]]
| The usable height of the Wesnoth main window.
|-
| gamemapx_offset
| [[GUIVariable#unsigned|unsigned]]
| The distance between left edge of the screen and the game map.
|-
| gamemap_width
| [[GUIVariable#unsigned|unsigned]]
| The usable width of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_width.
|-
| gamemap_height
| [[GUIVariable#unsigned|unsigned]]
| The usable height of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_height.
|-
| mouse_x
| [[GUIVariable#unsigned|unsigned]]
| The x coordinate of the mouse pointer.
|-
| mouse_y
| [[GUIVariable#unsigned|unsigned]]
| The y coordinate of the mouse pointer.
|-
| window_width
| [[GUIVariable#unsigned|unsigned]]
| The window width. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum width. If no maximum is wanted it should be set to the '"(screen_width)"'. - When not equal to 0 its value is the best width for the window. When the size should remain unchanged it should be set to '"(window_width)"'.
|-
| window_height
| [[GUIVariable#unsigned|unsigned]]
| The window height. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum height. If no maximum is wanted it should be set to the '"(screen_height)"'. - When not equal to 0 its value is the best height for the window. When the size should remain unchanged it should be set to '"(window_height)"'.
|}

Note when drawing the valid coordinates are: 
0 -> width - 1 
0 -> height -1

Drawing outside this area will result in unpredictable results including
crashing. (That should be fixed, when encountered.)

== Pre commit ==
This section contains the pre commit functions. These functions will be
executed before the drawn canvas is applied on top of the normal
background. There should only be one pre commit section and its order
regarding the other shapes doesn't matter. The function has effect on the
entire canvas, it's not possible to affect only a small part of the canvas.

The section can have one of the following subsections.

=== Blur ===
Blurs the background before applying the canvas. This doesn't make sense
if the widget isn't semi-transparent.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| depth
| [[GUIVariable#unsigned|unsigned]]
| 0
| The depth to blur.
|}

== Line ==
Definition of a line. When drawing a line it doesn't get blended on the
surface but replaces the pixels instead.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x1
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the startpoint.
|-
| y1
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the startpoint.
|-
| x2
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the endpoint.
|-
| y2
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the endpoint.
|-
| color
| [[GUIVariable#color|color]]
| ""
| The color of the line.
|-
| thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the line if 0 nothing is drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

== Bounded Shape ==
Common attributes of rectangles, round rectangles and text:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the rectangle.
|}

== Rectangle ==
Definition of a rectangle. When drawing a rectangle it doesn't get blended on
the surface but replaces the pixels instead. A blitting flag might be added
later if needed.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the rectangle.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#color|color]]
| ""
| The color of the border if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#color|color]]
| ""
| The color of the interior if omitted it's not drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

== Rounded Rectangle ==
Definition of a rounded rectangle shape.

When drawing a rounded rectangle it doesn't get blended on the surface but replaces the pixels instead. A blitting flag might be added later if needed.

{| border="1"
!key
!type
!default
!description
|-
| corner_radius
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The radius of the rectangle's corners.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border; if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#color|color]]
| ""
| The color of the border; if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#color|color]]
| ""
| The color of the interior; if omitted it's not drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation; this message is not stored.
|}

== Circle ==
Definition of a circle. When drawing a circle it doesn't get blended on
the surface but replaces the pixels instead. A blitting flag might be
added later if needed.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the center.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the center.
|-
| radius
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The radius of the circle if 0 nothing is drawn.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 1
| The thickness of the border; if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the border; if empty it's white.
|-
| fill_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the interior; if omitted it's not drawn.|-
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

Drawing outside the area will result in unpredictable results including
crashing. (That should be fixed, when encountered.)

== Image ==
Definition of an image.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the image, if not zero the image will be scaled to the desired width.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the image, if not zero the image will be scaled to the desired height.
|-
| resize_mode
| [[GUIVariable#resize_mode|resize_mode]]
| scale
| Determines how an image is scaled to fit the wanted size.
|-
| vertical_mirror
| [[GUIVariable#f_bool|f_bool]]
| false
| Mirror the image over the vertical axis.
|-
| name
| [[GUIVariable#f_string|f_string]]
| ""
| The name of the image.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

Local Variables:
{| border="1"
!Variable
!type
!description
|-
| image_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the image, either the requested width or the natural width of the image. This value can be used to set the x (or y) value of the image. (This means x and y are evaluated after the width and height.)
|-
| image_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the image, either the requested height or the natural height of the image. This value can be used to set the y (or x) value of the image. (This means x and y are evaluated after the width and height.)
|-
| image_original_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the image as stored on disk, can be used to set x or w (also y and h can be set).
|-
| image_original_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the image as stored on disk, can be used to set y or h (also x and y can be set).
|}

== Text ==
Definition of text.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the text's bounding rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the text's bounding rectangle.
|-
| font_family
| [[GUIVariable#font_family|font_family]]
| "sans"
| The font family used for the text.
|-
| font_size
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The size of the text font.
|-
| font_style
| [[GUIVariable#font_style|font_style]]
| ""
| The style of the text.
|-
| text_alignment
| [[GUIVariable#f_h_align|f_h_align]]
| "left"
| The alignment of the text.
|-
| color
| [[GUIVariable#color|color]]
| ""
| The color of the text.
|-
| text
| [[GUIVariable#f_tstring|f_tstring]]
| ""
| The text to draw (translatable).
|-
| text_markup
| [[GUIVariable#f_bool|f_bool]]
| false
| Can the text have mark-up?
|-
| text_link_aware
| [[GUIVariable#f_bool|f_bool]]
| false
| Is the text link aware?
|-
| text_link_color
| [[GUIVariable#f_string|f_string]]
| "#ffff00"
| The color of links in the text
|-
| maximum_width
| [[GUIVariable#f_int|f_int]]
| -1
| The maximum width the text is allowed to be.
|-
| maximum_height
| [[GUIVariable#f_int|f_int]]
| -1
| The maximum height the text is allowed to be.
|-
| actions
| [[GUIVariable#string|string]]
| ""
| WFL code that will be executed when this shape is drawn. In particular, [[FormulaAI_Functions#.27set_var.27_function|set_var]] can be used here to store any variables mentioned in the variables section for global use inside the canvas.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

NOTE alignment could only be done with the formulas, but now with the
text_alignment flag as well, older widgets might still use the formulas and
not all widgets may expose the text alignment yet and when exposed not use
it yet.

Local Variables:
{| border="1"
!Variable
!type
!description
|-
| text_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the rendered text.
|-
| text_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the rendered text.
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

Talk:GUIVariable

2024-11-05T05:36:39Z

White haired uncle: Created page with "resize_mode lists three values - perhaps they are the only ones actually used? <syntaxhighlight lang="cpp"> enum class resize_mode { scal..."

resize_mode lists three values - perhaps they are the only ones actually used?

<syntaxhighlight lang="cpp">
enum class resize_mode {
scale,
scale_sharp,
stretch,
tile,
tile_center,
tile_highres,
};
</syntaxhighlight>

grow_direction looks like it was just copied from resize_mode. Would that be this?
<syntaxhighlight lang="cpp">
struct grow_direction_defines
{
static constexpr const char* const horizontal = "horizontal";
static constexpr const char* const vertical = "vertical";

ENUM_AND_ARRAY(horizontal, vertical)
};
using grow_direction = string_enums::enum_base<grow_direction_defines>;
</syntaxhighlight>

Both of the above speak of acting on an image, which I guess is kind of true but perhaps there's a better word to avoid confusion with [image].
[[User:White haired uncle|White haired uncle]] ([[User talk:White haired uncle|talk]]) 05:36, 5 November 2024 (UTC)

GUICanvasWML

2024-11-05T03:16:42Z

White haired uncle: /* Circle */

== Canvas ==
A canvas is a blank drawing area on which the user can draw several shapes.
The drawing is done by adding WML structures to the canvas.

== Global Variables ==
These variables are available to all shapes inside the canvas, in addition to any local variables they may posess, if any.
{| border="1"
!Variable
!type
!description
|-
| width
| [[GUIVariable#unsigned|unsigned]]
| The width of the canvas.
|-
| height
| [[GUIVariable#unsigned|unsigned]]
| The height of the canvas.
|-
| text
| [[GUIVariable#tstring|tstring]]
| The text to render on the widget.
|-
| text_maximum_width
| [[GUIVariable#unsigned|unsigned]]
| The maximum width available for the text on the widget.
|-
| text_maximum_height
| [[GUIVariable#unsigned|unsigned]]
| The maximum height available for the text on the widget.
|-
| text_wrap_mode
| [[GUIVariable#int|int]]
| When the text doesn't fit in the available width there are several ways to fix that. This sets which method is used and possible values are the same as [https://docs.gtk.org/Pango/enum.EllipsizeMode.html here], that is, '''0''' (No elllipsization, wrap text instead), '''1''' (ellipsize start of text), '''2''' (ellipsize end of text), '''3''' (ellipsize at the middle). More details (slightly technical) are found at the Pango docs [https://docs.gtk.org/Pango/method.Layout.set_ellipsize.html here].
|-
| text_alignment
| [[GUIVariable#h_align|h_align]]
| The way the text is aligned inside the canvas.
|}

The size variables are copied to the window and will be determined at
runtime. This is needed since the main window can be resized and the dialog
needs to resize accordingly. The following variables are available:
{| border="1"
!Variable
!type
!description
|-
| screen_width
| [[GUIVariable#unsigned|unsigned]]
| The usable width of the Wesnoth main window.
|-
| screen_height
| [[GUIVariable#unsigned|unsigned]]
| The usable height of the Wesnoth main window.
|-
| gamemapx_offset
| [[GUIVariable#unsigned|unsigned]]
| The distance between left edge of the screen and the game map.
|-
| gamemap_width
| [[GUIVariable#unsigned|unsigned]]
| The usable width of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_width.
|-
| gamemap_height
| [[GUIVariable#unsigned|unsigned]]
| The usable height of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_height.
|-
| mouse_x
| [[GUIVariable#unsigned|unsigned]]
| The x coordinate of the mouse pointer.
|-
| mouse_y
| [[GUIVariable#unsigned|unsigned]]
| The y coordinate of the mouse pointer.
|-
| window_width
| [[GUIVariable#unsigned|unsigned]]
| The window width. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum width. If no maximum is wanted it should be set to the '"(screen_width)"'. - When not equal to 0 its value is the best width for the window. When the size should remain unchanged it should be set to '"(window_width)"'.
|-
| window_height
| [[GUIVariable#unsigned|unsigned]]
| The window height. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum height. If no maximum is wanted it should be set to the '"(screen_height)"'. - When not equal to 0 its value is the best height for the window. When the size should remain unchanged it should be set to '"(window_height)"'.
|}

Note when drawing the valid coordinates are: 
0 -> width - 1 
0 -> height -1

Drawing outside this area will result in unpredictable results including
crashing. (That should be fixed, when encountered.)

== Pre commit ==
This section contains the pre commit functions. These functions will be
executed before the drawn canvas is applied on top of the normal
background. There should only be one pre commit section and its order
regarding the other shapes doesn't matter. The function has effect on the
entire canvas, it's not possible to affect only a small part of the canvas.

The section can have one of the following subsections.

=== Blur ===
Blurs the background before applying the canvas. This doesn't make sense
if the widget isn't semi-transparent.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| depth
| [[GUIVariable#unsigned|unsigned]]
| 0
| The depth to blur.
|}

== Line ==
Definition of a line. When drawing a line it doesn't get blended on the
surface but replaces the pixels instead.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x1
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the startpoint.
|-
| y1
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the startpoint.
|-
| x2
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the endpoint.
|-
| y2
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the endpoint.
|-
| color
| [[GUIVariable#color|color]]
| ""
| The color of the line.
|-
| thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the line if 0 nothing is drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

== Bounded Shape ==
Common attributes of rectangles, round rectangles and text:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the rectangle.
|}

== Rectangle ==
Definition of a rectangle. When drawing a rectangle it doesn't get blended on
the surface but replaces the pixels instead. A blitting flag might be added
later if needed.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the rectangle.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#color|color]]
| ""
| The color of the border if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#color|color]]
| ""
| The color of the interior if omitted it's not drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

== Rounded Rectangle ==
Definition of a rounded rectangle shape.

When drawing a rounded rectangle it doesn't get blended on the surface but replaces the pixels instead. A blitting flag might be added later if needed.

{| border="1"
!key
!type
!default
!description
|-
| corner_radius
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The radius of the rectangle's corners.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border; if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#color|color]]
| ""
| The color of the border; if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#color|color]]
| ""
| The color of the interior; if omitted it's not drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation; this message is not stored.
|}

== Circle ==
Definition of a circle. When drawing a circle it doesn't get blended on
the surface but replaces the pixels instead. A blitting flag might be
added later if needed.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the center.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the center.
|-
| radius
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The radius of the circle if 0 nothing is drawn.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 1
| The thickness of the border; if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the border; if empty it's white.
|-
| fill_color
| [[GUIVariable#color|color]]
| ""
| The color of the interior; if omitted it's not drawn.|-
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

Drawing outside the area will result in unpredictable results including
crashing. (That should be fixed, when encountered.)

== Image ==
Definition of an image.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the image, if not zero the image will be scaled to the desired width.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the image, if not zero the image will be scaled to the desired height.
|-
| resize_mode
| [[GUIVariable#resize_mode|resize_mode]]
| scale
| Determines how an image is scaled to fit the wanted size.
|-
| vertical_mirror
| [[GUIVariable#f_bool|f_bool]]
| false
| Mirror the image over the vertical axis.
|-
| name
| [[GUIVariable#f_string|f_string]]
| ""
| The name of the image.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

Local Variables:
{| border="1"
!Variable
!type
!description
|-
| image_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the image, either the requested width or the natural width of the image. This value can be used to set the x (or y) value of the image. (This means x and y are evaluated after the width and height.)
|-
| image_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the image, either the requested height or the natural height of the image. This value can be used to set the y (or x) value of the image. (This means x and y are evaluated after the width and height.)
|-
| image_original_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the image as stored on disk, can be used to set x or w (also y and h can be set).
|-
| image_original_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the image as stored on disk, can be used to set y or h (also x and y can be set).
|}

== Text ==
Definition of text.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the text's bounding rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the text's bounding rectangle.
|-
| font_family
| [[GUIVariable#font_family|font_family]]
| "sans"
| The font family used for the text.
|-
| font_size
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The size of the text font.
|-
| font_style
| [[GUIVariable#font_style|font_style]]
| ""
| The style of the text.
|-
| text_alignment
| [[GUIVariable#f_h_align|f_h_align]]
| "left"
| The alignment of the text.
|-
| color
| [[GUIVariable#color|color]]
| ""
| The color of the text.
|-
| text
| [[GUIVariable#f_tstring|f_tstring]]
| ""
| The text to draw (translatable).
|-
| text_markup
| [[GUIVariable#f_bool|f_bool]]
| false
| Can the text have mark-up?
|-
| text_link_aware
| [[GUIVariable#f_bool|f_bool]]
| false
| Is the text link aware?
|-
| text_link_color
| [[GUIVariable#f_string|f_string]]
| "#ffff00"
| The color of links in the text
|-
| maximum_width
| [[GUIVariable#f_int|f_int]]
| -1
| The maximum width the text is allowed to be.
|-
| maximum_height
| [[GUIVariable#f_int|f_int]]
| -1
| The maximum height the text is allowed to be.
|-
| actions
| [[GUIVariable#string|string]]
| ""
| WFL code that will be executed when this shape is drawn. In particular, [[FormulaAI_Functions#.27set_var.27_function|set_var]] can be used here to store any variables mentioned in the variables section for global use inside the canvas.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

NOTE alignment could only be done with the formulas, but now with the
text_alignment flag as well, older widgets might still use the formulas and
not all widgets may expose the text alignment yet and when exposed not use
it yet.

Local Variables:
{| border="1"
!Variable
!type
!description
|-
| text_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the rendered text.
|-
| text_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the rendered text.
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

GUIVariable

2024-11-05T03:14:06Z

White haired uncle: /* Simple types */

== Variables ==
In various parts of the GUI there are several variables types in use. This
page describes them.

== Simple types ==
The simple types are types which have one value or a short list of options.

{| class="wikitable"
!Variable !!Description
|-
|style="vertical-align:top"| unsigned
| Unsigned number (positive whole numbers and zero).
|-
|style="vertical-align:top"| f_unsigned
| Unsigned number or formula returning an unsigned number.
|-
|style="vertical-align:top"| int
| Signed number (whole numbers).
|-
|style="vertical-align:top"| f_int
| Signed number or formula returning an signed number.
|-
|style="vertical-align:top"| bool
| A boolean value accepts the normal values as the rest of the game.
|-
|style="vertical-align:top"| f_bool
| Boolean value or a formula returning a boolean value.
|-
|style="vertical-align:top"| string
| A text.
|-
|style="vertical-align:top"| tstring
| A translatable string.
|-
|style="vertical-align:top"| f_tstring
| Formula returning a translatable string.
|-
|style="vertical-align:top"| function
| A string containing a set of function definition for the formula language.
|-
|style="vertical-align:top"| color
| A string which contains the color, this a group of 4 numbers between 0 and 255 separated by commas. The numbers are red component, green component, blue component and alpha. An alpha of 0 is fully transparent, while an alpha of 255 is fully opaque.
|-
|style="vertical-align:top"| f_color
| A color, or a formula returning a color value.
|-
|style="vertical-align:top"| font_style
| A string which contains the style of the font:
* normal normal font
* bold bold font
* italic italic font
* underline underlined font
Since SDL has problems combining these styles only one can be picked. Once SDL will allow multiple options, this type will be transformed to a comma separated list. If empty we default to the normal style. Since the render engine is replaced by Pango markup this field will change later on. Note widgets that allow marked up text can use markup to change the font style.
|-
|style="vertical-align:top"| v_align
| Vertical alignment; how an item is aligned vertically in the available space. Possible values:
* top aligned at the top
* bottom aligned at the bottom
* center centered
When nothing is set or an another value as in the list the item is centered.
|-
|style="vertical-align:top"| h_align
| Horizontal alignment; how an item is aligned horizontally in the available space. Possible values:
* left aligned at the left side
* right aligned at the right side
* center centered
|-
|style="vertical-align:top"| f_h_align
| A horizontal alignment or a formula returning a horizontal alignment.
|-
|style="vertical-align:top"| border
| Comma separated list of borders to use. Possible values:
* left border at the left side
* right border at the right side
* top border at the top
* bottom border at the bottom
* all alias for "left, right, top, bottom"
|-
|style="vertical-align:top"| scrollbar_mode
| How to show the scrollbar of a widget. Possible values:
* always The scrollbar is always shown, regardless whether it's required or not.
* never The scrollbar is never shown, even not when needed. (Note when setting this mode dialogs might not properly fit anymore).
* auto Shows the scrollbar when needed. The widget will reserve space for the scrollbar, but only show when needed.
* initial_auto Like auto, but when the scrollbar is not needed the space is not reserved.
Use auto when the list can be changed dynamically eg the game list in the lobby. For optimization you can also use auto when you really expect a scrollbar, but don't want it to be shown when not needed eg the language list will need a scrollbar on most screens.
|-
|style="vertical-align:top"| resize_mode
| Determines how an image is resized. Possible values:
* scale The image is scaled.
* stretch The first row or column of pixels is copied over the entire image. (Can only be used to scale resize in one direction, else falls back to scale.)
* tile The image is placed several times until the entire surface is filled. The last images are truncated.
|-
|style="vertical-align:top"| grow_direction
| Determines how an image is resized. Possible values:
* scale The image is scaled.
* stretch The first row or column of pixels is copied over the entire image. (Can only be used to scale resize in one direction, else falls back to scale.)
* tile The image is placed several times until the entire surface is filled. The last images are truncated.
|}

== Section types ==
For more complex parts, there are sections. Sections contain of several
lines of WML and can have sub sections. For example a grid has sub sections
which contain various widgets. Here's the list of sections.

{| border="1"
!Variable
!description
|-
| section
| A generic section. The documentation about the section should describe the section in further detail.
|-
| grid
| A grid contains several widgets. (TODO add link to generic grid page.)
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

GUIVariable

2024-11-05T03:06:55Z

White haired uncle: /* Simple types */ - add f_color, fix color description

== Variables ==
In various parts of the GUI there are several variables types in use. This
page describes them.

== Simple types ==
The simple types are types which have one value or a short list of options.

{| class="wikitable"
!Variable !!Description
|-
|style="vertical-align:top"| unsigned
| Unsigned number (positive whole numbers and zero).
|-
|style="vertical-align:top"| f_unsigned
| Unsigned number or formula returning an unsigned number.
|-
|style="vertical-align:top"| int
| Signed number (whole numbers).
|-
|style="vertical-align:top"| f_int
| Signed number or formula returning an signed number.
|-
|style="vertical-align:top"| bool
| A boolean value accepts the normal values as the rest of the game.
|-
|style="vertical-align:top"| f_bool
| Boolean value or a formula returning a boolean value.
|-
|style="vertical-align:top"| string
| A text.
|-
|style="vertical-align:top"| tstring
| A translatable string.
|-
|style="vertical-align:top"| f_tstring
| Formula returning a translatable string.
|-
|style="vertical-align:top"| function
| A string containing a set of function definition for the formula language.
|-
|style="vertical-align:top"| color
| A string which contains the color, this a group of 4 numbers between 0 and 255 separated by commas. The numbers are red component, green component, blue component and alpha. An alpha of 0 is fully transparent, while an alpha of 255 is fully opaque. Omitted values are set to 0.
|-
|style="vertical-align:top"| f_color
| A color, or a formula returning a color value.
|-
|style="vertical-align:top"| font_style
| A string which contains the style of the font:
* normal normal font
* bold bold font
* italic italic font
* underline underlined font
Since SDL has problems combining these styles only one can be picked. Once SDL will allow multiple options, this type will be transformed to a comma separated list. If empty we default to the normal style. Since the render engine is replaced by Pango markup this field will change later on. Note widgets that allow marked up text can use markup to change the font style.
|-
|style="vertical-align:top"| v_align
| Vertical alignment; how an item is aligned vertically in the available space. Possible values:
* top aligned at the top
* bottom aligned at the bottom
* center centered
When nothing is set or an another value as in the list the item is centered.
|-
|style="vertical-align:top"| h_align
| Horizontal alignment; how an item is aligned horizontally in the available space. Possible values:
* left aligned at the left side
* right aligned at the right side
* center centered
|-
|style="vertical-align:top"| f_h_align
| A horizontal alignment or a formula returning a horizontal alignment.
|-
|style="vertical-align:top"| border
| Comma separated list of borders to use. Possible values:
* left border at the left side
* right border at the right side
* top border at the top
* bottom border at the bottom
* all alias for "left, right, top, bottom"
|-
|style="vertical-align:top"| scrollbar_mode
| How to show the scrollbar of a widget. Possible values:
* always The scrollbar is always shown, regardless whether it's required or not.
* never The scrollbar is never shown, even not when needed. (Note when setting this mode dialogs might not properly fit anymore).
* auto Shows the scrollbar when needed. The widget will reserve space for the scrollbar, but only show when needed.
* initial_auto Like auto, but when the scrollbar is not needed the space is not reserved.
Use auto when the list can be changed dynamically eg the game list in the lobby. For optimization you can also use auto when you really expect a scrollbar, but don't want it to be shown when not needed eg the language list will need a scrollbar on most screens.
|-
|style="vertical-align:top"| resize_mode
| Determines how an image is resized. Possible values:
* scale The image is scaled.
* stretch The first row or column of pixels is copied over the entire image. (Can only be used to scale resize in one direction, else falls back to scale.)
* tile The image is placed several times until the entire surface is filled. The last images are truncated.
|-
|style="vertical-align:top"| grow_direction
| Determines how an image is resized. Possible values:
* scale The image is scaled.
* stretch The first row or column of pixels is copied over the entire image. (Can only be used to scale resize in one direction, else falls back to scale.)
* tile The image is placed several times until the entire surface is filled. The last images are truncated.
|}

== Section types ==
For more complex parts, there are sections. Sections contain of several
lines of WML and can have sub sections. For example a grid has sub sections
which contain various widgets. Here's the list of sections.

{| border="1"
!Variable
!description
|-
| section
| A generic section. The documentation about the section should describe the section in further detail.
|-
| grid
| A grid contains several widgets. (TODO add link to generic grid page.)
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

GUICanvasWML

2024-11-05T02:30:54Z

White haired uncle: /* Circle */

== Canvas ==
A canvas is a blank drawing area on which the user can draw several shapes.
The drawing is done by adding WML structures to the canvas.

== Global Variables ==
These variables are available to all shapes inside the canvas, in addition to any local variables they may posess, if any.
{| border="1"
!Variable
!type
!description
|-
| width
| [[GUIVariable#unsigned|unsigned]]
| The width of the canvas.
|-
| height
| [[GUIVariable#unsigned|unsigned]]
| The height of the canvas.
|-
| text
| [[GUIVariable#tstring|tstring]]
| The text to render on the widget.
|-
| text_maximum_width
| [[GUIVariable#unsigned|unsigned]]
| The maximum width available for the text on the widget.
|-
| text_maximum_height
| [[GUIVariable#unsigned|unsigned]]
| The maximum height available for the text on the widget.
|-
| text_wrap_mode
| [[GUIVariable#int|int]]
| When the text doesn't fit in the available width there are several ways to fix that. This sets which method is used and possible values are the same as [https://docs.gtk.org/Pango/enum.EllipsizeMode.html here], that is, '''0''' (No elllipsization, wrap text instead), '''1''' (ellipsize start of text), '''2''' (ellipsize end of text), '''3''' (ellipsize at the middle). More details (slightly technical) are found at the Pango docs [https://docs.gtk.org/Pango/method.Layout.set_ellipsize.html here].
|-
| text_alignment
| [[GUIVariable#h_align|h_align]]
| The way the text is aligned inside the canvas.
|}

The size variables are copied to the window and will be determined at
runtime. This is needed since the main window can be resized and the dialog
needs to resize accordingly. The following variables are available:
{| border="1"
!Variable
!type
!description
|-
| screen_width
| [[GUIVariable#unsigned|unsigned]]
| The usable width of the Wesnoth main window.
|-
| screen_height
| [[GUIVariable#unsigned|unsigned]]
| The usable height of the Wesnoth main window.
|-
| gamemapx_offset
| [[GUIVariable#unsigned|unsigned]]
| The distance between left edge of the screen and the game map.
|-
| gamemap_width
| [[GUIVariable#unsigned|unsigned]]
| The usable width of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_width.
|-
| gamemap_height
| [[GUIVariable#unsigned|unsigned]]
| The usable height of the Wesnoth gamemap, if no gamemap shown it's the same value as screen_height.
|-
| mouse_x
| [[GUIVariable#unsigned|unsigned]]
| The x coordinate of the mouse pointer.
|-
| mouse_y
| [[GUIVariable#unsigned|unsigned]]
| The y coordinate of the mouse pointer.
|-
| window_width
| [[GUIVariable#unsigned|unsigned]]
| The window width. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum width. If no maximum is wanted it should be set to the '"(screen_width)"'. - When not equal to 0 its value is the best width for the window. When the size should remain unchanged it should be set to '"(window_width)"'.
|-
| window_height
| [[GUIVariable#unsigned|unsigned]]
| The window height. This value has two meanings during the layout phase. This only applies if automatic placement is not enabled. - When set to 0 it should return the wanted maximum height. If no maximum is wanted it should be set to the '"(screen_height)"'. - When not equal to 0 its value is the best height for the window. When the size should remain unchanged it should be set to '"(window_height)"'.
|}

Note when drawing the valid coordinates are: 
0 -> width - 1 
0 -> height -1

Drawing outside this area will result in unpredictable results including
crashing. (That should be fixed, when encountered.)

== Pre commit ==
This section contains the pre commit functions. These functions will be
executed before the drawn canvas is applied on top of the normal
background. There should only be one pre commit section and its order
regarding the other shapes doesn't matter. The function has effect on the
entire canvas, it's not possible to affect only a small part of the canvas.

The section can have one of the following subsections.

=== Blur ===
Blurs the background before applying the canvas. This doesn't make sense
if the widget isn't semi-transparent.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| depth
| [[GUIVariable#unsigned|unsigned]]
| 0
| The depth to blur.
|}

== Line ==
Definition of a line. When drawing a line it doesn't get blended on the
surface but replaces the pixels instead.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x1
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the startpoint.
|-
| y1
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the startpoint.
|-
| x2
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the endpoint.
|-
| y2
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the endpoint.
|-
| color
| [[GUIVariable#color|color]]
| ""
| The color of the line.
|-
| thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the line if 0 nothing is drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

== Bounded Shape ==
Common attributes of rectangles, round rectangles and text:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the rectangle.
|}

== Rectangle ==
Definition of a rectangle. When drawing a rectangle it doesn't get blended on
the surface but replaces the pixels instead. A blitting flag might be added
later if needed.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the rectangle.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#color|color]]
| ""
| The color of the border if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#color|color]]
| ""
| The color of the interior if omitted it's not drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

== Rounded Rectangle ==
Definition of a rounded rectangle shape.

When drawing a rounded rectangle it doesn't get blended on the surface but replaces the pixels instead. A blitting flag might be added later if needed.

{| border="1"
!key
!type
!default
!description
|-
| corner_radius
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The radius of the rectangle's corners.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border; if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#color|color]]
| ""
| The color of the border; if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#color|color]]
| ""
| The color of the interior; if omitted it's not drawn.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation; this message is not stored.
|}

== Circle ==
Definition of a circle. When drawing a circle it doesn't get blended on
the surface but replaces the pixels instead. A blitting flag might be
added later if needed.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the center.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the center.
|-
| radius
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The radius of the circle if 0 nothing is drawn.
|-
| border_thickness
| [[GUIVariable#unsigned|unsigned]]
| 0
| The thickness of the border; if the thickness is zero it's not drawn.
|-
| border_color
| [[GUIVariable#f_color|f_color]]
| ""
| The color of the border; if empty it's not drawn.
|-
| fill_color
| [[GUIVariable#color|color]]
| ""
| The color of the interior; if omitted it's not drawn.|-
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

Drawing outside the area will result in unpredictable results including
crashing. (That should be fixed, when encountered.)

== Image ==
Definition of an image.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the image, if not zero the image will be scaled to the desired width.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the image, if not zero the image will be scaled to the desired height.
|-
| resize_mode
| [[GUIVariable#resize_mode|resize_mode]]
| scale
| Determines how an image is scaled to fit the wanted size.
|-
| vertical_mirror
| [[GUIVariable#f_bool|f_bool]]
| false
| Mirror the image over the vertical axis.
|-
| name
| [[GUIVariable#f_string|f_string]]
| ""
| The name of the image.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

Local Variables:
{| border="1"
!Variable
!type
!description
|-
| image_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the image, either the requested width or the natural width of the image. This value can be used to set the x (or y) value of the image. (This means x and y are evaluated after the width and height.)
|-
| image_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the image, either the requested height or the natural height of the image. This value can be used to set the y (or x) value of the image. (This means x and y are evaluated after the width and height.)
|-
| image_original_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the image as stored on disk, can be used to set x or w (also y and h can be set).
|-
| image_original_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the image as stored on disk, can be used to set y or h (also x and y can be set).
|}

== Text ==
Definition of text.

Keys:
{| border="1"
!key
!type
!default
!description
|-
| x
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The x coordinate of the top left corner.
|-
| y
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The y coordinate of the top left corner.
|-
| w
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the text's bounding rectangle.
|-
| h
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the text's bounding rectangle.
|-
| font_family
| [[GUIVariable#font_family|font_family]]
| "sans"
| The font family used for the text.
|-
| font_size
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The size of the text font.
|-
| font_style
| [[GUIVariable#font_style|font_style]]
| ""
| The style of the text.
|-
| text_alignment
| [[GUIVariable#f_h_align|f_h_align]]
| "left"
| The alignment of the text.
|-
| color
| [[GUIVariable#color|color]]
| ""
| The color of the text.
|-
| text
| [[GUIVariable#f_tstring|f_tstring]]
| ""
| The text to draw (translatable).
|-
| text_markup
| [[GUIVariable#f_bool|f_bool]]
| false
| Can the text have mark-up?
|-
| text_link_aware
| [[GUIVariable#f_bool|f_bool]]
| false
| Is the text link aware?
|-
| text_link_color
| [[GUIVariable#f_string|f_string]]
| "#ffff00"
| The color of links in the text
|-
| maximum_width
| [[GUIVariable#f_int|f_int]]
| -1
| The maximum width the text is allowed to be.
|-
| maximum_height
| [[GUIVariable#f_int|f_int]]
| -1
| The maximum height the text is allowed to be.
|-
| actions
| [[GUIVariable#string|string]]
| ""
| WFL code that will be executed when this shape is drawn. In particular, [[FormulaAI_Functions#.27set_var.27_function|set_var]] can be used here to store any variables mentioned in the variables section for global use inside the canvas.
|-
| debug
| [[GUIVariable#string|string]]
| ""
| Debug message to show upon creation this message is not stored.
|}

NOTE alignment could only be done with the formulas, but now with the
text_alignment flag as well, older widgets might still use the formulas and
not all widgets may expose the text alignment yet and when exposed not use
it yet.

Local Variables:
{| border="1"
!Variable
!type
!description
|-
| text_width
| [[GUIVariable#unsigned|unsigned]]
| The width of the rendered text.
|-
| text_height
| [[GUIVariable#unsigned|unsigned]]
| The height of the rendered text.
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

LuaAPI/wesnoth/interface

2024-11-04T13:50:08Z

White haired uncle: /* wesnoth.interface.delay */ - update deprecated example

<div class="tright"> __TOC__ </div>

{{DevFeature1.15|0}}

The entire interface module is only available in the game. It is not available to plugins or map generators.

== Interface functions ==

=== wesnoth.interface.delay ===

* {{LuaGameOnly}} '''wesnoth.interface.delay'''(''milliseconds'')

Delays the engine for a period of time, specified in milliseconds.

<syntaxhighlight lang=lua>
wesnoth.interface.delay(500)
</syntaxhighlight>

=== wesnoth.interface.deselect_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.deselect_hex'''()

Reverses any highlight_hex call, leaving all locations unhighlighted. Takes no arguments.

=== wesnoth.interface.highlight_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.highlight_hex'''(''x'', ''y'')

Draws an outline around the specified hex.

=== wesnoth.interface.select_unit ===

* {{LuaGameOnly}} '''wesnoth.interface.select_unit'''(''x'', ''y'', [''show_movement'', [''fire_events'']])
* {{LuaGameOnly}} '''wesnoth.units.select'''(''unit'', [''show_movement'', [''fire_events'']])
* {{LuaGameOnly}} ''unit'':'''select'''([''show_movement'', [''fire_events'']])

Selects the given unit in the game map as if the player had clicked on it.
Argument 3: boolean, whether to show the movement range of any unit on that location (def: true)
Argument 4: boolean, whether to fire any select events (def: false).

This function is available under two different names, but the possible arguments are the same in both cases. In other words, '''wesnoth.units.select''' can be called with a location instead of a unit, and '''wesnoth.interface.select_unit''' can be called with a unit instead of a location.

<syntaxhighlight lang=lua>
wesnoth.interface.select_unit(14, 6, true, true)
</syntaxhighlight>

If called without arguments, this function deselects the current unit from the map as long as the mouse cursor is not on its hex. It will continue to be displayed on the UI sidebar in any case.

=== wesnoth.interface.float_label ===

* {{LuaGameOnly}} '''wesnoth.interface.float_label'''(''x'', ''y'', ''text'')

Pops some text above a map tile.

<syntaxhighlight lang=lua>
wesnoth.float_label(unit.x, unit.y, "Ouch")
</syntaxhighlight>

=== wesnoth.interface.get_displayed_unit ===

* {{LuaGameOnly}} '''wesnoth.interface.get_displayed_unit'''() → ''unit''
* {{LuaGameOnly}} '''wesnoth.units.get_hovered'''() → ''unit''

Returns a proxy to the unit currently displayed in the side pane of the user interface, if any.

<syntaxhighlight lang=lua>
local name = tostring(wesnoth.interface.get_displayed_unit().name)
</syntaxhighlight>

=== wesnoth.interface.get_hovered_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.get_hovered_hex'''() → ''x'', ''y''

Returns the two coordinates of the currently hovered tile, that is, where the mouse cursor is located. This is mostly useful for defining command-mode helpers.

=== wesnoth.interface.get_selected_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.get_selected_hex'''() → ''x'', ''y''

Returns the two coordinates of the currently selected (highlighted) tile. This is mostly useful for defining command-mode helpers.

<syntaxhighlight lang=lua>
function chg_unit(attr, val)
local x, y = wesnoth.interface.get_selected_hex()
if not x then wesnoth.message("Error", "No unit selected."); return end
wesnoth.units.modify({ x = x, y = y }, { [attr] = val })
end
-- Function chg_unit can be used in command mode to modify unit attributes on the fly:
-- :lua chg_unit("status.poisoned", true)
</syntaxhighlight>

=== wesnoth.interface.get_viewing_side ===

* {{LuaGameOnly}} '''wesnoth.interface.get_viewing_side'''() → ''side'', ''full_vision''

Returns the viewing side of the current client in a multiplayer game.

For a player participating in the game, this will always be the side that they control, or, if they control multiple sides, the one they most recently had control over. However, for an observer client, this will return the currently-active side instead.

The second return value indicates whether the current client has full vision. This can only happen in replays or for observers.

For obvious reasons, use of this function can easily cause out-of-sync errors. Use with care.

=== wesnoth.interface.lock===

* {{LuaGameOnly}} '''wesnoth.interface.lock'''(''lock'')

Locks or unlocks gamemap view scrolling for human players. If true is passed as the first parameter, the view is locked; pass false to unlock.

Human players cannot scroll the gamemap view as long as it is locked, but Lua or WML actions such as wesnoth.scroll_to_hex still can; the locked/unlocked state is preserved when saving the current game. This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

<syntaxhighlight lang=lua>
wesnoth.interface.lock_view(true)
wesnoth.interface.scroll_to_hex(12, 14, false, true)
</syntaxhighlight>

=== wesnoth.interface.is_locked ===

* {{LuaGameOnly}} '''wesnoth.interface.is_locked'''() → ''locked?''

Returns a boolean indicating whether gamemap view scrolling is currently locked.

=== wesnoth.interface.scroll_to_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.scroll_to_hex'''(''x'', ''y'', [''only_if_visible'', [''instant'', [''only_if_needed'']]])
* {{LuaGameOnly}} '''wesnoth.units.scroll_to'''(''unit'', [''only_if_visible'', [''instant'', [''only_if_needed'']]])
* {{LuaGameOnly}} ''unit'':'''scroll_to'''([''only_if_visible'', [''instant'', [''only_if_needed'']]])

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. If true is passed as the fourth parameter, the view instantly warps to the location regardless of the scroll speed setting in Preferences. If true is passed as the fifth parameter, no scrolling occurs if the target location is already visible onscreen. It is also possible to pass a unit instead of a pair of tile coordinates (regardless of which module the function is called from).

<syntaxhighlight lang=lua>
local u = wesnoth.units.get "hero"
u:scroll_to()
</syntaxhighlight>

=== wesnoth.interface.scroll ===

* {{LuaGameOnly}} '''wesnoth.interface.scroll'''(''dx'', ''dy'')

Scrolls the map by the given amount, which may be either positive or negative.

=== wesnoth.interface.zoom ===

* {{LuaGameOnly}} '''wesnoth.interface.zoom'''(''factor'', [''relative'']) → ''new_zoom''

Changes the zoom level of the map. If relative is false, which is the default, it simply sets the zoom level. If relative is true, it zooms relative to the current zoom level. So, for example, if the zoom level is currently 0.5, then
<syntaxhighlight lang=lua inline>wesnoth.zoom(2)</syntaxhighlight>
sets it to 2, while
<syntaxhighlight lang=lua inline>wesnoth.zoom(2, true)</syntaxhighlight>
sets it to 1 (2 * 0.5).

This function also returns the resulting zoom level. Because of this, you can call
<syntaxhighlight lang=lua inline>wesnoth.zoom(1, true)</syntaxhighlight>
to simply get the current zoom level.

Note that this function cannot zoom to a level that the user would not be able to reach from the UI. Attempting to do so will simply select the nearest allowed zoom level.

=== wesnoth.interface.skip_messages ===

* {{LuaGameOnly}} '''wesnoth.interface.skip_messages'''([''skip?''])

Sets the skip messages flag. By default it sets it to true, but you can also pass false to unset the flag.

=== wesnoth.interface.is_skipping_messages ===

* {{LuaGameOnly}} '''wesnoth.interface.is_skipping_messages'''()

Returns true if messages are currently being skipped, for example because the player has chosen to skip replay, or has pressed escape to dismiss a message.

=== wesnoth.interface.add_chat_message ===

* {{LuaGameOnly}} '''wesnoth.interface.add_chat_message'''([''speaker'',] ''message'')

Displays a string in the onscreen chat. The chat line speaker is "Lua" by default, but it can be changed by passing a string before the message.

<syntaxhighlight lang=lua>
wesnoth.interface.add_chat_message "Hello World!" -- will result in "<Lua> Hello World!"
wesnoth.interface.add_chat_message("Big Brother", "I'm watching you.") -- will result in "<Big Brother> I'm watching you."
</syntaxhighlight>

See also [[LuaAPI/wml#wml.error|wml.error]] for displaying error messages.

=== wesnoth.interface.clear_chat_messages ===

* {{LuaGameOnly}} '''wesnoth.interface.clear_chat_messages'''()

Removes all messages from the onscreen chat, including error messages.

=== wesnoth.interface.add_item_image ===

* {{LuaGameOnly}} '''wesnoth.interface.add_item_image'''(''location'', ''filename'')

Places an image at a given location and registers it as a WML ''[item]'' would do, so that it can be restored after save/load. Note that the location must be passed as separate x and y coordinates, as in the example.

<syntaxhighlight lang=lua>
wesnoth.interface.add_item_image(17, 42, "items/orcish-flag.png")
</syntaxhighlight>

=== wesnoth.interface.add_item_halo ===

* {{LuaGameOnly}} '''wesnoth.interface.add_item_halo'''(''location'', ''filename'')

Behaves the same as [[#wesnoth.interface.add_item_image]] but for halos.

=== wesnoth.interface.remove_item ===

* {{LuaGameOnly}} '''wesnoth.interface.remove_item'''(''location'', [''filename''])

Removes an overlay set by [[#wesnoth.interface.add_item_image]] or [[#wesnoth.interface.add_item_halo]]. If no filename is provided, all the overlays on a given tile are removed. Note that the location must be passed as separate x and y coordinates, as in the example.

<syntaxhighlight lang=lua>
wesnoth.interface.remove_item(17, 42, "items/orcish-flag.png")
</syntaxhighlight>

=== wesnoth.interface.get_items ===

* {{LuaGameOnly}} '''wesnoth.interface.get_items'''(''location'') → ''array of item tables''

Get all items placed on the specified location. Note that the location must be passed as separate x and y coordinates.

=== wesnoth.interface.add_hex_overlay ===

* {{LuaGameOnly}} '''wesnoth.interface.add_hex_overlay'''(''location'', ''item_wml'')

Places a hex overlay (either an image or a halo) on the given location. The overlay is described by a table supporting the same fields as [[InterfaceActionsWML|[item]]]. This is a lower-level version of the item functions above. Note that the overlay is not kept over save/load cycles.

<syntaxhighlight lang=lua>
wesnoth.interface.add_hex_overlay(17, 42, { image = "items/orcish-flag.png" })
</syntaxhighlight>

=== wesnoth.interface.remove_hex_overlay ===

* {{LuaGameOnly}} '''wesnoth.interface.remove_hex_overlay'''(''location'', [''filename''])

Removes all the overlays at the given location, including any added by '''wesnoth.interface.add_item_halo''' or '''wesnoth.interface.add_item_image''' (however, such a removal will not be kept over save/load cycles). If a filename is passed as a third argument, only this overlay (either image or halo) is removed.

<syntaxhighlight lang=lua>
wesnoth.interface.remove_hex_overlay(17, 42, "items/orcish-flag.png")
</syntaxhighlight>

=== wesnoth.interface.end_turn ===

* {{LuaGameOnly}} '''wesnoth.interface.end_turn'''([''next_side''])

Immediately ends the current side's turn. By default, the next sequential side will gain control, but if you pass an argument that side gains control instead.

The ''next_side'' can either be a valid side number, or a valid side number plus the total number of sides in the scenario. In the latter case, this function also increases the turn counter by 1.

Using this, it's entirely possible to pass control around without ever increasing the turn counter.

=== wesnoth.interface.allow_end_turn ===

* {{LuaGameOnly}} '''wesnoth.interface.allow_end_turn'''(''allow'')
* {{LuaGameOnly}} '''wesnoth.interface.allow_end_turn'''(''reason'')

Enables or disables ending the turn in the UI. You can optionally pass a translatable string to show to the player if they attempt to do so anyway. It will be shown to the player without any additional framing, so it should normally be phrased similar to "You cannot end your turn because...".

To allow the player to end their turn again, just pass '''true'''. If you pass '''false''', a default message will be shown.

=== wesnoth.interface.color_adjust ===

* {{LuaGameOnly}} '''wesnoth.interface.color_adjust'''(''red'', ''green'', ''blue'')

Adjust the screen tint. (0,0,0) is no tint, and possible values range from -255 to 255.

=== wesnoth.interface.add_overlay_text ===

{{DevFeature1.17|3}}

* {{LuaGameOnly}} '''wesnoth.interface.add_overlay_text'''(''text'' [, ''options'']) → ''text handle''

Adds a text overlay to the screen that does not move with the map. [[Pango formatting]] is supported. The ''options'' table supports the following keys:

* ''size'' - The font size.
* ''max_width'' - Sets the maximum width the text can occupy on the screen, either in screen units (pixels) or as a percentage (a string ending in <tt>%</tt>). If the text is too long to fit in that width, it will automatically be word-wrapped. Defaults to 100%.
* ''color'' - The text color, either as a six-digit hex string (no leading <tt>#</tt>) or an array of three integers (red, green, and blue).
* ''bgcolor'' - If present, a background in this color is placed behind the text to enhance readability. This works like the background behind chat messages, but can be any colour. It is formatted the same as ''color''. If omitted, the background is fully transparent (ie, there is no background).
* ''bgalpha'' - If a background colour is specified, this sets its transparency. The default is fully opaque.
* ''duration'' - How long the text should be displayed, in milliseconds, or the string <syntaxhighlight lang=lua inline>'unlimited'</syntaxhighlight> for an infinite duration. Defaults to two seconds.
* ''fade_time'' - When the label is removed, either explicitly or because its duration expired, this is the time it takes to fade out, in milliseconds. A value of 0 means the label disappears instantly. Defaults to 100.
* ''halign'' - Where to anchor the text horizontally on the screen. Must be one of <syntaxhighlight lang=lua inline>'left', 'center', 'right'</syntaxhighlight>.
* ''valign'' - Where to anchor the text vertically on the screen. Must be one of <syntaxhighlight lang=lua inline>'top', 'center', 'bottom'</syntaxhighlight>.
* ''location'' - The screen offset where the text should be placed, relative to the specified anchor. Defaults to (0,0).

The text handle returned from this function supports the following method calls:

* ''handle'':'''move'''(''x'', ''y'')

Moves the text to a new location on the screen. The provided ''x'' and ''y'' are offsets from its current location.

* ''handle'':'''remove'''([''fade_time''])

Remove the text from the screen, optionally overriding the fade-out time.

* ''handle'':'''replace'''(''text'', ''options'') → ''handle''

Replaces the text with new text. Options are the same as in ''add_overlay_text'', and the returned handle is the same one.

=== wesnoth.interface.handle_user_interact ===

{{DevFeature1.17|6}}

* {{LuaGameOnly}} '''wesnoth.interface.handle_user_interact'''()

Handle user interaction with the game interface. This can be inserted into Lua code that takes a long time to execute in order to prevent the user interface from freezing.

== wesnoth.interface.game_display ==

* {{LuaGameOnly}} '''wesnoth.interface.game_display'''.''theme_item'' ↔ '''function'''() → ''wml table of theme elements''

This is an associative table linking item names to functions that describe the content of the in-game user interface. These functions are called with no arguments whenever the user interface is refreshed, and must return a WML table containing '''[element]''' children. Each subtag shall contain either a '''text''' or an '''image''' field that is displayed to the user. It can also contain a '''tooltip''' field that is displayed to the user when moused over, and a '''help''' field that points to the help section that is displayed when the user clicks on the theme item.

Note that the '''wesnoth.interface.game_display''' cannot be iterated using '''pairs''' or '''next''' to retrieve the items from the current theme. However, built-in items ''can'' be recovered as long as their name is known. The example below shows how to modify the ''unit_status'' item to display a custom status:

<syntaxhighlight lang=lua>
local old_unit_status = wesnoth.interface.game_display.unit_status
function wesnoth.interface.game_display.unit_status()
local _ = wesnoth.textdomain "mydomain"
local u = wesnoth.interface.get_displayed_unit()
if not u then return {} end
local s = old_unit_status()
if u.status.entangled then
table.insert(s, wml.tag.element {
image = "entangled.png",
tooltip = _"entangled: This unit is entangled. It cannot move but it can still attack."
})
end
return s
end
</syntaxhighlight>

The things that would need to be to modified in the above code are:

* the domain of your addon ("mydomain"), assuming that you are using translations. Otherwise just remove the underscore in the tooltip line.
* the name of the status (u.status.entangled). Note that if the attribute happens to be inside [variables], so be it: u.variables.whatever.
* the path to the image ("entangled.png").
* the tooltip of the status ("entangled: This unit ...").

The following is a list of valid entries in '''wesnoth.interface.game_display''' which will have an effect in the game, together with sample output and a brief description of their use.

=== unit_name ===

Shows the name of the unit the mouse is hovering over.

=== unit_type ===

Shows the type of the unit the mouse is hovering over.

=== unit_race ===

Shows the race of the unit the mouse is hovering over.

=== unit_side ===

Shows the side number and team color of the unit the mouse is hovering over.

=== unit_level ===

Shows the level of the unit the mouse is hovering over.

=== unit_amla ===

Similar to unit_advancement_options but shows AMLAs only.

=== unit_traits ===

Shows the list of trait names for the unit the mouse is hovering over.

=== unit_status ===

Shows the status icons for statuses afflicting the unit the mouse is hovering over.

=== unit_alignment ===

Shows the alignment of the unit the mouse is hovering over.

=== unit_abilities ===

Shows the ability names of the unit the mouse is hovering over.

=== unit_hp ===

Shows the current and maximum hit points of the unit the mouse is hovering over.

=== unit_xp ===

Shows the current and target experience points of the unit the mouse is hovering over.

=== unit_advancement_options ===

Shows the options the unit the mouse is hovering over has for advancement, including both level ups and AMLAs. This item is not used in the default theme.

=== unit_defense ===

Shows the defense of the unit the mouse is hovering over.

=== unit_vision ===

Shows the current and maximum vision points of the unit the mouse is hovering over.

=== unit_moves ===

Shows the current and maximum movement points of the unit the mouse is hovering over.

=== unit_weapons ===

Shows the available weapons of the unit the mouse is hovering over. The default generator expresses each weapon line (basic details, specials, etc) as a separate <code>element</code>. For example:

<syntaxhighlight lang=wml>
[element]
image="melee.png"
tooltip="...stuff..."
[/element]
[element]
image="arcane.png"
tooltip="...stuff..."
[/element]
[element]
text="6×3 holy sword"
tooltip="...stuff..."
[/element]
[element]
# This is empty if the range and type icons both exist.
text="melee-arcane"
tooltip="...stuff..."
[/element]
# If the weapon has accuracy or parry...
[element]
text="+20%/-10%"
tooltip="Accuracy: +20%
Parry: -10%
"
[/element]
# If the weapon has special abilities...
[element]
text="magical"
tooltip="...stuff..."
[/element]
</syntaxhighlight>

=== unit_image ===

Shows the sprite of the unit the mouse is hovering over.

=== unit_profile ===

Shows the portrait of the unit the mouse is hovering over.

=== selected_unit ===

Nearly every item beginning with '''unit_''' has a corresponding item beginning with '''selected_unit_''', which describes the currently-selected unit (if any) rather than the unit the mouse is hovering over. These items are not used in the default theme.

There is no '''selected_unit_amla''' however.

=== highlighted_unit_weapons ===

This is almost the same as '''selected_unit_weapons''' but with slightly different logic of choosing which unit to show.

=== tod_stats and selected_tod_stats ===

Shows the time of day stats for the hex the mouse is hovering over or the hex the selected unit is on. The time of day stats shows the counter of your position in the schedule as well as the entire cycle.

=== time_of_day and selected_time_of_day ===

Shows the time of day image for the hex the mouse is hovering over or the hex the selected unit is on.

=== unit_box ===

This is an experimental item that combines a unit display and the time of day.

=== turn ===

Shows the current turn count.

=== gold ===

Shows the amount of gold for the active side.

=== villages ===

Shows the number of villages owned by the active side.

=== num_units ===

Shows the number of units owned by the active side.

=== upkeep ===

Shows the upkeep and expenses for the active side.

=== income ===

Shows the income for the active side

=== terrain_info ===

Shows the icons of the terrain on hex the mouse is hovering over.

=== terrain  ===



Shows the name of the terrain on the hex the mouse is hovering over. For example:

<syntaxhighlight lang=wml>
[element]
text="Grassland (Flat)"
[/element]
</syntaxhighlight>

=== position ===

Shows the map coordinates of the hex the mouse is hovering over.

=== zoom_level ===

Shows the zoom level as a percentage. This item is not used in the default theme.

=== side_playing ===

Shows the active side's flag.

=== observers ===

When there is no observer, it returns an empty table. When there are observers, it returns:

<syntaxhighlight lang=wml>
[element]
tooltip="Observers
<observer1>
<observer2>
"
image="misc/eye.png"
[/element]
</syntaxhighlight>

=== report_clock ===

This returns the current time in HH:MM format according to the user's preferences, for example:

<syntaxhighlight lang=wml>
[element]
text="22:32"
[/element]
</syntaxhighlight>

=== report_countdown ===

This returns the current chess-timer countdown in MM:SS format for the player's turn, for example:

<syntaxhighlight lang=wml>
[element]
text="12:43"
[/element]
</syntaxhighlight>

Depending on the time limit, the text may also be colored using [[Pango formatting|Pango markup]].

If there is no time limit set then it forwards to [[#wesnoth.interface.game_display.report_clock|report_clock]].

[[Category:Lua Reference]]

Sandbox/GUI/Getting Started

2024-11-01T23:42:15Z

White haired uncle: /* Adding a little flavor */

So, it looks like I can't exclude this page/section from the search engine as I had hoped. I wanted to put this in a sandbox so that it wouldn't be published without some proper review.

==Introduction==

This guide is designed to help you get a simple Wesnoth GUI, implemented in lua, up and running while describing the basic building blocks along the way. It is written in a narrative format, where most examples build on previous examples, and therefore while not always necessary it may be desirable to read from start to finish. The reader, probably a UMC author, should have a basic knowledge of working with lua within Wesnoth.

Some would find creating a GUI in part or in full using WML simpler to follow, and those alternatives are available, for example [[LuaAPI/gui/example]], but we're using lua here. If you find WML easier to follow, you can always convert the lua tables that define the GUIs to WML using [[LuaAPI/wml#wml.tostring|wml.tostring]], for example:

<syntaxhighlight lang=lua>
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
</syntaxhighlight>

In the comments of our first GUI, below, is an example which loads a WML GUI configuration using [[LuaAPI/wml#wml.load|wml.load()]], validating against the GUI2 window schema.

In some examples, instead of defining the entire GUI at once, we'll break out some parts into separate variables. If you try to view one in WML and get an error from wml.tostring() about expecting a WML table and not a table, try passing your variable(/table) inside a table:

<syntaxhighlight lang=lua>
print(wml.tostring({listboxItem}))
gui.show_lua_console()
</syntaxhighlight>

===What is GUI2?===
Once upon a time, Wesnoth had a GUI system which is now commonly referred to as GUI1. As of 1.19, GUI1 has been almost completely replaced by GUI2. UMC authors will probably never encounter GUI1 and can simply use the terms GUI and GUI2 interchangeably, at least until GUI3 comes along.

Instead of spending a lot of time here giving an overview of what GUI2 is and what makes it great, and not so great, let's charge ahead so we can see it in action, and let readers who are interested look elsewhere(TODO: link) for a more formal definition. (TODO: is this the right approach for most readers?).

==Getting Started==

For example purposes, we'll create a directory in our campaign directory called lua containing a file called gui_tutorial.lua, and add a command in the prestart event for a scenario which will create a right-click menu option to invoke our new GUI. Of course there are other methods to invoke lua from WML, but this one will get us started. After all, we really just want to get something up on the screen ASAP, right?

===A most basic GUI===

{|
|[[File:Most basic gui.png|center|thumb|I can't believe this worked]]
|-
|In our prestart event, we create a simple menu item, which executes a single line of lua which calls the lua function most_basic_gui() which is found in gui_tutorial.lua:
|}

<syntaxhighlight lang=wml>
[set_menu_item]
id=most_basic_gui
description="Our first GUI"
[command]
[lua]
code=<<
wesnoth.require("~add-ons/<OUR_CAMPAIGN>/lua/gui_tutorial.lua").most_basic_gui()
>>
[/lua]
[/command]
[/set_menu_item]
</syntaxhighlight>

And create gui_tutorial.lua:
{| class="wikitable" style="margin:auto"
! !! The WML equivalent of dialogDefinition
|-
|
<syntaxhighlight lang=lua>
local function most_basic_gui()
local dialogDefinition = {
--click_dismiss = true, -- allow user to close dialog with click of a button
wml.tag.tooltip { id = "tooltip_large" }, -- required
wml.tag.helptip { id = "tooltip_large" }, -- required
wml.tag.grid { -- our most basic gui
wml.tag.row { -- a grid must include at least one row
wml.tag.column { -- a row needs a column
wml.tag.image { -- a column includes exactly one widget
label = "units/trolls/grunt.png"
}
}
}
}
}

local function preshow(dialog)
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
end
gui.show_dialog(dialogDefinition,preshow)

-- Or, if you want to define the gui in WML, something like:
-- local dialog_wml = wml.load("~add-ons/GUI_Tutorial/most_basic_gui.cfg",
-- true, "schema/gui_window.cfg")
-- gui.show_dialog(wml.get_child(dialog_wml, 'resolution'))
end
return { most_basic_gui = most_basic_gui}
</syntaxhighlight>
|
<syntaxhighlight lang=wml>
[tooltip]
id="tooltip_large"
[/tooltip]
[helptip]
id="tooltip_large"
[/helptip]
[grid]
[row]
[column]
[image]
label="units/trolls/grunt.png"
[/image]
[/column]
[/row]
[/grid]

</syntaxhighlight>
|}

In the above file, we have just the single function to create our GUI, followed by a return command which makes our function most_basic_gui() available to the [[LuaAPI/wesnoth#wesnoth.require|wesnoth.require()]] function as most_basic_gui().

Our function creates a table containing the definition of a "dialog", and then passes that to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]]. It should be noted that gui.show_dialog does not provide synchronization, so if your GUI makes changes to the game state, you'll need to jump through some hoops or you'll break replays and multiplayer, but that's not something we need to care about at this point, so just be aware that you may need to deal with it in the future.

Our dialog definition at this point includes three parts. The first two are a tooltip and a helptip, which are required and define how tooltips (use id = "tooltip_large" or id = "tooltip" or id = "tooltip_transparent"), and helptips (rarely used, but must be included here, and yes their definitions are "tooltip" not "helptip") will look (as we will see later, this really should be definition = "tooltip", but in this case it's id = "tooltip"). The third part is a grid, which is basically a table, like in HTML or MySQL, with rows and columns. A grid always contains at least one row. A row contains at least one column (note that a column does NOT span rows, it is completely contained within a row). Inside a column is exactly one item, a cell which contains a [[GUIWidgetDefinitionWML|widget]], in this case we'll use an image (later we'll see what else we can put in a cell). Note that we don't actually define a cell in our code, it's just a term used to refer to the contents of a column.

The preshow function is optional. If included in the call to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]], it is run before the GUI is displayed. In this case, we include it to display the dialog we created with lua in WML format. Near the end, in comments, we show how you would call [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] if you chose to define your dialog using WML. Note that what is shown here is the WML equivalent of our lua dialogDefinition, and not the complete WML you would need to use if you were to configure your GUI layout in WML.

Note: if you should try out the above, you'll have to hit escape or enter to close the GUI. Uncomment the "click_dismiss" line, and the user will be able to close the GUI with a mouse click.

===Adding a little flavor===

{|
|You may have noticed our GUI is missing a header and a way to close it when we're done admiring our work. Here we add a new first row to our grid, while demonstrating a couple formatting options: a border to put some distance between our grid cell and its neighbor, and the "use_markup = true" option to enable Pango support in our text.

Our third row adds an OK button at the bottom. You can associate actions with buttons to do all kinds of things, but here we just exploit the default behaviour to close the GUI.

Of course, we'll also have to modify our return to support the new function, and update our menu item(s) accordingly.
|-
|[[File:Most basic gui2.png|center|thumb|Adding header and a footer]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui2()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
wml.parse(wml.tostring({wml.tag.resolution(dialogDefinition)}), "schema/gui_window.cfg") -- schema validation errors will go to log
gui.show_dialog(dialogDefinition)
end
return { most_basic_gui = most_basic_gui, most_basic_gui2 = most_basic_gui2 }
</syntaxhighlight>

Note that in this example, just before we invoke gui.show_dialog(), we use [[LuaAPI/wml#wml.parse|wml.parse()]] to validate our input against the GUI2 window schema. If we've misspelled something, or placed a key in the wrong place (like placing a border in a widget instead of a column), etc, an error such as '''error validation: Invalid key 'garbage=' in tag [resolution]''' will be written to the wesnoth log.

===And a bit more===
{|

|And now a minor, but important change. We want to add a new text field next to the image in the body of our GUI. Obviously, we want to add a new column, but this is more difficult than when we added new rows in the previous example. The problem is that all rows (at a given level) in a grid must contain the same number of columns. We can't have two columns in the row that constitutes the body of our GUI, but only one in the header and one in the footer. To solve this problem, we replace our image widget with a new grid, which can use as many columns as we like (as long as they are the same within each row of our new grid). This new grid contains a row with two columns, but that is okay because the new grid itself is placed in a single column, which matches our single column header and footer (ok button), keeping the rows balanced.
|-
|[[File:Most basic gui3.png|center|thumb|Rows with different numbers of columns]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui3()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column { -- This is the only column in this row,
-- to match the number of columns in
-- the rows of our header and footer
wml.tag.grid { -- A new grid, so we can use a different
-- number of columns
wml.tag.row {
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
},
wml.tag.column {
wml.tag.label {
label = "A troll"
}
}
}
}
}
},
wml.tag.row { -- A footer
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = "Ok"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

While we see here just the simplest of examples, you can create many levels of grids inside grids, rows with multiple columns some of which containing grids, etc, to build complicated dialogs to your liking.

==Containers==

===Stacked Widget===

TODO

===Listbox===
{|
| Now we'd like to add some more monsters. Obviously, we could just add more rows, but what if we won't know until runtime how many and which ones? We could break up the definition of our dialog and add new rows dynamically, it's just a table after all, but fortunately we have a widget which handles this for us, a listbox. A listbox is kind of like an array, a collection of similar objects where the number of items can vary. We will tell the GUI where we want the box, and what each entry in the box will look like, and then at runtime we can add entries to the box.

Note that listbox items are added from top to bottom. Another container, the horizontal_listbox, works just like a listbox except the items are added from left to right. With a grid listbox, items are added horizontally with the list wrapping to a new line as necessary.
|-
| [[File:Gui with listbox.png|center|thumb|Listbox with three items. Each item is an image and a label. The third item has been selected.]]

<syntaxhighlight lang=lua>
local function gui_with_listbox()
local monsters = {
{ image = "units/trolls/grunt.png",
string = "A troll" },
{ image = "units/monsters/cuttlefish.png",
string = "A cuttlefish" },
{ image = "units/monsters/yeti.png",
string = "A yeti" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
}

local listboxDefinition = wml.tag.listbox { id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
listboxDefinition
}
},
wml.tag.row {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_label.label = monster.string
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We begin by creating a simple table which represents the data which will be presented in our listbox. In most cases, we probably wouldn't create that monster table here, but we need it for our example.

The variable listbox_id gives us an identifier for our listbox so we can reference it when we need to. We don't really need to use a variable here, it's just convenient.

We define the structure for the elements in our listbox, stored in listboxItem. Note that we've replaced the actual data with identifiers (e.g. 'units/trolls/grunt.png' becomes 'id = "monster_image"), since each element may have different data.

We define the listbox itself, specifying the identifier, and the definition of our listbox element (which looks a lot like a grid). The cell inside the column contains a variable which is just the listbox element definition we created above; it's not necessary to do this, we could have used one big table, but it's easier to read this way (IMO).

We replace the hardcoded data in our GUI body with our new listbox definition, again using a variable to make it easier to read.

We create a function, often called preshow(), which will be called for us as part of the drawing the GUI (see the new optional argument in [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] -- there's also an optional postshow(), but we don't need it here). This is where we pull the data from our example table into the listbox. We create a listbox variable associated with the listbox, identified by the listbox_id we assigned earlier, inside the dialog which gui.show_dialog() passes to preshow(). Then we iterate through our data table, using each entry from that table to populate a listbox item.

Let's look at that last action a little more closely using an example.

<syntaxhighlight lang=lua>
listbox[i].monster_image.label = monster.image
</syntaxhighlight>

Which we can read as "In listbox element i of our listbox, for the image with identifier monster_image which we defined in our listboxItem, use the data from the corresponding index i in our example data table" (you don't see the index i for the monsters table here, but remember we're iterating using ipairs, we could have just as easily used listbox[i].monster_image.label = monsters[i].image). If you were to step through all of the variable substitutions, you'd see that for i=1, our dialogDefinition is basically the same thing as it was in the earlier examples, just supplied from a table instead of hardcoded (note that you can hardcode entries in a listbox in your dialog definition using the [list_data] tag, aka wml.tag.list_data, which we do not demonstrate here).

You will probably notice that our data does not line up nicely in the GUI. We will fix that later. We'll also demonstrate how the user can select an item in a listbox, and how you can identify which item that was using the selected_index variable of the listbox.

===Tree View===
====Simple Tree View====
{|
| You may have noticed that clicking on a listbox item in our listbox caused it to be highlighted with a box around the contents. This is because the items in a listbox are selectable. This will be useful when we want to add actions, but it looks a bit odd if we just want to present a list of data.

Also, most of the data had to be formatted the same for each item in the listbox. We could, perhaps, include custom markup in our labels, but the actual layout, like the number of columns per row, had to be the same for every item.

Another way to present a list of data is the tree view. Since a tree view supports multiple data types, we may need to create multiple definitions for the elements in our list. These are known as nodes. It will also be necessary to explicitly define which node to use for each element when we populate our tree view.
|-
| [[File:Basic tree view.png|center|thumb|Tree_views can hold multiple data types (only trolls have names here)]]
|}
<syntaxhighlight lang=lua line>
local function basic_tree_view()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", type = "Seamonsters" },
{ image = "units/monsters/yeti.png", label = "A yeti",
type = "Coolers" }
}

local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "trolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name",
linked_group = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
},
wml.tag.node {
id = "nottrolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "monster_name",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_image",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_label",
fixed_width = true
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_tv:add_item_of_type("trolls_node")
dialog.monsters_tv[i].monster_name.label = monster.name -- only trolls have a name
else
dialog.monsters_tv:add_item_of_type("nottrolls_node")
end
-- All of our monsters have an image and a label
dialog.monsters_tv[i].monster_image.label = monster.image
dialog.monsters_tv[i].monster_label.label = monster.label
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We have expanded our list of monsters to include three types of trolls. We have also given each troll a name. This is of course a rather simplistic example, we could have simply given each monster that is not a troll an empty name, but it as presented here our approach serves the purpose of demonstrating how we deal with multiple data types. Our new tree view contains a node for each type of data we will present. In preshow, we explicitly define each element in our list using add_item_of_type(), and populate the item accordingly. [Note: in our listbox example, we could have used add_item() to add items to the listbox, but chose not to since that section was already introducing a number of new concepts. But here, since we have multiple types of items we need to be able to specify the type of the item when we add one, hence we need to use add_item_of_type()].

You may also note the addition of a few linked_group lines. We'll cover linked groups in more detail later, but as used here they instruct the GUI that each column using the same node type needs to be aligned with the others. For example, all of our trolls line up nicely.

====Building a Tree====
{|
| colspan="2" |At this point, one may wonder about the name "tree view", since what he have seen doesn't look much like a tree. To make a tree-like structure, we'll demonstrate adding children to nodes. At the top level our (upside-down) tree will have two nodes, one for trolls and one for everything else. A toggle_button (a type of button which changes states when you push it) will allow us to expand the trolls node to expose its children, which are themselves nodes, though they only contain a label at this point.
|-
| [[File:Basic tree view2a.png|center|thumb|Tree_view with Trolls folded]] || [[File:Basic tree view2b.png|center|thumb|Tree_view with Trolls unfolded]]
|}
<syntaxhighlight lang=lua line>
local function building_a_tree()
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
}
},
wml.tag.column {
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Show me the " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
-- You can refer to an object by its position

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[1].race_label.label = "Trolls"
-- dialog.monsters_tv[1].race_button.on_modified =
-- function()dialog.monsters_tv[1].unfolded =
-- dialog.monsters_tv[1].race_button.selected end

-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][1].monster_type.label = "Whelp"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][2].monster_type.label = "Shaman"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][3].monster_type.label = "Troll"

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[2].race_label.label = "Other scary things"
-- dialog.monsters_tv[2].race_button.visible = "hidden"

-- ... or you can refer to that object using the return value
-- from add_item_of_type
local troll_node = dialog.monsters_tv:add_item_of_type("race_node")
troll_node.race_label.label = "Trolls"
troll_node.race_button.on_modified =
function()
troll_node.unfolded = troll_node.race_button.selected
end
local item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Whelp"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Shaman"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Troll"

local not_troll_node =
dialog.monsters_tv:add_item_of_type("race_node")
not_troll_node.race_label.label = "Other scary things"
not_troll_node.race_button.visible = "hidden"

end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We define two nodes in our tree, a race_node for the top level, and a details_node for the children of a race_node. The rest of the interesting bits are in preshow().

We demonstrate two different ways of creating and accessing items, the first (commented out) just using the order in which they are created, while in the second we capture the result of add_item_of_type() in a variable we can use to refer to the newly defined object. The first method is shown primarily to demonstrate the structure of the resulting objects. The second method is perhaps easier to follow, and is almost necessary when you start doing things like dynamically deleting nodes, so it is in most cases a better practice (of course, you probably won't want to use the same variable for each node like we did, and perhaps not one local to the preview function).

We add a node, label it "Trolls", and add a callback to the button such that the children of the node will be visible (the node is "unfolded", a boolean value which defaults to false) when the button is checked (selected == true). Then we add three "details_node" nodes as children of this node.

Our second node, "Other scary things" will remain empty for now, so we'll set the visible attribute on its button to "hidden" (which is like false, but with hidden the widget still takes up space).

{|
| This example is rather ugly, both in the hardwired code and the appearance of the resulting GUI, but it addresses a couple important aspects of how tree views work and how we might use them. Let's clean it up a bit. We'll add an indentation_step_size to the tree view, along with a spacer and [[#Alignment|horizontal_alignment]] to our details node, to make the labels line up nicely, and change the button [[#Definitions|definition]] to replace the checkbox with something that looks like it belongs there. We will look at methods for handling layout in more depth [[#Appearance|later]].
|-
| [[File:Basic tree view2c.png|center|thumb|Our tree_view with proper alignment]]

<syntaxhighlight lang=lua>
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
indentation_step_size = 20,
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
definition = "tree_view_node"
}
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.spacer { width = 40 }
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}

</syntaxhighlight>

===Multi_page===
====Simple Multi_page====
{|
|-
Like a tree_view, a multi_page is a heterogeneous container which is dynamically populated, however, while a multi_page contains multiple elements (pages), only one page is displayed at any one time. Its purpose is perhaps best described by a couple of examples.
|-
[[File:Basic multipage.png|center|thumb|Multi_page showing active page]]
|}
<syntaxhighlight lang=lua>
local function basic_multipage()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll",
name = _"Bob", type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp",
name = "Junior", type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman",
name = _"Alice", type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish",
type = "Seamonsters" },
{ image = "units/monsters/yeti.png",
label = "A yeti",
type = "Coolers" }
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
multi_page
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}

local function preshow(dialog) -- Prepare the GUI before display
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_label.label = monster.label
end
--dialog.monsters_mp.selected_index = 5
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

As you can see, the code for our basic multi_page GUI looks a lot like our basic tree_view GUI. The difference is what is displayed. While both the tree_view and the multi_page containers contain five items, with the multi_page, only the first one is displayed. More specifically, only the page associated with the selected_index attribute of the multi_page object, which defaults to 1, is displayed. If we were to uncomment the last line in preshow(), we would still see only one item, but it would be the fifth one we allocated. It's nice to know all our pages are in there somewhere, but this example is pretty useless. What we need is a way to select which page we want to see from within our GUI.

====A More Useful Multi_page====

{|
| colspan="2" | To demonstrate the usefulness of a multi_page, and highlight its difference from a tree_view, we'll add a listbox to allow us to select the page to view. We'll also need to add a little action to our GUI.
|-
| style="align:centered" |[[File:More useful multipage.png|center|thumb|User selected Troll]] || [[File:More useful multipage2.png|center|thumb|User selected Cuttlefish]]
|}

<syntaxhighlight lang=lua>
local function more_useful_multi_page()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
race = "Trolls", tip = "Your uncle" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
race = "Trolls", tip = "Your nephew" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
race = "Trolls", tip = "Your auntie" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", race = "Seamonsters",
tip = "Not a fish" },
{ image = "units/monsters/yeti.png",
label = "A yeti", race = "Coolers",
tip = "ROAR!" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
}
}
}

local listboxDefinition = wml.tag.listbox {
id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
},
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
listboxDefinition
},
wml.tag.column {
wml.tag.spacer {
width = 30
}
},
wml.tag.column {
multi_page
},
}
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_image.tooltip = monster.tip
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_image.tooltip = monster.tip
dialog.monsters_mp[i].monster_label.label = monster.label
end
local function switch_page()
dialog.monsters_mp.selected_index = listbox.selected_index
end
listbox.on_modified = switch_page
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

Most of this should look pretty familiar. We've simply taken the previous example and added a second column to our GUI using code from an earlier example to add a listbox. In addition, we altered the page layout slightly, and added a spacer column in the dialog definition to approve the appearance.

The interesting stuff is in preshow(). Again we've merged in some listbox code from an earlier example, but we've also created a new local function switch_page(), which simply sets the selected_index attribute of our multi_page to the same as that of our listbox, and then we've configured the listbox.on_modified callback to call switch_page(). Now when the user selects an item in the listbox (updating listbox.selected_index and triggering listbox.on_modified), dialog.monsters_mp.selected_index is updated accordingly and therefore the visible page changes to the one associated with the selected unit.

Also note in preshow() we've added a new child to our monster_image identifier for both the listbox and the multi_page, a tooltip. When the user hovers the mouse over the image of one of our monsters, they'll see a popup message which we've added to our monster table. Try changing '''wml.tag.tooltip { id = "tooltip_large" }''' to '''wml.tag.tooltip { id = "tooltip }''' in the dialogDefinition to see a different tooltip style.

==Actions Have Consequences==

So far, our GUIs have only displayed some information on the screen, but at some point we're probably going to want to use a GUI to get input from the user. In this section we will look at return values that can be assigned to a widget based upon its state, and callbacks, which are functions invoked when something happens with a widget. As we will see, a button is a good example, as it can return a value or take an action, or both, when pressed. Earlier we saw how the selected_index attribute of some widgets, such as the listbox, can also be used as a sort of return value.

===Buttons===
{|
| colspan=2 | In this example, we'll create a couple buttons which provide the user a choice, use a handy confirmation popup to confirm that choice, and demonstrate how we get the results back where we can put them to use.
|-
| [[File:Basic return value.png|center|thumb|There can be only one]] || [[File:Basic return value_confirm.png|center|thumb|The user selected Alice, let's confirm this critical choice]]
|}

<syntaxhighlight lang=lua>
local function basic_return_value()

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "leader_lg",
fixed_height = true,
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" ..
_"Which unit shall lead your army?" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Alice" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/elves-wood/sylph.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 1
}
}
},
}
},
wml.tag.column {
wml.tag.spacer { width = 20 }
},
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Bob" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/human-loyalists/marshal.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 2
}
}
}
}
}
}
}
}
}
}
}
local user_chose = gui.show_dialog(dialogDefinition)
local leader
if user_chose == -1 then -- User closed the dialog by hitting the Enter key
leader = nil
end
if user_chose == -2 then -- User closed the dialog by hitting the Escape key
leader = nil
end

if user_chose == 1 then
leader = "Alice"
end
if user_chose == 2 then
leader = "Bob"
end

local confirmed_leader_choice

if leader ~= nil then
local query = _"You want " .. leader .. _" as your leader?"
confirmed_leader_choice = gui.confirm(query)
end

if confirmed_leader_choice then
wesnoth.message("Great!")
else
wesnoth.message("Fine, lead them yourself!")
end
end
</syntaxhighlight>

Here we've added a couple buttons, and assigned each of them a return value. When the user selects one of these buttons, the GUI is closed and the value of return_value is returned from gui.show_dialog(). We then use [https://wiki.wesnoth.org/LuaAPI/gui#gui.show_prompt gui.confirm()] which provides a very simple Yes/No popup and returns true or false, respectively. Other useful functions can be found on that page which provide handy alternatives to creating your own GUI for other simple user inputs.

The use of return_value is rather limited, as it only returns integers and can't be used with containers like listboxes. In more complex cases we'll need to turn to callback functions which are invoked when something happens to a widget, like clicking a button or a widget's value changing. Earlier, we saw an example of [[LuaAPI/types/widget#on_modified|widget.on_modified()]]. More examples of callbacks can be found at [[LuaAPI/types/widget#on_modified|that link]].

===Slider and Textbox===
{|
| Here we see a couple methods of getting more dynamic input from the user, a slider and a textbox presented in one silly example.
|-
| [[File:Slider and textbox.png|center|thumb|Two ways of getting input from the user]]
|}

<syntaxhighlight lang=lua>
function slider_and_textbox()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = _"How much gold will you pay for this old rusty sword?"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.slider {
id = "gold_sl",
minimum_value = 0,
maximum_value =
wesnoth.sides[wesnoth.current.side].gold,
value = math.floor(
wesnoth.sides[wesnoth.current.side].gold/2)
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.text_box {
id = "gold_tb",
--hint_text = _ "Enter gold here",
--hint_image = "images/gold_pile.png",
label = tostring(math.floor(
wesnoth.sides[wesnoth.current.side].gold/2))
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
local function show_input()
wesnoth.interface.add_chat_message(_"You chose " ..
dialog.gold_sl.value .. _" with the slider")
wesnoth.interface.add_chat_message(_"You entered " ..
tostring(dialog.gold_tb.text) .. _" in the text_box")
end
-- this is a button, so we use on_button_click, not on_left_click
dialog.ok.on_button_click = show_input

dialog.gold_sl.on_modified = function()
dialog.gold_tb.text = tostring(dialog.gold_sl.value)
end
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We create a slider, with a range from 0 to the amount of gold possessed by the current side and an initial value in the middle, and a text box with the same initial value. We assign a function to our OK button which simply reports on the values provided by the user. For no reason whatsoever, we add a callback such that when the user adjusts the slider the value in the textbox is update to match the slider.

Note that the textbox returns text, even though it looks like we're expecting the user to input a natural number. Remember to validate those inputs.

You can use text_hint to place a caption in the box that will help the user understand what to enter in the box, and possibly an image as well. For example, in the search box in the recall menu uses '''hint_text = _ "Search", hint_image = "icons/action/zoomdefault_25.png~FL(horiz)"'''. Of course, you can't have a hint and a label in the same text_box at the same time, so in our example we've only included them as comments.

There is also a widget called a spinner, which is kind of like the combination of a text_box and a slider. As of the release of 1.18, it appears to be unfinished so the strange syntax needed to make it work is probably not the best thing to document, and we will omit it for now.

==Appearance==

'''This section needs help'''

===Borders===

Borders allow you to force unused space around a column, for example so that your widgets don't runtogether. You can specify the border to be one or more of top, bottom, left, right, or all. The border_size sets the amount of padding, in pixels.

<syntaxhighlight lang=lua>
wml.tag.column{
border = "left, right"
border_size = 25
}
</syntaxhighlight>

===Alignment===
{|
| colspan=2 |By default, the GUI will usually center widgets in their cells, which is not always what we want. In this example, we use horizontal_alignment to move widgets around a little.

In more complex cases, it may be useful to add [[GUIWidgetDefinitionWML#Spacer|spacers]] to help force alignment, or use linked_groups to force consistent alignment for objects within a grid.
|-
| [[File:Gui tutorial alignment without.png|center|thumb|Default alignment]] ||[[File:Gui tutorial alignment with.png|center|thumb|Showing off some alignment options]]
|}
<syntaxhighlight lang=lua>
local function basic_alignment()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = "Ralph"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "right",
wml.tag.label {
label = "Sam"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/troll-hero-attack-se-4.png" -- 122x102
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "left",
wml.tag.label {
label = "Jr"
}
},
wml.tag.column {
horizontal_alignment = "right",
wml.tag.image {
label = "units/trolls/whelp.png" -- 72x72
}
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

The screenshots show the output of this example with and without the horizontal_alignment lines included above.

A label allows you to set the text_alignment field (e.g. text_alignment = "left"). Note, however, this only aligns the text within the label. The label itself will probably be centered in the column, giving the false appearance that your text alignment is not working.

===Growth===

To keep your dialog nicely balanced, the GUI2 engine may need to grow rows and/or columns. You can control which columns, for example, grow and which do not, by setting some with grow_factor = 1, and others with grow_factor = 0 (do not grow). While grow factors of 0 and 1 are the most common, you can use other values to adjust the relative growth if you really need to, see [[GUILayout]] for the gory details.

It it sometimes useful to include a column with a [spacer] and a grow_factor (often the only column with grow_factor != 0) whose sole purpose is to keep your GUI aligned nicely as the layout engine does its evil.

To force a column to stretch to fit available space, use horizontal_grow = true. Note that horizontal_grow is not compatible with horizontal_alignment. There is also a vertical_grow parameter.

If you need to see every little detail about the layout process, start wesnoth with --log-debug=gui/layout. Good luck with that.

===Definitions===
Many widgets can be configured to have to a different appearance, for example in our tree_view example we changed the definition of a toggle_button from the default of a checkbox by setting definition = "tree_view_node". This option was found by looking at the id of a toggle_button_definition in .../data/gui/widget/toggle_button_tree_view_node.cfg:

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib
###
### Definition of a toggle button to be used in a tree view as node fold/unfold indicator
###
[toggle_button_definition]
id = "tree_view_node" # <--- we can use 'definition = "tree_view_node"' in a [toggle_button] to select this definition
description = "Fold/unfold status indicator of a tree view node."
</syntaxhighlight>

{|
|There are many other definitions for buttons and other widget types in that directory. It would be nice to have a list (linked here), but for now you'll just have to look around.

We can even create our own custom definitions using [[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition()]]. In this example, we copy from .../data/gui/widget/toggle_button_tree_view_node.cfg with a slight change so that our button turns red ( '''~BLEND(255,0,0,1)''' ) when focused.

In this example, we will use wesnoth.wml_actions to create the WML tag [add_widget_def_demo].

Note the first line, a common convention for creating an alias for wml.tag.
|-
|[[File:Gui tutorial custom widget.png|center|thumb|Different definition of buttons, including one of our own (right)]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag -- save ourselves some typing
function wesnoth.wml_actions.add_widget_def_demo()
local definition = {
id = "tree_view_node_custom",
description = "Fold/unfold status indicator of a tree view node (MODIFIED).",
T.resolution {
min_width = 25,
min_height = 19,
default_width = 25,
default_height = 19,
max_width = 25,
max_height = 19,
-- Unselected - note there's no tags for unselected/selected, that's simply determined by the order
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/fold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/fold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/fold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
-- Selected
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/unfold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
}
}
gui.add_widget_definition("toggle_button", "tree_view_node_custom", definition)

local dialogDefinition = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid {
T.row {
T.column {
T.toggle_button {
definition = "default"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node_custom"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end

</syntaxhighlight>

See [[GUIWidgetDefinitionWML]] for more details on widget definitions.

You can also give the whole dialog a definition, like definition = "tooltip_large". There is no gui.add_window_definition(), however a window is technically a type of widget so it may be possible to create your own window definitions (please update this if you do).

===Panels===

===Canvases===
Part of panels? Sort of?

A canvas is a surface you can draw on. A dialog has them, as does a panel, and for these canvas 1 refers to the background, while canvas 2 refers to the foreground. Other widgets may have canvases that may have other meanings, or no canvases at all. See more at [[LuaAPI/gui/widget#set_canvas]].

Here's a fun little trick. Set your dialog background to be transparent:
<syntaxhighlight lang=lua>
local function preshow(dialog)
dialog:set_canvas(1, { } )
end
</syntaxhighlight>

Or, if you want an opaque GUI background with the screen behind it blurred like what you see behind the text of a [message], you can set your window definition to "message":
<syntaxhighlight lang=lua>
...
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
definition = "message",
...
</syntaxhighlight>

{|
|Here we take our [[#Progress Bar|progress bar]], and add a text overlay.

Note: either using text on a canvas is rather limited, or I just couldn't figure it out. For example, I could not get the text size any smaller, and any attempts to do so simply resulted in very blocky text. And the spaces were necessary so that the text wasn't stretched out. I also find it surprising that the progress bar does not have this feature inherently. So it's not a great example, but it should be enough to get you started using canvases. Be sure to visit the [[LuaAPI/gui/widget#set_canvas|link]] mentioned above for more options.
|-
|[[File:Gui tutorial canvas text.png|center|thumb|A progress bar in the background, with text in the foreground]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar_with_overlay()
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.grid {
T.row {
T.column {
T.panel { id = "panel",
T.grid {
T.row {
T.column {
T.button { id = "button",
label =_ "Press me"}
},
T.column {
T.progress_bar { id = "progress" }
},
T.column {
T.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
dialog.panel:set_canvas(2, { T.text { text_alignment = "center", font_size = 48,
text_markup = true, text = " " ..
dialog.progress.percentage .. "% " } } )
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

You may notice we added a panel and placed our text on the foreground canvas(2) on it, since the progress_bar itself does not support canvases.

===Placement===

You may have noticed that all of our dialogs are centered on the screen. This is the default. You can override this and place the dialog wherever you like by setting automatic_placement = false, along with x, y, width, and height at the top level of your dialog definition (next to tooltip =, etc).

'''This part about placement needs review'''
If you prefer, you may replace x and/or y with horizontal_placement and vertical_placement, such as horizontal_placement = "left". You can even set the placement values using WFL, for example horizontal_placement = "(gamemap_width / 3)" -- see [[#Using WFL with GUI2|Using WFL with GUI2]].

==Miscellaneous==

TODO: This stuff doesn't belong in a tutorial. It's worth documenting, but not here. Better to save these here for now than keep them on my laptop.

===Progress Bar===
{|
|A progress_bar is a graphical representation of a percent. In this example, we present the user with a puzzle. They must hit the button repeatedly before they can close the GUI. A progress_bar displays their current progress toward completion.
|-
|[[File:Gui tutorial progress bar.png|center|thumb|upright=2]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.button { id = "button",
label =_ "Press me"
}
},
wml.tag.column {
wml.tag.progress_bar { id = "progress" }
},
wml.tag.column {
wml.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end

gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

===Unit Preview Pane===

{|
|A unit_preview_pane takes a unit (or a unit type), and presents a graphical representation of the unit and its more important attributes, along with tooltips for additional details, in the same way that the recall menu does. Here we see an example of a unit which has picked up some items, including a weapon, which are affecting its stats.
|-
|[[File:Gui tutorial unit preview pane.png|center|thumb]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag

function wesnoth.wml_actions.recall_from_variable(cfg)
local from_array = cfg.from or wml.error(
"[recall_from_variable]: missing required from= ")
local to_var = cfg.to or wml.error(
"[recall_from_variable]: missing required to= ")
local unit_list = wml.array_access.get(from_array) or wml.error(
string.format("[recall_from_variable]: failed to fetch wml array %s",from_array))

local listboxItem = T.grid {
T.row {
T.column {
T.label { id = "available_unit",
linked_group = "available_unit"
}
}
}
}

local listbox_id = "available_units"
local listboxDefinition = T.listbox { id = listbox_id,
T.list_definition {
T.row {
T.column {
T.toggle_panel { listboxItem }
}
}
}
}
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.linked_group { id = "available_unit", fixed_width = true },
T.grid {
T.row { -- header
T.column {
T.grid {
T.row {
T.column {
border = "bottom",
border_size = 10,
T.label {
use_markup = true,
label = ""
.. _"Select unit to recall" .. ""
}
}
}
}
}
},
T.row { -- Body
T.column {
T.grid {
T.row {
T.column {
border = "right",
border_size = 40,
listboxDefinition
},
T.column {
T.unit_preview_pane { id = "unit_preview" }
}
}
}
}
},
T.row { -- Footer
T.column {
T.grid {
T.row {
T.column {
T.spacer { width = 400 }
},
T.column {
border = "top,right",
border_size = 10,
T.button { id = "ok",
label = _"OK"
}
}
}
}
}
}
}
}

local picked = 1

local function preshow(dialog)
local listbox = dialog[listbox_id]
for i,unit in ipairs(unit_list) do
listbox[i].available_unit.label = unit.name .. "(" ..
unit.language_name .. ")"
end
local function draw_unit()
wesnoth.units.to_recall(unit_list[listbox.selected_index])
local tmp = wesnoth.units.find_on_recall{ id =
unit_list[listbox.selected_index].id }[1]
dialog.unit_preview.unit = tmp
wesnoth.units.extract(tmp)
picked = listbox.selected_index
end
draw_unit()
listbox.on_modified = draw_unit
end

gui.show_dialog(dialogDefinition,preshow)

wml.variables[to_var] = picked - 1
end

</syntaxhighlight>

This should all be pretty self evident by now. We are provided with an array of stored units (from [store_unit] in WML). We create a listbox populated with units and we use the selected_index to determine which element in the table to send to unit_preview_pane. Since our input is an array of unit data, not actual units, we use [[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] to take the definition of one from our array and place it on the recall list (turning it into an actual unit), [[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] to fetch that unit in a form that the unit_preview_panel understands, and finally [[wesnoth.units.extract|wesnoth.units.extract]] to remove the unit from the recall list when we are done with it.

And of course we subtract one from the selected_index when we return our choice to WML, since lua arrays count from 1 and WML from 0.

The unit_preview_pane will also accept a unit_type instead of a specific unit.

==Appendix==

===Explore Your Options===

We've seen a lot of options that can be set to modify the behaviour of our dialogs, some on columns, some on widgets, etc. These are in the process of being documented [[GUIWidgetInstanceWML|here]], but if you would like to go straight to the source, the data Wesnoth uses to validate your configuration can be found in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui data/schema/gui] under your install directory.

Let's look at a scroll_label, for example. A scroll_label is a widget, so we look in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/widget_instances.cfg widget_instances.cfg] and find the following. Here we can see five parameters we can provide to our scroll_label (in addition to the ones available to all widgets, like id and definition, see the entry super=... which refers you to the widget_instance in the file [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/generic.cfg data/schema/gui/generic.cfg]), along with their types and default values. For example, we could set "link_aware = true", and if we do not we can assume that link_aware will be false. While this does not explain what these parameters do, the information provided in the schema directory is often helpful nonetheless.

<syntaxhighlight lang=wml>
[tag]
name="scroll_label"
min="0"
max="infinite"
super="$generic/widget_instance"
{DEFAULT_KEY "horizontal_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "vertical_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "wrap" bool true}
{DEFAULT_KEY "text_alignment" f_h_align "left"}
{DEFAULT_KEY "link_aware" bool false}
[/tag]
</syntaxhighlight>

We see that our scrollbars are of type scrollbar_mode. It would probably help if we knew what values are available to the scrollbar_mode. In [https://github.com/wesnoth/wesnoth/tree/master/data/schema/types/gui.cfg data/schema/types/gui.cfg] we find this:

<syntaxhighlight lang=wml>
[type]
name=scrollbar_mode
value="always|never|auto|initial_auto"
[/type]
</syntaxhighlight>

The variable types found in the schema files are described at [[GUIVariable]].

Note: The keys in the schema file correspond to the attributes used when configuring your widgets. They will not always align perfectly with keys used by the Lua API. For example, the slider uses maximum_value in its configuration, and max_value when using the Lua API:

<syntaxhighlight lang=wml>
[slider]
id="my_slider"
maximum_value = 100
[/slider]
</syntaxhighlight>

<syntaxhighlight lang=lua>
dialog.my_slider.max_value = 90
</syntaxhighlight>

===Using WFL with GUI2===

If you look at the variable type descriptions at [[GUIVariable]] you may notice that many of them start with "f_" and have "or formula" in the description. This means that you can use [[Wesnoth_Formula_Language|Wesnoth Formula Language (WFL)]] formulas in these fields, with certain variables made available to you (which variables and what they mean can be challenging to ascertain, but you can generally figure it out by example).

Looking at [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/window.cfg data/schema/gui/window.cfg] we see that 'height' has type f_unsigned, which tells us that height is an unsigned integer, and that we can use a WFL formula to define it in a window_definition. In [https://github.com/wesnoth/wesnoth/tree/master/data/gui/themes/default/window/wml_message.cfg data/gui/window/wml_message.cfg] (data/gui/themes/default/window/wml_message.cfg starting around 1.19.2), we find the line '''height = "(screen_height - 30)"'''. This does exactly what it looks like, it sets the height of our window to 30 pixels less than the height of the screen.

===Useful Links===
[[GUIToolkitWML]] - Documents the keys/values available on various objects (e.g. "what attributes can I set on a column?") 
[[LuaAPI/gui|LuaAPI/gui]] - Mostly about opening windows 
[[LuaAPI/types/widget]] - Widget attributes and callbacks 
[https://wiki.wesnoth.org/Category:GUI_WML_Reference GUI_WML_Reference] 
[https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui .../data/schema/gui/*.cfg] - Lists of valid options for various GUI objects 
[https://devdocs.wesnoth.org/layout_algorithm.html Layout Algorithm] - For windows, at least

===Credits===

The basic framework that composes the initial examples was lifted from LotI. It's a great place to find well written examples, but some of it is complex enough to be a little overwhelming when getting started.

Many examples, particularly tree view and multipage, are heavily derived from the World Conquest multiplayer campaign.

Sandbox/GUI/Getting Started

2024-11-01T21:13:54Z

White haired uncle: /* Adding a little flavor */

So, it looks like I can't exclude this page/section from the search engine as I had hoped. I wanted to put this in a sandbox so that it wouldn't be published without some proper review.

==Introduction==

This guide is designed to help you get a simple Wesnoth GUI, implemented in lua, up and running while describing the basic building blocks along the way. It is written in a narrative format, where most examples build on previous examples, and therefore while not always necessary it may be desirable to read from start to finish. The reader, probably a UMC author, should have a basic knowledge of working with lua within Wesnoth.

Some would find creating a GUI in part or in full using WML simpler to follow, and those alternatives are available, for example [[LuaAPI/gui/example]], but we're using lua here. If you find WML easier to follow, you can always convert the lua tables that define the GUIs to WML using [[LuaAPI/wml#wml.tostring|wml.tostring]], for example:

<syntaxhighlight lang=lua>
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
</syntaxhighlight>

In the comments of our first GUI, below, is an example which loads a WML GUI configuration using [[LuaAPI/wml#wml.load|wml.load()]], validating against the GUI2 window schema.

In some examples, instead of defining the entire GUI at once, we'll break out some parts into separate variables. If you try to view one in WML and get an error from wml.tostring() about expecting a WML table and not a table, try passing your variable(/table) inside a table:

<syntaxhighlight lang=lua>
print(wml.tostring({listboxItem}))
gui.show_lua_console()
</syntaxhighlight>

===What is GUI2?===
Once upon a time, Wesnoth had a GUI system which is now commonly referred to as GUI1. As of 1.19, GUI1 has been almost completely replaced by GUI2. UMC authors will probably never encounter GUI1 and can simply use the terms GUI and GUI2 interchangeably, at least until GUI3 comes along.

Instead of spending a lot of time here giving an overview of what GUI2 is and what makes it great, and not so great, let's charge ahead so we can see it in action, and let readers who are interested look elsewhere(TODO: link) for a more formal definition. (TODO: is this the right approach for most readers?).

==Getting Started==

For example purposes, we'll create a directory in our campaign directory called lua containing a file called gui_tutorial.lua, and add a command in the prestart event for a scenario which will create a right-click menu option to invoke our new GUI. Of course there are other methods to invoke lua from WML, but this one will get us started. After all, we really just want to get something up on the screen ASAP, right?

===A most basic GUI===

{|
|[[File:Most basic gui.png|center|thumb|I can't believe this worked]]
|-
|In our prestart event, we create a simple menu item, which executes a single line of lua which calls the lua function most_basic_gui() which is found in gui_tutorial.lua:
|}

<syntaxhighlight lang=wml>
[set_menu_item]
id=most_basic_gui
description="Our first GUI"
[command]
[lua]
code=<<
wesnoth.require("~add-ons/<OUR_CAMPAIGN>/lua/gui_tutorial.lua").most_basic_gui()
>>
[/lua]
[/command]
[/set_menu_item]
</syntaxhighlight>

And create gui_tutorial.lua:
{| class="wikitable" style="margin:auto"
! !! The WML equivalent of dialogDefinition
|-
|
<syntaxhighlight lang=lua>
local function most_basic_gui()
local dialogDefinition = {
--click_dismiss = true, -- allow user to close dialog with click of a button
wml.tag.tooltip { id = "tooltip_large" }, -- required
wml.tag.helptip { id = "tooltip_large" }, -- required
wml.tag.grid { -- our most basic gui
wml.tag.row { -- a grid must include at least one row
wml.tag.column { -- a row needs a column
wml.tag.image { -- a column includes exactly one widget
label = "units/trolls/grunt.png"
}
}
}
}
}

local function preshow(dialog)
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
end
gui.show_dialog(dialogDefinition,preshow)

-- Or, if you want to define the gui in WML, something like:
-- local dialog_wml = wml.load("~add-ons/GUI_Tutorial/most_basic_gui.cfg",
-- true, "schema/gui_window.cfg")
-- gui.show_dialog(wml.get_child(dialog_wml, 'resolution'))
end
return { most_basic_gui = most_basic_gui}
</syntaxhighlight>
|
<syntaxhighlight lang=wml>
[tooltip]
id="tooltip_large"
[/tooltip]
[helptip]
id="tooltip_large"
[/helptip]
[grid]
[row]
[column]
[image]
label="units/trolls/grunt.png"
[/image]
[/column]
[/row]
[/grid]

</syntaxhighlight>
|}

In the above file, we have just the single function to create our GUI, followed by a return command which makes our function most_basic_gui() available to the [[LuaAPI/wesnoth#wesnoth.require|wesnoth.require()]] function as most_basic_gui().

Our function creates a table containing the definition of a "dialog", and then passes that to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]]. It should be noted that gui.show_dialog does not provide synchronization, so if your GUI makes changes to the game state, you'll need to jump through some hoops or you'll break replays and multiplayer, but that's not something we need to care about at this point, so just be aware that you may need to deal with it in the future.

Our dialog definition at this point includes three parts. The first two are a tooltip and a helptip, which are required and define how tooltips (use id = "tooltip_large" or id = "tooltip" or id = "tooltip_transparent"), and helptips (rarely used, but must be included here, and yes their definitions are "tooltip" not "helptip") will look (as we will see later, this really should be definition = "tooltip", but in this case it's id = "tooltip"). The third part is a grid, which is basically a table, like in HTML or MySQL, with rows and columns. A grid always contains at least one row. A row contains at least one column (note that a column does NOT span rows, it is completely contained within a row). Inside a column is exactly one item, a cell which contains a [[GUIWidgetDefinitionWML|widget]], in this case we'll use an image (later we'll see what else we can put in a cell). Note that we don't actually define a cell in our code, it's just a term used to refer to the contents of a column.

The preshow function is optional. If included in the call to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]], it is run before the GUI is displayed. In this case, we include it to display the dialog we created with lua in WML format. Near the end, in comments, we show how you would call [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] if you chose to define your dialog using WML. Note that what is shown here is the WML equivalent of our lua dialogDefinition, and not the complete WML you would need to use if you were to configure your GUI layout in WML.

Note: if you should try out the above, you'll have to hit escape or enter to close the GUI. Uncomment the "click_dismiss" line, and the user will be able to close the GUI with a mouse click.

===Adding a little flavor===

{|
|You may have noticed our GUI is missing a header and a way to close it when we're done admiring our work. Here we add a new first row to our grid, while demonstrating a couple formatting options: a border to put some distance between our grid cell and its neighbor, and the "use_markup = true" option to enable Pango support in our text.

Our third row adds an OK button at the bottom. You can associate actions with buttons to do all kinds of things, but here we just exploit the default behaviour to close the GUI.

Of course, we'll also have to modify our return to support the new function, and update our menu item(s) accordingly.
|-
|[[File:Most basic gui2.png|center|thumb|Adding header and a footer]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui2()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
wml.parse(wml.tostring({{"resolution", dialogDefinition}}), "schema/gui_window.cfg") -- schema validation errors will go to log
gui.show_dialog(dialogDefinition)
end
return { most_basic_gui = most_basic_gui, most_basic_gui2 = most_basic_gui2 }
</syntaxhighlight>

Note that in this example, just before we invoke gui.show_dialog(), we use [[LuaAPI/wml#wml.parse|wml.parse()]] to validate our input against the GUI2 window schema. If we've misspelled something, or placed a key in the wrong place (like placing a border in a widget instead of a column), etc, an error such as '''error validation: Invalid key 'garbage=' in tag [resolution]''' will be written to the wesnoth log.

===And a bit more===
{|

|And now a minor, but important change. We want to add a new text field next to the image in the body of our GUI. Obviously, we want to add a new column, but this is more difficult than when we added new rows in the previous example. The problem is that all rows (at a given level) in a grid must contain the same number of columns. We can't have two columns in the row that constitutes the body of our GUI, but only one in the header and one in the footer. To solve this problem, we replace our image widget with a new grid, which can use as many columns as we like (as long as they are the same within each row of our new grid). This new grid contains a row with two columns, but that is okay because the new grid itself is placed in a single column, which matches our single column header and footer (ok button), keeping the rows balanced.
|-
|[[File:Most basic gui3.png|center|thumb|Rows with different numbers of columns]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui3()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column { -- This is the only column in this row,
-- to match the number of columns in
-- the rows of our header and footer
wml.tag.grid { -- A new grid, so we can use a different
-- number of columns
wml.tag.row {
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
},
wml.tag.column {
wml.tag.label {
label = "A troll"
}
}
}
}
}
},
wml.tag.row { -- A footer
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = "Ok"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

While we see here just the simplest of examples, you can create many levels of grids inside grids, rows with multiple columns some of which containing grids, etc, to build complicated dialogs to your liking.

==Containers==

===Stacked Widget===

TODO

===Listbox===
{|
| Now we'd like to add some more monsters. Obviously, we could just add more rows, but what if we won't know until runtime how many and which ones? We could break up the definition of our dialog and add new rows dynamically, it's just a table after all, but fortunately we have a widget which handles this for us, a listbox. A listbox is kind of like an array, a collection of similar objects where the number of items can vary. We will tell the GUI where we want the box, and what each entry in the box will look like, and then at runtime we can add entries to the box.

Note that listbox items are added from top to bottom. Another container, the horizontal_listbox, works just like a listbox except the items are added from left to right. With a grid listbox, items are added horizontally with the list wrapping to a new line as necessary.
|-
| [[File:Gui with listbox.png|center|thumb|Listbox with three items. Each item is an image and a label. The third item has been selected.]]

<syntaxhighlight lang=lua>
local function gui_with_listbox()
local monsters = {
{ image = "units/trolls/grunt.png",
string = "A troll" },
{ image = "units/monsters/cuttlefish.png",
string = "A cuttlefish" },
{ image = "units/monsters/yeti.png",
string = "A yeti" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
}

local listboxDefinition = wml.tag.listbox { id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
listboxDefinition
}
},
wml.tag.row {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_label.label = monster.string
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We begin by creating a simple table which represents the data which will be presented in our listbox. In most cases, we probably wouldn't create that monster table here, but we need it for our example.

The variable listbox_id gives us an identifier for our listbox so we can reference it when we need to. We don't really need to use a variable here, it's just convenient.

We define the structure for the elements in our listbox, stored in listboxItem. Note that we've replaced the actual data with identifiers (e.g. 'units/trolls/grunt.png' becomes 'id = "monster_image"), since each element may have different data.

We define the listbox itself, specifying the identifier, and the definition of our listbox element (which looks a lot like a grid). The cell inside the column contains a variable which is just the listbox element definition we created above; it's not necessary to do this, we could have used one big table, but it's easier to read this way (IMO).

We replace the hardcoded data in our GUI body with our new listbox definition, again using a variable to make it easier to read.

We create a function, often called preshow(), which will be called for us as part of the drawing the GUI (see the new optional argument in [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] -- there's also an optional postshow(), but we don't need it here). This is where we pull the data from our example table into the listbox. We create a listbox variable associated with the listbox, identified by the listbox_id we assigned earlier, inside the dialog which gui.show_dialog() passes to preshow(). Then we iterate through our data table, using each entry from that table to populate a listbox item.

Let's look at that last action a little more closely using an example.

<syntaxhighlight lang=lua>
listbox[i].monster_image.label = monster.image
</syntaxhighlight>

Which we can read as "In listbox element i of our listbox, for the image with identifier monster_image which we defined in our listboxItem, use the data from the corresponding index i in our example data table" (you don't see the index i for the monsters table here, but remember we're iterating using ipairs, we could have just as easily used listbox[i].monster_image.label = monsters[i].image). If you were to step through all of the variable substitutions, you'd see that for i=1, our dialogDefinition is basically the same thing as it was in the earlier examples, just supplied from a table instead of hardcoded (note that you can hardcode entries in a listbox in your dialog definition using the [list_data] tag, aka wml.tag.list_data, which we do not demonstrate here).

You will probably notice that our data does not line up nicely in the GUI. We will fix that later. We'll also demonstrate how the user can select an item in a listbox, and how you can identify which item that was using the selected_index variable of the listbox.

===Tree View===
====Simple Tree View====
{|
| You may have noticed that clicking on a listbox item in our listbox caused it to be highlighted with a box around the contents. This is because the items in a listbox are selectable. This will be useful when we want to add actions, but it looks a bit odd if we just want to present a list of data.

Also, most of the data had to be formatted the same for each item in the listbox. We could, perhaps, include custom markup in our labels, but the actual layout, like the number of columns per row, had to be the same for every item.

Another way to present a list of data is the tree view. Since a tree view supports multiple data types, we may need to create multiple definitions for the elements in our list. These are known as nodes. It will also be necessary to explicitly define which node to use for each element when we populate our tree view.
|-
| [[File:Basic tree view.png|center|thumb|Tree_views can hold multiple data types (only trolls have names here)]]
|}
<syntaxhighlight lang=lua line>
local function basic_tree_view()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", type = "Seamonsters" },
{ image = "units/monsters/yeti.png", label = "A yeti",
type = "Coolers" }
}

local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "trolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name",
linked_group = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
},
wml.tag.node {
id = "nottrolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "monster_name",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_image",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_label",
fixed_width = true
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_tv:add_item_of_type("trolls_node")
dialog.monsters_tv[i].monster_name.label = monster.name -- only trolls have a name
else
dialog.monsters_tv:add_item_of_type("nottrolls_node")
end
-- All of our monsters have an image and a label
dialog.monsters_tv[i].monster_image.label = monster.image
dialog.monsters_tv[i].monster_label.label = monster.label
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We have expanded our list of monsters to include three types of trolls. We have also given each troll a name. This is of course a rather simplistic example, we could have simply given each monster that is not a troll an empty name, but it as presented here our approach serves the purpose of demonstrating how we deal with multiple data types. Our new tree view contains a node for each type of data we will present. In preshow, we explicitly define each element in our list using add_item_of_type(), and populate the item accordingly. [Note: in our listbox example, we could have used add_item() to add items to the listbox, but chose not to since that section was already introducing a number of new concepts. But here, since we have multiple types of items we need to be able to specify the type of the item when we add one, hence we need to use add_item_of_type()].

You may also note the addition of a few linked_group lines. We'll cover linked groups in more detail later, but as used here they instruct the GUI that each column using the same node type needs to be aligned with the others. For example, all of our trolls line up nicely.

====Building a Tree====
{|
| colspan="2" |At this point, one may wonder about the name "tree view", since what he have seen doesn't look much like a tree. To make a tree-like structure, we'll demonstrate adding children to nodes. At the top level our (upside-down) tree will have two nodes, one for trolls and one for everything else. A toggle_button (a type of button which changes states when you push it) will allow us to expand the trolls node to expose its children, which are themselves nodes, though they only contain a label at this point.
|-
| [[File:Basic tree view2a.png|center|thumb|Tree_view with Trolls folded]] || [[File:Basic tree view2b.png|center|thumb|Tree_view with Trolls unfolded]]
|}
<syntaxhighlight lang=lua line>
local function building_a_tree()
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
}
},
wml.tag.column {
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Show me the " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
-- You can refer to an object by its position

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[1].race_label.label = "Trolls"
-- dialog.monsters_tv[1].race_button.on_modified =
-- function()dialog.monsters_tv[1].unfolded =
-- dialog.monsters_tv[1].race_button.selected end

-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][1].monster_type.label = "Whelp"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][2].monster_type.label = "Shaman"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][3].monster_type.label = "Troll"

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[2].race_label.label = "Other scary things"
-- dialog.monsters_tv[2].race_button.visible = "hidden"

-- ... or you can refer to that object using the return value
-- from add_item_of_type
local troll_node = dialog.monsters_tv:add_item_of_type("race_node")
troll_node.race_label.label = "Trolls"
troll_node.race_button.on_modified =
function()
troll_node.unfolded = troll_node.race_button.selected
end
local item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Whelp"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Shaman"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Troll"

local not_troll_node =
dialog.monsters_tv:add_item_of_type("race_node")
not_troll_node.race_label.label = "Other scary things"
not_troll_node.race_button.visible = "hidden"

end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We define two nodes in our tree, a race_node for the top level, and a details_node for the children of a race_node. The rest of the interesting bits are in preshow().

We demonstrate two different ways of creating and accessing items, the first (commented out) just using the order in which they are created, while in the second we capture the result of add_item_of_type() in a variable we can use to refer to the newly defined object. The first method is shown primarily to demonstrate the structure of the resulting objects. The second method is perhaps easier to follow, and is almost necessary when you start doing things like dynamically deleting nodes, so it is in most cases a better practice (of course, you probably won't want to use the same variable for each node like we did, and perhaps not one local to the preview function).

We add a node, label it "Trolls", and add a callback to the button such that the children of the node will be visible (the node is "unfolded", a boolean value which defaults to false) when the button is checked (selected == true). Then we add three "details_node" nodes as children of this node.

Our second node, "Other scary things" will remain empty for now, so we'll set the visible attribute on its button to "hidden" (which is like false, but with hidden the widget still takes up space).

{|
| This example is rather ugly, both in the hardwired code and the appearance of the resulting GUI, but it addresses a couple important aspects of how tree views work and how we might use them. Let's clean it up a bit. We'll add an indentation_step_size to the tree view, along with a spacer and [[#Alignment|horizontal_alignment]] to our details node, to make the labels line up nicely, and change the button [[#Definitions|definition]] to replace the checkbox with something that looks like it belongs there. We will look at methods for handling layout in more depth [[#Appearance|later]].
|-
| [[File:Basic tree view2c.png|center|thumb|Our tree_view with proper alignment]]

<syntaxhighlight lang=lua>
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
indentation_step_size = 20,
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
definition = "tree_view_node"
}
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.spacer { width = 40 }
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}

</syntaxhighlight>

===Multi_page===
====Simple Multi_page====
{|
|-
Like a tree_view, a multi_page is a heterogeneous container which is dynamically populated, however, while a multi_page contains multiple elements (pages), only one page is displayed at any one time. Its purpose is perhaps best described by a couple of examples.
|-
[[File:Basic multipage.png|center|thumb|Multi_page showing active page]]
|}
<syntaxhighlight lang=lua>
local function basic_multipage()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll",
name = _"Bob", type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp",
name = "Junior", type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman",
name = _"Alice", type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish",
type = "Seamonsters" },
{ image = "units/monsters/yeti.png",
label = "A yeti",
type = "Coolers" }
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
multi_page
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}

local function preshow(dialog) -- Prepare the GUI before display
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_label.label = monster.label
end
--dialog.monsters_mp.selected_index = 5
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

As you can see, the code for our basic multi_page GUI looks a lot like our basic tree_view GUI. The difference is what is displayed. While both the tree_view and the multi_page containers contain five items, with the multi_page, only the first one is displayed. More specifically, only the page associated with the selected_index attribute of the multi_page object, which defaults to 1, is displayed. If we were to uncomment the last line in preshow(), we would still see only one item, but it would be the fifth one we allocated. It's nice to know all our pages are in there somewhere, but this example is pretty useless. What we need is a way to select which page we want to see from within our GUI.

====A More Useful Multi_page====

{|
| colspan="2" | To demonstrate the usefulness of a multi_page, and highlight its difference from a tree_view, we'll add a listbox to allow us to select the page to view. We'll also need to add a little action to our GUI.
|-
| style="align:centered" |[[File:More useful multipage.png|center|thumb|User selected Troll]] || [[File:More useful multipage2.png|center|thumb|User selected Cuttlefish]]
|}

<syntaxhighlight lang=lua>
local function more_useful_multi_page()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
race = "Trolls", tip = "Your uncle" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
race = "Trolls", tip = "Your nephew" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
race = "Trolls", tip = "Your auntie" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", race = "Seamonsters",
tip = "Not a fish" },
{ image = "units/monsters/yeti.png",
label = "A yeti", race = "Coolers",
tip = "ROAR!" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
}
}
}

local listboxDefinition = wml.tag.listbox {
id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
},
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
listboxDefinition
},
wml.tag.column {
wml.tag.spacer {
width = 30
}
},
wml.tag.column {
multi_page
},
}
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_image.tooltip = monster.tip
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_image.tooltip = monster.tip
dialog.monsters_mp[i].monster_label.label = monster.label
end
local function switch_page()
dialog.monsters_mp.selected_index = listbox.selected_index
end
listbox.on_modified = switch_page
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

Most of this should look pretty familiar. We've simply taken the previous example and added a second column to our GUI using code from an earlier example to add a listbox. In addition, we altered the page layout slightly, and added a spacer column in the dialog definition to approve the appearance.

The interesting stuff is in preshow(). Again we've merged in some listbox code from an earlier example, but we've also created a new local function switch_page(), which simply sets the selected_index attribute of our multi_page to the same as that of our listbox, and then we've configured the listbox.on_modified callback to call switch_page(). Now when the user selects an item in the listbox (updating listbox.selected_index and triggering listbox.on_modified), dialog.monsters_mp.selected_index is updated accordingly and therefore the visible page changes to the one associated with the selected unit.

Also note in preshow() we've added a new child to our monster_image identifier for both the listbox and the multi_page, a tooltip. When the user hovers the mouse over the image of one of our monsters, they'll see a popup message which we've added to our monster table. Try changing '''wml.tag.tooltip { id = "tooltip_large" }''' to '''wml.tag.tooltip { id = "tooltip }''' in the dialogDefinition to see a different tooltip style.

==Actions Have Consequences==

So far, our GUIs have only displayed some information on the screen, but at some point we're probably going to want to use a GUI to get input from the user. In this section we will look at return values that can be assigned to a widget based upon its state, and callbacks, which are functions invoked when something happens with a widget. As we will see, a button is a good example, as it can return a value or take an action, or both, when pressed. Earlier we saw how the selected_index attribute of some widgets, such as the listbox, can also be used as a sort of return value.

===Buttons===
{|
| colspan=2 | In this example, we'll create a couple buttons which provide the user a choice, use a handy confirmation popup to confirm that choice, and demonstrate how we get the results back where we can put them to use.
|-
| [[File:Basic return value.png|center|thumb|There can be only one]] || [[File:Basic return value_confirm.png|center|thumb|The user selected Alice, let's confirm this critical choice]]
|}

<syntaxhighlight lang=lua>
local function basic_return_value()

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "leader_lg",
fixed_height = true,
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" ..
_"Which unit shall lead your army?" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Alice" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/elves-wood/sylph.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 1
}
}
},
}
},
wml.tag.column {
wml.tag.spacer { width = 20 }
},
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Bob" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/human-loyalists/marshal.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 2
}
}
}
}
}
}
}
}
}
}
}
local user_chose = gui.show_dialog(dialogDefinition)
local leader
if user_chose == -1 then -- User closed the dialog by hitting the Enter key
leader = nil
end
if user_chose == -2 then -- User closed the dialog by hitting the Escape key
leader = nil
end

if user_chose == 1 then
leader = "Alice"
end
if user_chose == 2 then
leader = "Bob"
end

local confirmed_leader_choice

if leader ~= nil then
local query = _"You want " .. leader .. _" as your leader?"
confirmed_leader_choice = gui.confirm(query)
end

if confirmed_leader_choice then
wesnoth.message("Great!")
else
wesnoth.message("Fine, lead them yourself!")
end
end
</syntaxhighlight>

Here we've added a couple buttons, and assigned each of them a return value. When the user selects one of these buttons, the GUI is closed and the value of return_value is returned from gui.show_dialog(). We then use [https://wiki.wesnoth.org/LuaAPI/gui#gui.show_prompt gui.confirm()] which provides a very simple Yes/No popup and returns true or false, respectively. Other useful functions can be found on that page which provide handy alternatives to creating your own GUI for other simple user inputs.

The use of return_value is rather limited, as it only returns integers and can't be used with containers like listboxes. In more complex cases we'll need to turn to callback functions which are invoked when something happens to a widget, like clicking a button or a widget's value changing. Earlier, we saw an example of [[LuaAPI/types/widget#on_modified|widget.on_modified()]]. More examples of callbacks can be found at [[LuaAPI/types/widget#on_modified|that link]].

===Slider and Textbox===
{|
| Here we see a couple methods of getting more dynamic input from the user, a slider and a textbox presented in one silly example.
|-
| [[File:Slider and textbox.png|center|thumb|Two ways of getting input from the user]]
|}

<syntaxhighlight lang=lua>
function slider_and_textbox()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = _"How much gold will you pay for this old rusty sword?"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.slider {
id = "gold_sl",
minimum_value = 0,
maximum_value =
wesnoth.sides[wesnoth.current.side].gold,
value = math.floor(
wesnoth.sides[wesnoth.current.side].gold/2)
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.text_box {
id = "gold_tb",
--hint_text = _ "Enter gold here",
--hint_image = "images/gold_pile.png",
label = tostring(math.floor(
wesnoth.sides[wesnoth.current.side].gold/2))
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
local function show_input()
wesnoth.interface.add_chat_message(_"You chose " ..
dialog.gold_sl.value .. _" with the slider")
wesnoth.interface.add_chat_message(_"You entered " ..
tostring(dialog.gold_tb.text) .. _" in the text_box")
end
-- this is a button, so we use on_button_click, not on_left_click
dialog.ok.on_button_click = show_input

dialog.gold_sl.on_modified = function()
dialog.gold_tb.text = tostring(dialog.gold_sl.value)
end
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We create a slider, with a range from 0 to the amount of gold possessed by the current side and an initial value in the middle, and a text box with the same initial value. We assign a function to our OK button which simply reports on the values provided by the user. For no reason whatsoever, we add a callback such that when the user adjusts the slider the value in the textbox is update to match the slider.

Note that the textbox returns text, even though it looks like we're expecting the user to input a natural number. Remember to validate those inputs.

You can use text_hint to place a caption in the box that will help the user understand what to enter in the box, and possibly an image as well. For example, in the search box in the recall menu uses '''hint_text = _ "Search", hint_image = "icons/action/zoomdefault_25.png~FL(horiz)"'''. Of course, you can't have a hint and a label in the same text_box at the same time, so in our example we've only included them as comments.

There is also a widget called a spinner, which is kind of like the combination of a text_box and a slider. As of the release of 1.18, it appears to be unfinished so the strange syntax needed to make it work is probably not the best thing to document, and we will omit it for now.

==Appearance==

'''This section needs help'''

===Borders===

Borders allow you to force unused space around a column, for example so that your widgets don't runtogether. You can specify the border to be one or more of top, bottom, left, right, or all. The border_size sets the amount of padding, in pixels.

<syntaxhighlight lang=lua>
wml.tag.column{
border = "left, right"
border_size = 25
}
</syntaxhighlight>

===Alignment===
{|
| colspan=2 |By default, the GUI will usually center widgets in their cells, which is not always what we want. In this example, we use horizontal_alignment to move widgets around a little.

In more complex cases, it may be useful to add [[GUIWidgetDefinitionWML#Spacer|spacers]] to help force alignment, or use linked_groups to force consistent alignment for objects within a grid.
|-
| [[File:Gui tutorial alignment without.png|center|thumb|Default alignment]] ||[[File:Gui tutorial alignment with.png|center|thumb|Showing off some alignment options]]
|}
<syntaxhighlight lang=lua>
local function basic_alignment()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = "Ralph"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "right",
wml.tag.label {
label = "Sam"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/troll-hero-attack-se-4.png" -- 122x102
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "left",
wml.tag.label {
label = "Jr"
}
},
wml.tag.column {
horizontal_alignment = "right",
wml.tag.image {
label = "units/trolls/whelp.png" -- 72x72
}
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

The screenshots show the output of this example with and without the horizontal_alignment lines included above.

A label allows you to set the text_alignment field (e.g. text_alignment = "left"). Note, however, this only aligns the text within the label. The label itself will probably be centered in the column, giving the false appearance that your text alignment is not working.

===Growth===

To keep your dialog nicely balanced, the GUI2 engine may need to grow rows and/or columns. You can control which columns, for example, grow and which do not, by setting some with grow_factor = 1, and others with grow_factor = 0 (do not grow). While grow factors of 0 and 1 are the most common, you can use other values to adjust the relative growth if you really need to, see [[GUILayout]] for the gory details.

It it sometimes useful to include a column with a [spacer] and a grow_factor (often the only column with grow_factor != 0) whose sole purpose is to keep your GUI aligned nicely as the layout engine does its evil.

To force a column to stretch to fit available space, use horizontal_grow = true. Note that horizontal_grow is not compatible with horizontal_alignment. There is also a vertical_grow parameter.

If you need to see every little detail about the layout process, start wesnoth with --log-debug=gui/layout. Good luck with that.

===Definitions===
Many widgets can be configured to have to a different appearance, for example in our tree_view example we changed the definition of a toggle_button from the default of a checkbox by setting definition = "tree_view_node". This option was found by looking at the id of a toggle_button_definition in .../data/gui/widget/toggle_button_tree_view_node.cfg:

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib
###
### Definition of a toggle button to be used in a tree view as node fold/unfold indicator
###
[toggle_button_definition]
id = "tree_view_node" # <--- we can use 'definition = "tree_view_node"' in a [toggle_button] to select this definition
description = "Fold/unfold status indicator of a tree view node."
</syntaxhighlight>

{|
|There are many other definitions for buttons and other widget types in that directory. It would be nice to have a list (linked here), but for now you'll just have to look around.

We can even create our own custom definitions using [[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition()]]. In this example, we copy from .../data/gui/widget/toggle_button_tree_view_node.cfg with a slight change so that our button turns red ( '''~BLEND(255,0,0,1)''' ) when focused.

In this example, we will use wesnoth.wml_actions to create the WML tag [add_widget_def_demo].

Note the first line, a common convention for creating an alias for wml.tag.
|-
|[[File:Gui tutorial custom widget.png|center|thumb|Different definition of buttons, including one of our own (right)]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag -- save ourselves some typing
function wesnoth.wml_actions.add_widget_def_demo()
local definition = {
id = "tree_view_node_custom",
description = "Fold/unfold status indicator of a tree view node (MODIFIED).",
T.resolution {
min_width = 25,
min_height = 19,
default_width = 25,
default_height = 19,
max_width = 25,
max_height = 19,
-- Unselected - note there's no tags for unselected/selected, that's simply determined by the order
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/fold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/fold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/fold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
-- Selected
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/unfold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
}
}
gui.add_widget_definition("toggle_button", "tree_view_node_custom", definition)

local dialogDefinition = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid {
T.row {
T.column {
T.toggle_button {
definition = "default"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node_custom"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end

</syntaxhighlight>

See [[GUIWidgetDefinitionWML]] for more details on widget definitions.

You can also give the whole dialog a definition, like definition = "tooltip_large". There is no gui.add_window_definition(), however a window is technically a type of widget so it may be possible to create your own window definitions (please update this if you do).

===Panels===

===Canvases===
Part of panels? Sort of?

A canvas is a surface you can draw on. A dialog has them, as does a panel, and for these canvas 1 refers to the background, while canvas 2 refers to the foreground. Other widgets may have canvases that may have other meanings, or no canvases at all. See more at [[LuaAPI/gui/widget#set_canvas]].

Here's a fun little trick. Set your dialog background to be transparent:
<syntaxhighlight lang=lua>
local function preshow(dialog)
dialog:set_canvas(1, { } )
end
</syntaxhighlight>

Or, if you want an opaque GUI background with the screen behind it blurred like what you see behind the text of a [message], you can set your window definition to "message":
<syntaxhighlight lang=lua>
...
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
definition = "message",
...
</syntaxhighlight>

{|
|Here we take our [[#Progress Bar|progress bar]], and add a text overlay.

Note: either using text on a canvas is rather limited, or I just couldn't figure it out. For example, I could not get the text size any smaller, and any attempts to do so simply resulted in very blocky text. And the spaces were necessary so that the text wasn't stretched out. I also find it surprising that the progress bar does not have this feature inherently. So it's not a great example, but it should be enough to get you started using canvases. Be sure to visit the [[LuaAPI/gui/widget#set_canvas|link]] mentioned above for more options.
|-
|[[File:Gui tutorial canvas text.png|center|thumb|A progress bar in the background, with text in the foreground]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar_with_overlay()
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.grid {
T.row {
T.column {
T.panel { id = "panel",
T.grid {
T.row {
T.column {
T.button { id = "button",
label =_ "Press me"}
},
T.column {
T.progress_bar { id = "progress" }
},
T.column {
T.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
dialog.panel:set_canvas(2, { T.text { text_alignment = "center", font_size = 48,
text_markup = true, text = " " ..
dialog.progress.percentage .. "% " } } )
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

You may notice we added a panel and placed our text on the foreground canvas(2) on it, since the progress_bar itself does not support canvases.

===Placement===

You may have noticed that all of our dialogs are centered on the screen. This is the default. You can override this and place the dialog wherever you like by setting automatic_placement = false, along with x, y, width, and height at the top level of your dialog definition (next to tooltip =, etc).

'''This part about placement needs review'''
If you prefer, you may replace x and/or y with horizontal_placement and vertical_placement, such as horizontal_placement = "left". You can even set the placement values using WFL, for example horizontal_placement = "(gamemap_width / 3)" -- see [[#Using WFL with GUI2|Using WFL with GUI2]].

==Miscellaneous==

TODO: This stuff doesn't belong in a tutorial. It's worth documenting, but not here. Better to save these here for now than keep them on my laptop.

===Progress Bar===
{|
|A progress_bar is a graphical representation of a percent. In this example, we present the user with a puzzle. They must hit the button repeatedly before they can close the GUI. A progress_bar displays their current progress toward completion.
|-
|[[File:Gui tutorial progress bar.png|center|thumb|upright=2]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.button { id = "button",
label =_ "Press me"
}
},
wml.tag.column {
wml.tag.progress_bar { id = "progress" }
},
wml.tag.column {
wml.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end

gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

===Unit Preview Pane===

{|
|A unit_preview_pane takes a unit (or a unit type), and presents a graphical representation of the unit and its more important attributes, along with tooltips for additional details, in the same way that the recall menu does. Here we see an example of a unit which has picked up some items, including a weapon, which are affecting its stats.
|-
|[[File:Gui tutorial unit preview pane.png|center|thumb]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag

function wesnoth.wml_actions.recall_from_variable(cfg)
local from_array = cfg.from or wml.error(
"[recall_from_variable]: missing required from= ")
local to_var = cfg.to or wml.error(
"[recall_from_variable]: missing required to= ")
local unit_list = wml.array_access.get(from_array) or wml.error(
string.format("[recall_from_variable]: failed to fetch wml array %s",from_array))

local listboxItem = T.grid {
T.row {
T.column {
T.label { id = "available_unit",
linked_group = "available_unit"
}
}
}
}

local listbox_id = "available_units"
local listboxDefinition = T.listbox { id = listbox_id,
T.list_definition {
T.row {
T.column {
T.toggle_panel { listboxItem }
}
}
}
}
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.linked_group { id = "available_unit", fixed_width = true },
T.grid {
T.row { -- header
T.column {
T.grid {
T.row {
T.column {
border = "bottom",
border_size = 10,
T.label {
use_markup = true,
label = ""
.. _"Select unit to recall" .. ""
}
}
}
}
}
},
T.row { -- Body
T.column {
T.grid {
T.row {
T.column {
border = "right",
border_size = 40,
listboxDefinition
},
T.column {
T.unit_preview_pane { id = "unit_preview" }
}
}
}
}
},
T.row { -- Footer
T.column {
T.grid {
T.row {
T.column {
T.spacer { width = 400 }
},
T.column {
border = "top,right",
border_size = 10,
T.button { id = "ok",
label = _"OK"
}
}
}
}
}
}
}
}

local picked = 1

local function preshow(dialog)
local listbox = dialog[listbox_id]
for i,unit in ipairs(unit_list) do
listbox[i].available_unit.label = unit.name .. "(" ..
unit.language_name .. ")"
end
local function draw_unit()
wesnoth.units.to_recall(unit_list[listbox.selected_index])
local tmp = wesnoth.units.find_on_recall{ id =
unit_list[listbox.selected_index].id }[1]
dialog.unit_preview.unit = tmp
wesnoth.units.extract(tmp)
picked = listbox.selected_index
end
draw_unit()
listbox.on_modified = draw_unit
end

gui.show_dialog(dialogDefinition,preshow)

wml.variables[to_var] = picked - 1
end

</syntaxhighlight>

This should all be pretty self evident by now. We are provided with an array of stored units (from [store_unit] in WML). We create a listbox populated with units and we use the selected_index to determine which element in the table to send to unit_preview_pane. Since our input is an array of unit data, not actual units, we use [[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] to take the definition of one from our array and place it on the recall list (turning it into an actual unit), [[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] to fetch that unit in a form that the unit_preview_panel understands, and finally [[wesnoth.units.extract|wesnoth.units.extract]] to remove the unit from the recall list when we are done with it.

And of course we subtract one from the selected_index when we return our choice to WML, since lua arrays count from 1 and WML from 0.

The unit_preview_pane will also accept a unit_type instead of a specific unit.

==Appendix==

===Explore Your Options===

We've seen a lot of options that can be set to modify the behaviour of our dialogs, some on columns, some on widgets, etc. These are in the process of being documented [[GUIWidgetInstanceWML|here]], but if you would like to go straight to the source, the data Wesnoth uses to validate your configuration can be found in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui data/schema/gui] under your install directory.

Let's look at a scroll_label, for example. A scroll_label is a widget, so we look in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/widget_instances.cfg widget_instances.cfg] and find the following. Here we can see five parameters we can provide to our scroll_label (in addition to the ones available to all widgets, like id and definition, see the entry super=... which refers you to the widget_instance in the file [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/generic.cfg data/schema/gui/generic.cfg]), along with their types and default values. For example, we could set "link_aware = true", and if we do not we can assume that link_aware will be false. While this does not explain what these parameters do, the information provided in the schema directory is often helpful nonetheless.

<syntaxhighlight lang=wml>
[tag]
name="scroll_label"
min="0"
max="infinite"
super="$generic/widget_instance"
{DEFAULT_KEY "horizontal_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "vertical_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "wrap" bool true}
{DEFAULT_KEY "text_alignment" f_h_align "left"}
{DEFAULT_KEY "link_aware" bool false}
[/tag]
</syntaxhighlight>

We see that our scrollbars are of type scrollbar_mode. It would probably help if we knew what values are available to the scrollbar_mode. In [https://github.com/wesnoth/wesnoth/tree/master/data/schema/types/gui.cfg data/schema/types/gui.cfg] we find this:

<syntaxhighlight lang=wml>
[type]
name=scrollbar_mode
value="always|never|auto|initial_auto"
[/type]
</syntaxhighlight>

The variable types found in the schema files are described at [[GUIVariable]].

Note: The keys in the schema file correspond to the attributes used when configuring your widgets. They will not always align perfectly with keys used by the Lua API. For example, the slider uses maximum_value in its configuration, and max_value when using the Lua API:

<syntaxhighlight lang=wml>
[slider]
id="my_slider"
maximum_value = 100
[/slider]
</syntaxhighlight>

<syntaxhighlight lang=lua>
dialog.my_slider.max_value = 90
</syntaxhighlight>

===Using WFL with GUI2===

If you look at the variable type descriptions at [[GUIVariable]] you may notice that many of them start with "f_" and have "or formula" in the description. This means that you can use [[Wesnoth_Formula_Language|Wesnoth Formula Language (WFL)]] formulas in these fields, with certain variables made available to you (which variables and what they mean can be challenging to ascertain, but you can generally figure it out by example).

Looking at [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/window.cfg data/schema/gui/window.cfg] we see that 'height' has type f_unsigned, which tells us that height is an unsigned integer, and that we can use a WFL formula to define it in a window_definition. In [https://github.com/wesnoth/wesnoth/tree/master/data/gui/themes/default/window/wml_message.cfg data/gui/window/wml_message.cfg] (data/gui/themes/default/window/wml_message.cfg starting around 1.19.2), we find the line '''height = "(screen_height - 30)"'''. This does exactly what it looks like, it sets the height of our window to 30 pixels less than the height of the screen.

===Useful Links===
[[GUIToolkitWML]] - Documents the keys/values available on various objects (e.g. "what attributes can I set on a column?") 
[[LuaAPI/gui|LuaAPI/gui]] - Mostly about opening windows 
[[LuaAPI/types/widget]] - Widget attributes and callbacks 
[https://wiki.wesnoth.org/Category:GUI_WML_Reference GUI_WML_Reference] 
[https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui .../data/schema/gui/*.cfg] - Lists of valid options for various GUI objects 
[https://devdocs.wesnoth.org/layout_algorithm.html Layout Algorithm] - For windows, at least

===Credits===

The basic framework that composes the initial examples was lifted from LotI. It's a great place to find well written examples, but some of it is complex enough to be a little overwhelming when getting started.

Many examples, particularly tree view and multipage, are heavily derived from the World Conquest multiplayer campaign.

Sandbox/GUI/Getting Started

2024-11-01T20:53:55Z

White haired uncle: /* Adding a little flavor */

So, it looks like I can't exclude this page/section from the search engine as I had hoped. I wanted to put this in a sandbox so that it wouldn't be published without some proper review.

==Introduction==

This guide is designed to help you get a simple Wesnoth GUI, implemented in lua, up and running while describing the basic building blocks along the way. It is written in a narrative format, where most examples build on previous examples, and therefore while not always necessary it may be desirable to read from start to finish. The reader, probably a UMC author, should have a basic knowledge of working with lua within Wesnoth.

Some would find creating a GUI in part or in full using WML simpler to follow, and those alternatives are available, for example [[LuaAPI/gui/example]], but we're using lua here. If you find WML easier to follow, you can always convert the lua tables that define the GUIs to WML using [[LuaAPI/wml#wml.tostring|wml.tostring]], for example:

<syntaxhighlight lang=lua>
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
</syntaxhighlight>

In the comments of our first GUI, below, is an example which loads a WML GUI configuration using [[LuaAPI/wml#wml.load|wml.load()]], validating against the GUI2 window schema.

In some examples, instead of defining the entire GUI at once, we'll break out some parts into separate variables. If you try to view one in WML and get an error from wml.tostring() about expecting a WML table and not a table, try passing your variable(/table) inside a table:

<syntaxhighlight lang=lua>
print(wml.tostring({listboxItem}))
gui.show_lua_console()
</syntaxhighlight>

===What is GUI2?===
Once upon a time, Wesnoth had a GUI system which is now commonly referred to as GUI1. As of 1.19, GUI1 has been almost completely replaced by GUI2. UMC authors will probably never encounter GUI1 and can simply use the terms GUI and GUI2 interchangeably, at least until GUI3 comes along.

Instead of spending a lot of time here giving an overview of what GUI2 is and what makes it great, and not so great, let's charge ahead so we can see it in action, and let readers who are interested look elsewhere(TODO: link) for a more formal definition. (TODO: is this the right approach for most readers?).

==Getting Started==

For example purposes, we'll create a directory in our campaign directory called lua containing a file called gui_tutorial.lua, and add a command in the prestart event for a scenario which will create a right-click menu option to invoke our new GUI. Of course there are other methods to invoke lua from WML, but this one will get us started. After all, we really just want to get something up on the screen ASAP, right?

===A most basic GUI===

{|
|[[File:Most basic gui.png|center|thumb|I can't believe this worked]]
|-
|In our prestart event, we create a simple menu item, which executes a single line of lua which calls the lua function most_basic_gui() which is found in gui_tutorial.lua:
|}

<syntaxhighlight lang=wml>
[set_menu_item]
id=most_basic_gui
description="Our first GUI"
[command]
[lua]
code=<<
wesnoth.require("~add-ons/<OUR_CAMPAIGN>/lua/gui_tutorial.lua").most_basic_gui()
>>
[/lua]
[/command]
[/set_menu_item]
</syntaxhighlight>

And create gui_tutorial.lua:
{| class="wikitable" style="margin:auto"
! !! The WML equivalent of dialogDefinition
|-
|
<syntaxhighlight lang=lua>
local function most_basic_gui()
local dialogDefinition = {
--click_dismiss = true, -- allow user to close dialog with click of a button
wml.tag.tooltip { id = "tooltip_large" }, -- required
wml.tag.helptip { id = "tooltip_large" }, -- required
wml.tag.grid { -- our most basic gui
wml.tag.row { -- a grid must include at least one row
wml.tag.column { -- a row needs a column
wml.tag.image { -- a column includes exactly one widget
label = "units/trolls/grunt.png"
}
}
}
}
}

local function preshow(dialog)
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
end
gui.show_dialog(dialogDefinition,preshow)

-- Or, if you want to define the gui in WML, something like:
-- local dialog_wml = wml.load("~add-ons/GUI_Tutorial/most_basic_gui.cfg",
-- true, "schema/gui_window.cfg")
-- gui.show_dialog(wml.get_child(dialog_wml, 'resolution'))
end
return { most_basic_gui = most_basic_gui}
</syntaxhighlight>
|
<syntaxhighlight lang=wml>
[tooltip]
id="tooltip_large"
[/tooltip]
[helptip]
id="tooltip_large"
[/helptip]
[grid]
[row]
[column]
[image]
label="units/trolls/grunt.png"
[/image]
[/column]
[/row]
[/grid]

</syntaxhighlight>
|}

In the above file, we have just the single function to create our GUI, followed by a return command which makes our function most_basic_gui() available to the [[LuaAPI/wesnoth#wesnoth.require|wesnoth.require()]] function as most_basic_gui().

Our function creates a table containing the definition of a "dialog", and then passes that to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]]. It should be noted that gui.show_dialog does not provide synchronization, so if your GUI makes changes to the game state, you'll need to jump through some hoops or you'll break replays and multiplayer, but that's not something we need to care about at this point, so just be aware that you may need to deal with it in the future.

Our dialog definition at this point includes three parts. The first two are a tooltip and a helptip, which are required and define how tooltips (use id = "tooltip_large" or id = "tooltip" or id = "tooltip_transparent"), and helptips (rarely used, but must be included here, and yes their definitions are "tooltip" not "helptip") will look (as we will see later, this really should be definition = "tooltip", but in this case it's id = "tooltip"). The third part is a grid, which is basically a table, like in HTML or MySQL, with rows and columns. A grid always contains at least one row. A row contains at least one column (note that a column does NOT span rows, it is completely contained within a row). Inside a column is exactly one item, a cell which contains a [[GUIWidgetDefinitionWML|widget]], in this case we'll use an image (later we'll see what else we can put in a cell). Note that we don't actually define a cell in our code, it's just a term used to refer to the contents of a column.

The preshow function is optional. If included in the call to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]], it is run before the GUI is displayed. In this case, we include it to display the dialog we created with lua in WML format. Near the end, in comments, we show how you would call [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] if you chose to define your dialog using WML. Note that what is shown here is the WML equivalent of our lua dialogDefinition, and not the complete WML you would need to use if you were to configure your GUI layout in WML.

Note: if you should try out the above, you'll have to hit escape or enter to close the GUI. Uncomment the "click_dismiss" line, and the user will be able to close the GUI with a mouse click.

===Adding a little flavor===

{|
|You may have noticed our GUI is missing a header and a way to close it when we're done admiring our work. Here we add a new first row to our grid, while demonstrating a couple formatting options: a border to put some distance between our grid cell and its neighbor, and the "use_markup = true" option to enable Pango support in our text.

Our third row adds an OK button at the bottom. You can associate actions with buttons to do all kinds of things, but here we just exploit the default behaviour to close the GUI.

Of course, we'll also have to modify our return to support the new function, and update our menu item(s) accordingly.
|-
|[[File:Most basic gui2.png|center|thumb|Adding header and a footer]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui2()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
wml.parse(wml.tostring({{"resolution", dialogDefinition}}), "schema/gui_window.cfg") -- schema validation errors will go to log
gui.show_dialog(dialogDefinition)
end
return { most_basic_gui = most_basic_gui, most_basic_gui2 = most_basic_gui2 }
</syntaxhighlight>

===And a bit more===
{|

|And now a minor, but important change. We want to add a new text field next to the image in the body of our GUI. Obviously, we want to add a new column, but this is more difficult than when we added new rows in the previous example. The problem is that all rows (at a given level) in a grid must contain the same number of columns. We can't have two columns in the row that constitutes the body of our GUI, but only one in the header and one in the footer. To solve this problem, we replace our image widget with a new grid, which can use as many columns as we like (as long as they are the same within each row of our new grid). This new grid contains a row with two columns, but that is okay because the new grid itself is placed in a single column, which matches our single column header and footer (ok button), keeping the rows balanced.
|-
|[[File:Most basic gui3.png|center|thumb|Rows with different numbers of columns]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui3()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column { -- This is the only column in this row,
-- to match the number of columns in
-- the rows of our header and footer
wml.tag.grid { -- A new grid, so we can use a different
-- number of columns
wml.tag.row {
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
},
wml.tag.column {
wml.tag.label {
label = "A troll"
}
}
}
}
}
},
wml.tag.row { -- A footer
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = "Ok"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

While we see here just the simplest of examples, you can create many levels of grids inside grids, rows with multiple columns some of which containing grids, etc, to build complicated dialogs to your liking.

==Containers==

===Stacked Widget===

TODO

===Listbox===
{|
| Now we'd like to add some more monsters. Obviously, we could just add more rows, but what if we won't know until runtime how many and which ones? We could break up the definition of our dialog and add new rows dynamically, it's just a table after all, but fortunately we have a widget which handles this for us, a listbox. A listbox is kind of like an array, a collection of similar objects where the number of items can vary. We will tell the GUI where we want the box, and what each entry in the box will look like, and then at runtime we can add entries to the box.

Note that listbox items are added from top to bottom. Another container, the horizontal_listbox, works just like a listbox except the items are added from left to right. With a grid listbox, items are added horizontally with the list wrapping to a new line as necessary.
|-
| [[File:Gui with listbox.png|center|thumb|Listbox with three items. Each item is an image and a label. The third item has been selected.]]

<syntaxhighlight lang=lua>
local function gui_with_listbox()
local monsters = {
{ image = "units/trolls/grunt.png",
string = "A troll" },
{ image = "units/monsters/cuttlefish.png",
string = "A cuttlefish" },
{ image = "units/monsters/yeti.png",
string = "A yeti" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
}

local listboxDefinition = wml.tag.listbox { id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
listboxDefinition
}
},
wml.tag.row {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_label.label = monster.string
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We begin by creating a simple table which represents the data which will be presented in our listbox. In most cases, we probably wouldn't create that monster table here, but we need it for our example.

The variable listbox_id gives us an identifier for our listbox so we can reference it when we need to. We don't really need to use a variable here, it's just convenient.

We define the structure for the elements in our listbox, stored in listboxItem. Note that we've replaced the actual data with identifiers (e.g. 'units/trolls/grunt.png' becomes 'id = "monster_image"), since each element may have different data.

We define the listbox itself, specifying the identifier, and the definition of our listbox element (which looks a lot like a grid). The cell inside the column contains a variable which is just the listbox element definition we created above; it's not necessary to do this, we could have used one big table, but it's easier to read this way (IMO).

We replace the hardcoded data in our GUI body with our new listbox definition, again using a variable to make it easier to read.

We create a function, often called preshow(), which will be called for us as part of the drawing the GUI (see the new optional argument in [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] -- there's also an optional postshow(), but we don't need it here). This is where we pull the data from our example table into the listbox. We create a listbox variable associated with the listbox, identified by the listbox_id we assigned earlier, inside the dialog which gui.show_dialog() passes to preshow(). Then we iterate through our data table, using each entry from that table to populate a listbox item.

Let's look at that last action a little more closely using an example.

<syntaxhighlight lang=lua>
listbox[i].monster_image.label = monster.image
</syntaxhighlight>

Which we can read as "In listbox element i of our listbox, for the image with identifier monster_image which we defined in our listboxItem, use the data from the corresponding index i in our example data table" (you don't see the index i for the monsters table here, but remember we're iterating using ipairs, we could have just as easily used listbox[i].monster_image.label = monsters[i].image). If you were to step through all of the variable substitutions, you'd see that for i=1, our dialogDefinition is basically the same thing as it was in the earlier examples, just supplied from a table instead of hardcoded (note that you can hardcode entries in a listbox in your dialog definition using the [list_data] tag, aka wml.tag.list_data, which we do not demonstrate here).

You will probably notice that our data does not line up nicely in the GUI. We will fix that later. We'll also demonstrate how the user can select an item in a listbox, and how you can identify which item that was using the selected_index variable of the listbox.

===Tree View===
====Simple Tree View====
{|
| You may have noticed that clicking on a listbox item in our listbox caused it to be highlighted with a box around the contents. This is because the items in a listbox are selectable. This will be useful when we want to add actions, but it looks a bit odd if we just want to present a list of data.

Also, most of the data had to be formatted the same for each item in the listbox. We could, perhaps, include custom markup in our labels, but the actual layout, like the number of columns per row, had to be the same for every item.

Another way to present a list of data is the tree view. Since a tree view supports multiple data types, we may need to create multiple definitions for the elements in our list. These are known as nodes. It will also be necessary to explicitly define which node to use for each element when we populate our tree view.
|-
| [[File:Basic tree view.png|center|thumb|Tree_views can hold multiple data types (only trolls have names here)]]
|}
<syntaxhighlight lang=lua line>
local function basic_tree_view()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", type = "Seamonsters" },
{ image = "units/monsters/yeti.png", label = "A yeti",
type = "Coolers" }
}

local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "trolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name",
linked_group = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
},
wml.tag.node {
id = "nottrolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "monster_name",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_image",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_label",
fixed_width = true
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_tv:add_item_of_type("trolls_node")
dialog.monsters_tv[i].monster_name.label = monster.name -- only trolls have a name
else
dialog.monsters_tv:add_item_of_type("nottrolls_node")
end
-- All of our monsters have an image and a label
dialog.monsters_tv[i].monster_image.label = monster.image
dialog.monsters_tv[i].monster_label.label = monster.label
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We have expanded our list of monsters to include three types of trolls. We have also given each troll a name. This is of course a rather simplistic example, we could have simply given each monster that is not a troll an empty name, but it as presented here our approach serves the purpose of demonstrating how we deal with multiple data types. Our new tree view contains a node for each type of data we will present. In preshow, we explicitly define each element in our list using add_item_of_type(), and populate the item accordingly. [Note: in our listbox example, we could have used add_item() to add items to the listbox, but chose not to since that section was already introducing a number of new concepts. But here, since we have multiple types of items we need to be able to specify the type of the item when we add one, hence we need to use add_item_of_type()].

You may also note the addition of a few linked_group lines. We'll cover linked groups in more detail later, but as used here they instruct the GUI that each column using the same node type needs to be aligned with the others. For example, all of our trolls line up nicely.

====Building a Tree====
{|
| colspan="2" |At this point, one may wonder about the name "tree view", since what he have seen doesn't look much like a tree. To make a tree-like structure, we'll demonstrate adding children to nodes. At the top level our (upside-down) tree will have two nodes, one for trolls and one for everything else. A toggle_button (a type of button which changes states when you push it) will allow us to expand the trolls node to expose its children, which are themselves nodes, though they only contain a label at this point.
|-
| [[File:Basic tree view2a.png|center|thumb|Tree_view with Trolls folded]] || [[File:Basic tree view2b.png|center|thumb|Tree_view with Trolls unfolded]]
|}
<syntaxhighlight lang=lua line>
local function building_a_tree()
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
}
},
wml.tag.column {
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Show me the " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
-- You can refer to an object by its position

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[1].race_label.label = "Trolls"
-- dialog.monsters_tv[1].race_button.on_modified =
-- function()dialog.monsters_tv[1].unfolded =
-- dialog.monsters_tv[1].race_button.selected end

-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][1].monster_type.label = "Whelp"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][2].monster_type.label = "Shaman"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][3].monster_type.label = "Troll"

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[2].race_label.label = "Other scary things"
-- dialog.monsters_tv[2].race_button.visible = "hidden"

-- ... or you can refer to that object using the return value
-- from add_item_of_type
local troll_node = dialog.monsters_tv:add_item_of_type("race_node")
troll_node.race_label.label = "Trolls"
troll_node.race_button.on_modified =
function()
troll_node.unfolded = troll_node.race_button.selected
end
local item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Whelp"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Shaman"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Troll"

local not_troll_node =
dialog.monsters_tv:add_item_of_type("race_node")
not_troll_node.race_label.label = "Other scary things"
not_troll_node.race_button.visible = "hidden"

end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We define two nodes in our tree, a race_node for the top level, and a details_node for the children of a race_node. The rest of the interesting bits are in preshow().

We demonstrate two different ways of creating and accessing items, the first (commented out) just using the order in which they are created, while in the second we capture the result of add_item_of_type() in a variable we can use to refer to the newly defined object. The first method is shown primarily to demonstrate the structure of the resulting objects. The second method is perhaps easier to follow, and is almost necessary when you start doing things like dynamically deleting nodes, so it is in most cases a better practice (of course, you probably won't want to use the same variable for each node like we did, and perhaps not one local to the preview function).

We add a node, label it "Trolls", and add a callback to the button such that the children of the node will be visible (the node is "unfolded", a boolean value which defaults to false) when the button is checked (selected == true). Then we add three "details_node" nodes as children of this node.

Our second node, "Other scary things" will remain empty for now, so we'll set the visible attribute on its button to "hidden" (which is like false, but with hidden the widget still takes up space).

{|
| This example is rather ugly, both in the hardwired code and the appearance of the resulting GUI, but it addresses a couple important aspects of how tree views work and how we might use them. Let's clean it up a bit. We'll add an indentation_step_size to the tree view, along with a spacer and [[#Alignment|horizontal_alignment]] to our details node, to make the labels line up nicely, and change the button [[#Definitions|definition]] to replace the checkbox with something that looks like it belongs there. We will look at methods for handling layout in more depth [[#Appearance|later]].
|-
| [[File:Basic tree view2c.png|center|thumb|Our tree_view with proper alignment]]

<syntaxhighlight lang=lua>
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
indentation_step_size = 20,
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
definition = "tree_view_node"
}
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.spacer { width = 40 }
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}

</syntaxhighlight>

===Multi_page===
====Simple Multi_page====
{|
|-
Like a tree_view, a multi_page is a heterogeneous container which is dynamically populated, however, while a multi_page contains multiple elements (pages), only one page is displayed at any one time. Its purpose is perhaps best described by a couple of examples.
|-
[[File:Basic multipage.png|center|thumb|Multi_page showing active page]]
|}
<syntaxhighlight lang=lua>
local function basic_multipage()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll",
name = _"Bob", type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp",
name = "Junior", type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman",
name = _"Alice", type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish",
type = "Seamonsters" },
{ image = "units/monsters/yeti.png",
label = "A yeti",
type = "Coolers" }
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
multi_page
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}

local function preshow(dialog) -- Prepare the GUI before display
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_label.label = monster.label
end
--dialog.monsters_mp.selected_index = 5
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

As you can see, the code for our basic multi_page GUI looks a lot like our basic tree_view GUI. The difference is what is displayed. While both the tree_view and the multi_page containers contain five items, with the multi_page, only the first one is displayed. More specifically, only the page associated with the selected_index attribute of the multi_page object, which defaults to 1, is displayed. If we were to uncomment the last line in preshow(), we would still see only one item, but it would be the fifth one we allocated. It's nice to know all our pages are in there somewhere, but this example is pretty useless. What we need is a way to select which page we want to see from within our GUI.

====A More Useful Multi_page====

{|
| colspan="2" | To demonstrate the usefulness of a multi_page, and highlight its difference from a tree_view, we'll add a listbox to allow us to select the page to view. We'll also need to add a little action to our GUI.
|-
| style="align:centered" |[[File:More useful multipage.png|center|thumb|User selected Troll]] || [[File:More useful multipage2.png|center|thumb|User selected Cuttlefish]]
|}

<syntaxhighlight lang=lua>
local function more_useful_multi_page()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
race = "Trolls", tip = "Your uncle" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
race = "Trolls", tip = "Your nephew" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
race = "Trolls", tip = "Your auntie" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", race = "Seamonsters",
tip = "Not a fish" },
{ image = "units/monsters/yeti.png",
label = "A yeti", race = "Coolers",
tip = "ROAR!" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
}
}
}

local listboxDefinition = wml.tag.listbox {
id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
},
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
listboxDefinition
},
wml.tag.column {
wml.tag.spacer {
width = 30
}
},
wml.tag.column {
multi_page
},
}
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_image.tooltip = monster.tip
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_image.tooltip = monster.tip
dialog.monsters_mp[i].monster_label.label = monster.label
end
local function switch_page()
dialog.monsters_mp.selected_index = listbox.selected_index
end
listbox.on_modified = switch_page
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

Most of this should look pretty familiar. We've simply taken the previous example and added a second column to our GUI using code from an earlier example to add a listbox. In addition, we altered the page layout slightly, and added a spacer column in the dialog definition to approve the appearance.

The interesting stuff is in preshow(). Again we've merged in some listbox code from an earlier example, but we've also created a new local function switch_page(), which simply sets the selected_index attribute of our multi_page to the same as that of our listbox, and then we've configured the listbox.on_modified callback to call switch_page(). Now when the user selects an item in the listbox (updating listbox.selected_index and triggering listbox.on_modified), dialog.monsters_mp.selected_index is updated accordingly and therefore the visible page changes to the one associated with the selected unit.

Also note in preshow() we've added a new child to our monster_image identifier for both the listbox and the multi_page, a tooltip. When the user hovers the mouse over the image of one of our monsters, they'll see a popup message which we've added to our monster table. Try changing '''wml.tag.tooltip { id = "tooltip_large" }''' to '''wml.tag.tooltip { id = "tooltip }''' in the dialogDefinition to see a different tooltip style.

==Actions Have Consequences==

So far, our GUIs have only displayed some information on the screen, but at some point we're probably going to want to use a GUI to get input from the user. In this section we will look at return values that can be assigned to a widget based upon its state, and callbacks, which are functions invoked when something happens with a widget. As we will see, a button is a good example, as it can return a value or take an action, or both, when pressed. Earlier we saw how the selected_index attribute of some widgets, such as the listbox, can also be used as a sort of return value.

===Buttons===
{|
| colspan=2 | In this example, we'll create a couple buttons which provide the user a choice, use a handy confirmation popup to confirm that choice, and demonstrate how we get the results back where we can put them to use.
|-
| [[File:Basic return value.png|center|thumb|There can be only one]] || [[File:Basic return value_confirm.png|center|thumb|The user selected Alice, let's confirm this critical choice]]
|}

<syntaxhighlight lang=lua>
local function basic_return_value()

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "leader_lg",
fixed_height = true,
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" ..
_"Which unit shall lead your army?" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Alice" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/elves-wood/sylph.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 1
}
}
},
}
},
wml.tag.column {
wml.tag.spacer { width = 20 }
},
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Bob" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/human-loyalists/marshal.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 2
}
}
}
}
}
}
}
}
}
}
}
local user_chose = gui.show_dialog(dialogDefinition)
local leader
if user_chose == -1 then -- User closed the dialog by hitting the Enter key
leader = nil
end
if user_chose == -2 then -- User closed the dialog by hitting the Escape key
leader = nil
end

if user_chose == 1 then
leader = "Alice"
end
if user_chose == 2 then
leader = "Bob"
end

local confirmed_leader_choice

if leader ~= nil then
local query = _"You want " .. leader .. _" as your leader?"
confirmed_leader_choice = gui.confirm(query)
end

if confirmed_leader_choice then
wesnoth.message("Great!")
else
wesnoth.message("Fine, lead them yourself!")
end
end
</syntaxhighlight>

Here we've added a couple buttons, and assigned each of them a return value. When the user selects one of these buttons, the GUI is closed and the value of return_value is returned from gui.show_dialog(). We then use [https://wiki.wesnoth.org/LuaAPI/gui#gui.show_prompt gui.confirm()] which provides a very simple Yes/No popup and returns true or false, respectively. Other useful functions can be found on that page which provide handy alternatives to creating your own GUI for other simple user inputs.

The use of return_value is rather limited, as it only returns integers and can't be used with containers like listboxes. In more complex cases we'll need to turn to callback functions which are invoked when something happens to a widget, like clicking a button or a widget's value changing. Earlier, we saw an example of [[LuaAPI/types/widget#on_modified|widget.on_modified()]]. More examples of callbacks can be found at [[LuaAPI/types/widget#on_modified|that link]].

===Slider and Textbox===
{|
| Here we see a couple methods of getting more dynamic input from the user, a slider and a textbox presented in one silly example.
|-
| [[File:Slider and textbox.png|center|thumb|Two ways of getting input from the user]]
|}

<syntaxhighlight lang=lua>
function slider_and_textbox()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = _"How much gold will you pay for this old rusty sword?"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.slider {
id = "gold_sl",
minimum_value = 0,
maximum_value =
wesnoth.sides[wesnoth.current.side].gold,
value = math.floor(
wesnoth.sides[wesnoth.current.side].gold/2)
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.text_box {
id = "gold_tb",
--hint_text = _ "Enter gold here",
--hint_image = "images/gold_pile.png",
label = tostring(math.floor(
wesnoth.sides[wesnoth.current.side].gold/2))
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
local function show_input()
wesnoth.interface.add_chat_message(_"You chose " ..
dialog.gold_sl.value .. _" with the slider")
wesnoth.interface.add_chat_message(_"You entered " ..
tostring(dialog.gold_tb.text) .. _" in the text_box")
end
-- this is a button, so we use on_button_click, not on_left_click
dialog.ok.on_button_click = show_input

dialog.gold_sl.on_modified = function()
dialog.gold_tb.text = tostring(dialog.gold_sl.value)
end
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We create a slider, with a range from 0 to the amount of gold possessed by the current side and an initial value in the middle, and a text box with the same initial value. We assign a function to our OK button which simply reports on the values provided by the user. For no reason whatsoever, we add a callback such that when the user adjusts the slider the value in the textbox is update to match the slider.

Note that the textbox returns text, even though it looks like we're expecting the user to input a natural number. Remember to validate those inputs.

You can use text_hint to place a caption in the box that will help the user understand what to enter in the box, and possibly an image as well. For example, in the search box in the recall menu uses '''hint_text = _ "Search", hint_image = "icons/action/zoomdefault_25.png~FL(horiz)"'''. Of course, you can't have a hint and a label in the same text_box at the same time, so in our example we've only included them as comments.

There is also a widget called a spinner, which is kind of like the combination of a text_box and a slider. As of the release of 1.18, it appears to be unfinished so the strange syntax needed to make it work is probably not the best thing to document, and we will omit it for now.

==Appearance==

'''This section needs help'''

===Borders===

Borders allow you to force unused space around a column, for example so that your widgets don't runtogether. You can specify the border to be one or more of top, bottom, left, right, or all. The border_size sets the amount of padding, in pixels.

<syntaxhighlight lang=lua>
wml.tag.column{
border = "left, right"
border_size = 25
}
</syntaxhighlight>

===Alignment===
{|
| colspan=2 |By default, the GUI will usually center widgets in their cells, which is not always what we want. In this example, we use horizontal_alignment to move widgets around a little.

In more complex cases, it may be useful to add [[GUIWidgetDefinitionWML#Spacer|spacers]] to help force alignment, or use linked_groups to force consistent alignment for objects within a grid.
|-
| [[File:Gui tutorial alignment without.png|center|thumb|Default alignment]] ||[[File:Gui tutorial alignment with.png|center|thumb|Showing off some alignment options]]
|}
<syntaxhighlight lang=lua>
local function basic_alignment()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = "Ralph"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "right",
wml.tag.label {
label = "Sam"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/troll-hero-attack-se-4.png" -- 122x102
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "left",
wml.tag.label {
label = "Jr"
}
},
wml.tag.column {
horizontal_alignment = "right",
wml.tag.image {
label = "units/trolls/whelp.png" -- 72x72
}
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

The screenshots show the output of this example with and without the horizontal_alignment lines included above.

A label allows you to set the text_alignment field (e.g. text_alignment = "left"). Note, however, this only aligns the text within the label. The label itself will probably be centered in the column, giving the false appearance that your text alignment is not working.

===Growth===

To keep your dialog nicely balanced, the GUI2 engine may need to grow rows and/or columns. You can control which columns, for example, grow and which do not, by setting some with grow_factor = 1, and others with grow_factor = 0 (do not grow). While grow factors of 0 and 1 are the most common, you can use other values to adjust the relative growth if you really need to, see [[GUILayout]] for the gory details.

It it sometimes useful to include a column with a [spacer] and a grow_factor (often the only column with grow_factor != 0) whose sole purpose is to keep your GUI aligned nicely as the layout engine does its evil.

To force a column to stretch to fit available space, use horizontal_grow = true. Note that horizontal_grow is not compatible with horizontal_alignment. There is also a vertical_grow parameter.

If you need to see every little detail about the layout process, start wesnoth with --log-debug=gui/layout. Good luck with that.

===Definitions===
Many widgets can be configured to have to a different appearance, for example in our tree_view example we changed the definition of a toggle_button from the default of a checkbox by setting definition = "tree_view_node". This option was found by looking at the id of a toggle_button_definition in .../data/gui/widget/toggle_button_tree_view_node.cfg:

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib
###
### Definition of a toggle button to be used in a tree view as node fold/unfold indicator
###
[toggle_button_definition]
id = "tree_view_node" # <--- we can use 'definition = "tree_view_node"' in a [toggle_button] to select this definition
description = "Fold/unfold status indicator of a tree view node."
</syntaxhighlight>

{|
|There are many other definitions for buttons and other widget types in that directory. It would be nice to have a list (linked here), but for now you'll just have to look around.

We can even create our own custom definitions using [[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition()]]. In this example, we copy from .../data/gui/widget/toggle_button_tree_view_node.cfg with a slight change so that our button turns red ( '''~BLEND(255,0,0,1)''' ) when focused.

In this example, we will use wesnoth.wml_actions to create the WML tag [add_widget_def_demo].

Note the first line, a common convention for creating an alias for wml.tag.
|-
|[[File:Gui tutorial custom widget.png|center|thumb|Different definition of buttons, including one of our own (right)]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag -- save ourselves some typing
function wesnoth.wml_actions.add_widget_def_demo()
local definition = {
id = "tree_view_node_custom",
description = "Fold/unfold status indicator of a tree view node (MODIFIED).",
T.resolution {
min_width = 25,
min_height = 19,
default_width = 25,
default_height = 19,
max_width = 25,
max_height = 19,
-- Unselected - note there's no tags for unselected/selected, that's simply determined by the order
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/fold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/fold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/fold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
-- Selected
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/unfold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
}
}
gui.add_widget_definition("toggle_button", "tree_view_node_custom", definition)

local dialogDefinition = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid {
T.row {
T.column {
T.toggle_button {
definition = "default"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node_custom"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end

</syntaxhighlight>

See [[GUIWidgetDefinitionWML]] for more details on widget definitions.

You can also give the whole dialog a definition, like definition = "tooltip_large". There is no gui.add_window_definition(), however a window is technically a type of widget so it may be possible to create your own window definitions (please update this if you do).

===Panels===

===Canvases===
Part of panels? Sort of?

A canvas is a surface you can draw on. A dialog has them, as does a panel, and for these canvas 1 refers to the background, while canvas 2 refers to the foreground. Other widgets may have canvases that may have other meanings, or no canvases at all. See more at [[LuaAPI/gui/widget#set_canvas]].

Here's a fun little trick. Set your dialog background to be transparent:
<syntaxhighlight lang=lua>
local function preshow(dialog)
dialog:set_canvas(1, { } )
end
</syntaxhighlight>

Or, if you want an opaque GUI background with the screen behind it blurred like what you see behind the text of a [message], you can set your window definition to "message":
<syntaxhighlight lang=lua>
...
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
definition = "message",
...
</syntaxhighlight>

{|
|Here we take our [[#Progress Bar|progress bar]], and add a text overlay.

Note: either using text on a canvas is rather limited, or I just couldn't figure it out. For example, I could not get the text size any smaller, and any attempts to do so simply resulted in very blocky text. And the spaces were necessary so that the text wasn't stretched out. I also find it surprising that the progress bar does not have this feature inherently. So it's not a great example, but it should be enough to get you started using canvases. Be sure to visit the [[LuaAPI/gui/widget#set_canvas|link]] mentioned above for more options.
|-
|[[File:Gui tutorial canvas text.png|center|thumb|A progress bar in the background, with text in the foreground]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar_with_overlay()
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.grid {
T.row {
T.column {
T.panel { id = "panel",
T.grid {
T.row {
T.column {
T.button { id = "button",
label =_ "Press me"}
},
T.column {
T.progress_bar { id = "progress" }
},
T.column {
T.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
dialog.panel:set_canvas(2, { T.text { text_alignment = "center", font_size = 48,
text_markup = true, text = " " ..
dialog.progress.percentage .. "% " } } )
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

You may notice we added a panel and placed our text on the foreground canvas(2) on it, since the progress_bar itself does not support canvases.

===Placement===

You may have noticed that all of our dialogs are centered on the screen. This is the default. You can override this and place the dialog wherever you like by setting automatic_placement = false, along with x, y, width, and height at the top level of your dialog definition (next to tooltip =, etc).

'''This part about placement needs review'''
If you prefer, you may replace x and/or y with horizontal_placement and vertical_placement, such as horizontal_placement = "left". You can even set the placement values using WFL, for example horizontal_placement = "(gamemap_width / 3)" -- see [[#Using WFL with GUI2|Using WFL with GUI2]].

==Miscellaneous==

TODO: This stuff doesn't belong in a tutorial. It's worth documenting, but not here. Better to save these here for now than keep them on my laptop.

===Progress Bar===
{|
|A progress_bar is a graphical representation of a percent. In this example, we present the user with a puzzle. They must hit the button repeatedly before they can close the GUI. A progress_bar displays their current progress toward completion.
|-
|[[File:Gui tutorial progress bar.png|center|thumb|upright=2]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.button { id = "button",
label =_ "Press me"
}
},
wml.tag.column {
wml.tag.progress_bar { id = "progress" }
},
wml.tag.column {
wml.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end

gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

===Unit Preview Pane===

{|
|A unit_preview_pane takes a unit (or a unit type), and presents a graphical representation of the unit and its more important attributes, along with tooltips for additional details, in the same way that the recall menu does. Here we see an example of a unit which has picked up some items, including a weapon, which are affecting its stats.
|-
|[[File:Gui tutorial unit preview pane.png|center|thumb]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag

function wesnoth.wml_actions.recall_from_variable(cfg)
local from_array = cfg.from or wml.error(
"[recall_from_variable]: missing required from= ")
local to_var = cfg.to or wml.error(
"[recall_from_variable]: missing required to= ")
local unit_list = wml.array_access.get(from_array) or wml.error(
string.format("[recall_from_variable]: failed to fetch wml array %s",from_array))

local listboxItem = T.grid {
T.row {
T.column {
T.label { id = "available_unit",
linked_group = "available_unit"
}
}
}
}

local listbox_id = "available_units"
local listboxDefinition = T.listbox { id = listbox_id,
T.list_definition {
T.row {
T.column {
T.toggle_panel { listboxItem }
}
}
}
}
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.linked_group { id = "available_unit", fixed_width = true },
T.grid {
T.row { -- header
T.column {
T.grid {
T.row {
T.column {
border = "bottom",
border_size = 10,
T.label {
use_markup = true,
label = ""
.. _"Select unit to recall" .. ""
}
}
}
}
}
},
T.row { -- Body
T.column {
T.grid {
T.row {
T.column {
border = "right",
border_size = 40,
listboxDefinition
},
T.column {
T.unit_preview_pane { id = "unit_preview" }
}
}
}
}
},
T.row { -- Footer
T.column {
T.grid {
T.row {
T.column {
T.spacer { width = 400 }
},
T.column {
border = "top,right",
border_size = 10,
T.button { id = "ok",
label = _"OK"
}
}
}
}
}
}
}
}

local picked = 1

local function preshow(dialog)
local listbox = dialog[listbox_id]
for i,unit in ipairs(unit_list) do
listbox[i].available_unit.label = unit.name .. "(" ..
unit.language_name .. ")"
end
local function draw_unit()
wesnoth.units.to_recall(unit_list[listbox.selected_index])
local tmp = wesnoth.units.find_on_recall{ id =
unit_list[listbox.selected_index].id }[1]
dialog.unit_preview.unit = tmp
wesnoth.units.extract(tmp)
picked = listbox.selected_index
end
draw_unit()
listbox.on_modified = draw_unit
end

gui.show_dialog(dialogDefinition,preshow)

wml.variables[to_var] = picked - 1
end

</syntaxhighlight>

This should all be pretty self evident by now. We are provided with an array of stored units (from [store_unit] in WML). We create a listbox populated with units and we use the selected_index to determine which element in the table to send to unit_preview_pane. Since our input is an array of unit data, not actual units, we use [[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] to take the definition of one from our array and place it on the recall list (turning it into an actual unit), [[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] to fetch that unit in a form that the unit_preview_panel understands, and finally [[wesnoth.units.extract|wesnoth.units.extract]] to remove the unit from the recall list when we are done with it.

And of course we subtract one from the selected_index when we return our choice to WML, since lua arrays count from 1 and WML from 0.

The unit_preview_pane will also accept a unit_type instead of a specific unit.

==Appendix==

===Explore Your Options===

We've seen a lot of options that can be set to modify the behaviour of our dialogs, some on columns, some on widgets, etc. These are in the process of being documented [[GUIWidgetInstanceWML|here]], but if you would like to go straight to the source, the data Wesnoth uses to validate your configuration can be found in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui data/schema/gui] under your install directory.

Let's look at a scroll_label, for example. A scroll_label is a widget, so we look in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/widget_instances.cfg widget_instances.cfg] and find the following. Here we can see five parameters we can provide to our scroll_label (in addition to the ones available to all widgets, like id and definition, see the entry super=... which refers you to the widget_instance in the file [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/generic.cfg data/schema/gui/generic.cfg]), along with their types and default values. For example, we could set "link_aware = true", and if we do not we can assume that link_aware will be false. While this does not explain what these parameters do, the information provided in the schema directory is often helpful nonetheless.

<syntaxhighlight lang=wml>
[tag]
name="scroll_label"
min="0"
max="infinite"
super="$generic/widget_instance"
{DEFAULT_KEY "horizontal_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "vertical_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "wrap" bool true}
{DEFAULT_KEY "text_alignment" f_h_align "left"}
{DEFAULT_KEY "link_aware" bool false}
[/tag]
</syntaxhighlight>

We see that our scrollbars are of type scrollbar_mode. It would probably help if we knew what values are available to the scrollbar_mode. In [https://github.com/wesnoth/wesnoth/tree/master/data/schema/types/gui.cfg data/schema/types/gui.cfg] we find this:

<syntaxhighlight lang=wml>
[type]
name=scrollbar_mode
value="always|never|auto|initial_auto"
[/type]
</syntaxhighlight>

The variable types found in the schema files are described at [[GUIVariable]].

Note: The keys in the schema file correspond to the attributes used when configuring your widgets. They will not always align perfectly with keys used by the Lua API. For example, the slider uses maximum_value in its configuration, and max_value when using the Lua API:

<syntaxhighlight lang=wml>
[slider]
id="my_slider"
maximum_value = 100
[/slider]
</syntaxhighlight>

<syntaxhighlight lang=lua>
dialog.my_slider.max_value = 90
</syntaxhighlight>

===Using WFL with GUI2===

If you look at the variable type descriptions at [[GUIVariable]] you may notice that many of them start with "f_" and have "or formula" in the description. This means that you can use [[Wesnoth_Formula_Language|Wesnoth Formula Language (WFL)]] formulas in these fields, with certain variables made available to you (which variables and what they mean can be challenging to ascertain, but you can generally figure it out by example).

Looking at [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/window.cfg data/schema/gui/window.cfg] we see that 'height' has type f_unsigned, which tells us that height is an unsigned integer, and that we can use a WFL formula to define it in a window_definition. In [https://github.com/wesnoth/wesnoth/tree/master/data/gui/themes/default/window/wml_message.cfg data/gui/window/wml_message.cfg] (data/gui/themes/default/window/wml_message.cfg starting around 1.19.2), we find the line '''height = "(screen_height - 30)"'''. This does exactly what it looks like, it sets the height of our window to 30 pixels less than the height of the screen.

===Useful Links===
[[GUIToolkitWML]] - Documents the keys/values available on various objects (e.g. "what attributes can I set on a column?") 
[[LuaAPI/gui|LuaAPI/gui]] - Mostly about opening windows 
[[LuaAPI/types/widget]] - Widget attributes and callbacks 
[https://wiki.wesnoth.org/Category:GUI_WML_Reference GUI_WML_Reference] 
[https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui .../data/schema/gui/*.cfg] - Lists of valid options for various GUI objects 
[https://devdocs.wesnoth.org/layout_algorithm.html Layout Algorithm] - For windows, at least

===Credits===

The basic framework that composes the initial examples was lifted from LotI. It's a great place to find well written examples, but some of it is complex enough to be a little overwhelming when getting started.

Many examples, particularly tree view and multipage, are heavily derived from the World Conquest multiplayer campaign.

Sandbox/GUI/Getting Started

2024-11-01T20:51:54Z

White haired uncle: /* Introduction */

So, it looks like I can't exclude this page/section from the search engine as I had hoped. I wanted to put this in a sandbox so that it wouldn't be published without some proper review.

==Introduction==

This guide is designed to help you get a simple Wesnoth GUI, implemented in lua, up and running while describing the basic building blocks along the way. It is written in a narrative format, where most examples build on previous examples, and therefore while not always necessary it may be desirable to read from start to finish. The reader, probably a UMC author, should have a basic knowledge of working with lua within Wesnoth.

Some would find creating a GUI in part or in full using WML simpler to follow, and those alternatives are available, for example [[LuaAPI/gui/example]], but we're using lua here. If you find WML easier to follow, you can always convert the lua tables that define the GUIs to WML using [[LuaAPI/wml#wml.tostring|wml.tostring]], for example:

<syntaxhighlight lang=lua>
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
</syntaxhighlight>

In the comments of our first GUI, below, is an example which loads a WML GUI configuration using [[LuaAPI/wml#wml.load|wml.load()]], validating against the GUI2 window schema.

In some examples, instead of defining the entire GUI at once, we'll break out some parts into separate variables. If you try to view one in WML and get an error from wml.tostring() about expecting a WML table and not a table, try passing your variable(/table) inside a table:

<syntaxhighlight lang=lua>
print(wml.tostring({listboxItem}))
gui.show_lua_console()
</syntaxhighlight>

===What is GUI2?===
Once upon a time, Wesnoth had a GUI system which is now commonly referred to as GUI1. As of 1.19, GUI1 has been almost completely replaced by GUI2. UMC authors will probably never encounter GUI1 and can simply use the terms GUI and GUI2 interchangeably, at least until GUI3 comes along.

Instead of spending a lot of time here giving an overview of what GUI2 is and what makes it great, and not so great, let's charge ahead so we can see it in action, and let readers who are interested look elsewhere(TODO: link) for a more formal definition. (TODO: is this the right approach for most readers?).

==Getting Started==

For example purposes, we'll create a directory in our campaign directory called lua containing a file called gui_tutorial.lua, and add a command in the prestart event for a scenario which will create a right-click menu option to invoke our new GUI. Of course there are other methods to invoke lua from WML, but this one will get us started. After all, we really just want to get something up on the screen ASAP, right?

===A most basic GUI===

{|
|[[File:Most basic gui.png|center|thumb|I can't believe this worked]]
|-
|In our prestart event, we create a simple menu item, which executes a single line of lua which calls the lua function most_basic_gui() which is found in gui_tutorial.lua:
|}

<syntaxhighlight lang=wml>
[set_menu_item]
id=most_basic_gui
description="Our first GUI"
[command]
[lua]
code=<<
wesnoth.require("~add-ons/<OUR_CAMPAIGN>/lua/gui_tutorial.lua").most_basic_gui()
>>
[/lua]
[/command]
[/set_menu_item]
</syntaxhighlight>

And create gui_tutorial.lua:
{| class="wikitable" style="margin:auto"
! !! The WML equivalent of dialogDefinition
|-
|
<syntaxhighlight lang=lua>
local function most_basic_gui()
local dialogDefinition = {
--click_dismiss = true, -- allow user to close dialog with click of a button
wml.tag.tooltip { id = "tooltip_large" }, -- required
wml.tag.helptip { id = "tooltip_large" }, -- required
wml.tag.grid { -- our most basic gui
wml.tag.row { -- a grid must include at least one row
wml.tag.column { -- a row needs a column
wml.tag.image { -- a column includes exactly one widget
label = "units/trolls/grunt.png"
}
}
}
}
}

local function preshow(dialog)
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
end
gui.show_dialog(dialogDefinition,preshow)

-- Or, if you want to define the gui in WML, something like:
-- local dialog_wml = wml.load("~add-ons/GUI_Tutorial/most_basic_gui.cfg",
-- true, "schema/gui_window.cfg")
-- gui.show_dialog(wml.get_child(dialog_wml, 'resolution'))
end
return { most_basic_gui = most_basic_gui}
</syntaxhighlight>
|
<syntaxhighlight lang=wml>
[tooltip]
id="tooltip_large"
[/tooltip]
[helptip]
id="tooltip_large"
[/helptip]
[grid]
[row]
[column]
[image]
label="units/trolls/grunt.png"
[/image]
[/column]
[/row]
[/grid]

</syntaxhighlight>
|}

In the above file, we have just the single function to create our GUI, followed by a return command which makes our function most_basic_gui() available to the [[LuaAPI/wesnoth#wesnoth.require|wesnoth.require()]] function as most_basic_gui().

Our function creates a table containing the definition of a "dialog", and then passes that to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]]. It should be noted that gui.show_dialog does not provide synchronization, so if your GUI makes changes to the game state, you'll need to jump through some hoops or you'll break replays and multiplayer, but that's not something we need to care about at this point, so just be aware that you may need to deal with it in the future.

Our dialog definition at this point includes three parts. The first two are a tooltip and a helptip, which are required and define how tooltips (use id = "tooltip_large" or id = "tooltip" or id = "tooltip_transparent"), and helptips (rarely used, but must be included here, and yes their definitions are "tooltip" not "helptip") will look (as we will see later, this really should be definition = "tooltip", but in this case it's id = "tooltip"). The third part is a grid, which is basically a table, like in HTML or MySQL, with rows and columns. A grid always contains at least one row. A row contains at least one column (note that a column does NOT span rows, it is completely contained within a row). Inside a column is exactly one item, a cell which contains a [[GUIWidgetDefinitionWML|widget]], in this case we'll use an image (later we'll see what else we can put in a cell). Note that we don't actually define a cell in our code, it's just a term used to refer to the contents of a column.

The preshow function is optional. If included in the call to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]], it is run before the GUI is displayed. In this case, we include it to display the dialog we created with lua in WML format. Near the end, in comments, we show how you would call [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] if you chose to define your dialog using WML. Note that what is shown here is the WML equivalent of our lua dialogDefinition, and not the complete WML you would need to use if you were to configure your GUI layout in WML.

Note: if you should try out the above, you'll have to hit escape or enter to close the GUI. Uncomment the "click_dismiss" line, and the user will be able to close the GUI with a mouse click.

===Adding a little flavor===

{|
|You may have noticed our GUI is missing a header and a way to close it when we're done admiring our work. Here we add a new first row to our grid, while demonstrating a couple formatting options: a border to put some distance between our grid cell and its neighbor, and the "use_markup = true" option to enable Pango support in our text.

Our third row adds an OK button at the bottom. You can associate actions with buttons to do all kinds of things, but here we just exploit the default behaviour to close the GUI.

Of course, we'll also have to modify our return to support the new function, and update our menu item(s) accordingly.
|-
|[[File:Most basic gui2.png|center|thumb|Adding header and a footer]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui2()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
gui.show_dialog(dialogDefinition)
end
return { most_basic_gui = most_basic_gui, most_basic_gui2 = most_basic_gui2 }
</syntaxhighlight>

===And a bit more===
{|

|And now a minor, but important change. We want to add a new text field next to the image in the body of our GUI. Obviously, we want to add a new column, but this is more difficult than when we added new rows in the previous example. The problem is that all rows (at a given level) in a grid must contain the same number of columns. We can't have two columns in the row that constitutes the body of our GUI, but only one in the header and one in the footer. To solve this problem, we replace our image widget with a new grid, which can use as many columns as we like (as long as they are the same within each row of our new grid). This new grid contains a row with two columns, but that is okay because the new grid itself is placed in a single column, which matches our single column header and footer (ok button), keeping the rows balanced.
|-
|[[File:Most basic gui3.png|center|thumb|Rows with different numbers of columns]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui3()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column { -- This is the only column in this row,
-- to match the number of columns in
-- the rows of our header and footer
wml.tag.grid { -- A new grid, so we can use a different
-- number of columns
wml.tag.row {
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
},
wml.tag.column {
wml.tag.label {
label = "A troll"
}
}
}
}
}
},
wml.tag.row { -- A footer
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = "Ok"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

While we see here just the simplest of examples, you can create many levels of grids inside grids, rows with multiple columns some of which containing grids, etc, to build complicated dialogs to your liking.

==Containers==

===Stacked Widget===

TODO

===Listbox===
{|
| Now we'd like to add some more monsters. Obviously, we could just add more rows, but what if we won't know until runtime how many and which ones? We could break up the definition of our dialog and add new rows dynamically, it's just a table after all, but fortunately we have a widget which handles this for us, a listbox. A listbox is kind of like an array, a collection of similar objects where the number of items can vary. We will tell the GUI where we want the box, and what each entry in the box will look like, and then at runtime we can add entries to the box.

Note that listbox items are added from top to bottom. Another container, the horizontal_listbox, works just like a listbox except the items are added from left to right. With a grid listbox, items are added horizontally with the list wrapping to a new line as necessary.
|-
| [[File:Gui with listbox.png|center|thumb|Listbox with three items. Each item is an image and a label. The third item has been selected.]]

<syntaxhighlight lang=lua>
local function gui_with_listbox()
local monsters = {
{ image = "units/trolls/grunt.png",
string = "A troll" },
{ image = "units/monsters/cuttlefish.png",
string = "A cuttlefish" },
{ image = "units/monsters/yeti.png",
string = "A yeti" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
}

local listboxDefinition = wml.tag.listbox { id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
listboxDefinition
}
},
wml.tag.row {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_label.label = monster.string
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We begin by creating a simple table which represents the data which will be presented in our listbox. In most cases, we probably wouldn't create that monster table here, but we need it for our example.

The variable listbox_id gives us an identifier for our listbox so we can reference it when we need to. We don't really need to use a variable here, it's just convenient.

We define the structure for the elements in our listbox, stored in listboxItem. Note that we've replaced the actual data with identifiers (e.g. 'units/trolls/grunt.png' becomes 'id = "monster_image"), since each element may have different data.

We define the listbox itself, specifying the identifier, and the definition of our listbox element (which looks a lot like a grid). The cell inside the column contains a variable which is just the listbox element definition we created above; it's not necessary to do this, we could have used one big table, but it's easier to read this way (IMO).

We replace the hardcoded data in our GUI body with our new listbox definition, again using a variable to make it easier to read.

We create a function, often called preshow(), which will be called for us as part of the drawing the GUI (see the new optional argument in [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] -- there's also an optional postshow(), but we don't need it here). This is where we pull the data from our example table into the listbox. We create a listbox variable associated with the listbox, identified by the listbox_id we assigned earlier, inside the dialog which gui.show_dialog() passes to preshow(). Then we iterate through our data table, using each entry from that table to populate a listbox item.

Let's look at that last action a little more closely using an example.

<syntaxhighlight lang=lua>
listbox[i].monster_image.label = monster.image
</syntaxhighlight>

Which we can read as "In listbox element i of our listbox, for the image with identifier monster_image which we defined in our listboxItem, use the data from the corresponding index i in our example data table" (you don't see the index i for the monsters table here, but remember we're iterating using ipairs, we could have just as easily used listbox[i].monster_image.label = monsters[i].image). If you were to step through all of the variable substitutions, you'd see that for i=1, our dialogDefinition is basically the same thing as it was in the earlier examples, just supplied from a table instead of hardcoded (note that you can hardcode entries in a listbox in your dialog definition using the [list_data] tag, aka wml.tag.list_data, which we do not demonstrate here).

You will probably notice that our data does not line up nicely in the GUI. We will fix that later. We'll also demonstrate how the user can select an item in a listbox, and how you can identify which item that was using the selected_index variable of the listbox.

===Tree View===
====Simple Tree View====
{|
| You may have noticed that clicking on a listbox item in our listbox caused it to be highlighted with a box around the contents. This is because the items in a listbox are selectable. This will be useful when we want to add actions, but it looks a bit odd if we just want to present a list of data.

Also, most of the data had to be formatted the same for each item in the listbox. We could, perhaps, include custom markup in our labels, but the actual layout, like the number of columns per row, had to be the same for every item.

Another way to present a list of data is the tree view. Since a tree view supports multiple data types, we may need to create multiple definitions for the elements in our list. These are known as nodes. It will also be necessary to explicitly define which node to use for each element when we populate our tree view.
|-
| [[File:Basic tree view.png|center|thumb|Tree_views can hold multiple data types (only trolls have names here)]]
|}
<syntaxhighlight lang=lua line>
local function basic_tree_view()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", type = "Seamonsters" },
{ image = "units/monsters/yeti.png", label = "A yeti",
type = "Coolers" }
}

local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "trolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name",
linked_group = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
},
wml.tag.node {
id = "nottrolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "monster_name",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_image",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_label",
fixed_width = true
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_tv:add_item_of_type("trolls_node")
dialog.monsters_tv[i].monster_name.label = monster.name -- only trolls have a name
else
dialog.monsters_tv:add_item_of_type("nottrolls_node")
end
-- All of our monsters have an image and a label
dialog.monsters_tv[i].monster_image.label = monster.image
dialog.monsters_tv[i].monster_label.label = monster.label
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We have expanded our list of monsters to include three types of trolls. We have also given each troll a name. This is of course a rather simplistic example, we could have simply given each monster that is not a troll an empty name, but it as presented here our approach serves the purpose of demonstrating how we deal with multiple data types. Our new tree view contains a node for each type of data we will present. In preshow, we explicitly define each element in our list using add_item_of_type(), and populate the item accordingly. [Note: in our listbox example, we could have used add_item() to add items to the listbox, but chose not to since that section was already introducing a number of new concepts. But here, since we have multiple types of items we need to be able to specify the type of the item when we add one, hence we need to use add_item_of_type()].

You may also note the addition of a few linked_group lines. We'll cover linked groups in more detail later, but as used here they instruct the GUI that each column using the same node type needs to be aligned with the others. For example, all of our trolls line up nicely.

====Building a Tree====
{|
| colspan="2" |At this point, one may wonder about the name "tree view", since what he have seen doesn't look much like a tree. To make a tree-like structure, we'll demonstrate adding children to nodes. At the top level our (upside-down) tree will have two nodes, one for trolls and one for everything else. A toggle_button (a type of button which changes states when you push it) will allow us to expand the trolls node to expose its children, which are themselves nodes, though they only contain a label at this point.
|-
| [[File:Basic tree view2a.png|center|thumb|Tree_view with Trolls folded]] || [[File:Basic tree view2b.png|center|thumb|Tree_view with Trolls unfolded]]
|}
<syntaxhighlight lang=lua line>
local function building_a_tree()
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
}
},
wml.tag.column {
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Show me the " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
-- You can refer to an object by its position

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[1].race_label.label = "Trolls"
-- dialog.monsters_tv[1].race_button.on_modified =
-- function()dialog.monsters_tv[1].unfolded =
-- dialog.monsters_tv[1].race_button.selected end

-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][1].monster_type.label = "Whelp"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][2].monster_type.label = "Shaman"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][3].monster_type.label = "Troll"

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[2].race_label.label = "Other scary things"
-- dialog.monsters_tv[2].race_button.visible = "hidden"

-- ... or you can refer to that object using the return value
-- from add_item_of_type
local troll_node = dialog.monsters_tv:add_item_of_type("race_node")
troll_node.race_label.label = "Trolls"
troll_node.race_button.on_modified =
function()
troll_node.unfolded = troll_node.race_button.selected
end
local item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Whelp"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Shaman"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Troll"

local not_troll_node =
dialog.monsters_tv:add_item_of_type("race_node")
not_troll_node.race_label.label = "Other scary things"
not_troll_node.race_button.visible = "hidden"

end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We define two nodes in our tree, a race_node for the top level, and a details_node for the children of a race_node. The rest of the interesting bits are in preshow().

We demonstrate two different ways of creating and accessing items, the first (commented out) just using the order in which they are created, while in the second we capture the result of add_item_of_type() in a variable we can use to refer to the newly defined object. The first method is shown primarily to demonstrate the structure of the resulting objects. The second method is perhaps easier to follow, and is almost necessary when you start doing things like dynamically deleting nodes, so it is in most cases a better practice (of course, you probably won't want to use the same variable for each node like we did, and perhaps not one local to the preview function).

We add a node, label it "Trolls", and add a callback to the button such that the children of the node will be visible (the node is "unfolded", a boolean value which defaults to false) when the button is checked (selected == true). Then we add three "details_node" nodes as children of this node.

Our second node, "Other scary things" will remain empty for now, so we'll set the visible attribute on its button to "hidden" (which is like false, but with hidden the widget still takes up space).

{|
| This example is rather ugly, both in the hardwired code and the appearance of the resulting GUI, but it addresses a couple important aspects of how tree views work and how we might use them. Let's clean it up a bit. We'll add an indentation_step_size to the tree view, along with a spacer and [[#Alignment|horizontal_alignment]] to our details node, to make the labels line up nicely, and change the button [[#Definitions|definition]] to replace the checkbox with something that looks like it belongs there. We will look at methods for handling layout in more depth [[#Appearance|later]].
|-
| [[File:Basic tree view2c.png|center|thumb|Our tree_view with proper alignment]]

<syntaxhighlight lang=lua>
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
indentation_step_size = 20,
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
definition = "tree_view_node"
}
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.spacer { width = 40 }
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}

</syntaxhighlight>

===Multi_page===
====Simple Multi_page====
{|
|-
Like a tree_view, a multi_page is a heterogeneous container which is dynamically populated, however, while a multi_page contains multiple elements (pages), only one page is displayed at any one time. Its purpose is perhaps best described by a couple of examples.
|-
[[File:Basic multipage.png|center|thumb|Multi_page showing active page]]
|}
<syntaxhighlight lang=lua>
local function basic_multipage()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll",
name = _"Bob", type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp",
name = "Junior", type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman",
name = _"Alice", type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish",
type = "Seamonsters" },
{ image = "units/monsters/yeti.png",
label = "A yeti",
type = "Coolers" }
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
multi_page
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}

local function preshow(dialog) -- Prepare the GUI before display
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_label.label = monster.label
end
--dialog.monsters_mp.selected_index = 5
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

As you can see, the code for our basic multi_page GUI looks a lot like our basic tree_view GUI. The difference is what is displayed. While both the tree_view and the multi_page containers contain five items, with the multi_page, only the first one is displayed. More specifically, only the page associated with the selected_index attribute of the multi_page object, which defaults to 1, is displayed. If we were to uncomment the last line in preshow(), we would still see only one item, but it would be the fifth one we allocated. It's nice to know all our pages are in there somewhere, but this example is pretty useless. What we need is a way to select which page we want to see from within our GUI.

====A More Useful Multi_page====

{|
| colspan="2" | To demonstrate the usefulness of a multi_page, and highlight its difference from a tree_view, we'll add a listbox to allow us to select the page to view. We'll also need to add a little action to our GUI.
|-
| style="align:centered" |[[File:More useful multipage.png|center|thumb|User selected Troll]] || [[File:More useful multipage2.png|center|thumb|User selected Cuttlefish]]
|}

<syntaxhighlight lang=lua>
local function more_useful_multi_page()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
race = "Trolls", tip = "Your uncle" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
race = "Trolls", tip = "Your nephew" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
race = "Trolls", tip = "Your auntie" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", race = "Seamonsters",
tip = "Not a fish" },
{ image = "units/monsters/yeti.png",
label = "A yeti", race = "Coolers",
tip = "ROAR!" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
}
}
}

local listboxDefinition = wml.tag.listbox {
id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
},
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
listboxDefinition
},
wml.tag.column {
wml.tag.spacer {
width = 30
}
},
wml.tag.column {
multi_page
},
}
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_image.tooltip = monster.tip
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_image.tooltip = monster.tip
dialog.monsters_mp[i].monster_label.label = monster.label
end
local function switch_page()
dialog.monsters_mp.selected_index = listbox.selected_index
end
listbox.on_modified = switch_page
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

Most of this should look pretty familiar. We've simply taken the previous example and added a second column to our GUI using code from an earlier example to add a listbox. In addition, we altered the page layout slightly, and added a spacer column in the dialog definition to approve the appearance.

The interesting stuff is in preshow(). Again we've merged in some listbox code from an earlier example, but we've also created a new local function switch_page(), which simply sets the selected_index attribute of our multi_page to the same as that of our listbox, and then we've configured the listbox.on_modified callback to call switch_page(). Now when the user selects an item in the listbox (updating listbox.selected_index and triggering listbox.on_modified), dialog.monsters_mp.selected_index is updated accordingly and therefore the visible page changes to the one associated with the selected unit.

Also note in preshow() we've added a new child to our monster_image identifier for both the listbox and the multi_page, a tooltip. When the user hovers the mouse over the image of one of our monsters, they'll see a popup message which we've added to our monster table. Try changing '''wml.tag.tooltip { id = "tooltip_large" }''' to '''wml.tag.tooltip { id = "tooltip }''' in the dialogDefinition to see a different tooltip style.

==Actions Have Consequences==

So far, our GUIs have only displayed some information on the screen, but at some point we're probably going to want to use a GUI to get input from the user. In this section we will look at return values that can be assigned to a widget based upon its state, and callbacks, which are functions invoked when something happens with a widget. As we will see, a button is a good example, as it can return a value or take an action, or both, when pressed. Earlier we saw how the selected_index attribute of some widgets, such as the listbox, can also be used as a sort of return value.

===Buttons===
{|
| colspan=2 | In this example, we'll create a couple buttons which provide the user a choice, use a handy confirmation popup to confirm that choice, and demonstrate how we get the results back where we can put them to use.
|-
| [[File:Basic return value.png|center|thumb|There can be only one]] || [[File:Basic return value_confirm.png|center|thumb|The user selected Alice, let's confirm this critical choice]]
|}

<syntaxhighlight lang=lua>
local function basic_return_value()

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "leader_lg",
fixed_height = true,
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" ..
_"Which unit shall lead your army?" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Alice" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/elves-wood/sylph.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 1
}
}
},
}
},
wml.tag.column {
wml.tag.spacer { width = 20 }
},
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Bob" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/human-loyalists/marshal.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 2
}
}
}
}
}
}
}
}
}
}
}
local user_chose = gui.show_dialog(dialogDefinition)
local leader
if user_chose == -1 then -- User closed the dialog by hitting the Enter key
leader = nil
end
if user_chose == -2 then -- User closed the dialog by hitting the Escape key
leader = nil
end

if user_chose == 1 then
leader = "Alice"
end
if user_chose == 2 then
leader = "Bob"
end

local confirmed_leader_choice

if leader ~= nil then
local query = _"You want " .. leader .. _" as your leader?"
confirmed_leader_choice = gui.confirm(query)
end

if confirmed_leader_choice then
wesnoth.message("Great!")
else
wesnoth.message("Fine, lead them yourself!")
end
end
</syntaxhighlight>

Here we've added a couple buttons, and assigned each of them a return value. When the user selects one of these buttons, the GUI is closed and the value of return_value is returned from gui.show_dialog(). We then use [https://wiki.wesnoth.org/LuaAPI/gui#gui.show_prompt gui.confirm()] which provides a very simple Yes/No popup and returns true or false, respectively. Other useful functions can be found on that page which provide handy alternatives to creating your own GUI for other simple user inputs.

The use of return_value is rather limited, as it only returns integers and can't be used with containers like listboxes. In more complex cases we'll need to turn to callback functions which are invoked when something happens to a widget, like clicking a button or a widget's value changing. Earlier, we saw an example of [[LuaAPI/types/widget#on_modified|widget.on_modified()]]. More examples of callbacks can be found at [[LuaAPI/types/widget#on_modified|that link]].

===Slider and Textbox===
{|
| Here we see a couple methods of getting more dynamic input from the user, a slider and a textbox presented in one silly example.
|-
| [[File:Slider and textbox.png|center|thumb|Two ways of getting input from the user]]
|}

<syntaxhighlight lang=lua>
function slider_and_textbox()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = _"How much gold will you pay for this old rusty sword?"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.slider {
id = "gold_sl",
minimum_value = 0,
maximum_value =
wesnoth.sides[wesnoth.current.side].gold,
value = math.floor(
wesnoth.sides[wesnoth.current.side].gold/2)
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.text_box {
id = "gold_tb",
--hint_text = _ "Enter gold here",
--hint_image = "images/gold_pile.png",
label = tostring(math.floor(
wesnoth.sides[wesnoth.current.side].gold/2))
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
local function show_input()
wesnoth.interface.add_chat_message(_"You chose " ..
dialog.gold_sl.value .. _" with the slider")
wesnoth.interface.add_chat_message(_"You entered " ..
tostring(dialog.gold_tb.text) .. _" in the text_box")
end
-- this is a button, so we use on_button_click, not on_left_click
dialog.ok.on_button_click = show_input

dialog.gold_sl.on_modified = function()
dialog.gold_tb.text = tostring(dialog.gold_sl.value)
end
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We create a slider, with a range from 0 to the amount of gold possessed by the current side and an initial value in the middle, and a text box with the same initial value. We assign a function to our OK button which simply reports on the values provided by the user. For no reason whatsoever, we add a callback such that when the user adjusts the slider the value in the textbox is update to match the slider.

Note that the textbox returns text, even though it looks like we're expecting the user to input a natural number. Remember to validate those inputs.

You can use text_hint to place a caption in the box that will help the user understand what to enter in the box, and possibly an image as well. For example, in the search box in the recall menu uses '''hint_text = _ "Search", hint_image = "icons/action/zoomdefault_25.png~FL(horiz)"'''. Of course, you can't have a hint and a label in the same text_box at the same time, so in our example we've only included them as comments.

There is also a widget called a spinner, which is kind of like the combination of a text_box and a slider. As of the release of 1.18, it appears to be unfinished so the strange syntax needed to make it work is probably not the best thing to document, and we will omit it for now.

==Appearance==

'''This section needs help'''

===Borders===

Borders allow you to force unused space around a column, for example so that your widgets don't runtogether. You can specify the border to be one or more of top, bottom, left, right, or all. The border_size sets the amount of padding, in pixels.

<syntaxhighlight lang=lua>
wml.tag.column{
border = "left, right"
border_size = 25
}
</syntaxhighlight>

===Alignment===
{|
| colspan=2 |By default, the GUI will usually center widgets in their cells, which is not always what we want. In this example, we use horizontal_alignment to move widgets around a little.

In more complex cases, it may be useful to add [[GUIWidgetDefinitionWML#Spacer|spacers]] to help force alignment, or use linked_groups to force consistent alignment for objects within a grid.
|-
| [[File:Gui tutorial alignment without.png|center|thumb|Default alignment]] ||[[File:Gui tutorial alignment with.png|center|thumb|Showing off some alignment options]]
|}
<syntaxhighlight lang=lua>
local function basic_alignment()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = "Ralph"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "right",
wml.tag.label {
label = "Sam"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/troll-hero-attack-se-4.png" -- 122x102
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "left",
wml.tag.label {
label = "Jr"
}
},
wml.tag.column {
horizontal_alignment = "right",
wml.tag.image {
label = "units/trolls/whelp.png" -- 72x72
}
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

The screenshots show the output of this example with and without the horizontal_alignment lines included above.

A label allows you to set the text_alignment field (e.g. text_alignment = "left"). Note, however, this only aligns the text within the label. The label itself will probably be centered in the column, giving the false appearance that your text alignment is not working.

===Growth===

To keep your dialog nicely balanced, the GUI2 engine may need to grow rows and/or columns. You can control which columns, for example, grow and which do not, by setting some with grow_factor = 1, and others with grow_factor = 0 (do not grow). While grow factors of 0 and 1 are the most common, you can use other values to adjust the relative growth if you really need to, see [[GUILayout]] for the gory details.

It it sometimes useful to include a column with a [spacer] and a grow_factor (often the only column with grow_factor != 0) whose sole purpose is to keep your GUI aligned nicely as the layout engine does its evil.

To force a column to stretch to fit available space, use horizontal_grow = true. Note that horizontal_grow is not compatible with horizontal_alignment. There is also a vertical_grow parameter.

If you need to see every little detail about the layout process, start wesnoth with --log-debug=gui/layout. Good luck with that.

===Definitions===
Many widgets can be configured to have to a different appearance, for example in our tree_view example we changed the definition of a toggle_button from the default of a checkbox by setting definition = "tree_view_node". This option was found by looking at the id of a toggle_button_definition in .../data/gui/widget/toggle_button_tree_view_node.cfg:

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib
###
### Definition of a toggle button to be used in a tree view as node fold/unfold indicator
###
[toggle_button_definition]
id = "tree_view_node" # <--- we can use 'definition = "tree_view_node"' in a [toggle_button] to select this definition
description = "Fold/unfold status indicator of a tree view node."
</syntaxhighlight>

{|
|There are many other definitions for buttons and other widget types in that directory. It would be nice to have a list (linked here), but for now you'll just have to look around.

We can even create our own custom definitions using [[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition()]]. In this example, we copy from .../data/gui/widget/toggle_button_tree_view_node.cfg with a slight change so that our button turns red ( '''~BLEND(255,0,0,1)''' ) when focused.

In this example, we will use wesnoth.wml_actions to create the WML tag [add_widget_def_demo].

Note the first line, a common convention for creating an alias for wml.tag.
|-
|[[File:Gui tutorial custom widget.png|center|thumb|Different definition of buttons, including one of our own (right)]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag -- save ourselves some typing
function wesnoth.wml_actions.add_widget_def_demo()
local definition = {
id = "tree_view_node_custom",
description = "Fold/unfold status indicator of a tree view node (MODIFIED).",
T.resolution {
min_width = 25,
min_height = 19,
default_width = 25,
default_height = 19,
max_width = 25,
max_height = 19,
-- Unselected - note there's no tags for unselected/selected, that's simply determined by the order
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/fold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/fold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/fold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
-- Selected
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/unfold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
}
}
gui.add_widget_definition("toggle_button", "tree_view_node_custom", definition)

local dialogDefinition = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid {
T.row {
T.column {
T.toggle_button {
definition = "default"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node_custom"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end

</syntaxhighlight>

See [[GUIWidgetDefinitionWML]] for more details on widget definitions.

You can also give the whole dialog a definition, like definition = "tooltip_large". There is no gui.add_window_definition(), however a window is technically a type of widget so it may be possible to create your own window definitions (please update this if you do).

===Panels===

===Canvases===
Part of panels? Sort of?

A canvas is a surface you can draw on. A dialog has them, as does a panel, and for these canvas 1 refers to the background, while canvas 2 refers to the foreground. Other widgets may have canvases that may have other meanings, or no canvases at all. See more at [[LuaAPI/gui/widget#set_canvas]].

Here's a fun little trick. Set your dialog background to be transparent:
<syntaxhighlight lang=lua>
local function preshow(dialog)
dialog:set_canvas(1, { } )
end
</syntaxhighlight>

Or, if you want an opaque GUI background with the screen behind it blurred like what you see behind the text of a [message], you can set your window definition to "message":
<syntaxhighlight lang=lua>
...
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
definition = "message",
...
</syntaxhighlight>

{|
|Here we take our [[#Progress Bar|progress bar]], and add a text overlay.

Note: either using text on a canvas is rather limited, or I just couldn't figure it out. For example, I could not get the text size any smaller, and any attempts to do so simply resulted in very blocky text. And the spaces were necessary so that the text wasn't stretched out. I also find it surprising that the progress bar does not have this feature inherently. So it's not a great example, but it should be enough to get you started using canvases. Be sure to visit the [[LuaAPI/gui/widget#set_canvas|link]] mentioned above for more options.
|-
|[[File:Gui tutorial canvas text.png|center|thumb|A progress bar in the background, with text in the foreground]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar_with_overlay()
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.grid {
T.row {
T.column {
T.panel { id = "panel",
T.grid {
T.row {
T.column {
T.button { id = "button",
label =_ "Press me"}
},
T.column {
T.progress_bar { id = "progress" }
},
T.column {
T.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
dialog.panel:set_canvas(2, { T.text { text_alignment = "center", font_size = 48,
text_markup = true, text = " " ..
dialog.progress.percentage .. "% " } } )
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

You may notice we added a panel and placed our text on the foreground canvas(2) on it, since the progress_bar itself does not support canvases.

===Placement===

You may have noticed that all of our dialogs are centered on the screen. This is the default. You can override this and place the dialog wherever you like by setting automatic_placement = false, along with x, y, width, and height at the top level of your dialog definition (next to tooltip =, etc).

'''This part about placement needs review'''
If you prefer, you may replace x and/or y with horizontal_placement and vertical_placement, such as horizontal_placement = "left". You can even set the placement values using WFL, for example horizontal_placement = "(gamemap_width / 3)" -- see [[#Using WFL with GUI2|Using WFL with GUI2]].

==Miscellaneous==

TODO: This stuff doesn't belong in a tutorial. It's worth documenting, but not here. Better to save these here for now than keep them on my laptop.

===Progress Bar===
{|
|A progress_bar is a graphical representation of a percent. In this example, we present the user with a puzzle. They must hit the button repeatedly before they can close the GUI. A progress_bar displays their current progress toward completion.
|-
|[[File:Gui tutorial progress bar.png|center|thumb|upright=2]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.button { id = "button",
label =_ "Press me"
}
},
wml.tag.column {
wml.tag.progress_bar { id = "progress" }
},
wml.tag.column {
wml.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end

gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

===Unit Preview Pane===

{|
|A unit_preview_pane takes a unit (or a unit type), and presents a graphical representation of the unit and its more important attributes, along with tooltips for additional details, in the same way that the recall menu does. Here we see an example of a unit which has picked up some items, including a weapon, which are affecting its stats.
|-
|[[File:Gui tutorial unit preview pane.png|center|thumb]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag

function wesnoth.wml_actions.recall_from_variable(cfg)
local from_array = cfg.from or wml.error(
"[recall_from_variable]: missing required from= ")
local to_var = cfg.to or wml.error(
"[recall_from_variable]: missing required to= ")
local unit_list = wml.array_access.get(from_array) or wml.error(
string.format("[recall_from_variable]: failed to fetch wml array %s",from_array))

local listboxItem = T.grid {
T.row {
T.column {
T.label { id = "available_unit",
linked_group = "available_unit"
}
}
}
}

local listbox_id = "available_units"
local listboxDefinition = T.listbox { id = listbox_id,
T.list_definition {
T.row {
T.column {
T.toggle_panel { listboxItem }
}
}
}
}
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.linked_group { id = "available_unit", fixed_width = true },
T.grid {
T.row { -- header
T.column {
T.grid {
T.row {
T.column {
border = "bottom",
border_size = 10,
T.label {
use_markup = true,
label = ""
.. _"Select unit to recall" .. ""
}
}
}
}
}
},
T.row { -- Body
T.column {
T.grid {
T.row {
T.column {
border = "right",
border_size = 40,
listboxDefinition
},
T.column {
T.unit_preview_pane { id = "unit_preview" }
}
}
}
}
},
T.row { -- Footer
T.column {
T.grid {
T.row {
T.column {
T.spacer { width = 400 }
},
T.column {
border = "top,right",
border_size = 10,
T.button { id = "ok",
label = _"OK"
}
}
}
}
}
}
}
}

local picked = 1

local function preshow(dialog)
local listbox = dialog[listbox_id]
for i,unit in ipairs(unit_list) do
listbox[i].available_unit.label = unit.name .. "(" ..
unit.language_name .. ")"
end
local function draw_unit()
wesnoth.units.to_recall(unit_list[listbox.selected_index])
local tmp = wesnoth.units.find_on_recall{ id =
unit_list[listbox.selected_index].id }[1]
dialog.unit_preview.unit = tmp
wesnoth.units.extract(tmp)
picked = listbox.selected_index
end
draw_unit()
listbox.on_modified = draw_unit
end

gui.show_dialog(dialogDefinition,preshow)

wml.variables[to_var] = picked - 1
end

</syntaxhighlight>

This should all be pretty self evident by now. We are provided with an array of stored units (from [store_unit] in WML). We create a listbox populated with units and we use the selected_index to determine which element in the table to send to unit_preview_pane. Since our input is an array of unit data, not actual units, we use [[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] to take the definition of one from our array and place it on the recall list (turning it into an actual unit), [[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] to fetch that unit in a form that the unit_preview_panel understands, and finally [[wesnoth.units.extract|wesnoth.units.extract]] to remove the unit from the recall list when we are done with it.

And of course we subtract one from the selected_index when we return our choice to WML, since lua arrays count from 1 and WML from 0.

The unit_preview_pane will also accept a unit_type instead of a specific unit.

==Appendix==

===Explore Your Options===

We've seen a lot of options that can be set to modify the behaviour of our dialogs, some on columns, some on widgets, etc. These are in the process of being documented [[GUIWidgetInstanceWML|here]], but if you would like to go straight to the source, the data Wesnoth uses to validate your configuration can be found in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui data/schema/gui] under your install directory.

Let's look at a scroll_label, for example. A scroll_label is a widget, so we look in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/widget_instances.cfg widget_instances.cfg] and find the following. Here we can see five parameters we can provide to our scroll_label (in addition to the ones available to all widgets, like id and definition, see the entry super=... which refers you to the widget_instance in the file [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/generic.cfg data/schema/gui/generic.cfg]), along with their types and default values. For example, we could set "link_aware = true", and if we do not we can assume that link_aware will be false. While this does not explain what these parameters do, the information provided in the schema directory is often helpful nonetheless.

<syntaxhighlight lang=wml>
[tag]
name="scroll_label"
min="0"
max="infinite"
super="$generic/widget_instance"
{DEFAULT_KEY "horizontal_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "vertical_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "wrap" bool true}
{DEFAULT_KEY "text_alignment" f_h_align "left"}
{DEFAULT_KEY "link_aware" bool false}
[/tag]
</syntaxhighlight>

We see that our scrollbars are of type scrollbar_mode. It would probably help if we knew what values are available to the scrollbar_mode. In [https://github.com/wesnoth/wesnoth/tree/master/data/schema/types/gui.cfg data/schema/types/gui.cfg] we find this:

<syntaxhighlight lang=wml>
[type]
name=scrollbar_mode
value="always|never|auto|initial_auto"
[/type]
</syntaxhighlight>

The variable types found in the schema files are described at [[GUIVariable]].

Note: The keys in the schema file correspond to the attributes used when configuring your widgets. They will not always align perfectly with keys used by the Lua API. For example, the slider uses maximum_value in its configuration, and max_value when using the Lua API:

<syntaxhighlight lang=wml>
[slider]
id="my_slider"
maximum_value = 100
[/slider]
</syntaxhighlight>

<syntaxhighlight lang=lua>
dialog.my_slider.max_value = 90
</syntaxhighlight>

===Using WFL with GUI2===

If you look at the variable type descriptions at [[GUIVariable]] you may notice that many of them start with "f_" and have "or formula" in the description. This means that you can use [[Wesnoth_Formula_Language|Wesnoth Formula Language (WFL)]] formulas in these fields, with certain variables made available to you (which variables and what they mean can be challenging to ascertain, but you can generally figure it out by example).

Looking at [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/window.cfg data/schema/gui/window.cfg] we see that 'height' has type f_unsigned, which tells us that height is an unsigned integer, and that we can use a WFL formula to define it in a window_definition. In [https://github.com/wesnoth/wesnoth/tree/master/data/gui/themes/default/window/wml_message.cfg data/gui/window/wml_message.cfg] (data/gui/themes/default/window/wml_message.cfg starting around 1.19.2), we find the line '''height = "(screen_height - 30)"'''. This does exactly what it looks like, it sets the height of our window to 30 pixels less than the height of the screen.

===Useful Links===
[[GUIToolkitWML]] - Documents the keys/values available on various objects (e.g. "what attributes can I set on a column?") 
[[LuaAPI/gui|LuaAPI/gui]] - Mostly about opening windows 
[[LuaAPI/types/widget]] - Widget attributes and callbacks 
[https://wiki.wesnoth.org/Category:GUI_WML_Reference GUI_WML_Reference] 
[https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui .../data/schema/gui/*.cfg] - Lists of valid options for various GUI objects 
[https://devdocs.wesnoth.org/layout_algorithm.html Layout Algorithm] - For windows, at least

===Credits===

The basic framework that composes the initial examples was lifted from LotI. It's a great place to find well written examples, but some of it is complex enough to be a little overwhelming when getting started.

Many examples, particularly tree view and multipage, are heavily derived from the World Conquest multiplayer campaign.

Sandbox/GUI/Getting Started

2024-11-01T20:46:33Z

White haired uncle: /* And a bit more */

So, it looks like I can't exclude this page/section from the search engine as I had hoped. I wanted to put this in a sandbox so that it wouldn't be published without some proper review.

==Introduction==

This guide is designed to help you get a simple Wesnoth GUI, implemented in lua, up and running while describing the basic building blocks along the way. It is written in a narrative format, where most examples build on previous examples, and therefore while not always necessary it may be desirable to read from start to finish. The reader, probably a UMC author, should have a basic knowledge of working with lua within Wesnoth.

Some would find creating a GUI in part or in full using WML simpler to follow, and those alternatives are available, for example [[LuaAPI/gui/example]], but we're using lua here. If you find WML easier to follow, you can always convert the lua tables that define the GUIs to WML using [[LuaAPI/wml#wml.tostring|wml.tostring]], for example:

<syntaxhighlight lang=lua>
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
</syntaxhighlight>

In some examples, instead of defining the entire GUI at once, we'll break out some parts into separate variables. If you try to view one in WML and get an error from wml.tostring() about expecting a WML table and not a table, try passing your variable(/table) inside a table:

<syntaxhighlight lang=lua>
print(wml.tostring({listboxItem}))
gui.show_lua_console()
</syntaxhighlight>

One distinct advantage of using WML to define your GUI layout is that you get better (any) validation. Invalid keys, and sometimes values, are often flagged in the log, unlike with lua where they are silently ignored. In the comments of our first GUI, below, is an example which loads a WML GUI configuration using [[LuaAPI/wml#wml.load|wml.load()]], validating against the GUI2 window schema.

===What is GUI2?===
Once upon a time, Wesnoth had a GUI system which is now commonly referred to as GUI1. As of 1.19, GUI1 has been almost completely replaced by GUI2. UMC authors will probably never encounter GUI1 and can simply use the terms GUI and GUI2 interchangeably, at least until GUI3 comes along.

Instead of spending a lot of time here giving an overview of what GUI2 is and what makes it great, and not so great, let's charge ahead so we can see it in action, and let readers who are interested look elsewhere(TODO: link) for a more formal definition. (TODO: is this the right approach for most readers?).

==Getting Started==

For example purposes, we'll create a directory in our campaign directory called lua containing a file called gui_tutorial.lua, and add a command in the prestart event for a scenario which will create a right-click menu option to invoke our new GUI. Of course there are other methods to invoke lua from WML, but this one will get us started. After all, we really just want to get something up on the screen ASAP, right?

===A most basic GUI===

{|
|[[File:Most basic gui.png|center|thumb|I can't believe this worked]]
|-
|In our prestart event, we create a simple menu item, which executes a single line of lua which calls the lua function most_basic_gui() which is found in gui_tutorial.lua:
|}

<syntaxhighlight lang=wml>
[set_menu_item]
id=most_basic_gui
description="Our first GUI"
[command]
[lua]
code=<<
wesnoth.require("~add-ons/<OUR_CAMPAIGN>/lua/gui_tutorial.lua").most_basic_gui()
>>
[/lua]
[/command]
[/set_menu_item]
</syntaxhighlight>

And create gui_tutorial.lua:
{| class="wikitable" style="margin:auto"
! !! The WML equivalent of dialogDefinition
|-
|
<syntaxhighlight lang=lua>
local function most_basic_gui()
local dialogDefinition = {
--click_dismiss = true, -- allow user to close dialog with click of a button
wml.tag.tooltip { id = "tooltip_large" }, -- required
wml.tag.helptip { id = "tooltip_large" }, -- required
wml.tag.grid { -- our most basic gui
wml.tag.row { -- a grid must include at least one row
wml.tag.column { -- a row needs a column
wml.tag.image { -- a column includes exactly one widget
label = "units/trolls/grunt.png"
}
}
}
}
}

local function preshow(dialog)
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
end
gui.show_dialog(dialogDefinition,preshow)

-- Or, if you want to define the gui in WML, something like:
-- local dialog_wml = wml.load("~add-ons/GUI_Tutorial/most_basic_gui.cfg",
-- true, "schema/gui_window.cfg")
-- gui.show_dialog(wml.get_child(dialog_wml, 'resolution'))
end
return { most_basic_gui = most_basic_gui}
</syntaxhighlight>
|
<syntaxhighlight lang=wml>
[tooltip]
id="tooltip_large"
[/tooltip]
[helptip]
id="tooltip_large"
[/helptip]
[grid]
[row]
[column]
[image]
label="units/trolls/grunt.png"
[/image]
[/column]
[/row]
[/grid]

</syntaxhighlight>
|}

In the above file, we have just the single function to create our GUI, followed by a return command which makes our function most_basic_gui() available to the [[LuaAPI/wesnoth#wesnoth.require|wesnoth.require()]] function as most_basic_gui().

Our function creates a table containing the definition of a "dialog", and then passes that to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]]. It should be noted that gui.show_dialog does not provide synchronization, so if your GUI makes changes to the game state, you'll need to jump through some hoops or you'll break replays and multiplayer, but that's not something we need to care about at this point, so just be aware that you may need to deal with it in the future.

Our dialog definition at this point includes three parts. The first two are a tooltip and a helptip, which are required and define how tooltips (use id = "tooltip_large" or id = "tooltip" or id = "tooltip_transparent"), and helptips (rarely used, but must be included here, and yes their definitions are "tooltip" not "helptip") will look (as we will see later, this really should be definition = "tooltip", but in this case it's id = "tooltip"). The third part is a grid, which is basically a table, like in HTML or MySQL, with rows and columns. A grid always contains at least one row. A row contains at least one column (note that a column does NOT span rows, it is completely contained within a row). Inside a column is exactly one item, a cell which contains a [[GUIWidgetDefinitionWML|widget]], in this case we'll use an image (later we'll see what else we can put in a cell). Note that we don't actually define a cell in our code, it's just a term used to refer to the contents of a column.

The preshow function is optional. If included in the call to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]], it is run before the GUI is displayed. In this case, we include it to display the dialog we created with lua in WML format. Near the end, in comments, we show how you would call [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] if you chose to define your dialog using WML. Note that what is shown here is the WML equivalent of our lua dialogDefinition, and not the complete WML you would need to use if you were to configure your GUI layout in WML.

Note: if you should try out the above, you'll have to hit escape or enter to close the GUI. Uncomment the "click_dismiss" line, and the user will be able to close the GUI with a mouse click.

===Adding a little flavor===

{|
|You may have noticed our GUI is missing a header and a way to close it when we're done admiring our work. Here we add a new first row to our grid, while demonstrating a couple formatting options: a border to put some distance between our grid cell and its neighbor, and the "use_markup = true" option to enable Pango support in our text.

Our third row adds an OK button at the bottom. You can associate actions with buttons to do all kinds of things, but here we just exploit the default behaviour to close the GUI.

Of course, we'll also have to modify our return to support the new function, and update our menu item(s) accordingly.
|-
|[[File:Most basic gui2.png|center|thumb|Adding header and a footer]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui2()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
gui.show_dialog(dialogDefinition)
end
return { most_basic_gui = most_basic_gui, most_basic_gui2 = most_basic_gui2 }
</syntaxhighlight>

===And a bit more===
{|

|And now a minor, but important change. We want to add a new text field next to the image in the body of our GUI. Obviously, we want to add a new column, but this is more difficult than when we added new rows in the previous example. The problem is that all rows (at a given level) in a grid must contain the same number of columns. We can't have two columns in the row that constitutes the body of our GUI, but only one in the header and one in the footer. To solve this problem, we replace our image widget with a new grid, which can use as many columns as we like (as long as they are the same within each row of our new grid). This new grid contains a row with two columns, but that is okay because the new grid itself is placed in a single column, which matches our single column header and footer (ok button), keeping the rows balanced.
|-
|[[File:Most basic gui3.png|center|thumb|Rows with different numbers of columns]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui3()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column { -- This is the only column in this row,
-- to match the number of columns in
-- the rows of our header and footer
wml.tag.grid { -- A new grid, so we can use a different
-- number of columns
wml.tag.row {
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
},
wml.tag.column {
wml.tag.label {
label = "A troll"
}
}
}
}
}
},
wml.tag.row { -- A footer
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = "Ok"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

While we see here just the simplest of examples, you can create many levels of grids inside grids, rows with multiple columns some of which containing grids, etc, to build complicated dialogs to your liking.

==Containers==

===Stacked Widget===

TODO

===Listbox===
{|
| Now we'd like to add some more monsters. Obviously, we could just add more rows, but what if we won't know until runtime how many and which ones? We could break up the definition of our dialog and add new rows dynamically, it's just a table after all, but fortunately we have a widget which handles this for us, a listbox. A listbox is kind of like an array, a collection of similar objects where the number of items can vary. We will tell the GUI where we want the box, and what each entry in the box will look like, and then at runtime we can add entries to the box.

Note that listbox items are added from top to bottom. Another container, the horizontal_listbox, works just like a listbox except the items are added from left to right. With a grid listbox, items are added horizontally with the list wrapping to a new line as necessary.
|-
| [[File:Gui with listbox.png|center|thumb|Listbox with three items. Each item is an image and a label. The third item has been selected.]]

<syntaxhighlight lang=lua>
local function gui_with_listbox()
local monsters = {
{ image = "units/trolls/grunt.png",
string = "A troll" },
{ image = "units/monsters/cuttlefish.png",
string = "A cuttlefish" },
{ image = "units/monsters/yeti.png",
string = "A yeti" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
}

local listboxDefinition = wml.tag.listbox { id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
listboxDefinition
}
},
wml.tag.row {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_label.label = monster.string
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We begin by creating a simple table which represents the data which will be presented in our listbox. In most cases, we probably wouldn't create that monster table here, but we need it for our example.

The variable listbox_id gives us an identifier for our listbox so we can reference it when we need to. We don't really need to use a variable here, it's just convenient.

We define the structure for the elements in our listbox, stored in listboxItem. Note that we've replaced the actual data with identifiers (e.g. 'units/trolls/grunt.png' becomes 'id = "monster_image"), since each element may have different data.

We define the listbox itself, specifying the identifier, and the definition of our listbox element (which looks a lot like a grid). The cell inside the column contains a variable which is just the listbox element definition we created above; it's not necessary to do this, we could have used one big table, but it's easier to read this way (IMO).

We replace the hardcoded data in our GUI body with our new listbox definition, again using a variable to make it easier to read.

We create a function, often called preshow(), which will be called for us as part of the drawing the GUI (see the new optional argument in [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] -- there's also an optional postshow(), but we don't need it here). This is where we pull the data from our example table into the listbox. We create a listbox variable associated with the listbox, identified by the listbox_id we assigned earlier, inside the dialog which gui.show_dialog() passes to preshow(). Then we iterate through our data table, using each entry from that table to populate a listbox item.

Let's look at that last action a little more closely using an example.

<syntaxhighlight lang=lua>
listbox[i].monster_image.label = monster.image
</syntaxhighlight>

Which we can read as "In listbox element i of our listbox, for the image with identifier monster_image which we defined in our listboxItem, use the data from the corresponding index i in our example data table" (you don't see the index i for the monsters table here, but remember we're iterating using ipairs, we could have just as easily used listbox[i].monster_image.label = monsters[i].image). If you were to step through all of the variable substitutions, you'd see that for i=1, our dialogDefinition is basically the same thing as it was in the earlier examples, just supplied from a table instead of hardcoded (note that you can hardcode entries in a listbox in your dialog definition using the [list_data] tag, aka wml.tag.list_data, which we do not demonstrate here).

You will probably notice that our data does not line up nicely in the GUI. We will fix that later. We'll also demonstrate how the user can select an item in a listbox, and how you can identify which item that was using the selected_index variable of the listbox.

===Tree View===
====Simple Tree View====
{|
| You may have noticed that clicking on a listbox item in our listbox caused it to be highlighted with a box around the contents. This is because the items in a listbox are selectable. This will be useful when we want to add actions, but it looks a bit odd if we just want to present a list of data.

Also, most of the data had to be formatted the same for each item in the listbox. We could, perhaps, include custom markup in our labels, but the actual layout, like the number of columns per row, had to be the same for every item.

Another way to present a list of data is the tree view. Since a tree view supports multiple data types, we may need to create multiple definitions for the elements in our list. These are known as nodes. It will also be necessary to explicitly define which node to use for each element when we populate our tree view.
|-
| [[File:Basic tree view.png|center|thumb|Tree_views can hold multiple data types (only trolls have names here)]]
|}
<syntaxhighlight lang=lua line>
local function basic_tree_view()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", type = "Seamonsters" },
{ image = "units/monsters/yeti.png", label = "A yeti",
type = "Coolers" }
}

local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "trolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name",
linked_group = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
},
wml.tag.node {
id = "nottrolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "monster_name",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_image",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_label",
fixed_width = true
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_tv:add_item_of_type("trolls_node")
dialog.monsters_tv[i].monster_name.label = monster.name -- only trolls have a name
else
dialog.monsters_tv:add_item_of_type("nottrolls_node")
end
-- All of our monsters have an image and a label
dialog.monsters_tv[i].monster_image.label = monster.image
dialog.monsters_tv[i].monster_label.label = monster.label
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We have expanded our list of monsters to include three types of trolls. We have also given each troll a name. This is of course a rather simplistic example, we could have simply given each monster that is not a troll an empty name, but it as presented here our approach serves the purpose of demonstrating how we deal with multiple data types. Our new tree view contains a node for each type of data we will present. In preshow, we explicitly define each element in our list using add_item_of_type(), and populate the item accordingly. [Note: in our listbox example, we could have used add_item() to add items to the listbox, but chose not to since that section was already introducing a number of new concepts. But here, since we have multiple types of items we need to be able to specify the type of the item when we add one, hence we need to use add_item_of_type()].

You may also note the addition of a few linked_group lines. We'll cover linked groups in more detail later, but as used here they instruct the GUI that each column using the same node type needs to be aligned with the others. For example, all of our trolls line up nicely.

====Building a Tree====
{|
| colspan="2" |At this point, one may wonder about the name "tree view", since what he have seen doesn't look much like a tree. To make a tree-like structure, we'll demonstrate adding children to nodes. At the top level our (upside-down) tree will have two nodes, one for trolls and one for everything else. A toggle_button (a type of button which changes states when you push it) will allow us to expand the trolls node to expose its children, which are themselves nodes, though they only contain a label at this point.
|-
| [[File:Basic tree view2a.png|center|thumb|Tree_view with Trolls folded]] || [[File:Basic tree view2b.png|center|thumb|Tree_view with Trolls unfolded]]
|}
<syntaxhighlight lang=lua line>
local function building_a_tree()
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
}
},
wml.tag.column {
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Show me the " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
-- You can refer to an object by its position

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[1].race_label.label = "Trolls"
-- dialog.monsters_tv[1].race_button.on_modified =
-- function()dialog.monsters_tv[1].unfolded =
-- dialog.monsters_tv[1].race_button.selected end

-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][1].monster_type.label = "Whelp"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][2].monster_type.label = "Shaman"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][3].monster_type.label = "Troll"

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[2].race_label.label = "Other scary things"
-- dialog.monsters_tv[2].race_button.visible = "hidden"

-- ... or you can refer to that object using the return value
-- from add_item_of_type
local troll_node = dialog.monsters_tv:add_item_of_type("race_node")
troll_node.race_label.label = "Trolls"
troll_node.race_button.on_modified =
function()
troll_node.unfolded = troll_node.race_button.selected
end
local item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Whelp"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Shaman"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Troll"

local not_troll_node =
dialog.monsters_tv:add_item_of_type("race_node")
not_troll_node.race_label.label = "Other scary things"
not_troll_node.race_button.visible = "hidden"

end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We define two nodes in our tree, a race_node for the top level, and a details_node for the children of a race_node. The rest of the interesting bits are in preshow().

We demonstrate two different ways of creating and accessing items, the first (commented out) just using the order in which they are created, while in the second we capture the result of add_item_of_type() in a variable we can use to refer to the newly defined object. The first method is shown primarily to demonstrate the structure of the resulting objects. The second method is perhaps easier to follow, and is almost necessary when you start doing things like dynamically deleting nodes, so it is in most cases a better practice (of course, you probably won't want to use the same variable for each node like we did, and perhaps not one local to the preview function).

We add a node, label it "Trolls", and add a callback to the button such that the children of the node will be visible (the node is "unfolded", a boolean value which defaults to false) when the button is checked (selected == true). Then we add three "details_node" nodes as children of this node.

Our second node, "Other scary things" will remain empty for now, so we'll set the visible attribute on its button to "hidden" (which is like false, but with hidden the widget still takes up space).

{|
| This example is rather ugly, both in the hardwired code and the appearance of the resulting GUI, but it addresses a couple important aspects of how tree views work and how we might use them. Let's clean it up a bit. We'll add an indentation_step_size to the tree view, along with a spacer and [[#Alignment|horizontal_alignment]] to our details node, to make the labels line up nicely, and change the button [[#Definitions|definition]] to replace the checkbox with something that looks like it belongs there. We will look at methods for handling layout in more depth [[#Appearance|later]].
|-
| [[File:Basic tree view2c.png|center|thumb|Our tree_view with proper alignment]]

<syntaxhighlight lang=lua>
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
indentation_step_size = 20,
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
definition = "tree_view_node"
}
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.spacer { width = 40 }
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}

</syntaxhighlight>

===Multi_page===
====Simple Multi_page====
{|
|-
Like a tree_view, a multi_page is a heterogeneous container which is dynamically populated, however, while a multi_page contains multiple elements (pages), only one page is displayed at any one time. Its purpose is perhaps best described by a couple of examples.
|-
[[File:Basic multipage.png|center|thumb|Multi_page showing active page]]
|}
<syntaxhighlight lang=lua>
local function basic_multipage()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll",
name = _"Bob", type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp",
name = "Junior", type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman",
name = _"Alice", type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish",
type = "Seamonsters" },
{ image = "units/monsters/yeti.png",
label = "A yeti",
type = "Coolers" }
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
multi_page
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}

local function preshow(dialog) -- Prepare the GUI before display
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_label.label = monster.label
end
--dialog.monsters_mp.selected_index = 5
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

As you can see, the code for our basic multi_page GUI looks a lot like our basic tree_view GUI. The difference is what is displayed. While both the tree_view and the multi_page containers contain five items, with the multi_page, only the first one is displayed. More specifically, only the page associated with the selected_index attribute of the multi_page object, which defaults to 1, is displayed. If we were to uncomment the last line in preshow(), we would still see only one item, but it would be the fifth one we allocated. It's nice to know all our pages are in there somewhere, but this example is pretty useless. What we need is a way to select which page we want to see from within our GUI.

====A More Useful Multi_page====

{|
| colspan="2" | To demonstrate the usefulness of a multi_page, and highlight its difference from a tree_view, we'll add a listbox to allow us to select the page to view. We'll also need to add a little action to our GUI.
|-
| style="align:centered" |[[File:More useful multipage.png|center|thumb|User selected Troll]] || [[File:More useful multipage2.png|center|thumb|User selected Cuttlefish]]
|}

<syntaxhighlight lang=lua>
local function more_useful_multi_page()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
race = "Trolls", tip = "Your uncle" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
race = "Trolls", tip = "Your nephew" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
race = "Trolls", tip = "Your auntie" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", race = "Seamonsters",
tip = "Not a fish" },
{ image = "units/monsters/yeti.png",
label = "A yeti", race = "Coolers",
tip = "ROAR!" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
}
}
}

local listboxDefinition = wml.tag.listbox {
id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
},
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
listboxDefinition
},
wml.tag.column {
wml.tag.spacer {
width = 30
}
},
wml.tag.column {
multi_page
},
}
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_image.tooltip = monster.tip
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_image.tooltip = monster.tip
dialog.monsters_mp[i].monster_label.label = monster.label
end
local function switch_page()
dialog.monsters_mp.selected_index = listbox.selected_index
end
listbox.on_modified = switch_page
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

Most of this should look pretty familiar. We've simply taken the previous example and added a second column to our GUI using code from an earlier example to add a listbox. In addition, we altered the page layout slightly, and added a spacer column in the dialog definition to approve the appearance.

The interesting stuff is in preshow(). Again we've merged in some listbox code from an earlier example, but we've also created a new local function switch_page(), which simply sets the selected_index attribute of our multi_page to the same as that of our listbox, and then we've configured the listbox.on_modified callback to call switch_page(). Now when the user selects an item in the listbox (updating listbox.selected_index and triggering listbox.on_modified), dialog.monsters_mp.selected_index is updated accordingly and therefore the visible page changes to the one associated with the selected unit.

Also note in preshow() we've added a new child to our monster_image identifier for both the listbox and the multi_page, a tooltip. When the user hovers the mouse over the image of one of our monsters, they'll see a popup message which we've added to our monster table. Try changing '''wml.tag.tooltip { id = "tooltip_large" }''' to '''wml.tag.tooltip { id = "tooltip }''' in the dialogDefinition to see a different tooltip style.

==Actions Have Consequences==

So far, our GUIs have only displayed some information on the screen, but at some point we're probably going to want to use a GUI to get input from the user. In this section we will look at return values that can be assigned to a widget based upon its state, and callbacks, which are functions invoked when something happens with a widget. As we will see, a button is a good example, as it can return a value or take an action, or both, when pressed. Earlier we saw how the selected_index attribute of some widgets, such as the listbox, can also be used as a sort of return value.

===Buttons===
{|
| colspan=2 | In this example, we'll create a couple buttons which provide the user a choice, use a handy confirmation popup to confirm that choice, and demonstrate how we get the results back where we can put them to use.
|-
| [[File:Basic return value.png|center|thumb|There can be only one]] || [[File:Basic return value_confirm.png|center|thumb|The user selected Alice, let's confirm this critical choice]]
|}

<syntaxhighlight lang=lua>
local function basic_return_value()

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "leader_lg",
fixed_height = true,
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" ..
_"Which unit shall lead your army?" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Alice" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/elves-wood/sylph.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 1
}
}
},
}
},
wml.tag.column {
wml.tag.spacer { width = 20 }
},
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Bob" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/human-loyalists/marshal.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 2
}
}
}
}
}
}
}
}
}
}
}
local user_chose = gui.show_dialog(dialogDefinition)
local leader
if user_chose == -1 then -- User closed the dialog by hitting the Enter key
leader = nil
end
if user_chose == -2 then -- User closed the dialog by hitting the Escape key
leader = nil
end

if user_chose == 1 then
leader = "Alice"
end
if user_chose == 2 then
leader = "Bob"
end

local confirmed_leader_choice

if leader ~= nil then
local query = _"You want " .. leader .. _" as your leader?"
confirmed_leader_choice = gui.confirm(query)
end

if confirmed_leader_choice then
wesnoth.message("Great!")
else
wesnoth.message("Fine, lead them yourself!")
end
end
</syntaxhighlight>

Here we've added a couple buttons, and assigned each of them a return value. When the user selects one of these buttons, the GUI is closed and the value of return_value is returned from gui.show_dialog(). We then use [https://wiki.wesnoth.org/LuaAPI/gui#gui.show_prompt gui.confirm()] which provides a very simple Yes/No popup and returns true or false, respectively. Other useful functions can be found on that page which provide handy alternatives to creating your own GUI for other simple user inputs.

The use of return_value is rather limited, as it only returns integers and can't be used with containers like listboxes. In more complex cases we'll need to turn to callback functions which are invoked when something happens to a widget, like clicking a button or a widget's value changing. Earlier, we saw an example of [[LuaAPI/types/widget#on_modified|widget.on_modified()]]. More examples of callbacks can be found at [[LuaAPI/types/widget#on_modified|that link]].

===Slider and Textbox===
{|
| Here we see a couple methods of getting more dynamic input from the user, a slider and a textbox presented in one silly example.
|-
| [[File:Slider and textbox.png|center|thumb|Two ways of getting input from the user]]
|}

<syntaxhighlight lang=lua>
function slider_and_textbox()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = _"How much gold will you pay for this old rusty sword?"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.slider {
id = "gold_sl",
minimum_value = 0,
maximum_value =
wesnoth.sides[wesnoth.current.side].gold,
value = math.floor(
wesnoth.sides[wesnoth.current.side].gold/2)
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.text_box {
id = "gold_tb",
--hint_text = _ "Enter gold here",
--hint_image = "images/gold_pile.png",
label = tostring(math.floor(
wesnoth.sides[wesnoth.current.side].gold/2))
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
local function show_input()
wesnoth.interface.add_chat_message(_"You chose " ..
dialog.gold_sl.value .. _" with the slider")
wesnoth.interface.add_chat_message(_"You entered " ..
tostring(dialog.gold_tb.text) .. _" in the text_box")
end
-- this is a button, so we use on_button_click, not on_left_click
dialog.ok.on_button_click = show_input

dialog.gold_sl.on_modified = function()
dialog.gold_tb.text = tostring(dialog.gold_sl.value)
end
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We create a slider, with a range from 0 to the amount of gold possessed by the current side and an initial value in the middle, and a text box with the same initial value. We assign a function to our OK button which simply reports on the values provided by the user. For no reason whatsoever, we add a callback such that when the user adjusts the slider the value in the textbox is update to match the slider.

Note that the textbox returns text, even though it looks like we're expecting the user to input a natural number. Remember to validate those inputs.

You can use text_hint to place a caption in the box that will help the user understand what to enter in the box, and possibly an image as well. For example, in the search box in the recall menu uses '''hint_text = _ "Search", hint_image = "icons/action/zoomdefault_25.png~FL(horiz)"'''. Of course, you can't have a hint and a label in the same text_box at the same time, so in our example we've only included them as comments.

There is also a widget called a spinner, which is kind of like the combination of a text_box and a slider. As of the release of 1.18, it appears to be unfinished so the strange syntax needed to make it work is probably not the best thing to document, and we will omit it for now.

==Appearance==

'''This section needs help'''

===Borders===

Borders allow you to force unused space around a column, for example so that your widgets don't runtogether. You can specify the border to be one or more of top, bottom, left, right, or all. The border_size sets the amount of padding, in pixels.

<syntaxhighlight lang=lua>
wml.tag.column{
border = "left, right"
border_size = 25
}
</syntaxhighlight>

===Alignment===
{|
| colspan=2 |By default, the GUI will usually center widgets in their cells, which is not always what we want. In this example, we use horizontal_alignment to move widgets around a little.

In more complex cases, it may be useful to add [[GUIWidgetDefinitionWML#Spacer|spacers]] to help force alignment, or use linked_groups to force consistent alignment for objects within a grid.
|-
| [[File:Gui tutorial alignment without.png|center|thumb|Default alignment]] ||[[File:Gui tutorial alignment with.png|center|thumb|Showing off some alignment options]]
|}
<syntaxhighlight lang=lua>
local function basic_alignment()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = "Ralph"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "right",
wml.tag.label {
label = "Sam"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/troll-hero-attack-se-4.png" -- 122x102
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "left",
wml.tag.label {
label = "Jr"
}
},
wml.tag.column {
horizontal_alignment = "right",
wml.tag.image {
label = "units/trolls/whelp.png" -- 72x72
}
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

The screenshots show the output of this example with and without the horizontal_alignment lines included above.

A label allows you to set the text_alignment field (e.g. text_alignment = "left"). Note, however, this only aligns the text within the label. The label itself will probably be centered in the column, giving the false appearance that your text alignment is not working.

===Growth===

To keep your dialog nicely balanced, the GUI2 engine may need to grow rows and/or columns. You can control which columns, for example, grow and which do not, by setting some with grow_factor = 1, and others with grow_factor = 0 (do not grow). While grow factors of 0 and 1 are the most common, you can use other values to adjust the relative growth if you really need to, see [[GUILayout]] for the gory details.

It it sometimes useful to include a column with a [spacer] and a grow_factor (often the only column with grow_factor != 0) whose sole purpose is to keep your GUI aligned nicely as the layout engine does its evil.

To force a column to stretch to fit available space, use horizontal_grow = true. Note that horizontal_grow is not compatible with horizontal_alignment. There is also a vertical_grow parameter.

If you need to see every little detail about the layout process, start wesnoth with --log-debug=gui/layout. Good luck with that.

===Definitions===
Many widgets can be configured to have to a different appearance, for example in our tree_view example we changed the definition of a toggle_button from the default of a checkbox by setting definition = "tree_view_node". This option was found by looking at the id of a toggle_button_definition in .../data/gui/widget/toggle_button_tree_view_node.cfg:

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib
###
### Definition of a toggle button to be used in a tree view as node fold/unfold indicator
###
[toggle_button_definition]
id = "tree_view_node" # <--- we can use 'definition = "tree_view_node"' in a [toggle_button] to select this definition
description = "Fold/unfold status indicator of a tree view node."
</syntaxhighlight>

{|
|There are many other definitions for buttons and other widget types in that directory. It would be nice to have a list (linked here), but for now you'll just have to look around.

We can even create our own custom definitions using [[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition()]]. In this example, we copy from .../data/gui/widget/toggle_button_tree_view_node.cfg with a slight change so that our button turns red ( '''~BLEND(255,0,0,1)''' ) when focused.

In this example, we will use wesnoth.wml_actions to create the WML tag [add_widget_def_demo].

Note the first line, a common convention for creating an alias for wml.tag.
|-
|[[File:Gui tutorial custom widget.png|center|thumb|Different definition of buttons, including one of our own (right)]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag -- save ourselves some typing
function wesnoth.wml_actions.add_widget_def_demo()
local definition = {
id = "tree_view_node_custom",
description = "Fold/unfold status indicator of a tree view node (MODIFIED).",
T.resolution {
min_width = 25,
min_height = 19,
default_width = 25,
default_height = 19,
max_width = 25,
max_height = 19,
-- Unselected - note there's no tags for unselected/selected, that's simply determined by the order
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/fold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/fold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/fold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
-- Selected
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/unfold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
}
}
gui.add_widget_definition("toggle_button", "tree_view_node_custom", definition)

local dialogDefinition = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid {
T.row {
T.column {
T.toggle_button {
definition = "default"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node_custom"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end

</syntaxhighlight>

See [[GUIWidgetDefinitionWML]] for more details on widget definitions.

You can also give the whole dialog a definition, like definition = "tooltip_large". There is no gui.add_window_definition(), however a window is technically a type of widget so it may be possible to create your own window definitions (please update this if you do).

===Panels===

===Canvases===
Part of panels? Sort of?

A canvas is a surface you can draw on. A dialog has them, as does a panel, and for these canvas 1 refers to the background, while canvas 2 refers to the foreground. Other widgets may have canvases that may have other meanings, or no canvases at all. See more at [[LuaAPI/gui/widget#set_canvas]].

Here's a fun little trick. Set your dialog background to be transparent:
<syntaxhighlight lang=lua>
local function preshow(dialog)
dialog:set_canvas(1, { } )
end
</syntaxhighlight>

Or, if you want an opaque GUI background with the screen behind it blurred like what you see behind the text of a [message], you can set your window definition to "message":
<syntaxhighlight lang=lua>
...
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
definition = "message",
...
</syntaxhighlight>

{|
|Here we take our [[#Progress Bar|progress bar]], and add a text overlay.

Note: either using text on a canvas is rather limited, or I just couldn't figure it out. For example, I could not get the text size any smaller, and any attempts to do so simply resulted in very blocky text. And the spaces were necessary so that the text wasn't stretched out. I also find it surprising that the progress bar does not have this feature inherently. So it's not a great example, but it should be enough to get you started using canvases. Be sure to visit the [[LuaAPI/gui/widget#set_canvas|link]] mentioned above for more options.
|-
|[[File:Gui tutorial canvas text.png|center|thumb|A progress bar in the background, with text in the foreground]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar_with_overlay()
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.grid {
T.row {
T.column {
T.panel { id = "panel",
T.grid {
T.row {
T.column {
T.button { id = "button",
label =_ "Press me"}
},
T.column {
T.progress_bar { id = "progress" }
},
T.column {
T.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
dialog.panel:set_canvas(2, { T.text { text_alignment = "center", font_size = 48,
text_markup = true, text = " " ..
dialog.progress.percentage .. "% " } } )
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

You may notice we added a panel and placed our text on the foreground canvas(2) on it, since the progress_bar itself does not support canvases.

===Placement===

You may have noticed that all of our dialogs are centered on the screen. This is the default. You can override this and place the dialog wherever you like by setting automatic_placement = false, along with x, y, width, and height at the top level of your dialog definition (next to tooltip =, etc).

'''This part about placement needs review'''
If you prefer, you may replace x and/or y with horizontal_placement and vertical_placement, such as horizontal_placement = "left". You can even set the placement values using WFL, for example horizontal_placement = "(gamemap_width / 3)" -- see [[#Using WFL with GUI2|Using WFL with GUI2]].

==Miscellaneous==

TODO: This stuff doesn't belong in a tutorial. It's worth documenting, but not here. Better to save these here for now than keep them on my laptop.

===Progress Bar===
{|
|A progress_bar is a graphical representation of a percent. In this example, we present the user with a puzzle. They must hit the button repeatedly before they can close the GUI. A progress_bar displays their current progress toward completion.
|-
|[[File:Gui tutorial progress bar.png|center|thumb|upright=2]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.button { id = "button",
label =_ "Press me"
}
},
wml.tag.column {
wml.tag.progress_bar { id = "progress" }
},
wml.tag.column {
wml.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end

gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

===Unit Preview Pane===

{|
|A unit_preview_pane takes a unit (or a unit type), and presents a graphical representation of the unit and its more important attributes, along with tooltips for additional details, in the same way that the recall menu does. Here we see an example of a unit which has picked up some items, including a weapon, which are affecting its stats.
|-
|[[File:Gui tutorial unit preview pane.png|center|thumb]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag

function wesnoth.wml_actions.recall_from_variable(cfg)
local from_array = cfg.from or wml.error(
"[recall_from_variable]: missing required from= ")
local to_var = cfg.to or wml.error(
"[recall_from_variable]: missing required to= ")
local unit_list = wml.array_access.get(from_array) or wml.error(
string.format("[recall_from_variable]: failed to fetch wml array %s",from_array))

local listboxItem = T.grid {
T.row {
T.column {
T.label { id = "available_unit",
linked_group = "available_unit"
}
}
}
}

local listbox_id = "available_units"
local listboxDefinition = T.listbox { id = listbox_id,
T.list_definition {
T.row {
T.column {
T.toggle_panel { listboxItem }
}
}
}
}
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.linked_group { id = "available_unit", fixed_width = true },
T.grid {
T.row { -- header
T.column {
T.grid {
T.row {
T.column {
border = "bottom",
border_size = 10,
T.label {
use_markup = true,
label = ""
.. _"Select unit to recall" .. ""
}
}
}
}
}
},
T.row { -- Body
T.column {
T.grid {
T.row {
T.column {
border = "right",
border_size = 40,
listboxDefinition
},
T.column {
T.unit_preview_pane { id = "unit_preview" }
}
}
}
}
},
T.row { -- Footer
T.column {
T.grid {
T.row {
T.column {
T.spacer { width = 400 }
},
T.column {
border = "top,right",
border_size = 10,
T.button { id = "ok",
label = _"OK"
}
}
}
}
}
}
}
}

local picked = 1

local function preshow(dialog)
local listbox = dialog[listbox_id]
for i,unit in ipairs(unit_list) do
listbox[i].available_unit.label = unit.name .. "(" ..
unit.language_name .. ")"
end
local function draw_unit()
wesnoth.units.to_recall(unit_list[listbox.selected_index])
local tmp = wesnoth.units.find_on_recall{ id =
unit_list[listbox.selected_index].id }[1]
dialog.unit_preview.unit = tmp
wesnoth.units.extract(tmp)
picked = listbox.selected_index
end
draw_unit()
listbox.on_modified = draw_unit
end

gui.show_dialog(dialogDefinition,preshow)

wml.variables[to_var] = picked - 1
end

</syntaxhighlight>

This should all be pretty self evident by now. We are provided with an array of stored units (from [store_unit] in WML). We create a listbox populated with units and we use the selected_index to determine which element in the table to send to unit_preview_pane. Since our input is an array of unit data, not actual units, we use [[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] to take the definition of one from our array and place it on the recall list (turning it into an actual unit), [[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] to fetch that unit in a form that the unit_preview_panel understands, and finally [[wesnoth.units.extract|wesnoth.units.extract]] to remove the unit from the recall list when we are done with it.

And of course we subtract one from the selected_index when we return our choice to WML, since lua arrays count from 1 and WML from 0.

The unit_preview_pane will also accept a unit_type instead of a specific unit.

==Appendix==

===Explore Your Options===

We've seen a lot of options that can be set to modify the behaviour of our dialogs, some on columns, some on widgets, etc. These are in the process of being documented [[GUIWidgetInstanceWML|here]], but if you would like to go straight to the source, the data Wesnoth uses to validate your configuration can be found in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui data/schema/gui] under your install directory.

Let's look at a scroll_label, for example. A scroll_label is a widget, so we look in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/widget_instances.cfg widget_instances.cfg] and find the following. Here we can see five parameters we can provide to our scroll_label (in addition to the ones available to all widgets, like id and definition, see the entry super=... which refers you to the widget_instance in the file [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/generic.cfg data/schema/gui/generic.cfg]), along with their types and default values. For example, we could set "link_aware = true", and if we do not we can assume that link_aware will be false. While this does not explain what these parameters do, the information provided in the schema directory is often helpful nonetheless.

<syntaxhighlight lang=wml>
[tag]
name="scroll_label"
min="0"
max="infinite"
super="$generic/widget_instance"
{DEFAULT_KEY "horizontal_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "vertical_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "wrap" bool true}
{DEFAULT_KEY "text_alignment" f_h_align "left"}
{DEFAULT_KEY "link_aware" bool false}
[/tag]
</syntaxhighlight>

We see that our scrollbars are of type scrollbar_mode. It would probably help if we knew what values are available to the scrollbar_mode. In [https://github.com/wesnoth/wesnoth/tree/master/data/schema/types/gui.cfg data/schema/types/gui.cfg] we find this:

<syntaxhighlight lang=wml>
[type]
name=scrollbar_mode
value="always|never|auto|initial_auto"
[/type]
</syntaxhighlight>

The variable types found in the schema files are described at [[GUIVariable]].

Note: The keys in the schema file correspond to the attributes used when configuring your widgets. They will not always align perfectly with keys used by the Lua API. For example, the slider uses maximum_value in its configuration, and max_value when using the Lua API:

<syntaxhighlight lang=wml>
[slider]
id="my_slider"
maximum_value = 100
[/slider]
</syntaxhighlight>

<syntaxhighlight lang=lua>
dialog.my_slider.max_value = 90
</syntaxhighlight>

===Using WFL with GUI2===

If you look at the variable type descriptions at [[GUIVariable]] you may notice that many of them start with "f_" and have "or formula" in the description. This means that you can use [[Wesnoth_Formula_Language|Wesnoth Formula Language (WFL)]] formulas in these fields, with certain variables made available to you (which variables and what they mean can be challenging to ascertain, but you can generally figure it out by example).

Looking at [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/window.cfg data/schema/gui/window.cfg] we see that 'height' has type f_unsigned, which tells us that height is an unsigned integer, and that we can use a WFL formula to define it in a window_definition. In [https://github.com/wesnoth/wesnoth/tree/master/data/gui/themes/default/window/wml_message.cfg data/gui/window/wml_message.cfg] (data/gui/themes/default/window/wml_message.cfg starting around 1.19.2), we find the line '''height = "(screen_height - 30)"'''. This does exactly what it looks like, it sets the height of our window to 30 pixels less than the height of the screen.

===Useful Links===
[[GUIToolkitWML]] - Documents the keys/values available on various objects (e.g. "what attributes can I set on a column?") 
[[LuaAPI/gui|LuaAPI/gui]] - Mostly about opening windows 
[[LuaAPI/types/widget]] - Widget attributes and callbacks 
[https://wiki.wesnoth.org/Category:GUI_WML_Reference GUI_WML_Reference] 
[https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui .../data/schema/gui/*.cfg] - Lists of valid options for various GUI objects 
[https://devdocs.wesnoth.org/layout_algorithm.html Layout Algorithm] - For windows, at least

===Credits===

The basic framework that composes the initial examples was lifted from LotI. It's a great place to find well written examples, but some of it is complex enough to be a little overwhelming when getting started.

Many examples, particularly tree view and multipage, are heavily derived from the World Conquest multiplayer campaign.

Sandbox/GUI/Getting Started

2024-10-30T23:49:51Z

White haired uncle: /* Listbox */

So, it looks like I can't exclude this page/section from the search engine as I had hoped. I wanted to put this in a sandbox so that it wouldn't be published without some proper review.

==Introduction==

This guide is designed to help you get a simple Wesnoth GUI, implemented in lua, up and running while describing the basic building blocks along the way. It is written in a narrative format, where most examples build on previous examples, and therefore while not always necessary it may be desirable to read from start to finish. The reader, probably a UMC author, should have a basic knowledge of working with lua within Wesnoth.

Some would find creating a GUI in part or in full using WML simpler to follow, and those alternatives are available, for example [[LuaAPI/gui/example]], but we're using lua here. If you find WML easier to follow, you can always convert the lua tables that define the GUIs to WML using [[LuaAPI/wml#wml.tostring|wml.tostring]], for example:

<syntaxhighlight lang=lua>
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
</syntaxhighlight>

In some examples, instead of defining the entire GUI at once, we'll break out some parts into separate variables. If you try to view one in WML and get an error from wml.tostring() about expecting a WML table and not a table, try passing your variable(/table) inside a table:

<syntaxhighlight lang=lua>
print(wml.tostring({listboxItem}))
gui.show_lua_console()
</syntaxhighlight>

One distinct advantage of using WML to define your GUI layout is that you get better (any) validation. Invalid keys, and sometimes values, are often flagged in the log, unlike with lua where they are silently ignored. In the comments of our first GUI, below, is an example which loads a WML GUI configuration using [[LuaAPI/wml#wml.load|wml.load()]], validating against the GUI2 window schema.

===What is GUI2?===
Once upon a time, Wesnoth had a GUI system which is now commonly referred to as GUI1. As of 1.19, GUI1 has been almost completely replaced by GUI2. UMC authors will probably never encounter GUI1 and can simply use the terms GUI and GUI2 interchangeably, at least until GUI3 comes along.

Instead of spending a lot of time here giving an overview of what GUI2 is and what makes it great, and not so great, let's charge ahead so we can see it in action, and let readers who are interested look elsewhere(TODO: link) for a more formal definition. (TODO: is this the right approach for most readers?).

==Getting Started==

For example purposes, we'll create a directory in our campaign directory called lua containing a file called gui_tutorial.lua, and add a command in the prestart event for a scenario which will create a right-click menu option to invoke our new GUI. Of course there are other methods to invoke lua from WML, but this one will get us started. After all, we really just want to get something up on the screen ASAP, right?

===A most basic GUI===

{|
|[[File:Most basic gui.png|center|thumb|I can't believe this worked]]
|-
|In our prestart event, we create a simple menu item, which executes a single line of lua which calls the lua function most_basic_gui() which is found in gui_tutorial.lua:
|}

<syntaxhighlight lang=wml>
[set_menu_item]
id=most_basic_gui
description="Our first GUI"
[command]
[lua]
code=<<
wesnoth.require("~add-ons/<OUR_CAMPAIGN>/lua/gui_tutorial.lua").most_basic_gui()
>>
[/lua]
[/command]
[/set_menu_item]
</syntaxhighlight>

And create gui_tutorial.lua:
{| class="wikitable" style="margin:auto"
! !! The WML equivalent of dialogDefinition
|-
|
<syntaxhighlight lang=lua>
local function most_basic_gui()
local dialogDefinition = {
--click_dismiss = true, -- allow user to close dialog with click of a button
wml.tag.tooltip { id = "tooltip_large" }, -- required
wml.tag.helptip { id = "tooltip_large" }, -- required
wml.tag.grid { -- our most basic gui
wml.tag.row { -- a grid must include at least one row
wml.tag.column { -- a row needs a column
wml.tag.image { -- a column includes exactly one widget
label = "units/trolls/grunt.png"
}
}
}
}
}

local function preshow(dialog)
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
end
gui.show_dialog(dialogDefinition,preshow)

-- Or, if you want to define the gui in WML, something like:
-- local dialog_wml = wml.load("~add-ons/GUI_Tutorial/most_basic_gui.cfg",
-- true, "schema/gui_window.cfg")
-- gui.show_dialog(wml.get_child(dialog_wml, 'resolution'))
end
return { most_basic_gui = most_basic_gui}
</syntaxhighlight>
|
<syntaxhighlight lang=wml>
[tooltip]
id="tooltip_large"
[/tooltip]
[helptip]
id="tooltip_large"
[/helptip]
[grid]
[row]
[column]
[image]
label="units/trolls/grunt.png"
[/image]
[/column]
[/row]
[/grid]

</syntaxhighlight>
|}

In the above file, we have just the single function to create our GUI, followed by a return command which makes our function most_basic_gui() available to the [[LuaAPI/wesnoth#wesnoth.require|wesnoth.require()]] function as most_basic_gui().

Our function creates a table containing the definition of a "dialog", and then passes that to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]]. It should be noted that gui.show_dialog does not provide synchronization, so if your GUI makes changes to the game state, you'll need to jump through some hoops or you'll break replays and multiplayer, but that's not something we need to care about at this point, so just be aware that you may need to deal with it in the future.

Our dialog definition at this point includes three parts. The first two are a tooltip and a helptip, which are required and define how tooltips (use id = "tooltip_large" or id = "tooltip" or id = "tooltip_transparent"), and helptips (rarely used, but must be included here, and yes their definitions are "tooltip" not "helptip") will look (as we will see later, this really should be definition = "tooltip", but in this case it's id = "tooltip"). The third part is a grid, which is basically a table, like in HTML or MySQL, with rows and columns. A grid always contains at least one row. A row contains at least one column (note that a column does NOT span rows, it is completely contained within a row). Inside a column is exactly one item, a cell which contains a [[GUIWidgetDefinitionWML|widget]], in this case we'll use an image (later we'll see what else we can put in a cell). Note that we don't actually define a cell in our code, it's just a term used to refer to the contents of a column.

The preshow function is optional. If included in the call to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]], it is run before the GUI is displayed. In this case, we include it to display the dialog we created with lua in WML format. Near the end, in comments, we show how you would call [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] if you chose to define your dialog using WML. Note that what is shown here is the WML equivalent of our lua dialogDefinition, and not the complete WML you would need to use if you were to configure your GUI layout in WML.

Note: if you should try out the above, you'll have to hit escape or enter to close the GUI. Uncomment the "click_dismiss" line, and the user will be able to close the GUI with a mouse click.

===Adding a little flavor===

{|
|You may have noticed our GUI is missing a header and a way to close it when we're done admiring our work. Here we add a new first row to our grid, while demonstrating a couple formatting options: a border to put some distance between our grid cell and its neighbor, and the "use_markup = true" option to enable Pango support in our text.

Our third row adds an OK button at the bottom. You can associate actions with buttons to do all kinds of things, but here we just exploit the default behaviour to close the GUI.

Of course, we'll also have to modify our return to support the new function, and update our menu item(s) accordingly.
|-
|[[File:Most basic gui2.png|center|thumb|Adding header and a footer]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui2()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
gui.show_dialog(dialogDefinition)
end
return { most_basic_gui = most_basic_gui, most_basic_gui2 = most_basic_gui2 }
</syntaxhighlight>

===And a bit more===
{|

|And now a minor, but important change. We want to add a new text field next to the image in the body of our GUI. Obviously, we want to add a new column, but this is more difficult than when we added new rows in the previous example. The problem is that all rows (at a given level) in a grid must contain the same number of columns. We can't have two columns in the row that constitutes the body of our GUI, but only one in the header and one in the footer. To solve this problem, we replace our image widget with a new grid, which can use as many columns as we like (as long as they are the same within each row of our new grid). This new grid contains a row with two columns, but that is okay because the new grid itself is placed in a single column, which matches our single column header and footer (ok button), keeping the rows balanced.
|-
|[[File:Most basic gui3.png|center|thumb|Rows with different numbers of columns]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui3()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column { -- This is the only column in this row,
-- to match the number of columns in
-- the rows of our header and footer
wml.tag.grid { -- A new grid, so we can use a different
-- number of columns
wml.tag.row {
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
},
wml.tag.column {
wml.tag.label {
label = "A troll"
}
}
}
}
}
},
wml.tag.row { -- A footer
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = "Ok"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

While we see here just the simplest of examples, you can many levels of grids in grids, rows with multiple columns some of which containing grids, etc, to build complicated dialogs to your liking.

==Containers==

===Stacked Widget===

TODO

===Listbox===
{|
| Now we'd like to add some more monsters. Obviously, we could just add more rows, but what if we won't know until runtime how many and which ones? We could break up the definition of our dialog and add new rows dynamically, it's just a table after all, but fortunately we have a widget which handles this for us, a listbox. A listbox is kind of like an array, a collection of similar objects where the number of items can vary. We will tell the GUI where we want the box, and what each entry in the box will look like, and then at runtime we can add entries to the box.

Note that listbox items are added from top to bottom. Another container, the horizontal_listbox, works just like a listbox except the items are added from left to right. With a grid listbox, items are added horizontally with the list wrapping to a new line as necessary.
|-
| [[File:Gui with listbox.png|center|thumb|Listbox with three items. Each item is an image and a label. The third item has been selected.]]

<syntaxhighlight lang=lua>
local function gui_with_listbox()
local monsters = {
{ image = "units/trolls/grunt.png",
string = "A troll" },
{ image = "units/monsters/cuttlefish.png",
string = "A cuttlefish" },
{ image = "units/monsters/yeti.png",
string = "A yeti" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
}

local listboxDefinition = wml.tag.listbox { id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
listboxDefinition
}
},
wml.tag.row {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_label.label = monster.string
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We begin by creating a simple table which represents the data which will be presented in our listbox. In most cases, we probably wouldn't create that monster table here, but we need it for our example.

The variable listbox_id gives us an identifier for our listbox so we can reference it when we need to. We don't really need to use a variable here, it's just convenient.

We define the structure for the elements in our listbox, stored in listboxItem. Note that we've replaced the actual data with identifiers (e.g. 'units/trolls/grunt.png' becomes 'id = "monster_image"), since each element may have different data.

We define the listbox itself, specifying the identifier, and the definition of our listbox element (which looks a lot like a grid). The cell inside the column contains a variable which is just the listbox element definition we created above; it's not necessary to do this, we could have used one big table, but it's easier to read this way (IMO).

We replace the hardcoded data in our GUI body with our new listbox definition, again using a variable to make it easier to read.

We create a function, often called preshow(), which will be called for us as part of the drawing the GUI (see the new optional argument in [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] -- there's also an optional postshow(), but we don't need it here). This is where we pull the data from our example table into the listbox. We create a listbox variable associated with the listbox, identified by the listbox_id we assigned earlier, inside the dialog which gui.show_dialog() passes to preshow(). Then we iterate through our data table, using each entry from that table to populate a listbox item.

Let's look at that last action a little more closely using an example.

<syntaxhighlight lang=lua>
listbox[i].monster_image.label = monster.image
</syntaxhighlight>

Which we can read as "In listbox element i of our listbox, for the image with identifier monster_image which we defined in our listboxItem, use the data from the corresponding index i in our example data table" (you don't see the index i for the monsters table here, but remember we're iterating using ipairs, we could have just as easily used listbox[i].monster_image.label = monsters[i].image). If you were to step through all of the variable substitutions, you'd see that for i=1, our dialogDefinition is basically the same thing as it was in the earlier examples, just supplied from a table instead of hardcoded (note that you can hardcode entries in a listbox in your dialog definition using the [list_data] tag, aka wml.tag.list_data, which we do not demonstrate here).

You will probably notice that our data does not line up nicely in the GUI. We will fix that later. We'll also demonstrate how the user can select an item in a listbox, and how you can identify which item that was using the selected_index variable of the listbox.

===Tree View===
====Simple Tree View====
{|
| You may have noticed that clicking on a listbox item in our listbox caused it to be highlighted with a box around the contents. This is because the items in a listbox are selectable. This will be useful when we want to add actions, but it looks a bit odd if we just want to present a list of data.

Also, most of the data had to be formatted the same for each item in the listbox. We could, perhaps, include custom markup in our labels, but the actual layout, like the number of columns per row, had to be the same for every item.

Another way to present a list of data is the tree view. Since a tree view supports multiple data types, we may need to create multiple definitions for the elements in our list. These are known as nodes. It will also be necessary to explicitly define which node to use for each element when we populate our tree view.
|-
| [[File:Basic tree view.png|center|thumb|Tree_views can hold multiple data types (only trolls have names here)]]
|}
<syntaxhighlight lang=lua line>
local function basic_tree_view()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", type = "Seamonsters" },
{ image = "units/monsters/yeti.png", label = "A yeti",
type = "Coolers" }
}

local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "trolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name",
linked_group = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
},
wml.tag.node {
id = "nottrolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "monster_name",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_image",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_label",
fixed_width = true
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_tv:add_item_of_type("trolls_node")
dialog.monsters_tv[i].monster_name.label = monster.name -- only trolls have a name
else
dialog.monsters_tv:add_item_of_type("nottrolls_node")
end
-- All of our monsters have an image and a label
dialog.monsters_tv[i].monster_image.label = monster.image
dialog.monsters_tv[i].monster_label.label = monster.label
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We have expanded our list of monsters to include three types of trolls. We have also given each troll a name. This is of course a rather simplistic example, we could have simply given each monster that is not a troll an empty name, but it as presented here our approach serves the purpose of demonstrating how we deal with multiple data types. Our new tree view contains a node for each type of data we will present. In preshow, we explicitly define each element in our list using add_item_of_type(), and populate the item accordingly. [Note: in our listbox example, we could have used add_item() to add items to the listbox, but chose not to since that section was already introducing a number of new concepts. But here, since we have multiple types of items we need to be able to specify the type of the item when we add one, hence we need to use add_item_of_type()].

You may also note the addition of a few linked_group lines. We'll cover linked groups in more detail later, but as used here they instruct the GUI that each column using the same node type needs to be aligned with the others. For example, all of our trolls line up nicely.

====Building a Tree====
{|
| colspan="2" |At this point, one may wonder about the name "tree view", since what he have seen doesn't look much like a tree. To make a tree-like structure, we'll demonstrate adding children to nodes. At the top level our (upside-down) tree will have two nodes, one for trolls and one for everything else. A toggle_button (a type of button which changes states when you push it) will allow us to expand the trolls node to expose its children, which are themselves nodes, though they only contain a label at this point.
|-
| [[File:Basic tree view2a.png|center|thumb|Tree_view with Trolls folded]] || [[File:Basic tree view2b.png|center|thumb|Tree_view with Trolls unfolded]]
|}
<syntaxhighlight lang=lua line>
local function building_a_tree()
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
}
},
wml.tag.column {
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Show me the " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
-- You can refer to an object by its position

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[1].race_label.label = "Trolls"
-- dialog.monsters_tv[1].race_button.on_modified =
-- function()dialog.monsters_tv[1].unfolded =
-- dialog.monsters_tv[1].race_button.selected end

-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][1].monster_type.label = "Whelp"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][2].monster_type.label = "Shaman"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][3].monster_type.label = "Troll"

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[2].race_label.label = "Other scary things"
-- dialog.monsters_tv[2].race_button.visible = "hidden"

-- ... or you can refer to that object using the return value
-- from add_item_of_type
local troll_node = dialog.monsters_tv:add_item_of_type("race_node")
troll_node.race_label.label = "Trolls"
troll_node.race_button.on_modified =
function()
troll_node.unfolded = troll_node.race_button.selected
end
local item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Whelp"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Shaman"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Troll"

local not_troll_node =
dialog.monsters_tv:add_item_of_type("race_node")
not_troll_node.race_label.label = "Other scary things"
not_troll_node.race_button.visible = "hidden"

end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We define two nodes in our tree, a race_node for the top level, and a details_node for the children of a race_node. The rest of the interesting bits are in preshow().

We demonstrate two different ways of creating and accessing items, the first (commented out) just using the order in which they are created, while in the second we capture the result of add_item_of_type() in a variable we can use to refer to the newly defined object. The first method is shown primarily to demonstrate the structure of the resulting objects. The second method is perhaps easier to follow, and is almost necessary when you start doing things like dynamically deleting nodes, so it is in most cases a better practice (of course, you probably won't want to use the same variable for each node like we did, and perhaps not one local to the preview function).

We add a node, label it "Trolls", and add a callback to the button such that the children of the node will be visible (the node is "unfolded", a boolean value which defaults to false) when the button is checked (selected == true). Then we add three "details_node" nodes as children of this node.

Our second node, "Other scary things" will remain empty for now, so we'll set the visible attribute on its button to "hidden" (which is like false, but with hidden the widget still takes up space).

{|
| This example is rather ugly, both in the hardwired code and the appearance of the resulting GUI, but it addresses a couple important aspects of how tree views work and how we might use them. Let's clean it up a bit. We'll add an indentation_step_size to the tree view, along with a spacer and [[#Alignment|horizontal_alignment]] to our details node, to make the labels line up nicely, and change the button [[#Definitions|definition]] to replace the checkbox with something that looks like it belongs there. We will look at methods for handling layout in more depth [[#Appearance|later]].
|-
| [[File:Basic tree view2c.png|center|thumb|Our tree_view with proper alignment]]

<syntaxhighlight lang=lua>
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
indentation_step_size = 20,
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
definition = "tree_view_node"
}
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.spacer { width = 40 }
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}

</syntaxhighlight>

===Multi_page===
====Simple Multi_page====
{|
|-
Like a tree_view, a multi_page is a heterogeneous container which is dynamically populated, however, while a multi_page contains multiple elements (pages), only one page is displayed at any one time. Its purpose is perhaps best described by a couple of examples.
|-
[[File:Basic multipage.png|center|thumb|Multi_page showing active page]]
|}
<syntaxhighlight lang=lua>
local function basic_multipage()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll",
name = _"Bob", type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp",
name = "Junior", type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman",
name = _"Alice", type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish",
type = "Seamonsters" },
{ image = "units/monsters/yeti.png",
label = "A yeti",
type = "Coolers" }
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
multi_page
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}

local function preshow(dialog) -- Prepare the GUI before display
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_label.label = monster.label
end
--dialog.monsters_mp.selected_index = 5
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

As you can see, the code for our basic multi_page GUI looks a lot like our basic tree_view GUI. The difference is what is displayed. While both the tree_view and the multi_page containers contain five items, with the multi_page, only the first one is displayed. More specifically, only the page associated with the selected_index attribute of the multi_page object, which defaults to 1, is displayed. If we were to uncomment the last line in preshow(), we would still see only one item, but it would be the fifth one we allocated. It's nice to know all our pages are in there somewhere, but this example is pretty useless. What we need is a way to select which page we want to see from within our GUI.

====A More Useful Multi_page====

{|
| colspan="2" | To demonstrate the usefulness of a multi_page, and highlight its difference from a tree_view, we'll add a listbox to allow us to select the page to view. We'll also need to add a little action to our GUI.
|-
| style="align:centered" |[[File:More useful multipage.png|center|thumb|User selected Troll]] || [[File:More useful multipage2.png|center|thumb|User selected Cuttlefish]]
|}

<syntaxhighlight lang=lua>
local function more_useful_multi_page()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
race = "Trolls", tip = "Your uncle" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
race = "Trolls", tip = "Your nephew" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
race = "Trolls", tip = "Your auntie" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", race = "Seamonsters",
tip = "Not a fish" },
{ image = "units/monsters/yeti.png",
label = "A yeti", race = "Coolers",
tip = "ROAR!" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
}
}
}

local listboxDefinition = wml.tag.listbox {
id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
},
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
listboxDefinition
},
wml.tag.column {
wml.tag.spacer {
width = 30
}
},
wml.tag.column {
multi_page
},
}
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_image.tooltip = monster.tip
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_image.tooltip = monster.tip
dialog.monsters_mp[i].monster_label.label = monster.label
end
local function switch_page()
dialog.monsters_mp.selected_index = listbox.selected_index
end
listbox.on_modified = switch_page
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

Most of this should look pretty familiar. We've simply taken the previous example and added a second column to our GUI using code from an earlier example to add a listbox. In addition, we altered the page layout slightly, and added a spacer column in the dialog definition to approve the appearance.

The interesting stuff is in preshow(). Again we've merged in some listbox code from an earlier example, but we've also created a new local function switch_page(), which simply sets the selected_index attribute of our multi_page to the same as that of our listbox, and then we've configured the listbox.on_modified callback to call switch_page(). Now when the user selects an item in the listbox (updating listbox.selected_index and triggering listbox.on_modified), dialog.monsters_mp.selected_index is updated accordingly and therefore the visible page changes to the one associated with the selected unit.

Also note in preshow() we've added a new child to our monster_image identifier for both the listbox and the multi_page, a tooltip. When the user hovers the mouse over the image of one of our monsters, they'll see a popup message which we've added to our monster table. Try changing '''wml.tag.tooltip { id = "tooltip_large" }''' to '''wml.tag.tooltip { id = "tooltip }''' in the dialogDefinition to see a different tooltip style.

==Actions Have Consequences==

So far, our GUIs have only displayed some information on the screen, but at some point we're probably going to want to use a GUI to get input from the user. In this section we will look at return values that can be assigned to a widget based upon its state, and callbacks, which are functions invoked when something happens with a widget. As we will see, a button is a good example, as it can return a value or take an action, or both, when pressed. Earlier we saw how the selected_index attribute of some widgets, such as the listbox, can also be used as a sort of return value.

===Buttons===
{|
| colspan=2 | In this example, we'll create a couple buttons which provide the user a choice, use a handy confirmation popup to confirm that choice, and demonstrate how we get the results back where we can put them to use.
|-
| [[File:Basic return value.png|center|thumb|There can be only one]] || [[File:Basic return value_confirm.png|center|thumb|The user selected Alice, let's confirm this critical choice]]
|}

<syntaxhighlight lang=lua>
local function basic_return_value()

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "leader_lg",
fixed_height = true,
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" ..
_"Which unit shall lead your army?" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Alice" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/elves-wood/sylph.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 1
}
}
},
}
},
wml.tag.column {
wml.tag.spacer { width = 20 }
},
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Bob" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/human-loyalists/marshal.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 2
}
}
}
}
}
}
}
}
}
}
}
local user_chose = gui.show_dialog(dialogDefinition)
local leader
if user_chose == -1 then -- User closed the dialog by hitting the Enter key
leader = nil
end
if user_chose == -2 then -- User closed the dialog by hitting the Escape key
leader = nil
end

if user_chose == 1 then
leader = "Alice"
end
if user_chose == 2 then
leader = "Bob"
end

local confirmed_leader_choice

if leader ~= nil then
local query = _"You want " .. leader .. _" as your leader?"
confirmed_leader_choice = gui.confirm(query)
end

if confirmed_leader_choice then
wesnoth.message("Great!")
else
wesnoth.message("Fine, lead them yourself!")
end
end
</syntaxhighlight>

Here we've added a couple buttons, and assigned each of them a return value. When the user selects one of these buttons, the GUI is closed and the value of return_value is returned from gui.show_dialog(). We then use [https://wiki.wesnoth.org/LuaAPI/gui#gui.show_prompt gui.confirm()] which provides a very simple Yes/No popup and returns true or false, respectively. Other useful functions can be found on that page which provide handy alternatives to creating your own GUI for other simple user inputs.

The use of return_value is rather limited, as it only returns integers and can't be used with containers like listboxes. In more complex cases we'll need to turn to callback functions which are invoked when something happens to a widget, like clicking a button or a widget's value changing. Earlier, we saw an example of [[LuaAPI/types/widget#on_modified|widget.on_modified()]]. More examples of callbacks can be found at [[LuaAPI/types/widget#on_modified|that link]].

===Slider and Textbox===
{|
| Here we see a couple methods of getting more dynamic input from the user, a slider and a textbox presented in one silly example.
|-
| [[File:Slider and textbox.png|center|thumb|Two ways of getting input from the user]]
|}

<syntaxhighlight lang=lua>
function slider_and_textbox()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = _"How much gold will you pay for this old rusty sword?"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.slider {
id = "gold_sl",
minimum_value = 0,
maximum_value =
wesnoth.sides[wesnoth.current.side].gold,
value = math.floor(
wesnoth.sides[wesnoth.current.side].gold/2)
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.text_box {
id = "gold_tb",
--hint_text = _ "Enter gold here",
--hint_image = "images/gold_pile.png",
label = tostring(math.floor(
wesnoth.sides[wesnoth.current.side].gold/2))
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
local function show_input()
wesnoth.interface.add_chat_message(_"You chose " ..
dialog.gold_sl.value .. _" with the slider")
wesnoth.interface.add_chat_message(_"You entered " ..
tostring(dialog.gold_tb.text) .. _" in the text_box")
end
-- this is a button, so we use on_button_click, not on_left_click
dialog.ok.on_button_click = show_input

dialog.gold_sl.on_modified = function()
dialog.gold_tb.text = tostring(dialog.gold_sl.value)
end
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We create a slider, with a range from 0 to the amount of gold possessed by the current side and an initial value in the middle, and a text box with the same initial value. We assign a function to our OK button which simply reports on the values provided by the user. For no reason whatsoever, we add a callback such that when the user adjusts the slider the value in the textbox is update to match the slider.

Note that the textbox returns text, even though it looks like we're expecting the user to input a natural number. Remember to validate those inputs.

You can use text_hint to place a caption in the box that will help the user understand what to enter in the box, and possibly an image as well. For example, in the search box in the recall menu uses '''hint_text = _ "Search", hint_image = "icons/action/zoomdefault_25.png~FL(horiz)"'''. Of course, you can't have a hint and a label in the same text_box at the same time, so in our example we've only included them as comments.

There is also a widget called a spinner, which is kind of like the combination of a text_box and a slider. As of the release of 1.18, it appears to be unfinished so the strange syntax needed to make it work is probably not the best thing to document, and we will omit it for now.

==Appearance==

'''This section needs help'''

===Borders===

Borders allow you to force unused space around a column, for example so that your widgets don't runtogether. You can specify the border to be one or more of top, bottom, left, right, or all. The border_size sets the amount of padding, in pixels.

<syntaxhighlight lang=lua>
wml.tag.column{
border = "left, right"
border_size = 25
}
</syntaxhighlight>

===Alignment===
{|
| colspan=2 |By default, the GUI will usually center widgets in their cells, which is not always what we want. In this example, we use horizontal_alignment to move widgets around a little.

In more complex cases, it may be useful to add [[GUIWidgetDefinitionWML#Spacer|spacers]] to help force alignment, or use linked_groups to force consistent alignment for objects within a grid.
|-
| [[File:Gui tutorial alignment without.png|center|thumb|Default alignment]] ||[[File:Gui tutorial alignment with.png|center|thumb|Showing off some alignment options]]
|}
<syntaxhighlight lang=lua>
local function basic_alignment()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = "Ralph"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "right",
wml.tag.label {
label = "Sam"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/troll-hero-attack-se-4.png" -- 122x102
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "left",
wml.tag.label {
label = "Jr"
}
},
wml.tag.column {
horizontal_alignment = "right",
wml.tag.image {
label = "units/trolls/whelp.png" -- 72x72
}
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

The screenshots show the output of this example with and without the horizontal_alignment lines included above.

A label allows you to set the text_alignment field (e.g. text_alignment = "left"). Note, however, this only aligns the text within the label. The label itself will probably be centered in the column, giving the false appearance that your text alignment is not working.

===Growth===

To keep your dialog nicely balanced, the GUI2 engine may need to grow rows and/or columns. You can control which columns, for example, grow and which do not, by setting some with grow_factor = 1, and others with grow_factor = 0 (do not grow). While grow factors of 0 and 1 are the most common, you can use other values to adjust the relative growth if you really need to, see [[GUILayout]] for the gory details.

It it sometimes useful to include a column with a [spacer] and a grow_factor (often the only column with grow_factor != 0) whose sole purpose is to keep your GUI aligned nicely as the layout engine does its evil.

To force a column to stretch to fit available space, use horizontal_grow = true. Note that horizontal_grow is not compatible with horizontal_alignment. There is also a vertical_grow parameter.

If you need to see every little detail about the layout process, start wesnoth with --log-debug=gui/layout. Good luck with that.

===Definitions===
Many widgets can be configured to have to a different appearance, for example in our tree_view example we changed the definition of a toggle_button from the default of a checkbox by setting definition = "tree_view_node". This option was found by looking at the id of a toggle_button_definition in .../data/gui/widget/toggle_button_tree_view_node.cfg:

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib
###
### Definition of a toggle button to be used in a tree view as node fold/unfold indicator
###
[toggle_button_definition]
id = "tree_view_node" # <--- we can use 'definition = "tree_view_node"' in a [toggle_button] to select this definition
description = "Fold/unfold status indicator of a tree view node."
</syntaxhighlight>

{|
|There are many other definitions for buttons and other widget types in that directory. It would be nice to have a list (linked here), but for now you'll just have to look around.

We can even create our own custom definitions using [[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition()]]. In this example, we copy from .../data/gui/widget/toggle_button_tree_view_node.cfg with a slight change so that our button turns red ( '''~BLEND(255,0,0,1)''' ) when focused.

In this example, we will use wesnoth.wml_actions to create the WML tag [add_widget_def_demo].

Note the first line, a common convention for creating an alias for wml.tag.
|-
|[[File:Gui tutorial custom widget.png|center|thumb|Different definition of buttons, including one of our own (right)]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag -- save ourselves some typing
function wesnoth.wml_actions.add_widget_def_demo()
local definition = {
id = "tree_view_node_custom",
description = "Fold/unfold status indicator of a tree view node (MODIFIED).",
T.resolution {
min_width = 25,
min_height = 19,
default_width = 25,
default_height = 19,
max_width = 25,
max_height = 19,
-- Unselected - note there's no tags for unselected/selected, that's simply determined by the order
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/fold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/fold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/fold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
-- Selected
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/unfold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
}
}
gui.add_widget_definition("toggle_button", "tree_view_node_custom", definition)

local dialogDefinition = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid {
T.row {
T.column {
T.toggle_button {
definition = "default"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node_custom"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end

</syntaxhighlight>

See [[GUIWidgetDefinitionWML]] for more details on widget definitions.

You can also give the whole dialog a definition, like definition = "tooltip_large". There is no gui.add_window_definition(), however a window is technically a type of widget so it may be possible to create your own window definitions (please update this if you do).

===Panels===

===Canvases===
Part of panels? Sort of?

A canvas is a surface you can draw on. A dialog has them, as does a panel, and for these canvas 1 refers to the background, while canvas 2 refers to the foreground. Other widgets may have canvases that may have other meanings, or no canvases at all. See more at [[LuaAPI/gui/widget#set_canvas]].

Here's a fun little trick. Set your dialog background to be transparent:
<syntaxhighlight lang=lua>
local function preshow(dialog)
dialog:set_canvas(1, { } )
end
</syntaxhighlight>

Or, if you want an opaque GUI background with the screen behind it blurred like what you see behind the text of a [message], you can set your window definition to "message":
<syntaxhighlight lang=lua>
...
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
definition = "message",
...
</syntaxhighlight>

{|
|Here we take our [[#Progress Bar|progress bar]], and add a text overlay.

Note: either using text on a canvas is rather limited, or I just couldn't figure it out. For example, I could not get the text size any smaller, and any attempts to do so simply resulted in very blocky text. And the spaces were necessary so that the text wasn't stretched out. I also find it surprising that the progress bar does not have this feature inherently. So it's not a great example, but it should be enough to get you started using canvases. Be sure to visit the [[LuaAPI/gui/widget#set_canvas|link]] mentioned above for more options.
|-
|[[File:Gui tutorial canvas text.png|center|thumb|A progress bar in the background, with text in the foreground]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar_with_overlay()
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.grid {
T.row {
T.column {
T.panel { id = "panel",
T.grid {
T.row {
T.column {
T.button { id = "button",
label =_ "Press me"}
},
T.column {
T.progress_bar { id = "progress" }
},
T.column {
T.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
dialog.panel:set_canvas(2, { T.text { text_alignment = "center", font_size = 48,
text_markup = true, text = " " ..
dialog.progress.percentage .. "% " } } )
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

You may notice we added a panel and placed our text on the foreground canvas(2) on it, since the progress_bar itself does not support canvases.

===Placement===

You may have noticed that all of our dialogs are centered on the screen. This is the default. You can override this and place the dialog wherever you like by setting automatic_placement = false, along with x, y, width, and height at the top level of your dialog definition (next to tooltip =, etc).

'''This part about placement needs review'''
If you prefer, you may replace x and/or y with horizontal_placement and vertical_placement, such as horizontal_placement = "left". You can even set the placement values using WFL, for example horizontal_placement = "(gamemap_width / 3)" -- see [[#Using WFL with GUI2|Using WFL with GUI2]].

==Miscellaneous==

TODO: This stuff doesn't belong in a tutorial. It's worth documenting, but not here. Better to save these here for now than keep them on my laptop.

===Progress Bar===
{|
|A progress_bar is a graphical representation of a percent. In this example, we present the user with a puzzle. They must hit the button repeatedly before they can close the GUI. A progress_bar displays their current progress toward completion.
|-
|[[File:Gui tutorial progress bar.png|center|thumb|upright=2]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.button { id = "button",
label =_ "Press me"
}
},
wml.tag.column {
wml.tag.progress_bar { id = "progress" }
},
wml.tag.column {
wml.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end

gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

===Unit Preview Pane===

{|
|A unit_preview_pane takes a unit (or a unit type), and presents a graphical representation of the unit and its more important attributes, along with tooltips for additional details, in the same way that the recall menu does. Here we see an example of a unit which has picked up some items, including a weapon, which are affecting its stats.
|-
|[[File:Gui tutorial unit preview pane.png|center|thumb]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag

function wesnoth.wml_actions.recall_from_variable(cfg)
local from_array = cfg.from or wml.error(
"[recall_from_variable]: missing required from= ")
local to_var = cfg.to or wml.error(
"[recall_from_variable]: missing required to= ")
local unit_list = wml.array_access.get(from_array) or wml.error(
string.format("[recall_from_variable]: failed to fetch wml array %s",from_array))

local listboxItem = T.grid {
T.row {
T.column {
T.label { id = "available_unit",
linked_group = "available_unit"
}
}
}
}

local listbox_id = "available_units"
local listboxDefinition = T.listbox { id = listbox_id,
T.list_definition {
T.row {
T.column {
T.toggle_panel { listboxItem }
}
}
}
}
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.linked_group { id = "available_unit", fixed_width = true },
T.grid {
T.row { -- header
T.column {
T.grid {
T.row {
T.column {
border = "bottom",
border_size = 10,
T.label {
use_markup = true,
label = ""
.. _"Select unit to recall" .. ""
}
}
}
}
}
},
T.row { -- Body
T.column {
T.grid {
T.row {
T.column {
border = "right",
border_size = 40,
listboxDefinition
},
T.column {
T.unit_preview_pane { id = "unit_preview" }
}
}
}
}
},
T.row { -- Footer
T.column {
T.grid {
T.row {
T.column {
T.spacer { width = 400 }
},
T.column {
border = "top,right",
border_size = 10,
T.button { id = "ok",
label = _"OK"
}
}
}
}
}
}
}
}

local picked = 1

local function preshow(dialog)
local listbox = dialog[listbox_id]
for i,unit in ipairs(unit_list) do
listbox[i].available_unit.label = unit.name .. "(" ..
unit.language_name .. ")"
end
local function draw_unit()
wesnoth.units.to_recall(unit_list[listbox.selected_index])
local tmp = wesnoth.units.find_on_recall{ id =
unit_list[listbox.selected_index].id }[1]
dialog.unit_preview.unit = tmp
wesnoth.units.extract(tmp)
picked = listbox.selected_index
end
draw_unit()
listbox.on_modified = draw_unit
end

gui.show_dialog(dialogDefinition,preshow)

wml.variables[to_var] = picked - 1
end

</syntaxhighlight>

This should all be pretty self evident by now. We are provided with an array of stored units (from [store_unit] in WML). We create a listbox populated with units and we use the selected_index to determine which element in the table to send to unit_preview_pane. Since our input is an array of unit data, not actual units, we use [[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] to take the definition of one from our array and place it on the recall list (turning it into an actual unit), [[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] to fetch that unit in a form that the unit_preview_panel understands, and finally [[wesnoth.units.extract|wesnoth.units.extract]] to remove the unit from the recall list when we are done with it.

And of course we subtract one from the selected_index when we return our choice to WML, since lua arrays count from 1 and WML from 0.

The unit_preview_pane will also accept a unit_type instead of a specific unit.

==Appendix==

===Explore Your Options===

We've seen a lot of options that can be set to modify the behaviour of our dialogs, some on columns, some on widgets, etc. These are in the process of being documented [[GUIWidgetInstanceWML|here]], but if you would like to go straight to the source, the data Wesnoth uses to validate your configuration can be found in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui data/schema/gui] under your install directory.

Let's look at a scroll_label, for example. A scroll_label is a widget, so we look in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/widget_instances.cfg widget_instances.cfg] and find the following. Here we can see five parameters we can provide to our scroll_label (in addition to the ones available to all widgets, like id and definition, see the entry super=... which refers you to the widget_instance in the file [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/generic.cfg data/schema/gui/generic.cfg]), along with their types and default values. For example, we could set "link_aware = true", and if we do not we can assume that link_aware will be false. While this does not explain what these parameters do, the information provided in the schema directory is often helpful nonetheless.

<syntaxhighlight lang=wml>
[tag]
name="scroll_label"
min="0"
max="infinite"
super="$generic/widget_instance"
{DEFAULT_KEY "horizontal_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "vertical_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "wrap" bool true}
{DEFAULT_KEY "text_alignment" f_h_align "left"}
{DEFAULT_KEY "link_aware" bool false}
[/tag]
</syntaxhighlight>

We see that our scrollbars are of type scrollbar_mode. It would probably help if we knew what values are available to the scrollbar_mode. In [https://github.com/wesnoth/wesnoth/tree/master/data/schema/types/gui.cfg data/schema/types/gui.cfg] we find this:

<syntaxhighlight lang=wml>
[type]
name=scrollbar_mode
value="always|never|auto|initial_auto"
[/type]
</syntaxhighlight>

The variable types found in the schema files are described at [[GUIVariable]].

Note: The keys in the schema file correspond to the attributes used when configuring your widgets. They will not always align perfectly with keys used by the Lua API. For example, the slider uses maximum_value in its configuration, and max_value when using the Lua API:

<syntaxhighlight lang=wml>
[slider]
id="my_slider"
maximum_value = 100
[/slider]
</syntaxhighlight>

<syntaxhighlight lang=lua>
dialog.my_slider.max_value = 90
</syntaxhighlight>

===Using WFL with GUI2===

If you look at the variable type descriptions at [[GUIVariable]] you may notice that many of them start with "f_" and have "or formula" in the description. This means that you can use [[Wesnoth_Formula_Language|Wesnoth Formula Language (WFL)]] formulas in these fields, with certain variables made available to you (which variables and what they mean can be challenging to ascertain, but you can generally figure it out by example).

Looking at [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/window.cfg data/schema/gui/window.cfg] we see that 'height' has type f_unsigned, which tells us that height is an unsigned integer, and that we can use a WFL formula to define it in a window_definition. In [https://github.com/wesnoth/wesnoth/tree/master/data/gui/themes/default/window/wml_message.cfg data/gui/window/wml_message.cfg] (data/gui/themes/default/window/wml_message.cfg starting around 1.19.2), we find the line '''height = "(screen_height - 30)"'''. This does exactly what it looks like, it sets the height of our window to 30 pixels less than the height of the screen.

===Useful Links===
[[GUIToolkitWML]] - Documents the keys/values available on various objects (e.g. "what attributes can I set on a column?") 
[[LuaAPI/gui|LuaAPI/gui]] - Mostly about opening windows 
[[LuaAPI/types/widget]] - Widget attributes and callbacks 
[https://wiki.wesnoth.org/Category:GUI_WML_Reference GUI_WML_Reference] 
[https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui .../data/schema/gui/*.cfg] - Lists of valid options for various GUI objects 
[https://devdocs.wesnoth.org/layout_algorithm.html Layout Algorithm] - For windows, at least

===Credits===

The basic framework that composes the initial examples was lifted from LotI. It's a great place to find well written examples, but some of it is complex enough to be a little overwhelming when getting started.

Many examples, particularly tree view and multipage, are heavily derived from the World Conquest multiplayer campaign.

LuaAPI/types/widget

2024-10-26T00:44:09Z

White haired uncle: /* Widget Attributes */ - change "All" to "Most" for attributes 'only' available to styled_widget

<div class="tright"> __TOC__ </div>

The '''widget''' userdata offers access to a widget of a GUI2 dialog. While there is only one type of widget userdata that covers all widgets including the window itself, the properties of a widget userdata are different for each type of widget. Indexing a widget's userdata can either be used to access a child widget or to set or get a property of a widget. Some properties are read-only or write-only; the properties depend on the type of the widget.

An example of accessing a child widget:

<syntaxhighlight lang=lua>
function preshow(dialog)
local okay_button = dialog.okay_button
-- okay_button is now a handle to the the widget's child with the id 'okay_button'
end
</syntaxhighlight>

== Widget Attributes ==

=== selected ===

* ''widget''.'''selected''' ↔ ''boolean''
* Available on: '''[toggle_button]''', '''[toggle_panel]'''

Whether the item is selected or not. Note that this should only be used for widgets that have only 2 states. In particular, there exist 3-State toggle_buttons (for example in listbox headers). For those, selected_index must be used instead.

=== selected_index ===

* ''widget''.'''selected_index''' ↔ ''index''
* Available on: '''[listbox]''', '''[multi_page]''', '''[stacked_widget]''', '''[menu_button]''', '''[toggle_button]''', '''[toggle_panel]'''

The selected index of the item. For '''[toggle_button]''' and '''[toggle_panel]''', this is the same as '''selected''' only encoded as a number (1 for false or 2 for true) instead of a boolean.

For a '''[listbox]'''with '''has_maximum=false''' and more than one item selected, reading '''selected_index''' will return the first selected index.

For a '''[stacked_widget]''', 0 represents all layers being visible. If one or more (but not all) layers are visible, reading '''selected_index''' returns the layer most recently made visible. Writing to '''selected_index''' will make the specified layer (or all layers if 0 is specified) visible.

=== text ===

* ''widget''.'''text''' ↔ ''text''
* Available on: '''[text_box]'''

The text of the textbox.

=== value ===

* ''widget''.'''value''' ↔ ''position''
* Available on: '''[slider]'''

The current position of the slider.

=== percentage ===

* ''widget''.'''percentage''' ↔ ''position''
* Available on: '''[progress_bar]'''

The current position of the progress bar, between 0 and 100.

=== selected_item_path ===

* ''widget''.'''selected_item_path''' → ''array of indices''
* Available on: '''[tree_view]'''

A table describing the currently selected node. If for example, in the following treeview, Item 9 is selected, the result will be {2,1,3}.

+Section1
+Subsection11
*Item1
*Item2
*Item3
+Subsection12
*Item4
*Item5
*Item6
+Section2
+Subsection21
*Item7
*Item8
*Item9
+Subsection22
*Item10
*Item11
*Item12

=== path ===

* ''widget''.'''path''' → ''array of indices''
* Available on: '''[tree_view_node]'''

A table describing this node in the overall treeview. See [[#selected_item_path|selected_item_path]] for the meaning of the table..

=== unfolded ===

* ''widget''.'''unfolded''' ← ''boolean''
* Available on: '''[tree_view_node]'''

Control whether a tree node is currently expanded or not.

=== unit ===

* ''widget''.'''unit''' ← ''unit or unit type''
* Available on: '''[unit_preview_pane]'''

Change the displayed unit or unit type in the preview pane.

=== item_count ===

* ''widget''.'''item_count''' → ''number of items''
* Available on: '''[multi_page]''', '''[listbox]'''

The number of items in the container widget.

=== use_markup ===

* ''widget''.'''use_markup''' → ''boolean''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Sets whether the widget's label will parse [[Pango formatting]].

=== label ===

* ''widget''.'''label''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]''', '''[image]'''

The widget's label. Technically this is a special string used in the widget's wml definition. It usually does what one would expect, but also sets the image for '''image''' widgets. For '''[text_box]''', use '''text''' for initial values.

=== marked_up_text ===

* ''widget''.'''marked_up_text''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Shortcut for setting label and use_markup=yes.

=== enabled ===

* ''widget''.'''enabled''' ← ''boolean''
* Available on: Most widgets

=== tooltip ===

* ''widget''.'''tooltip''' ← ''text''
* Available on: Most widgets

=== visible ===

* ''widget''.'''visible''' ← ''visibility string''
* Available on: Most widgets

Determines whether the widget is visible onscreen. The following visibility statuses are recognized:
{| clasS="wikitable"
! String value !! Boolean shorthand !! Meaning
|-
| visible || true || The widget is visible and handles events.
|-
| hidden || || The widget is not visible, doesn't handle events, but still takes up space on the dialog grid.
|-
| invisible || false || The widget is not visible, doesn't handle events, and does not take up space on the dialog grid.
|}

=== type ===

* ''widget''.'''type''' → ''string''
* Available on: All widgets

Returns a string specifying the type of the widget.

== Widget callbacks ==

=== on_modified ===

* ''widget''.'''on_modified''' ← '''function'''()
* Available on: Most widgets, in particular '''[slider]''', '''[toggle_button]''', '''[listbox]''', '''[menu_button]''', '''[text_box]'''

Triggers when the user changes the value of the widget.

=== on_left_click ===

* ''widget''.'''on_left_click''' ← '''function'''()
* Available on: All widgets

Triggers when the user clicks on the widget.

=== on_button_click ===

* ''widget''.'''on_button_click''' ← '''function'''()
* Available on: '''[button]''', '''[repeating_button]'''

Triggers when the user clicks on the button. This can differ from '''on_left_click''', depending on the type of widget. For example, on a '''[repeating_button]''' it will fire multiple times if the user holds the mouse button down.

== Widget methods ==

Any function defined in the [[LuaAPI/gui/widget|gui.widget]] module and taking a widget as its first parameter can be called as a method of a widget. This includes any functions that are added to the module by user code. Note that these methods are available even if the widget itself doesn't support that function, so in some cases it may be necessary to check '''widget.type''' befor calling the method.

[[Category:Lua Reference]]

LuaAPI/types/widget

2024-10-26T00:35:49Z

White haired uncle: /* selected_index */ - when multiple items/layers selected

<div class="tright"> __TOC__ </div>

The '''widget''' userdata offers access to a widget of a GUI2 dialog. While there is only one type of widget userdata that covers all widgets including the window itself, the properties of a widget userdata are different for each type of widget. Indexing a widget's userdata can either be used to access a child widget or to set or get a property of a widget. Some properties are read-only or write-only; the properties depend on the type of the widget.

An example of accessing a child widget:

<syntaxhighlight lang=lua>
function preshow(dialog)
local okay_button = dialog.okay_button
-- okay_button is now a handle to the the widget's child with the id 'okay_button'
end
</syntaxhighlight>

== Widget Attributes ==

=== selected ===

* ''widget''.'''selected''' ↔ ''boolean''
* Available on: '''[toggle_button]''', '''[toggle_panel]'''

Whether the item is selected or not. Note that this should only be used for widgets that have only 2 states. In particular, there exist 3-State toggle_buttons (for example in listbox headers). For those, selected_index must be used instead.

=== selected_index ===

* ''widget''.'''selected_index''' ↔ ''index''
* Available on: '''[listbox]''', '''[multi_page]''', '''[stacked_widget]''', '''[menu_button]''', '''[toggle_button]''', '''[toggle_panel]'''

The selected index of the item. For '''[toggle_button]''' and '''[toggle_panel]''', this is the same as '''selected''' only encoded as a number (1 for false or 2 for true) instead of a boolean.

For a '''[listbox]'''with '''has_maximum=false''' and more than one item selected, reading '''selected_index''' will return the first selected index.

For a '''[stacked_widget]''', 0 represents all layers being visible. If one or more (but not all) layers are visible, reading '''selected_index''' returns the layer most recently made visible. Writing to '''selected_index''' will make the specified layer (or all layers if 0 is specified) visible.

=== text ===

* ''widget''.'''text''' ↔ ''text''
* Available on: '''[text_box]'''

The text of the textbox.

=== value ===

* ''widget''.'''value''' ↔ ''position''
* Available on: '''[slider]'''

The current position of the slider.

=== percentage ===

* ''widget''.'''percentage''' ↔ ''position''
* Available on: '''[progress_bar]'''

The current position of the progress bar, between 0 and 100.

=== selected_item_path ===

* ''widget''.'''selected_item_path''' → ''array of indices''
* Available on: '''[tree_view]'''

A table describing the currently selected node. If for example, in the following treeview, Item 9 is selected, the result will be {2,1,3}.

+Section1
+Subsection11
*Item1
*Item2
*Item3
+Subsection12
*Item4
*Item5
*Item6
+Section2
+Subsection21
*Item7
*Item8
*Item9
+Subsection22
*Item10
*Item11
*Item12

=== path ===

* ''widget''.'''path''' → ''array of indices''
* Available on: '''[tree_view_node]'''

A table describing this node in the overall treeview. See [[#selected_item_path|selected_item_path]] for the meaning of the table..

=== unfolded ===

* ''widget''.'''unfolded''' ← ''boolean''
* Available on: '''[tree_view_node]'''

Control whether a tree node is currently expanded or not.

=== unit ===

* ''widget''.'''unit''' ← ''unit or unit type''
* Available on: '''[unit_preview_pane]'''

Change the displayed unit or unit type in the preview pane.

=== item_count ===

* ''widget''.'''item_count''' → ''number of items''
* Available on: '''[multi_page]''', '''[listbox]'''

The number of items in the container widget.

=== use_markup ===

* ''widget''.'''use_markup''' → ''boolean''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Sets whether the widget's label will parse [[Pango formatting]].

=== label ===

* ''widget''.'''label''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]''', '''[image]'''

The widget's label. Technically this is a special string used in the widget's wml definition. It usually does what one would expect, but also sets the image for '''image''' widgets. For '''[text_box]''', use '''text''' for initial values.

=== marked_up_text ===

* ''widget''.'''marked_up_text''' ← ''text''
* Available on: Most widgets, in particular '''[label]''', '''[button]'''

Shortcut for setting label and use_markup=yes.

=== enabled ===

* ''widget''.'''enabled''' ← ''boolean''
* Available on: All widgets

=== tooltip ===

* ''widget''.'''tooltip''' ← ''text''
* Available on: All widgets

=== visible ===

* ''widget''.'''visible''' ← ''visibility string''
* Available on: All widgets

Determines whether the widget is visible onscreen. The following visibility statuses are recognized:
{| clasS="wikitable"
! String value !! Boolean shorthand !! Meaning
|-
| visible || true || The widget is visible and handles events.
|-
| hidden || || The widget is not visible, doesn't handle events, but still takes up space on the dialog grid.
|-
| invisible || false || The widget is not visible, doesn't handle events, and does not take up space on the dialog grid.
|}

=== type ===

* ''widget''.'''type''' → ''string''
* Available on: All widgets

Returns a string specifying the type of the widget.

== Widget callbacks ==

=== on_modified ===

* ''widget''.'''on_modified''' ← '''function'''()
* Available on: Most widgets, in particular '''[slider]''', '''[toggle_button]''', '''[listbox]''', '''[menu_button]''', '''[text_box]'''

Triggers when the user changes the value of the widget.

=== on_left_click ===

* ''widget''.'''on_left_click''' ← '''function'''()
* Available on: All widgets

Triggers when the user clicks on the widget.

=== on_button_click ===

* ''widget''.'''on_button_click''' ← '''function'''()
* Available on: '''[button]''', '''[repeating_button]'''

Triggers when the user clicks on the button. This can differ from '''on_left_click''', depending on the type of widget. For example, on a '''[repeating_button]''' it will fire multiple times if the user holds the mouse button down.

== Widget methods ==

Any function defined in the [[LuaAPI/gui/widget|gui.widget]] module and taking a widget as its first parameter can be called as a method of a widget. This includes any functions that are added to the module by user code. Note that these methods are available even if the widget itself doesn't support that function, so in some cases it may be necessary to check '''widget.type''' befor calling the method.

[[Category:Lua Reference]]

GUIWidgetInstanceWML

2024-10-25T18:05:19Z

White haired uncle: /* Multiline Text */ - use scroll_text in GUIs

== Widget instance ==
Inside a grid (which is inside all container widgets) a widget is
instantiated. With this instantiation some more variables of a widget can
be tuned. This page will describe what can be tuned.

== Widget ==
All widgets placed in the cell have some values in common:
{| class="wikitable"
!key
!type
!default
!description
|-
| id
| [[GUIVariable#string|string]]
| ""
| This value is used for the engine to identify 'special' items. This means that for example a text_box can get the proper initial value. This value should be unique or empty. Those special values are documented at the window definition that uses them. NOTE items starting with an underscore are used for composed widgets and these should be unique per composed widget.
|-
| definition
| [[GUIVariable#string|string]]
| "default"
| The id of the widget definition to use. This way it's possible to select a specific version of the widget e.g. a title label when the label is used as title.
|-
| linked_group
| [[GUIVariable#string|string]]
| ""
| The linked group the control belongs to.
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| Most widgets have some text associated with them, this field contain the value of that text. Some widgets use this value for other purposes, this is documented at the widget. E.g. an image uses the filename in this field.
|-
| tooltip
| [[GUIVariable#t_string|t_string]]
| ""
| If you hover over a widget a while (the time it takes can differ per widget) a short help can show up.This defines the text of that message. This field may not be empty when 'help' is set.
|-
| help
| [[GUIVariable#t_string|t_string]]
| ""
| If you hover over a widget and press F10 (or the key the user defined for the help tip) a help message can show up. This help message might be the same as the tooltip but in general (if used) this message should show more help. This defines the text of that message.
|-
| use_tooltip_on_label_overflow
| [[GUIVariable#bool|bool]]
| true
| If the text on the label is truncated and the tooltip is empty the label can be used for the tooltip. If this variable is set to true this will happen.
|-
| debug_border_mode
| [[GUIVariable#unsigned|unsigned]]
| 0
| The mode for showing the debug border. This border shows the area reserved for a widget. This function is only meant for debugging and might not be available in all Wesnoth binaries. Available modes:
* '''0:''' no border.
* '''1:''' 1 pixel border.
* '''2:''' floodfill the widget area.
|-
| debug_border_color
| [[GUIVariable#color|color]]
| ""
| The color of the debug border.
|-
| size_text
| [[GUIVariable#t_string|t_string]]
| ""
| Sets the minimum width of the widget depending on the text in it. (Note not implemented yet.)
|}

== Button ==
A button is a control that can be pushed to start an action or close a dialog.

Instance of a button. When a button has a return value it sets the
return value for the window. Normally this closes the window and returns
this value to the caller. The return value can either be defined by the
user or determined from the id of the button. The return value has a
higher precedence as the one defined by the id. (Of course it's weird to
give a button an id and then override its return value.)

When the button doesn't have a standard id, but you still want to use the
return value of that id, use return_value_id instead. This has a higher
precedence as return_value.

List with the button specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

Supported values for return_value_id:
{| class="wikitable"
!string
!value
!description
|-
|"ok"||-1||Equivalent to closing the dialog by pressing the Enter key
|-
|"cancel"||-2||Equivalent to closing the dialog by pressing the Esc key
|-
|"quit"||-2||An alias for cancel
|-
|""||N/A||Clears any previously set return_value_id
|}

== Combobox ==
[[File:Combobox.png|frame|right|A Combobox with its list open]]
A widget with a text box and a dropdown list. Selecting an element from the list sets the value of the text box to that item of the list. The user can also manually enter a value in the text box.

{| class="wikitable"
|-
! key !! type !! default !! description
|-
| label || [[GUIVariable#string|string]] || "" || The text of the combobox
|-
| max_input_length || [[GUIVariable#int|int]] || 0 || Maximum length of text in characters that can be entered into the combobox
|-
| hint_text || [[GUIVariable#string|string]] || "" || Text that is shown in the background when there is no input
|-
| hint_image || [[GUIVariable#string|string]] || "" || Image that is shown in the background when there is no input

|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>combobox</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| icon || [[GUIVariable#string|string]] || "" || WML path to the icon to be shown alongside the text in this option, if any.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Drawing ==
A drawing is widget with a fixed size and gives access to the canvas of the widget in the window instance. This allows special display only widgets.

If either the width or the height is not zero the drawing functions as a
fixed size drawing.

{| class="wikitable"
!key
!type
!default
!description
|-
| width
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the drawing.
|-
| height
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the drawing.
|-
| draw
| [[GUIVariable#config|config]]
| mandatory
| The config containing the drawing.
|}

The variable available are the same as for the window resolution see
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
items.

== Grid Listbox ==
List with the listbox specific variables:
{| class="wikitable"
!ID (return value)
!Type
!Mandatory
!Description
|-
| vertical_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIToolkitWML#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIToolkitWML#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, more than one row can be selected.
|}

== Horizontal listbox ==
A horizontal listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version orders them in columns instead.

List with the horizontal listbox specific variables:
{| class="wikitable"
!ID (return value)
!Type
!Mandatory
!Description
|-
| vertical_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIToolkitWML#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIToolkitWML#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, more than one row can be selected.
|}

In order to force widgets to be the same size inside a horizontal listbox,
the widgets need to be inside a linked_group.

Inside the list section there are only the following widgets allowed
* grid (to nest)
* selectable widgets which are
** toggle_button
** toggle_panel

== Image ==
An image shows a static image whose path is specified by its '''[[GUIWidgetInstanceWML#Widget|label]]''' key. Unlike other widgets, the '''label''' key here is not translatable since it specifies a path. The path is a standard WML path, i.e., <code>label="units/konrad.png"</code> or <code>label="~add-ons/MyAddon/image/test.png"</code>.

It has no other extra fields.

== Label ==
A label displays text provided via the '''[[GUIWidgetInstanceWML#Widget|label]]''' key that can be wrapped but no scrollbars are provided. For a version with scrollbars, see the [[GUIWidgetInstanceWML#Scroll_Label|Scroll Label]] widget.

[[File:Title Label.png|frame|right|A Label with definition "title"]]

List with the label specific variables:
{| class="wikitable"
!key !!type !!default !!description
|-
| wrap || [[GUIVariable#bool|bool]] || false || Is wrapping enabled for the label.
|-
| characters_per_line || [[GUIVariable#unsigned|unsigned]] || 0 || Sets the maximum number of characters per line. The amount is an approximate since the width of a character differs. E.g. iii is smaller than MMM. When the value is non-zero it also implies '''can_wrap''' is true.
When having long strings, wrapping them can increase readability. A rule of thumb is 66 characters per line is considered the optimum for a one column text.
|-
| text_alignment || [[GUIVariable#h_align|h_align]] || left || The way the text is aligned inside the canvas.
|-
| can_shrink || [[GUIVariable#bool|bool]] || false || Whether the label can shrink past its optimal size.
|-
| link_aware || [[GUIVariable#bool|bool]] || false || Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
|}

== Listbox ==
A listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version might allow more options for ordering the items in the future.

List with the listbox specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIVariable#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIVariable#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIVariable#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIVariable#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIVariable#bool|bool]]
| true
| If false, more than one row can be selected.
|}

In order to force widgets to be the same size inside a listbox, the widgets
need to be inside a linked_group.

Inside the list section there are only the following widgets allowed
* grid (to nest)
* selectable widgets which are
** toggle_button
** toggle_panel

== Matrix ==
List with the matrix specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|}

== Menu Button ==
[[File:Menu Button.png|thumb|left|A Menu Button with it's list open.]]
A button that shows a dropdown list when clicked. The user can select any one of the predefined options.
{| class="wikitable"
!key
!type
!default
!description
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>menu_button</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| icon || [[GUIVariable#string|string]] || "" || WML path to the icon to be shown alongside the text in this option, if any.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Minimap ==
A minimap to show the gamemap, this only shows the map and has no interaction options. This version is used for map previews, there will be a another version which allows interaction.

A minimap has no extra fields.

== Multiline Text ==
Base class for a multiline text area. Not to be used directly in a GUI, use the [[GUIWidgetInstanceWML#Scroll_Text|scroll_text]] widget instead.

The following variables exist:
{| class="wikitable"
!key
!type
!default
!description
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| The initial text of the text box.
|-
| history
| [[GUIVariable#string|string]]
| ""
| The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
|-
| editable
| [[GUIVariable#bool|bool]]
| "true"
| If the contents of the text box can be edited.
|}

== Multimenu Button ==
[[File:Multimenu Button.png|thumb|right|A Multimenu Button with its list open]]
A widget clicking on which shows a list from which one or more options can be selected.

List with the multimenu_button specific variables:
{| class="wikitable"
!key !!type !!default !!description
|-
| return_value_id || [[GUIVariable#string|string]] || "" || The return value id.
|-
| return_value || [[GUIVariable#int|int]] || 0 || The return value.
|-
| maximum_shown || [[GUIVariable#int|int]] || -1 || The maximum number of currently selected values to list on the button.
|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>multimenu_button</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| checkbox || [[GUIVariable#bool|bool]] || "" || Whether the checkbox alongside this option is selected or not.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Multi page ==
A multi page is a control that contains several 'pages' of which only one is visible. The pages can contain the same widgets containing the same 'kind' of data or look completely different.

List with the multi page specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| page_definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a multi page item looks. It must contain the grid definition for at least one page.
|-
| page_data
| [[GUIVariable#section|section]]
| []
| A grid alike section which stores the initial data for the multi page. Every row must have the same number of columns as the 'page_definition'.
|}

== Panel ==
A panel is an item which can hold other items. The difference between a grid and a panel is that it's possible to define how a panel looks. A grid in an invisible container to just hold the items.

{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|}

== Password box ==
{| class="wikitable"
!key
!type
!default
!description
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| The initial text of the password box.
|}

== Progress bar ==
A progress bar shows the progress of a certain object.

A progress bar has no extra fields.

== Repeating button ==
A repeating_button is a control that can be pushed down and repeat a certain action. Once the button is down every x milliseconds it is down a new down event is triggered.

== Rich Label ==
A label that shows formatted text marked up with [[Help markup]]. It can show embedded images, links and tables inside text.

{| class="wikitable"
!key !!type !!default !!description
|-
| text_alignment || [[GUIVariable#h_align|h_align]] || left || The way the text is aligned inside the canvas.
|-
| width || [[GUIVariable#int|int]] || 500 || Width of its internal formatted content. Text will wrap beyond this width.
|-
| link_aware || [[GUIVariable#bool|bool]] || false || Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
|}

== Scroll label ==
A scroll label is a label that wraps its text and also has a vertical scrollbar. This way a text can't be too long to be shown for this widget.

List with the scroll label specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|}

== Scrollbar panel ==
Instance of a scrollbar_panel.

List with the scrollbar_panel specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a scrollbar_panel item looks. It must contain the grid definition for 1 row of the list.
|}

== Spacer ==
A spacer is a dummy item to either fill in a widget since no empty items are allowed or to reserve a fixed space.

If either the width or the height is non-zero the spacer functions as a
fixed size spacer.

{| class="wikitable"
!key !!type !!default !!description
|-
| width || [[GUIVariable#f_unsigned|f_unsigned]] || 0 || The width of the spacer.
|-
| height || [[GUIVariable#f_unsigned|f_unsigned]] || 0 || The height of the spacer.
|}

The variable available are the same as for the window resolution see
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
items.

== Tab Container ==

A container widget that can show its contents separated into various pages, each of which are accessible.

It can contain one or more <code>[tab]</code> tags inside it, each defining a tab's name, image (if any) and the contents of the tag, specified by the <code>[data]</code> tag inside the <code>[tab]</code> tag.

=== Subtag [tab] ===

{| class = "wikitable"
!key !!type !!default !!description
|-
| name || [[GUIVariable#t_string|t_string]] || "" || Name of the tab
|-
| image || [[GUIVariable#string|string]] || "" || Image for the tab to be shown alongside the name, if any
|-
| [data] || [[GUIVariable#grid|grid]] || empty grid || This subtag contains a grid that defines the contents for this tab.
|}

== Text box ==
A single line text entry widget.

[[File:Text Box.png|frame|right|A Text Box]]

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || The initial text of the text box.
|-
| history || [[GUIVariable#string|string]] || "" || The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
|-
| max_input_length || [[GUIVariable#int|int]] || 0 || Maximum length of text in characters that can be entered into the combobox
|-
| hint_text || [[GUIVariable#string|string]] || "" || Text that is shown in the background when there is no input
|-
| hint_image || [[GUIVariable#string|string]] || "" || Image that is shown in the background when there is no input
|-
| editable || [[GUIVariable#bool|bool]] || "true" || If the contents of the text box can be edited.
|}

== Toggle panel ==
A toggle panel is an item which can hold other items. The difference between
a grid and a panel is that it's possible to define how a panel looks. A grid
in an invisible container to just hold the items. The toggle panel is a
combination of the panel and a toggle button, it allows a toggle button with
its own grid.

Variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id, see [[GUIToolkitWML#Button]] for more information.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value, see [[GUIToolkitWML#Button]] for more information.
|}

== Tree view ==
A tree view is a control that holds several items of the same or different types. The items shown are called tree view nodes and when a node has children, these can be shown or hidden. Nodes that contain children need to provide a clickable button in order to fold or unfold the children.

List with the tree view specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| indention_step_size
| [[GUIVariable#unsigned|unsigned]]
| 0
| The number of pixels every level of nodes is indented from the previous level.
|-
| node
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The tree view can contain multiple node sections. This part needs more documentation.
|-
| id
| [[GUIVariable#unsigned|unsigned]]
| ""
| .
|-
| return_value_id
| [[GUIVariable#unsigned|unsigned]]
| ""
| .
|}

NOTE more documentation and examples are needed.

== Vertical scrollbar ==

== Viewport ==
A viewport is an special widget used to view only a part of the widget it `holds'.

List with the viewport specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grow_direction
| [[GUIVariable#grow_direction|grow_direction]]
| mandatory
| The direction in which new items grow.
|-
| parallel_items
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The number of items that are growing in parallel.
|-
| item_definition
| [[GUIVariable#section|section]]
| mandatory
| The definition of a new item.
|}

== Scroll Text ==
A multiline text area that shows a scrollbar if the text gets too long.

List with the scrollbar container specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| editable
| [[GUIVariable#bool|bool]]
| "true"
| If the contents of this scroll_text can be edited.
|}

== Slider ==

A slider is a control that can select a value by moving a grip on a groove.

{| class="wikitable"
!key
!type
!default
!description
|-
| best_slider_length
| [[GUIVariable#unsigned|unsigned]]
| 0
| The best length for the sliding part.
|-
| minimum_value
| [[GUIVariable#int|int]]
| 0
| The minimum value the slider can have.
|-
| maximum_value
| [[GUIVariable#int|int]]
| 0
| The maximum value the slider can have.
|-
| step_size
| [[GUIVariable#unsigned|unsigned]]
| 0
| The number of items the slider's value increases with one step.
|-
| value
| [[GUIVariable#int|int]]
| 0
| The value of the slider.
|-
| minimum_value_label
| [[GUIVariable#t_string|t_string]]
| ""
| If the minimum value is chosen there might be the need for a special value (eg off). When this key has a value that value will be shown if the minimum is selected.
|-
| maximum_value_label
| [[GUIVariable#t_string|t_string]]
| ""
| If the maximum value is chosen there might be the need for a special value (eg unlimited)). When this key has a value that value will be shown if the maximum is selected.
|}

== Toggle button ==
Variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

Talk:GUIWidgetDefinitionWML

2024-10-24T15:07:47Z

White haired uncle: Created page with "There are two sections for Scrollbar Panel. It's not clear to me why. ~~~~"

There are two sections for Scrollbar Panel. It's not clear to me why.
[[User:White haired uncle|White haired uncle]] ([[User talk:White haired uncle|talk]]) 15:07, 24 October 2024 (UTC)

LuaAPI/gui/widget

2024-10-21T21:04:55Z

White haired uncle: Add clear()

The '''gui.widget''' module contains functions for managing widgets in custom GUI2 dialogs. Since these functions take a [[LuaAPI/types/widget|widget userdata]] as the first parameter, they can only be used in the preshow or postshow of a GUI2 dialog (directly or indirectly). However, the table is available at all times, and additional methods can be installed here for unusual needs.

'''Note:''' The '''gui.widget.set_callback''' is a compatibility wrapper and is unsupported. It may be removed without warning. Callbacks should be bound by assigning the appropriate callback key on the widget.

=== focus ===

* '''gui.widget.focus'''(''widget'')
* ''widget'':'''focus'''()

Switches the keyboard focus to the widget. This is often useful for dialogs containing a central listbox, so that it can be controlled with the keyboard as soon as it is displayed.

=== set_canvas ===

* '''gui.widget.set_canvas'''(''widget'', ''layer index'', ''content'')
* ''widget'':'''set_canvas'''(''layer index'', ''content'')

Sets the WML passed as the second argument as the canvas content (index given by the first argument) of the widget. The content of the WML table depends on which shape is used:

* [[GUICanvasWML#Circle|Circle]]
* [[GUICanvasWML#Image|Image]]
* [[GUICanvasWML#Line|Line]]
* [[GUICanvasWML#Bounded_Shape|common attributes of rectangles, round rectangles and text]]
* [[GUICanvasWML#Rectangle|Rectangle]]
* [[GUICanvasWML#Rounded_Rectangle|Rounded Rectangle]]
* [[GUICanvasWML#Text|Text]]

<syntaxhighlight lang=lua>
-- draw two rectangles in the upper-left corner of the window (assume dialog is the window widget)
dialog:set_canvas(2, {
wml.tag.rectangle { x = 20, y = 20, w = 20, h = 20, fill_color= "0,0,255,255" },
wml.tag.rectangle { x = 30, y = 30, w = 20, h = 20, fill_color = "255,0,0,255" }
})
</syntaxhighlight>

The meaning of the canvas index depends on the chosen widget. It may be the disabled / enabled states of the widget, or its background / foreground planes, or... For instance, overwriting canvas 1 of the window with an empty canvas causes the window to become transparent.

=== add_item ===

* '''gui.widget.add_item'''(''widget'', [''position'']) → ''the new item'', ''position''
* ''widget'':'''add_item'''([''position'']) → ''the new item'', ''position''

Add an item to a container widget, for example a listbox. Returns the created item as a [[LuaAPI/types/widget|widget userdata]].

=== add_item_of_type ===

* '''gui.widget.add_item_of_type'''(''widget'', ''category'', [''position'']) → ''the new item'', ''position''
* ''widget'':'''add_item_of_type'''(''category'', [''position'']) → ''the new item'', ''position''

Add an item to a widget which is a heterogeneous container of different types of widgets, in particular multi_pages and treeviews.

=== remove_items_at ===

* '''gui.widget.remove_items_at'''(''widget'', ''position'', ''count'')
* ''widget'':'''remove_items_at'''(''position'', ''count'')

Removes one or more elements of a container type widget (like treeviews), starting at the given index. If 0 is passed as the count, all elements from that point to the end are removed. Otherwise, the specified number of elements are removed.

=== clear ===
{{DevFeature1.19|5}}

* '''gui.widget.clear'''(''widget'')
* ''widget'':'''clear'''()

Removes all elements of a container type widget.

=== find ===

* '''gui.widget.find'''(''root widget'', ...)
* ''widget'':'''find'''(...)

Finds a child widget of the widget of the given path. For example, here it searches for the widget with the id 'preview_panel' of the second item of the widget with the id 'unit_list':

<syntaxhighlight lang=lua>
dialog:find('unit_list', 2, 'preview_panel')
</syntaxhighlight>

This is more or less equivalent to the following:

<syntaxhighlight lang=lua>
dialog.unit_list[2].preview_panel
</syntaxhighlight>

However, if the path comes from a variable, the functional form may be more convenient:

<syntaxhighlight lang=lua>
dialog:find(table.unpack(path))
</syntaxhighlight>

=== close ===

* '''gui.widget.close'''(''dialog'')
* ''widget'':'''close'''()

Closes the dialog.

[[Category:Lua Reference]]

Sandbox/GUI/Getting Started

2024-09-29T16:06:39Z

White haired uncle: /* Listbox */

So, it looks like I can't exclude this page/section from the search engine as I had hoped. I wanted to put this in a sandbox so that it wouldn't be published without some proper review.

==Introduction==

This guide is designed to help you get a simple Wesnoth GUI, implemented in lua, up and running while describing the basic building blocks along the way. It is written in a narrative format, where most examples build on previous examples, and therefore while not always necessary it may be desirable to read from start to finish. The reader, probably a UMC author, should have a basic knowledge of working with lua within Wesnoth.

Some would find creating a GUI in part or in full using WML simpler to follow, and those alternatives are available, for example [[LuaAPI/gui/example]], but we're using lua here. If you find WML easier to follow, you can always convert the lua tables that define the GUIs to WML using [[LuaAPI/wml#wml.tostring|wml.tostring]], for example:

<syntaxhighlight lang=lua>
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
</syntaxhighlight>

In some examples, instead of defining the entire GUI at once, we'll break out some parts into separate variables. If you try to view one in WML and get an error from wml.tostring() about expecting a WML table and not a table, try passing your variable(/table) inside a table:

<syntaxhighlight lang=lua>
print(wml.tostring({listboxItem}))
gui.show_lua_console()
</syntaxhighlight>

One distinct advantage of using WML to define your GUI layout is that you get better (any) validation. Invalid keys, and sometimes values, are often flagged in the log, unlike with lua where they are silently ignored. In the comments of our first GUI, below, is an example which loads a WML GUI configuration using [[LuaAPI/wml#wml.load|wml.load()]], validating against the GUI2 window schema.

===What is GUI2?===
Once upon a time, Wesnoth had a GUI system which is now commonly referred to as GUI1. As of 1.19, GUI1 has been almost completely replaced by GUI2. UMC authors will probably never encounter GUI1 and can simply use the terms GUI and GUI2 interchangeably, at least until GUI3 comes along.

Instead of spending a lot of time here giving an overview of what GUI2 is and what makes it great, and not so great, let's charge ahead so we can see it in action, and let readers who are interested look elsewhere(TODO: link) for a more formal definition. (TODO: is this the right approach for most readers?).

==Getting Started==

For example purposes, we'll create a directory in our campaign directory called lua containing a file called gui_tutorial.lua, and add a command in the prestart event for a scenario which will create a right-click menu option to invoke our new GUI. Of course there are other methods to invoke lua from WML, but this one will get us started. After all, we really just want to get something up on the screen ASAP, right?

===A most basic GUI===

{|
|[[File:Most basic gui.png|center|thumb|I can't believe this worked]]
|-
|In our prestart event, we create a simple menu item, which executes a single line of lua which calls the lua function most_basic_gui() which is found in gui_tutorial.lua:
|}

<syntaxhighlight lang=wml>
[set_menu_item]
id=most_basic_gui
description="Our first GUI"
[command]
[lua]
code=<<
wesnoth.require("~add-ons/<OUR_CAMPAIGN>/lua/gui_tutorial.lua").most_basic_gui()
>>
[/lua]
[/command]
[/set_menu_item]
</syntaxhighlight>

And create gui_tutorial.lua:
{| class="wikitable" style="margin:auto"
! !! The WML equivalent of dialogDefinition
|-
|
<syntaxhighlight lang=lua>
local function most_basic_gui()
local dialogDefinition = {
--click_dismiss = true, -- allow user to close dialog with click of a button
wml.tag.tooltip { id = "tooltip_large" }, -- required
wml.tag.helptip { id = "tooltip_large" }, -- required
wml.tag.grid { -- our most basic gui
wml.tag.row { -- a grid must include at least one row
wml.tag.column { -- a row needs a column
wml.tag.image { -- a column includes exactly one widget
label = "units/trolls/grunt.png"
}
}
}
}
}

local function preshow(dialog)
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
end
gui.show_dialog(dialogDefinition,preshow)

-- Or, if you want to define the gui in WML, something like:
-- local dialog_wml = wml.load("~add-ons/GUI_Tutorial/most_basic_gui.cfg",
-- true, "schema/gui_window.cfg")
-- gui.show_dialog(wml.get_child(dialog_wml, 'resolution'))
end
return { most_basic_gui = most_basic_gui}
</syntaxhighlight>
|
<syntaxhighlight lang=wml>
[tooltip]
id="tooltip_large"
[/tooltip]
[helptip]
id="tooltip_large"
[/helptip]
[grid]
[row]
[column]
[image]
label="units/trolls/grunt.png"
[/image]
[/column]
[/row]
[/grid]

</syntaxhighlight>
|}

In the above file, we have just the single function to create our GUI, followed by a return command which makes our function most_basic_gui() available to the [[LuaAPI/wesnoth#wesnoth.require|wesnoth.require()]] function as most_basic_gui().

Our function creates a table containing the definition of a "dialog", and then passes that to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]]. It should be noted that gui.show_dialog does not provide synchronization, so if your GUI makes changes to the game state, you'll need to jump through some hoops or you'll break replays and multiplayer, but that's not something we need to care about at this point, so just be aware that you may need to deal with it in the future.

Our dialog definition at this point includes three parts. The first two are a tooltip and a helptip, which are required and define how tooltips (use id = "tooltip_large" or id = "tooltip" or id = "tooltip_transparent"), and helptips (rarely used, but must be included here, and yes their definitions are "tooltip" not "helptip") will look (as we will see later, this really should be definition = "tooltip", but in this case it's id = "tooltip"). The third part is a grid, which is basically a table, like in HTML or MySQL, with rows and columns. A grid always contains at least one row. A row contains at least one column (note that a column does NOT span rows, it is completely contained within a row). Inside a column is exactly one item, a cell which contains a [[GUIWidgetDefinitionWML|widget]], in this case we'll use an image (later we'll see what else we can put in a cell). Note that we don't actually define a cell in our code, it's just a term used to refer to the contents of a column.

The preshow function is optional. If included in the call to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]], it is run before the GUI is displayed. In this case, we include it to display the dialog we created with lua in WML format. Near the end, in comments, we show how you would call [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] if you chose to define your dialog using WML. Note that what is shown here is the WML equivalent of our lua dialogDefinition, and not the complete WML you would need to use if you were to configure your GUI layout in WML.

Note: if you should try out the above, you'll have to hit escape or enter to close the GUI. Uncomment the "click_dismiss" line, and the user will be able to close the GUI with a mouse click.

===Adding a little flavor===

{|
|You may have noticed our GUI is missing a header and a way to close it when we're done admiring our work. Here we add a new first row to our grid, while demonstrating a couple formatting options: a border to put some distance between our grid cell and its neighbor, and the "use_markup = true" option to enable Pango support in our text.

Our third row adds an OK button at the bottom. You can associate actions with buttons to do all kinds of things, but here we just exploit the default behaviour to close the GUI.

Of course, we'll also have to modify our return to support the new function, and update our menu item(s) accordingly.
|-
|[[File:Most basic gui2.png|center|thumb|Adding header and a footer]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui2()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
gui.show_dialog(dialogDefinition)
end
return { most_basic_gui = most_basic_gui, most_basic_gui2 = most_basic_gui2 }
</syntaxhighlight>

===And a bit more===
{|

|And now a minor, but important change. We want to add a new text field next to the image in the body of our GUI. Obviously, we want to add a new column, but this is more difficult than when we added new rows in the previous example. The problem is that all rows (at a given level) in a grid must contain the same number of columns. We can't have two columns in the row that constitutes the body of our GUI, but only one in the header and one in the footer. To solve this problem, we replace our image widget with a new grid, which can use as many columns as we like (as long as they are the same within each row of our new grid). This new grid contains a row with two columns, but that is okay because the new grid itself is placed in a single column, which matches our single column header and footer (ok button), keeping the rows balanced.
|-
|[[File:Most basic gui3.png|center|thumb|Rows with different numbers of columns]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui3()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column { -- This is the only column in this row,
-- to match the number of columns in
-- the rows of our header and footer
wml.tag.grid { -- A new grid, so we can use a different
-- number of columns
wml.tag.row {
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
},
wml.tag.column {
wml.tag.label {
label = "A troll"
}
}
}
}
}
},
wml.tag.row { -- A footer
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = "Ok"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

While we see here just the simplest of examples, you can many levels of grids in grids, rows with multiple columns some of which containing grids, etc, to build complicated dialogs to your liking.

==Containers==

===Stacked Widget===

TODO

===Listbox===
{|
| Now we'd like to add some more monsters. Obviously, we could just add more rows, but what if we won't know until runtime how many and which ones? We could break up the definition of our dialog and add new rows dynamically, it's just a table after all, but fortunately we have a widget which handles this for us, a listbox. A listbox is kind of like an array, a collection of similar objects where the number of items can vary. We will tell the GUI where we want the box, and what each entry in the box will look like, and then at runtime we can add entries to the box.

Note that listbox items are added from top to bottom. Another container, the horizontal_listbox, works just like a listbox except the items are added from left to right.
|-
| [[File:Gui with listbox.png|center|thumb|Listbox with three items. Each item is an image and a label. The third item has been selected.]]

<syntaxhighlight lang=lua>
local function gui_with_listbox()
local monsters = {
{ image = "units/trolls/grunt.png",
string = "A troll" },
{ image = "units/monsters/cuttlefish.png",
string = "A cuttlefish" },
{ image = "units/monsters/yeti.png",
string = "A yeti" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
}

local listboxDefinition = wml.tag.listbox { id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
listboxDefinition
}
},
wml.tag.row {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_label.label = monster.string
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We begin by creating a simple table which represents the data which will be presented in our listbox. In most cases, we probably wouldn't create that monster table here, but we need it for our example.

The variable listbox_id gives us an identifier for our listbox so we can reference it when we need to. We don't really need to use a variable here, it's just convenient.

We define the structure for the elements in our listbox, stored in listboxItem. Note that we've replaced the actual data with identifiers (e.g. 'units/trolls/grunt.png' becomes 'id = "monster_image"), since each element may have different data.

We define the listbox itself, specifying the identifier, and the definition of our listbox element (which looks a lot like a grid). The cell inside the column contains a variable which is just the listbox element definition we created above; it's not necessary to do this, we could have used one big table, but it's easier to read this way (IMO).

We replace the hardcoded data in our GUI body with our new listbox definition, again using a variable to make it easier to read.

We create a function, often called preshow(), which will be called for us as part of the drawing the GUI (see the new optional argument in [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] -- there's also an optional postshow(), but we don't need it here). This is where we pull the data from our example table into the listbox. We create a listbox variable associated with the listbox, identified by the listbox_id we assigned earlier, inside the dialog which gui.show_dialog() passes to preshow(). Then we iterate through our data table, using each entry from that table to populate a listbox item.

Let's look at that last action a little more closely using an example.

<syntaxhighlight lang=lua>
listbox[i].monster_image.label = monster.image
</syntaxhighlight>

Which we can read as "In listbox element i of our listbox, for the image with identifier monster_image which we defined in our listboxItem, use the data from the corresponding index i in our example data table" (you don't see the index i for the monsters table here, but remember we're iterating using ipairs, we could have just as easily used listbox[i].monster_image.label = monsters[i].image). If you were to step through all of the variable substitutions, you'd see that for i=1, our dialogDefinition is basically the same thing as it was in the earlier examples, just supplied from a table instead of hardcoded (note that you can hardcode entries in a listbox in your dialog definition using the [list_data] tag, aka wml.tag.list_data, which we do not demonstrate here).

You will probably notice that our data does not line up nicely in the GUI. We will fix that later. We'll also demonstrate how the user can select an item in a listbox, and how you can identify which item that was using the selected_index variable of the listbox.

===Tree View===
====Simple Tree View====
{|
| You may have noticed that clicking on a listbox item in our listbox caused it to be highlighted with a box around the contents. This is because the items in a listbox are selectable. This will be useful when we want to add actions, but it looks a bit odd if we just want to present a list of data.

Also, most of the data had to be formatted the same for each item in the listbox. We could, perhaps, include custom markup in our labels, but the actual layout, like the number of columns per row, had to be the same for every item.

Another way to present a list of data is the tree view. Since a tree view supports multiple data types, we may need to create multiple definitions for the elements in our list. These are known as nodes. It will also be necessary to explicitly define which node to use for each element when we populate our tree view.
|-
| [[File:Basic tree view.png|center|thumb|Tree_views can hold multiple data types (only trolls have names here)]]
|}
<syntaxhighlight lang=lua line>
local function basic_tree_view()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", type = "Seamonsters" },
{ image = "units/monsters/yeti.png", label = "A yeti",
type = "Coolers" }
}

local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "trolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name",
linked_group = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
},
wml.tag.node {
id = "nottrolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "monster_name",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_image",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_label",
fixed_width = true
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_tv:add_item_of_type("trolls_node")
dialog.monsters_tv[i].monster_name.label = monster.name -- only trolls have a name
else
dialog.monsters_tv:add_item_of_type("nottrolls_node")
end
-- All of our monsters have an image and a label
dialog.monsters_tv[i].monster_image.label = monster.image
dialog.monsters_tv[i].monster_label.label = monster.label
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We have expanded our list of monsters to include three types of trolls. We have also given each troll a name. This is of course a rather simplistic example, we could have simply given each monster that is not a troll an empty name, but it as presented here our approach serves the purpose of demonstrating how we deal with multiple data types. Our new tree view contains a node for each type of data we will present. In preshow, we explicitly define each element in our list using add_item_of_type(), and populate the item accordingly. [Note: in our listbox example, we could have used add_item() to add items to the listbox, but chose not to since that section was already introducing a number of new concepts. But here, since we have multiple types of items we need to be able to specify the type of the item when we add one, hence we need to use add_item_of_type()].

You may also note the addition of a few linked_group lines. We'll cover linked groups in more detail later, but as used here they instruct the GUI that each column using the same node type needs to be aligned with the others. For example, all of our trolls line up nicely.

====Building a Tree====
{|
| colspan="2" |At this point, one may wonder about the name "tree view", since what he have seen doesn't look much like a tree. To make a tree-like structure, we'll demonstrate adding children to nodes. At the top level our (upside-down) tree will have two nodes, one for trolls and one for everything else. A toggle_button (a type of button which changes states when you push it) will allow us to expand the trolls node to expose its children, which are themselves nodes, though they only contain a label at this point.
|-
| [[File:Basic tree view2a.png|center|thumb|Tree_view with Trolls folded]] || [[File:Basic tree view2b.png|center|thumb|Tree_view with Trolls unfolded]]
|}
<syntaxhighlight lang=lua line>
local function building_a_tree()
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
}
},
wml.tag.column {
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Show me the " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
-- You can refer to an object by its position

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[1].race_label.label = "Trolls"
-- dialog.monsters_tv[1].race_button.on_modified =
-- function()dialog.monsters_tv[1].unfolded =
-- dialog.monsters_tv[1].race_button.selected end

-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][1].monster_type.label = "Whelp"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][2].monster_type.label = "Shaman"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][3].monster_type.label = "Troll"

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[2].race_label.label = "Other scary things"
-- dialog.monsters_tv[2].race_button.visible = "hidden"

-- ... or you can refer to that object using the return value
-- from add_item_of_type
local troll_node = dialog.monsters_tv:add_item_of_type("race_node")
troll_node.race_label.label = "Trolls"
troll_node.race_button.on_modified =
function()
troll_node.unfolded = troll_node.race_button.selected
end
local item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Whelp"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Shaman"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Troll"

local not_troll_node =
dialog.monsters_tv:add_item_of_type("race_node")
not_troll_node.race_label.label = "Other scary things"
not_troll_node.race_button.visible = "hidden"

end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We define two nodes in our tree, a race_node for the top level, and a details_node for the children of a race_node. The rest of the interesting bits are in preshow().

We demonstrate two different ways of creating and accessing items, the first (commented out) just using the order in which they are created, while in the second we capture the result of add_item_of_type() in a variable we can use to refer to the newly defined object. The first method is shown primarily to demonstrate the structure of the resulting objects. The second method is perhaps easier to follow, and is almost necessary when you start doing things like dynamically deleting nodes, so it is in most cases a better practice (of course, you probably won't want to use the same variable for each node like we did, and perhaps not one local to the preview function).

We add a node, label it "Trolls", and add a callback to the button such that the children of the node will be visible (the node is "unfolded", a boolean value which defaults to false) when the button is checked (selected == true). Then we add three "details_node" nodes as children of this node.

Our second node, "Other scary things" will remain empty for now, so we'll set the visible attribute on its button to "hidden" (which is like false, but with hidden the widget still takes up space).

{|
| This example is rather ugly, both in the hardwired code and the appearance of the resulting GUI, but it addresses a couple important aspects of how tree views work and how we might use them. Let's clean it up a bit. We'll add an indentation_step_size to the tree view, along with a spacer and [[#Alignment|horizontal_alignment]] to our details node, to make the labels line up nicely, and change the button [[#Definitions|definition]] to replace the checkbox with something that looks like it belongs there. We will look at methods for handling layout in more depth [[#Appearance|later]].
|-
| [[File:Basic tree view2c.png|center|thumb|Our tree_view with proper alignment]]

<syntaxhighlight lang=lua>
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
indentation_step_size = 20,
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
definition = "tree_view_node"
}
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.spacer { width = 40 }
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}

</syntaxhighlight>

===Multi_page===
====Simple Multi_page====
{|
|-
Like a tree_view, a multi_page is a heterogeneous container which is dynamically populated, however, while a multi_page contains multiple elements (pages), only one page is displayed at any one time. Its purpose is perhaps best described by a couple of examples.
|-
[[File:Basic multipage.png|center|thumb|Multi_page showing active page]]
|}
<syntaxhighlight lang=lua>
local function basic_multipage()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll",
name = _"Bob", type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp",
name = "Junior", type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman",
name = _"Alice", type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish",
type = "Seamonsters" },
{ image = "units/monsters/yeti.png",
label = "A yeti",
type = "Coolers" }
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
multi_page
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}

local function preshow(dialog) -- Prepare the GUI before display
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_label.label = monster.label
end
--dialog.monsters_mp.selected_index = 5
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

As you can see, the code for our basic multi_page GUI looks a lot like our basic tree_view GUI. The difference is what is displayed. While both the tree_view and the multi_page containers contain five items, with the multi_page, only the first one is displayed. More specifically, only the page associated with the selected_index attribute of the multi_page object, which defaults to 1, is displayed. If we were to uncomment the last line in preshow(), we would still see only one item, but it would be the fifth one we allocated. It's nice to know all our pages are in there somewhere, but this example is pretty useless. What we need is a way to select which page we want to see from within our GUI.

====A More Useful Multi_page====

{|
| colspan="2" | To demonstrate the usefulness of a multi_page, and highlight its difference from a tree_view, we'll add a listbox to allow us to select the page to view. We'll also need to add a little action to our GUI.
|-
| style="align:centered" |[[File:More useful multipage.png|center|thumb|User selected Troll]] || [[File:More useful multipage2.png|center|thumb|User selected Cuttlefish]]
|}

<syntaxhighlight lang=lua>
local function more_useful_multi_page()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
race = "Trolls", tip = "Your uncle" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
race = "Trolls", tip = "Your nephew" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
race = "Trolls", tip = "Your auntie" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", race = "Seamonsters",
tip = "Not a fish" },
{ image = "units/monsters/yeti.png",
label = "A yeti", race = "Coolers",
tip = "ROAR!" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
}
}
}

local listboxDefinition = wml.tag.listbox {
id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
},
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
listboxDefinition
},
wml.tag.column {
wml.tag.spacer {
width = 30
}
},
wml.tag.column {
multi_page
},
}
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_image.tooltip = monster.tip
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_image.tooltip = monster.tip
dialog.monsters_mp[i].monster_label.label = monster.label
end
local function switch_page()
dialog.monsters_mp.selected_index = listbox.selected_index
end
listbox.on_modified = switch_page
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

Most of this should look pretty familiar. We've simply taken the previous example and added a second column to our GUI using code from an earlier example to add a listbox. In addition, we altered the page layout slightly, and added a spacer column in the dialog definition to approve the appearance.

The interesting stuff is in preshow(). Again we've merged in some listbox code from an earlier example, but we've also created a new local function switch_page(), which simply sets the selected_index attribute of our multi_page to the same as that of our listbox, and then we've configured the listbox.on_modified callback to call switch_page(). Now when the user selects an item in the listbox (updating listbox.selected_index and triggering listbox.on_modified), dialog.monsters_mp.selected_index is updated accordingly and therefore the visible page changes to the one associated with the selected unit.

Also note in preshow() we've added a new child to our monster_image identifier for both the listbox and the multi_page, a tooltip. When the user hovers the mouse over the image of one of our monsters, they'll see a popup message which we've added to our monster table. Try changing '''wml.tag.tooltip { id = "tooltip_large" }''' to '''wml.tag.tooltip { id = "tooltip }''' in the dialogDefinition to see a different tooltip style.

==Actions Have Consequences==

So far, our GUIs have only displayed some information on the screen, but at some point we're probably going to want to use a GUI to get input from the user. In this section we will look at return values that can be assigned to a widget based upon its state, and callbacks, which are functions invoked when something happens with a widget. As we will see, a button is a good example, as it can return a value or take an action, or both, when pressed. Earlier we saw how the selected_index attribute of some widgets, such as the listbox, can also be used as a sort of return value.

===Buttons===
{|
| colspan=2 | In this example, we'll create a couple buttons which provide the user a choice, use a handy confirmation popup to confirm that choice, and demonstrate how we get the results back where we can put them to use.
|-
| [[File:Basic return value.png|center|thumb|There can be only one]] || [[File:Basic return value_confirm.png|center|thumb|The user selected Alice, let's confirm this critical choice]]
|}

<syntaxhighlight lang=lua>
local function basic_return_value()

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "leader_lg",
fixed_height = true,
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" ..
_"Which unit shall lead your army?" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Alice" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/elves-wood/sylph.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 1
}
}
},
}
},
wml.tag.column {
wml.tag.spacer { width = 20 }
},
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Bob" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/human-loyalists/marshal.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 2
}
}
}
}
}
}
}
}
}
}
}
local user_chose = gui.show_dialog(dialogDefinition)
local leader
if user_chose == -1 then -- User closed the dialog by hitting the Enter key
leader = nil
end
if user_chose == -2 then -- User closed the dialog by hitting the Escape key
leader = nil
end

if user_chose == 1 then
leader = "Alice"
end
if user_chose == 2 then
leader = "Bob"
end

local confirmed_leader_choice

if leader ~= nil then
local query = _"You want " .. leader .. _" as your leader?"
confirmed_leader_choice = gui.confirm(query)
end

if confirmed_leader_choice then
wesnoth.message("Great!")
else
wesnoth.message("Fine, lead them yourself!")
end
end
</syntaxhighlight>

Here we've added a couple buttons, and assigned each of them a return value. When the user selects one of these buttons, the GUI is closed and the value of return_value is returned from gui.show_dialog(). We then use [https://wiki.wesnoth.org/LuaAPI/gui#gui.show_prompt gui.confirm()] which provides a very simple Yes/No popup and returns true or false, respectively. Other useful functions can be found on that page which provide handy alternatives to creating your own GUI for other simple user inputs.

The use of return_value is rather limited, as it only returns integers and can't be used with containers like listboxes. In more complex cases we'll need to turn to callback functions which are invoked when something happens to a widget, like clicking a button or a widget's value changing. Earlier, we saw an example of [[LuaAPI/types/widget#on_modified|widget.on_modified()]]. More examples of callbacks can be found at [[LuaAPI/types/widget#on_modified|that link]].

===Slider and Textbox===
{|
| Here we see a couple methods of getting more dynamic input from the user, a slider and a textbox presented in one silly example.
|-
| [[File:Slider and textbox.png|center|thumb|Two ways of getting input from the user]]
|}

<syntaxhighlight lang=lua>
function slider_and_textbox()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = _"How much gold will you pay for this old rusty sword?"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.slider {
id = "gold_sl",
minimum_value = 0,
maximum_value =
wesnoth.sides[wesnoth.current.side].gold,
value = math.floor(
wesnoth.sides[wesnoth.current.side].gold/2)
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.text_box {
id = "gold_tb",
--hint_text = _ "Enter gold here",
--hint_image = "images/gold_pile.png",
label = tostring(math.floor(
wesnoth.sides[wesnoth.current.side].gold/2))
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
local function show_input()
wesnoth.interface.add_chat_message(_"You chose " ..
dialog.gold_sl.value .. _" with the slider")
wesnoth.interface.add_chat_message(_"You entered " ..
tostring(dialog.gold_tb.text) .. _" in the text_box")
end
-- this is a button, so we use on_button_click, not on_left_click
dialog.ok.on_button_click = show_input

dialog.gold_sl.on_modified = function()
dialog.gold_tb.text = tostring(dialog.gold_sl.value)
end
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We create a slider, with a range from 0 to the amount of gold possessed by the current side and an initial value in the middle, and a text box with the same initial value. We assign a function to our OK button which simply reports on the values provided by the user. For no reason whatsoever, we add a callback such that when the user adjusts the slider the value in the textbox is update to match the slider.

Note that the textbox returns text, even though it looks like we're expecting the user to input a natural number. Remember to validate those inputs.

You can use text_hint to place a caption in the box that will help the user understand what to enter in the box, and possibly an image as well. For example, in the search box in the recall menu uses '''hint_text = _ "Search", hint_image = "icons/action/zoomdefault_25.png~FL(horiz)"'''. Of course, you can't have a hint and a label in the same text_box at the same time, so in our example we've only included them as comments.

There is also a widget called a spinner, which is kind of like the combination of a text_box and a slider. As of the release of 1.18, it appears to be unfinished so the strange syntax needed to make it work is probably not the best thing to document, and we will omit it for now.

==Appearance==

'''This section needs help'''

===Borders===

Borders allow you to force unused space around a column, for example so that your widgets don't runtogether. You can specify the border to be one or more of top, bottom, left, right, or all. The border_size sets the amount of padding, in pixels.

<syntaxhighlight lang=lua>
wml.tag.column{
border = "left, right"
border_size = 25
}
</syntaxhighlight>

===Alignment===
{|
| colspan=2 |By default, the GUI will usually center widgets in their cells, which is not always what we want. In this example, we use horizontal_alignment to move widgets around a little.

In more complex cases, it may be useful to add [[GUIWidgetDefinitionWML#Spacer|spacers]] to help force alignment, or use linked_groups to force consistent alignment for objects within a grid.
|-
| [[File:Gui tutorial alignment without.png|center|thumb|Default alignment]] ||[[File:Gui tutorial alignment with.png|center|thumb|Showing off some alignment options]]
|}
<syntaxhighlight lang=lua>
local function basic_alignment()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = "Ralph"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "right",
wml.tag.label {
label = "Sam"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/troll-hero-attack-se-4.png" -- 122x102
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "left",
wml.tag.label {
label = "Jr"
}
},
wml.tag.column {
horizontal_alignment = "right",
wml.tag.image {
label = "units/trolls/whelp.png" -- 72x72
}
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

The screenshots show the output of this example with and without the horizontal_alignment lines included above.

A label allows you to set the text_alignment field (e.g. text_alignment = "left"). Note, however, this only aligns the text within the label. The label itself will probably be centered in the column, giving the false appearance that your text alignment is not working.

===Growth===

To keep your dialog nicely balanced, the GUI2 engine may need to grow rows and/or columns. You can control which columns, for example, grow and which do not, by setting some with grow_factor = 1, and others with grow_factor = 0 (do not grow). While grow factors of 0 and 1 are the most common, you can use other values to adjust the relative growth if you really need to, see [[GUILayout]] for the gory details.

It it sometimes useful to include a column with a [spacer] and a grow_factor (often the only column with grow_factor != 0) whose sole purpose is to keep your GUI aligned nicely as the layout engine does its evil.

To force a column to stretch to fit available space, use horizontal_grow = true. Note that horizontal_grow is not compatible with horizontal_alignment. There is also a vertical_grow parameter.

If you need to see every little detail about the layout process, start wesnoth with --log-debug=gui/layout. Good luck with that.

===Definitions===
Many widgets can be configured to have to a different appearance, for example in our tree_view example we changed the definition of a toggle_button from the default of a checkbox by setting definition = "tree_view_node". This option was found by looking at the id of a toggle_button_definition in .../data/gui/widget/toggle_button_tree_view_node.cfg:

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib
###
### Definition of a toggle button to be used in a tree view as node fold/unfold indicator
###
[toggle_button_definition]
id = "tree_view_node" # <--- we can use 'definition = "tree_view_node"' in a [toggle_button] to select this definition
description = "Fold/unfold status indicator of a tree view node."
</syntaxhighlight>

{|
|There are many other definitions for buttons and other widget types in that directory. It would be nice to have a list (linked here), but for now you'll just have to look around.

We can even create our own custom definitions using [[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition()]]. In this example, we copy from .../data/gui/widget/toggle_button_tree_view_node.cfg with a slight change so that our button turns red ( '''~BLEND(255,0,0,1)''' ) when focused.

In this example, we will use wesnoth.wml_actions to create the WML tag [add_widget_def_demo].

Note the first line, a common convention for creating an alias for wml.tag.
|-
|[[File:Gui tutorial custom widget.png|center|thumb|Different definition of buttons, including one of our own (right)]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag -- save ourselves some typing
function wesnoth.wml_actions.add_widget_def_demo()
local definition = {
id = "tree_view_node_custom",
description = "Fold/unfold status indicator of a tree view node (MODIFIED).",
T.resolution {
min_width = 25,
min_height = 19,
default_width = 25,
default_height = 19,
max_width = 25,
max_height = 19,
-- Unselected - note there's no tags for unselected/selected, that's simply determined by the order
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/fold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/fold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/fold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
-- Selected
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/unfold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
}
}
gui.add_widget_definition("toggle_button", "tree_view_node_custom", definition)

local dialogDefinition = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid {
T.row {
T.column {
T.toggle_button {
definition = "default"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node_custom"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end

</syntaxhighlight>

See [[GUIWidgetDefinitionWML]] for more details on widget definitions.

You can also give the whole dialog a definition, like definition = "tooltip_large". There is no gui.add_window_definition(), however a window is technically a type of widget so it may be possible to create your own window definitions (please update this if you do).

===Panels===

===Canvases===
Part of panels? Sort of?

A canvas is a surface you can draw on. A dialog has them, as does a panel, and for these canvas 1 refers to the background, while canvas 2 refers to the foreground. Other widgets may have canvases that may have other meanings, or no canvases at all. See more at [[LuaAPI/gui/widget#set_canvas]].

Here's a fun little trick. Set your dialog background to be transparent:
<syntaxhighlight lang=lua>
local function preshow(dialog)
dialog:set_canvas(1, { } )
end
</syntaxhighlight>

Or, if you want an opaque GUI background with the screen behind it blurred like what you see behind the text of a [message], you can set your window definition to "message":
<syntaxhighlight lang=lua>
...
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
definition = "message",
...
</syntaxhighlight>

{|
|Here we take our [[#Progress Bar|progress bar]], and add a text overlay.

Note: either using text on a canvas is rather limited, or I just couldn't figure it out. For example, I could not get the text size any smaller, and any attempts to do so simply resulted in very blocky text. And the spaces were necessary so that the text wasn't stretched out. I also find it surprising that the progress bar does not have this feature inherently. So it's not a great example, but it should be enough to get you started using canvases. Be sure to visit the [[LuaAPI/gui/widget#set_canvas|link]] mentioned above for more options.
|-
|[[File:Gui tutorial canvas text.png|center|thumb|A progress bar in the background, with text in the foreground]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar_with_overlay()
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.grid {
T.row {
T.column {
T.panel { id = "panel",
T.grid {
T.row {
T.column {
T.button { id = "button",
label =_ "Press me"}
},
T.column {
T.progress_bar { id = "progress" }
},
T.column {
T.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
dialog.panel:set_canvas(2, { T.text { text_alignment = "center", font_size = 48,
text_markup = true, text = " " ..
dialog.progress.percentage .. "% " } } )
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

You may notice we added a panel and placed our text on the foreground canvas(2) on it, since the progress_bar itself does not support canvases.

===Placement===

You may have noticed that all of our dialogs are centered on the screen. This is the default. You can override this and place the dialog wherever you like by setting automatic_placement = false, along with x, y, width, and height at the top level of your dialog definition (next to tooltip =, etc).

'''This part about placement needs review'''
If you prefer, you may replace x and/or y with horizontal_placement and vertical_placement, such as horizontal_placement = "left". You can even set the placement values using WFL, for example horizontal_placement = "(gamemap_width / 3)" -- see [[#Using WFL with GUI2|Using WFL with GUI2]].

==Miscellaneous==

TODO: This stuff doesn't belong in a tutorial. It's worth documenting, but not here. Better to save these here for now than keep them on my laptop.

===Progress Bar===
{|
|A progress_bar is a graphical representation of a percent. In this example, we present the user with a puzzle. They must hit the button repeatedly before they can close the GUI. A progress_bar displays their current progress toward completion.
|-
|[[File:Gui tutorial progress bar.png|center|thumb|upright=2]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.button { id = "button",
label =_ "Press me"
}
},
wml.tag.column {
wml.tag.progress_bar { id = "progress" }
},
wml.tag.column {
wml.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end

gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

===Unit Preview Pane===

{|
|A unit_preview_pane takes a unit (or a unit type), and presents a graphical representation of the unit and its more important attributes, along with tooltips for additional details, in the same way that the recall menu does. Here we see an example of a unit which has picked up some items, including a weapon, which are affecting its stats.
|-
|[[File:Gui tutorial unit preview pane.png|center|thumb]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag

function wesnoth.wml_actions.recall_from_variable(cfg)
local from_array = cfg.from or wml.error(
"[recall_from_variable]: missing required from= ")
local to_var = cfg.to or wml.error(
"[recall_from_variable]: missing required to= ")
local unit_list = wml.array_access.get(from_array) or wml.error(
string.format("[recall_from_variable]: failed to fetch wml array %s",from_array))

local listboxItem = T.grid {
T.row {
T.column {
T.label { id = "available_unit",
linked_group = "available_unit"
}
}
}
}

local listbox_id = "available_units"
local listboxDefinition = T.listbox { id = listbox_id,
T.list_definition {
T.row {
T.column {
T.toggle_panel { listboxItem }
}
}
}
}
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.linked_group { id = "available_unit", fixed_width = true },
T.grid {
T.row { -- header
T.column {
T.grid {
T.row {
T.column {
border = "bottom",
border_size = 10,
T.label {
use_markup = true,
label = ""
.. _"Select unit to recall" .. ""
}
}
}
}
}
},
T.row { -- Body
T.column {
T.grid {
T.row {
T.column {
border = "right",
border_size = 40,
listboxDefinition
},
T.column {
T.unit_preview_pane { id = "unit_preview" }
}
}
}
}
},
T.row { -- Footer
T.column {
T.grid {
T.row {
T.column {
T.spacer { width = 400 }
},
T.column {
border = "top,right",
border_size = 10,
T.button { id = "ok",
label = _"OK"
}
}
}
}
}
}
}
}

local picked = 1

local function preshow(dialog)
local listbox = dialog[listbox_id]
for i,unit in ipairs(unit_list) do
listbox[i].available_unit.label = unit.name .. "(" ..
unit.language_name .. ")"
end
local function draw_unit()
wesnoth.units.to_recall(unit_list[listbox.selected_index])
local tmp = wesnoth.units.find_on_recall{ id =
unit_list[listbox.selected_index].id }[1]
dialog.unit_preview.unit = tmp
wesnoth.units.extract(tmp)
picked = listbox.selected_index
end
draw_unit()
listbox.on_modified = draw_unit
end

gui.show_dialog(dialogDefinition,preshow)

wml.variables[to_var] = picked - 1
end

</syntaxhighlight>

This should all be pretty self evident by now. We are provided with an array of stored units (from [store_unit] in WML). We create a listbox populated with units and we use the selected_index to determine which element in the table to send to unit_preview_pane. Since our input is an array of unit data, not actual units, we use [[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] to take the definition of one from our array and place it on the recall list (turning it into an actual unit), [[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] to fetch that unit in a form that the unit_preview_panel understands, and finally [[wesnoth.units.extract|wesnoth.units.extract]] to remove the unit from the recall list when we are done with it.

And of course we subtract one from the selected_index when we return our choice to WML, since lua arrays count from 1 and WML from 0.

The unit_preview_pane will also accept a unit_type instead of a specific unit.

==Appendix==

===Explore Your Options===

We've seen a lot of options that can be set to modify the behaviour of our dialogs, some on columns, some on widgets, etc. These are in the process of being documented [[GUIWidgetInstanceWML|here]], but if you would like to go straight to the source, the data Wesnoth uses to validate your configuration can be found in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui data/schema/gui] under your install directory.

Let's look at a scroll_label, for example. A scroll_label is a widget, so we look in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/widget_instances.cfg widget_instances.cfg] and find the following. Here we can see five parameters we can provide to our scroll_label (in addition to the ones available to all widgets, like id and definition, see the entry super=... which refers you to the widget_instance in the file [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/generic.cfg data/schema/gui/generic.cfg]), along with their types and default values. For example, we could set "link_aware = true", and if we do not we can assume that link_aware will be false. While this does not explain what these parameters do, the information provided in the schema directory is often helpful nonetheless.

<syntaxhighlight lang=wml>
[tag]
name="scroll_label"
min="0"
max="infinite"
super="$generic/widget_instance"
{DEFAULT_KEY "horizontal_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "vertical_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "wrap" bool true}
{DEFAULT_KEY "text_alignment" f_h_align "left"}
{DEFAULT_KEY "link_aware" bool false}
[/tag]
</syntaxhighlight>

We see that our scrollbars are of type scrollbar_mode. It would probably help if we knew what values are available to the scrollbar_mode. In [https://github.com/wesnoth/wesnoth/tree/master/data/schema/types/gui.cfg data/schema/types/gui.cfg] we find this:

<syntaxhighlight lang=wml>
[type]
name=scrollbar_mode
value="always|never|auto|initial_auto"
[/type]
</syntaxhighlight>

The variable types found in the schema files are described at [[GUIVariable]].

Note: The keys in the schema file correspond to the attributes used when configuring your widgets. They will not always align perfectly with keys used by the Lua API. For example, the slider uses maximum_value in its configuration, and max_value when using the Lua API:

<syntaxhighlight lang=wml>
[slider]
id="my_slider"
maximum_value = 100
[/slider]
</syntaxhighlight>

<syntaxhighlight lang=lua>
dialog.my_slider.max_value = 90
</syntaxhighlight>

===Using WFL with GUI2===

If you look at the variable type descriptions at [[GUIVariable]] you may notice that many of them start with "f_" and have "or formula" in the description. This means that you can use [[Wesnoth_Formula_Language|Wesnoth Formula Language (WFL)]] formulas in these fields, with certain variables made available to you (which variables and what they mean can be challenging to ascertain, but you can generally figure it out by example).

Looking at [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/window.cfg data/schema/gui/window.cfg] we see that 'height' has type f_unsigned, which tells us that height is an unsigned integer, and that we can use a WFL formula to define it in a window_definition. In [https://github.com/wesnoth/wesnoth/tree/master/data/gui/themes/default/window/wml_message.cfg data/gui/window/wml_message.cfg] (data/gui/themes/default/window/wml_message.cfg starting around 1.19.2), we find the line '''height = "(screen_height - 30)"'''. This does exactly what it looks like, it sets the height of our window to 30 pixels less than the height of the screen.

===Useful Links===
[[GUIToolkitWML]] - Documents the keys/values available on various objects (e.g. "what attributes can I set on a column?") 
[[LuaAPI/gui|LuaAPI/gui]] - Mostly about opening windows 
[[LuaAPI/types/widget]] - Widget attributes and callbacks 
[https://wiki.wesnoth.org/Category:GUI_WML_Reference GUI_WML_Reference] 
[https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui .../data/schema/gui/*.cfg] - Lists of valid options for various GUI objects 
[https://devdocs.wesnoth.org/layout_algorithm.html Layout Algorithm] - For windows, at least

===Credits===

The basic framework that composes the initial examples was lifted from LotI. It's a great place to find well written examples, but some of it is complex enough to be a little overwhelming when getting started.

Many examples, particularly tree view and multipage, are heavily derived from the World Conquest multiplayer campaign.

Sandbox/GUI/Getting Started

2024-09-29T16:05:55Z

White haired uncle: /* Listbox */

So, it looks like I can't exclude this page/section from the search engine as I had hoped. I wanted to put this in a sandbox so that it wouldn't be published without some proper review.

==Introduction==

This guide is designed to help you get a simple Wesnoth GUI, implemented in lua, up and running while describing the basic building blocks along the way. It is written in a narrative format, where most examples build on previous examples, and therefore while not always necessary it may be desirable to read from start to finish. The reader, probably a UMC author, should have a basic knowledge of working with lua within Wesnoth.

Some would find creating a GUI in part or in full using WML simpler to follow, and those alternatives are available, for example [[LuaAPI/gui/example]], but we're using lua here. If you find WML easier to follow, you can always convert the lua tables that define the GUIs to WML using [[LuaAPI/wml#wml.tostring|wml.tostring]], for example:

<syntaxhighlight lang=lua>
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
</syntaxhighlight>

In some examples, instead of defining the entire GUI at once, we'll break out some parts into separate variables. If you try to view one in WML and get an error from wml.tostring() about expecting a WML table and not a table, try passing your variable(/table) inside a table:

<syntaxhighlight lang=lua>
print(wml.tostring({listboxItem}))
gui.show_lua_console()
</syntaxhighlight>

One distinct advantage of using WML to define your GUI layout is that you get better (any) validation. Invalid keys, and sometimes values, are often flagged in the log, unlike with lua where they are silently ignored. In the comments of our first GUI, below, is an example which loads a WML GUI configuration using [[LuaAPI/wml#wml.load|wml.load()]], validating against the GUI2 window schema.

===What is GUI2?===
Once upon a time, Wesnoth had a GUI system which is now commonly referred to as GUI1. As of 1.19, GUI1 has been almost completely replaced by GUI2. UMC authors will probably never encounter GUI1 and can simply use the terms GUI and GUI2 interchangeably, at least until GUI3 comes along.

Instead of spending a lot of time here giving an overview of what GUI2 is and what makes it great, and not so great, let's charge ahead so we can see it in action, and let readers who are interested look elsewhere(TODO: link) for a more formal definition. (TODO: is this the right approach for most readers?).

==Getting Started==

For example purposes, we'll create a directory in our campaign directory called lua containing a file called gui_tutorial.lua, and add a command in the prestart event for a scenario which will create a right-click menu option to invoke our new GUI. Of course there are other methods to invoke lua from WML, but this one will get us started. After all, we really just want to get something up on the screen ASAP, right?

===A most basic GUI===

{|
|[[File:Most basic gui.png|center|thumb|I can't believe this worked]]
|-
|In our prestart event, we create a simple menu item, which executes a single line of lua which calls the lua function most_basic_gui() which is found in gui_tutorial.lua:
|}

<syntaxhighlight lang=wml>
[set_menu_item]
id=most_basic_gui
description="Our first GUI"
[command]
[lua]
code=<<
wesnoth.require("~add-ons/<OUR_CAMPAIGN>/lua/gui_tutorial.lua").most_basic_gui()
>>
[/lua]
[/command]
[/set_menu_item]
</syntaxhighlight>

And create gui_tutorial.lua:
{| class="wikitable" style="margin:auto"
! !! The WML equivalent of dialogDefinition
|-
|
<syntaxhighlight lang=lua>
local function most_basic_gui()
local dialogDefinition = {
--click_dismiss = true, -- allow user to close dialog with click of a button
wml.tag.tooltip { id = "tooltip_large" }, -- required
wml.tag.helptip { id = "tooltip_large" }, -- required
wml.tag.grid { -- our most basic gui
wml.tag.row { -- a grid must include at least one row
wml.tag.column { -- a row needs a column
wml.tag.image { -- a column includes exactly one widget
label = "units/trolls/grunt.png"
}
}
}
}
}

local function preshow(dialog)
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
end
gui.show_dialog(dialogDefinition,preshow)

-- Or, if you want to define the gui in WML, something like:
-- local dialog_wml = wml.load("~add-ons/GUI_Tutorial/most_basic_gui.cfg",
-- true, "schema/gui_window.cfg")
-- gui.show_dialog(wml.get_child(dialog_wml, 'resolution'))
end
return { most_basic_gui = most_basic_gui}
</syntaxhighlight>
|
<syntaxhighlight lang=wml>
[tooltip]
id="tooltip_large"
[/tooltip]
[helptip]
id="tooltip_large"
[/helptip]
[grid]
[row]
[column]
[image]
label="units/trolls/grunt.png"
[/image]
[/column]
[/row]
[/grid]

</syntaxhighlight>
|}

In the above file, we have just the single function to create our GUI, followed by a return command which makes our function most_basic_gui() available to the [[LuaAPI/wesnoth#wesnoth.require|wesnoth.require()]] function as most_basic_gui().

Our function creates a table containing the definition of a "dialog", and then passes that to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]]. It should be noted that gui.show_dialog does not provide synchronization, so if your GUI makes changes to the game state, you'll need to jump through some hoops or you'll break replays and multiplayer, but that's not something we need to care about at this point, so just be aware that you may need to deal with it in the future.

Our dialog definition at this point includes three parts. The first two are a tooltip and a helptip, which are required and define how tooltips (use id = "tooltip_large" or id = "tooltip" or id = "tooltip_transparent"), and helptips (rarely used, but must be included here, and yes their definitions are "tooltip" not "helptip") will look (as we will see later, this really should be definition = "tooltip", but in this case it's id = "tooltip"). The third part is a grid, which is basically a table, like in HTML or MySQL, with rows and columns. A grid always contains at least one row. A row contains at least one column (note that a column does NOT span rows, it is completely contained within a row). Inside a column is exactly one item, a cell which contains a [[GUIWidgetDefinitionWML|widget]], in this case we'll use an image (later we'll see what else we can put in a cell). Note that we don't actually define a cell in our code, it's just a term used to refer to the contents of a column.

The preshow function is optional. If included in the call to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]], it is run before the GUI is displayed. In this case, we include it to display the dialog we created with lua in WML format. Near the end, in comments, we show how you would call [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] if you chose to define your dialog using WML. Note that what is shown here is the WML equivalent of our lua dialogDefinition, and not the complete WML you would need to use if you were to configure your GUI layout in WML.

Note: if you should try out the above, you'll have to hit escape or enter to close the GUI. Uncomment the "click_dismiss" line, and the user will be able to close the GUI with a mouse click.

===Adding a little flavor===

{|
|You may have noticed our GUI is missing a header and a way to close it when we're done admiring our work. Here we add a new first row to our grid, while demonstrating a couple formatting options: a border to put some distance between our grid cell and its neighbor, and the "use_markup = true" option to enable Pango support in our text.

Our third row adds an OK button at the bottom. You can associate actions with buttons to do all kinds of things, but here we just exploit the default behaviour to close the GUI.

Of course, we'll also have to modify our return to support the new function, and update our menu item(s) accordingly.
|-
|[[File:Most basic gui2.png|center|thumb|Adding header and a footer]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui2()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
gui.show_dialog(dialogDefinition)
end
return { most_basic_gui = most_basic_gui, most_basic_gui2 = most_basic_gui2 }
</syntaxhighlight>

===And a bit more===
{|

|And now a minor, but important change. We want to add a new text field next to the image in the body of our GUI. Obviously, we want to add a new column, but this is more difficult than when we added new rows in the previous example. The problem is that all rows (at a given level) in a grid must contain the same number of columns. We can't have two columns in the row that constitutes the body of our GUI, but only one in the header and one in the footer. To solve this problem, we replace our image widget with a new grid, which can use as many columns as we like (as long as they are the same within each row of our new grid). This new grid contains a row with two columns, but that is okay because the new grid itself is placed in a single column, which matches our single column header and footer (ok button), keeping the rows balanced.
|-
|[[File:Most basic gui3.png|center|thumb|Rows with different numbers of columns]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui3()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column { -- This is the only column in this row,
-- to match the number of columns in
-- the rows of our header and footer
wml.tag.grid { -- A new grid, so we can use a different
-- number of columns
wml.tag.row {
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
},
wml.tag.column {
wml.tag.label {
label = "A troll"
}
}
}
}
}
},
wml.tag.row { -- A footer
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = "Ok"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

While we see here just the simplest of examples, you can many levels of grids in grids, rows with multiple columns some of which containing grids, etc, to build complicated dialogs to your liking.

==Containers==

===Stacked Widget===

TODO

===Listbox===
{|
| Now we'd like to add some more monsters. Obviously, we could just add more rows, but what if we won't know until runtime how many and which ones? We could break up the definition of our dialog and add new rows dynamically, it's just a table after all, but fortunately we have a widget which handles this for us, a listbox. A listbox is kind of like an array, a collection of similar objects where the number of items can vary. We will tell the GUI where we want the box, and what each entry in the box will look like, and then at runtime we can add entries to the box.

Note that listbox items are added from top to bottom. Another container, the horizontal_listbox, works just like a listbox except the items are added from left to right.
|-
| [[File:Gui with listbox.png|center|thumb|Listbox with three items. Each item is an image and a label.]]

<syntaxhighlight lang=lua>
local function gui_with_listbox()
local monsters = {
{ image = "units/trolls/grunt.png",
string = "A troll" },
{ image = "units/monsters/cuttlefish.png",
string = "A cuttlefish" },
{ image = "units/monsters/yeti.png",
string = "A yeti" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
}

local listboxDefinition = wml.tag.listbox { id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
listboxDefinition
}
},
wml.tag.row {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_label.label = monster.string
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We begin by creating a simple table which represents the data which will be presented in our listbox. In most cases, we probably wouldn't create that monster table here, but we need it for our example.

The variable listbox_id gives us an identifier for our listbox so we can reference it when we need to. We don't really need to use a variable here, it's just convenient.

We define the structure for the elements in our listbox, stored in listboxItem. Note that we've replaced the actual data with identifiers (e.g. 'units/trolls/grunt.png' becomes 'id = "monster_image"), since each element may have different data.

We define the listbox itself, specifying the identifier, and the definition of our listbox element (which looks a lot like a grid). The cell inside the column contains a variable which is just the listbox element definition we created above; it's not necessary to do this, we could have used one big table, but it's easier to read this way (IMO).

We replace the hardcoded data in our GUI body with our new listbox definition, again using a variable to make it easier to read.

We create a function, often called preshow(), which will be called for us as part of the drawing the GUI (see the new optional argument in [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] -- there's also an optional postshow(), but we don't need it here). This is where we pull the data from our example table into the listbox. We create a listbox variable associated with the listbox, identified by the listbox_id we assigned earlier, inside the dialog which gui.show_dialog() passes to preshow(). Then we iterate through our data table, using each entry from that table to populate a listbox item.

Let's look at that last action a little more closely using an example.

<syntaxhighlight lang=lua>
listbox[i].monster_image.label = monster.image
</syntaxhighlight>

Which we can read as "In listbox element i of our listbox, for the image with identifier monster_image which we defined in our listboxItem, use the data from the corresponding index i in our example data table" (you don't see the index i for the monsters table here, but remember we're iterating using ipairs, we could have just as easily used listbox[i].monster_image.label = monsters[i].image). If you were to step through all of the variable substitutions, you'd see that for i=1, our dialogDefinition is basically the same thing as it was in the earlier examples, just supplied from a table instead of hardcoded (note that you can hardcode entries in a listbox in your dialog definition using the [list_data] tag, aka wml.tag.list_data, which we do not demonstrate here).

You will probably notice that our data does not line up nicely in the GUI. We will fix that later. We'll also demonstrate how the user can select an item in a listbox, and how you can identify which item that was using the selected_index variable of the listbox.

===Tree View===
====Simple Tree View====
{|
| You may have noticed that clicking on a listbox item in our listbox caused it to be highlighted with a box around the contents. This is because the items in a listbox are selectable. This will be useful when we want to add actions, but it looks a bit odd if we just want to present a list of data.

Also, most of the data had to be formatted the same for each item in the listbox. We could, perhaps, include custom markup in our labels, but the actual layout, like the number of columns per row, had to be the same for every item.

Another way to present a list of data is the tree view. Since a tree view supports multiple data types, we may need to create multiple definitions for the elements in our list. These are known as nodes. It will also be necessary to explicitly define which node to use for each element when we populate our tree view.
|-
| [[File:Basic tree view.png|center|thumb|Tree_views can hold multiple data types (only trolls have names here)]]
|}
<syntaxhighlight lang=lua line>
local function basic_tree_view()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", type = "Seamonsters" },
{ image = "units/monsters/yeti.png", label = "A yeti",
type = "Coolers" }
}

local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "trolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name",
linked_group = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
},
wml.tag.node {
id = "nottrolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "monster_name",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_image",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_label",
fixed_width = true
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_tv:add_item_of_type("trolls_node")
dialog.monsters_tv[i].monster_name.label = monster.name -- only trolls have a name
else
dialog.monsters_tv:add_item_of_type("nottrolls_node")
end
-- All of our monsters have an image and a label
dialog.monsters_tv[i].monster_image.label = monster.image
dialog.monsters_tv[i].monster_label.label = monster.label
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We have expanded our list of monsters to include three types of trolls. We have also given each troll a name. This is of course a rather simplistic example, we could have simply given each monster that is not a troll an empty name, but it as presented here our approach serves the purpose of demonstrating how we deal with multiple data types. Our new tree view contains a node for each type of data we will present. In preshow, we explicitly define each element in our list using add_item_of_type(), and populate the item accordingly. [Note: in our listbox example, we could have used add_item() to add items to the listbox, but chose not to since that section was already introducing a number of new concepts. But here, since we have multiple types of items we need to be able to specify the type of the item when we add one, hence we need to use add_item_of_type()].

You may also note the addition of a few linked_group lines. We'll cover linked groups in more detail later, but as used here they instruct the GUI that each column using the same node type needs to be aligned with the others. For example, all of our trolls line up nicely.

====Building a Tree====
{|
| colspan="2" |At this point, one may wonder about the name "tree view", since what he have seen doesn't look much like a tree. To make a tree-like structure, we'll demonstrate adding children to nodes. At the top level our (upside-down) tree will have two nodes, one for trolls and one for everything else. A toggle_button (a type of button which changes states when you push it) will allow us to expand the trolls node to expose its children, which are themselves nodes, though they only contain a label at this point.
|-
| [[File:Basic tree view2a.png|center|thumb|Tree_view with Trolls folded]] || [[File:Basic tree view2b.png|center|thumb|Tree_view with Trolls unfolded]]
|}
<syntaxhighlight lang=lua line>
local function building_a_tree()
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
}
},
wml.tag.column {
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Show me the " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
-- You can refer to an object by its position

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[1].race_label.label = "Trolls"
-- dialog.monsters_tv[1].race_button.on_modified =
-- function()dialog.monsters_tv[1].unfolded =
-- dialog.monsters_tv[1].race_button.selected end

-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][1].monster_type.label = "Whelp"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][2].monster_type.label = "Shaman"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][3].monster_type.label = "Troll"

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[2].race_label.label = "Other scary things"
-- dialog.monsters_tv[2].race_button.visible = "hidden"

-- ... or you can refer to that object using the return value
-- from add_item_of_type
local troll_node = dialog.monsters_tv:add_item_of_type("race_node")
troll_node.race_label.label = "Trolls"
troll_node.race_button.on_modified =
function()
troll_node.unfolded = troll_node.race_button.selected
end
local item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Whelp"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Shaman"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Troll"

local not_troll_node =
dialog.monsters_tv:add_item_of_type("race_node")
not_troll_node.race_label.label = "Other scary things"
not_troll_node.race_button.visible = "hidden"

end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We define two nodes in our tree, a race_node for the top level, and a details_node for the children of a race_node. The rest of the interesting bits are in preshow().

We demonstrate two different ways of creating and accessing items, the first (commented out) just using the order in which they are created, while in the second we capture the result of add_item_of_type() in a variable we can use to refer to the newly defined object. The first method is shown primarily to demonstrate the structure of the resulting objects. The second method is perhaps easier to follow, and is almost necessary when you start doing things like dynamically deleting nodes, so it is in most cases a better practice (of course, you probably won't want to use the same variable for each node like we did, and perhaps not one local to the preview function).

We add a node, label it "Trolls", and add a callback to the button such that the children of the node will be visible (the node is "unfolded", a boolean value which defaults to false) when the button is checked (selected == true). Then we add three "details_node" nodes as children of this node.

Our second node, "Other scary things" will remain empty for now, so we'll set the visible attribute on its button to "hidden" (which is like false, but with hidden the widget still takes up space).

{|
| This example is rather ugly, both in the hardwired code and the appearance of the resulting GUI, but it addresses a couple important aspects of how tree views work and how we might use them. Let's clean it up a bit. We'll add an indentation_step_size to the tree view, along with a spacer and [[#Alignment|horizontal_alignment]] to our details node, to make the labels line up nicely, and change the button [[#Definitions|definition]] to replace the checkbox with something that looks like it belongs there. We will look at methods for handling layout in more depth [[#Appearance|later]].
|-
| [[File:Basic tree view2c.png|center|thumb|Our tree_view with proper alignment]]

<syntaxhighlight lang=lua>
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
indentation_step_size = 20,
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
definition = "tree_view_node"
}
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.spacer { width = 40 }
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}

</syntaxhighlight>

===Multi_page===
====Simple Multi_page====
{|
|-
Like a tree_view, a multi_page is a heterogeneous container which is dynamically populated, however, while a multi_page contains multiple elements (pages), only one page is displayed at any one time. Its purpose is perhaps best described by a couple of examples.
|-
[[File:Basic multipage.png|center|thumb|Multi_page showing active page]]
|}
<syntaxhighlight lang=lua>
local function basic_multipage()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll",
name = _"Bob", type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp",
name = "Junior", type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman",
name = _"Alice", type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish",
type = "Seamonsters" },
{ image = "units/monsters/yeti.png",
label = "A yeti",
type = "Coolers" }
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
multi_page
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}

local function preshow(dialog) -- Prepare the GUI before display
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_label.label = monster.label
end
--dialog.monsters_mp.selected_index = 5
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

As you can see, the code for our basic multi_page GUI looks a lot like our basic tree_view GUI. The difference is what is displayed. While both the tree_view and the multi_page containers contain five items, with the multi_page, only the first one is displayed. More specifically, only the page associated with the selected_index attribute of the multi_page object, which defaults to 1, is displayed. If we were to uncomment the last line in preshow(), we would still see only one item, but it would be the fifth one we allocated. It's nice to know all our pages are in there somewhere, but this example is pretty useless. What we need is a way to select which page we want to see from within our GUI.

====A More Useful Multi_page====

{|
| colspan="2" | To demonstrate the usefulness of a multi_page, and highlight its difference from a tree_view, we'll add a listbox to allow us to select the page to view. We'll also need to add a little action to our GUI.
|-
| style="align:centered" |[[File:More useful multipage.png|center|thumb|User selected Troll]] || [[File:More useful multipage2.png|center|thumb|User selected Cuttlefish]]
|}

<syntaxhighlight lang=lua>
local function more_useful_multi_page()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
race = "Trolls", tip = "Your uncle" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
race = "Trolls", tip = "Your nephew" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
race = "Trolls", tip = "Your auntie" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", race = "Seamonsters",
tip = "Not a fish" },
{ image = "units/monsters/yeti.png",
label = "A yeti", race = "Coolers",
tip = "ROAR!" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
}
}
}

local listboxDefinition = wml.tag.listbox {
id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
},
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
listboxDefinition
},
wml.tag.column {
wml.tag.spacer {
width = 30
}
},
wml.tag.column {
multi_page
},
}
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_image.tooltip = monster.tip
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_image.tooltip = monster.tip
dialog.monsters_mp[i].monster_label.label = monster.label
end
local function switch_page()
dialog.monsters_mp.selected_index = listbox.selected_index
end
listbox.on_modified = switch_page
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

Most of this should look pretty familiar. We've simply taken the previous example and added a second column to our GUI using code from an earlier example to add a listbox. In addition, we altered the page layout slightly, and added a spacer column in the dialog definition to approve the appearance.

The interesting stuff is in preshow(). Again we've merged in some listbox code from an earlier example, but we've also created a new local function switch_page(), which simply sets the selected_index attribute of our multi_page to the same as that of our listbox, and then we've configured the listbox.on_modified callback to call switch_page(). Now when the user selects an item in the listbox (updating listbox.selected_index and triggering listbox.on_modified), dialog.monsters_mp.selected_index is updated accordingly and therefore the visible page changes to the one associated with the selected unit.

Also note in preshow() we've added a new child to our monster_image identifier for both the listbox and the multi_page, a tooltip. When the user hovers the mouse over the image of one of our monsters, they'll see a popup message which we've added to our monster table. Try changing '''wml.tag.tooltip { id = "tooltip_large" }''' to '''wml.tag.tooltip { id = "tooltip }''' in the dialogDefinition to see a different tooltip style.

==Actions Have Consequences==

So far, our GUIs have only displayed some information on the screen, but at some point we're probably going to want to use a GUI to get input from the user. In this section we will look at return values that can be assigned to a widget based upon its state, and callbacks, which are functions invoked when something happens with a widget. As we will see, a button is a good example, as it can return a value or take an action, or both, when pressed. Earlier we saw how the selected_index attribute of some widgets, such as the listbox, can also be used as a sort of return value.

===Buttons===
{|
| colspan=2 | In this example, we'll create a couple buttons which provide the user a choice, use a handy confirmation popup to confirm that choice, and demonstrate how we get the results back where we can put them to use.
|-
| [[File:Basic return value.png|center|thumb|There can be only one]] || [[File:Basic return value_confirm.png|center|thumb|The user selected Alice, let's confirm this critical choice]]
|}

<syntaxhighlight lang=lua>
local function basic_return_value()

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "leader_lg",
fixed_height = true,
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" ..
_"Which unit shall lead your army?" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Alice" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/elves-wood/sylph.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 1
}
}
},
}
},
wml.tag.column {
wml.tag.spacer { width = 20 }
},
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Bob" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/human-loyalists/marshal.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 2
}
}
}
}
}
}
}
}
}
}
}
local user_chose = gui.show_dialog(dialogDefinition)
local leader
if user_chose == -1 then -- User closed the dialog by hitting the Enter key
leader = nil
end
if user_chose == -2 then -- User closed the dialog by hitting the Escape key
leader = nil
end

if user_chose == 1 then
leader = "Alice"
end
if user_chose == 2 then
leader = "Bob"
end

local confirmed_leader_choice

if leader ~= nil then
local query = _"You want " .. leader .. _" as your leader?"
confirmed_leader_choice = gui.confirm(query)
end

if confirmed_leader_choice then
wesnoth.message("Great!")
else
wesnoth.message("Fine, lead them yourself!")
end
end
</syntaxhighlight>

Here we've added a couple buttons, and assigned each of them a return value. When the user selects one of these buttons, the GUI is closed and the value of return_value is returned from gui.show_dialog(). We then use [https://wiki.wesnoth.org/LuaAPI/gui#gui.show_prompt gui.confirm()] which provides a very simple Yes/No popup and returns true or false, respectively. Other useful functions can be found on that page which provide handy alternatives to creating your own GUI for other simple user inputs.

The use of return_value is rather limited, as it only returns integers and can't be used with containers like listboxes. In more complex cases we'll need to turn to callback functions which are invoked when something happens to a widget, like clicking a button or a widget's value changing. Earlier, we saw an example of [[LuaAPI/types/widget#on_modified|widget.on_modified()]]. More examples of callbacks can be found at [[LuaAPI/types/widget#on_modified|that link]].

===Slider and Textbox===
{|
| Here we see a couple methods of getting more dynamic input from the user, a slider and a textbox presented in one silly example.
|-
| [[File:Slider and textbox.png|center|thumb|Two ways of getting input from the user]]
|}

<syntaxhighlight lang=lua>
function slider_and_textbox()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = _"How much gold will you pay for this old rusty sword?"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.slider {
id = "gold_sl",
minimum_value = 0,
maximum_value =
wesnoth.sides[wesnoth.current.side].gold,
value = math.floor(
wesnoth.sides[wesnoth.current.side].gold/2)
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.text_box {
id = "gold_tb",
--hint_text = _ "Enter gold here",
--hint_image = "images/gold_pile.png",
label = tostring(math.floor(
wesnoth.sides[wesnoth.current.side].gold/2))
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
local function show_input()
wesnoth.interface.add_chat_message(_"You chose " ..
dialog.gold_sl.value .. _" with the slider")
wesnoth.interface.add_chat_message(_"You entered " ..
tostring(dialog.gold_tb.text) .. _" in the text_box")
end
-- this is a button, so we use on_button_click, not on_left_click
dialog.ok.on_button_click = show_input

dialog.gold_sl.on_modified = function()
dialog.gold_tb.text = tostring(dialog.gold_sl.value)
end
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We create a slider, with a range from 0 to the amount of gold possessed by the current side and an initial value in the middle, and a text box with the same initial value. We assign a function to our OK button which simply reports on the values provided by the user. For no reason whatsoever, we add a callback such that when the user adjusts the slider the value in the textbox is update to match the slider.

Note that the textbox returns text, even though it looks like we're expecting the user to input a natural number. Remember to validate those inputs.

You can use text_hint to place a caption in the box that will help the user understand what to enter in the box, and possibly an image as well. For example, in the search box in the recall menu uses '''hint_text = _ "Search", hint_image = "icons/action/zoomdefault_25.png~FL(horiz)"'''. Of course, you can't have a hint and a label in the same text_box at the same time, so in our example we've only included them as comments.

There is also a widget called a spinner, which is kind of like the combination of a text_box and a slider. As of the release of 1.18, it appears to be unfinished so the strange syntax needed to make it work is probably not the best thing to document, and we will omit it for now.

==Appearance==

'''This section needs help'''

===Borders===

Borders allow you to force unused space around a column, for example so that your widgets don't runtogether. You can specify the border to be one or more of top, bottom, left, right, or all. The border_size sets the amount of padding, in pixels.

<syntaxhighlight lang=lua>
wml.tag.column{
border = "left, right"
border_size = 25
}
</syntaxhighlight>

===Alignment===
{|
| colspan=2 |By default, the GUI will usually center widgets in their cells, which is not always what we want. In this example, we use horizontal_alignment to move widgets around a little.

In more complex cases, it may be useful to add [[GUIWidgetDefinitionWML#Spacer|spacers]] to help force alignment, or use linked_groups to force consistent alignment for objects within a grid.
|-
| [[File:Gui tutorial alignment without.png|center|thumb|Default alignment]] ||[[File:Gui tutorial alignment with.png|center|thumb|Showing off some alignment options]]
|}
<syntaxhighlight lang=lua>
local function basic_alignment()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = "Ralph"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "right",
wml.tag.label {
label = "Sam"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/troll-hero-attack-se-4.png" -- 122x102
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "left",
wml.tag.label {
label = "Jr"
}
},
wml.tag.column {
horizontal_alignment = "right",
wml.tag.image {
label = "units/trolls/whelp.png" -- 72x72
}
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

The screenshots show the output of this example with and without the horizontal_alignment lines included above.

A label allows you to set the text_alignment field (e.g. text_alignment = "left"). Note, however, this only aligns the text within the label. The label itself will probably be centered in the column, giving the false appearance that your text alignment is not working.

===Growth===

To keep your dialog nicely balanced, the GUI2 engine may need to grow rows and/or columns. You can control which columns, for example, grow and which do not, by setting some with grow_factor = 1, and others with grow_factor = 0 (do not grow). While grow factors of 0 and 1 are the most common, you can use other values to adjust the relative growth if you really need to, see [[GUILayout]] for the gory details.

It it sometimes useful to include a column with a [spacer] and a grow_factor (often the only column with grow_factor != 0) whose sole purpose is to keep your GUI aligned nicely as the layout engine does its evil.

To force a column to stretch to fit available space, use horizontal_grow = true. Note that horizontal_grow is not compatible with horizontal_alignment. There is also a vertical_grow parameter.

If you need to see every little detail about the layout process, start wesnoth with --log-debug=gui/layout. Good luck with that.

===Definitions===
Many widgets can be configured to have to a different appearance, for example in our tree_view example we changed the definition of a toggle_button from the default of a checkbox by setting definition = "tree_view_node". This option was found by looking at the id of a toggle_button_definition in .../data/gui/widget/toggle_button_tree_view_node.cfg:

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib
###
### Definition of a toggle button to be used in a tree view as node fold/unfold indicator
###
[toggle_button_definition]
id = "tree_view_node" # <--- we can use 'definition = "tree_view_node"' in a [toggle_button] to select this definition
description = "Fold/unfold status indicator of a tree view node."
</syntaxhighlight>

{|
|There are many other definitions for buttons and other widget types in that directory. It would be nice to have a list (linked here), but for now you'll just have to look around.

We can even create our own custom definitions using [[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition()]]. In this example, we copy from .../data/gui/widget/toggle_button_tree_view_node.cfg with a slight change so that our button turns red ( '''~BLEND(255,0,0,1)''' ) when focused.

In this example, we will use wesnoth.wml_actions to create the WML tag [add_widget_def_demo].

Note the first line, a common convention for creating an alias for wml.tag.
|-
|[[File:Gui tutorial custom widget.png|center|thumb|Different definition of buttons, including one of our own (right)]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag -- save ourselves some typing
function wesnoth.wml_actions.add_widget_def_demo()
local definition = {
id = "tree_view_node_custom",
description = "Fold/unfold status indicator of a tree view node (MODIFIED).",
T.resolution {
min_width = 25,
min_height = 19,
default_width = 25,
default_height = 19,
max_width = 25,
max_height = 19,
-- Unselected - note there's no tags for unselected/selected, that's simply determined by the order
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/fold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/fold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/fold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
-- Selected
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/unfold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
}
}
gui.add_widget_definition("toggle_button", "tree_view_node_custom", definition)

local dialogDefinition = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid {
T.row {
T.column {
T.toggle_button {
definition = "default"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node_custom"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end

</syntaxhighlight>

See [[GUIWidgetDefinitionWML]] for more details on widget definitions.

You can also give the whole dialog a definition, like definition = "tooltip_large". There is no gui.add_window_definition(), however a window is technically a type of widget so it may be possible to create your own window definitions (please update this if you do).

===Panels===

===Canvases===
Part of panels? Sort of?

A canvas is a surface you can draw on. A dialog has them, as does a panel, and for these canvas 1 refers to the background, while canvas 2 refers to the foreground. Other widgets may have canvases that may have other meanings, or no canvases at all. See more at [[LuaAPI/gui/widget#set_canvas]].

Here's a fun little trick. Set your dialog background to be transparent:
<syntaxhighlight lang=lua>
local function preshow(dialog)
dialog:set_canvas(1, { } )
end
</syntaxhighlight>

Or, if you want an opaque GUI background with the screen behind it blurred like what you see behind the text of a [message], you can set your window definition to "message":
<syntaxhighlight lang=lua>
...
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
definition = "message",
...
</syntaxhighlight>

{|
|Here we take our [[#Progress Bar|progress bar]], and add a text overlay.

Note: either using text on a canvas is rather limited, or I just couldn't figure it out. For example, I could not get the text size any smaller, and any attempts to do so simply resulted in very blocky text. And the spaces were necessary so that the text wasn't stretched out. I also find it surprising that the progress bar does not have this feature inherently. So it's not a great example, but it should be enough to get you started using canvases. Be sure to visit the [[LuaAPI/gui/widget#set_canvas|link]] mentioned above for more options.
|-
|[[File:Gui tutorial canvas text.png|center|thumb|A progress bar in the background, with text in the foreground]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar_with_overlay()
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.grid {
T.row {
T.column {
T.panel { id = "panel",
T.grid {
T.row {
T.column {
T.button { id = "button",
label =_ "Press me"}
},
T.column {
T.progress_bar { id = "progress" }
},
T.column {
T.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
dialog.panel:set_canvas(2, { T.text { text_alignment = "center", font_size = 48,
text_markup = true, text = " " ..
dialog.progress.percentage .. "% " } } )
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

You may notice we added a panel and placed our text on the foreground canvas(2) on it, since the progress_bar itself does not support canvases.

===Placement===

You may have noticed that all of our dialogs are centered on the screen. This is the default. You can override this and place the dialog wherever you like by setting automatic_placement = false, along with x, y, width, and height at the top level of your dialog definition (next to tooltip =, etc).

'''This part about placement needs review'''
If you prefer, you may replace x and/or y with horizontal_placement and vertical_placement, such as horizontal_placement = "left". You can even set the placement values using WFL, for example horizontal_placement = "(gamemap_width / 3)" -- see [[#Using WFL with GUI2|Using WFL with GUI2]].

==Miscellaneous==

TODO: This stuff doesn't belong in a tutorial. It's worth documenting, but not here. Better to save these here for now than keep them on my laptop.

===Progress Bar===
{|
|A progress_bar is a graphical representation of a percent. In this example, we present the user with a puzzle. They must hit the button repeatedly before they can close the GUI. A progress_bar displays their current progress toward completion.
|-
|[[File:Gui tutorial progress bar.png|center|thumb|upright=2]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.button { id = "button",
label =_ "Press me"
}
},
wml.tag.column {
wml.tag.progress_bar { id = "progress" }
},
wml.tag.column {
wml.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end

gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

===Unit Preview Pane===

{|
|A unit_preview_pane takes a unit (or a unit type), and presents a graphical representation of the unit and its more important attributes, along with tooltips for additional details, in the same way that the recall menu does. Here we see an example of a unit which has picked up some items, including a weapon, which are affecting its stats.
|-
|[[File:Gui tutorial unit preview pane.png|center|thumb]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag

function wesnoth.wml_actions.recall_from_variable(cfg)
local from_array = cfg.from or wml.error(
"[recall_from_variable]: missing required from= ")
local to_var = cfg.to or wml.error(
"[recall_from_variable]: missing required to= ")
local unit_list = wml.array_access.get(from_array) or wml.error(
string.format("[recall_from_variable]: failed to fetch wml array %s",from_array))

local listboxItem = T.grid {
T.row {
T.column {
T.label { id = "available_unit",
linked_group = "available_unit"
}
}
}
}

local listbox_id = "available_units"
local listboxDefinition = T.listbox { id = listbox_id,
T.list_definition {
T.row {
T.column {
T.toggle_panel { listboxItem }
}
}
}
}
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.linked_group { id = "available_unit", fixed_width = true },
T.grid {
T.row { -- header
T.column {
T.grid {
T.row {
T.column {
border = "bottom",
border_size = 10,
T.label {
use_markup = true,
label = ""
.. _"Select unit to recall" .. ""
}
}
}
}
}
},
T.row { -- Body
T.column {
T.grid {
T.row {
T.column {
border = "right",
border_size = 40,
listboxDefinition
},
T.column {
T.unit_preview_pane { id = "unit_preview" }
}
}
}
}
},
T.row { -- Footer
T.column {
T.grid {
T.row {
T.column {
T.spacer { width = 400 }
},
T.column {
border = "top,right",
border_size = 10,
T.button { id = "ok",
label = _"OK"
}
}
}
}
}
}
}
}

local picked = 1

local function preshow(dialog)
local listbox = dialog[listbox_id]
for i,unit in ipairs(unit_list) do
listbox[i].available_unit.label = unit.name .. "(" ..
unit.language_name .. ")"
end
local function draw_unit()
wesnoth.units.to_recall(unit_list[listbox.selected_index])
local tmp = wesnoth.units.find_on_recall{ id =
unit_list[listbox.selected_index].id }[1]
dialog.unit_preview.unit = tmp
wesnoth.units.extract(tmp)
picked = listbox.selected_index
end
draw_unit()
listbox.on_modified = draw_unit
end

gui.show_dialog(dialogDefinition,preshow)

wml.variables[to_var] = picked - 1
end

</syntaxhighlight>

This should all be pretty self evident by now. We are provided with an array of stored units (from [store_unit] in WML). We create a listbox populated with units and we use the selected_index to determine which element in the table to send to unit_preview_pane. Since our input is an array of unit data, not actual units, we use [[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] to take the definition of one from our array and place it on the recall list (turning it into an actual unit), [[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] to fetch that unit in a form that the unit_preview_panel understands, and finally [[wesnoth.units.extract|wesnoth.units.extract]] to remove the unit from the recall list when we are done with it.

And of course we subtract one from the selected_index when we return our choice to WML, since lua arrays count from 1 and WML from 0.

The unit_preview_pane will also accept a unit_type instead of a specific unit.

==Appendix==

===Explore Your Options===

We've seen a lot of options that can be set to modify the behaviour of our dialogs, some on columns, some on widgets, etc. These are in the process of being documented [[GUIWidgetInstanceWML|here]], but if you would like to go straight to the source, the data Wesnoth uses to validate your configuration can be found in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui data/schema/gui] under your install directory.

Let's look at a scroll_label, for example. A scroll_label is a widget, so we look in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/widget_instances.cfg widget_instances.cfg] and find the following. Here we can see five parameters we can provide to our scroll_label (in addition to the ones available to all widgets, like id and definition, see the entry super=... which refers you to the widget_instance in the file [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/generic.cfg data/schema/gui/generic.cfg]), along with their types and default values. For example, we could set "link_aware = true", and if we do not we can assume that link_aware will be false. While this does not explain what these parameters do, the information provided in the schema directory is often helpful nonetheless.

<syntaxhighlight lang=wml>
[tag]
name="scroll_label"
min="0"
max="infinite"
super="$generic/widget_instance"
{DEFAULT_KEY "horizontal_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "vertical_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "wrap" bool true}
{DEFAULT_KEY "text_alignment" f_h_align "left"}
{DEFAULT_KEY "link_aware" bool false}
[/tag]
</syntaxhighlight>

We see that our scrollbars are of type scrollbar_mode. It would probably help if we knew what values are available to the scrollbar_mode. In [https://github.com/wesnoth/wesnoth/tree/master/data/schema/types/gui.cfg data/schema/types/gui.cfg] we find this:

<syntaxhighlight lang=wml>
[type]
name=scrollbar_mode
value="always|never|auto|initial_auto"
[/type]
</syntaxhighlight>

The variable types found in the schema files are described at [[GUIVariable]].

Note: The keys in the schema file correspond to the attributes used when configuring your widgets. They will not always align perfectly with keys used by the Lua API. For example, the slider uses maximum_value in its configuration, and max_value when using the Lua API:

<syntaxhighlight lang=wml>
[slider]
id="my_slider"
maximum_value = 100
[/slider]
</syntaxhighlight>

<syntaxhighlight lang=lua>
dialog.my_slider.max_value = 90
</syntaxhighlight>

===Using WFL with GUI2===

If you look at the variable type descriptions at [[GUIVariable]] you may notice that many of them start with "f_" and have "or formula" in the description. This means that you can use [[Wesnoth_Formula_Language|Wesnoth Formula Language (WFL)]] formulas in these fields, with certain variables made available to you (which variables and what they mean can be challenging to ascertain, but you can generally figure it out by example).

Looking at [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/window.cfg data/schema/gui/window.cfg] we see that 'height' has type f_unsigned, which tells us that height is an unsigned integer, and that we can use a WFL formula to define it in a window_definition. In [https://github.com/wesnoth/wesnoth/tree/master/data/gui/themes/default/window/wml_message.cfg data/gui/window/wml_message.cfg] (data/gui/themes/default/window/wml_message.cfg starting around 1.19.2), we find the line '''height = "(screen_height - 30)"'''. This does exactly what it looks like, it sets the height of our window to 30 pixels less than the height of the screen.

===Useful Links===
[[GUIToolkitWML]] - Documents the keys/values available on various objects (e.g. "what attributes can I set on a column?") 
[[LuaAPI/gui|LuaAPI/gui]] - Mostly about opening windows 
[[LuaAPI/types/widget]] - Widget attributes and callbacks 
[https://wiki.wesnoth.org/Category:GUI_WML_Reference GUI_WML_Reference] 
[https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui .../data/schema/gui/*.cfg] - Lists of valid options for various GUI objects 
[https://devdocs.wesnoth.org/layout_algorithm.html Layout Algorithm] - For windows, at least

===Credits===

The basic framework that composes the initial examples was lifted from LotI. It's a great place to find well written examples, but some of it is complex enough to be a little overwhelming when getting started.

Many examples, particularly tree view and multipage, are heavily derived from the World Conquest multiplayer campaign.

Talk:GUIToolkitWML

2024-09-26T14:03:30Z

White haired uncle: /* Feedback */

== Feedback ==

There are two Resolution sections, mostly redundant (ah, I see now, widget vs window, confusing at first)

popup_* - might want to mention the word "tooltip" in there - I assume that's what a "popup" is

Settings > has_helptip_message - "The string used to append the tooltip " should that be "The string used to append to the tooltip" (assuming that's how it works)?

"A linked group needs to have at least one size fixed. " - one fixed size?
: No, that's correct. It means either the width or height needs to be fixed. [[User:Celtic Minstrel|Celtic Minstrel]] ([[User talk:Celtic Minstrel|talk]]) 13:59, 26 September 2024 (UTC)

Toggle Button:

# GUIToolkitWML#Button is a link that doesn't seem to go anywhere (yet?)
# "List if the id's that have generate a return value:" - this looks like a list of the valid values of return_value_id. I have no idea what that phrase means as written. Also, quit (an alias for cancel) is missing

[[User:White haired uncle|White haired uncle]] ([[User talk:White haired uncle|talk]]) 14:03, 26 September 2024 (UTC)

Sandbox/GUI/Getting Started

2024-09-25T20:29:48Z

White haired uncle: /* Slider and Textbox */

So, it looks like I can't exclude this page/section from the search engine as I had hoped. I wanted to put this in a sandbox so that it wouldn't be published without some proper review.

==Introduction==

This guide is designed to help you get a simple Wesnoth GUI, implemented in lua, up and running while describing the basic building blocks along the way. It is written in a narrative format, where most examples build on previous examples, and therefore while not always necessary it may be desirable to read from start to finish. The reader, probably a UMC author, should have a basic knowledge of working with lua within Wesnoth.

Some would find creating a GUI in part or in full using WML simpler to follow, and those alternatives are available, for example [[LuaAPI/gui/example]], but we're using lua here. If you find WML easier to follow, you can always convert the lua tables that define the GUIs to WML using [[LuaAPI/wml#wml.tostring|wml.tostring]], for example:

<syntaxhighlight lang=lua>
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
</syntaxhighlight>

In some examples, instead of defining the entire GUI at once, we'll break out some parts into separate variables. If you try to view one in WML and get an error from wml.tostring() about expecting a WML table and not a table, try passing your variable(/table) inside a table:

<syntaxhighlight lang=lua>
print(wml.tostring({listboxItem}))
gui.show_lua_console()
</syntaxhighlight>

One distinct advantage of using WML to define your GUI layout is that you get better (any) validation. Invalid keys, and sometimes values, are often flagged in the log, unlike with lua where they are silently ignored. In the comments of our first GUI, below, is an example which loads a WML GUI configuration using [[LuaAPI/wml#wml.load|wml.load()]], validating against the GUI2 window schema.

===What is GUI2?===
Once upon a time, Wesnoth had a GUI system which is now commonly referred to as GUI1. As of 1.19, GUI1 has been almost completely replaced by GUI2. UMC authors will probably never encounter GUI1 and can simply use the terms GUI and GUI2 interchangeably, at least until GUI3 comes along.

Instead of spending a lot of time here giving an overview of what GUI2 is and what makes it great, and not so great, let's charge ahead so we can see it in action, and let readers who are interested look elsewhere(TODO: link) for a more formal definition. (TODO: is this the right approach for most readers?).

==Getting Started==

For example purposes, we'll create a directory in our campaign directory called lua containing a file called gui_tutorial.lua, and add a command in the prestart event for a scenario which will create a right-click menu option to invoke our new GUI. Of course there are other methods to invoke lua from WML, but this one will get us started. After all, we really just want to get something up on the screen ASAP, right?

===A most basic GUI===

{|
|[[File:Most basic gui.png|center|thumb|I can't believe this worked]]
|-
|In our prestart event, we create a simple menu item, which executes a single line of lua which calls the lua function most_basic_gui() which is found in gui_tutorial.lua:
|}

<syntaxhighlight lang=wml>
[set_menu_item]
id=most_basic_gui
description="Our first GUI"
[command]
[lua]
code=<<
wesnoth.require("~add-ons/<OUR_CAMPAIGN>/lua/gui_tutorial.lua").most_basic_gui()
>>
[/lua]
[/command]
[/set_menu_item]
</syntaxhighlight>

And create gui_tutorial.lua:
{| class="wikitable" style="margin:auto"
! !! The WML equivalent of dialogDefinition
|-
|
<syntaxhighlight lang=lua>
local function most_basic_gui()
local dialogDefinition = {
--click_dismiss = true, -- allow user to close dialog with click of a button
wml.tag.tooltip { id = "tooltip_large" }, -- required
wml.tag.helptip { id = "tooltip_large" }, -- required
wml.tag.grid { -- our most basic gui
wml.tag.row { -- a grid must include at least one row
wml.tag.column { -- a row needs a column
wml.tag.image { -- a column includes exactly one widget
label = "units/trolls/grunt.png"
}
}
}
}
}

local function preshow(dialog)
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
end
gui.show_dialog(dialogDefinition,preshow)

-- Or, if you want to define the gui in WML, something like:
-- local dialog_wml = wml.load("~add-ons/GUI_Tutorial/most_basic_gui.cfg",
-- true, "schema/gui_window.cfg")
-- gui.show_dialog(wml.get_child(dialog_wml, 'resolution'))
end
return { most_basic_gui = most_basic_gui}
</syntaxhighlight>
|
<syntaxhighlight lang=wml>
[tooltip]
id="tooltip_large"
[/tooltip]
[helptip]
id="tooltip_large"
[/helptip]
[grid]
[row]
[column]
[image]
label="units/trolls/grunt.png"
[/image]
[/column]
[/row]
[/grid]

</syntaxhighlight>
|}

In the above file, we have just the single function to create our GUI, followed by a return command which makes our function most_basic_gui() available to the [[LuaAPI/wesnoth#wesnoth.require|wesnoth.require()]] function as most_basic_gui().

Our function creates a table containing the definition of a "dialog", and then passes that to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]]. It should be noted that gui.show_dialog does not provide synchronization, so if your GUI makes changes to the game state, you'll need to jump through some hoops or you'll break replays and multiplayer, but that's not something we need to care about at this point, so just be aware that you may need to deal with it in the future.

Our dialog definition at this point includes three parts. The first two are a tooltip and a helptip, which are required and define how tooltips (use id = "tooltip_large" or id = "tooltip" or id = "tooltip_transparent"), and helptips (rarely used, but must be included here, and yes their definitions are "tooltip" not "helptip") will look (as we will see later, this really should be definition = "tooltip", but in this case it's id = "tooltip"). The third part is a grid, which is basically a table, like in HTML or MySQL, with rows and columns. A grid always contains at least one row. A row contains at least one column (note that a column does NOT span rows, it is completely contained within a row). Inside a column is exactly one item, a cell which contains a [[GUIWidgetDefinitionWML|widget]], in this case we'll use an image (later we'll see what else we can put in a cell). Note that we don't actually define a cell in our code, it's just a term used to refer to the contents of a column.

The preshow function is optional. If included in the call to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]], it is run before the GUI is displayed. In this case, we include it to display the dialog we created with lua in WML format. Near the end, in comments, we show how you would call [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] if you chose to define your dialog using WML. Note that what is shown here is the WML equivalent of our lua dialogDefinition, and not the complete WML you would need to use if you were to configure your GUI layout in WML.

Note: if you should try out the above, you'll have to hit escape or enter to close the GUI. Uncomment the "click_dismiss" line, and the user will be able to close the GUI with a mouse click.

===Adding a little flavor===

{|
|You may have noticed our GUI is missing a header and a way to close it when we're done admiring our work. Here we add a new first row to our grid, while demonstrating a couple formatting options: a border to put some distance between our grid cell and its neighbor, and the "use_markup = true" option to enable Pango support in our text.

Our third row adds an OK button at the bottom. You can associate actions with buttons to do all kinds of things, but here we just exploit the default behaviour to close the GUI.

Of course, we'll also have to modify our return to support the new function, and update our menu item(s) accordingly.
|-
|[[File:Most basic gui2.png|center|thumb|Adding header and a footer]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui2()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
gui.show_dialog(dialogDefinition)
end
return { most_basic_gui = most_basic_gui, most_basic_gui2 = most_basic_gui2 }
</syntaxhighlight>

===And a bit more===
{|

|And now a minor, but important change. We want to add a new text field next to the image in the body of our GUI. Obviously, we want to add a new column, but this is more difficult than when we added new rows in the previous example. The problem is that all rows (at a given level) in a grid must contain the same number of columns. We can't have two columns in the row that constitutes the body of our GUI, but only one in the header and one in the footer. To solve this problem, we replace our image widget with a new grid, which can use as many columns as we like (as long as they are the same within each row of our new grid). This new grid contains a row with two columns, but that is okay because the new grid itself is placed in a single column, which matches our single column header and footer (ok button), keeping the rows balanced.
|-
|[[File:Most basic gui3.png|center|thumb|Rows with different numbers of columns]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui3()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column { -- This is the only column in this row,
-- to match the number of columns in
-- the rows of our header and footer
wml.tag.grid { -- A new grid, so we can use a different
-- number of columns
wml.tag.row {
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
},
wml.tag.column {
wml.tag.label {
label = "A troll"
}
}
}
}
}
},
wml.tag.row { -- A footer
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = "Ok"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

While we see here just the simplest of examples, you can many levels of grids in grids, rows with multiple columns some of which containing grids, etc, to build complicated dialogs to your liking.

==Containers==

===Stacked Widget===

TODO

===Listbox===
{|
| Now we'd like to add some more monsters. Obviously, we could just add more rows, but what if we won't know until runtime how many and which ones? We could break up the definition of our dialog and add new rows dynamically, it's just a table after all, but fortunately we have a widget which handles this for us, a listbox. A listbox is kind of like an array, a collection of similar objects where the number of items can vary. We will tell the GUI where we want the box, and what each entry in the box will look like, and then at runtime we can add entries to the box.
|-
| [[File:Gui with listbox.png|center|thumb|Listbox with three items]]

<syntaxhighlight lang=lua>
local function gui_with_listbox()
local monsters = {
{ image = "units/trolls/grunt.png",
string = "A troll" },
{ image = "units/monsters/cuttlefish.png",
string = "A cuttlefish" },
{ image = "units/monsters/yeti.png",
string = "A yeti" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
}

local listboxDefinition = wml.tag.listbox { id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
listboxDefinition
}
},
wml.tag.row {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_label.label = monster.string
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We begin by creating a simple table which represents the data which will be presented in our listbox. In most cases, we probably wouldn't create that monster table here, but we need it for our example.

The variable listbox_id gives us an identifier for our listbox so we can reference it when we need to. We don't really need to use a variable here, it's just convenient.

We define the structure for the elements in our listbox, stored in listboxItem. Note that we've replaced the actual data with identifiers (e.g. 'units/trolls/grunt.png' becomes 'id = "monster_image"), since each element may have different data.

We define the listbox itself, specifying the identifier, and the definition of our listbox element (which looks a lot like a grid). The cell inside the column contains a variable which is just the listbox element definition we created above; it's not necessary to do this, we could have used one big table, but it's easier to read this way (IMO).

We replace the hardcoded data in our GUI body with our new listbox definition, again using a variable to make it easier to read.

We create a function, often called preshow(), which will be called for us as part of the drawing the GUI (see the new optional argument in [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] -- there's also an optional postshow(), but we don't need it here). This is where we pull the data from our example table into the listbox. We create a listbox variable associated with the listbox, identified by the listbox_id we assigned earlier, inside the dialog which gui.show_dialog() passes to preshow(). Then we iterate through our data table, using each entry from that table to populate a listbox item.

Let's look at that last action a little more closely using an example.

<syntaxhighlight lang=lua>
listbox[i].monster_image.label = monster.image
</syntaxhighlight>

Which we can read as "In listbox element i of our listbox, for the image with identifier monster_image which we defined in our listboxItem, use the data from the corresponding index i in our example data table" (you don't see the index i for the monsters table here, but remember we're iterating using ipairs, we could have just as easily used listbox[i].monster_image.label = monsters[i].image). If you were to step through all of the variable substitutions, you'd see that for i=1, our dialogDefinition is basically the same thing as it was in the earlier examples, just supplied from a table instead of hardcoded (note that you can hardcode entries in a listbox in your dialog definition using the [list_data] tag, aka wml.tag.list_data, which we do not demonstrate here).

You will probably notice that our data does not line up nicely in the GUI. We will fix that later. We'll also demonstrate how the user can select an item in a listbox, and how you can identify which item that was using the selected_index variable of the listbox.

===Tree View===
====Simple Tree View====
{|
| You may have noticed that clicking on a listbox item in our listbox caused it to be highlighted with a box around the contents. This is because the items in a listbox are selectable. This will be useful when we want to add actions, but it looks a bit odd if we just want to present a list of data.

Also, most of the data had to be formatted the same for each item in the listbox. We could, perhaps, include custom markup in our labels, but the actual layout, like the number of columns per row, had to be the same for every item.

Another way to present a list of data is the tree view. Since a tree view supports multiple data types, we may need to create multiple definitions for the elements in our list. These are known as nodes. It will also be necessary to explicitly define which node to use for each element when we populate our tree view.
|-
| [[File:Basic tree view.png|center|thumb|Tree_views can hold multiple data types (only trolls have names here)]]
|}
<syntaxhighlight lang=lua line>
local function basic_tree_view()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", type = "Seamonsters" },
{ image = "units/monsters/yeti.png", label = "A yeti",
type = "Coolers" }
}

local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "trolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name",
linked_group = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
},
wml.tag.node {
id = "nottrolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "monster_name",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_image",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_label",
fixed_width = true
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_tv:add_item_of_type("trolls_node")
dialog.monsters_tv[i].monster_name.label = monster.name -- only trolls have a name
else
dialog.monsters_tv:add_item_of_type("nottrolls_node")
end
-- All of our monsters have an image and a label
dialog.monsters_tv[i].monster_image.label = monster.image
dialog.monsters_tv[i].monster_label.label = monster.label
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We have expanded our list of monsters to include three types of trolls. We have also given each troll a name. This is of course a rather simplistic example, we could have simply given each monster that is not a troll an empty name, but it as presented here our approach serves the purpose of demonstrating how we deal with multiple data types. Our new tree view contains a node for each type of data we will present. In preshow, we explicitly define each element in our list using add_item_of_type(), and populate the item accordingly. [Note: in our listbox example, we could have used add_item() to add items to the listbox, but chose not to since that section was already introducing a number of new concepts. But here, since we have multiple types of items we need to be able to specify the type of the item when we add one, hence we need to use add_item_of_type()].

You may also note the addition of a few linked_group lines. We'll cover linked groups in more detail later, but as used here they instruct the GUI that each column using the same node type needs to be aligned with the others. For example, all of our trolls line up nicely.

====Building a Tree====
{|
| colspan="2" |At this point, one may wonder about the name "tree view", since what he have seen doesn't look much like a tree. To make a tree-like structure, we'll demonstrate adding children to nodes. At the top level our (upside-down) tree will have two nodes, one for trolls and one for everything else. A toggle_button (a type of button which changes states when you push it) will allow us to expand the trolls node to expose its children, which are themselves nodes, though they only contain a label at this point.
|-
| [[File:Basic tree view2a.png|center|thumb|Tree_view with Trolls folded]] || [[File:Basic tree view2b.png|center|thumb|Tree_view with Trolls unfolded]]
|}
<syntaxhighlight lang=lua line>
local function building_a_tree()
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
}
},
wml.tag.column {
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Show me the " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
-- You can refer to an object by its position

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[1].race_label.label = "Trolls"
-- dialog.monsters_tv[1].race_button.on_modified =
-- function()dialog.monsters_tv[1].unfolded =
-- dialog.monsters_tv[1].race_button.selected end

-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][1].monster_type.label = "Whelp"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][2].monster_type.label = "Shaman"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][3].monster_type.label = "Troll"

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[2].race_label.label = "Other scary things"
-- dialog.monsters_tv[2].race_button.visible = "hidden"

-- ... or you can refer to that object using the return value
-- from add_item_of_type
local troll_node = dialog.monsters_tv:add_item_of_type("race_node")
troll_node.race_label.label = "Trolls"
troll_node.race_button.on_modified =
function()
troll_node.unfolded = troll_node.race_button.selected
end
local item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Whelp"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Shaman"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Troll"

local not_troll_node =
dialog.monsters_tv:add_item_of_type("race_node")
not_troll_node.race_label.label = "Other scary things"
not_troll_node.race_button.visible = "hidden"

end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We define two nodes in our tree, a race_node for the top level, and a details_node for the children of a race_node. The rest of the interesting bits are in preshow().

We demonstrate two different ways of creating and accessing items, the first (commented out) just using the order in which they are created, while in the second we capture the result of add_item_of_type() in a variable we can use to refer to the newly defined object. The first method is shown primarily to demonstrate the structure of the resulting objects. The second method is perhaps easier to follow, and is almost necessary when you start doing things like dynamically deleting nodes, so it is in most cases a better practice (of course, you probably won't want to use the same variable for each node like we did, and perhaps not one local to the preview function).

We add a node, label it "Trolls", and add a callback to the button such that the children of the node will be visible (the node is "unfolded", a boolean value which defaults to false) when the button is checked (selected == true). Then we add three "details_node" nodes as children of this node.

Our second node, "Other scary things" will remain empty for now, so we'll set the visible attribute on its button to "hidden" (which is like false, but with hidden the widget still takes up space).

{|
| This example is rather ugly, both in the hardwired code and the appearance of the resulting GUI, but it addresses a couple important aspects of how tree views work and how we might use them. Let's clean it up a bit. We'll add an indentation_step_size to the tree view, along with a spacer and [[#Alignment|horizontal_alignment]] to our details node, to make the labels line up nicely, and change the button [[#Definitions|definition]] to replace the checkbox with something that looks like it belongs there. We will look at methods for handling layout in more depth [[#Appearance|later]].
|-
| [[File:Basic tree view2c.png|center|thumb|Our tree_view with proper alignment]]

<syntaxhighlight lang=lua>
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
indentation_step_size = 20,
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
definition = "tree_view_node"
}
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.spacer { width = 40 }
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}

</syntaxhighlight>

===Multi_page===
====Simple Multi_page====
{|
|-
Like a tree_view, a multi_page is a heterogeneous container which is dynamically populated, however, while a multi_page contains multiple elements (pages), only one page is displayed at any one time. Its purpose is perhaps best described by a couple of examples.
|-
[[File:Basic multipage.png|center|thumb|Multi_page showing active page]]
|}
<syntaxhighlight lang=lua>
local function basic_multipage()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll",
name = _"Bob", type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp",
name = "Junior", type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman",
name = _"Alice", type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish",
type = "Seamonsters" },
{ image = "units/monsters/yeti.png",
label = "A yeti",
type = "Coolers" }
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
multi_page
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}

local function preshow(dialog) -- Prepare the GUI before display
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_label.label = monster.label
end
--dialog.monsters_mp.selected_index = 5
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

As you can see, the code for our basic multi_page GUI looks a lot like our basic tree_view GUI. The difference is what is displayed. While both the tree_view and the multi_page containers contain five items, with the multi_page, only the first one is displayed. More specifically, only the page associated with the selected_index attribute of the multi_page object, which defaults to 1, is displayed. If we were to uncomment the last line in preshow(), we would still see only one item, but it would be the fifth one we allocated. It's nice to know all our pages are in there somewhere, but this example is pretty useless. What we need is a way to select which page we want to see from within our GUI.

====A More Useful Multi_page====

{|
| colspan="2" | To demonstrate the usefulness of a multi_page, and highlight its difference from a tree_view, we'll add a listbox to allow us to select the page to view. We'll also need to add a little action to our GUI.
|-
| style="align:centered" |[[File:More useful multipage.png|center|thumb|User selected Troll]] || [[File:More useful multipage2.png|center|thumb|User selected Cuttlefish]]
|}

<syntaxhighlight lang=lua>
local function more_useful_multi_page()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
race = "Trolls", tip = "Your uncle" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
race = "Trolls", tip = "Your nephew" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
race = "Trolls", tip = "Your auntie" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", race = "Seamonsters",
tip = "Not a fish" },
{ image = "units/monsters/yeti.png",
label = "A yeti", race = "Coolers",
tip = "ROAR!" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
}
}
}

local listboxDefinition = wml.tag.listbox {
id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
},
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
listboxDefinition
},
wml.tag.column {
wml.tag.spacer {
width = 30
}
},
wml.tag.column {
multi_page
},
}
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_image.tooltip = monster.tip
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_image.tooltip = monster.tip
dialog.monsters_mp[i].monster_label.label = monster.label
end
local function switch_page()
dialog.monsters_mp.selected_index = listbox.selected_index
end
listbox.on_modified = switch_page
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

Most of this should look pretty familiar. We've simply taken the previous example and added a second column to our GUI using code from an earlier example to add a listbox. In addition, we altered the page layout slightly, and added a spacer column in the dialog definition to approve the appearance.

The interesting stuff is in preshow(). Again we've merged in some listbox code from an earlier example, but we've also created a new local function switch_page(), which simply sets the selected_index attribute of our multi_page to the same as that of our listbox, and then we've configured the listbox.on_modified callback to call switch_page(). Now when the user selects an item in the listbox (updating listbox.selected_index and triggering listbox.on_modified), dialog.monsters_mp.selected_index is updated accordingly and therefore the visible page changes to the one associated with the selected unit.

Also note in preshow() we've added a new child to our monster_image identifier for both the listbox and the multi_page, a tooltip. When the user hovers the mouse over the image of one of our monsters, they'll see a popup message which we've added to our monster table. Try changing '''wml.tag.tooltip { id = "tooltip_large" }''' to '''wml.tag.tooltip { id = "tooltip }''' in the dialogDefinition to see a different tooltip style.

==Actions Have Consequences==

So far, our GUIs have only displayed some information on the screen, but at some point we're probably going to want to use a GUI to get input from the user. In this section we will look at return values that can be assigned to a widget based upon its state, and callbacks, which are functions invoked when something happens with a widget. As we will see, a button is a good example, as it can return a value or take an action, or both, when pressed. Earlier we saw how the selected_index attribute of some widgets, such as the listbox, can also be used as a sort of return value.

===Buttons===
{|
| colspan=2 | In this example, we'll create a couple buttons which provide the user a choice, use a handy confirmation popup to confirm that choice, and demonstrate how we get the results back where we can put them to use.
|-
| [[File:Basic return value.png|center|thumb|There can be only one]] || [[File:Basic return value_confirm.png|center|thumb|The user selected Alice, let's confirm this critical choice]]
|}

<syntaxhighlight lang=lua>
local function basic_return_value()

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "leader_lg",
fixed_height = true,
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" ..
_"Which unit shall lead your army?" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Alice" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/elves-wood/sylph.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 1
}
}
},
}
},
wml.tag.column {
wml.tag.spacer { width = 20 }
},
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Bob" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/human-loyalists/marshal.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 2
}
}
}
}
}
}
}
}
}
}
}
local user_chose = gui.show_dialog(dialogDefinition)
local leader
if user_chose == -1 then -- User closed the dialog by hitting the Enter key
leader = nil
end
if user_chose == -2 then -- User closed the dialog by hitting the Escape key
leader = nil
end

if user_chose == 1 then
leader = "Alice"
end
if user_chose == 2 then
leader = "Bob"
end

local confirmed_leader_choice

if leader ~= nil then
local query = _"You want " .. leader .. _" as your leader?"
confirmed_leader_choice = gui.confirm(query)
end

if confirmed_leader_choice then
wesnoth.message("Great!")
else
wesnoth.message("Fine, lead them yourself!")
end
end
</syntaxhighlight>

Here we've added a couple buttons, and assigned each of them a return value. When the user selects one of these buttons, the GUI is closed and the value of return_value is returned from gui.show_dialog(). We then use [https://wiki.wesnoth.org/LuaAPI/gui#gui.show_prompt gui.confirm()] which provides a very simple Yes/No popup and returns true or false, respectively. Other useful functions can be found on that page which provide handy alternatives to creating your own GUI for other simple user inputs.

The use of return_value is rather limited, as it only returns integers and can't be used with containers like listboxes. In more complex cases we'll need to turn to callback functions which are invoked when something happens to a widget, like clicking a button or a widget's value changing. Earlier, we saw an example of [[LuaAPI/types/widget#on_modified|widget.on_modified()]]. More examples of callbacks can be found at [[LuaAPI/types/widget#on_modified|that link]].

===Slider and Textbox===
{|
| Here we see a couple methods of getting more dynamic input from the user, a slider and a textbox presented in one silly example.
|-
| [[File:Slider and textbox.png|center|thumb|Two ways of getting input from the user]]
|}

<syntaxhighlight lang=lua>
function slider_and_textbox()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = _"How much gold will you pay for this old rusty sword?"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.slider {
id = "gold_sl",
minimum_value = 0,
maximum_value =
wesnoth.sides[wesnoth.current.side].gold,
value = math.floor(
wesnoth.sides[wesnoth.current.side].gold/2)
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.text_box {
id = "gold_tb",
--hint_text = _ "Enter gold here",
--hint_image = "images/gold_pile.png",
label = tostring(math.floor(
wesnoth.sides[wesnoth.current.side].gold/2))
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
local function show_input()
wesnoth.interface.add_chat_message(_"You chose " ..
dialog.gold_sl.value .. _" with the slider")
wesnoth.interface.add_chat_message(_"You entered " ..
tostring(dialog.gold_tb.text) .. _" in the text_box")
end
-- this is a button, so we use on_button_click, not on_left_click
dialog.ok.on_button_click = show_input

dialog.gold_sl.on_modified = function()
dialog.gold_tb.text = tostring(dialog.gold_sl.value)
end
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We create a slider, with a range from 0 to the amount of gold possessed by the current side and an initial value in the middle, and a text box with the same initial value. We assign a function to our OK button which simply reports on the values provided by the user. For no reason whatsoever, we add a callback such that when the user adjusts the slider the value in the textbox is update to match the slider.

Note that the textbox returns text, even though it looks like we're expecting the user to input a natural number. Remember to validate those inputs.

You can use text_hint to place a caption in the box that will help the user understand what to enter in the box, and possibly an image as well. For example, in the search box in the recall menu uses '''hint_text = _ "Search", hint_image = "icons/action/zoomdefault_25.png~FL(horiz)"'''. Of course, you can't have a hint and a label in the same text_box at the same time, so in our example we've only included them as comments.

There is also a widget called a spinner, which is kind of like the combination of a text_box and a slider. As of the release of 1.18, it appears to be unfinished so the strange syntax needed to make it work is probably not the best thing to document, and we will omit it for now.

==Appearance==

'''This section needs help'''

===Borders===

Borders allow you to force unused space around a column, for example so that your widgets don't runtogether. You can specify the border to be one or more of top, bottom, left, right, or all. The border_size sets the amount of padding, in pixels.

<syntaxhighlight lang=lua>
wml.tag.column{
border = "left, right"
border_size = 25
}
</syntaxhighlight>

===Alignment===
{|
| colspan=2 |By default, the GUI will usually center widgets in their cells, which is not always what we want. In this example, we use horizontal_alignment to move widgets around a little.

In more complex cases, it may be useful to add [[GUIWidgetDefinitionWML#Spacer|spacers]] to help force alignment, or use linked_groups to force consistent alignment for objects within a grid.
|-
| [[File:Gui tutorial alignment without.png|center|thumb|Default alignment]] ||[[File:Gui tutorial alignment with.png|center|thumb|Showing off some alignment options]]
|}
<syntaxhighlight lang=lua>
local function basic_alignment()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = "Ralph"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "right",
wml.tag.label {
label = "Sam"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/troll-hero-attack-se-4.png" -- 122x102
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "left",
wml.tag.label {
label = "Jr"
}
},
wml.tag.column {
horizontal_alignment = "right",
wml.tag.image {
label = "units/trolls/whelp.png" -- 72x72
}
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

The screenshots show the output of this example with and without the horizontal_alignment lines included above.

A label allows you to set the text_alignment field (e.g. text_alignment = "left"). Note, however, this only aligns the text within the label. The label itself will probably be centered in the column, giving the false appearance that your text alignment is not working.

===Growth===

To keep your dialog nicely balanced, the GUI2 engine may need to grow rows and/or columns. You can control which columns, for example, grow and which do not, by setting some with grow_factor = 1, and others with grow_factor = 0 (do not grow). While grow factors of 0 and 1 are the most common, you can use other values to adjust the relative growth if you really need to, see [[GUILayout]] for the gory details.

It it sometimes useful to include a column with a [spacer] and a grow_factor (often the only column with grow_factor != 0) whose sole purpose is to keep your GUI aligned nicely as the layout engine does its evil.

To force a column to stretch to fit available space, use horizontal_grow = true. Note that horizontal_grow is not compatible with horizontal_alignment. There is also a vertical_grow parameter.

If you need to see every little detail about the layout process, start wesnoth with --log-debug=gui/layout. Good luck with that.

===Definitions===
Many widgets can be configured to have to a different appearance, for example in our tree_view example we changed the definition of a toggle_button from the default of a checkbox by setting definition = "tree_view_node". This option was found by looking at the id of a toggle_button_definition in .../data/gui/widget/toggle_button_tree_view_node.cfg:

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib
###
### Definition of a toggle button to be used in a tree view as node fold/unfold indicator
###
[toggle_button_definition]
id = "tree_view_node" # <--- we can use 'definition = "tree_view_node"' in a [toggle_button] to select this definition
description = "Fold/unfold status indicator of a tree view node."
</syntaxhighlight>

{|
|There are many other definitions for buttons and other widget types in that directory. It would be nice to have a list (linked here), but for now you'll just have to look around.

We can even create our own custom definitions using [[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition()]]. In this example, we copy from .../data/gui/widget/toggle_button_tree_view_node.cfg with a slight change so that our button turns red ( '''~BLEND(255,0,0,1)''' ) when focused.

In this example, we will use wesnoth.wml_actions to create the WML tag [add_widget_def_demo].

Note the first line, a common convention for creating an alias for wml.tag.
|-
|[[File:Gui tutorial custom widget.png|center|thumb|Different definition of buttons, including one of our own (right)]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag -- save ourselves some typing
function wesnoth.wml_actions.add_widget_def_demo()
local definition = {
id = "tree_view_node_custom",
description = "Fold/unfold status indicator of a tree view node (MODIFIED).",
T.resolution {
min_width = 25,
min_height = 19,
default_width = 25,
default_height = 19,
max_width = 25,
max_height = 19,
-- Unselected - note there's no tags for unselected/selected, that's simply determined by the order
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/fold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/fold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/fold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
-- Selected
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/unfold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
}
}
gui.add_widget_definition("toggle_button", "tree_view_node_custom", definition)

local dialogDefinition = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid {
T.row {
T.column {
T.toggle_button {
definition = "default"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node_custom"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end

</syntaxhighlight>

See [[GUIWidgetDefinitionWML]] for more details on widget definitions.

You can also give the whole dialog a definition, like definition = "tooltip_large". There is no gui.add_window_definition(), however a window is technically a type of widget so it may be possible to create your own window definitions (please update this if you do).

===Panels===

===Canvases===
Part of panels? Sort of?

A canvas is a surface you can draw on. A dialog has them, as does a panel, and for these canvas 1 refers to the background, while canvas 2 refers to the foreground. Other widgets may have canvases that may have other meanings, or no canvases at all. See more at [[LuaAPI/gui/widget#set_canvas]].

Here's a fun little trick. Set your dialog background to be transparent:
<syntaxhighlight lang=lua>
local function preshow(dialog)
dialog:set_canvas(1, { } )
end
</syntaxhighlight>

Or, if you want an opaque GUI background with the screen behind it blurred like what you see behind the text of a [message], you can set your window definition to "message":
<syntaxhighlight lang=lua>
...
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
definition = "message",
...
</syntaxhighlight>

{|
|Here we take our [[#Progress Bar|progress bar]], and add a text overlay.

Note: either using text on a canvas is rather limited, or I just couldn't figure it out. For example, I could not get the text size any smaller, and any attempts to do so simply resulted in very blocky text. And the spaces were necessary so that the text wasn't stretched out. I also find it surprising that the progress bar does not have this feature inherently. So it's not a great example, but it should be enough to get you started using canvases. Be sure to visit the [[LuaAPI/gui/widget#set_canvas|link]] mentioned above for more options.
|-
|[[File:Gui tutorial canvas text.png|center|thumb|A progress bar in the background, with text in the foreground]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar_with_overlay()
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.grid {
T.row {
T.column {
T.panel { id = "panel",
T.grid {
T.row {
T.column {
T.button { id = "button",
label =_ "Press me"}
},
T.column {
T.progress_bar { id = "progress" }
},
T.column {
T.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
dialog.panel:set_canvas(2, { T.text { text_alignment = "center", font_size = 48,
text_markup = true, text = " " ..
dialog.progress.percentage .. "% " } } )
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

You may notice we added a panel and placed our text on the foreground canvas(2) on it, since the progress_bar itself does not support canvases.

===Placement===

You may have noticed that all of our dialogs are centered on the screen. This is the default. You can override this and place the dialog wherever you like by setting automatic_placement = false, along with x, y, width, and height at the top level of your dialog definition (next to tooltip =, etc).

'''This part about placement needs review'''
If you prefer, you may replace x and/or y with horizontal_placement and vertical_placement, such as horizontal_placement = "left". You can even set the placement values using WFL, for example horizontal_placement = "(gamemap_width / 3)" -- see [[#Using WFL with GUI2|Using WFL with GUI2]].

==Miscellaneous==

TODO: This stuff doesn't belong in a tutorial. It's worth documenting, but not here. Better to save these here for now than keep them on my laptop.

===Progress Bar===
{|
|A progress_bar is a graphical representation of a percent. In this example, we present the user with a puzzle. They must hit the button repeatedly before they can close the GUI. A progress_bar displays their current progress toward completion.
|-
|[[File:Gui tutorial progress bar.png|center|thumb|upright=2]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.button { id = "button",
label =_ "Press me"
}
},
wml.tag.column {
wml.tag.progress_bar { id = "progress" }
},
wml.tag.column {
wml.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end

gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

===Unit Preview Pane===

{|
|A unit_preview_pane takes a unit (or a unit type), and presents a graphical representation of the unit and its more important attributes, along with tooltips for additional details, in the same way that the recall menu does. Here we see an example of a unit which has picked up some items, including a weapon, which are affecting its stats.
|-
|[[File:Gui tutorial unit preview pane.png|center|thumb]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag

function wesnoth.wml_actions.recall_from_variable(cfg)
local from_array = cfg.from or wml.error(
"[recall_from_variable]: missing required from= ")
local to_var = cfg.to or wml.error(
"[recall_from_variable]: missing required to= ")
local unit_list = wml.array_access.get(from_array) or wml.error(
string.format("[recall_from_variable]: failed to fetch wml array %s",from_array))

local listboxItem = T.grid {
T.row {
T.column {
T.label { id = "available_unit",
linked_group = "available_unit"
}
}
}
}

local listbox_id = "available_units"
local listboxDefinition = T.listbox { id = listbox_id,
T.list_definition {
T.row {
T.column {
T.toggle_panel { listboxItem }
}
}
}
}
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.linked_group { id = "available_unit", fixed_width = true },
T.grid {
T.row { -- header
T.column {
T.grid {
T.row {
T.column {
border = "bottom",
border_size = 10,
T.label {
use_markup = true,
label = ""
.. _"Select unit to recall" .. ""
}
}
}
}
}
},
T.row { -- Body
T.column {
T.grid {
T.row {
T.column {
border = "right",
border_size = 40,
listboxDefinition
},
T.column {
T.unit_preview_pane { id = "unit_preview" }
}
}
}
}
},
T.row { -- Footer
T.column {
T.grid {
T.row {
T.column {
T.spacer { width = 400 }
},
T.column {
border = "top,right",
border_size = 10,
T.button { id = "ok",
label = _"OK"
}
}
}
}
}
}
}
}

local picked = 1

local function preshow(dialog)
local listbox = dialog[listbox_id]
for i,unit in ipairs(unit_list) do
listbox[i].available_unit.label = unit.name .. "(" ..
unit.language_name .. ")"
end
local function draw_unit()
wesnoth.units.to_recall(unit_list[listbox.selected_index])
local tmp = wesnoth.units.find_on_recall{ id =
unit_list[listbox.selected_index].id }[1]
dialog.unit_preview.unit = tmp
wesnoth.units.extract(tmp)
picked = listbox.selected_index
end
draw_unit()
listbox.on_modified = draw_unit
end

gui.show_dialog(dialogDefinition,preshow)

wml.variables[to_var] = picked - 1
end

</syntaxhighlight>

This should all be pretty self evident by now. We are provided with an array of stored units (from [store_unit] in WML). We create a listbox populated with units and we use the selected_index to determine which element in the table to send to unit_preview_pane. Since our input is an array of unit data, not actual units, we use [[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] to take the definition of one from our array and place it on the recall list (turning it into an actual unit), [[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] to fetch that unit in a form that the unit_preview_panel understands, and finally [[wesnoth.units.extract|wesnoth.units.extract]] to remove the unit from the recall list when we are done with it.

And of course we subtract one from the selected_index when we return our choice to WML, since lua arrays count from 1 and WML from 0.

The unit_preview_pane will also accept a unit_type instead of a specific unit.

==Appendix==

===Explore Your Options===

We've seen a lot of options that can be set to modify the behaviour of our dialogs, some on columns, some on widgets, etc. These are in the process of being documented [[GUIWidgetInstanceWML|here]], but if you would like to go straight to the source, the data Wesnoth uses to validate your configuration can be found in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui data/schema/gui] under your install directory.

Let's look at a scroll_label, for example. A scroll_label is a widget, so we look in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/widget_instances.cfg widget_instances.cfg] and find the following. Here we can see five parameters we can provide to our scroll_label (in addition to the ones available to all widgets, like id and definition, see the entry super=... which refers you to the widget_instance in the file [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/generic.cfg data/schema/gui/generic.cfg]), along with their types and default values. For example, we could set "link_aware = true", and if we do not we can assume that link_aware will be false. While this does not explain what these parameters do, the information provided in the schema directory is often helpful nonetheless.

<syntaxhighlight lang=wml>
[tag]
name="scroll_label"
min="0"
max="infinite"
super="$generic/widget_instance"
{DEFAULT_KEY "horizontal_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "vertical_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "wrap" bool true}
{DEFAULT_KEY "text_alignment" f_h_align "left"}
{DEFAULT_KEY "link_aware" bool false}
[/tag]
</syntaxhighlight>

We see that our scrollbars are of type scrollbar_mode. It would probably help if we knew what values are available to the scrollbar_mode. In [https://github.com/wesnoth/wesnoth/tree/master/data/schema/types/gui.cfg data/schema/types/gui.cfg] we find this:

<syntaxhighlight lang=wml>
[type]
name=scrollbar_mode
value="always|never|auto|initial_auto"
[/type]
</syntaxhighlight>

The variable types found in the schema files are described at [[GUIVariable]].

Note: The keys in the schema file correspond to the attributes used when configuring your widgets. They will not always align perfectly with keys used by the Lua API. For example, the slider uses maximum_value in its configuration, and max_value when using the Lua API:

<syntaxhighlight lang=wml>
[slider]
id="my_slider"
maximum_value = 100
[/slider]
</syntaxhighlight>

<syntaxhighlight lang=lua>
dialog.my_slider.max_value = 90
</syntaxhighlight>

===Using WFL with GUI2===

If you look at the variable type descriptions at [[GUIVariable]] you may notice that many of them start with "f_" and have "or formula" in the description. This means that you can use [[Wesnoth_Formula_Language|Wesnoth Formula Language (WFL)]] formulas in these fields, with certain variables made available to you (which variables and what they mean can be challenging to ascertain, but you can generally figure it out by example).

Looking at [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/window.cfg data/schema/gui/window.cfg] we see that 'height' has type f_unsigned, which tells us that height is an unsigned integer, and that we can use a WFL formula to define it in a window_definition. In [https://github.com/wesnoth/wesnoth/tree/master/data/gui/themes/default/window/wml_message.cfg data/gui/window/wml_message.cfg] (data/gui/themes/default/window/wml_message.cfg starting around 1.19.2), we find the line '''height = "(screen_height - 30)"'''. This does exactly what it looks like, it sets the height of our window to 30 pixels less than the height of the screen.

===Useful Links===
[[GUIToolkitWML]] - Documents the keys/values available on various objects (e.g. "what attributes can I set on a column?") 
[[LuaAPI/gui|LuaAPI/gui]] - Mostly about opening windows 
[[LuaAPI/types/widget]] - Widget attributes and callbacks 
[https://wiki.wesnoth.org/Category:GUI_WML_Reference GUI_WML_Reference] 
[https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui .../data/schema/gui/*.cfg] - Lists of valid options for various GUI objects 
[https://devdocs.wesnoth.org/layout_algorithm.html Layout Algorithm] - For windows, at least

===Credits===

The basic framework that composes the initial examples was lifted from LotI. It's a great place to find well written examples, but some of it is complex enough to be a little overwhelming when getting started.

Many examples, particularly tree view and multipage, are heavily derived from the World Conquest multiplayer campaign.

Talk:GUIToolkitWML

2024-09-25T10:53:00Z

White haired uncle: /* Feedback */

== Feedback ==

There are two Resolution sections, mostly redundant

popup_* - might want to mention the word "tooltip" in there - I assume that's what a "popup" is

Settings > has_helptip_message - "The string used to append the tooltip " should that be "The string used to append to the tooltip" (assuming that's how it works)?

"A linked group needs to have at least one size fixed. " - one fixed size?

Toggle Button:

# GUIToolkitWML#Button is a link that doesn't seem to go anywhere (yet?)
# "List if the id's that have generate a return value:" - this looks like a list of the valid values of return_value_id. I have no idea what that phrase means as written. Also, quit (an alias for cancel) is missing

Talk:GUIToolkitWML

2024-09-25T10:51:27Z

White haired uncle: /* Feedback */ new section

== Feedback ==

There are two Resolution sections, mostly redundant

popup_* - might want to mention the word "tooltip" in there - I assume that's what a "popup" is

Settings > has_helptip_message - "The string used to append the tooltip " should that be "The string used to append to the tooltip" (assuming that's how it works)?

"A linked group needs to have at least one size fixed. " - one fixed size?

Toggle Button:

1) GUIToolkitWML#Button is a link that doesn't seem to go anywhere (yet?)
2) "List if the id's that have generate a return value:" - this looks like a list of the valid values of return_value_id. I have no idea what that phrase means as written.
quit (an alias for cancel) is missing

Sandbox/GUI/Getting Started

2024-09-25T10:50:40Z

White haired uncle: /* Useful Links */

So, it looks like I can't exclude this page/section from the search engine as I had hoped. I wanted to put this in a sandbox so that it wouldn't be published without some proper review.

==Introduction==

This guide is designed to help you get a simple Wesnoth GUI, implemented in lua, up and running while describing the basic building blocks along the way. It is written in a narrative format, where most examples build on previous examples, and therefore while not always necessary it may be desirable to read from start to finish. The reader, probably a UMC author, should have a basic knowledge of working with lua within Wesnoth.

Some would find creating a GUI in part or in full using WML simpler to follow, and those alternatives are available, for example [[LuaAPI/gui/example]], but we're using lua here. If you find WML easier to follow, you can always convert the lua tables that define the GUIs to WML using [[LuaAPI/wml#wml.tostring|wml.tostring]], for example:

<syntaxhighlight lang=lua>
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
</syntaxhighlight>

In some examples, instead of defining the entire GUI at once, we'll break out some parts into separate variables. If you try to view one in WML and get an error from wml.tostring() about expecting a WML table and not a table, try passing your variable(/table) inside a table:

<syntaxhighlight lang=lua>
print(wml.tostring({listboxItem}))
gui.show_lua_console()
</syntaxhighlight>

One distinct advantage of using WML to define your GUI layout is that you get better (any) validation. Invalid keys, and sometimes values, are often flagged in the log, unlike with lua where they are silently ignored. In the comments of our first GUI, below, is an example which loads a WML GUI configuration using [[LuaAPI/wml#wml.load|wml.load()]], validating against the GUI2 window schema.

===What is GUI2?===
Once upon a time, Wesnoth had a GUI system which is now commonly referred to as GUI1. As of 1.19, GUI1 has been almost completely replaced by GUI2. UMC authors will probably never encounter GUI1 and can simply use the terms GUI and GUI2 interchangeably, at least until GUI3 comes along.

Instead of spending a lot of time here giving an overview of what GUI2 is and what makes it great, and not so great, let's charge ahead so we can see it in action, and let readers who are interested look elsewhere(TODO: link) for a more formal definition. (TODO: is this the right approach for most readers?).

==Getting Started==

For example purposes, we'll create a directory in our campaign directory called lua containing a file called gui_tutorial.lua, and add a command in the prestart event for a scenario which will create a right-click menu option to invoke our new GUI. Of course there are other methods to invoke lua from WML, but this one will get us started. After all, we really just want to get something up on the screen ASAP, right?

===A most basic GUI===

{|
|[[File:Most basic gui.png|center|thumb|I can't believe this worked]]
|-
|In our prestart event, we create a simple menu item, which executes a single line of lua which calls the lua function most_basic_gui() which is found in gui_tutorial.lua:
|}

<syntaxhighlight lang=wml>
[set_menu_item]
id=most_basic_gui
description="Our first GUI"
[command]
[lua]
code=<<
wesnoth.require("~add-ons/<OUR_CAMPAIGN>/lua/gui_tutorial.lua").most_basic_gui()
>>
[/lua]
[/command]
[/set_menu_item]
</syntaxhighlight>

And create gui_tutorial.lua:
{| class="wikitable" style="margin:auto"
! !! The WML equivalent of dialogDefinition
|-
|
<syntaxhighlight lang=lua>
local function most_basic_gui()
local dialogDefinition = {
--click_dismiss = true, -- allow user to close dialog with click of a button
wml.tag.tooltip { id = "tooltip_large" }, -- required
wml.tag.helptip { id = "tooltip_large" }, -- required
wml.tag.grid { -- our most basic gui
wml.tag.row { -- a grid must include at least one row
wml.tag.column { -- a row needs a column
wml.tag.image { -- a column includes exactly one widget
label = "units/trolls/grunt.png"
}
}
}
}
}

local function preshow(dialog)
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
end
gui.show_dialog(dialogDefinition,preshow)

-- Or, if you want to define the gui in WML, something like:
-- local dialog_wml = wml.load("~add-ons/GUI_Tutorial/most_basic_gui.cfg",
-- true, "schema/gui_window.cfg")
-- gui.show_dialog(wml.get_child(dialog_wml, 'resolution'))
end
return { most_basic_gui = most_basic_gui}
</syntaxhighlight>
|
<syntaxhighlight lang=wml>
[tooltip]
id="tooltip_large"
[/tooltip]
[helptip]
id="tooltip_large"
[/helptip]
[grid]
[row]
[column]
[image]
label="units/trolls/grunt.png"
[/image]
[/column]
[/row]
[/grid]

</syntaxhighlight>
|}

In the above file, we have just the single function to create our GUI, followed by a return command which makes our function most_basic_gui() available to the [[LuaAPI/wesnoth#wesnoth.require|wesnoth.require()]] function as most_basic_gui().

Our function creates a table containing the definition of a "dialog", and then passes that to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]]. It should be noted that gui.show_dialog does not provide synchronization, so if your GUI makes changes to the game state, you'll need to jump through some hoops or you'll break replays and multiplayer, but that's not something we need to care about at this point, so just be aware that you may need to deal with it in the future.

Our dialog definition at this point includes three parts. The first two are a tooltip and a helptip, which are required and define how tooltips (use id = "tooltip_large" or id = "tooltip" or id = "tooltip_transparent"), and helptips (rarely used, but must be included here, and yes their definitions are "tooltip" not "helptip") will look (as we will see later, this really should be definition = "tooltip", but in this case it's id = "tooltip"). The third part is a grid, which is basically a table, like in HTML or MySQL, with rows and columns. A grid always contains at least one row. A row contains at least one column (note that a column does NOT span rows, it is completely contained within a row). Inside a column is exactly one item, a cell which contains a [[GUIWidgetDefinitionWML|widget]], in this case we'll use an image (later we'll see what else we can put in a cell). Note that we don't actually define a cell in our code, it's just a term used to refer to the contents of a column.

The preshow function is optional. If included in the call to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]], it is run before the GUI is displayed. In this case, we include it to display the dialog we created with lua in WML format. Near the end, in comments, we show how you would call [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] if you chose to define your dialog using WML. Note that what is shown here is the WML equivalent of our lua dialogDefinition, and not the complete WML you would need to use if you were to configure your GUI layout in WML.

Note: if you should try out the above, you'll have to hit escape or enter to close the GUI. Uncomment the "click_dismiss" line, and the user will be able to close the GUI with a mouse click.

===Adding a little flavor===

{|
|You may have noticed our GUI is missing a header and a way to close it when we're done admiring our work. Here we add a new first row to our grid, while demonstrating a couple formatting options: a border to put some distance between our grid cell and its neighbor, and the "use_markup = true" option to enable Pango support in our text.

Our third row adds an OK button at the bottom. You can associate actions with buttons to do all kinds of things, but here we just exploit the default behaviour to close the GUI.

Of course, we'll also have to modify our return to support the new function, and update our menu item(s) accordingly.
|-
|[[File:Most basic gui2.png|center|thumb|Adding header and a footer]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui2()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
gui.show_dialog(dialogDefinition)
end
return { most_basic_gui = most_basic_gui, most_basic_gui2 = most_basic_gui2 }
</syntaxhighlight>

===And a bit more===
{|

|And now a minor, but important change. We want to add a new text field next to the image in the body of our GUI. Obviously, we want to add a new column, but this is more difficult than when we added new rows in the previous example. The problem is that all rows (at a given level) in a grid must contain the same number of columns. We can't have two columns in the row that constitutes the body of our GUI, but only one in the header and one in the footer. To solve this problem, we replace our image widget with a new grid, which can use as many columns as we like (as long as they are the same within each row of our new grid). This new grid contains a row with two columns, but that is okay because the new grid itself is placed in a single column, which matches our single column header and footer (ok button), keeping the rows balanced.
|-
|[[File:Most basic gui3.png|center|thumb|Rows with different numbers of columns]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui3()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column { -- This is the only column in this row,
-- to match the number of columns in
-- the rows of our header and footer
wml.tag.grid { -- A new grid, so we can use a different
-- number of columns
wml.tag.row {
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
},
wml.tag.column {
wml.tag.label {
label = "A troll"
}
}
}
}
}
},
wml.tag.row { -- A footer
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = "Ok"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

While we see here just the simplest of examples, you can many levels of grids in grids, rows with multiple columns some of which containing grids, etc, to build complicated dialogs to your liking.

==Containers==

===Stacked Widget===

TODO

===Listbox===
{|
| Now we'd like to add some more monsters. Obviously, we could just add more rows, but what if we won't know until runtime how many and which ones? We could break up the definition of our dialog and add new rows dynamically, it's just a table after all, but fortunately we have a widget which handles this for us, a listbox. A listbox is kind of like an array, a collection of similar objects where the number of items can vary. We will tell the GUI where we want the box, and what each entry in the box will look like, and then at runtime we can add entries to the box.
|-
| [[File:Gui with listbox.png|center|thumb|Listbox with three items]]

<syntaxhighlight lang=lua>
local function gui_with_listbox()
local monsters = {
{ image = "units/trolls/grunt.png",
string = "A troll" },
{ image = "units/monsters/cuttlefish.png",
string = "A cuttlefish" },
{ image = "units/monsters/yeti.png",
string = "A yeti" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
}

local listboxDefinition = wml.tag.listbox { id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
listboxDefinition
}
},
wml.tag.row {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_label.label = monster.string
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We begin by creating a simple table which represents the data which will be presented in our listbox. In most cases, we probably wouldn't create that monster table here, but we need it for our example.

The variable listbox_id gives us an identifier for our listbox so we can reference it when we need to. We don't really need to use a variable here, it's just convenient.

We define the structure for the elements in our listbox, stored in listboxItem. Note that we've replaced the actual data with identifiers (e.g. 'units/trolls/grunt.png' becomes 'id = "monster_image"), since each element may have different data.

We define the listbox itself, specifying the identifier, and the definition of our listbox element (which looks a lot like a grid). The cell inside the column contains a variable which is just the listbox element definition we created above; it's not necessary to do this, we could have used one big table, but it's easier to read this way (IMO).

We replace the hardcoded data in our GUI body with our new listbox definition, again using a variable to make it easier to read.

We create a function, often called preshow(), which will be called for us as part of the drawing the GUI (see the new optional argument in [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] -- there's also an optional postshow(), but we don't need it here). This is where we pull the data from our example table into the listbox. We create a listbox variable associated with the listbox, identified by the listbox_id we assigned earlier, inside the dialog which gui.show_dialog() passes to preshow(). Then we iterate through our data table, using each entry from that table to populate a listbox item.

Let's look at that last action a little more closely using an example.

<syntaxhighlight lang=lua>
listbox[i].monster_image.label = monster.image
</syntaxhighlight>

Which we can read as "In listbox element i of our listbox, for the image with identifier monster_image which we defined in our listboxItem, use the data from the corresponding index i in our example data table" (you don't see the index i for the monsters table here, but remember we're iterating using ipairs, we could have just as easily used listbox[i].monster_image.label = monsters[i].image). If you were to step through all of the variable substitutions, you'd see that for i=1, our dialogDefinition is basically the same thing as it was in the earlier examples, just supplied from a table instead of hardcoded (note that you can hardcode entries in a listbox in your dialog definition using the [list_data] tag, aka wml.tag.list_data, which we do not demonstrate here).

You will probably notice that our data does not line up nicely in the GUI. We will fix that later. We'll also demonstrate how the user can select an item in a listbox, and how you can identify which item that was using the selected_index variable of the listbox.

===Tree View===
====Simple Tree View====
{|
| You may have noticed that clicking on a listbox item in our listbox caused it to be highlighted with a box around the contents. This is because the items in a listbox are selectable. This will be useful when we want to add actions, but it looks a bit odd if we just want to present a list of data.

Also, most of the data had to be formatted the same for each item in the listbox. We could, perhaps, include custom markup in our labels, but the actual layout, like the number of columns per row, had to be the same for every item.

Another way to present a list of data is the tree view. Since a tree view supports multiple data types, we may need to create multiple definitions for the elements in our list. These are known as nodes. It will also be necessary to explicitly define which node to use for each element when we populate our tree view.
|-
| [[File:Basic tree view.png|center|thumb|Tree_views can hold multiple data types (only trolls have names here)]]
|}
<syntaxhighlight lang=lua line>
local function basic_tree_view()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", type = "Seamonsters" },
{ image = "units/monsters/yeti.png", label = "A yeti",
type = "Coolers" }
}

local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "trolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name",
linked_group = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
},
wml.tag.node {
id = "nottrolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "monster_name",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_image",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_label",
fixed_width = true
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_tv:add_item_of_type("trolls_node")
dialog.monsters_tv[i].monster_name.label = monster.name -- only trolls have a name
else
dialog.monsters_tv:add_item_of_type("nottrolls_node")
end
-- All of our monsters have an image and a label
dialog.monsters_tv[i].monster_image.label = monster.image
dialog.monsters_tv[i].monster_label.label = monster.label
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We have expanded our list of monsters to include three types of trolls. We have also given each troll a name. This is of course a rather simplistic example, we could have simply given each monster that is not a troll an empty name, but it as presented here our approach serves the purpose of demonstrating how we deal with multiple data types. Our new tree view contains a node for each type of data we will present. In preshow, we explicitly define each element in our list using add_item_of_type(), and populate the item accordingly. [Note: in our listbox example, we could have used add_item() to add items to the listbox, but chose not to since that section was already introducing a number of new concepts. But here, since we have multiple types of items we need to be able to specify the type of the item when we add one, hence we need to use add_item_of_type()].

You may also note the addition of a few linked_group lines. We'll cover linked groups in more detail later, but as used here they instruct the GUI that each column using the same node type needs to be aligned with the others. For example, all of our trolls line up nicely.

====Building a Tree====
{|
| colspan="2" |At this point, one may wonder about the name "tree view", since what he have seen doesn't look much like a tree. To make a tree-like structure, we'll demonstrate adding children to nodes. At the top level our (upside-down) tree will have two nodes, one for trolls and one for everything else. A toggle_button (a type of button which changes states when you push it) will allow us to expand the trolls node to expose its children, which are themselves nodes, though they only contain a label at this point.
|-
| [[File:Basic tree view2a.png|center|thumb|Tree_view with Trolls folded]] || [[File:Basic tree view2b.png|center|thumb|Tree_view with Trolls unfolded]]
|}
<syntaxhighlight lang=lua line>
local function building_a_tree()
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
}
},
wml.tag.column {
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Show me the " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
-- You can refer to an object by its position

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[1].race_label.label = "Trolls"
-- dialog.monsters_tv[1].race_button.on_modified =
-- function()dialog.monsters_tv[1].unfolded =
-- dialog.monsters_tv[1].race_button.selected end

-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][1].monster_type.label = "Whelp"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][2].monster_type.label = "Shaman"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][3].monster_type.label = "Troll"

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[2].race_label.label = "Other scary things"
-- dialog.monsters_tv[2].race_button.visible = "hidden"

-- ... or you can refer to that object using the return value
-- from add_item_of_type
local troll_node = dialog.monsters_tv:add_item_of_type("race_node")
troll_node.race_label.label = "Trolls"
troll_node.race_button.on_modified =
function()
troll_node.unfolded = troll_node.race_button.selected
end
local item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Whelp"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Shaman"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Troll"

local not_troll_node =
dialog.monsters_tv:add_item_of_type("race_node")
not_troll_node.race_label.label = "Other scary things"
not_troll_node.race_button.visible = "hidden"

end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We define two nodes in our tree, a race_node for the top level, and a details_node for the children of a race_node. The rest of the interesting bits are in preshow().

We demonstrate two different ways of creating and accessing items, the first (commented out) just using the order in which they are created, while in the second we capture the result of add_item_of_type() in a variable we can use to refer to the newly defined object. The first method is shown primarily to demonstrate the structure of the resulting objects. The second method is perhaps easier to follow, and is almost necessary when you start doing things like dynamically deleting nodes, so it is in most cases a better practice (of course, you probably won't want to use the same variable for each node like we did, and perhaps not one local to the preview function).

We add a node, label it "Trolls", and add a callback to the button such that the children of the node will be visible (the node is "unfolded", a boolean value which defaults to false) when the button is checked (selected == true). Then we add three "details_node" nodes as children of this node.

Our second node, "Other scary things" will remain empty for now, so we'll set the visible attribute on its button to "hidden" (which is like false, but with hidden the widget still takes up space).

{|
| This example is rather ugly, both in the hardwired code and the appearance of the resulting GUI, but it addresses a couple important aspects of how tree views work and how we might use them. Let's clean it up a bit. We'll add an indentation_step_size to the tree view, along with a spacer and [[#Alignment|horizontal_alignment]] to our details node, to make the labels line up nicely, and change the button [[#Definitions|definition]] to replace the checkbox with something that looks like it belongs there. We will look at methods for handling layout in more depth [[#Appearance|later]].
|-
| [[File:Basic tree view2c.png|center|thumb|Our tree_view with proper alignment]]

<syntaxhighlight lang=lua>
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
indentation_step_size = 20,
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
definition = "tree_view_node"
}
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.spacer { width = 40 }
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}

</syntaxhighlight>

===Multi_page===
====Simple Multi_page====
{|
|-
Like a tree_view, a multi_page is a heterogeneous container which is dynamically populated, however, while a multi_page contains multiple elements (pages), only one page is displayed at any one time. Its purpose is perhaps best described by a couple of examples.
|-
[[File:Basic multipage.png|center|thumb|Multi_page showing active page]]
|}
<syntaxhighlight lang=lua>
local function basic_multipage()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll",
name = _"Bob", type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp",
name = "Junior", type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman",
name = _"Alice", type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish",
type = "Seamonsters" },
{ image = "units/monsters/yeti.png",
label = "A yeti",
type = "Coolers" }
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
multi_page
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}

local function preshow(dialog) -- Prepare the GUI before display
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_label.label = monster.label
end
--dialog.monsters_mp.selected_index = 5
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

As you can see, the code for our basic multi_page GUI looks a lot like our basic tree_view GUI. The difference is what is displayed. While both the tree_view and the multi_page containers contain five items, with the multi_page, only the first one is displayed. More specifically, only the page associated with the selected_index attribute of the multi_page object, which defaults to 1, is displayed. If we were to uncomment the last line in preshow(), we would still see only one item, but it would be the fifth one we allocated. It's nice to know all our pages are in there somewhere, but this example is pretty useless. What we need is a way to select which page we want to see from within our GUI.

====A More Useful Multi_page====

{|
| colspan="2" | To demonstrate the usefulness of a multi_page, and highlight its difference from a tree_view, we'll add a listbox to allow us to select the page to view. We'll also need to add a little action to our GUI.
|-
| style="align:centered" |[[File:More useful multipage.png|center|thumb|User selected Troll]] || [[File:More useful multipage2.png|center|thumb|User selected Cuttlefish]]
|}

<syntaxhighlight lang=lua>
local function more_useful_multi_page()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
race = "Trolls", tip = "Your uncle" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
race = "Trolls", tip = "Your nephew" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
race = "Trolls", tip = "Your auntie" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", race = "Seamonsters",
tip = "Not a fish" },
{ image = "units/monsters/yeti.png",
label = "A yeti", race = "Coolers",
tip = "ROAR!" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
}
}
}

local listboxDefinition = wml.tag.listbox {
id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
},
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
listboxDefinition
},
wml.tag.column {
wml.tag.spacer {
width = 30
}
},
wml.tag.column {
multi_page
},
}
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_image.tooltip = monster.tip
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_image.tooltip = monster.tip
dialog.monsters_mp[i].monster_label.label = monster.label
end
local function switch_page()
dialog.monsters_mp.selected_index = listbox.selected_index
end
listbox.on_modified = switch_page
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

Most of this should look pretty familiar. We've simply taken the previous example and added a second column to our GUI using code from an earlier example to add a listbox. In addition, we altered the page layout slightly, and added a spacer column in the dialog definition to approve the appearance.

The interesting stuff is in preshow(). Again we've merged in some listbox code from an earlier example, but we've also created a new local function switch_page(), which simply sets the selected_index attribute of our multi_page to the same as that of our listbox, and then we've configured the listbox.on_modified callback to call switch_page(). Now when the user selects an item in the listbox (updating listbox.selected_index and triggering listbox.on_modified), dialog.monsters_mp.selected_index is updated accordingly and therefore the visible page changes to the one associated with the selected unit.

Also note in preshow() we've added a new child to our monster_image identifier for both the listbox and the multi_page, a tooltip. When the user hovers the mouse over the image of one of our monsters, they'll see a popup message which we've added to our monster table. Try changing '''wml.tag.tooltip { id = "tooltip_large" }''' to '''wml.tag.tooltip { id = "tooltip }''' in the dialogDefinition to see a different tooltip style.

==Actions Have Consequences==

So far, our GUIs have only displayed some information on the screen, but at some point we're probably going to want to use a GUI to get input from the user. In this section we will look at return values that can be assigned to a widget based upon its state, and callbacks, which are functions invoked when something happens with a widget. As we will see, a button is a good example, as it can return a value or take an action, or both, when pressed. Earlier we saw how the selected_index attribute of some widgets, such as the listbox, can also be used as a sort of return value.

===Buttons===
{|
| colspan=2 | In this example, we'll create a couple buttons which provide the user a choice, use a handy confirmation popup to confirm that choice, and demonstrate how we get the results back where we can put them to use.
|-
| [[File:Basic return value.png|center|thumb|There can be only one]] || [[File:Basic return value_confirm.png|center|thumb|The user selected Alice, let's confirm this critical choice]]
|}

<syntaxhighlight lang=lua>
local function basic_return_value()

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "leader_lg",
fixed_height = true,
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" ..
_"Which unit shall lead your army?" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Alice" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/elves-wood/sylph.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 1
}
}
},
}
},
wml.tag.column {
wml.tag.spacer { width = 20 }
},
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Bob" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/human-loyalists/marshal.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 2
}
}
}
}
}
}
}
}
}
}
}
local user_chose = gui.show_dialog(dialogDefinition)
local leader
if user_chose == -1 then -- User closed the dialog by hitting the Enter key
leader = nil
end
if user_chose == -2 then -- User closed the dialog by hitting the Escape key
leader = nil
end

if user_chose == 1 then
leader = "Alice"
end
if user_chose == 2 then
leader = "Bob"
end

local confirmed_leader_choice

if leader ~= nil then
local query = _"You want " .. leader .. _" as your leader?"
confirmed_leader_choice = gui.confirm(query)
end

if confirmed_leader_choice then
wesnoth.message("Great!")
else
wesnoth.message("Fine, lead them yourself!")
end
end
</syntaxhighlight>

Here we've added a couple buttons, and assigned each of them a return value. When the user selects one of these buttons, the GUI is closed and the value of return_value is returned from gui.show_dialog(). We then use [https://wiki.wesnoth.org/LuaAPI/gui#gui.show_prompt gui.confirm()] which provides a very simple Yes/No popup and returns true or false, respectively. Other useful functions can be found on that page which provide handy alternatives to creating your own GUI for other simple user inputs.

The use of return_value is rather limited, as it only returns integers and can't be used with containers like listboxes. In more complex cases we'll need to turn to callback functions which are invoked when something happens to a widget, like clicking a button or a widget's value changing. Earlier, we saw an example of [[LuaAPI/types/widget#on_modified|widget.on_modified()]]. More examples of callbacks can be found at [[LuaAPI/types/widget#on_modified|that link]].

===Slider and Textbox===
{|
| Here we see a couple methods of getting more dynamic input from the user, a slider and a textbox presented in one silly example.
|-
| [[File:Slider and textbox.png|center|thumb|Two ways of getting input from the user]]
|}

<syntaxhighlight lang=lua>
function scrollbar_and_textbox()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = _"How much gold will you pay for this old rusty sword?"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.slider {
id = "gold_sl",
minimum_value = 0,
maximum_value =
wesnoth.sides[wesnoth.current.side].gold,
value = math.floor(
wesnoth.sides[wesnoth.current.side].gold/2)
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.text_box {
id = "gold_tb",
--hint_text = _ "Enter gold here",
--hint_image = "images/gold_pile.png",
label = tostring(math.floor(
wesnoth.sides[wesnoth.current.side].gold/2))
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
local function show_input()
wesnoth.interface.add_chat_message(_"You chose " ..
dialog.gold_sl.value .. _" with the slider")
wesnoth.interface.add_chat_message(_"You entered " ..
tostring(dialog.gold_tb.text) .. _" in the text_box")
end
-- this is a button, so we use on_button_click, not on_left_click
dialog.ok.on_button_click = show_input

dialog.gold_sl.on_modified = function()
dialog.gold_tb.text = tostring(dialog.gold_sl.value)
end
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We create a slider, with a range from 0 to the amount of gold possessed by the current side and an initial value in the middle, and a text box with the same initial value. We assign a function to our OK button which simply reports on the values provided by the user. For no reason whatsoever, we add a callback such that when the user adjusts the slider the value in the textbox is update to match the slider.

Note that the textbox returns text, even though it looks like we're expecting the user to input a natural number. Remember to validate those inputs.

You can use text_hint to place a caption in the box that will help the user understand what to enter in the box, and possibly an image as well. For example, in the search box in the recall menu uses '''hint_text = _ "Search", hint_image = "icons/action/zoomdefault_25.png~FL(horiz)"'''. Of course, you can't have a hint and a label in the same text_box at the same time, so in our example we've only included them as comments.

There is also a widget called a spinner, which is kind of like the combination of a text_box and a slider. As of the release of 1.18, it appears to be unfinished so the strange syntax needed to make it work is probably not the best thing to document, and we will omit it for now.

==Appearance==

'''This section needs help'''

===Borders===

Borders allow you to force unused space around a column, for example so that your widgets don't runtogether. You can specify the border to be one or more of top, bottom, left, right, or all. The border_size sets the amount of padding, in pixels.

<syntaxhighlight lang=lua>
wml.tag.column{
border = "left, right"
border_size = 25
}
</syntaxhighlight>

===Alignment===
{|
| colspan=2 |By default, the GUI will usually center widgets in their cells, which is not always what we want. In this example, we use horizontal_alignment to move widgets around a little.

In more complex cases, it may be useful to add [[GUIWidgetDefinitionWML#Spacer|spacers]] to help force alignment, or use linked_groups to force consistent alignment for objects within a grid.
|-
| [[File:Gui tutorial alignment without.png|center|thumb|Default alignment]] ||[[File:Gui tutorial alignment with.png|center|thumb|Showing off some alignment options]]
|}
<syntaxhighlight lang=lua>
local function basic_alignment()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = "Ralph"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "right",
wml.tag.label {
label = "Sam"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/troll-hero-attack-se-4.png" -- 122x102
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "left",
wml.tag.label {
label = "Jr"
}
},
wml.tag.column {
horizontal_alignment = "right",
wml.tag.image {
label = "units/trolls/whelp.png" -- 72x72
}
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

The screenshots show the output of this example with and without the horizontal_alignment lines included above.

A label allows you to set the text_alignment field (e.g. text_alignment = "left"). Note, however, this only aligns the text within the label. The label itself will probably be centered in the column, giving the false appearance that your text alignment is not working.

===Growth===

To keep your dialog nicely balanced, the GUI2 engine may need to grow rows and/or columns. You can control which columns, for example, grow and which do not, by setting some with grow_factor = 1, and others with grow_factor = 0 (do not grow). While grow factors of 0 and 1 are the most common, you can use other values to adjust the relative growth if you really need to, see [[GUILayout]] for the gory details.

It it sometimes useful to include a column with a [spacer] and a grow_factor (often the only column with grow_factor != 0) whose sole purpose is to keep your GUI aligned nicely as the layout engine does its evil.

To force a column to stretch to fit available space, use horizontal_grow = true. Note that horizontal_grow is not compatible with horizontal_alignment. There is also a vertical_grow parameter.

If you need to see every little detail about the layout process, start wesnoth with --log-debug=gui/layout. Good luck with that.

===Definitions===
Many widgets can be configured to have to a different appearance, for example in our tree_view example we changed the definition of a toggle_button from the default of a checkbox by setting definition = "tree_view_node". This option was found by looking at the id of a toggle_button_definition in .../data/gui/widget/toggle_button_tree_view_node.cfg:

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib
###
### Definition of a toggle button to be used in a tree view as node fold/unfold indicator
###
[toggle_button_definition]
id = "tree_view_node" # <--- we can use 'definition = "tree_view_node"' in a [toggle_button] to select this definition
description = "Fold/unfold status indicator of a tree view node."
</syntaxhighlight>

{|
|There are many other definitions for buttons and other widget types in that directory. It would be nice to have a list (linked here), but for now you'll just have to look around.

We can even create our own custom definitions using [[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition()]]. In this example, we copy from .../data/gui/widget/toggle_button_tree_view_node.cfg with a slight change so that our button turns red ( '''~BLEND(255,0,0,1)''' ) when focused.

In this example, we will use wesnoth.wml_actions to create the WML tag [add_widget_def_demo].

Note the first line, a common convention for creating an alias for wml.tag.
|-
|[[File:Gui tutorial custom widget.png|center|thumb|Different definition of buttons, including one of our own (right)]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag -- save ourselves some typing
function wesnoth.wml_actions.add_widget_def_demo()
local definition = {
id = "tree_view_node_custom",
description = "Fold/unfold status indicator of a tree view node (MODIFIED).",
T.resolution {
min_width = 25,
min_height = 19,
default_width = 25,
default_height = 19,
max_width = 25,
max_height = 19,
-- Unselected - note there's no tags for unselected/selected, that's simply determined by the order
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/fold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/fold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/fold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
-- Selected
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/unfold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
}
}
gui.add_widget_definition("toggle_button", "tree_view_node_custom", definition)

local dialogDefinition = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid {
T.row {
T.column {
T.toggle_button {
definition = "default"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node_custom"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end

</syntaxhighlight>

See [[GUIWidgetDefinitionWML]] for more details on widget definitions.

You can also give the whole dialog a definition, like definition = "tooltip_large". There is no gui.add_window_definition(), however a window is technically a type of widget so it may be possible to create your own window definitions (please update this if you do).

===Panels===

===Canvases===
Part of panels? Sort of?

A canvas is a surface you can draw on. A dialog has them, as does a panel, and for these canvas 1 refers to the background, while canvas 2 refers to the foreground. Other widgets may have canvases that may have other meanings, or no canvases at all. See more at [[LuaAPI/gui/widget#set_canvas]].

Here's a fun little trick. Set your dialog background to be transparent:
<syntaxhighlight lang=lua>
local function preshow(dialog)
dialog:set_canvas(1, { } )
end
</syntaxhighlight>

Or, if you want an opaque GUI background with the screen behind it blurred like what you see behind the text of a [message], you can set your window definition to "message":
<syntaxhighlight lang=lua>
...
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
definition = "message",
...
</syntaxhighlight>

{|
|Here we take our [[#Progress Bar|progress bar]], and add a text overlay.

Note: either using text on a canvas is rather limited, or I just couldn't figure it out. For example, I could not get the text size any smaller, and any attempts to do so simply resulted in very blocky text. And the spaces were necessary so that the text wasn't stretched out. I also find it surprising that the progress bar does not have this feature inherently. So it's not a great example, but it should be enough to get you started using canvases. Be sure to visit the [[LuaAPI/gui/widget#set_canvas|link]] mentioned above for more options.
|-
|[[File:Gui tutorial canvas text.png|center|thumb|A progress bar in the background, with text in the foreground]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar_with_overlay()
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.grid {
T.row {
T.column {
T.panel { id = "panel",
T.grid {
T.row {
T.column {
T.button { id = "button",
label =_ "Press me"}
},
T.column {
T.progress_bar { id = "progress" }
},
T.column {
T.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
dialog.panel:set_canvas(2, { T.text { text_alignment = "center", font_size = 48,
text_markup = true, text = " " ..
dialog.progress.percentage .. "% " } } )
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

You may notice we added a panel and placed our text on the foreground canvas(2) on it, since the progress_bar itself does not support canvases.

===Placement===

You may have noticed that all of our dialogs are centered on the screen. This is the default. You can override this and place the dialog wherever you like by setting automatic_placement = false, along with x, y, width, and height at the top level of your dialog definition (next to tooltip =, etc).

'''This part about placement needs review'''
If you prefer, you may replace x and/or y with horizontal_placement and vertical_placement, such as horizontal_placement = "left". You can even set the placement values using WFL, for example horizontal_placement = "(gamemap_width / 3)" -- see [[#Using WFL with GUI2|Using WFL with GUI2]].

==Miscellaneous==

TODO: This stuff doesn't belong in a tutorial. It's worth documenting, but not here. Better to save these here for now than keep them on my laptop.

===Progress Bar===
{|
|A progress_bar is a graphical representation of a percent. In this example, we present the user with a puzzle. They must hit the button repeatedly before they can close the GUI. A progress_bar displays their current progress toward completion.
|-
|[[File:Gui tutorial progress bar.png|center|thumb|upright=2]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.button { id = "button",
label =_ "Press me"
}
},
wml.tag.column {
wml.tag.progress_bar { id = "progress" }
},
wml.tag.column {
wml.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end

gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

===Unit Preview Pane===

{|
|A unit_preview_pane takes a unit (or a unit type), and presents a graphical representation of the unit and its more important attributes, along with tooltips for additional details, in the same way that the recall menu does. Here we see an example of a unit which has picked up some items, including a weapon, which are affecting its stats.
|-
|[[File:Gui tutorial unit preview pane.png|center|thumb]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag

function wesnoth.wml_actions.recall_from_variable(cfg)
local from_array = cfg.from or wml.error(
"[recall_from_variable]: missing required from= ")
local to_var = cfg.to or wml.error(
"[recall_from_variable]: missing required to= ")
local unit_list = wml.array_access.get(from_array) or wml.error(
string.format("[recall_from_variable]: failed to fetch wml array %s",from_array))

local listboxItem = T.grid {
T.row {
T.column {
T.label { id = "available_unit",
linked_group = "available_unit"
}
}
}
}

local listbox_id = "available_units"
local listboxDefinition = T.listbox { id = listbox_id,
T.list_definition {
T.row {
T.column {
T.toggle_panel { listboxItem }
}
}
}
}
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.linked_group { id = "available_unit", fixed_width = true },
T.grid {
T.row { -- header
T.column {
T.grid {
T.row {
T.column {
border = "bottom",
border_size = 10,
T.label {
use_markup = true,
label = ""
.. _"Select unit to recall" .. ""
}
}
}
}
}
},
T.row { -- Body
T.column {
T.grid {
T.row {
T.column {
border = "right",
border_size = 40,
listboxDefinition
},
T.column {
T.unit_preview_pane { id = "unit_preview" }
}
}
}
}
},
T.row { -- Footer
T.column {
T.grid {
T.row {
T.column {
T.spacer { width = 400 }
},
T.column {
border = "top,right",
border_size = 10,
T.button { id = "ok",
label = _"OK"
}
}
}
}
}
}
}
}

local picked = 1

local function preshow(dialog)
local listbox = dialog[listbox_id]
for i,unit in ipairs(unit_list) do
listbox[i].available_unit.label = unit.name .. "(" ..
unit.language_name .. ")"
end
local function draw_unit()
wesnoth.units.to_recall(unit_list[listbox.selected_index])
local tmp = wesnoth.units.find_on_recall{ id =
unit_list[listbox.selected_index].id }[1]
dialog.unit_preview.unit = tmp
wesnoth.units.extract(tmp)
picked = listbox.selected_index
end
draw_unit()
listbox.on_modified = draw_unit
end

gui.show_dialog(dialogDefinition,preshow)

wml.variables[to_var] = picked - 1
end

</syntaxhighlight>

This should all be pretty self evident by now. We are provided with an array of stored units (from [store_unit] in WML). We create a listbox populated with units and we use the selected_index to determine which element in the table to send to unit_preview_pane. Since our input is an array of unit data, not actual units, we use [[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] to take the definition of one from our array and place it on the recall list (turning it into an actual unit), [[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] to fetch that unit in a form that the unit_preview_panel understands, and finally [[wesnoth.units.extract|wesnoth.units.extract]] to remove the unit from the recall list when we are done with it.

And of course we subtract one from the selected_index when we return our choice to WML, since lua arrays count from 1 and WML from 0.

The unit_preview_pane will also accept a unit_type instead of a specific unit.

==Appendix==

===Explore Your Options===

We've seen a lot of options that can be set to modify the behaviour of our dialogs, some on columns, some on widgets, etc. These are in the process of being documented [[GUIWidgetInstanceWML|here]], but if you would like to go straight to the source, the data Wesnoth uses to validate your configuration can be found in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui data/schema/gui] under your install directory.

Let's look at a scroll_label, for example. A scroll_label is a widget, so we look in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/widget_instances.cfg widget_instances.cfg] and find the following. Here we can see five parameters we can provide to our scroll_label (in addition to the ones available to all widgets, like id and definition, see the entry super=... which refers you to the widget_instance in the file [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/generic.cfg data/schema/gui/generic.cfg]), along with their types and default values. For example, we could set "link_aware = true", and if we do not we can assume that link_aware will be false. While this does not explain what these parameters do, the information provided in the schema directory is often helpful nonetheless.

<syntaxhighlight lang=wml>
[tag]
name="scroll_label"
min="0"
max="infinite"
super="$generic/widget_instance"
{DEFAULT_KEY "horizontal_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "vertical_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "wrap" bool true}
{DEFAULT_KEY "text_alignment" f_h_align "left"}
{DEFAULT_KEY "link_aware" bool false}
[/tag]
</syntaxhighlight>

We see that our scrollbars are of type scrollbar_mode. It would probably help if we knew what values are available to the scrollbar_mode. In [https://github.com/wesnoth/wesnoth/tree/master/data/schema/types/gui.cfg data/schema/types/gui.cfg] we find this:

<syntaxhighlight lang=wml>
[type]
name=scrollbar_mode
value="always|never|auto|initial_auto"
[/type]
</syntaxhighlight>

The variable types found in the schema files are described at [[GUIVariable]].

Note: The keys in the schema file correspond to the attributes used when configuring your widgets. They will not always align perfectly with keys used by the Lua API. For example, the slider uses maximum_value in its configuration, and max_value when using the Lua API:

<syntaxhighlight lang=wml>
[slider]
id="my_slider"
maximum_value = 100
[/slider]
</syntaxhighlight>

<syntaxhighlight lang=lua>
dialog.my_slider.max_value = 90
</syntaxhighlight>

===Using WFL with GUI2===

If you look at the variable type descriptions at [[GUIVariable]] you may notice that many of them start with "f_" and have "or formula" in the description. This means that you can use [[Wesnoth_Formula_Language|Wesnoth Formula Language (WFL)]] formulas in these fields, with certain variables made available to you (which variables and what they mean can be challenging to ascertain, but you can generally figure it out by example).

Looking at [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/window.cfg data/schema/gui/window.cfg] we see that 'height' has type f_unsigned, which tells us that height is an unsigned integer, and that we can use a WFL formula to define it in a window_definition. In [https://github.com/wesnoth/wesnoth/tree/master/data/gui/themes/default/window/wml_message.cfg data/gui/window/wml_message.cfg] (data/gui/themes/default/window/wml_message.cfg starting around 1.19.2), we find the line '''height = "(screen_height - 30)"'''. This does exactly what it looks like, it sets the height of our window to 30 pixels less than the height of the screen.

===Useful Links===
[[GUIToolkitWML]] - Documents the keys/values available on various objects (e.g. "what attributes can I set on a column?") 
[[LuaAPI/gui|LuaAPI/gui]] - Mostly about opening windows 
[[LuaAPI/types/widget]] - Widget attributes and callbacks 
[https://wiki.wesnoth.org/Category:GUI_WML_Reference GUI_WML_Reference] 
[https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui .../data/schema/gui/*.cfg] - Lists of valid options for various GUI objects 
[https://devdocs.wesnoth.org/layout_algorithm.html Layout Algorithm] - For windows, at least

===Credits===

The basic framework that composes the initial examples was lifted from LotI. It's a great place to find well written examples, but some of it is complex enough to be a little overwhelming when getting started.

Many examples, particularly tree view and multipage, are heavily derived from the World Conquest multiplayer campaign.

Sandbox/GUI/Getting Started

2024-09-25T10:48:15Z

White haired uncle: /* Appendix */

So, it looks like I can't exclude this page/section from the search engine as I had hoped. I wanted to put this in a sandbox so that it wouldn't be published without some proper review.

==Introduction==

This guide is designed to help you get a simple Wesnoth GUI, implemented in lua, up and running while describing the basic building blocks along the way. It is written in a narrative format, where most examples build on previous examples, and therefore while not always necessary it may be desirable to read from start to finish. The reader, probably a UMC author, should have a basic knowledge of working with lua within Wesnoth.

Some would find creating a GUI in part or in full using WML simpler to follow, and those alternatives are available, for example [[LuaAPI/gui/example]], but we're using lua here. If you find WML easier to follow, you can always convert the lua tables that define the GUIs to WML using [[LuaAPI/wml#wml.tostring|wml.tostring]], for example:

<syntaxhighlight lang=lua>
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
</syntaxhighlight>

In some examples, instead of defining the entire GUI at once, we'll break out some parts into separate variables. If you try to view one in WML and get an error from wml.tostring() about expecting a WML table and not a table, try passing your variable(/table) inside a table:

<syntaxhighlight lang=lua>
print(wml.tostring({listboxItem}))
gui.show_lua_console()
</syntaxhighlight>

One distinct advantage of using WML to define your GUI layout is that you get better (any) validation. Invalid keys, and sometimes values, are often flagged in the log, unlike with lua where they are silently ignored. In the comments of our first GUI, below, is an example which loads a WML GUI configuration using [[LuaAPI/wml#wml.load|wml.load()]], validating against the GUI2 window schema.

===What is GUI2?===
Once upon a time, Wesnoth had a GUI system which is now commonly referred to as GUI1. As of 1.19, GUI1 has been almost completely replaced by GUI2. UMC authors will probably never encounter GUI1 and can simply use the terms GUI and GUI2 interchangeably, at least until GUI3 comes along.

Instead of spending a lot of time here giving an overview of what GUI2 is and what makes it great, and not so great, let's charge ahead so we can see it in action, and let readers who are interested look elsewhere(TODO: link) for a more formal definition. (TODO: is this the right approach for most readers?).

==Getting Started==

For example purposes, we'll create a directory in our campaign directory called lua containing a file called gui_tutorial.lua, and add a command in the prestart event for a scenario which will create a right-click menu option to invoke our new GUI. Of course there are other methods to invoke lua from WML, but this one will get us started. After all, we really just want to get something up on the screen ASAP, right?

===A most basic GUI===

{|
|[[File:Most basic gui.png|center|thumb|I can't believe this worked]]
|-
|In our prestart event, we create a simple menu item, which executes a single line of lua which calls the lua function most_basic_gui() which is found in gui_tutorial.lua:
|}

<syntaxhighlight lang=wml>
[set_menu_item]
id=most_basic_gui
description="Our first GUI"
[command]
[lua]
code=<<
wesnoth.require("~add-ons/<OUR_CAMPAIGN>/lua/gui_tutorial.lua").most_basic_gui()
>>
[/lua]
[/command]
[/set_menu_item]
</syntaxhighlight>

And create gui_tutorial.lua:
{| class="wikitable" style="margin:auto"
! !! The WML equivalent of dialogDefinition
|-
|
<syntaxhighlight lang=lua>
local function most_basic_gui()
local dialogDefinition = {
--click_dismiss = true, -- allow user to close dialog with click of a button
wml.tag.tooltip { id = "tooltip_large" }, -- required
wml.tag.helptip { id = "tooltip_large" }, -- required
wml.tag.grid { -- our most basic gui
wml.tag.row { -- a grid must include at least one row
wml.tag.column { -- a row needs a column
wml.tag.image { -- a column includes exactly one widget
label = "units/trolls/grunt.png"
}
}
}
}
}

local function preshow(dialog)
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
end
gui.show_dialog(dialogDefinition,preshow)

-- Or, if you want to define the gui in WML, something like:
-- local dialog_wml = wml.load("~add-ons/GUI_Tutorial/most_basic_gui.cfg",
-- true, "schema/gui_window.cfg")
-- gui.show_dialog(wml.get_child(dialog_wml, 'resolution'))
end
return { most_basic_gui = most_basic_gui}
</syntaxhighlight>
|
<syntaxhighlight lang=wml>
[tooltip]
id="tooltip_large"
[/tooltip]
[helptip]
id="tooltip_large"
[/helptip]
[grid]
[row]
[column]
[image]
label="units/trolls/grunt.png"
[/image]
[/column]
[/row]
[/grid]

</syntaxhighlight>
|}

In the above file, we have just the single function to create our GUI, followed by a return command which makes our function most_basic_gui() available to the [[LuaAPI/wesnoth#wesnoth.require|wesnoth.require()]] function as most_basic_gui().

Our function creates a table containing the definition of a "dialog", and then passes that to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]]. It should be noted that gui.show_dialog does not provide synchronization, so if your GUI makes changes to the game state, you'll need to jump through some hoops or you'll break replays and multiplayer, but that's not something we need to care about at this point, so just be aware that you may need to deal with it in the future.

Our dialog definition at this point includes three parts. The first two are a tooltip and a helptip, which are required and define how tooltips (use id = "tooltip_large" or id = "tooltip" or id = "tooltip_transparent"), and helptips (rarely used, but must be included here, and yes their definitions are "tooltip" not "helptip") will look (as we will see later, this really should be definition = "tooltip", but in this case it's id = "tooltip"). The third part is a grid, which is basically a table, like in HTML or MySQL, with rows and columns. A grid always contains at least one row. A row contains at least one column (note that a column does NOT span rows, it is completely contained within a row). Inside a column is exactly one item, a cell which contains a [[GUIWidgetDefinitionWML|widget]], in this case we'll use an image (later we'll see what else we can put in a cell). Note that we don't actually define a cell in our code, it's just a term used to refer to the contents of a column.

The preshow function is optional. If included in the call to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]], it is run before the GUI is displayed. In this case, we include it to display the dialog we created with lua in WML format. Near the end, in comments, we show how you would call [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] if you chose to define your dialog using WML. Note that what is shown here is the WML equivalent of our lua dialogDefinition, and not the complete WML you would need to use if you were to configure your GUI layout in WML.

Note: if you should try out the above, you'll have to hit escape or enter to close the GUI. Uncomment the "click_dismiss" line, and the user will be able to close the GUI with a mouse click.

===Adding a little flavor===

{|
|You may have noticed our GUI is missing a header and a way to close it when we're done admiring our work. Here we add a new first row to our grid, while demonstrating a couple formatting options: a border to put some distance between our grid cell and its neighbor, and the "use_markup = true" option to enable Pango support in our text.

Our third row adds an OK button at the bottom. You can associate actions with buttons to do all kinds of things, but here we just exploit the default behaviour to close the GUI.

Of course, we'll also have to modify our return to support the new function, and update our menu item(s) accordingly.
|-
|[[File:Most basic gui2.png|center|thumb|Adding header and a footer]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui2()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
gui.show_dialog(dialogDefinition)
end
return { most_basic_gui = most_basic_gui, most_basic_gui2 = most_basic_gui2 }
</syntaxhighlight>

===And a bit more===
{|

|And now a minor, but important change. We want to add a new text field next to the image in the body of our GUI. Obviously, we want to add a new column, but this is more difficult than when we added new rows in the previous example. The problem is that all rows (at a given level) in a grid must contain the same number of columns. We can't have two columns in the row that constitutes the body of our GUI, but only one in the header and one in the footer. To solve this problem, we replace our image widget with a new grid, which can use as many columns as we like (as long as they are the same within each row of our new grid). This new grid contains a row with two columns, but that is okay because the new grid itself is placed in a single column, which matches our single column header and footer (ok button), keeping the rows balanced.
|-
|[[File:Most basic gui3.png|center|thumb|Rows with different numbers of columns]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui3()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column { -- This is the only column in this row,
-- to match the number of columns in
-- the rows of our header and footer
wml.tag.grid { -- A new grid, so we can use a different
-- number of columns
wml.tag.row {
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
},
wml.tag.column {
wml.tag.label {
label = "A troll"
}
}
}
}
}
},
wml.tag.row { -- A footer
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = "Ok"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

While we see here just the simplest of examples, you can many levels of grids in grids, rows with multiple columns some of which containing grids, etc, to build complicated dialogs to your liking.

==Containers==

===Stacked Widget===

TODO

===Listbox===
{|
| Now we'd like to add some more monsters. Obviously, we could just add more rows, but what if we won't know until runtime how many and which ones? We could break up the definition of our dialog and add new rows dynamically, it's just a table after all, but fortunately we have a widget which handles this for us, a listbox. A listbox is kind of like an array, a collection of similar objects where the number of items can vary. We will tell the GUI where we want the box, and what each entry in the box will look like, and then at runtime we can add entries to the box.
|-
| [[File:Gui with listbox.png|center|thumb|Listbox with three items]]

<syntaxhighlight lang=lua>
local function gui_with_listbox()
local monsters = {
{ image = "units/trolls/grunt.png",
string = "A troll" },
{ image = "units/monsters/cuttlefish.png",
string = "A cuttlefish" },
{ image = "units/monsters/yeti.png",
string = "A yeti" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
}

local listboxDefinition = wml.tag.listbox { id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
listboxDefinition
}
},
wml.tag.row {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_label.label = monster.string
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We begin by creating a simple table which represents the data which will be presented in our listbox. In most cases, we probably wouldn't create that monster table here, but we need it for our example.

The variable listbox_id gives us an identifier for our listbox so we can reference it when we need to. We don't really need to use a variable here, it's just convenient.

We define the structure for the elements in our listbox, stored in listboxItem. Note that we've replaced the actual data with identifiers (e.g. 'units/trolls/grunt.png' becomes 'id = "monster_image"), since each element may have different data.

We define the listbox itself, specifying the identifier, and the definition of our listbox element (which looks a lot like a grid). The cell inside the column contains a variable which is just the listbox element definition we created above; it's not necessary to do this, we could have used one big table, but it's easier to read this way (IMO).

We replace the hardcoded data in our GUI body with our new listbox definition, again using a variable to make it easier to read.

We create a function, often called preshow(), which will be called for us as part of the drawing the GUI (see the new optional argument in [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] -- there's also an optional postshow(), but we don't need it here). This is where we pull the data from our example table into the listbox. We create a listbox variable associated with the listbox, identified by the listbox_id we assigned earlier, inside the dialog which gui.show_dialog() passes to preshow(). Then we iterate through our data table, using each entry from that table to populate a listbox item.

Let's look at that last action a little more closely using an example.

<syntaxhighlight lang=lua>
listbox[i].monster_image.label = monster.image
</syntaxhighlight>

Which we can read as "In listbox element i of our listbox, for the image with identifier monster_image which we defined in our listboxItem, use the data from the corresponding index i in our example data table" (you don't see the index i for the monsters table here, but remember we're iterating using ipairs, we could have just as easily used listbox[i].monster_image.label = monsters[i].image). If you were to step through all of the variable substitutions, you'd see that for i=1, our dialogDefinition is basically the same thing as it was in the earlier examples, just supplied from a table instead of hardcoded (note that you can hardcode entries in a listbox in your dialog definition using the [list_data] tag, aka wml.tag.list_data, which we do not demonstrate here).

You will probably notice that our data does not line up nicely in the GUI. We will fix that later. We'll also demonstrate how the user can select an item in a listbox, and how you can identify which item that was using the selected_index variable of the listbox.

===Tree View===
====Simple Tree View====
{|
| You may have noticed that clicking on a listbox item in our listbox caused it to be highlighted with a box around the contents. This is because the items in a listbox are selectable. This will be useful when we want to add actions, but it looks a bit odd if we just want to present a list of data.

Also, most of the data had to be formatted the same for each item in the listbox. We could, perhaps, include custom markup in our labels, but the actual layout, like the number of columns per row, had to be the same for every item.

Another way to present a list of data is the tree view. Since a tree view supports multiple data types, we may need to create multiple definitions for the elements in our list. These are known as nodes. It will also be necessary to explicitly define which node to use for each element when we populate our tree view.
|-
| [[File:Basic tree view.png|center|thumb|Tree_views can hold multiple data types (only trolls have names here)]]
|}
<syntaxhighlight lang=lua line>
local function basic_tree_view()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", type = "Seamonsters" },
{ image = "units/monsters/yeti.png", label = "A yeti",
type = "Coolers" }
}

local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "trolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name",
linked_group = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
},
wml.tag.node {
id = "nottrolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "monster_name",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_image",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_label",
fixed_width = true
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_tv:add_item_of_type("trolls_node")
dialog.monsters_tv[i].monster_name.label = monster.name -- only trolls have a name
else
dialog.monsters_tv:add_item_of_type("nottrolls_node")
end
-- All of our monsters have an image and a label
dialog.monsters_tv[i].monster_image.label = monster.image
dialog.monsters_tv[i].monster_label.label = monster.label
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We have expanded our list of monsters to include three types of trolls. We have also given each troll a name. This is of course a rather simplistic example, we could have simply given each monster that is not a troll an empty name, but it as presented here our approach serves the purpose of demonstrating how we deal with multiple data types. Our new tree view contains a node for each type of data we will present. In preshow, we explicitly define each element in our list using add_item_of_type(), and populate the item accordingly. [Note: in our listbox example, we could have used add_item() to add items to the listbox, but chose not to since that section was already introducing a number of new concepts. But here, since we have multiple types of items we need to be able to specify the type of the item when we add one, hence we need to use add_item_of_type()].

You may also note the addition of a few linked_group lines. We'll cover linked groups in more detail later, but as used here they instruct the GUI that each column using the same node type needs to be aligned with the others. For example, all of our trolls line up nicely.

====Building a Tree====
{|
| colspan="2" |At this point, one may wonder about the name "tree view", since what he have seen doesn't look much like a tree. To make a tree-like structure, we'll demonstrate adding children to nodes. At the top level our (upside-down) tree will have two nodes, one for trolls and one for everything else. A toggle_button (a type of button which changes states when you push it) will allow us to expand the trolls node to expose its children, which are themselves nodes, though they only contain a label at this point.
|-
| [[File:Basic tree view2a.png|center|thumb|Tree_view with Trolls folded]] || [[File:Basic tree view2b.png|center|thumb|Tree_view with Trolls unfolded]]
|}
<syntaxhighlight lang=lua line>
local function building_a_tree()
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
}
},
wml.tag.column {
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Show me the " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
-- You can refer to an object by its position

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[1].race_label.label = "Trolls"
-- dialog.monsters_tv[1].race_button.on_modified =
-- function()dialog.monsters_tv[1].unfolded =
-- dialog.monsters_tv[1].race_button.selected end

-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][1].monster_type.label = "Whelp"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][2].monster_type.label = "Shaman"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][3].monster_type.label = "Troll"

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[2].race_label.label = "Other scary things"
-- dialog.monsters_tv[2].race_button.visible = "hidden"

-- ... or you can refer to that object using the return value
-- from add_item_of_type
local troll_node = dialog.monsters_tv:add_item_of_type("race_node")
troll_node.race_label.label = "Trolls"
troll_node.race_button.on_modified =
function()
troll_node.unfolded = troll_node.race_button.selected
end
local item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Whelp"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Shaman"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Troll"

local not_troll_node =
dialog.monsters_tv:add_item_of_type("race_node")
not_troll_node.race_label.label = "Other scary things"
not_troll_node.race_button.visible = "hidden"

end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We define two nodes in our tree, a race_node for the top level, and a details_node for the children of a race_node. The rest of the interesting bits are in preshow().

We demonstrate two different ways of creating and accessing items, the first (commented out) just using the order in which they are created, while in the second we capture the result of add_item_of_type() in a variable we can use to refer to the newly defined object. The first method is shown primarily to demonstrate the structure of the resulting objects. The second method is perhaps easier to follow, and is almost necessary when you start doing things like dynamically deleting nodes, so it is in most cases a better practice (of course, you probably won't want to use the same variable for each node like we did, and perhaps not one local to the preview function).

We add a node, label it "Trolls", and add a callback to the button such that the children of the node will be visible (the node is "unfolded", a boolean value which defaults to false) when the button is checked (selected == true). Then we add three "details_node" nodes as children of this node.

Our second node, "Other scary things" will remain empty for now, so we'll set the visible attribute on its button to "hidden" (which is like false, but with hidden the widget still takes up space).

{|
| This example is rather ugly, both in the hardwired code and the appearance of the resulting GUI, but it addresses a couple important aspects of how tree views work and how we might use them. Let's clean it up a bit. We'll add an indentation_step_size to the tree view, along with a spacer and [[#Alignment|horizontal_alignment]] to our details node, to make the labels line up nicely, and change the button [[#Definitions|definition]] to replace the checkbox with something that looks like it belongs there. We will look at methods for handling layout in more depth [[#Appearance|later]].
|-
| [[File:Basic tree view2c.png|center|thumb|Our tree_view with proper alignment]]

<syntaxhighlight lang=lua>
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
indentation_step_size = 20,
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
definition = "tree_view_node"
}
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.spacer { width = 40 }
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}

</syntaxhighlight>

===Multi_page===
====Simple Multi_page====
{|
|-
Like a tree_view, a multi_page is a heterogeneous container which is dynamically populated, however, while a multi_page contains multiple elements (pages), only one page is displayed at any one time. Its purpose is perhaps best described by a couple of examples.
|-
[[File:Basic multipage.png|center|thumb|Multi_page showing active page]]
|}
<syntaxhighlight lang=lua>
local function basic_multipage()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll",
name = _"Bob", type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp",
name = "Junior", type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman",
name = _"Alice", type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish",
type = "Seamonsters" },
{ image = "units/monsters/yeti.png",
label = "A yeti",
type = "Coolers" }
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
multi_page
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}

local function preshow(dialog) -- Prepare the GUI before display
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_label.label = monster.label
end
--dialog.monsters_mp.selected_index = 5
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

As you can see, the code for our basic multi_page GUI looks a lot like our basic tree_view GUI. The difference is what is displayed. While both the tree_view and the multi_page containers contain five items, with the multi_page, only the first one is displayed. More specifically, only the page associated with the selected_index attribute of the multi_page object, which defaults to 1, is displayed. If we were to uncomment the last line in preshow(), we would still see only one item, but it would be the fifth one we allocated. It's nice to know all our pages are in there somewhere, but this example is pretty useless. What we need is a way to select which page we want to see from within our GUI.

====A More Useful Multi_page====

{|
| colspan="2" | To demonstrate the usefulness of a multi_page, and highlight its difference from a tree_view, we'll add a listbox to allow us to select the page to view. We'll also need to add a little action to our GUI.
|-
| style="align:centered" |[[File:More useful multipage.png|center|thumb|User selected Troll]] || [[File:More useful multipage2.png|center|thumb|User selected Cuttlefish]]
|}

<syntaxhighlight lang=lua>
local function more_useful_multi_page()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
race = "Trolls", tip = "Your uncle" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
race = "Trolls", tip = "Your nephew" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
race = "Trolls", tip = "Your auntie" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", race = "Seamonsters",
tip = "Not a fish" },
{ image = "units/monsters/yeti.png",
label = "A yeti", race = "Coolers",
tip = "ROAR!" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
}
}
}

local listboxDefinition = wml.tag.listbox {
id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
},
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
listboxDefinition
},
wml.tag.column {
wml.tag.spacer {
width = 30
}
},
wml.tag.column {
multi_page
},
}
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_image.tooltip = monster.tip
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_image.tooltip = monster.tip
dialog.monsters_mp[i].monster_label.label = monster.label
end
local function switch_page()
dialog.monsters_mp.selected_index = listbox.selected_index
end
listbox.on_modified = switch_page
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

Most of this should look pretty familiar. We've simply taken the previous example and added a second column to our GUI using code from an earlier example to add a listbox. In addition, we altered the page layout slightly, and added a spacer column in the dialog definition to approve the appearance.

The interesting stuff is in preshow(). Again we've merged in some listbox code from an earlier example, but we've also created a new local function switch_page(), which simply sets the selected_index attribute of our multi_page to the same as that of our listbox, and then we've configured the listbox.on_modified callback to call switch_page(). Now when the user selects an item in the listbox (updating listbox.selected_index and triggering listbox.on_modified), dialog.monsters_mp.selected_index is updated accordingly and therefore the visible page changes to the one associated with the selected unit.

Also note in preshow() we've added a new child to our monster_image identifier for both the listbox and the multi_page, a tooltip. When the user hovers the mouse over the image of one of our monsters, they'll see a popup message which we've added to our monster table. Try changing '''wml.tag.tooltip { id = "tooltip_large" }''' to '''wml.tag.tooltip { id = "tooltip }''' in the dialogDefinition to see a different tooltip style.

==Actions Have Consequences==

So far, our GUIs have only displayed some information on the screen, but at some point we're probably going to want to use a GUI to get input from the user. In this section we will look at return values that can be assigned to a widget based upon its state, and callbacks, which are functions invoked when something happens with a widget. As we will see, a button is a good example, as it can return a value or take an action, or both, when pressed. Earlier we saw how the selected_index attribute of some widgets, such as the listbox, can also be used as a sort of return value.

===Buttons===
{|
| colspan=2 | In this example, we'll create a couple buttons which provide the user a choice, use a handy confirmation popup to confirm that choice, and demonstrate how we get the results back where we can put them to use.
|-
| [[File:Basic return value.png|center|thumb|There can be only one]] || [[File:Basic return value_confirm.png|center|thumb|The user selected Alice, let's confirm this critical choice]]
|}

<syntaxhighlight lang=lua>
local function basic_return_value()

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "leader_lg",
fixed_height = true,
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" ..
_"Which unit shall lead your army?" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Alice" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/elves-wood/sylph.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 1
}
}
},
}
},
wml.tag.column {
wml.tag.spacer { width = 20 }
},
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Bob" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/human-loyalists/marshal.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 2
}
}
}
}
}
}
}
}
}
}
}
local user_chose = gui.show_dialog(dialogDefinition)
local leader
if user_chose == -1 then -- User closed the dialog by hitting the Enter key
leader = nil
end
if user_chose == -2 then -- User closed the dialog by hitting the Escape key
leader = nil
end

if user_chose == 1 then
leader = "Alice"
end
if user_chose == 2 then
leader = "Bob"
end

local confirmed_leader_choice

if leader ~= nil then
local query = _"You want " .. leader .. _" as your leader?"
confirmed_leader_choice = gui.confirm(query)
end

if confirmed_leader_choice then
wesnoth.message("Great!")
else
wesnoth.message("Fine, lead them yourself!")
end
end
</syntaxhighlight>

Here we've added a couple buttons, and assigned each of them a return value. When the user selects one of these buttons, the GUI is closed and the value of return_value is returned from gui.show_dialog(). We then use [https://wiki.wesnoth.org/LuaAPI/gui#gui.show_prompt gui.confirm()] which provides a very simple Yes/No popup and returns true or false, respectively. Other useful functions can be found on that page which provide handy alternatives to creating your own GUI for other simple user inputs.

The use of return_value is rather limited, as it only returns integers and can't be used with containers like listboxes. In more complex cases we'll need to turn to callback functions which are invoked when something happens to a widget, like clicking a button or a widget's value changing. Earlier, we saw an example of [[LuaAPI/types/widget#on_modified|widget.on_modified()]]. More examples of callbacks can be found at [[LuaAPI/types/widget#on_modified|that link]].

===Slider and Textbox===
{|
| Here we see a couple methods of getting more dynamic input from the user, a slider and a textbox presented in one silly example.
|-
| [[File:Slider and textbox.png|center|thumb|Two ways of getting input from the user]]
|}

<syntaxhighlight lang=lua>
function scrollbar_and_textbox()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = _"How much gold will you pay for this old rusty sword?"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.slider {
id = "gold_sl",
minimum_value = 0,
maximum_value =
wesnoth.sides[wesnoth.current.side].gold,
value = math.floor(
wesnoth.sides[wesnoth.current.side].gold/2)
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.text_box {
id = "gold_tb",
--hint_text = _ "Enter gold here",
--hint_image = "images/gold_pile.png",
label = tostring(math.floor(
wesnoth.sides[wesnoth.current.side].gold/2))
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
local function show_input()
wesnoth.interface.add_chat_message(_"You chose " ..
dialog.gold_sl.value .. _" with the slider")
wesnoth.interface.add_chat_message(_"You entered " ..
tostring(dialog.gold_tb.text) .. _" in the text_box")
end
-- this is a button, so we use on_button_click, not on_left_click
dialog.ok.on_button_click = show_input

dialog.gold_sl.on_modified = function()
dialog.gold_tb.text = tostring(dialog.gold_sl.value)
end
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We create a slider, with a range from 0 to the amount of gold possessed by the current side and an initial value in the middle, and a text box with the same initial value. We assign a function to our OK button which simply reports on the values provided by the user. For no reason whatsoever, we add a callback such that when the user adjusts the slider the value in the textbox is update to match the slider.

Note that the textbox returns text, even though it looks like we're expecting the user to input a natural number. Remember to validate those inputs.

You can use text_hint to place a caption in the box that will help the user understand what to enter in the box, and possibly an image as well. For example, in the search box in the recall menu uses '''hint_text = _ "Search", hint_image = "icons/action/zoomdefault_25.png~FL(horiz)"'''. Of course, you can't have a hint and a label in the same text_box at the same time, so in our example we've only included them as comments.

There is also a widget called a spinner, which is kind of like the combination of a text_box and a slider. As of the release of 1.18, it appears to be unfinished so the strange syntax needed to make it work is probably not the best thing to document, and we will omit it for now.

==Appearance==

'''This section needs help'''

===Borders===

Borders allow you to force unused space around a column, for example so that your widgets don't runtogether. You can specify the border to be one or more of top, bottom, left, right, or all. The border_size sets the amount of padding, in pixels.

<syntaxhighlight lang=lua>
wml.tag.column{
border = "left, right"
border_size = 25
}
</syntaxhighlight>

===Alignment===
{|
| colspan=2 |By default, the GUI will usually center widgets in their cells, which is not always what we want. In this example, we use horizontal_alignment to move widgets around a little.

In more complex cases, it may be useful to add [[GUIWidgetDefinitionWML#Spacer|spacers]] to help force alignment, or use linked_groups to force consistent alignment for objects within a grid.
|-
| [[File:Gui tutorial alignment without.png|center|thumb|Default alignment]] ||[[File:Gui tutorial alignment with.png|center|thumb|Showing off some alignment options]]
|}
<syntaxhighlight lang=lua>
local function basic_alignment()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = "Ralph"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "right",
wml.tag.label {
label = "Sam"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/troll-hero-attack-se-4.png" -- 122x102
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "left",
wml.tag.label {
label = "Jr"
}
},
wml.tag.column {
horizontal_alignment = "right",
wml.tag.image {
label = "units/trolls/whelp.png" -- 72x72
}
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

The screenshots show the output of this example with and without the horizontal_alignment lines included above.

A label allows you to set the text_alignment field (e.g. text_alignment = "left"). Note, however, this only aligns the text within the label. The label itself will probably be centered in the column, giving the false appearance that your text alignment is not working.

===Growth===

To keep your dialog nicely balanced, the GUI2 engine may need to grow rows and/or columns. You can control which columns, for example, grow and which do not, by setting some with grow_factor = 1, and others with grow_factor = 0 (do not grow). While grow factors of 0 and 1 are the most common, you can use other values to adjust the relative growth if you really need to, see [[GUILayout]] for the gory details.

It it sometimes useful to include a column with a [spacer] and a grow_factor (often the only column with grow_factor != 0) whose sole purpose is to keep your GUI aligned nicely as the layout engine does its evil.

To force a column to stretch to fit available space, use horizontal_grow = true. Note that horizontal_grow is not compatible with horizontal_alignment. There is also a vertical_grow parameter.

If you need to see every little detail about the layout process, start wesnoth with --log-debug=gui/layout. Good luck with that.

===Definitions===
Many widgets can be configured to have to a different appearance, for example in our tree_view example we changed the definition of a toggle_button from the default of a checkbox by setting definition = "tree_view_node". This option was found by looking at the id of a toggle_button_definition in .../data/gui/widget/toggle_button_tree_view_node.cfg:

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib
###
### Definition of a toggle button to be used in a tree view as node fold/unfold indicator
###
[toggle_button_definition]
id = "tree_view_node" # <--- we can use 'definition = "tree_view_node"' in a [toggle_button] to select this definition
description = "Fold/unfold status indicator of a tree view node."
</syntaxhighlight>

{|
|There are many other definitions for buttons and other widget types in that directory. It would be nice to have a list (linked here), but for now you'll just have to look around.

We can even create our own custom definitions using [[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition()]]. In this example, we copy from .../data/gui/widget/toggle_button_tree_view_node.cfg with a slight change so that our button turns red ( '''~BLEND(255,0,0,1)''' ) when focused.

In this example, we will use wesnoth.wml_actions to create the WML tag [add_widget_def_demo].

Note the first line, a common convention for creating an alias for wml.tag.
|-
|[[File:Gui tutorial custom widget.png|center|thumb|Different definition of buttons, including one of our own (right)]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag -- save ourselves some typing
function wesnoth.wml_actions.add_widget_def_demo()
local definition = {
id = "tree_view_node_custom",
description = "Fold/unfold status indicator of a tree view node (MODIFIED).",
T.resolution {
min_width = 25,
min_height = 19,
default_width = 25,
default_height = 19,
max_width = 25,
max_height = 19,
-- Unselected - note there's no tags for unselected/selected, that's simply determined by the order
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/fold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/fold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/fold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
-- Selected
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/unfold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
}
}
gui.add_widget_definition("toggle_button", "tree_view_node_custom", definition)

local dialogDefinition = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid {
T.row {
T.column {
T.toggle_button {
definition = "default"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node_custom"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end

</syntaxhighlight>

See [[GUIWidgetDefinitionWML]] for more details on widget definitions.

You can also give the whole dialog a definition, like definition = "tooltip_large". There is no gui.add_window_definition(), however a window is technically a type of widget so it may be possible to create your own window definitions (please update this if you do).

===Panels===

===Canvases===
Part of panels? Sort of?

A canvas is a surface you can draw on. A dialog has them, as does a panel, and for these canvas 1 refers to the background, while canvas 2 refers to the foreground. Other widgets may have canvases that may have other meanings, or no canvases at all. See more at [[LuaAPI/gui/widget#set_canvas]].

Here's a fun little trick. Set your dialog background to be transparent:
<syntaxhighlight lang=lua>
local function preshow(dialog)
dialog:set_canvas(1, { } )
end
</syntaxhighlight>

Or, if you want an opaque GUI background with the screen behind it blurred like what you see behind the text of a [message], you can set your window definition to "message":
<syntaxhighlight lang=lua>
...
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
definition = "message",
...
</syntaxhighlight>

{|
|Here we take our [[#Progress Bar|progress bar]], and add a text overlay.

Note: either using text on a canvas is rather limited, or I just couldn't figure it out. For example, I could not get the text size any smaller, and any attempts to do so simply resulted in very blocky text. And the spaces were necessary so that the text wasn't stretched out. I also find it surprising that the progress bar does not have this feature inherently. So it's not a great example, but it should be enough to get you started using canvases. Be sure to visit the [[LuaAPI/gui/widget#set_canvas|link]] mentioned above for more options.
|-
|[[File:Gui tutorial canvas text.png|center|thumb|A progress bar in the background, with text in the foreground]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar_with_overlay()
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.grid {
T.row {
T.column {
T.panel { id = "panel",
T.grid {
T.row {
T.column {
T.button { id = "button",
label =_ "Press me"}
},
T.column {
T.progress_bar { id = "progress" }
},
T.column {
T.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
dialog.panel:set_canvas(2, { T.text { text_alignment = "center", font_size = 48,
text_markup = true, text = " " ..
dialog.progress.percentage .. "% " } } )
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

You may notice we added a panel and placed our text on the foreground canvas(2) on it, since the progress_bar itself does not support canvases.

===Placement===

You may have noticed that all of our dialogs are centered on the screen. This is the default. You can override this and place the dialog wherever you like by setting automatic_placement = false, along with x, y, width, and height at the top level of your dialog definition (next to tooltip =, etc).

'''This part about placement needs review'''
If you prefer, you may replace x and/or y with horizontal_placement and vertical_placement, such as horizontal_placement = "left". You can even set the placement values using WFL, for example horizontal_placement = "(gamemap_width / 3)" -- see [[#Using WFL with GUI2|Using WFL with GUI2]].

==Miscellaneous==

TODO: This stuff doesn't belong in a tutorial. It's worth documenting, but not here. Better to save these here for now than keep them on my laptop.

===Progress Bar===
{|
|A progress_bar is a graphical representation of a percent. In this example, we present the user with a puzzle. They must hit the button repeatedly before they can close the GUI. A progress_bar displays their current progress toward completion.
|-
|[[File:Gui tutorial progress bar.png|center|thumb|upright=2]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.button { id = "button",
label =_ "Press me"
}
},
wml.tag.column {
wml.tag.progress_bar { id = "progress" }
},
wml.tag.column {
wml.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end

gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

===Unit Preview Pane===

{|
|A unit_preview_pane takes a unit (or a unit type), and presents a graphical representation of the unit and its more important attributes, along with tooltips for additional details, in the same way that the recall menu does. Here we see an example of a unit which has picked up some items, including a weapon, which are affecting its stats.
|-
|[[File:Gui tutorial unit preview pane.png|center|thumb]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag

function wesnoth.wml_actions.recall_from_variable(cfg)
local from_array = cfg.from or wml.error(
"[recall_from_variable]: missing required from= ")
local to_var = cfg.to or wml.error(
"[recall_from_variable]: missing required to= ")
local unit_list = wml.array_access.get(from_array) or wml.error(
string.format("[recall_from_variable]: failed to fetch wml array %s",from_array))

local listboxItem = T.grid {
T.row {
T.column {
T.label { id = "available_unit",
linked_group = "available_unit"
}
}
}
}

local listbox_id = "available_units"
local listboxDefinition = T.listbox { id = listbox_id,
T.list_definition {
T.row {
T.column {
T.toggle_panel { listboxItem }
}
}
}
}
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.linked_group { id = "available_unit", fixed_width = true },
T.grid {
T.row { -- header
T.column {
T.grid {
T.row {
T.column {
border = "bottom",
border_size = 10,
T.label {
use_markup = true,
label = ""
.. _"Select unit to recall" .. ""
}
}
}
}
}
},
T.row { -- Body
T.column {
T.grid {
T.row {
T.column {
border = "right",
border_size = 40,
listboxDefinition
},
T.column {
T.unit_preview_pane { id = "unit_preview" }
}
}
}
}
},
T.row { -- Footer
T.column {
T.grid {
T.row {
T.column {
T.spacer { width = 400 }
},
T.column {
border = "top,right",
border_size = 10,
T.button { id = "ok",
label = _"OK"
}
}
}
}
}
}
}
}

local picked = 1

local function preshow(dialog)
local listbox = dialog[listbox_id]
for i,unit in ipairs(unit_list) do
listbox[i].available_unit.label = unit.name .. "(" ..
unit.language_name .. ")"
end
local function draw_unit()
wesnoth.units.to_recall(unit_list[listbox.selected_index])
local tmp = wesnoth.units.find_on_recall{ id =
unit_list[listbox.selected_index].id }[1]
dialog.unit_preview.unit = tmp
wesnoth.units.extract(tmp)
picked = listbox.selected_index
end
draw_unit()
listbox.on_modified = draw_unit
end

gui.show_dialog(dialogDefinition,preshow)

wml.variables[to_var] = picked - 1
end

</syntaxhighlight>

This should all be pretty self evident by now. We are provided with an array of stored units (from [store_unit] in WML). We create a listbox populated with units and we use the selected_index to determine which element in the table to send to unit_preview_pane. Since our input is an array of unit data, not actual units, we use [[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] to take the definition of one from our array and place it on the recall list (turning it into an actual unit), [[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] to fetch that unit in a form that the unit_preview_panel understands, and finally [[wesnoth.units.extract|wesnoth.units.extract]] to remove the unit from the recall list when we are done with it.

And of course we subtract one from the selected_index when we return our choice to WML, since lua arrays count from 1 and WML from 0.

The unit_preview_pane will also accept a unit_type instead of a specific unit.

==Appendix==

===Explore Your Options===

We've seen a lot of options that can be set to modify the behaviour of our dialogs, some on columns, some on widgets, etc. These are in the process of being documented [[GUIWidgetInstanceWML|here]], but if you would like to go straight to the source, the data Wesnoth uses to validate your configuration can be found in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui data/schema/gui] under your install directory.

Let's look at a scroll_label, for example. A scroll_label is a widget, so we look in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/widget_instances.cfg widget_instances.cfg] and find the following. Here we can see five parameters we can provide to our scroll_label (in addition to the ones available to all widgets, like id and definition, see the entry super=... which refers you to the widget_instance in the file [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/generic.cfg data/schema/gui/generic.cfg]), along with their types and default values. For example, we could set "link_aware = true", and if we do not we can assume that link_aware will be false. While this does not explain what these parameters do, the information provided in the schema directory is often helpful nonetheless.

<syntaxhighlight lang=wml>
[tag]
name="scroll_label"
min="0"
max="infinite"
super="$generic/widget_instance"
{DEFAULT_KEY "horizontal_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "vertical_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "wrap" bool true}
{DEFAULT_KEY "text_alignment" f_h_align "left"}
{DEFAULT_KEY "link_aware" bool false}
[/tag]
</syntaxhighlight>

We see that our scrollbars are of type scrollbar_mode. It would probably help if we knew what values are available to the scrollbar_mode. In [https://github.com/wesnoth/wesnoth/tree/master/data/schema/types/gui.cfg data/schema/types/gui.cfg] we find this:

<syntaxhighlight lang=wml>
[type]
name=scrollbar_mode
value="always|never|auto|initial_auto"
[/type]
</syntaxhighlight>

The variable types found in the schema files are described at [[GUIVariable]].

Note: The keys in the schema file correspond to the attributes used when configuring your widgets. They will not always align perfectly with keys used by the Lua API. For example, the slider uses maximum_value in its configuration, and max_value when using the Lua API:

<syntaxhighlight lang=wml>
[slider]
id="my_slider"
maximum_value = 100
[/slider]
</syntaxhighlight>

<syntaxhighlight lang=lua>
dialog.my_slider.max_value = 90
</syntaxhighlight>

===Using WFL with GUI2===

If you look at the variable type descriptions at [[GUIVariable]] you may notice that many of them start with "f_" and have "or formula" in the description. This means that you can use [[Wesnoth_Formula_Language|Wesnoth Formula Language (WFL)]] formulas in these fields, with certain variables made available to you (which variables and what they mean can be challenging to ascertain, but you can generally figure it out by example).

Looking at [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/window.cfg data/schema/gui/window.cfg] we see that 'height' has type f_unsigned, which tells us that height is an unsigned integer, and that we can use a WFL formula to define it in a window_definition. In [https://github.com/wesnoth/wesnoth/tree/master/data/gui/themes/default/window/wml_message.cfg data/gui/window/wml_message.cfg] (data/gui/themes/default/window/wml_message.cfg starting around 1.19.2), we find the line '''height = "(screen_height - 30)"'''. This does exactly what it looks like, it sets the height of our window to 30 pixels less than the height of the screen.

===Useful Links===
[[GUIToolkitWML - Documents the keys/values available on various objects ("what attributes can I set on a column?"]]
[[LuaAPI/gui|LuaAPI/gui - Mostly about opening windows]] 
[[LuaAPI/types/widget|LuaAPI/types/widget - Widget attributes and callbacks]] 
[https://wiki.wesnoth.org/Category:GUI_WML_Reference GUI_WML_Reference] 
[https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui .../data/schema/gui/*.cfg] - Lists of valid options for various GUI objects 
[https://devdocs.wesnoth.org/layout_algorithm.html Layout Algorithm] - For windows, at least

===Credits===

The basic framework that composes the initial examples was lifted from LotI. It's a great place to find well written examples, but some of it is complex enough to be a little overwhelming when getting started.

Many examples, particularly tree view and multipage, are heavily derived from the World Conquest multiplayer campaign.

GUIWidgetInstanceWML

2024-09-24T18:47:52Z

White haired uncle: /* Button - add description of valid values for return_value_id */

== Widget instance ==
Inside a grid (which is inside all container widgets) a widget is
instantiated. With this instantiation some more variables of a widget can
be tuned. This page will describe what can be tuned.

== Widget ==
All widgets placed in the cell have some values in common:
{| class="wikitable"
!key
!type
!default
!description
|-
| id
| [[GUIVariable#string|string]]
| ""
| This value is used for the engine to identify 'special' items. This means that for example a text_box can get the proper initial value. This value should be unique or empty. Those special values are documented at the window definition that uses them. NOTE items starting with an underscore are used for composed widgets and these should be unique per composed widget.
|-
| definition
| [[GUIVariable#string|string]]
| "default"
| The id of the widget definition to use. This way it's possible to select a specific version of the widget e.g. a title label when the label is used as title.
|-
| linked_group
| [[GUIVariable#string|string]]
| ""
| The linked group the control belongs to.
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| Most widgets have some text associated with them, this field contain the value of that text. Some widgets use this value for other purposes, this is documented at the widget. E.g. an image uses the filename in this field.
|-
| tooltip
| [[GUIVariable#t_string|t_string]]
| ""
| If you hover over a widget a while (the time it takes can differ per widget) a short help can show up.This defines the text of that message. This field may not be empty when 'help' is set.
|-
| help
| [[GUIVariable#t_string|t_string]]
| ""
| If you hover over a widget and press F10 (or the key the user defined for the help tip) a help message can show up. This help message might be the same as the tooltip but in general (if used) this message should show more help. This defines the text of that message.
|-
| use_tooltip_on_label_overflow
| [[GUIVariable#bool|bool]]
| true
| If the text on the label is truncated and the tooltip is empty the label can be used for the tooltip. If this variable is set to true this will happen.
|-
| debug_border_mode
| [[GUIVariable#unsigned|unsigned]]
| 0
| The mode for showing the debug border. This border shows the area reserved for a widget. This function is only meant for debugging and might not be available in all Wesnoth binaries. Available modes:
* 0 no border.
* 1 1 pixel border.
* 2 floodfill the widget area.
|-
| debug_border_color
| [[GUIVariable#color|color]]
| ""
| The color of the debug border.
|-
| size_text
| [[GUIVariable#t_string|t_string]]
| ""
| Sets the minimum width of the widget depending on the text in it. (Note not implemented yet.)
|}

== Button ==
A button is a control that can be pushed to start an action or close a dialog.

Instance of a button. When a button has a return value it sets the
return value for the window. Normally this closes the window and returns
this value to the caller. The return value can either be defined by the
user or determined from the id of the button. The return value has a
higher precedence as the one defined by the id. (Of course it's weird to
give a button an id and then override its return value.)

When the button doesn't have a standard id, but you still want to use the
return value of that id, use return_value_id instead. This has a higher
precedence as return_value.

List with the button specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

Supported values for return_value_id:
{| class="wikitable"
!string
!value
!description
|-
|"ok"||-1||Equivalent to closing the dialog by pressing the Enter key
|-
|"cancel"||-2||Equivalent to closing the dialog by pressing the Esc key
|-
|"quit"||-2||An alias for cancel
|-
|""||N/A||Clears any previously set return_value_id
|}

== Combobox ==
[[File:Combobox.png|frame|right|A Combobox with its list open]]
A widget with a text box and a dropdown list. Selecting an element from the list sets the value of the text box to that item of the list. The user can also manually enter a value in the text box.

{| class="wikitable"
|-
! key !! type !! default !! description
|-
| label || [[GUIVariable#string|string]] || "" || The text of the combobox
|-
| max_input_length || [[GUIVariable#int|int]] || 0 || Maximum length of text in characters that can be entered into the combobox
|-
| hint_text || [[GUIVariable#string|string]] || "" || Text that is shown in the background when there is no input
|-
| hint_image || [[GUIVariable#string|string]] || "" || Image that is shown in the background when there is no input

|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>combobox</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| icon || [[GUIVariable#string|string]] || "" || WML path to the icon to be shown alongside the text in this option, if any.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Drawing ==
A drawing is widget with a fixed size and gives access to the canvas of the widget in the window instance. This allows special display only widgets.

If either the width or the height is not zero the drawing functions as a
fixed size drawing.

{| class="wikitable"
!key
!type
!default
!description
|-
| width
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the drawing.
|-
| height
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the drawing.
|-
| draw
| [[GUIVariable#config|config]]
| mandatory
| The config containing the drawing.
|}

The variable available are the same as for the window resolution see
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
items.

== Grid Listbox ==
List with the listbox specific variables:
{| class="wikitable"
!ID (return value)
!Type
!Mandatory
!Description
|-
| vertical_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIToolkitWML#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIToolkitWML#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, more than one row can be selected.
|}

== Horizontal listbox ==
A horizontal listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version orders them in columns instead.

List with the horizontal listbox specific variables:
{| class="wikitable"
!ID (return value)
!Type
!Mandatory
!Description
|-
| vertical_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIToolkitWML#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIToolkitWML#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, more than one row can be selected.
|}

In order to force widgets to be the same size inside a horizontal listbox,
the widgets need to be inside a linked_group.

Inside the list section there are only the following widgets allowed
* grid (to nest)
* selectable widgets which are
** toggle_button
** toggle_panel

== Image ==
An image shows a static image.

An image has no extra fields.

== Label ==
A label displays text that can be wrapped but no scrollbars are provided.

[[File:Title Label.png|frame|right|A Label with definition "title"]]

List with the label specific variables:
{| class="wikitable"
!key !!type !!default !!description
|-
| wrap || [[GUIVariable#bool|bool]] || false || Is wrapping enabled for the label.
|-
| characters_per_line || [[GUIVariable#unsigned|unsigned]] || 0 || Sets the maximum number of characters per line. The amount is an approximate since the width of a character differs. E.g. iii is smaller than MMM. When the value is non-zero it also implies can_wrap is true. When having long strings wrapping them can increase readability, often 66 characters per line is considered the optimum for a one column text. text_alignment & h_align & "left" & How is the text aligned in the label.
|-
| text_alignment || [[GUIVariable#h_align|h_align]] || left || The way the text is aligned inside the canvas.
|-
| can_shrink || [[GUIVariable#bool|bool]] || false || Whether the label can shrink past its optimal size.
|-
| link_aware || [[GUIVariable#bool|bool]] || false || Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
|}

== Listbox ==
A listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version might allow more options for ordering the items in the future.

List with the listbox specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIVariable#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIVariable#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIVariable#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIVariable#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIVariable#bool|bool]]
| true
| If false, more than one row can be selected.
|}

In order to force widgets to be the same size inside a listbox, the widgets
need to be inside a linked_group.

Inside the list section there are only the following widgets allowed
* grid (to nest)
* selectable widgets which are
** toggle_button
** toggle_panel

== Matrix ==
List with the matrix specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|}

== Menu Button ==
[[File:Menu Button.png|thumb|left|A Menu Button with it's list open.]]
A button that shows a dropdown list when clicked. The user can select any one of the predefined options.
{| class="wikitable"
!key
!type
!default
!description
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>menu_button</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| icon || [[GUIVariable#string|string]] || "" || WML path to the icon to be shown alongside the text in this option, if any.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Minimap ==
A minimap to show the gamemap, this only shows the map and has no interaction options. This version is used for map previews, there will be a another version which allows interaction.

A minimap has no extra fields.

== Multiline Text ==
Base class for a multiline text area.

The following variables exist:
{| class="wikitable"
!key
!type
!default
!description
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| The initial text of the text box.
|-
| history
| [[GUIVariable#string|string]]
| ""
| The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
|-
| editable
| [[GUIVariable#bool|bool]]
| "true"
| If the contents of the text box can be edited.
|}

== Multimenu Button ==
[[File:Multimenu Button.png|thumb|right|A Multimenu Button with its list open]]
A widget clicking on which shows a list from which one or more options can be selected.

List with the multimenu_button specific variables:
{| class="wikitable"
!key !!type !!default !!description
|-
| return_value_id || [[GUIVariable#string|string]] || "" || The return value id.
|-
| return_value || [[GUIVariable#int|int]] || 0 || The return value.
|-
| maximum_shown || [[GUIVariable#int|int]] || -1 || The maximum number of currently selected values to list on the button.
|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>multimenu_button</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| checkbox || [[GUIVariable#bool|bool]] || "" || Whether the checkbox alongside this option is selected or not.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Multi page ==
A multi page is a control that contains several 'pages' of which only one is visible. The pages can contain the same widgets containing the same 'kind' of data or look completely different.

List with the multi page specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| page_definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a multi page item looks. It must contain the grid definition for at least one page.
|-
| page_data
| [[GUIVariable#section|section]]
| []
| A grid alike section which stores the initial data for the multi page. Every row must have the same number of columns as the 'page_definition'.
|}

== Panel ==
A panel is an item which can hold other items. The difference between a grid and a panel is that it's possible to define how a panel looks. A grid in an invisible container to just hold the items.

{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|}

== Password box ==
{| class="wikitable"
!key
!type
!default
!description
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| The initial text of the password box.
|}

== Progress bar ==
A progress bar shows the progress of a certain object.

A progress bar has no extra fields.

== Repeating button ==
A repeating_button is a control that can be pushed down and repeat a certain action. Once the button is down every x milliseconds it is down a new down event is triggered.

== Rich Label ==
A label that shows formatted text marked up with [[Help markup]]. It can show embedded images, links and tables inside text.

{| class="wikitable"
!key !!type !!default !!description
|-
| text_alignment || [[GUIVariable#h_align|h_align]] || left || The way the text is aligned inside the canvas.
|-
| width || [[GUIVariable#int|int]] || 500 || Width of its internal formatted content. Text will wrap beyond this width.
|-
| link_aware || [[GUIVariable#bool|bool]] || false || Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
|}

== Scroll label ==
A scroll label is a label that wraps its text and also has a vertical scrollbar. This way a text can't be too long to be shown for this widget.

List with the scroll label specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|}

== Scrollbar panel ==
Instance of a scrollbar_panel.

List with the scrollbar_panel specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a scrollbar_panel item looks. It must contain the grid definition for 1 row of the list.
|}

== Spacer ==
A spacer is a dummy item to either fill in a widget since no empty items are allowed or to reserve a fixed space.

If either the width or the height is non-zero the spacer functions as a
fixed size spacer.

{| class="wikitable"
!key !!type !!default !!description
|-
| width || [[GUIVariable#f_unsigned|f_unsigned]] || 0 || The width of the spacer.
|-
| height || [[GUIVariable#f_unsigned|f_unsigned]] || 0 || The height of the spacer.
|}

The variable available are the same as for the window resolution see
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
items.

== Tab Container ==

A container widget that can show its contents separated into various pages, each of which are accessible.

It can contain one or more <code>[tab]</code> tags inside it, each defining a tab's name, image (if any) and the contents of the tag, specified by the <code>[data]</code> tag inside the <code>[tab]</code> tag.

=== Subtag [tab] ===

{| class = "wikitable"
!key !!type !!default !!description
|-
| name || [[GUIVariable#t_string|t_string]] || "" || Name of the tab
|-
| image || [[GUIVariable#string|string]] || "" || Image for the tab to be shown alongside the name, if any
|-
| [data] || [[GUIVariable#grid|grid]] || empty grid || This subtag contains a grid that defines the contents for this tab.
|}

== Text box ==
A single line text entry widget.

[[File:Text Box.png|frame|right|A Text Box]]

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || The initial text of the text box.
|-
| history || [[GUIVariable#string|string]] || "" || The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
|-
| max_input_length || [[GUIVariable#int|int]] || 0 || Maximum length of text in characters that can be entered into the combobox
|-
| hint_text || [[GUIVariable#string|string]] || "" || Text that is shown in the background when there is no input
|-
| hint_image || [[GUIVariable#string|string]] || "" || Image that is shown in the background when there is no input
|-
| editable || [[GUIVariable#bool|bool]] || "true" || If the contents of the text box can be edited.
|}

== Toggle panel ==
A toggle panel is an item which can hold other items. The difference between
a grid and a panel is that it's possible to define how a panel looks. A grid
in an invisible container to just hold the items. The toggle panel is a
combination of the panel and a toggle button, it allows a toggle button with
its own grid.

Variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id, see [[GUIToolkitWML#Button]] for more information.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value, see [[GUIToolkitWML#Button]] for more information.
|}

== Tree view ==
A tree view is a control that holds several items of the same or different types. The items shown are called tree view nodes and when a node has children, these can be shown or hidden. Nodes that contain children need to provide a clickable button in order to fold or unfold the children.

List with the tree view specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| indention_step_size
| [[GUIVariable#unsigned|unsigned]]
| 0
| The number of pixels every level of nodes is indented from the previous level.
|-
| node
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The tree view can contain multiple node sections. This part needs more documentation.
|-
| id
| [[GUIVariable#unsigned|unsigned]]
| ""
| .
|-
| return_value_id
| [[GUIVariable#unsigned|unsigned]]
| ""
| .
|}

NOTE more documentation and examples are needed.

== Vertical scrollbar ==

== Viewport ==
A viewport is an special widget used to view only a part of the widget it `holds'.

List with the viewport specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grow_direction
| [[GUIVariable#grow_direction|grow_direction]]
| mandatory
| The direction in which new items grow.
|-
| parallel_items
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The number of items that are growing in parallel.
|-
| item_definition
| [[GUIVariable#section|section]]
| mandatory
| The definition of a new item.
|}

== Scroll Text ==
A multiline text area that shows a scrollbar if the text gets too long.

List with the scrollbar container specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| editable
| [[GUIVariable#bool|bool]]
| "true"
| If the contents of this scroll_text can be edited.
|}

== Slider ==

A slider is a control that can select a value by moving a grip on a groove.

{| class="wikitable"
!key
!type
!default
!description
|-
| best_slider_length
| [[GUIVariable#unsigned|unsigned]]
| 0
| The best length for the sliding part.
|-
| minimum_value
| [[GUIVariable#int|int]]
| 0
| The minimum value the slider can have.
|-
| maximum_value
| [[GUIVariable#int|int]]
| 0
| The maximum value the slider can have.
|-
| step_size
| [[GUIVariable#unsigned|unsigned]]
| 0
| The number of items the slider's value increases with one step.
|-
| value
| [[GUIVariable#int|int]]
| 0
| The value of the slider.
|-
| minimum_value_label
| [[GUIVariable#t_string|t_string]]
| ""
| If the minimum value is chosen there might be the need for a special value (eg off). When this key has a value that value will be shown if the minimum is selected.
|-
| maximum_value_label
| [[GUIVariable#t_string|t_string]]
| ""
| If the maximum value is chosen there might be the need for a special value (eg unlimited)). When this key has a value that value will be shown if the maximum is selected.
|}

== Toggle button ==
Variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

GUIWidgetInstanceWML

2024-09-24T18:45:24Z

White haired uncle: /* Button */ add description of valid values for return_value_id

== Widget instance ==
Inside a grid (which is inside all container widgets) a widget is
instantiated. With this instantiation some more variables of a widget can
be tuned. This page will describe what can be tuned.

== Widget ==
All widgets placed in the cell have some values in common:
{| class="wikitable"
!key
!type
!default
!description
|-
| id
| [[GUIVariable#string|string]]
| ""
| This value is used for the engine to identify 'special' items. This means that for example a text_box can get the proper initial value. This value should be unique or empty. Those special values are documented at the window definition that uses them. NOTE items starting with an underscore are used for composed widgets and these should be unique per composed widget.
|-
| definition
| [[GUIVariable#string|string]]
| "default"
| The id of the widget definition to use. This way it's possible to select a specific version of the widget e.g. a title label when the label is used as title.
|-
| linked_group
| [[GUIVariable#string|string]]
| ""
| The linked group the control belongs to.
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| Most widgets have some text associated with them, this field contain the value of that text. Some widgets use this value for other purposes, this is documented at the widget. E.g. an image uses the filename in this field.
|-
| tooltip
| [[GUIVariable#t_string|t_string]]
| ""
| If you hover over a widget a while (the time it takes can differ per widget) a short help can show up.This defines the text of that message. This field may not be empty when 'help' is set.
|-
| help
| [[GUIVariable#t_string|t_string]]
| ""
| If you hover over a widget and press F10 (or the key the user defined for the help tip) a help message can show up. This help message might be the same as the tooltip but in general (if used) this message should show more help. This defines the text of that message.
|-
| use_tooltip_on_label_overflow
| [[GUIVariable#bool|bool]]
| true
| If the text on the label is truncated and the tooltip is empty the label can be used for the tooltip. If this variable is set to true this will happen.
|-
| debug_border_mode
| [[GUIVariable#unsigned|unsigned]]
| 0
| The mode for showing the debug border. This border shows the area reserved for a widget. This function is only meant for debugging and might not be available in all Wesnoth binaries. Available modes:
* 0 no border.
* 1 1 pixel border.
* 2 floodfill the widget area.
|-
| debug_border_color
| [[GUIVariable#color|color]]
| ""
| The color of the debug border.
|-
| size_text
| [[GUIVariable#t_string|t_string]]
| ""
| Sets the minimum width of the widget depending on the text in it. (Note not implemented yet.)
|}

== Button ==
A button is a control that can be pushed to start an action or close a dialog.

Instance of a button. When a button has a return value it sets the
return value for the window. Normally this closes the window and returns
this value to the caller. The return value can either be defined by the
user or determined from the id of the button. The return value has a
higher precedence as the one defined by the id. (Of course it's weird to
give a button an id and then override its return value.)

When the button doesn't have a standard id, but you still want to use the
return value of that id, use return_value_id instead. This has a higher
precedence as return_value.

List with the button specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

Supported values for return_value_id:
{| class="wikitable"
!string
!value
!description
|-
|"ok"|-1|Equivalent to closing the dialog by pressing the Enter key
|"cancel"|-2|Equivalent to closing the dialog by pressing the Esc key
|"quit"|-2|Alias for cancel
|""|N/A|Clears any previously set return_value_id
|}

== Combobox ==
[[File:Combobox.png|frame|right|A Combobox with its list open]]
A widget with a text box and a dropdown list. Selecting an element from the list sets the value of the text box to that item of the list. The user can also manually enter a value in the text box.

{| class="wikitable"
|-
! key !! type !! default !! description
|-
| label || [[GUIVariable#string|string]] || "" || The text of the combobox
|-
| max_input_length || [[GUIVariable#int|int]] || 0 || Maximum length of text in characters that can be entered into the combobox
|-
| hint_text || [[GUIVariable#string|string]] || "" || Text that is shown in the background when there is no input
|-
| hint_image || [[GUIVariable#string|string]] || "" || Image that is shown in the background when there is no input

|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>combobox</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| icon || [[GUIVariable#string|string]] || "" || WML path to the icon to be shown alongside the text in this option, if any.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Drawing ==
A drawing is widget with a fixed size and gives access to the canvas of the widget in the window instance. This allows special display only widgets.

If either the width or the height is not zero the drawing functions as a
fixed size drawing.

{| class="wikitable"
!key
!type
!default
!description
|-
| width
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the drawing.
|-
| height
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the drawing.
|-
| draw
| [[GUIVariable#config|config]]
| mandatory
| The config containing the drawing.
|}

The variable available are the same as for the window resolution see
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
items.

== Grid Listbox ==
List with the listbox specific variables:
{| class="wikitable"
!ID (return value)
!Type
!Mandatory
!Description
|-
| vertical_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIToolkitWML#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIToolkitWML#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, more than one row can be selected.
|}

== Horizontal listbox ==
A horizontal listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version orders them in columns instead.

List with the horizontal listbox specific variables:
{| class="wikitable"
!ID (return value)
!Type
!Mandatory
!Description
|-
| vertical_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIToolkitWML#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIToolkitWML#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, more than one row can be selected.
|}

In order to force widgets to be the same size inside a horizontal listbox,
the widgets need to be inside a linked_group.

Inside the list section there are only the following widgets allowed
* grid (to nest)
* selectable widgets which are
** toggle_button
** toggle_panel

== Image ==
An image shows a static image.

An image has no extra fields.

== Label ==
A label displays text that can be wrapped but no scrollbars are provided.

[[File:Title Label.png|frame|right|A Label with definition "title"]]

List with the label specific variables:
{| class="wikitable"
!key !!type !!default !!description
|-
| wrap || [[GUIVariable#bool|bool]] || false || Is wrapping enabled for the label.
|-
| characters_per_line || [[GUIVariable#unsigned|unsigned]] || 0 || Sets the maximum number of characters per line. The amount is an approximate since the width of a character differs. E.g. iii is smaller than MMM. When the value is non-zero it also implies can_wrap is true. When having long strings wrapping them can increase readability, often 66 characters per line is considered the optimum for a one column text. text_alignment & h_align & "left" & How is the text aligned in the label.
|-
| text_alignment || [[GUIVariable#h_align|h_align]] || left || The way the text is aligned inside the canvas.
|-
| can_shrink || [[GUIVariable#bool|bool]] || false || Whether the label can shrink past its optimal size.
|-
| link_aware || [[GUIVariable#bool|bool]] || false || Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
|}

== Listbox ==
A listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version might allow more options for ordering the items in the future.

List with the listbox specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIVariable#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIVariable#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIVariable#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIVariable#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIVariable#bool|bool]]
| true
| If false, more than one row can be selected.
|}

In order to force widgets to be the same size inside a listbox, the widgets
need to be inside a linked_group.

Inside the list section there are only the following widgets allowed
* grid (to nest)
* selectable widgets which are
** toggle_button
** toggle_panel

== Matrix ==
List with the matrix specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|}

== Menu Button ==
[[File:Menu Button.png|thumb|left|A Menu Button with it's list open.]]
A button that shows a dropdown list when clicked. The user can select any one of the predefined options.
{| class="wikitable"
!key
!type
!default
!description
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>menu_button</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| icon || [[GUIVariable#string|string]] || "" || WML path to the icon to be shown alongside the text in this option, if any.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Minimap ==
A minimap to show the gamemap, this only shows the map and has no interaction options. This version is used for map previews, there will be a another version which allows interaction.

A minimap has no extra fields.

== Multiline Text ==
Base class for a multiline text area.

The following variables exist:
{| class="wikitable"
!key
!type
!default
!description
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| The initial text of the text box.
|-
| history
| [[GUIVariable#string|string]]
| ""
| The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
|-
| editable
| [[GUIVariable#bool|bool]]
| "true"
| If the contents of the text box can be edited.
|}

== Multimenu Button ==
[[File:Multimenu Button.png|thumb|right|A Multimenu Button with its list open]]
A widget clicking on which shows a list from which one or more options can be selected.

List with the multimenu_button specific variables:
{| class="wikitable"
!key !!type !!default !!description
|-
| return_value_id || [[GUIVariable#string|string]] || "" || The return value id.
|-
| return_value || [[GUIVariable#int|int]] || 0 || The return value.
|-
| maximum_shown || [[GUIVariable#int|int]] || -1 || The maximum number of currently selected values to list on the button.
|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>multimenu_button</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| checkbox || [[GUIVariable#bool|bool]] || "" || Whether the checkbox alongside this option is selected or not.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Multi page ==
A multi page is a control that contains several 'pages' of which only one is visible. The pages can contain the same widgets containing the same 'kind' of data or look completely different.

List with the multi page specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| page_definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a multi page item looks. It must contain the grid definition for at least one page.
|-
| page_data
| [[GUIVariable#section|section]]
| []
| A grid alike section which stores the initial data for the multi page. Every row must have the same number of columns as the 'page_definition'.
|}

== Panel ==
A panel is an item which can hold other items. The difference between a grid and a panel is that it's possible to define how a panel looks. A grid in an invisible container to just hold the items.

{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|}

== Password box ==
{| class="wikitable"
!key
!type
!default
!description
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| The initial text of the password box.
|}

== Progress bar ==
A progress bar shows the progress of a certain object.

A progress bar has no extra fields.

== Repeating button ==
A repeating_button is a control that can be pushed down and repeat a certain action. Once the button is down every x milliseconds it is down a new down event is triggered.

== Rich Label ==
A label that shows formatted text marked up with [[Help markup]]. It can show embedded images, links and tables inside text.

{| class="wikitable"
!key !!type !!default !!description
|-
| text_alignment || [[GUIVariable#h_align|h_align]] || left || The way the text is aligned inside the canvas.
|-
| width || [[GUIVariable#int|int]] || 500 || Width of its internal formatted content. Text will wrap beyond this width.
|-
| link_aware || [[GUIVariable#bool|bool]] || false || Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
|}

== Scroll label ==
A scroll label is a label that wraps its text and also has a vertical scrollbar. This way a text can't be too long to be shown for this widget.

List with the scroll label specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|}

== Scrollbar panel ==
Instance of a scrollbar_panel.

List with the scrollbar_panel specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a scrollbar_panel item looks. It must contain the grid definition for 1 row of the list.
|}

== Spacer ==
A spacer is a dummy item to either fill in a widget since no empty items are allowed or to reserve a fixed space.

If either the width or the height is non-zero the spacer functions as a
fixed size spacer.

{| class="wikitable"
!key !!type !!default !!description
|-
| width || [[GUIVariable#f_unsigned|f_unsigned]] || 0 || The width of the spacer.
|-
| height || [[GUIVariable#f_unsigned|f_unsigned]] || 0 || The height of the spacer.
|}

The variable available are the same as for the window resolution see
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
items.

== Tab Container ==

A container widget that can show its contents separated into various pages, each of which are accessible.

It can contain one or more <code>[tab]</code> tags inside it, each defining a tab's name, image (if any) and the contents of the tag, specified by the <code>[data]</code> tag inside the <code>[tab]</code> tag.

=== Subtag [tab] ===

{| class = "wikitable"
!key !!type !!default !!description
|-
| name || [[GUIVariable#t_string|t_string]] || "" || Name of the tab
|-
| image || [[GUIVariable#string|string]] || "" || Image for the tab to be shown alongside the name, if any
|-
| [data] || [[GUIVariable#grid|grid]] || empty grid || This subtag contains a grid that defines the contents for this tab.
|}

== Text box ==
A single line text entry widget.

[[File:Text Box.png|frame|right|A Text Box]]

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || The initial text of the text box.
|-
| history || [[GUIVariable#string|string]] || "" || The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
|-
| max_input_length || [[GUIVariable#int|int]] || 0 || Maximum length of text in characters that can be entered into the combobox
|-
| hint_text || [[GUIVariable#string|string]] || "" || Text that is shown in the background when there is no input
|-
| hint_image || [[GUIVariable#string|string]] || "" || Image that is shown in the background when there is no input
|-
| editable || [[GUIVariable#bool|bool]] || "true" || If the contents of the text box can be edited.
|}

== Toggle panel ==
A toggle panel is an item which can hold other items. The difference between
a grid and a panel is that it's possible to define how a panel looks. A grid
in an invisible container to just hold the items. The toggle panel is a
combination of the panel and a toggle button, it allows a toggle button with
its own grid.

Variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id, see [[GUIToolkitWML#Button]] for more information.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value, see [[GUIToolkitWML#Button]] for more information.
|}

== Tree view ==
A tree view is a control that holds several items of the same or different types. The items shown are called tree view nodes and when a node has children, these can be shown or hidden. Nodes that contain children need to provide a clickable button in order to fold or unfold the children.

List with the tree view specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| indention_step_size
| [[GUIVariable#unsigned|unsigned]]
| 0
| The number of pixels every level of nodes is indented from the previous level.
|-
| node
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The tree view can contain multiple node sections. This part needs more documentation.
|-
| id
| [[GUIVariable#unsigned|unsigned]]
| ""
| .
|-
| return_value_id
| [[GUIVariable#unsigned|unsigned]]
| ""
| .
|}

NOTE more documentation and examples are needed.

== Vertical scrollbar ==

== Viewport ==
A viewport is an special widget used to view only a part of the widget it `holds'.

List with the viewport specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grow_direction
| [[GUIVariable#grow_direction|grow_direction]]
| mandatory
| The direction in which new items grow.
|-
| parallel_items
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The number of items that are growing in parallel.
|-
| item_definition
| [[GUIVariable#section|section]]
| mandatory
| The definition of a new item.
|}

== Scroll Text ==
A multiline text area that shows a scrollbar if the text gets too long.

List with the scrollbar container specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| editable
| [[GUIVariable#bool|bool]]
| "true"
| If the contents of this scroll_text can be edited.
|}

== Slider ==

A slider is a control that can select a value by moving a grip on a groove.

{| class="wikitable"
!key
!type
!default
!description
|-
| best_slider_length
| [[GUIVariable#unsigned|unsigned]]
| 0
| The best length for the sliding part.
|-
| minimum_value
| [[GUIVariable#int|int]]
| 0
| The minimum value the slider can have.
|-
| maximum_value
| [[GUIVariable#int|int]]
| 0
| The maximum value the slider can have.
|-
| step_size
| [[GUIVariable#unsigned|unsigned]]
| 0
| The number of items the slider's value increases with one step.
|-
| value
| [[GUIVariable#int|int]]
| 0
| The value of the slider.
|-
| minimum_value_label
| [[GUIVariable#t_string|t_string]]
| ""
| If the minimum value is chosen there might be the need for a special value (eg off). When this key has a value that value will be shown if the minimum is selected.
|-
| maximum_value_label
| [[GUIVariable#t_string|t_string]]
| ""
| If the maximum value is chosen there might be the need for a special value (eg unlimited)). When this key has a value that value will be shown if the maximum is selected.
|}

== Toggle button ==
Variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

GUIWidgetInstanceWML

2024-09-23T12:42:43Z

White haired uncle: /* MMB Subtag [option] checkbox*/

== Widget instance ==
Inside a grid (which is inside all container widgets) a widget is
instantiated. With this instantiation some more variables of a widget can
be tuned. This page will describe what can be tuned.

== Widget ==
All widgets placed in the cell have some values in common:
{| class="wikitable"
!key
!type
!default
!description
|-
| id
| [[GUIVariable#string|string]]
| ""
| This value is used for the engine to identify 'special' items. This means that for example a text_box can get the proper initial value. This value should be unique or empty. Those special values are documented at the window definition that uses them. NOTE items starting with an underscore are used for composed widgets and these should be unique per composed widget.
|-
| definition
| [[GUIVariable#string|string]]
| "default"
| The id of the widget definition to use. This way it's possible to select a specific version of the widget e.g. a title label when the label is used as title.
|-
| linked_group
| [[GUIVariable#string|string]]
| ""
| The linked group the control belongs to.
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| Most widgets have some text associated with them, this field contain the value of that text. Some widgets use this value for other purposes, this is documented at the widget. E.g. an image uses the filename in this field.
|-
| tooltip
| [[GUIVariable#t_string|t_string]]
| ""
| If you hover over a widget a while (the time it takes can differ per widget) a short help can show up.This defines the text of that message. This field may not be empty when 'help' is set.
|-
| help
| [[GUIVariable#t_string|t_string]]
| ""
| If you hover over a widget and press F10 (or the key the user defined for the help tip) a help message can show up. This help message might be the same as the tooltip but in general (if used) this message should show more help. This defines the text of that message.
|-
| use_tooltip_on_label_overflow
| [[GUIVariable#bool|bool]]
| true
| If the text on the label is truncated and the tooltip is empty the label can be used for the tooltip. If this variable is set to true this will happen.
|-
| debug_border_mode
| [[GUIVariable#unsigned|unsigned]]
| 0
| The mode for showing the debug border. This border shows the area reserved for a widget. This function is only meant for debugging and might not be available in all Wesnoth binaries. Available modes:
* 0 no border.
* 1 1 pixel border.
* 2 floodfill the widget area.
|-
| debug_border_color
| [[GUIVariable#color|color]]
| ""
| The color of the debug border.
|-
| size_text
| [[GUIVariable#t_string|t_string]]
| ""
| Sets the minimum width of the widget depending on the text in it. (Note not implemented yet.)
|}

== Button ==
A button is a control that can be pushed to start an action or close a dialog.

Instance of a button. When a button has a return value it sets the
return value for the window. Normally this closes the window and returns
this value to the caller. The return value can either be defined by the
user or determined from the id of the button. The return value has a
higher precedence as the one defined by the id. (Of course it's weird to
give a button an id and then override its return value.)

When the button doesn't have a standard id, but you still want to use the
return value of that id, use return_value_id instead. This has a higher
precedence as return_value.

List with the button specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

== Combobox ==
[[File:Combobox.png|frame|right|A Combobox with its list open]]
A widget with a text box and a dropdown list. Selecting an element from the list sets the value of the text box to that item of the list. The user can also manually enter a value in the text box.

{| class="wikitable"
|-
! key !! type !! default !! description
|-
| label || [[GUIVariable#string|string]] || "" || The text of the combobox
|-
| max_input_length || [[GUIVariable#int|int]] || 0 || Maximum length of text in characters that can be entered into the combobox
|-
| hint_text || [[GUIVariable#string|string]] || "" || Text that is shown in the background when there is no input
|-
| hint_image || [[GUIVariable#string|string]] || "" || Image that is shown in the background when there is no input

|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>combobox</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| icon || [[GUIVariable#string|string]] || "" || WML path to the icon to be shown alongside the text in this option, if any.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Drawing ==
A drawing is widget with a fixed size and gives access to the canvas of the widget in the window instance. This allows special display only widgets.

If either the width or the height is not zero the drawing functions as a
fixed size drawing.

{| class="wikitable"
!key
!type
!default
!description
|-
| width
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The width of the drawing.
|-
| height
| [[GUIVariable#f_unsigned|f_unsigned]]
| 0
| The height of the drawing.
|-
| draw
| [[GUIVariable#config|config]]
| mandatory
| The config containing the drawing.
|}

The variable available are the same as for the window resolution see
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
items.

== Grid Listbox ==
List with the listbox specific variables:
{| class="wikitable"
!ID (return value)
!Type
!Mandatory
!Description
|-
| vertical_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIToolkitWML#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIToolkitWML#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, more than one row can be selected.
|}

== Horizontal listbox ==
A horizontal listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version orders them in columns instead.

List with the horizontal listbox specific variables:
{| class="wikitable"
!ID (return value)
!Type
!Mandatory
!Description
|-
| vertical_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIToolkitWML#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIToolkitWML#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIToolkitWML#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIToolkitWML#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIToolkitWML#bool|bool]]
| true
| If false, more than one row can be selected.
|}

In order to force widgets to be the same size inside a horizontal listbox,
the widgets need to be inside a linked_group.

Inside the list section there are only the following widgets allowed
* grid (to nest)
* selectable widgets which are
** toggle_button
** toggle_panel

== Image ==
An image shows a static image.

An image has no extra fields.

== Label ==
A label displays text that can be wrapped but no scrollbars are provided.

[[File:Title Label.png|frame|right|A Label with definition "title"]]

List with the label specific variables:
{| class="wikitable"
!key !!type !!default !!description
|-
| wrap || [[GUIVariable#bool|bool]] || false || Is wrapping enabled for the label.
|-
| characters_per_line || [[GUIVariable#unsigned|unsigned]] || 0 || Sets the maximum number of characters per line. The amount is an approximate since the width of a character differs. E.g. iii is smaller than MMM. When the value is non-zero it also implies can_wrap is true. When having long strings wrapping them can increase readability, often 66 characters per line is considered the optimum for a one column text. text_alignment & h_align & "left" & How is the text aligned in the label.
|-
| text_alignment || [[GUIVariable#h_align|h_align]] || left || The way the text is aligned inside the canvas.
|-
| can_shrink || [[GUIVariable#bool|bool]] || false || Whether the label can shrink past its optimal size.
|-
| link_aware || [[GUIVariable#bool|bool]] || false || Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
|}

== Listbox ==
A listbox is a control that holds several items of the same type. Normally the items in a listbox are ordered in rows, this version might allow more options for ordering the items in the future.

List with the listbox specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| header
| [[GUIVariable#grid|grid]]
| []
| Defines the grid for the optional header. (This grid will automatically get the id _header_grid.)
|-
| footer
| [[GUIVariable#grid|grid]]
| []
| Defines the grid for the optional footer. (This grid will automatically get the id _footer_grid.)
|-
| list_definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a listbox item looks. It must contain the grid definition for 1 row of the list.
|-
| list_data
| [[GUIVariable#section|section]]
| []
| A grid alike section which stores the initial data for the listbox. Every row must have the same number of columns as the 'list_definition'.
|-
| has_minimum
| [[GUIVariable#bool|bool]]
| true
| If false, less than one row can be selected.
|-
| has_maximum
| [[GUIVariable#bool|bool]]
| true
| If false, more than one row can be selected.
|}

In order to force widgets to be the same size inside a listbox, the widgets
need to be inside a linked_group.

Inside the list section there are only the following widgets allowed
* grid (to nest)
* selectable widgets which are
** toggle_button
** toggle_panel

== Matrix ==
List with the matrix specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|}

== Menu Button ==
[[File:Menu Button.png|thumb|left|A Menu Button with it's list open.]]
A button that shows a dropdown list when clicked. The user can select any one of the predefined options.
{| class="wikitable"
!key
!type
!default
!description
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>menu_button</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| icon || [[GUIVariable#string|string]] || "" || WML path to the icon to be shown alongside the text in this option, if any.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Minimap ==
A minimap to show the gamemap, this only shows the map and has no interaction options. This version is used for map previews, there will be a another version which allows interaction.

A minimap has no extra fields.

== Multiline Text ==
Base class for a multiline text area.

The following variables exist:
{| class="wikitable"
!key
!type
!default
!description
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| The initial text of the text box.
|-
| history
| [[GUIVariable#string|string]]
| ""
| The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
|-
| editable
| [[GUIVariable#bool|bool]]
| "true"
| If the contents of the text box can be edited.
|}

== Multimenu Button ==
[[File:Multimenu Button.png|thumb|right|A Multimenu Button with its list open]]
A widget clicking on which shows a list from which one or more options can be selected.

List with the multimenu_button specific variables:
{| class="wikitable"
!key !!type !!default !!description
|-
| return_value_id || [[GUIVariable#string|string]] || "" || The return value id.
|-
| return_value || [[GUIVariable#int|int]] || 0 || The return value.
|-
| maximum_shown || [[GUIVariable#int|int]] || -1 || The maximum number of currently selected values to list on the button.
|}

=== Subtag [option] ===
Specifies the initial list of options to be shown in the <code>multimenu_button</code>.

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || Name of the option.
|-
| tooltip || [[GUIVariable#t_string|t_string]] || "" || Tooltip that is shown when the mouse hovers above this option.
|-
| checkbox || [[GUIVariable#bool|bool]] || "" || Whether the checkbox alongside this option is selected or not.
|-
| details || [[GUIVariable#t_string|t_string]] || "" || Short description about this option.
|}

== Multi page ==
A multi page is a control that contains several 'pages' of which only one is visible. The pages can contain the same widgets containing the same 'kind' of data or look completely different.

List with the multi page specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| page_definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a multi page item looks. It must contain the grid definition for at least one page.
|-
| page_data
| [[GUIVariable#section|section]]
| []
| A grid alike section which stores the initial data for the multi page. Every row must have the same number of columns as the 'page_definition'.
|}

== Panel ==
A panel is an item which can hold other items. The difference between a grid and a panel is that it's possible to define how a panel looks. A grid in an invisible container to just hold the items.

{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|}

== Password box ==
{| class="wikitable"
!key
!type
!default
!description
|-
| label
| [[GUIVariable#t_string|t_string]]
| ""
| The initial text of the password box.
|}

== Progress bar ==
A progress bar shows the progress of a certain object.

A progress bar has no extra fields.

== Repeating button ==
A repeating_button is a control that can be pushed down and repeat a certain action. Once the button is down every x milliseconds it is down a new down event is triggered.

== Rich Label ==
A label that shows formatted text marked up with [[Help markup]]. It can show embedded images, links and tables inside text.

{| class="wikitable"
!key !!type !!default !!description
|-
| text_alignment || [[GUIVariable#h_align|h_align]] || left || The way the text is aligned inside the canvas.
|-
| width || [[GUIVariable#int|int]] || 500 || Width of its internal formatted content. Text will wrap beyond this width.
|-
| link_aware || [[GUIVariable#bool|bool]] || false || Whether the label is link aware. This means it is rendered with links highlighted, and responds to click events on those links.
|}

== Scroll label ==
A scroll label is a label that wraps its text and also has a vertical scrollbar. This way a text can't be too long to be shown for this widget.

List with the scroll label specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|}

== Scrollbar panel ==
Instance of a scrollbar_panel.

List with the scrollbar_panel specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| definition
| [[GUIVariable#section|section]]
| mandatory
| This defines how a scrollbar_panel item looks. It must contain the grid definition for 1 row of the list.
|}

== Spacer ==
A spacer is a dummy item to either fill in a widget since no empty items are allowed or to reserve a fixed space.

If either the width or the height is non-zero the spacer functions as a
fixed size spacer.

{| class="wikitable"
!key !!type !!default !!description
|-
| width || [[GUIVariable#f_unsigned|f_unsigned]] || 0 || The width of the spacer.
|-
| height || [[GUIVariable#f_unsigned|f_unsigned]] || 0 || The height of the spacer.
|}

The variable available are the same as for the window resolution see
http://www.wesnoth.org/wiki/GUIToolkitWML#Resolution_2 for the list of
items.

== Tab Container ==

A container widget that can show its contents separated into various pages, each of which are accessible.

It can contain one or more <code>[tab]</code> tags inside it, each defining a tab's name, image (if any) and the contents of the tag, specified by the <code>[data]</code> tag inside the <code>[tab]</code> tag.

=== Subtag [tab] ===

{| class = "wikitable"
!key !!type !!default !!description
|-
| name || [[GUIVariable#t_string|t_string]] || "" || Name of the tab
|-
| image || [[GUIVariable#string|string]] || "" || Image for the tab to be shown alongside the name, if any
|-
| [data] || [[GUIVariable#grid|grid]] || empty grid || This subtag contains a grid that defines the contents for this tab.
|}

== Text box ==
A single line text entry widget.

[[File:Text Box.png|frame|right|A Text Box]]

{| class = "wikitable"
!key !!type !!default !!description
|-
| label || [[GUIVariable#t_string|t_string]] || "" || The initial text of the text box.
|-
| history || [[GUIVariable#string|string]] || "" || The name of the history for the text box. A history saves the data entered in a text box between the games. With the up and down arrow it can be accessed. To create a new history item just add a new unique name for this field and the engine will handle the rest.
|-
| max_input_length || [[GUIVariable#int|int]] || 0 || Maximum length of text in characters that can be entered into the combobox
|-
| hint_text || [[GUIVariable#string|string]] || "" || Text that is shown in the background when there is no input
|-
| hint_image || [[GUIVariable#string|string]] || "" || Image that is shown in the background when there is no input
|-
| editable || [[GUIVariable#bool|bool]] || "true" || If the contents of the text box can be edited.
|}

== Toggle panel ==
A toggle panel is an item which can hold other items. The difference between
a grid and a panel is that it's possible to define how a panel looks. A grid
in an invisible container to just hold the items. The toggle panel is a
combination of the panel and a toggle button, it allows a toggle button with
its own grid.

Variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id, see [[GUIToolkitWML#Button]] for more information.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value, see [[GUIToolkitWML#Button]] for more information.
|}

== Tree view ==
A tree view is a control that holds several items of the same or different types. The items shown are called tree view nodes and when a node has children, these can be shown or hidden. Nodes that contain children need to provide a clickable button in order to fold or unfold the children.

List with the tree view specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| indention_step_size
| [[GUIVariable#unsigned|unsigned]]
| 0
| The number of pixels every level of nodes is indented from the previous level.
|-
| node
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The tree view can contain multiple node sections. This part needs more documentation.
|-
| id
| [[GUIVariable#unsigned|unsigned]]
| ""
| .
|-
| return_value_id
| [[GUIVariable#unsigned|unsigned]]
| ""
| .
|}

NOTE more documentation and examples are needed.

== Vertical scrollbar ==

== Viewport ==
A viewport is an special widget used to view only a part of the widget it `holds'.

List with the viewport specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grow_direction
| [[GUIVariable#grow_direction|grow_direction]]
| mandatory
| The direction in which new items grow.
|-
| parallel_items
| [[GUIVariable#unsigned|unsigned]]
| mandatory
| The number of items that are growing in parallel.
|-
| item_definition
| [[GUIVariable#section|section]]
| mandatory
| The definition of a new item.
|}

== Scroll Text ==
A multiline text area that shows a scrollbar if the text gets too long.

List with the scrollbar container specific variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| vertical_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| horizontal_scrollbar_mode
| [[GUIVariable#scrollbar_mode|scrollbar_mode]]
| initial_auto
| Determines whether or not to show the scrollbar.
|-
| editable
| [[GUIVariable#bool|bool]]
| "true"
| If the contents of this scroll_text can be edited.
|}

== Slider ==

A slider is a control that can select a value by moving a grip on a groove.

{| class="wikitable"
!key
!type
!default
!description
|-
| best_slider_length
| [[GUIVariable#unsigned|unsigned]]
| 0
| The best length for the sliding part.
|-
| minimum_value
| [[GUIVariable#int|int]]
| 0
| The minimum value the slider can have.
|-
| maximum_value
| [[GUIVariable#int|int]]
| 0
| The maximum value the slider can have.
|-
| step_size
| [[GUIVariable#unsigned|unsigned]]
| 0
| The number of items the slider's value increases with one step.
|-
| value
| [[GUIVariable#int|int]]
| 0
| The value of the slider.
|-
| minimum_value_label
| [[GUIVariable#t_string|t_string]]
| ""
| If the minimum value is chosen there might be the need for a special value (eg off). When this key has a value that value will be shown if the minimum is selected.
|-
| maximum_value_label
| [[GUIVariable#t_string|t_string]]
| ""
| If the maximum value is chosen there might be the need for a special value (eg unlimited)). When this key has a value that value will be shown if the maximum is selected.
|}

== Toggle button ==
Variables:
{| class="wikitable"
!key
!type
!default
!description
|-
| grid
| [[GUIVariable#grid|grid]]
| mandatory
| Defines the grid with the widgets to place on the panel.
|-
| return_value_id
| [[GUIVariable#string|string]]
| ""
| The return value id.
|-
| return_value
| [[GUIVariable#int|int]]
| 0
| The return value.
|}

[[Category: WML Reference]]
[[Category: GUI WML Reference]]

Sandbox/GUI/Getting Started

2024-09-22T12:33:16Z

White haired uncle: /* Definitions */

So, it looks like I can't exclude this page/section from the search engine as I had hoped. I wanted to put this in a sandbox so that it wouldn't be published without some proper review.

==Introduction==

This guide is designed to help you get a simple Wesnoth GUI, implemented in lua, up and running while describing the basic building blocks along the way. It is written in a narrative format, where most examples build on previous examples, and therefore while not always necessary it may be desirable to read from start to finish. The reader, probably a UMC author, should have a basic knowledge of working with lua within Wesnoth.

Some would find creating a GUI in part or in full using WML simpler to follow, and those alternatives are available, for example [[LuaAPI/gui/example]], but we're using lua here. If you find WML easier to follow, you can always convert the lua tables that define the GUIs to WML using [[LuaAPI/wml#wml.tostring|wml.tostring]], for example:

<syntaxhighlight lang=lua>
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
</syntaxhighlight>

In some examples, instead of defining the entire GUI at once, we'll break out some parts into separate variables. If you try to view one in WML and get an error from wml.tostring() about expecting a WML table and not a table, try passing your variable(/table) inside a table:

<syntaxhighlight lang=lua>
print(wml.tostring({listboxItem}))
gui.show_lua_console()
</syntaxhighlight>

One distinct advantage of using WML to define your GUI layout is that you get better (any) validation. Invalid keys, and sometimes values, are often flagged in the log, unlike with lua where they are silently ignored. In the comments of our first GUI, below, is an example which loads a WML GUI configuration using [[LuaAPI/wml#wml.load|wml.load()]], validating against the GUI2 window schema.

===What is GUI2?===
Once upon a time, Wesnoth had a GUI system which is now commonly referred to as GUI1. As of 1.19, GUI1 has been almost completely replaced by GUI2. UMC authors will probably never encounter GUI1 and can simply use the terms GUI and GUI2 interchangeably, at least until GUI3 comes along.

Instead of spending a lot of time here giving an overview of what GUI2 is and what makes it great, and not so great, let's charge ahead so we can see it in action, and let readers who are interested look elsewhere(TODO: link) for a more formal definition. (TODO: is this the right approach for most readers?).

==Getting Started==

For example purposes, we'll create a directory in our campaign directory called lua containing a file called gui_tutorial.lua, and add a command in the prestart event for a scenario which will create a right-click menu option to invoke our new GUI. Of course there are other methods to invoke lua from WML, but this one will get us started. After all, we really just want to get something up on the screen ASAP, right?

===A most basic GUI===

{|
|[[File:Most basic gui.png|center|thumb|I can't believe this worked]]
|-
|In our prestart event, we create a simple menu item, which executes a single line of lua which calls the lua function most_basic_gui() which is found in gui_tutorial.lua:
|}

<syntaxhighlight lang=wml>
[set_menu_item]
id=most_basic_gui
description="Our first GUI"
[command]
[lua]
code=<<
wesnoth.require("~add-ons/<OUR_CAMPAIGN>/lua/gui_tutorial.lua").most_basic_gui()
>>
[/lua]
[/command]
[/set_menu_item]
</syntaxhighlight>

And create gui_tutorial.lua:
{| class="wikitable" style="margin:auto"
! !! The WML equivalent of dialogDefinition
|-
|
<syntaxhighlight lang=lua>
local function most_basic_gui()
local dialogDefinition = {
--click_dismiss = true, -- allow user to close dialog with click of a button
wml.tag.tooltip { id = "tooltip_large" }, -- required
wml.tag.helptip { id = "tooltip_large" }, -- required
wml.tag.grid { -- our most basic gui
wml.tag.row { -- a grid must include at least one row
wml.tag.column { -- a row needs a column
wml.tag.image { -- a column includes exactly one widget
label = "units/trolls/grunt.png"
}
}
}
}
}

local function preshow(dialog)
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
end
gui.show_dialog(dialogDefinition,preshow)

-- Or, if you want to define the gui in WML, something like:
-- local dialog_wml = wml.load("~add-ons/GUI_Tutorial/most_basic_gui.cfg",
-- true, "schema/gui_window.cfg")
-- gui.show_dialog(wml.get_child(dialog_wml, 'resolution'))
end
return { most_basic_gui = most_basic_gui}
</syntaxhighlight>
|
<syntaxhighlight lang=wml>
[tooltip]
id="tooltip_large"
[/tooltip]
[helptip]
id="tooltip_large"
[/helptip]
[grid]
[row]
[column]
[image]
label="units/trolls/grunt.png"
[/image]
[/column]
[/row]
[/grid]

</syntaxhighlight>
|}

In the above file, we have just the single function to create our GUI, followed by a return command which makes our function most_basic_gui() available to the [[LuaAPI/wesnoth#wesnoth.require|wesnoth.require()]] function as most_basic_gui().

Our function creates a table containing the definition of a "dialog", and then passes that to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]]. It should be noted that gui.show_dialog does not provide synchronization, so if your GUI makes changes to the game state, you'll need to jump through some hoops or you'll break replays and multiplayer, but that's not something we need to care about at this point, so just be aware that you may need to deal with it in the future.

Our dialog definition at this point includes three parts. The first two are a tooltip and a helptip, which are required and define how tooltips (use id = "tooltip_large" or id = "tooltip" or id = "tooltip_transparent"), and helptips (rarely used, but must be included here, and yes their definitions are "tooltip" not "helptip") will look (as we will see later, this really should be definition = "tooltip", but in this case it's id = "tooltip"). The third part is a grid, which is basically a table, like in HTML or MySQL, with rows and columns. A grid always contains at least one row. A row contains at least one column (note that a column does NOT span rows, it is completely contained within a row). Inside a column is exactly one item, a cell which contains a [[GUIWidgetDefinitionWML|widget]], in this case we'll use an image (later we'll see what else we can put in a cell). Note that we don't actually define a cell in our code, it's just a term used to refer to the contents of a column.

The preshow function is optional. If included in the call to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]], it is run before the GUI is displayed. In this case, we include it to display the dialog we created with lua in WML format. Near the end, in comments, we show how you would call [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] if you chose to define your dialog using WML. Note that what is shown here is the WML equivalent of our lua dialogDefinition, and not the complete WML you would need to use if you were to configure your GUI layout in WML.

Note: if you should try out the above, you'll have to hit escape or enter to close the GUI. Uncomment the "click_dismiss" line, and the user will be able to close the GUI with a mouse click.

===Adding a little flavor===

{|
|You may have noticed our GUI is missing a header and a way to close it when we're done admiring our work. Here we add a new first row to our grid, while demonstrating a couple formatting options: a border to put some distance between our grid cell and its neighbor, and the "use_markup = true" option to enable Pango support in our text.

Our third row adds an OK button at the bottom. You can associate actions with buttons to do all kinds of things, but here we just exploit the default behaviour to close the GUI.

Of course, we'll also have to modify our return to support the new function, and update our menu item(s) accordingly.
|-
|[[File:Most basic gui2.png|center|thumb|Adding header and a footer]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui2()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
gui.show_dialog(dialogDefinition)
end
return { most_basic_gui = most_basic_gui, most_basic_gui2 = most_basic_gui2 }
</syntaxhighlight>

===And a bit more===
{|

|And now a minor, but important change. We want to add a new text field next to the image in the body of our GUI. Obviously, we want to add a new column, but this is more difficult than when we added new rows in the previous example. The problem is that all rows (at a given level) in a grid must contain the same number of columns. We can't have two columns in the row that constitutes the body of our GUI, but only one in the header and one in the footer. To solve this problem, we replace our image widget with a new grid, which can use as many columns as we like (as long as they are the same within each row of our new grid). This new grid contains a row with two columns, but that is okay because the new grid itself is placed in a single column, which matches our single column header and footer (ok button), keeping the rows balanced.
|-
|[[File:Most basic gui3.png|center|thumb|Rows with different numbers of columns]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui3()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column { -- This is the only column in this row,
-- to match the number of columns in
-- the rows of our header and footer
wml.tag.grid { -- A new grid, so we can use a different
-- number of columns
wml.tag.row {
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
},
wml.tag.column {
wml.tag.label {
label = "A troll"
}
}
}
}
}
},
wml.tag.row { -- A footer
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = "Ok"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

While we see here just the simplest of examples, you can many levels of grids in grids, rows with multiple columns some of which containing grids, etc, to build complicated dialogs to your liking.

==Containers==

===Stacked Widget===

TODO

===Listbox===
{|
| Now we'd like to add some more monsters. Obviously, we could just add more rows, but what if we won't know until runtime how many and which ones? We could break up the definition of our dialog and add new rows dynamically, it's just a table after all, but fortunately we have a widget which handles this for us, a listbox. A listbox is kind of like an array, a collection of similar objects where the number of items can vary. We will tell the GUI where we want the box, and what each entry in the box will look like, and then at runtime we can add entries to the box.
|-
| [[File:Gui with listbox.png|center|thumb|Listbox with three items]]

<syntaxhighlight lang=lua>
local function gui_with_listbox()
local monsters = {
{ image = "units/trolls/grunt.png",
string = "A troll" },
{ image = "units/monsters/cuttlefish.png",
string = "A cuttlefish" },
{ image = "units/monsters/yeti.png",
string = "A yeti" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
}

local listboxDefinition = wml.tag.listbox { id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
listboxDefinition
}
},
wml.tag.row {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_label.label = monster.string
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We begin by creating a simple table which represents the data which will be presented in our listbox. In most cases, we probably wouldn't create that monster table here, but we need it for our example.

The variable listbox_id gives us an identifier for our listbox so we can reference it when we need to. We don't really need to use a variable here, it's just convenient.

We define the structure for the elements in our listbox, stored in listboxItem. Note that we've replaced the actual data with identifiers (e.g. 'units/trolls/grunt.png' becomes 'id = "monster_image"), since each element may have different data.

We define the listbox itself, specifying the identifier, and the definition of our listbox element (which looks a lot like a grid). The cell inside the column contains a variable which is just the listbox element definition we created above; it's not necessary to do this, we could have used one big table, but it's easier to read this way (IMO).

We replace the hardcoded data in our GUI body with our new listbox definition, again using a variable to make it easier to read.

We create a function, often called preshow(), which will be called for us as part of the drawing the GUI (see the new optional argument in [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] -- there's also an optional postshow(), but we don't need it here). This is where we pull the data from our example table into the listbox. We create a listbox variable associated with the listbox, identified by the listbox_id we assigned earlier, inside the dialog which gui.show_dialog() passes to preshow(). Then we iterate through our data table, using each entry from that table to populate a listbox item.

Let's look at that last action a little more closely using an example.

<syntaxhighlight lang=lua>
listbox[i].monster_image.label = monster.image
</syntaxhighlight>

Which we can read as "In listbox element i of our listbox, for the image with identifier monster_image which we defined in our listboxItem, use the data from the corresponding index i in our example data table" (you don't see the index i for the monsters table here, but remember we're iterating using ipairs, we could have just as easily used listbox[i].monster_image.label = monsters[i].image). If you were to step through all of the variable substitutions, you'd see that for i=1, our dialogDefinition is basically the same thing as it was in the earlier examples, just supplied from a table instead of hardcoded (note that you can hardcode entries in a listbox in your dialog definition using the [list_data] tag, aka wml.tag.list_data, which we do not demonstrate here).

You will probably notice that our data does not line up nicely in the GUI. We will fix that later. We'll also demonstrate how the user can select an item in a listbox, and how you can identify which item that was using the selected_index variable of the listbox.

===Tree View===
====Simple Tree View====
{|
| You may have noticed that clicking on a listbox item in our listbox caused it to be highlighted with a box around the contents. This is because the items in a listbox are selectable. This will be useful when we want to add actions, but it looks a bit odd if we just want to present a list of data.

Also, most of the data had to be formatted the same for each item in the listbox. We could, perhaps, include custom markup in our labels, but the actual layout, like the number of columns per row, had to be the same for every item.

Another way to present a list of data is the tree view. Since a tree view supports multiple data types, we may need to create multiple definitions for the elements in our list. These are known as nodes. It will also be necessary to explicitly define which node to use for each element when we populate our tree view.
|-
| [[File:Basic tree view.png|center|thumb|Tree_views can hold multiple data types (only trolls have names here)]]
|}
<syntaxhighlight lang=lua line>
local function basic_tree_view()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", type = "Seamonsters" },
{ image = "units/monsters/yeti.png", label = "A yeti",
type = "Coolers" }
}

local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "trolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name",
linked_group = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
},
wml.tag.node {
id = "nottrolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "monster_name",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_image",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_label",
fixed_width = true
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_tv:add_item_of_type("trolls_node")
dialog.monsters_tv[i].monster_name.label = monster.name -- only trolls have a name
else
dialog.monsters_tv:add_item_of_type("nottrolls_node")
end
-- All of our monsters have an image and a label
dialog.monsters_tv[i].monster_image.label = monster.image
dialog.monsters_tv[i].monster_label.label = monster.label
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We have expanded our list of monsters to include three types of trolls. We have also given each troll a name. This is of course a rather simplistic example, we could have simply given each monster that is not a troll an empty name, but it as presented here our approach serves the purpose of demonstrating how we deal with multiple data types. Our new tree view contains a node for each type of data we will present. In preshow, we explicitly define each element in our list using add_item_of_type(), and populate the item accordingly. [Note: in our listbox example, we could have used add_item() to add items to the listbox, but chose not to since that section was already introducing a number of new concepts. But here, since we have multiple types of items we need to be able to specify the type of the item when we add one, hence we need to use add_item_of_type()].

You may also note the addition of a few linked_group lines. We'll cover linked groups in more detail later, but as used here they instruct the GUI that each column using the same node type needs to be aligned with the others. For example, all of our trolls line up nicely.

====Building a Tree====
{|
| colspan="2" |At this point, one may wonder about the name "tree view", since what he have seen doesn't look much like a tree. To make a tree-like structure, we'll demonstrate adding children to nodes. At the top level our (upside-down) tree will have two nodes, one for trolls and one for everything else. A toggle_button (a type of button which changes states when you push it) will allow us to expand the trolls node to expose its children, which are themselves nodes, though they only contain a label at this point.
|-
| [[File:Basic tree view2a.png|center|thumb|Tree_view with Trolls folded]] || [[File:Basic tree view2b.png|center|thumb|Tree_view with Trolls unfolded]]
|}
<syntaxhighlight lang=lua line>
local function building_a_tree()
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
}
},
wml.tag.column {
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Show me the " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
-- You can refer to an object by its position

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[1].race_label.label = "Trolls"
-- dialog.monsters_tv[1].race_button.on_modified =
-- function()dialog.monsters_tv[1].unfolded =
-- dialog.monsters_tv[1].race_button.selected end

-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][1].monster_type.label = "Whelp"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][2].monster_type.label = "Shaman"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][3].monster_type.label = "Troll"

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[2].race_label.label = "Other scary things"
-- dialog.monsters_tv[2].race_button.visible = "hidden"

-- ... or you can refer to that object using the return value
-- from add_item_of_type
local troll_node = dialog.monsters_tv:add_item_of_type("race_node")
troll_node.race_label.label = "Trolls"
troll_node.race_button.on_modified =
function()
troll_node.unfolded = troll_node.race_button.selected
end
local item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Whelp"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Shaman"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Troll"

local not_troll_node =
dialog.monsters_tv:add_item_of_type("race_node")
not_troll_node.race_label.label = "Other scary things"
not_troll_node.race_button.visible = "hidden"

end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We define two nodes in our tree, a race_node for the top level, and a details_node for the children of a race_node. The rest of the interesting bits are in preshow().

We demonstrate two different ways of creating and accessing items, the first (commented out) just using the order in which they are created, while in the second we capture the result of add_item_of_type() in a variable we can use to refer to the newly defined object. The first method is shown primarily to demonstrate the structure of the resulting objects. The second method is perhaps easier to follow, and is almost necessary when you start doing things like dynamically deleting nodes, so it is in most cases a better practice (of course, you probably won't want to use the same variable for each node like we did, and perhaps not one local to the preview function).

We add a node, label it "Trolls", and add a callback to the button such that the children of the node will be visible (the node is "unfolded", a boolean value which defaults to false) when the button is checked (selected == true). Then we add three "details_node" nodes as children of this node.

Our second node, "Other scary things" will remain empty for now, so we'll set the visible attribute on its button to "hidden" (which is like false, but with hidden the widget still takes up space).

{|
| This example is rather ugly, both in the hardwired code and the appearance of the resulting GUI, but it addresses a couple important aspects of how tree views work and how we might use them. Let's clean it up a bit. We'll add an indentation_step_size to the tree view, along with a spacer and [[#Alignment|horizontal_alignment]] to our details node, to make the labels line up nicely, and change the button [[#Definitions|definition]] to replace the checkbox with something that looks like it belongs there. We will look at methods for handling layout in more depth [[#Appearance|later]].
|-
| [[File:Basic tree view2c.png|center|thumb|Our tree_view with proper alignment]]

<syntaxhighlight lang=lua>
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
indentation_step_size = 20,
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
definition = "tree_view_node"
}
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.spacer { width = 40 }
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}

</syntaxhighlight>

===Multi_page===
====Simple Multi_page====
{|
|-
Like a tree_view, a multi_page is a heterogeneous container which is dynamically populated, however, while a multi_page contains multiple elements (pages), only one page is displayed at any one time. Its purpose is perhaps best described by a couple of examples.
|-
[[File:Basic multipage.png|center|thumb|Multi_page showing active page]]
|}
<syntaxhighlight lang=lua>
local function basic_multipage()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll",
name = _"Bob", type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp",
name = "Junior", type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman",
name = _"Alice", type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish",
type = "Seamonsters" },
{ image = "units/monsters/yeti.png",
label = "A yeti",
type = "Coolers" }
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
multi_page
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}

local function preshow(dialog) -- Prepare the GUI before display
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_label.label = monster.label
end
--dialog.monsters_mp.selected_index = 5
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

As you can see, the code for our basic multi_page GUI looks a lot like our basic tree_view GUI. The difference is what is displayed. While both the tree_view and the multi_page containers contain five items, with the multi_page, only the first one is displayed. More specifically, only the page associated with the selected_index attribute of the multi_page object, which defaults to 1, is displayed. If we were to uncomment the last line in preshow(), we would still see only one item, but it would be the fifth one we allocated. It's nice to know all our pages are in there somewhere, but this example is pretty useless. What we need is a way to select which page we want to see from within our GUI.

====A More Useful Multi_page====

{|
| colspan="2" | To demonstrate the usefulness of a multi_page, and highlight its difference from a tree_view, we'll add a listbox to allow us to select the page to view. We'll also need to add a little action to our GUI.
|-
| style="align:centered" |[[File:More useful multipage.png|center|thumb|User selected Troll]] || [[File:More useful multipage2.png|center|thumb|User selected Cuttlefish]]
|}

<syntaxhighlight lang=lua>
local function more_useful_multi_page()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
race = "Trolls", tip = "Your uncle" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
race = "Trolls", tip = "Your nephew" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
race = "Trolls", tip = "Your auntie" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", race = "Seamonsters",
tip = "Not a fish" },
{ image = "units/monsters/yeti.png",
label = "A yeti", race = "Coolers",
tip = "ROAR!" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
}
}
}

local listboxDefinition = wml.tag.listbox {
id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
},
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
listboxDefinition
},
wml.tag.column {
wml.tag.spacer {
width = 30
}
},
wml.tag.column {
multi_page
},
}
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_image.tooltip = monster.tip
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_image.tooltip = monster.tip
dialog.monsters_mp[i].monster_label.label = monster.label
end
local function switch_page()
dialog.monsters_mp.selected_index = listbox.selected_index
end
listbox.on_modified = switch_page
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

Most of this should look pretty familiar. We've simply taken the previous example and added a second column to our GUI using code from an earlier example to add a listbox. In addition, we altered the page layout slightly, and added a spacer column in the dialog definition to approve the appearance.

The interesting stuff is in preshow(). Again we've merged in some listbox code from an earlier example, but we've also created a new local function switch_page(), which simply sets the selected_index attribute of our multi_page to the same as that of our listbox, and then we've configured the listbox.on_modified callback to call switch_page(). Now when the user selects an item in the listbox (updating listbox.selected_index and triggering listbox.on_modified), dialog.monsters_mp.selected_index is updated accordingly and therefore the visible page changes to the one associated with the selected unit.

Also note in preshow() we've added a new child to our monster_image identifier for both the listbox and the multi_page, a tooltip. When the user hovers the mouse over the image of one of our monsters, they'll see a popup message which we've added to our monster table. Try changing '''wml.tag.tooltip { id = "tooltip_large" }''' to '''wml.tag.tooltip { id = "tooltip }''' in the dialogDefinition to see a different tooltip style.

==Actions Have Consequences==

So far, our GUIs have only displayed some information on the screen, but at some point we're probably going to want to use a GUI to get input from the user. In this section we will look at return values that can be assigned to a widget based upon its state, and callbacks, which are functions invoked when something happens with a widget. As we will see, a button is a good example, as it can return a value or take an action, or both, when pressed. Earlier we saw how the selected_index attribute of some widgets, such as the listbox, can also be used as a sort of return value.

===Buttons===
{|
| colspan=2 | In this example, we'll create a couple buttons which provide the user a choice, use a handy confirmation popup to confirm that choice, and demonstrate how we get the results back where we can put them to use.
|-
| [[File:Basic return value.png|center|thumb|There can be only one]] || [[File:Basic return value_confirm.png|center|thumb|The user selected Alice, let's confirm this critical choice]]
|}

<syntaxhighlight lang=lua>
local function basic_return_value()

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "leader_lg",
fixed_height = true,
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" ..
_"Which unit shall lead your army?" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Alice" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/elves-wood/sylph.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 1
}
}
},
}
},
wml.tag.column {
wml.tag.spacer { width = 20 }
},
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Bob" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/human-loyalists/marshal.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 2
}
}
}
}
}
}
}
}
}
}
}
local user_chose = gui.show_dialog(dialogDefinition)
local leader
if user_chose == -1 then -- User closed the dialog by hitting the Enter key
leader = nil
end
if user_chose == -2 then -- User closed the dialog by hitting the Escape key
leader = nil
end

if user_chose == 1 then
leader = "Alice"
end
if user_chose == 2 then
leader = "Bob"
end

local confirmed_leader_choice

if leader ~= nil then
local query = _"You want " .. leader .. _" as your leader?"
confirmed_leader_choice = gui.confirm(query)
end

if confirmed_leader_choice then
wesnoth.message("Great!")
else
wesnoth.message("Fine, lead them yourself!")
end
end
</syntaxhighlight>

Here we've added a couple buttons, and assigned each of them a return value. When the user selects one of these buttons, the GUI is closed and the value of return_value is returned from gui.show_dialog(). We then use [https://wiki.wesnoth.org/LuaAPI/gui#gui.show_prompt gui.confirm()] which provides a very simple Yes/No popup and returns true or false, respectively. Other useful functions can be found on that page which provide handy alternatives to creating your own GUI for other simple user inputs.

The use of return_value is rather limited, as it only returns integers and can't be used with containers like listboxes. In more complex cases we'll need to turn to callback functions which are invoked when something happens to a widget, like clicking a button or a widget's value changing. Earlier, we saw an example of [[LuaAPI/types/widget#on_modified|widget.on_modified()]]. More examples of callbacks can be found at [[LuaAPI/types/widget#on_modified|that link]].

===Slider and Textbox===
{|
| Here we see a couple methods of getting more dynamic input from the user, a slider and a textbox presented in one silly example.
|-
| [[File:Slider and textbox.png|center|thumb|Two ways of getting input from the user]]
|}

<syntaxhighlight lang=lua>
function scrollbar_and_textbox()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = _"How much gold will you pay for this old rusty sword?"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.slider {
id = "gold_sl",
minimum_value = 0,
maximum_value =
wesnoth.sides[wesnoth.current.side].gold,
value = math.floor(
wesnoth.sides[wesnoth.current.side].gold/2)
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.text_box {
id = "gold_tb",
--hint_text = _ "Enter gold here",
--hint_image = "images/gold_pile.png",
label = tostring(math.floor(
wesnoth.sides[wesnoth.current.side].gold/2))
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
local function show_input()
wesnoth.interface.add_chat_message(_"You chose " ..
dialog.gold_sl.value .. _" with the slider")
wesnoth.interface.add_chat_message(_"You entered " ..
tostring(dialog.gold_tb.text) .. _" in the text_box")
end
-- this is a button, so we use on_button_click, not on_left_click
dialog.ok.on_button_click = show_input

dialog.gold_sl.on_modified = function()
dialog.gold_tb.text = tostring(dialog.gold_sl.value)
end
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We create a slider, with a range from 0 to the amount of gold possessed by the current side and an initial value in the middle, and a text box with the same initial value. We assign a function to our OK button which simply reports on the values provided by the user. For no reason whatsoever, we add a callback such that when the user adjusts the slider the value in the textbox is update to match the slider.

Note that the textbox returns text, even though it looks like we're expecting the user to input a natural number. Remember to validate those inputs.

You can use text_hint to place a caption in the box that will help the user understand what to enter in the box, and possibly an image as well. For example, in the search box in the recall menu uses '''hint_text = _ "Search", hint_image = "icons/action/zoomdefault_25.png~FL(horiz)"'''. Of course, you can't have a hint and a label in the same text_box at the same time, so in our example we've only included them as comments.

There is also a widget called a spinner, which is kind of like the combination of a text_box and a slider. As of the release of 1.18, it appears to be unfinished so the strange syntax needed to make it work is probably not the best thing to document, and we will omit it for now.

==Appearance==

'''This section needs help'''

===Borders===

Borders allow you to force unused space around a column, for example so that your widgets don't runtogether. You can specify the border to be one or more of top, bottom, left, right, or all. The border_size sets the amount of padding, in pixels.

<syntaxhighlight lang=lua>
wml.tag.column{
border = "left, right"
border_size = 25
}
</syntaxhighlight>

===Alignment===
{|
| colspan=2 |By default, the GUI will usually center widgets in their cells, which is not always what we want. In this example, we use horizontal_alignment to move widgets around a little.

In more complex cases, it may be useful to add [[GUIWidgetDefinitionWML#Spacer|spacers]] to help force alignment, or use linked_groups to force consistent alignment for objects within a grid.
|-
| [[File:Gui tutorial alignment without.png|center|thumb|Default alignment]] ||[[File:Gui tutorial alignment with.png|center|thumb|Showing off some alignment options]]
|}
<syntaxhighlight lang=lua>
local function basic_alignment()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = "Ralph"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "right",
wml.tag.label {
label = "Sam"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/troll-hero-attack-se-4.png" -- 122x102
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "left",
wml.tag.label {
label = "Jr"
}
},
wml.tag.column {
horizontal_alignment = "right",
wml.tag.image {
label = "units/trolls/whelp.png" -- 72x72
}
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

The screenshots show the output of this example with and without the horizontal_alignment lines included above.

A label allows you to set the text_alignment field (e.g. text_alignment = "left"). Note, however, this only aligns the text within the label. The label itself will probably be centered in the column, giving the false appearance that your text alignment is not working.

===Growth===

To keep your dialog nicely balanced, the GUI2 engine may need to grow rows and/or columns. You can control which columns, for example, grow and which do not, by setting some with grow_factor = 1, and others with grow_factor = 0 (do not grow). While grow factors of 0 and 1 are the most common, you can use other values to adjust the relative growth if you really need to, see [[GUILayout]] for the gory details.

It it sometimes useful to include a column with a [spacer] and a grow_factor (often the only column with grow_factor != 0) whose sole purpose is to keep your GUI aligned nicely as the layout engine does its evil.

To force a column to stretch to fit available space, use horizontal_grow = true. Note that horizontal_grow is not compatible with horizontal_alignment. There is also a vertical_grow parameter.

If you need to see every little detail about the layout process, start wesnoth with --log-debug=gui/layout. Good luck with that.

===Definitions===
Many widgets can be configured to have to a different appearance, for example in our tree_view example we changed the definition of a toggle_button from the default of a checkbox by setting definition = "tree_view_node". This option was found by looking at the id of a toggle_button_definition in .../data/gui/widget/toggle_button_tree_view_node.cfg:

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib
###
### Definition of a toggle button to be used in a tree view as node fold/unfold indicator
###
[toggle_button_definition]
id = "tree_view_node" # <--- we can use 'definition = "tree_view_node"' in a [toggle_button] to select this definition
description = "Fold/unfold status indicator of a tree view node."
</syntaxhighlight>

{|
|There are many other definitions for buttons and other widget types in that directory. It would be nice to have a list (linked here), but for now you'll just have to look around.

We can even create our own custom definitions using [[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition()]]. In this example, we copy from .../data/gui/widget/toggle_button_tree_view_node.cfg with a slight change so that our button turns red ( '''~BLEND(255,0,0,1)''' ) when focused.

In this example, we will use wesnoth.wml_actions to create the WML tag [add_widget_def_demo].

Note the first line, a common convention for creating an alias for wml.tag.
|-
|[[File:Gui tutorial custom widget.png|center|thumb|Different definition of buttons, including one of our own (right)]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag -- save ourselves some typing
function wesnoth.wml_actions.add_widget_def_demo()
local definition = {
id = "tree_view_node_custom",
description = "Fold/unfold status indicator of a tree view node (MODIFIED).",
T.resolution {
min_width = 25,
min_height = 19,
default_width = 25,
default_height = 19,
max_width = 25,
max_height = 19,
-- Unselected - note there's no tags for unselected/selected, that's simply determined by the order
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/fold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/fold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/fold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
-- Selected
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/unfold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
}
}
gui.add_widget_definition("toggle_button", "tree_view_node_custom", definition)

local dialogDefinition = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid {
T.row {
T.column {
T.toggle_button {
definition = "default"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node_custom"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end

</syntaxhighlight>

See [[GUIWidgetDefinitionWML]] for more details on widget definitions.

You can also give the whole dialog a definition, like definition = "tooltip_large". There is no gui.add_window_definition(), however a window is technically a type of widget so it may be possible to create your own window definitions (please update this if you do).

===Panels===

===Canvases===
Part of panels? Sort of?

A canvas is a surface you can draw on. A dialog has them, as does a panel, and for these canvas 1 refers to the background, while canvas 2 refers to the foreground. Other widgets may have canvases that may have other meanings, or no canvases at all. See more at [[LuaAPI/gui/widget#set_canvas]].

Here's a fun little trick. Set your dialog background to be transparent:
<syntaxhighlight lang=lua>
local function preshow(dialog)
dialog:set_canvas(1, { } )
end
</syntaxhighlight>

Or, if you want an opaque GUI background with the screen behind it blurred like what you see behind the text of a [message], you can set your window definition to "message":
<syntaxhighlight lang=lua>
...
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
definition = "message",
...
</syntaxhighlight>

{|
|Here we take our [[#Progress Bar|progress bar]], and add a text overlay.

Note: either using text on a canvas is rather limited, or I just couldn't figure it out. For example, I could not get the text size any smaller, and any attempts to do so simply resulted in very blocky text. And the spaces were necessary so that the text wasn't stretched out. I also find it surprising that the progress bar does not have this feature inherently. So it's not a great example, but it should be enough to get you started using canvases. Be sure to visit the [[LuaAPI/gui/widget#set_canvas|link]] mentioned above for more options.
|-
|[[File:Gui tutorial canvas text.png|center|thumb|A progress bar in the background, with text in the foreground]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar_with_overlay()
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.grid {
T.row {
T.column {
T.panel { id = "panel",
T.grid {
T.row {
T.column {
T.button { id = "button",
label =_ "Press me"}
},
T.column {
T.progress_bar { id = "progress" }
},
T.column {
T.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
dialog.panel:set_canvas(2, { T.text { text_alignment = "center", font_size = 48,
text_markup = true, text = " " ..
dialog.progress.percentage .. "% " } } )
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

You may notice we added a panel and placed our text on the foreground canvas(2) on it, since the progress_bar itself does not support canvases.

===Placement===

You may have noticed that all of our dialogs are centered on the screen. This is the default. You can override this and place the dialog wherever you like by setting automatic_placement = false, along with x, y, width, and height at the top level of your dialog definition (next to tooltip =, etc).

'''This part about placement needs review'''
If you prefer, you may replace x and/or y with horizontal_placement and vertical_placement, such as horizontal_placement = "left". You can even set the placement values using WFL, for example horizontal_placement = "(gamemap_width / 3)" -- see [[#Using WFL with GUI2|Using WFL with GUI2]].

==Miscellaneous==

TODO: This stuff doesn't belong in a tutorial. It's worth documenting, but not here. Better to save these here for now than keep them on my laptop.

===Progress Bar===
{|
|A progress_bar is a graphical representation of a percent. In this example, we present the user with a puzzle. They must hit the button repeatedly before they can close the GUI. A progress_bar displays their current progress toward completion.
|-
|[[File:Gui tutorial progress bar.png|center|thumb|upright=2]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.button { id = "button",
label =_ "Press me"
}
},
wml.tag.column {
wml.tag.progress_bar { id = "progress" }
},
wml.tag.column {
wml.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end

gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

===Unit Preview Pane===

{|
|A unit_preview_pane takes a unit (or a unit type), and presents a graphical representation of the unit and its more important attributes, along with tooltips for additional details, in the same way that the recall menu does. Here we see an example of a unit which has picked up some items, including a weapon, which are affecting its stats.
|-
|[[File:Gui tutorial unit preview pane.png|center|thumb]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag

function wesnoth.wml_actions.recall_from_variable(cfg)
local from_array = cfg.from or wml.error(
"[recall_from_variable]: missing required from= ")
local to_var = cfg.to or wml.error(
"[recall_from_variable]: missing required to= ")
local unit_list = wml.array_access.get(from_array) or wml.error(
string.format("[recall_from_variable]: failed to fetch wml array %s",from_array))

local listboxItem = T.grid {
T.row {
T.column {
T.label { id = "available_unit",
linked_group = "available_unit"
}
}
}
}

local listbox_id = "available_units"
local listboxDefinition = T.listbox { id = listbox_id,
T.list_definition {
T.row {
T.column {
T.toggle_panel { listboxItem }
}
}
}
}
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.linked_group { id = "available_unit", fixed_width = true },
T.grid {
T.row { -- header
T.column {
T.grid {
T.row {
T.column {
border = "bottom",
border_size = 10,
T.label {
use_markup = true,
label = ""
.. _"Select unit to recall" .. ""
}
}
}
}
}
},
T.row { -- Body
T.column {
T.grid {
T.row {
T.column {
border = "right",
border_size = 40,
listboxDefinition
},
T.column {
T.unit_preview_pane { id = "unit_preview" }
}
}
}
}
},
T.row { -- Footer
T.column {
T.grid {
T.row {
T.column {
T.spacer { width = 400 }
},
T.column {
border = "top,right",
border_size = 10,
T.button { id = "ok",
label = _"OK"
}
}
}
}
}
}
}
}

local picked = 1

local function preshow(dialog)
local listbox = dialog[listbox_id]
for i,unit in ipairs(unit_list) do
listbox[i].available_unit.label = unit.name .. "(" ..
unit.language_name .. ")"
end
local function draw_unit()
wesnoth.units.to_recall(unit_list[listbox.selected_index])
local tmp = wesnoth.units.find_on_recall{ id =
unit_list[listbox.selected_index].id }[1]
dialog.unit_preview.unit = tmp
wesnoth.units.extract(tmp)
picked = listbox.selected_index
end
draw_unit()
listbox.on_modified = draw_unit
end

gui.show_dialog(dialogDefinition,preshow)

wml.variables[to_var] = picked - 1
end

</syntaxhighlight>

This should all be pretty self evident by now. We are provided with an array of stored units (from [store_unit] in WML). We create a listbox populated with units and we use the selected_index to determine which element in the table to send to unit_preview_pane. Since our input is an array of unit data, not actual units, we use [[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] to take the definition of one from our array and place it on the recall list (turning it into an actual unit), [[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] to fetch that unit in a form that the unit_preview_panel understands, and finally [[wesnoth.units.extract|wesnoth.units.extract]] to remove the unit from the recall list when we are done with it.

And of course we subtract one from the selected_index when we return our choice to WML, since lua arrays count from 1 and WML from 0.

The unit_preview_pane will also accept a unit_type instead of a specific unit.

==Appendix==

===Explore Your Options===

We've seen a lot of options that can be set to modify the behaviour of our dialogs, some on columns, some on widgets, etc. These are in the process of being documented [[GUIWidgetInstanceWML|here]], but if you would like to go straight to the source, the data Wesnoth uses to validate your configuration can be found in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui data/schema/gui] under your install directory.

Let's look at a scroll_label, for example. A scroll_label is a widget, so we look in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/widget_instances.cfg widget_instances.cfg] and find the following. Here we can see five parameters we can provide to our scroll_label (in addition to the ones available to all widgets, like id and definition, see the entry super=... which refers you to the widget_instance in the file [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/generic.cfg data/schema/gui/generic.cfg]), along with their types and default values. For example, we could set "link_aware = true", and if we do not we can assume that link_aware will be false. While this does not explain what these parameters do, the information provided in the schema directory is often helpful nonetheless.

<syntaxhighlight lang=wml>
[tag]
name="scroll_label"
min="0"
max="infinite"
super="$generic/widget_instance"
{DEFAULT_KEY "horizontal_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "vertical_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "wrap" bool true}
{DEFAULT_KEY "text_alignment" f_h_align "left"}
{DEFAULT_KEY "link_aware" bool false}
[/tag]
</syntaxhighlight>

We see that our scrollbars are of type scrollbar_mode. It would probably help if we knew what values are available to the scrollbar_mode. In [https://github.com/wesnoth/wesnoth/tree/master/data/schema/types/gui.cfg data/schema/types/gui.cfg] we find this:

<syntaxhighlight lang=wml>
[type]
name=scrollbar_mode
value="always|never|auto|initial_auto"
[/type]
</syntaxhighlight>

The variable types found in the schema files are described at [[GUIVariable]].

Note: The keys in the schema file correspond to the attributes used when configuring your widgets. They will not always align perfectly with keys used by the Lua API. For example, the slider uses maximum_value in its configuration, and max_value when using the Lua API:

<syntaxhighlight lang=wml>
[slider]
id="my_slider"
maximum_value = 100
[/slider]
</syntaxhighlight>

<syntaxhighlight lang=lua>
dialog.my_slider.max_value = 90
</syntaxhighlight>

===Using WFL with GUI2===

If you look at the variable type descriptions at [[GUIVariable]] you may notice that many of them start with "f_" and have "or formula" in the description. This means that you can use [[Wesnoth_Formula_Language|Wesnoth Formula Language (WFL)]] formulas in these fields, with certain variables made available to you (which variables and what they mean can be challenging to ascertain, but you can generally figure it out by example).

Looking at [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/window.cfg data/schema/gui/window.cfg] we see that 'height' has type f_unsigned, which tells us that height is an unsigned integer, and that we can use a WFL formula to define it in a window_definition. In [https://github.com/wesnoth/wesnoth/tree/master/data/gui/themes/default/window/wml_message.cfg data/gui/window/wml_message.cfg] (data/gui/themes/default/window/wml_message.cfg starting around 1.19.2), we find the line '''height = "(screen_height - 30)"'''. This does exactly what it looks like, it sets the height of our window to 30 pixels less than the height of the screen.

===Useful Links===

[[LuaAPI/gui|LuaAPI/gui - Mostly about opening windows]] 
[[LuaAPI/types/widget|LuaAPI/types/widget - Widget attributes and callbacks]] 
[https://wiki.wesnoth.org/Category:GUI_WML_Reference GUI_WML_Reference] 
[https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui .../data/schema/gui/*.cfg] - Lists of valid options for various GUI objects 
[https://devdocs.wesnoth.org/layout_algorithm.html Layout Algorithm] - For windows, at least

===Credits===

The basic framework that composes the initial examples was lifted from LotI. It's a great place to find well written examples, but some of it is complex enough to be a little overwhelming when getting started.

Many examples, particularly tree view and multipage, are heavily derived from the World Conquest multiplayer campaign.

Sandbox/GUI/Getting Started

2024-09-22T11:54:08Z

White haired uncle: /* Definitions */

So, it looks like I can't exclude this page/section from the search engine as I had hoped. I wanted to put this in a sandbox so that it wouldn't be published without some proper review.

==Introduction==

This guide is designed to help you get a simple Wesnoth GUI, implemented in lua, up and running while describing the basic building blocks along the way. It is written in a narrative format, where most examples build on previous examples, and therefore while not always necessary it may be desirable to read from start to finish. The reader, probably a UMC author, should have a basic knowledge of working with lua within Wesnoth.

Some would find creating a GUI in part or in full using WML simpler to follow, and those alternatives are available, for example [[LuaAPI/gui/example]], but we're using lua here. If you find WML easier to follow, you can always convert the lua tables that define the GUIs to WML using [[LuaAPI/wml#wml.tostring|wml.tostring]], for example:

<syntaxhighlight lang=lua>
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
</syntaxhighlight>

In some examples, instead of defining the entire GUI at once, we'll break out some parts into separate variables. If you try to view one in WML and get an error from wml.tostring() about expecting a WML table and not a table, try passing your variable(/table) inside a table:

<syntaxhighlight lang=lua>
print(wml.tostring({listboxItem}))
gui.show_lua_console()
</syntaxhighlight>

One distinct advantage of using WML to define your GUI layout is that you get better (any) validation. Invalid keys, and sometimes values, are often flagged in the log, unlike with lua where they are silently ignored. In the comments of our first GUI, below, is an example which loads a WML GUI configuration using [[LuaAPI/wml#wml.load|wml.load()]], validating against the GUI2 window schema.

===What is GUI2?===
Once upon a time, Wesnoth had a GUI system which is now commonly referred to as GUI1. As of 1.19, GUI1 has been almost completely replaced by GUI2. UMC authors will probably never encounter GUI1 and can simply use the terms GUI and GUI2 interchangeably, at least until GUI3 comes along.

Instead of spending a lot of time here giving an overview of what GUI2 is and what makes it great, and not so great, let's charge ahead so we can see it in action, and let readers who are interested look elsewhere(TODO: link) for a more formal definition. (TODO: is this the right approach for most readers?).

==Getting Started==

For example purposes, we'll create a directory in our campaign directory called lua containing a file called gui_tutorial.lua, and add a command in the prestart event for a scenario which will create a right-click menu option to invoke our new GUI. Of course there are other methods to invoke lua from WML, but this one will get us started. After all, we really just want to get something up on the screen ASAP, right?

===A most basic GUI===

{|
|[[File:Most basic gui.png|center|thumb|I can't believe this worked]]
|-
|In our prestart event, we create a simple menu item, which executes a single line of lua which calls the lua function most_basic_gui() which is found in gui_tutorial.lua:
|}

<syntaxhighlight lang=wml>
[set_menu_item]
id=most_basic_gui
description="Our first GUI"
[command]
[lua]
code=<<
wesnoth.require("~add-ons/<OUR_CAMPAIGN>/lua/gui_tutorial.lua").most_basic_gui()
>>
[/lua]
[/command]
[/set_menu_item]
</syntaxhighlight>

And create gui_tutorial.lua:
{| class="wikitable" style="margin:auto"
! !! The WML equivalent of dialogDefinition
|-
|
<syntaxhighlight lang=lua>
local function most_basic_gui()
local dialogDefinition = {
--click_dismiss = true, -- allow user to close dialog with click of a button
wml.tag.tooltip { id = "tooltip_large" }, -- required
wml.tag.helptip { id = "tooltip_large" }, -- required
wml.tag.grid { -- our most basic gui
wml.tag.row { -- a grid must include at least one row
wml.tag.column { -- a row needs a column
wml.tag.image { -- a column includes exactly one widget
label = "units/trolls/grunt.png"
}
}
}
}
}

local function preshow(dialog)
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
end
gui.show_dialog(dialogDefinition,preshow)

-- Or, if you want to define the gui in WML, something like:
-- local dialog_wml = wml.load("~add-ons/GUI_Tutorial/most_basic_gui.cfg",
-- true, "schema/gui_window.cfg")
-- gui.show_dialog(wml.get_child(dialog_wml, 'resolution'))
end
return { most_basic_gui = most_basic_gui}
</syntaxhighlight>
|
<syntaxhighlight lang=wml>
[tooltip]
id="tooltip_large"
[/tooltip]
[helptip]
id="tooltip_large"
[/helptip]
[grid]
[row]
[column]
[image]
label="units/trolls/grunt.png"
[/image]
[/column]
[/row]
[/grid]

</syntaxhighlight>
|}

In the above file, we have just the single function to create our GUI, followed by a return command which makes our function most_basic_gui() available to the [[LuaAPI/wesnoth#wesnoth.require|wesnoth.require()]] function as most_basic_gui().

Our function creates a table containing the definition of a "dialog", and then passes that to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]]. It should be noted that gui.show_dialog does not provide synchronization, so if your GUI makes changes to the game state, you'll need to jump through some hoops or you'll break replays and multiplayer, but that's not something we need to care about at this point, so just be aware that you may need to deal with it in the future.

Our dialog definition at this point includes three parts. The first two are a tooltip and a helptip, which are required and define how tooltips (use id = "tooltip_large" or id = "tooltip" or id = "tooltip_transparent"), and helptips (rarely used, but must be included here, and yes their definitions are "tooltip" not "helptip") will look (as we will see later, this really should be definition = "tooltip", but in this case it's id = "tooltip"). The third part is a grid, which is basically a table, like in HTML or MySQL, with rows and columns. A grid always contains at least one row. A row contains at least one column (note that a column does NOT span rows, it is completely contained within a row). Inside a column is exactly one item, a cell which contains a [[GUIWidgetDefinitionWML|widget]], in this case we'll use an image (later we'll see what else we can put in a cell). Note that we don't actually define a cell in our code, it's just a term used to refer to the contents of a column.

The preshow function is optional. If included in the call to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]], it is run before the GUI is displayed. In this case, we include it to display the dialog we created with lua in WML format. Near the end, in comments, we show how you would call [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] if you chose to define your dialog using WML. Note that what is shown here is the WML equivalent of our lua dialogDefinition, and not the complete WML you would need to use if you were to configure your GUI layout in WML.

Note: if you should try out the above, you'll have to hit escape or enter to close the GUI. Uncomment the "click_dismiss" line, and the user will be able to close the GUI with a mouse click.

===Adding a little flavor===

{|
|You may have noticed our GUI is missing a header and a way to close it when we're done admiring our work. Here we add a new first row to our grid, while demonstrating a couple formatting options: a border to put some distance between our grid cell and its neighbor, and the "use_markup = true" option to enable Pango support in our text.

Our third row adds an OK button at the bottom. You can associate actions with buttons to do all kinds of things, but here we just exploit the default behaviour to close the GUI.

Of course, we'll also have to modify our return to support the new function, and update our menu item(s) accordingly.
|-
|[[File:Most basic gui2.png|center|thumb|Adding header and a footer]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui2()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
gui.show_dialog(dialogDefinition)
end
return { most_basic_gui = most_basic_gui, most_basic_gui2 = most_basic_gui2 }
</syntaxhighlight>

===And a bit more===
{|

|And now a minor, but important change. We want to add a new text field next to the image in the body of our GUI. Obviously, we want to add a new column, but this is more difficult than when we added new rows in the previous example. The problem is that all rows (at a given level) in a grid must contain the same number of columns. We can't have two columns in the row that constitutes the body of our GUI, but only one in the header and one in the footer. To solve this problem, we replace our image widget with a new grid, which can use as many columns as we like (as long as they are the same within each row of our new grid). This new grid contains a row with two columns, but that is okay because the new grid itself is placed in a single column, which matches our single column header and footer (ok button), keeping the rows balanced.
|-
|[[File:Most basic gui3.png|center|thumb|Rows with different numbers of columns]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui3()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column { -- This is the only column in this row,
-- to match the number of columns in
-- the rows of our header and footer
wml.tag.grid { -- A new grid, so we can use a different
-- number of columns
wml.tag.row {
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
},
wml.tag.column {
wml.tag.label {
label = "A troll"
}
}
}
}
}
},
wml.tag.row { -- A footer
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = "Ok"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

While we see here just the simplest of examples, you can many levels of grids in grids, rows with multiple columns some of which containing grids, etc, to build complicated dialogs to your liking.

==Containers==

===Stacked Widget===

TODO

===Listbox===
{|
| Now we'd like to add some more monsters. Obviously, we could just add more rows, but what if we won't know until runtime how many and which ones? We could break up the definition of our dialog and add new rows dynamically, it's just a table after all, but fortunately we have a widget which handles this for us, a listbox. A listbox is kind of like an array, a collection of similar objects where the number of items can vary. We will tell the GUI where we want the box, and what each entry in the box will look like, and then at runtime we can add entries to the box.
|-
| [[File:Gui with listbox.png|center|thumb|Listbox with three items]]

<syntaxhighlight lang=lua>
local function gui_with_listbox()
local monsters = {
{ image = "units/trolls/grunt.png",
string = "A troll" },
{ image = "units/monsters/cuttlefish.png",
string = "A cuttlefish" },
{ image = "units/monsters/yeti.png",
string = "A yeti" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
}

local listboxDefinition = wml.tag.listbox { id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
listboxDefinition
}
},
wml.tag.row {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_label.label = monster.string
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We begin by creating a simple table which represents the data which will be presented in our listbox. In most cases, we probably wouldn't create that monster table here, but we need it for our example.

The variable listbox_id gives us an identifier for our listbox so we can reference it when we need to. We don't really need to use a variable here, it's just convenient.

We define the structure for the elements in our listbox, stored in listboxItem. Note that we've replaced the actual data with identifiers (e.g. 'units/trolls/grunt.png' becomes 'id = "monster_image"), since each element may have different data.

We define the listbox itself, specifying the identifier, and the definition of our listbox element (which looks a lot like a grid). The cell inside the column contains a variable which is just the listbox element definition we created above; it's not necessary to do this, we could have used one big table, but it's easier to read this way (IMO).

We replace the hardcoded data in our GUI body with our new listbox definition, again using a variable to make it easier to read.

We create a function, often called preshow(), which will be called for us as part of the drawing the GUI (see the new optional argument in [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] -- there's also an optional postshow(), but we don't need it here). This is where we pull the data from our example table into the listbox. We create a listbox variable associated with the listbox, identified by the listbox_id we assigned earlier, inside the dialog which gui.show_dialog() passes to preshow(). Then we iterate through our data table, using each entry from that table to populate a listbox item.

Let's look at that last action a little more closely using an example.

<syntaxhighlight lang=lua>
listbox[i].monster_image.label = monster.image
</syntaxhighlight>

Which we can read as "In listbox element i of our listbox, for the image with identifier monster_image which we defined in our listboxItem, use the data from the corresponding index i in our example data table" (you don't see the index i for the monsters table here, but remember we're iterating using ipairs, we could have just as easily used listbox[i].monster_image.label = monsters[i].image). If you were to step through all of the variable substitutions, you'd see that for i=1, our dialogDefinition is basically the same thing as it was in the earlier examples, just supplied from a table instead of hardcoded (note that you can hardcode entries in a listbox in your dialog definition using the [list_data] tag, aka wml.tag.list_data, which we do not demonstrate here).

You will probably notice that our data does not line up nicely in the GUI. We will fix that later. We'll also demonstrate how the user can select an item in a listbox, and how you can identify which item that was using the selected_index variable of the listbox.

===Tree View===
====Simple Tree View====
{|
| You may have noticed that clicking on a listbox item in our listbox caused it to be highlighted with a box around the contents. This is because the items in a listbox are selectable. This will be useful when we want to add actions, but it looks a bit odd if we just want to present a list of data.

Also, most of the data had to be formatted the same for each item in the listbox. We could, perhaps, include custom markup in our labels, but the actual layout, like the number of columns per row, had to be the same for every item.

Another way to present a list of data is the tree view. Since a tree view supports multiple data types, we may need to create multiple definitions for the elements in our list. These are known as nodes. It will also be necessary to explicitly define which node to use for each element when we populate our tree view.
|-
| [[File:Basic tree view.png|center|thumb|Tree_views can hold multiple data types (only trolls have names here)]]
|}
<syntaxhighlight lang=lua line>
local function basic_tree_view()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", type = "Seamonsters" },
{ image = "units/monsters/yeti.png", label = "A yeti",
type = "Coolers" }
}

local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "trolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name",
linked_group = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
},
wml.tag.node {
id = "nottrolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "monster_name",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_image",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_label",
fixed_width = true
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_tv:add_item_of_type("trolls_node")
dialog.monsters_tv[i].monster_name.label = monster.name -- only trolls have a name
else
dialog.monsters_tv:add_item_of_type("nottrolls_node")
end
-- All of our monsters have an image and a label
dialog.monsters_tv[i].monster_image.label = monster.image
dialog.monsters_tv[i].monster_label.label = monster.label
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We have expanded our list of monsters to include three types of trolls. We have also given each troll a name. This is of course a rather simplistic example, we could have simply given each monster that is not a troll an empty name, but it as presented here our approach serves the purpose of demonstrating how we deal with multiple data types. Our new tree view contains a node for each type of data we will present. In preshow, we explicitly define each element in our list using add_item_of_type(), and populate the item accordingly. [Note: in our listbox example, we could have used add_item() to add items to the listbox, but chose not to since that section was already introducing a number of new concepts. But here, since we have multiple types of items we need to be able to specify the type of the item when we add one, hence we need to use add_item_of_type()].

You may also note the addition of a few linked_group lines. We'll cover linked groups in more detail later, but as used here they instruct the GUI that each column using the same node type needs to be aligned with the others. For example, all of our trolls line up nicely.

====Building a Tree====
{|
| colspan="2" |At this point, one may wonder about the name "tree view", since what he have seen doesn't look much like a tree. To make a tree-like structure, we'll demonstrate adding children to nodes. At the top level our (upside-down) tree will have two nodes, one for trolls and one for everything else. A toggle_button (a type of button which changes states when you push it) will allow us to expand the trolls node to expose its children, which are themselves nodes, though they only contain a label at this point.
|-
| [[File:Basic tree view2a.png|center|thumb|Tree_view with Trolls folded]] || [[File:Basic tree view2b.png|center|thumb|Tree_view with Trolls unfolded]]
|}
<syntaxhighlight lang=lua line>
local function building_a_tree()
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
}
},
wml.tag.column {
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Show me the " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
-- You can refer to an object by its position

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[1].race_label.label = "Trolls"
-- dialog.monsters_tv[1].race_button.on_modified =
-- function()dialog.monsters_tv[1].unfolded =
-- dialog.monsters_tv[1].race_button.selected end

-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][1].monster_type.label = "Whelp"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][2].monster_type.label = "Shaman"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][3].monster_type.label = "Troll"

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[2].race_label.label = "Other scary things"
-- dialog.monsters_tv[2].race_button.visible = "hidden"

-- ... or you can refer to that object using the return value
-- from add_item_of_type
local troll_node = dialog.monsters_tv:add_item_of_type("race_node")
troll_node.race_label.label = "Trolls"
troll_node.race_button.on_modified =
function()
troll_node.unfolded = troll_node.race_button.selected
end
local item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Whelp"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Shaman"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Troll"

local not_troll_node =
dialog.monsters_tv:add_item_of_type("race_node")
not_troll_node.race_label.label = "Other scary things"
not_troll_node.race_button.visible = "hidden"

end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We define two nodes in our tree, a race_node for the top level, and a details_node for the children of a race_node. The rest of the interesting bits are in preshow().

We demonstrate two different ways of creating and accessing items, the first (commented out) just using the order in which they are created, while in the second we capture the result of add_item_of_type() in a variable we can use to refer to the newly defined object. The first method is shown primarily to demonstrate the structure of the resulting objects. The second method is perhaps easier to follow, and is almost necessary when you start doing things like dynamically deleting nodes, so it is in most cases a better practice (of course, you probably won't want to use the same variable for each node like we did, and perhaps not one local to the preview function).

We add a node, label it "Trolls", and add a callback to the button such that the children of the node will be visible (the node is "unfolded", a boolean value which defaults to false) when the button is checked (selected == true). Then we add three "details_node" nodes as children of this node.

Our second node, "Other scary things" will remain empty for now, so we'll set the visible attribute on its button to "hidden" (which is like false, but with hidden the widget still takes up space).

{|
| This example is rather ugly, both in the hardwired code and the appearance of the resulting GUI, but it addresses a couple important aspects of how tree views work and how we might use them. Let's clean it up a bit. We'll add an indentation_step_size to the tree view, along with a spacer and [[#Alignment|horizontal_alignment]] to our details node, to make the labels line up nicely, and change the button [[#Definitions|definition]] to replace the checkbox with something that looks like it belongs there. We will look at methods for handling layout in more depth [[#Appearance|later]].
|-
| [[File:Basic tree view2c.png|center|thumb|Our tree_view with proper alignment]]

<syntaxhighlight lang=lua>
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
indentation_step_size = 20,
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
definition = "tree_view_node"
}
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.spacer { width = 40 }
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}

</syntaxhighlight>

===Multi_page===
====Simple Multi_page====
{|
|-
Like a tree_view, a multi_page is a heterogeneous container which is dynamically populated, however, while a multi_page contains multiple elements (pages), only one page is displayed at any one time. Its purpose is perhaps best described by a couple of examples.
|-
[[File:Basic multipage.png|center|thumb|Multi_page showing active page]]
|}
<syntaxhighlight lang=lua>
local function basic_multipage()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll",
name = _"Bob", type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp",
name = "Junior", type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman",
name = _"Alice", type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish",
type = "Seamonsters" },
{ image = "units/monsters/yeti.png",
label = "A yeti",
type = "Coolers" }
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
multi_page
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}

local function preshow(dialog) -- Prepare the GUI before display
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_label.label = monster.label
end
--dialog.monsters_mp.selected_index = 5
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

As you can see, the code for our basic multi_page GUI looks a lot like our basic tree_view GUI. The difference is what is displayed. While both the tree_view and the multi_page containers contain five items, with the multi_page, only the first one is displayed. More specifically, only the page associated with the selected_index attribute of the multi_page object, which defaults to 1, is displayed. If we were to uncomment the last line in preshow(), we would still see only one item, but it would be the fifth one we allocated. It's nice to know all our pages are in there somewhere, but this example is pretty useless. What we need is a way to select which page we want to see from within our GUI.

====A More Useful Multi_page====

{|
| colspan="2" | To demonstrate the usefulness of a multi_page, and highlight its difference from a tree_view, we'll add a listbox to allow us to select the page to view. We'll also need to add a little action to our GUI.
|-
| style="align:centered" |[[File:More useful multipage.png|center|thumb|User selected Troll]] || [[File:More useful multipage2.png|center|thumb|User selected Cuttlefish]]
|}

<syntaxhighlight lang=lua>
local function more_useful_multi_page()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
race = "Trolls", tip = "Your uncle" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
race = "Trolls", tip = "Your nephew" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
race = "Trolls", tip = "Your auntie" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", race = "Seamonsters",
tip = "Not a fish" },
{ image = "units/monsters/yeti.png",
label = "A yeti", race = "Coolers",
tip = "ROAR!" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
}
}
}

local listboxDefinition = wml.tag.listbox {
id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
},
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
listboxDefinition
},
wml.tag.column {
wml.tag.spacer {
width = 30
}
},
wml.tag.column {
multi_page
},
}
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_image.tooltip = monster.tip
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_image.tooltip = monster.tip
dialog.monsters_mp[i].monster_label.label = monster.label
end
local function switch_page()
dialog.monsters_mp.selected_index = listbox.selected_index
end
listbox.on_modified = switch_page
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

Most of this should look pretty familiar. We've simply taken the previous example and added a second column to our GUI using code from an earlier example to add a listbox. In addition, we altered the page layout slightly, and added a spacer column in the dialog definition to approve the appearance.

The interesting stuff is in preshow(). Again we've merged in some listbox code from an earlier example, but we've also created a new local function switch_page(), which simply sets the selected_index attribute of our multi_page to the same as that of our listbox, and then we've configured the listbox.on_modified callback to call switch_page(). Now when the user selects an item in the listbox (updating listbox.selected_index and triggering listbox.on_modified), dialog.monsters_mp.selected_index is updated accordingly and therefore the visible page changes to the one associated with the selected unit.

Also note in preshow() we've added a new child to our monster_image identifier for both the listbox and the multi_page, a tooltip. When the user hovers the mouse over the image of one of our monsters, they'll see a popup message which we've added to our monster table. Try changing '''wml.tag.tooltip { id = "tooltip_large" }''' to '''wml.tag.tooltip { id = "tooltip }''' in the dialogDefinition to see a different tooltip style.

==Actions Have Consequences==

So far, our GUIs have only displayed some information on the screen, but at some point we're probably going to want to use a GUI to get input from the user. In this section we will look at return values that can be assigned to a widget based upon its state, and callbacks, which are functions invoked when something happens with a widget. As we will see, a button is a good example, as it can return a value or take an action, or both, when pressed. Earlier we saw how the selected_index attribute of some widgets, such as the listbox, can also be used as a sort of return value.

===Buttons===
{|
| colspan=2 | In this example, we'll create a couple buttons which provide the user a choice, use a handy confirmation popup to confirm that choice, and demonstrate how we get the results back where we can put them to use.
|-
| [[File:Basic return value.png|center|thumb|There can be only one]] || [[File:Basic return value_confirm.png|center|thumb|The user selected Alice, let's confirm this critical choice]]
|}

<syntaxhighlight lang=lua>
local function basic_return_value()

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "leader_lg",
fixed_height = true,
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" ..
_"Which unit shall lead your army?" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Alice" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/elves-wood/sylph.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 1
}
}
},
}
},
wml.tag.column {
wml.tag.spacer { width = 20 }
},
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Bob" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/human-loyalists/marshal.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 2
}
}
}
}
}
}
}
}
}
}
}
local user_chose = gui.show_dialog(dialogDefinition)
local leader
if user_chose == -1 then -- User closed the dialog by hitting the Enter key
leader = nil
end
if user_chose == -2 then -- User closed the dialog by hitting the Escape key
leader = nil
end

if user_chose == 1 then
leader = "Alice"
end
if user_chose == 2 then
leader = "Bob"
end

local confirmed_leader_choice

if leader ~= nil then
local query = _"You want " .. leader .. _" as your leader?"
confirmed_leader_choice = gui.confirm(query)
end

if confirmed_leader_choice then
wesnoth.message("Great!")
else
wesnoth.message("Fine, lead them yourself!")
end
end
</syntaxhighlight>

Here we've added a couple buttons, and assigned each of them a return value. When the user selects one of these buttons, the GUI is closed and the value of return_value is returned from gui.show_dialog(). We then use [https://wiki.wesnoth.org/LuaAPI/gui#gui.show_prompt gui.confirm()] which provides a very simple Yes/No popup and returns true or false, respectively. Other useful functions can be found on that page which provide handy alternatives to creating your own GUI for other simple user inputs.

The use of return_value is rather limited, as it only returns integers and can't be used with containers like listboxes. In more complex cases we'll need to turn to callback functions which are invoked when something happens to a widget, like clicking a button or a widget's value changing. Earlier, we saw an example of [[LuaAPI/types/widget#on_modified|widget.on_modified()]]. More examples of callbacks can be found at [[LuaAPI/types/widget#on_modified|that link]].

===Slider and Textbox===
{|
| Here we see a couple methods of getting more dynamic input from the user, a slider and a textbox presented in one silly example.
|-
| [[File:Slider and textbox.png|center|thumb|Two ways of getting input from the user]]
|}

<syntaxhighlight lang=lua>
function scrollbar_and_textbox()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = _"How much gold will you pay for this old rusty sword?"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.slider {
id = "gold_sl",
minimum_value = 0,
maximum_value =
wesnoth.sides[wesnoth.current.side].gold,
value = math.floor(
wesnoth.sides[wesnoth.current.side].gold/2)
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.text_box {
id = "gold_tb",
--hint_text = _ "Enter gold here",
--hint_image = "images/gold_pile.png",
label = tostring(math.floor(
wesnoth.sides[wesnoth.current.side].gold/2))
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
local function show_input()
wesnoth.interface.add_chat_message(_"You chose " ..
dialog.gold_sl.value .. _" with the slider")
wesnoth.interface.add_chat_message(_"You entered " ..
tostring(dialog.gold_tb.text) .. _" in the text_box")
end
-- this is a button, so we use on_button_click, not on_left_click
dialog.ok.on_button_click = show_input

dialog.gold_sl.on_modified = function()
dialog.gold_tb.text = tostring(dialog.gold_sl.value)
end
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We create a slider, with a range from 0 to the amount of gold possessed by the current side and an initial value in the middle, and a text box with the same initial value. We assign a function to our OK button which simply reports on the values provided by the user. For no reason whatsoever, we add a callback such that when the user adjusts the slider the value in the textbox is update to match the slider.

Note that the textbox returns text, even though it looks like we're expecting the user to input a natural number. Remember to validate those inputs.

You can use text_hint to place a caption in the box that will help the user understand what to enter in the box, and possibly an image as well. For example, in the search box in the recall menu uses '''hint_text = _ "Search", hint_image = "icons/action/zoomdefault_25.png~FL(horiz)"'''. Of course, you can't have a hint and a label in the same text_box at the same time, so in our example we've only included them as comments.

There is also a widget called a spinner, which is kind of like the combination of a text_box and a slider. As of the release of 1.18, it appears to be unfinished so the strange syntax needed to make it work is probably not the best thing to document, and we will omit it for now.

==Appearance==

'''This section needs help'''

===Borders===

Borders allow you to force unused space around a column, for example so that your widgets don't runtogether. You can specify the border to be one or more of top, bottom, left, right, or all. The border_size sets the amount of padding, in pixels.

<syntaxhighlight lang=lua>
wml.tag.column{
border = "left, right"
border_size = 25
}
</syntaxhighlight>

===Alignment===
{|
| colspan=2 |By default, the GUI will usually center widgets in their cells, which is not always what we want. In this example, we use horizontal_alignment to move widgets around a little.

In more complex cases, it may be useful to add [[GUIWidgetDefinitionWML#Spacer|spacers]] to help force alignment, or use linked_groups to force consistent alignment for objects within a grid.
|-
| [[File:Gui tutorial alignment without.png|center|thumb|Default alignment]] ||[[File:Gui tutorial alignment with.png|center|thumb|Showing off some alignment options]]
|}
<syntaxhighlight lang=lua>
local function basic_alignment()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = "Ralph"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "right",
wml.tag.label {
label = "Sam"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/troll-hero-attack-se-4.png" -- 122x102
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "left",
wml.tag.label {
label = "Jr"
}
},
wml.tag.column {
horizontal_alignment = "right",
wml.tag.image {
label = "units/trolls/whelp.png" -- 72x72
}
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

The screenshots show the output of this example with and without the horizontal_alignment lines included above.

A label allows you to set the text_alignment field (e.g. text_alignment = "left"). Note, however, this only aligns the text within the label. The label itself will probably be centered in the column, giving the false appearance that your text alignment is not working.

===Growth===

To keep your dialog nicely balanced, the GUI2 engine may need to grow rows and/or columns. You can control which columns, for example, grow and which do not, by setting some with grow_factor = 1, and others with grow_factor = 0 (do not grow). While grow factors of 0 and 1 are the most common, you can use other values to adjust the relative growth if you really need to, see [[GUILayout]] for the gory details.

It it sometimes useful to include a column with a [spacer] and a grow_factor (often the only column with grow_factor != 0) whose sole purpose is to keep your GUI aligned nicely as the layout engine does its evil.

To force a column to stretch to fit available space, use horizontal_grow = true. Note that horizontal_grow is not compatible with horizontal_alignment. There is also a vertical_grow parameter.

If you need to see every little detail about the layout process, start wesnoth with --log-debug=gui/layout. Good luck with that.

===Definitions===
Many widgets can be configured to have to a different appearance, for example in our tree_view example we changed the definition of a toggle_button from the default of a checkbox by setting definition = "tree_view_node". This option was found by looking at the id of a toggle_button_definition in .../data/gui/widget/toggle_button_tree_view_node.cfg:

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib
###
### Definition of a toggle button to be used in a tree view as node fold/unfold indicator
###
[toggle_button_definition]
id = "tree_view_node" # <--- we can use 'definition = "tree_view_node"' in a [toggle_button] to select this definition
description = "Fold/unfold status indicator of a tree view node."
</syntaxhighlight>

{|
|There are many other definitions for buttons and other widget types in that directory. It would be nice to have a list (linked here), but for now you'll just have to look around.

We can even create our own custom definitions using [[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition()]]. In this example, we copy from .../data/gui/widget/toggle_button_tree_view_node.cfg with a slight change so that our button turns red ( '''~BLEND(255,0,0,1)''' ) when focused.

In this example, we will use wesnoth.wml_actions to create the WML tag [add_widget_def_demo].

Note the first line, a common convention for creating an alias for wml.tag.
|-
|[[File:Gui tutorial custom widget.png|center|thumb|Different definition of buttons, including one of our own (right)]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag -- save ourselves some typing
function wesnoth.wml_actions.add_widget_def_demo()
local definition = {
id = "tree_view_node_custom",
description = "Fold/unfold status indicator of a tree view node (MODIFIED).",
T.resolution {
min_width = 25,
min_height = 19,
default_width = 25,
default_height = 19,
max_width = 25,
max_height = 19,
-- Unselected - note there's no tags for unselected/selected, that's simply determined by the order
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/fold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/fold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/fold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
-- Selected
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/unfold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
}
}
gui.add_widget_definition("toggle_button", "tree_view_node_custom", definition)

local dialogDefinition = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid {
T.row {
T.column {
T.tag.toggle_button {
definition = "default"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node_custom"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end

</syntaxhighlight>

See [[GUIWidgetDefinitionWML]] for more details on widget definitions.

You can also give the whole dialog a definition, like definition = "tooltip_large". There is no gui.add_window_definition(), however a window is technically a type of widget so it may be possible to create your own window definitions (please update this if you do).

===Panels===

===Canvases===
Part of panels? Sort of?

A canvas is a surface you can draw on. A dialog has them, as does a panel, and for these canvas 1 refers to the background, while canvas 2 refers to the foreground. Other widgets may have canvases that may have other meanings, or no canvases at all. See more at [[LuaAPI/gui/widget#set_canvas]].

Here's a fun little trick. Set your dialog background to be transparent:
<syntaxhighlight lang=lua>
local function preshow(dialog)
dialog:set_canvas(1, { } )
end
</syntaxhighlight>

Or, if you want an opaque GUI background with the screen behind it blurred like what you see behind the text of a [message], you can set your window definition to "message":
<syntaxhighlight lang=lua>
...
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
definition = "message",
...
</syntaxhighlight>

{|
|Here we take our [[#Progress Bar|progress bar]], and add a text overlay.

Note: either using text on a canvas is rather limited, or I just couldn't figure it out. For example, I could not get the text size any smaller, and any attempts to do so simply resulted in very blocky text. And the spaces were necessary so that the text wasn't stretched out. I also find it surprising that the progress bar does not have this feature inherently. So it's not a great example, but it should be enough to get you started using canvases. Be sure to visit the [[LuaAPI/gui/widget#set_canvas|link]] mentioned above for more options.
|-
|[[File:Gui tutorial canvas text.png|center|thumb|A progress bar in the background, with text in the foreground]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar_with_overlay()
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.grid {
T.row {
T.column {
T.panel { id = "panel",
T.grid {
T.row {
T.column {
T.button { id = "button",
label =_ "Press me"}
},
T.column {
T.progress_bar { id = "progress" }
},
T.column {
T.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
dialog.panel:set_canvas(2, { T.text { text_alignment = "center", font_size = 48,
text_markup = true, text = " " ..
dialog.progress.percentage .. "% " } } )
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

You may notice we added a panel and placed our text on the foreground canvas(2) on it, since the progress_bar itself does not support canvases.

===Placement===

You may have noticed that all of our dialogs are centered on the screen. This is the default. You can override this and place the dialog wherever you like by setting automatic_placement = false, along with x, y, width, and height at the top level of your dialog definition (next to tooltip =, etc).

'''This part about placement needs review'''
If you prefer, you may replace x and/or y with horizontal_placement and vertical_placement, such as horizontal_placement = "left". You can even set the placement values using WFL, for example horizontal_placement = "(gamemap_width / 3)" -- see [[#Using WFL with GUI2|Using WFL with GUI2]].

==Miscellaneous==

TODO: This stuff doesn't belong in a tutorial. It's worth documenting, but not here. Better to save these here for now than keep them on my laptop.

===Progress Bar===
{|
|A progress_bar is a graphical representation of a percent. In this example, we present the user with a puzzle. They must hit the button repeatedly before they can close the GUI. A progress_bar displays their current progress toward completion.
|-
|[[File:Gui tutorial progress bar.png|center|thumb|upright=2]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.button { id = "button",
label =_ "Press me"
}
},
wml.tag.column {
wml.tag.progress_bar { id = "progress" }
},
wml.tag.column {
wml.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end

gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

===Unit Preview Pane===

{|
|A unit_preview_pane takes a unit (or a unit type), and presents a graphical representation of the unit and its more important attributes, along with tooltips for additional details, in the same way that the recall menu does. Here we see an example of a unit which has picked up some items, including a weapon, which are affecting its stats.
|-
|[[File:Gui tutorial unit preview pane.png|center|thumb]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag

function wesnoth.wml_actions.recall_from_variable(cfg)
local from_array = cfg.from or wml.error(
"[recall_from_variable]: missing required from= ")
local to_var = cfg.to or wml.error(
"[recall_from_variable]: missing required to= ")
local unit_list = wml.array_access.get(from_array) or wml.error(
string.format("[recall_from_variable]: failed to fetch wml array %s",from_array))

local listboxItem = T.grid {
T.row {
T.column {
T.label { id = "available_unit",
linked_group = "available_unit"
}
}
}
}

local listbox_id = "available_units"
local listboxDefinition = T.listbox { id = listbox_id,
T.list_definition {
T.row {
T.column {
T.toggle_panel { listboxItem }
}
}
}
}
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.linked_group { id = "available_unit", fixed_width = true },
T.grid {
T.row { -- header
T.column {
T.grid {
T.row {
T.column {
border = "bottom",
border_size = 10,
T.label {
use_markup = true,
label = ""
.. _"Select unit to recall" .. ""
}
}
}
}
}
},
T.row { -- Body
T.column {
T.grid {
T.row {
T.column {
border = "right",
border_size = 40,
listboxDefinition
},
T.column {
T.unit_preview_pane { id = "unit_preview" }
}
}
}
}
},
T.row { -- Footer
T.column {
T.grid {
T.row {
T.column {
T.spacer { width = 400 }
},
T.column {
border = "top,right",
border_size = 10,
T.button { id = "ok",
label = _"OK"
}
}
}
}
}
}
}
}

local picked = 1

local function preshow(dialog)
local listbox = dialog[listbox_id]
for i,unit in ipairs(unit_list) do
listbox[i].available_unit.label = unit.name .. "(" ..
unit.language_name .. ")"
end
local function draw_unit()
wesnoth.units.to_recall(unit_list[listbox.selected_index])
local tmp = wesnoth.units.find_on_recall{ id =
unit_list[listbox.selected_index].id }[1]
dialog.unit_preview.unit = tmp
wesnoth.units.extract(tmp)
picked = listbox.selected_index
end
draw_unit()
listbox.on_modified = draw_unit
end

gui.show_dialog(dialogDefinition,preshow)

wml.variables[to_var] = picked - 1
end

</syntaxhighlight>

This should all be pretty self evident by now. We are provided with an array of stored units (from [store_unit] in WML). We create a listbox populated with units and we use the selected_index to determine which element in the table to send to unit_preview_pane. Since our input is an array of unit data, not actual units, we use [[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] to take the definition of one from our array and place it on the recall list (turning it into an actual unit), [[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] to fetch that unit in a form that the unit_preview_panel understands, and finally [[wesnoth.units.extract|wesnoth.units.extract]] to remove the unit from the recall list when we are done with it.

And of course we subtract one from the selected_index when we return our choice to WML, since lua arrays count from 1 and WML from 0.

The unit_preview_pane will also accept a unit_type instead of a specific unit.

==Appendix==

===Explore Your Options===

We've seen a lot of options that can be set to modify the behaviour of our dialogs, some on columns, some on widgets, etc. These are in the process of being documented [[GUIWidgetInstanceWML|here]], but if you would like to go straight to the source, the data Wesnoth uses to validate your configuration can be found in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui data/schema/gui] under your install directory.

Let's look at a scroll_label, for example. A scroll_label is a widget, so we look in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/widget_instances.cfg widget_instances.cfg] and find the following. Here we can see five parameters we can provide to our scroll_label (in addition to the ones available to all widgets, like id and definition, see the entry super=... which refers you to the widget_instance in the file [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/generic.cfg data/schema/gui/generic.cfg]), along with their types and default values. For example, we could set "link_aware = true", and if we do not we can assume that link_aware will be false. While this does not explain what these parameters do, the information provided in the schema directory is often helpful nonetheless.

<syntaxhighlight lang=wml>
[tag]
name="scroll_label"
min="0"
max="infinite"
super="$generic/widget_instance"
{DEFAULT_KEY "horizontal_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "vertical_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "wrap" bool true}
{DEFAULT_KEY "text_alignment" f_h_align "left"}
{DEFAULT_KEY "link_aware" bool false}
[/tag]
</syntaxhighlight>

We see that our scrollbars are of type scrollbar_mode. It would probably help if we knew what values are available to the scrollbar_mode. In [https://github.com/wesnoth/wesnoth/tree/master/data/schema/types/gui.cfg data/schema/types/gui.cfg] we find this:

<syntaxhighlight lang=wml>
[type]
name=scrollbar_mode
value="always|never|auto|initial_auto"
[/type]
</syntaxhighlight>

The variable types found in the schema files are described at [[GUIVariable]].

Note: The keys in the schema file correspond to the attributes used when configuring your widgets. They will not always align perfectly with keys used by the Lua API. For example, the slider uses maximum_value in its configuration, and max_value when using the Lua API:

<syntaxhighlight lang=wml>
[slider]
id="my_slider"
maximum_value = 100
[/slider]
</syntaxhighlight>

<syntaxhighlight lang=lua>
dialog.my_slider.max_value = 90
</syntaxhighlight>

===Using WFL with GUI2===

If you look at the variable type descriptions at [[GUIVariable]] you may notice that many of them start with "f_" and have "or formula" in the description. This means that you can use [[Wesnoth_Formula_Language|Wesnoth Formula Language (WFL)]] formulas in these fields, with certain variables made available to you (which variables and what they mean can be challenging to ascertain, but you can generally figure it out by example).

Looking at [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/window.cfg data/schema/gui/window.cfg] we see that 'height' has type f_unsigned, which tells us that height is an unsigned integer, and that we can use a WFL formula to define it in a window_definition. In [https://github.com/wesnoth/wesnoth/tree/master/data/gui/themes/default/window/wml_message.cfg data/gui/window/wml_message.cfg] (data/gui/themes/default/window/wml_message.cfg starting around 1.19.2), we find the line '''height = "(screen_height - 30)"'''. This does exactly what it looks like, it sets the height of our window to 30 pixels less than the height of the screen.

===Useful Links===

[[LuaAPI/gui|LuaAPI/gui - Mostly about opening windows]] 
[[LuaAPI/types/widget|LuaAPI/types/widget - Widget attributes and callbacks]] 
[https://wiki.wesnoth.org/Category:GUI_WML_Reference GUI_WML_Reference] 
[https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui .../data/schema/gui/*.cfg] - Lists of valid options for various GUI objects 
[https://devdocs.wesnoth.org/layout_algorithm.html Layout Algorithm] - For windows, at least

===Credits===

The basic framework that composes the initial examples was lifted from LotI. It's a great place to find well written examples, but some of it is complex enough to be a little overwhelming when getting started.

Many examples, particularly tree view and multipage, are heavily derived from the World Conquest multiplayer campaign.

LuaAPI/gui/widget

2024-09-21T17:59:12Z

White haired uncle: removed reference to negative index to add_item_of_type (has been removed, never worked anyway)

The '''gui.widget''' module contains functions for managing widgets in custom GUI2 dialogs. Since these functions take a [[LuaAPI/types/widget|widget userdata]] as the first parameter, they can only be used in the preshow or postshow of a GUI2 dialog (directly or indirectly). However, the table is available at all times, and additional methods can be installed here for unusual needs.

'''Note:''' The '''gui.widget.set_callback''' is a compatibility wrapper and is unsupported. It may be removed without warning. Callbacks should be bound by assigning the appropriate callback key on the widget.

=== focus ===

* '''gui.widget.focus'''(''widget'')
* ''widget'':'''focus'''()

Switches the keyboard focus to the widget. This is often useful for dialogs containing a central listbox, so that it can be controlled with the keyboard as soon as it is displayed.

=== set_canvas ===

* '''gui.widget.set_canvas'''(''widget'', ''layer index'', ''content'')
* ''widget'':'''set_canvas'''(''layer index'', ''content'')

Sets the WML passed as the second argument as the canvas content (index given by the first argument) of the widget. The content of the WML table depends on which shape is used:

* [[GUICanvasWML#Circle|Circle]]
* [[GUICanvasWML#Image|Image]]
* [[GUICanvasWML#Line|Line]]
* [[GUICanvasWML#Bounded_Shape|common attributes of rectangles, round rectangles and text]]
* [[GUICanvasWML#Rectangle|Rectangle]]
* [[GUICanvasWML#Rounded_Rectangle|Rounded Rectangle]]
* [[GUICanvasWML#Text|Text]]

<syntaxhighlight lang=lua>
-- draw two rectangles in the upper-left corner of the window (assume dialog is the window widget)
dialog:set_canvas(2, {
wml.tag.rectangle { x = 20, y = 20, w = 20, h = 20, fill_color= "0,0,255,255" },
wml.tag.rectangle { x = 30, y = 30, w = 20, h = 20, fill_color = "255,0,0,255" }
})
</syntaxhighlight>

The meaning of the canvas index depends on the chosen widget. It may be the disabled / enabled states of the widget, or its background / foreground planes, or... For instance, overwriting canvas 1 of the window with an empty canvas causes the window to become transparent.

=== add_item ===

* '''gui.widget.add_item'''(''widget'', [''position'']) → ''the new item'', ''position''
* ''widget'':'''add_item'''([''position'']) → ''the new item'', ''position''

Add an item to a container widget, for example a listbox. Returns the created item as a [[LuaAPI/types/widget|widget userdata]].

=== add_item_of_type ===

* '''gui.widget.add_item_of_type'''(''widget'', ''category'', [''position'']) → ''the new item'', ''position''
* ''widget'':'''add_item_of_type'''(''category'', [''position'']) → ''the new item'', ''position''

Add an item to a widget which is a heterogeneous container of different types of widgets, in particular multi_pages and treeviews.

=== remove_items_at ===

* '''gui.widget.remove_items_at'''(''widget'', ''position'', ''count'')
* ''widget'':'''remove_items_at'''(''position'', ''count'')

Removes one or more elements of a container type widget (like treeviews), starting at the given index. If 0 is passed as the count, all elements from that point to the end are removed. Otherwise, the specified number of elements are removed.

=== find ===

* '''gui.widget.find'''(''root widget'', ...)
* ''widget'':'''find'''(...)

Finds a child widget of the widget of the given path. For example, here it searches for the widget with the id 'preview_panel' of the second item of the widget with the id 'unit_list':

<syntaxhighlight lang=lua>
dialog:find('unit_list', 2, 'preview_panel')
</syntaxhighlight>

This is more or less equivalent to the following:

<syntaxhighlight lang=lua>
dialog.unit_list[2].preview_panel
</syntaxhighlight>

However, if the path comes from a variable, the functional form may be more convenient:

<syntaxhighlight lang=lua>
dialog:find(table.unpack(path))
</syntaxhighlight>

=== close ===

* '''gui.widget.close'''(''dialog'')
* ''widget'':'''close'''()

Closes the dialog.

[[Category:Lua Reference]]

LuaAPI/gui/widget

2024-09-21T17:58:40Z

White haired uncle: removed reference to negative index to add_item (has been removed, never worked anyway)

The '''gui.widget''' module contains functions for managing widgets in custom GUI2 dialogs. Since these functions take a [[LuaAPI/types/widget|widget userdata]] as the first parameter, they can only be used in the preshow or postshow of a GUI2 dialog (directly or indirectly). However, the table is available at all times, and additional methods can be installed here for unusual needs.

'''Note:''' The '''gui.widget.set_callback''' is a compatibility wrapper and is unsupported. It may be removed without warning. Callbacks should be bound by assigning the appropriate callback key on the widget.

=== focus ===

* '''gui.widget.focus'''(''widget'')
* ''widget'':'''focus'''()

Switches the keyboard focus to the widget. This is often useful for dialogs containing a central listbox, so that it can be controlled with the keyboard as soon as it is displayed.

=== set_canvas ===

* '''gui.widget.set_canvas'''(''widget'', ''layer index'', ''content'')
* ''widget'':'''set_canvas'''(''layer index'', ''content'')

Sets the WML passed as the second argument as the canvas content (index given by the first argument) of the widget. The content of the WML table depends on which shape is used:

* [[GUICanvasWML#Circle|Circle]]
* [[GUICanvasWML#Image|Image]]
* [[GUICanvasWML#Line|Line]]
* [[GUICanvasWML#Bounded_Shape|common attributes of rectangles, round rectangles and text]]
* [[GUICanvasWML#Rectangle|Rectangle]]
* [[GUICanvasWML#Rounded_Rectangle|Rounded Rectangle]]
* [[GUICanvasWML#Text|Text]]

<syntaxhighlight lang=lua>
-- draw two rectangles in the upper-left corner of the window (assume dialog is the window widget)
dialog:set_canvas(2, {
wml.tag.rectangle { x = 20, y = 20, w = 20, h = 20, fill_color= "0,0,255,255" },
wml.tag.rectangle { x = 30, y = 30, w = 20, h = 20, fill_color = "255,0,0,255" }
})
</syntaxhighlight>

The meaning of the canvas index depends on the chosen widget. It may be the disabled / enabled states of the widget, or its background / foreground planes, or... For instance, overwriting canvas 1 of the window with an empty canvas causes the window to become transparent.

=== add_item ===

* '''gui.widget.add_item'''(''widget'', [''position'']) → ''the new item'', ''position''
* ''widget'':'''add_item'''([''position'']) → ''the new item'', ''position''

Add an item to a container widget, for example a listbox. Returns the created item as a [[LuaAPI/types/widget|widget userdata]].

=== add_item_of_type ===

* '''gui.widget.add_item_of_type'''(''widget'', ''category'', [''position'']) → ''the new item'', ''position''
* ''widget'':'''add_item_of_type'''(''category'', [''position'']) → ''the new item'', ''position''

Add an item to a widget which is a heterogeneous container of different types of widgets, in particular multi_pages and treeviews. You can pass a negative position to count from the end of the container, but the returned position is always positive.

=== remove_items_at ===

* '''gui.widget.remove_items_at'''(''widget'', ''position'', ''count'')
* ''widget'':'''remove_items_at'''(''position'', ''count'')

Removes one or more elements of a container type widget (like treeviews), starting at the given index. If 0 is passed as the count, all elements from that point to the end are removed. Otherwise, the specified number of elements are removed.

=== find ===

* '''gui.widget.find'''(''root widget'', ...)
* ''widget'':'''find'''(...)

Finds a child widget of the widget of the given path. For example, here it searches for the widget with the id 'preview_panel' of the second item of the widget with the id 'unit_list':

<syntaxhighlight lang=lua>
dialog:find('unit_list', 2, 'preview_panel')
</syntaxhighlight>

This is more or less equivalent to the following:

<syntaxhighlight lang=lua>
dialog.unit_list[2].preview_panel
</syntaxhighlight>

However, if the path comes from a variable, the functional form may be more convenient:

<syntaxhighlight lang=lua>
dialog:find(table.unpack(path))
</syntaxhighlight>

=== close ===

* '''gui.widget.close'''(''dialog'')
* ''widget'':'''close'''()

Closes the dialog.

[[Category:Lua Reference]]

Sandbox/GUI/Getting Started

2024-09-05T07:16:42Z

White haired uncle: /* Explore Your Options */

So, it looks like I can't exclude this page/section from the search engine as I had hoped. I wanted to put this in a sandbox so that it wouldn't be published without some proper review.

==Introduction==

This guide is designed to help you get a simple Wesnoth GUI, implemented in lua, up and running while describing the basic building blocks along the way. It is written in a narrative format, where most examples build on previous examples, and therefore while not always necessary it may be desirable to read from start to finish. The reader, probably a UMC author, should have a basic knowledge of working with lua within Wesnoth.

Some would find creating a GUI in part or in full using WML simpler to follow, and those alternatives are available, for example [[LuaAPI/gui/example]], but we're using lua here. If you find WML easier to follow, you can always convert the lua tables that define the GUIs to WML using [[LuaAPI/wml#wml.tostring|wml.tostring]], for example:

<syntaxhighlight lang=lua>
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
</syntaxhighlight>

In some examples, instead of defining the entire GUI at once, we'll break out some parts into separate variables. If you try to view one in WML and get an error from wml.tostring() about expecting a WML table and not a table, try passing your variable(/table) inside a table:

<syntaxhighlight lang=lua>
print(wml.tostring({listboxItem}))
gui.show_lua_console()
</syntaxhighlight>

One distinct advantage of using WML to define your GUI layout is that you get better (any) validation. Invalid keys, and sometimes values, are often flagged in the log, unlike with lua where they are silently ignored. In the comments of our first GUI, below, is an example which loads a WML GUI configuration using [[LuaAPI/wml#wml.load|wml.load()]], validating against the GUI2 window schema.

===What is GUI2?===
Once upon a time, Wesnoth had a GUI system which is now commonly referred to as GUI1. As of 1.19, GUI1 has been almost completely replaced by GUI2. UMC authors will probably never encounter GUI1 and can simply use the terms GUI and GUI2 interchangeably, at least until GUI3 comes along.

Instead of spending a lot of time here giving an overview of what GUI2 is and what makes it great, and not so great, let's charge ahead so we can see it in action, and let readers who are interested look elsewhere(TODO: link) for a more formal definition. (TODO: is this the right approach for most readers?).

==Getting Started==

For example purposes, we'll create a directory in our campaign directory called lua containing a file called gui_tutorial.lua, and add a command in the prestart event for a scenario which will create a right-click menu option to invoke our new GUI. Of course there are other methods to invoke lua from WML, but this one will get us started. After all, we really just want to get something up on the screen ASAP, right?

===A most basic GUI===

{|
|[[File:Most basic gui.png|center|thumb|I can't believe this worked]]
|-
|In our prestart event, we create a simple menu item, which executes a single line of lua which calls the lua function most_basic_gui() which is found in gui_tutorial.lua:
|}

<syntaxhighlight lang=wml>
[set_menu_item]
id=most_basic_gui
description="Our first GUI"
[command]
[lua]
code=<<
wesnoth.require("~add-ons/<OUR_CAMPAIGN>/lua/gui_tutorial.lua").most_basic_gui()
>>
[/lua]
[/command]
[/set_menu_item]
</syntaxhighlight>

And create gui_tutorial.lua:
{| class="wikitable" style="margin:auto"
! !! The WML equivalent of dialogDefinition
|-
|
<syntaxhighlight lang=lua>
local function most_basic_gui()
local dialogDefinition = {
--click_dismiss = true, -- allow user to close dialog with click of a button
wml.tag.tooltip { id = "tooltip_large" }, -- required
wml.tag.helptip { id = "tooltip_large" }, -- required
wml.tag.grid { -- our most basic gui
wml.tag.row { -- a grid must include at least one row
wml.tag.column { -- a row needs a column
wml.tag.image { -- a column includes exactly one widget
label = "units/trolls/grunt.png"
}
}
}
}
}

local function preshow(dialog)
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
end
gui.show_dialog(dialogDefinition,preshow)

-- Or, if you want to define the gui in WML, something like:
-- local dialog_wml = wml.load("~add-ons/GUI_Tutorial/most_basic_gui.cfg",
-- true, "schema/gui_window.cfg")
-- gui.show_dialog(wml.get_child(dialog_wml, 'resolution'))
end
return { most_basic_gui = most_basic_gui}
</syntaxhighlight>
|
<syntaxhighlight lang=wml>
[tooltip]
id="tooltip_large"
[/tooltip]
[helptip]
id="tooltip_large"
[/helptip]
[grid]
[row]
[column]
[image]
label="units/trolls/grunt.png"
[/image]
[/column]
[/row]
[/grid]

</syntaxhighlight>
|}

In the above file, we have just the single function to create our GUI, followed by a return command which makes our function most_basic_gui() available to the [[LuaAPI/wesnoth#wesnoth.require|wesnoth.require()]] function as most_basic_gui().

Our function creates a table containing the definition of a "dialog", and then passes that to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]]. It should be noted that gui.show_dialog does not provide synchronization, so if your GUI makes changes to the game state, you'll need to jump through some hoops or you'll break replays and multiplayer, but that's not something we need to care about at this point, so just be aware that you may need to deal with it in the future.

Our dialog definition at this point includes three parts. The first two are a tooltip and a helptip, which are required and define how tooltips (use id = "tooltip_large" or id = "tooltip" or id = "tooltip_transparent"), and helptips (rarely used, but must be included here, and yes their definitions are "tooltip" not "helptip") will look (as we will see later, this really should be definition = "tooltip", but in this case it's id = "tooltip"). The third part is a grid, which is basically a table, like in HTML or MySQL, with rows and columns. A grid always contains at least one row. A row contains at least one column (note that a column does NOT span rows, it is completely contained within a row). Inside a column is exactly one item, a cell which contains a [[GUIWidgetDefinitionWML|widget]], in this case we'll use an image (later we'll see what else we can put in a cell). Note that we don't actually define a cell in our code, it's just a term used to refer to the contents of a column.

The preshow function is optional. If included in the call to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]], it is run before the GUI is displayed. In this case, we include it to display the dialog we created with lua in WML format. Near the end, in comments, we show how you would call [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] if you chose to define your dialog using WML. Note that what is shown here is the WML equivalent of our lua dialogDefinition, and not the complete WML you would need to use if you were to configure your GUI layout in WML.

Note: if you should try out the above, you'll have to hit escape or enter to close the GUI. Uncomment the "click_dismiss" line, and the user will be able to close the GUI with a mouse click.

===Adding a little flavor===

{|
|You may have noticed our GUI is missing a header and a way to close it when we're done admiring our work. Here we add a new first row to our grid, while demonstrating a couple formatting options: a border to put some distance between our grid cell and its neighbor, and the "use_markup = true" option to enable Pango support in our text.

Our third row adds an OK button at the bottom. You can associate actions with buttons to do all kinds of things, but here we just exploit the default behaviour to close the GUI.

Of course, we'll also have to modify our return to support the new function, and update our menu item(s) accordingly.
|-
|[[File:Most basic gui2.png|center|thumb|Adding header and a footer]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui2()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
gui.show_dialog(dialogDefinition)
end
return { most_basic_gui = most_basic_gui, most_basic_gui2 = most_basic_gui2 }
</syntaxhighlight>

===And a bit more===
{|

|And now a minor, but important change. We want to add a new text field next to the image in the body of our GUI. Obviously, we want to add a new column, but this is more difficult than when we added new rows in the previous example. The problem is that all rows (at a given level) in a grid must contain the same number of columns. We can't have two columns in the row that constitutes the body of our GUI, but only one in the header and one in the footer. To solve this problem, we replace our image widget with a new grid, which can use as many columns as we like (as long as they are the same within each row of our new grid). This new grid contains a row with two columns, but that is okay because the new grid itself is placed in a single column, which matches our single column header and footer (ok button), keeping the rows balanced.
|-
|[[File:Most basic gui3.png|center|thumb|Rows with different numbers of columns]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui3()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column { -- This is the only column in this row,
-- to match the number of columns in
-- the rows of our header and footer
wml.tag.grid { -- A new grid, so we can use a different
-- number of columns
wml.tag.row {
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
},
wml.tag.column {
wml.tag.label {
label = "A troll"
}
}
}
}
}
},
wml.tag.row { -- A footer
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = "Ok"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

While we see here just the simplest of examples, you can many levels of grids in grids, rows with multiple columns some of which containing grids, etc, to build complicated dialogs to your liking.

==Containers==

===Stacked Widget===

TODO

===Listbox===
{|
| Now we'd like to add some more monsters. Obviously, we could just add more rows, but what if we won't know until runtime how many and which ones? We could break up the definition of our dialog and add new rows dynamically, it's just a table after all, but fortunately we have a widget which handles this for us, a listbox. A listbox is kind of like an array, a collection of similar objects where the number of items can vary. We will tell the GUI where we want the box, and what each entry in the box will look like, and then at runtime we can add entries to the box.
|-
| [[File:Gui with listbox.png|center|thumb|Listbox with three items]]

<syntaxhighlight lang=lua>
local function gui_with_listbox()
local monsters = {
{ image = "units/trolls/grunt.png",
string = "A troll" },
{ image = "units/monsters/cuttlefish.png",
string = "A cuttlefish" },
{ image = "units/monsters/yeti.png",
string = "A yeti" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
}

local listboxDefinition = wml.tag.listbox { id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
listboxDefinition
}
},
wml.tag.row {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_label.label = monster.string
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We begin by creating a simple table which represents the data which will be presented in our listbox. In most cases, we probably wouldn't create that monster table here, but we need it for our example.

The variable listbox_id gives us an identifier for our listbox so we can reference it when we need to. We don't really need to use a variable here, it's just convenient.

We define the structure for the elements in our listbox, stored in listboxItem. Note that we've replaced the actual data with identifiers (e.g. 'units/trolls/grunt.png' becomes 'id = "monster_image"), since each element may have different data.

We define the listbox itself, specifying the identifier, and the definition of our listbox element (which looks a lot like a grid). The cell inside the column contains a variable which is just the listbox element definition we created above; it's not necessary to do this, we could have used one big table, but it's easier to read this way (IMO).

We replace the hardcoded data in our GUI body with our new listbox definition, again using a variable to make it easier to read.

We create a function, often called preshow(), which will be called for us as part of the drawing the GUI (see the new optional argument in [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] -- there's also an optional postshow(), but we don't need it here). This is where we pull the data from our example table into the listbox. We create a listbox variable associated with the listbox, identified by the listbox_id we assigned earlier, inside the dialog which gui.show_dialog() passes to preshow(). Then we iterate through our data table, using each entry from that table to populate a listbox item.

Let's look at that last action a little more closely using an example.

<syntaxhighlight lang=lua>
listbox[i].monster_image.label = monster.image
</syntaxhighlight>

Which we can read as "In listbox element i of our listbox, for the image with identifier monster_image which we defined in our listboxItem, use the data from the corresponding index i in our example data table" (you don't see the index i for the monsters table here, but remember we're iterating using ipairs, we could have just as easily used listbox[i].monster_image.label = monsters[i].image). If you were to step through all of the variable substitutions, you'd see that for i=1, our dialogDefinition is basically the same thing as it was in the earlier examples, just supplied from a table instead of hardcoded (note that you can hardcode entries in a listbox in your dialog definition using the [list_data] tag, aka wml.tag.list_data, which we do not demonstrate here).

You will probably notice that our data does not line up nicely in the GUI. We will fix that later. We'll also demonstrate how the user can select an item in a listbox, and how you can identify which item that was using the selected_index variable of the listbox.

===Tree View===
====Simple Tree View====
{|
| You may have noticed that clicking on a listbox item in our listbox caused it to be highlighted with a box around the contents. This is because the items in a listbox are selectable. This will be useful when we want to add actions, but it looks a bit odd if we just want to present a list of data.

Also, most of the data had to be formatted the same for each item in the listbox. We could, perhaps, include custom markup in our labels, but the actual layout, like the number of columns per row, had to be the same for every item.

Another way to present a list of data is the tree view. Since a tree view supports multiple data types, we may need to create multiple definitions for the elements in our list. These are known as nodes. It will also be necessary to explicitly define which node to use for each element when we populate our tree view.
|-
| [[File:Basic tree view.png|center|thumb|Tree_views can hold multiple data types (only trolls have names here)]]
|}
<syntaxhighlight lang=lua line>
local function basic_tree_view()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", type = "Seamonsters" },
{ image = "units/monsters/yeti.png", label = "A yeti",
type = "Coolers" }
}

local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "trolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name",
linked_group = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
},
wml.tag.node {
id = "nottrolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "monster_name",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_image",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_label",
fixed_width = true
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_tv:add_item_of_type("trolls_node")
dialog.monsters_tv[i].monster_name.label = monster.name -- only trolls have a name
else
dialog.monsters_tv:add_item_of_type("nottrolls_node")
end
-- All of our monsters have an image and a label
dialog.monsters_tv[i].monster_image.label = monster.image
dialog.monsters_tv[i].monster_label.label = monster.label
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We have expanded our list of monsters to include three types of trolls. We have also given each troll a name. This is of course a rather simplistic example, we could have simply given each monster that is not a troll an empty name, but it as presented here our approach serves the purpose of demonstrating how we deal with multiple data types. Our new tree view contains a node for each type of data we will present. In preshow, we explicitly define each element in our list using add_item_of_type(), and populate the item accordingly. [Note: in our listbox example, we could have used add_item() to add items to the listbox, but chose not to since that section was already introducing a number of new concepts. But here, since we have multiple types of items we need to be able to specify the type of the item when we add one, hence we need to use add_item_of_type()].

You may also note the addition of a few linked_group lines. We'll cover linked groups in more detail later, but as used here they instruct the GUI that each column using the same node type needs to be aligned with the others. For example, all of our trolls line up nicely.

====Building a Tree====
{|
| colspan="2" |At this point, one may wonder about the name "tree view", since what he have seen doesn't look much like a tree. To make a tree-like structure, we'll demonstrate adding children to nodes. At the top level our (upside-down) tree will have two nodes, one for trolls and one for everything else. A toggle_button (a type of button which changes states when you push it) will allow us to expand the trolls node to expose its children, which are themselves nodes, though they only contain a label at this point.
|-
| [[File:Basic tree view2a.png|center|thumb|Tree_view with Trolls folded]] || [[File:Basic tree view2b.png|center|thumb|Tree_view with Trolls unfolded]]
|}
<syntaxhighlight lang=lua line>
local function building_a_tree()
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
}
},
wml.tag.column {
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Show me the " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
-- You can refer to an object by its position

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[1].race_label.label = "Trolls"
-- dialog.monsters_tv[1].race_button.on_modified =
-- function()dialog.monsters_tv[1].unfolded =
-- dialog.monsters_tv[1].race_button.selected end

-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][1].monster_type.label = "Whelp"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][2].monster_type.label = "Shaman"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][3].monster_type.label = "Troll"

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[2].race_label.label = "Other scary things"
-- dialog.monsters_tv[2].race_button.visible = "hidden"

-- ... or you can refer to that object using the return value
-- from add_item_of_type
local troll_node = dialog.monsters_tv:add_item_of_type("race_node")
troll_node.race_label.label = "Trolls"
troll_node.race_button.on_modified =
function()
troll_node.unfolded = troll_node.race_button.selected
end
local item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Whelp"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Shaman"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Troll"

local not_troll_node =
dialog.monsters_tv:add_item_of_type("race_node")
not_troll_node.race_label.label = "Other scary things"
not_troll_node.race_button.visible = "hidden"

end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We define two nodes in our tree, a race_node for the top level, and a details_node for the children of a race_node. The rest of the interesting bits are in preshow().

We demonstrate two different ways of creating and accessing items, the first (commented out) just using the order in which they are created, while in the second we capture the result of add_item_of_type() in a variable we can use to refer to the newly defined object. The first method is shown primarily to demonstrate the structure of the resulting objects. The second method is perhaps easier to follow, and is almost necessary when you start doing things like dynamically deleting nodes, so it is in most cases a better practice (of course, you probably won't want to use the same variable for each node like we did, and perhaps not one local to the preview function).

We add a node, label it "Trolls", and add a callback to the button such that the children of the node will be visible (the node is "unfolded", a boolean value which defaults to false) when the button is checked (selected == true). Then we add three "details_node" nodes as children of this node.

Our second node, "Other scary things" will remain empty for now, so we'll set the visible attribute on its button to "hidden" (which is like false, but with hidden the widget still takes up space).

{|
| This example is rather ugly, both in the hardwired code and the appearance of the resulting GUI, but it addresses a couple important aspects of how tree views work and how we might use them. Let's clean it up a bit. We'll add an indentation_step_size to the tree view, along with a spacer and [[#Alignment|horizontal_alignment]] to our details node, to make the labels line up nicely, and change the button [[#Definitions|definition]] to replace the checkbox with something that looks like it belongs there. We will look at methods for handling layout in more depth [[#Appearance|later]].
|-
| [[File:Basic tree view2c.png|center|thumb|Our tree_view with proper alignment]]

<syntaxhighlight lang=lua>
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
indentation_step_size = 20,
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
definition = "tree_view_node"
}
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.spacer { width = 40 }
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}

</syntaxhighlight>

===Multi_page===
====Simple Multi_page====
{|
|-
Like a tree_view, a multi_page is a heterogeneous container which is dynamically populated, however, while a multi_page contains multiple elements (pages), only one page is displayed at any one time. Its purpose is perhaps best described by a couple of examples.
|-
[[File:Basic multipage.png|center|thumb|Multi_page showing active page]]
|}
<syntaxhighlight lang=lua>
local function basic_multipage()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll",
name = _"Bob", type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp",
name = "Junior", type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman",
name = _"Alice", type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish",
type = "Seamonsters" },
{ image = "units/monsters/yeti.png",
label = "A yeti",
type = "Coolers" }
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
multi_page
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}

local function preshow(dialog) -- Prepare the GUI before display
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_label.label = monster.label
end
--dialog.monsters_mp.selected_index = 5
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

As you can see, the code for our basic multi_page GUI looks a lot like our basic tree_view GUI. The difference is what is displayed. While both the tree_view and the multi_page containers contain five items, with the multi_page, only the first one is displayed. More specifically, only the page associated with the selected_index attribute of the multi_page object, which defaults to 1, is displayed. If we were to uncomment the last line in preshow(), we would still see only one item, but it would be the fifth one we allocated. It's nice to know all our pages are in there somewhere, but this example is pretty useless. What we need is a way to select which page we want to see from within our GUI.

====A More Useful Multi_page====

{|
| colspan="2" | To demonstrate the usefulness of a multi_page, and highlight its difference from a tree_view, we'll add a listbox to allow us to select the page to view. We'll also need to add a little action to our GUI.
|-
| style="align:centered" |[[File:More useful multipage.png|center|thumb|User selected Troll]] || [[File:More useful multipage2.png|center|thumb|User selected Cuttlefish]]
|}

<syntaxhighlight lang=lua>
local function more_useful_multi_page()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
race = "Trolls", tip = "Your uncle" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
race = "Trolls", tip = "Your nephew" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
race = "Trolls", tip = "Your auntie" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", race = "Seamonsters",
tip = "Not a fish" },
{ image = "units/monsters/yeti.png",
label = "A yeti", race = "Coolers",
tip = "ROAR!" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
}
}
}

local listboxDefinition = wml.tag.listbox {
id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
},
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
listboxDefinition
},
wml.tag.column {
wml.tag.spacer {
width = 30
}
},
wml.tag.column {
multi_page
},
}
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_image.tooltip = monster.tip
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_image.tooltip = monster.tip
dialog.monsters_mp[i].monster_label.label = monster.label
end
local function switch_page()
dialog.monsters_mp.selected_index = listbox.selected_index
end
listbox.on_modified = switch_page
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

Most of this should look pretty familiar. We've simply taken the previous example and added a second column to our GUI using code from an earlier example to add a listbox. In addition, we altered the page layout slightly, and added a spacer column in the dialog definition to approve the appearance.

The interesting stuff is in preshow(). Again we've merged in some listbox code from an earlier example, but we've also created a new local function switch_page(), which simply sets the selected_index attribute of our multi_page to the same as that of our listbox, and then we've configured the listbox.on_modified callback to call switch_page(). Now when the user selects an item in the listbox (updating listbox.selected_index and triggering listbox.on_modified), dialog.monsters_mp.selected_index is updated accordingly and therefore the visible page changes to the one associated with the selected unit.

Also note in preshow() we've added a new child to our monster_image identifier for both the listbox and the multi_page, a tooltip. When the user hovers the mouse over the image of one of our monsters, they'll see a popup message which we've added to our monster table. Try changing '''wml.tag.tooltip { id = "tooltip_large" }''' to '''wml.tag.tooltip { id = "tooltip }''' in the dialogDefinition to see a different tooltip style.

==Actions Have Consequences==

So far, our GUIs have only displayed some information on the screen, but at some point we're probably going to want to use a GUI to get input from the user. In this section we will look at return values that can be assigned to a widget based upon its state, and callbacks, which are functions invoked when something happens with a widget. As we will see, a button is a good example, as it can return a value or take an action, or both, when pressed. Earlier we saw how the selected_index attribute of some widgets, such as the listbox, can also be used as a sort of return value.

===Buttons===
{|
| colspan=2 | In this example, we'll create a couple buttons which provide the user a choice, use a handy confirmation popup to confirm that choice, and demonstrate how we get the results back where we can put them to use.
|-
| [[File:Basic return value.png|center|thumb|There can be only one]] || [[File:Basic return value_confirm.png|center|thumb|The user selected Alice, let's confirm this critical choice]]
|}

<syntaxhighlight lang=lua>
local function basic_return_value()

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "leader_lg",
fixed_height = true,
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" ..
_"Which unit shall lead your army?" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Alice" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/elves-wood/sylph.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 1
}
}
},
}
},
wml.tag.column {
wml.tag.spacer { width = 20 }
},
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Bob" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/human-loyalists/marshal.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 2
}
}
}
}
}
}
}
}
}
}
}
local user_chose = gui.show_dialog(dialogDefinition)
local leader
if user_chose == -1 then -- User closed the dialog by hitting the Enter key
leader = nil
end
if user_chose == -2 then -- User closed the dialog by hitting the Escape key
leader = nil
end

if user_chose == 1 then
leader = "Alice"
end
if user_chose == 2 then
leader = "Bob"
end

local confirmed_leader_choice

if leader ~= nil then
local query = _"You want " .. leader .. _" as your leader?"
confirmed_leader_choice = gui.confirm(query)
end

if confirmed_leader_choice then
wesnoth.message("Great!")
else
wesnoth.message("Fine, lead them yourself!")
end
end
</syntaxhighlight>

Here we've added a couple buttons, and assigned each of them a return value. When the user selects one of these buttons, the GUI is closed and the value of return_value is returned from gui.show_dialog(). We then use [https://wiki.wesnoth.org/LuaAPI/gui#gui.show_prompt gui.confirm()] which provides a very simple Yes/No popup and returns true or false, respectively. Other useful functions can be found on that page which provide handy alternatives to creating your own GUI for other simple user inputs.

The use of return_value is rather limited, as it only returns integers and can't be used with containers like listboxes. In more complex cases we'll need to turn to callback functions which are invoked when something happens to a widget, like clicking a button or a widget's value changing. Earlier, we saw an example of [[LuaAPI/types/widget#on_modified|widget.on_modified()]]. More examples of callbacks can be found at [[LuaAPI/types/widget#on_modified|that link]].

===Slider and Textbox===
{|
| Here we see a couple methods of getting more dynamic input from the user, a slider and a textbox presented in one silly example.
|-
| [[File:Slider and textbox.png|center|thumb|Two ways of getting input from the user]]
|}

<syntaxhighlight lang=lua>
function scrollbar_and_textbox()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = _"How much gold will you pay for this old rusty sword?"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.slider {
id = "gold_sl",
minimum_value = 0,
maximum_value =
wesnoth.sides[wesnoth.current.side].gold,
value = math.floor(
wesnoth.sides[wesnoth.current.side].gold/2)
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.text_box {
id = "gold_tb",
--hint_text = _ "Enter gold here",
--hint_image = "images/gold_pile.png",
label = tostring(math.floor(
wesnoth.sides[wesnoth.current.side].gold/2))
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
local function show_input()
wesnoth.interface.add_chat_message(_"You chose " ..
dialog.gold_sl.value .. _" with the slider")
wesnoth.interface.add_chat_message(_"You entered " ..
tostring(dialog.gold_tb.text) .. _" in the text_box")
end
-- this is a button, so we use on_button_click, not on_left_click
dialog.ok.on_button_click = show_input

dialog.gold_sl.on_modified = function()
dialog.gold_tb.text = tostring(dialog.gold_sl.value)
end
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We create a slider, with a range from 0 to the amount of gold possessed by the current side and an initial value in the middle, and a text box with the same initial value. We assign a function to our OK button which simply reports on the values provided by the user. For no reason whatsoever, we add a callback such that when the user adjusts the slider the value in the textbox is update to match the slider.

Note that the textbox returns text, even though it looks like we're expecting the user to input a natural number. Remember to validate those inputs.

You can use text_hint to place a caption in the box that will help the user understand what to enter in the box, and possibly an image as well. For example, in the search box in the recall menu uses '''hint_text = _ "Search", hint_image = "icons/action/zoomdefault_25.png~FL(horiz)"'''. Of course, you can't have a hint and a label in the same text_box at the same time, so in our example we've only included them as comments.

There is also a widget called a spinner, which is kind of like the combination of a text_box and a slider. As of the release of 1.18, it appears to be unfinished so the strange syntax needed to make it work is probably not the best thing to document, and we will omit it for now.

==Appearance==

'''This section needs help'''

===Borders===

Borders allow you to force unused space around a column, for example so that your widgets don't runtogether. You can specify the border to be one or more of top, bottom, left, right, or all. The border_size sets the amount of padding, in pixels.

<syntaxhighlight lang=lua>
wml.tag.column{
border = "left, right"
border_size = 25
}
</syntaxhighlight>

===Alignment===
{|
| colspan=2 |By default, the GUI will usually center widgets in their cells, which is not always what we want. In this example, we use horizontal_alignment to move widgets around a little.

In more complex cases, it may be useful to add [[GUIWidgetDefinitionWML#Spacer|spacers]] to help force alignment, or use linked_groups to force consistent alignment for objects within a grid.
|-
| [[File:Gui tutorial alignment without.png|center|thumb|Default alignment]] ||[[File:Gui tutorial alignment with.png|center|thumb|Showing off some alignment options]]
|}
<syntaxhighlight lang=lua>
local function basic_alignment()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = "Ralph"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "right",
wml.tag.label {
label = "Sam"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/troll-hero-attack-se-4.png" -- 122x102
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "left",
wml.tag.label {
label = "Jr"
}
},
wml.tag.column {
horizontal_alignment = "right",
wml.tag.image {
label = "units/trolls/whelp.png" -- 72x72
}
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

The screenshots show the output of this example with and without the horizontal_alignment lines included above.

A label allows you to set the text_alignment field (e.g. text_alignment = "left"). Note, however, this only aligns the text within the label. The label itself will probably be centered in the column, giving the false appearance that your text alignment is not working.

===Growth===

To keep your dialog nicely balanced, the GUI2 engine may need to grow rows and/or columns. You can control which columns, for example, grow and which do not, by setting some with grow_factor = 1, and others with grow_factor = 0 (do not grow). While grow factors of 0 and 1 are the most common, you can use other values to adjust the relative growth if you really need to, see [[GUILayout]] for the gory details.

It it sometimes useful to include a column with a [spacer] and a grow_factor (often the only column with grow_factor != 0) whose sole purpose is to keep your GUI aligned nicely as the layout engine does its evil.

To force a column to stretch to fit available space, use horizontal_grow = true. Note that horizontal_grow is not compatible with horizontal_alignment. There is also a vertical_grow parameter.

If you need to see every little detail about the layout process, start wesnoth with --log-debug=gui/layout. Good luck with that.

===Definitions===
Many widgets can be configured to have to a different appearance, for example in our tree_view example we changed the definition of a toggle_button from the default of a checkbox by setting definition = "tree_view_node". This option was found by looking at the id of a toggle_button_definition in .../data/gui/widget/toggle_button_tree_view_node.cfg:

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib
###
### Definition of a toggle button to be used in a tree view as node fold/unfold indicator
###
[toggle_button_definition]
id = "tree_view_node" # <--- we can use 'definition = "tree_view_node"' in a [toggle_button] to select this definition
description = "Fold/unfold status indicator of a tree view node."
</syntaxhighlight>

{|
|There are many other definitions for buttons and other widget types in that directory. It would be nice to have a list (linked here), but for now you'll just have to look around.

We can even create our own custom definitions using [[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition()]]. In this example, we copy from .../data/gui/widget/toggle_button_tree_view_node.cfg with a slight change so that our button turns red ( '''~BLEND(255,0,0,1)''' ) when focused.

In this example, we will use wesnoth.wml_actions to create the WML tag [add_widget_def_demo].

Note the first line, a common convention for creating an alias for wml.tag.
|-
|[[File:Gui tutorial custom widget.png|center|thumb|Different definition of buttons, including one of our own (right)]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag -- save ourselves some typing
function wesnoth.wml_actions.add_widget_def_demo()
local definition = {
id = "tree_view_node_custom",
description = "Fold/unfold status indicator of a tree view node (MODIFIED).",
T.resolution {
min_width = 25,
min_height = 19,
default_width = 25,
default_height = 19,
max_width = 25,
max_height = 19,
-- Unselected - note there's no tags for unselected/selected, that's simply determined by the order
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/fold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/fold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/fold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
-- Selected
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/unfold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
}
}
gui.add_widget_definition("toggle_button", "tree_view_node_custom", definition)

local dialogDefinition = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid {
T.row {
T.column {
T.tag.toggle_button {
definition = "default"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node_custom"
}
}
}
}
gui.show_dialog(dialogDefinition)
end

</syntaxhighlight>

See [[GUIWidgetDefinitionWML]] for more details on widget definitions.

You can also give the whole dialog a definition, like definition = "tooltip_large". There is no gui.add_window_definition(), however a window is technically a type of widget so it may be possible to create your own window definitions (please update this if you do).

===Panels===

===Canvases===
Part of panels? Sort of?

A canvas is a surface you can draw on. A dialog has them, as does a panel, and for these canvas 1 refers to the background, while canvas 2 refers to the foreground. Other widgets may have canvases that may have other meanings, or no canvases at all. See more at [[LuaAPI/gui/widget#set_canvas]].

Here's a fun little trick. Set your dialog background to be transparent:
<syntaxhighlight lang=lua>
local function preshow(dialog)
dialog:set_canvas(1, { } )
end
</syntaxhighlight>

Or, if you want an opaque GUI background with the screen behind it blurred like what you see behind the text of a [message], you can set your window definition to "message":
<syntaxhighlight lang=lua>
...
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
definition = "message",
...
</syntaxhighlight>

{|
|Here we take our [[#Progress Bar|progress bar]], and add a text overlay.

Note: either using text on a canvas is rather limited, or I just couldn't figure it out. For example, I could not get the text size any smaller, and any attempts to do so simply resulted in very blocky text. And the spaces were necessary so that the text wasn't stretched out. I also find it surprising that the progress bar does not have this feature inherently. So it's not a great example, but it should be enough to get you started using canvases. Be sure to visit the [[LuaAPI/gui/widget#set_canvas|link]] mentioned above for more options.
|-
|[[File:Gui tutorial canvas text.png|center|thumb|A progress bar in the background, with text in the foreground]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar_with_overlay()
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.grid {
T.row {
T.column {
T.panel { id = "panel",
T.grid {
T.row {
T.column {
T.button { id = "button",
label =_ "Press me"}
},
T.column {
T.progress_bar { id = "progress" }
},
T.column {
T.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
dialog.panel:set_canvas(2, { T.text { text_alignment = "center", font_size = 48,
text_markup = true, text = " " ..
dialog.progress.percentage .. "% " } } )
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

You may notice we added a panel and placed our text on the foreground canvas(2) on it, since the progress_bar itself does not support canvases.

===Placement===

You may have noticed that all of our dialogs are centered on the screen. This is the default. You can override this and place the dialog wherever you like by setting automatic_placement = false, along with x, y, width, and height at the top level of your dialog definition (next to tooltip =, etc).

'''This part about placement needs review'''
If you prefer, you may replace x and/or y with horizontal_placement and vertical_placement, such as horizontal_placement = "left". You can even set the placement values using WFL, for example horizontal_placement = "(gamemap_width / 3)" -- see [[#Using WFL with GUI2|Using WFL with GUI2]].

==Miscellaneous==

TODO: This stuff doesn't belong in a tutorial. It's worth documenting, but not here. Better to save these here for now than keep them on my laptop.

===Progress Bar===
{|
|A progress_bar is a graphical representation of a percent. In this example, we present the user with a puzzle. They must hit the button repeatedly before they can close the GUI. A progress_bar displays their current progress toward completion.
|-
|[[File:Gui tutorial progress bar.png|center|thumb|upright=2]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.button { id = "button",
label =_ "Press me"
}
},
wml.tag.column {
wml.tag.progress_bar { id = "progress" }
},
wml.tag.column {
wml.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end

gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

===Unit Preview Pane===

{|
|A unit_preview_pane takes a unit (or a unit type), and presents a graphical representation of the unit and its more important attributes, along with tooltips for additional details, in the same way that the recall menu does. Here we see an example of a unit which has picked up some items, including a weapon, which are affecting its stats.
|-
|[[File:Gui tutorial unit preview pane.png|center|thumb]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag

function wesnoth.wml_actions.recall_from_variable(cfg)
local from_array = cfg.from or wml.error(
"[recall_from_variable]: missing required from= ")
local to_var = cfg.to or wml.error(
"[recall_from_variable]: missing required to= ")
local unit_list = wml.array_access.get(from_array) or wml.error(
string.format("[recall_from_variable]: failed to fetch wml array %s",from_array))

local listboxItem = T.grid {
T.row {
T.column {
T.label { id = "available_unit",
linked_group = "available_unit"
}
}
}
}

local listbox_id = "available_units"
local listboxDefinition = T.listbox { id = listbox_id,
T.list_definition {
T.row {
T.column {
T.toggle_panel { listboxItem }
}
}
}
}
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.linked_group { id = "available_unit", fixed_width = true },
T.grid {
T.row { -- header
T.column {
T.grid {
T.row {
T.column {
border = "bottom",
border_size = 10,
T.label {
use_markup = true,
label = ""
.. _"Select unit to recall" .. ""
}
}
}
}
}
},
T.row { -- Body
T.column {
T.grid {
T.row {
T.column {
border = "right",
border_size = 40,
listboxDefinition
},
T.column {
T.unit_preview_pane { id = "unit_preview" }
}
}
}
}
},
T.row { -- Footer
T.column {
T.grid {
T.row {
T.column {
T.spacer { width = 400 }
},
T.column {
border = "top,right",
border_size = 10,
T.button { id = "ok",
label = _"OK"
}
}
}
}
}
}
}
}

local picked = 1

local function preshow(dialog)
local listbox = dialog[listbox_id]
for i,unit in ipairs(unit_list) do
listbox[i].available_unit.label = unit.name .. "(" ..
unit.language_name .. ")"
end
local function draw_unit()
wesnoth.units.to_recall(unit_list[listbox.selected_index])
local tmp = wesnoth.units.find_on_recall{ id =
unit_list[listbox.selected_index].id }[1]
dialog.unit_preview.unit = tmp
wesnoth.units.extract(tmp)
picked = listbox.selected_index
end
draw_unit()
listbox.on_modified = draw_unit
end

gui.show_dialog(dialogDefinition,preshow)

wml.variables[to_var] = picked - 1
end

</syntaxhighlight>

This should all be pretty self evident by now. We are provided with an array of stored units (from [store_unit] in WML). We create a listbox populated with units and we use the selected_index to determine which element in the table to send to unit_preview_pane. Since our input is an array of unit data, not actual units, we use [[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] to take the definition of one from our array and place it on the recall list (turning it into an actual unit), [[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] to fetch that unit in a form that the unit_preview_panel understands, and finally [[wesnoth.units.extract|wesnoth.units.extract]] to remove the unit from the recall list when we are done with it.

And of course we subtract one from the selected_index when we return our choice to WML, since lua arrays count from 1 and WML from 0.

The unit_preview_pane will also accept a unit_type instead of a specific unit.

==Appendix==

===Explore Your Options===

We've seen a lot of options that can be set to modify the behaviour of our dialogs, some on columns, some on widgets, etc. These are in the process of being documented [[GUIWidgetInstanceWML|here]], but if you would like to go straight to the source, the data Wesnoth uses to validate your configuration can be found in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui data/schema/gui] under your install directory.

Let's look at a scroll_label, for example. A scroll_label is a widget, so we look in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/widget_instances.cfg widget_instances.cfg] and find the following. Here we can see five parameters we can provide to our scroll_label (in addition to the ones available to all widgets, like id and definition, see the entry super=... which refers you to the widget_instance in the file [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/generic.cfg data/schema/gui/generic.cfg]), along with their types and default values. For example, we could set "link_aware = true", and if we do not we can assume that link_aware will be false. While this does not explain what these parameters do, the information provided in the schema directory is often helpful nonetheless.

<syntaxhighlight lang=wml>
[tag]
name="scroll_label"
min="0"
max="infinite"
super="$generic/widget_instance"
{DEFAULT_KEY "horizontal_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "vertical_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "wrap" bool true}
{DEFAULT_KEY "text_alignment" f_h_align "left"}
{DEFAULT_KEY "link_aware" bool false}
[/tag]
</syntaxhighlight>

We see that our scrollbars are of type scrollbar_mode. It would probably help if we knew what values are available to the scrollbar_mode. In [https://github.com/wesnoth/wesnoth/tree/master/data/schema/types/gui.cfg data/schema/types/gui.cfg] we find this:

<syntaxhighlight lang=wml>
[type]
name=scrollbar_mode
value="always|never|auto|initial_auto"
[/type]
</syntaxhighlight>

The variable types found in the schema files are described at [[GUIVariable]].

Note: The keys in the schema file correspond to the attributes used when configuring your widgets. They will not always align perfectly with keys used by the Lua API. For example, the slider uses maximum_value in its configuration, and max_value when using the Lua API:

<syntaxhighlight lang=wml>
[slider]
id="my_slider"
maximum_value = 100
[/slider]
</syntaxhighlight>

<syntaxhighlight lang=lua>
dialog.my_slider.max_value = 90
</syntaxhighlight>

===Using WFL with GUI2===

If you look at the variable type descriptions at [[GUIVariable]] you may notice that many of them start with "f_" and have "or formula" in the description. This means that you can use [[Wesnoth_Formula_Language|Wesnoth Formula Language (WFL)]] formulas in these fields, with certain variables made available to you (which variables and what they mean can be challenging to ascertain, but you can generally figure it out by example).

Looking at [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/window.cfg data/schema/gui/window.cfg] we see that 'height' has type f_unsigned, which tells us that height is an unsigned integer, and that we can use a WFL formula to define it in a window_definition. In [https://github.com/wesnoth/wesnoth/tree/master/data/gui/themes/default/window/wml_message.cfg data/gui/window/wml_message.cfg] (data/gui/themes/default/window/wml_message.cfg starting around 1.19.2), we find the line '''height = "(screen_height - 30)"'''. This does exactly what it looks like, it sets the height of our window to 30 pixels less than the height of the screen.

===Useful Links===

[[LuaAPI/gui|LuaAPI/gui - Mostly about opening windows]] 
[[LuaAPI/types/widget|LuaAPI/types/widget - Widget attributes and callbacks]] 
[https://wiki.wesnoth.org/Category:GUI_WML_Reference GUI_WML_Reference] 
[https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui .../data/schema/gui/*.cfg] - Lists of valid options for various GUI objects 
[https://devdocs.wesnoth.org/layout_algorithm.html Layout Algorithm] - For windows, at least

===Credits===

The basic framework that composes the initial examples was lifted from LotI. It's a great place to find well written examples, but some of it is complex enough to be a little overwhelming when getting started.

Many examples, particularly tree view and multipage, are heavily derived from the World Conquest multiplayer campaign.

Sandbox/GUI/Getting Started

2024-09-05T06:56:47Z

White haired uncle: /* Building a Tree */

So, it looks like I can't exclude this page/section from the search engine as I had hoped. I wanted to put this in a sandbox so that it wouldn't be published without some proper review.

==Introduction==

This guide is designed to help you get a simple Wesnoth GUI, implemented in lua, up and running while describing the basic building blocks along the way. It is written in a narrative format, where most examples build on previous examples, and therefore while not always necessary it may be desirable to read from start to finish. The reader, probably a UMC author, should have a basic knowledge of working with lua within Wesnoth.

Some would find creating a GUI in part or in full using WML simpler to follow, and those alternatives are available, for example [[LuaAPI/gui/example]], but we're using lua here. If you find WML easier to follow, you can always convert the lua tables that define the GUIs to WML using [[LuaAPI/wml#wml.tostring|wml.tostring]], for example:

<syntaxhighlight lang=lua>
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
</syntaxhighlight>

In some examples, instead of defining the entire GUI at once, we'll break out some parts into separate variables. If you try to view one in WML and get an error from wml.tostring() about expecting a WML table and not a table, try passing your variable(/table) inside a table:

<syntaxhighlight lang=lua>
print(wml.tostring({listboxItem}))
gui.show_lua_console()
</syntaxhighlight>

One distinct advantage of using WML to define your GUI layout is that you get better (any) validation. Invalid keys, and sometimes values, are often flagged in the log, unlike with lua where they are silently ignored. In the comments of our first GUI, below, is an example which loads a WML GUI configuration using [[LuaAPI/wml#wml.load|wml.load()]], validating against the GUI2 window schema.

===What is GUI2?===
Once upon a time, Wesnoth had a GUI system which is now commonly referred to as GUI1. As of 1.19, GUI1 has been almost completely replaced by GUI2. UMC authors will probably never encounter GUI1 and can simply use the terms GUI and GUI2 interchangeably, at least until GUI3 comes along.

Instead of spending a lot of time here giving an overview of what GUI2 is and what makes it great, and not so great, let's charge ahead so we can see it in action, and let readers who are interested look elsewhere(TODO: link) for a more formal definition. (TODO: is this the right approach for most readers?).

==Getting Started==

For example purposes, we'll create a directory in our campaign directory called lua containing a file called gui_tutorial.lua, and add a command in the prestart event for a scenario which will create a right-click menu option to invoke our new GUI. Of course there are other methods to invoke lua from WML, but this one will get us started. After all, we really just want to get something up on the screen ASAP, right?

===A most basic GUI===

{|
|[[File:Most basic gui.png|center|thumb|I can't believe this worked]]
|-
|In our prestart event, we create a simple menu item, which executes a single line of lua which calls the lua function most_basic_gui() which is found in gui_tutorial.lua:
|}

<syntaxhighlight lang=wml>
[set_menu_item]
id=most_basic_gui
description="Our first GUI"
[command]
[lua]
code=<<
wesnoth.require("~add-ons/<OUR_CAMPAIGN>/lua/gui_tutorial.lua").most_basic_gui()
>>
[/lua]
[/command]
[/set_menu_item]
</syntaxhighlight>

And create gui_tutorial.lua:
{| class="wikitable" style="margin:auto"
! !! The WML equivalent of dialogDefinition
|-
|
<syntaxhighlight lang=lua>
local function most_basic_gui()
local dialogDefinition = {
--click_dismiss = true, -- allow user to close dialog with click of a button
wml.tag.tooltip { id = "tooltip_large" }, -- required
wml.tag.helptip { id = "tooltip_large" }, -- required
wml.tag.grid { -- our most basic gui
wml.tag.row { -- a grid must include at least one row
wml.tag.column { -- a row needs a column
wml.tag.image { -- a column includes exactly one widget
label = "units/trolls/grunt.png"
}
}
}
}
}

local function preshow(dialog)
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
end
gui.show_dialog(dialogDefinition,preshow)

-- Or, if you want to define the gui in WML, something like:
-- local dialog_wml = wml.load("~add-ons/GUI_Tutorial/most_basic_gui.cfg",
-- true, "schema/gui_window.cfg")
-- gui.show_dialog(wml.get_child(dialog_wml, 'resolution'))
end
return { most_basic_gui = most_basic_gui}
</syntaxhighlight>
|
<syntaxhighlight lang=wml>
[tooltip]
id="tooltip_large"
[/tooltip]
[helptip]
id="tooltip_large"
[/helptip]
[grid]
[row]
[column]
[image]
label="units/trolls/grunt.png"
[/image]
[/column]
[/row]
[/grid]

</syntaxhighlight>
|}

In the above file, we have just the single function to create our GUI, followed by a return command which makes our function most_basic_gui() available to the [[LuaAPI/wesnoth#wesnoth.require|wesnoth.require()]] function as most_basic_gui().

Our function creates a table containing the definition of a "dialog", and then passes that to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]]. It should be noted that gui.show_dialog does not provide synchronization, so if your GUI makes changes to the game state, you'll need to jump through some hoops or you'll break replays and multiplayer, but that's not something we need to care about at this point, so just be aware that you may need to deal with it in the future.

Our dialog definition at this point includes three parts. The first two are a tooltip and a helptip, which are required and define how tooltips (use id = "tooltip_large" or id = "tooltip" or id = "tooltip_transparent"), and helptips (rarely used, but must be included here, and yes their definitions are "tooltip" not "helptip") will look (as we will see later, this really should be definition = "tooltip", but in this case it's id = "tooltip"). The third part is a grid, which is basically a table, like in HTML or MySQL, with rows and columns. A grid always contains at least one row. A row contains at least one column (note that a column does NOT span rows, it is completely contained within a row). Inside a column is exactly one item, a cell which contains a [[GUIWidgetDefinitionWML|widget]], in this case we'll use an image (later we'll see what else we can put in a cell). Note that we don't actually define a cell in our code, it's just a term used to refer to the contents of a column.

The preshow function is optional. If included in the call to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]], it is run before the GUI is displayed. In this case, we include it to display the dialog we created with lua in WML format. Near the end, in comments, we show how you would call [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] if you chose to define your dialog using WML. Note that what is shown here is the WML equivalent of our lua dialogDefinition, and not the complete WML you would need to use if you were to configure your GUI layout in WML.

Note: if you should try out the above, you'll have to hit escape or enter to close the GUI. Uncomment the "click_dismiss" line, and the user will be able to close the GUI with a mouse click.

===Adding a little flavor===

{|
|You may have noticed our GUI is missing a header and a way to close it when we're done admiring our work. Here we add a new first row to our grid, while demonstrating a couple formatting options: a border to put some distance between our grid cell and its neighbor, and the "use_markup = true" option to enable Pango support in our text.

Our third row adds an OK button at the bottom. You can associate actions with buttons to do all kinds of things, but here we just exploit the default behaviour to close the GUI.

Of course, we'll also have to modify our return to support the new function, and update our menu item(s) accordingly.
|-
|[[File:Most basic gui2.png|center|thumb|Adding header and a footer]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui2()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
gui.show_dialog(dialogDefinition)
end
return { most_basic_gui = most_basic_gui, most_basic_gui2 = most_basic_gui2 }
</syntaxhighlight>

===And a bit more===
{|

|And now a minor, but important change. We want to add a new text field next to the image in the body of our GUI. Obviously, we want to add a new column, but this is more difficult than when we added new rows in the previous example. The problem is that all rows (at a given level) in a grid must contain the same number of columns. We can't have two columns in the row that constitutes the body of our GUI, but only one in the header and one in the footer. To solve this problem, we replace our image widget with a new grid, which can use as many columns as we like (as long as they are the same within each row of our new grid). This new grid contains a row with two columns, but that is okay because the new grid itself is placed in a single column, which matches our single column header and footer (ok button), keeping the rows balanced.
|-
|[[File:Most basic gui3.png|center|thumb|Rows with different numbers of columns]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui3()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column { -- This is the only column in this row,
-- to match the number of columns in
-- the rows of our header and footer
wml.tag.grid { -- A new grid, so we can use a different
-- number of columns
wml.tag.row {
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
},
wml.tag.column {
wml.tag.label {
label = "A troll"
}
}
}
}
}
},
wml.tag.row { -- A footer
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = "Ok"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

While we see here just the simplest of examples, you can many levels of grids in grids, rows with multiple columns some of which containing grids, etc, to build complicated dialogs to your liking.

==Containers==

===Stacked Widget===

TODO

===Listbox===
{|
| Now we'd like to add some more monsters. Obviously, we could just add more rows, but what if we won't know until runtime how many and which ones? We could break up the definition of our dialog and add new rows dynamically, it's just a table after all, but fortunately we have a widget which handles this for us, a listbox. A listbox is kind of like an array, a collection of similar objects where the number of items can vary. We will tell the GUI where we want the box, and what each entry in the box will look like, and then at runtime we can add entries to the box.
|-
| [[File:Gui with listbox.png|center|thumb|Listbox with three items]]

<syntaxhighlight lang=lua>
local function gui_with_listbox()
local monsters = {
{ image = "units/trolls/grunt.png",
string = "A troll" },
{ image = "units/monsters/cuttlefish.png",
string = "A cuttlefish" },
{ image = "units/monsters/yeti.png",
string = "A yeti" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
}

local listboxDefinition = wml.tag.listbox { id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
listboxDefinition
}
},
wml.tag.row {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_label.label = monster.string
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We begin by creating a simple table which represents the data which will be presented in our listbox. In most cases, we probably wouldn't create that monster table here, but we need it for our example.

The variable listbox_id gives us an identifier for our listbox so we can reference it when we need to. We don't really need to use a variable here, it's just convenient.

We define the structure for the elements in our listbox, stored in listboxItem. Note that we've replaced the actual data with identifiers (e.g. 'units/trolls/grunt.png' becomes 'id = "monster_image"), since each element may have different data.

We define the listbox itself, specifying the identifier, and the definition of our listbox element (which looks a lot like a grid). The cell inside the column contains a variable which is just the listbox element definition we created above; it's not necessary to do this, we could have used one big table, but it's easier to read this way (IMO).

We replace the hardcoded data in our GUI body with our new listbox definition, again using a variable to make it easier to read.

We create a function, often called preshow(), which will be called for us as part of the drawing the GUI (see the new optional argument in [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] -- there's also an optional postshow(), but we don't need it here). This is where we pull the data from our example table into the listbox. We create a listbox variable associated with the listbox, identified by the listbox_id we assigned earlier, inside the dialog which gui.show_dialog() passes to preshow(). Then we iterate through our data table, using each entry from that table to populate a listbox item.

Let's look at that last action a little more closely using an example.

<syntaxhighlight lang=lua>
listbox[i].monster_image.label = monster.image
</syntaxhighlight>

Which we can read as "In listbox element i of our listbox, for the image with identifier monster_image which we defined in our listboxItem, use the data from the corresponding index i in our example data table" (you don't see the index i for the monsters table here, but remember we're iterating using ipairs, we could have just as easily used listbox[i].monster_image.label = monsters[i].image). If you were to step through all of the variable substitutions, you'd see that for i=1, our dialogDefinition is basically the same thing as it was in the earlier examples, just supplied from a table instead of hardcoded (note that you can hardcode entries in a listbox in your dialog definition using the [list_data] tag, aka wml.tag.list_data, which we do not demonstrate here).

You will probably notice that our data does not line up nicely in the GUI. We will fix that later. We'll also demonstrate how the user can select an item in a listbox, and how you can identify which item that was using the selected_index variable of the listbox.

===Tree View===
====Simple Tree View====
{|
| You may have noticed that clicking on a listbox item in our listbox caused it to be highlighted with a box around the contents. This is because the items in a listbox are selectable. This will be useful when we want to add actions, but it looks a bit odd if we just want to present a list of data.

Also, most of the data had to be formatted the same for each item in the listbox. We could, perhaps, include custom markup in our labels, but the actual layout, like the number of columns per row, had to be the same for every item.

Another way to present a list of data is the tree view. Since a tree view supports multiple data types, we may need to create multiple definitions for the elements in our list. These are known as nodes. It will also be necessary to explicitly define which node to use for each element when we populate our tree view.
|-
| [[File:Basic tree view.png|center|thumb|Tree_views can hold multiple data types (only trolls have names here)]]
|}
<syntaxhighlight lang=lua line>
local function basic_tree_view()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", type = "Seamonsters" },
{ image = "units/monsters/yeti.png", label = "A yeti",
type = "Coolers" }
}

local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "trolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name",
linked_group = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
},
wml.tag.node {
id = "nottrolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "monster_name",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_image",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_label",
fixed_width = true
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_tv:add_item_of_type("trolls_node")
dialog.monsters_tv[i].monster_name.label = monster.name -- only trolls have a name
else
dialog.monsters_tv:add_item_of_type("nottrolls_node")
end
-- All of our monsters have an image and a label
dialog.monsters_tv[i].monster_image.label = monster.image
dialog.monsters_tv[i].monster_label.label = monster.label
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We have expanded our list of monsters to include three types of trolls. We have also given each troll a name. This is of course a rather simplistic example, we could have simply given each monster that is not a troll an empty name, but it as presented here our approach serves the purpose of demonstrating how we deal with multiple data types. Our new tree view contains a node for each type of data we will present. In preshow, we explicitly define each element in our list using add_item_of_type(), and populate the item accordingly. [Note: in our listbox example, we could have used add_item() to add items to the listbox, but chose not to since that section was already introducing a number of new concepts. But here, since we have multiple types of items we need to be able to specify the type of the item when we add one, hence we need to use add_item_of_type()].

You may also note the addition of a few linked_group lines. We'll cover linked groups in more detail later, but as used here they instruct the GUI that each column using the same node type needs to be aligned with the others. For example, all of our trolls line up nicely.

====Building a Tree====
{|
| colspan="2" |At this point, one may wonder about the name "tree view", since what he have seen doesn't look much like a tree. To make a tree-like structure, we'll demonstrate adding children to nodes. At the top level our (upside-down) tree will have two nodes, one for trolls and one for everything else. A toggle_button (a type of button which changes states when you push it) will allow us to expand the trolls node to expose its children, which are themselves nodes, though they only contain a label at this point.
|-
| [[File:Basic tree view2a.png|center|thumb|Tree_view with Trolls folded]] || [[File:Basic tree view2b.png|center|thumb|Tree_view with Trolls unfolded]]
|}
<syntaxhighlight lang=lua line>
local function building_a_tree()
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
}
},
wml.tag.column {
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Show me the " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
-- You can refer to an object by its position

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[1].race_label.label = "Trolls"
-- dialog.monsters_tv[1].race_button.on_modified =
-- function()dialog.monsters_tv[1].unfolded =
-- dialog.monsters_tv[1].race_button.selected end

-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][1].monster_type.label = "Whelp"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][2].monster_type.label = "Shaman"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][3].monster_type.label = "Troll"

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[2].race_label.label = "Other scary things"
-- dialog.monsters_tv[2].race_button.visible = "hidden"

-- ... or you can refer to that object using the return value
-- from add_item_of_type
local troll_node = dialog.monsters_tv:add_item_of_type("race_node")
troll_node.race_label.label = "Trolls"
troll_node.race_button.on_modified =
function()
troll_node.unfolded = troll_node.race_button.selected
end
local item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Whelp"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Shaman"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Troll"

local not_troll_node =
dialog.monsters_tv:add_item_of_type("race_node")
not_troll_node.race_label.label = "Other scary things"
not_troll_node.race_button.visible = "hidden"

end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We define two nodes in our tree, a race_node for the top level, and a details_node for the children of a race_node. The rest of the interesting bits are in preshow().

We demonstrate two different ways of creating and accessing items, the first (commented out) just using the order in which they are created, while in the second we capture the result of add_item_of_type() in a variable we can use to refer to the newly defined object. The first method is shown primarily to demonstrate the structure of the resulting objects. The second method is perhaps easier to follow, and is almost necessary when you start doing things like dynamically deleting nodes, so it is in most cases a better practice (of course, you probably won't want to use the same variable for each node like we did, and perhaps not one local to the preview function).

We add a node, label it "Trolls", and add a callback to the button such that the children of the node will be visible (the node is "unfolded", a boolean value which defaults to false) when the button is checked (selected == true). Then we add three "details_node" nodes as children of this node.

Our second node, "Other scary things" will remain empty for now, so we'll set the visible attribute on its button to "hidden" (which is like false, but with hidden the widget still takes up space).

{|
| This example is rather ugly, both in the hardwired code and the appearance of the resulting GUI, but it addresses a couple important aspects of how tree views work and how we might use them. Let's clean it up a bit. We'll add an indentation_step_size to the tree view, along with a spacer and [[#Alignment|horizontal_alignment]] to our details node, to make the labels line up nicely, and change the button [[#Definitions|definition]] to replace the checkbox with something that looks like it belongs there. We will look at methods for handling layout in more depth [[#Appearance|later]].
|-
| [[File:Basic tree view2c.png|center|thumb|Our tree_view with proper alignment]]

<syntaxhighlight lang=lua>
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
indentation_step_size = 20,
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
definition = "tree_view_node"
}
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.spacer { width = 40 }
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}

</syntaxhighlight>

===Multi_page===
====Simple Multi_page====
{|
|-
Like a tree_view, a multi_page is a heterogeneous container which is dynamically populated, however, while a multi_page contains multiple elements (pages), only one page is displayed at any one time. Its purpose is perhaps best described by a couple of examples.
|-
[[File:Basic multipage.png|center|thumb|Multi_page showing active page]]
|}
<syntaxhighlight lang=lua>
local function basic_multipage()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll",
name = _"Bob", type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp",
name = "Junior", type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman",
name = _"Alice", type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish",
type = "Seamonsters" },
{ image = "units/monsters/yeti.png",
label = "A yeti",
type = "Coolers" }
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
multi_page
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}

local function preshow(dialog) -- Prepare the GUI before display
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_label.label = monster.label
end
--dialog.monsters_mp.selected_index = 5
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

As you can see, the code for our basic multi_page GUI looks a lot like our basic tree_view GUI. The difference is what is displayed. While both the tree_view and the multi_page containers contain five items, with the multi_page, only the first one is displayed. More specifically, only the page associated with the selected_index attribute of the multi_page object, which defaults to 1, is displayed. If we were to uncomment the last line in preshow(), we would still see only one item, but it would be the fifth one we allocated. It's nice to know all our pages are in there somewhere, but this example is pretty useless. What we need is a way to select which page we want to see from within our GUI.

====A More Useful Multi_page====

{|
| colspan="2" | To demonstrate the usefulness of a multi_page, and highlight its difference from a tree_view, we'll add a listbox to allow us to select the page to view. We'll also need to add a little action to our GUI.
|-
| style="align:centered" |[[File:More useful multipage.png|center|thumb|User selected Troll]] || [[File:More useful multipage2.png|center|thumb|User selected Cuttlefish]]
|}

<syntaxhighlight lang=lua>
local function more_useful_multi_page()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
race = "Trolls", tip = "Your uncle" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
race = "Trolls", tip = "Your nephew" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
race = "Trolls", tip = "Your auntie" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", race = "Seamonsters",
tip = "Not a fish" },
{ image = "units/monsters/yeti.png",
label = "A yeti", race = "Coolers",
tip = "ROAR!" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
}
}
}

local listboxDefinition = wml.tag.listbox {
id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
},
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
listboxDefinition
},
wml.tag.column {
wml.tag.spacer {
width = 30
}
},
wml.tag.column {
multi_page
},
}
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_image.tooltip = monster.tip
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_image.tooltip = monster.tip
dialog.monsters_mp[i].monster_label.label = monster.label
end
local function switch_page()
dialog.monsters_mp.selected_index = listbox.selected_index
end
listbox.on_modified = switch_page
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

Most of this should look pretty familiar. We've simply taken the previous example and added a second column to our GUI using code from an earlier example to add a listbox. In addition, we altered the page layout slightly, and added a spacer column in the dialog definition to approve the appearance.

The interesting stuff is in preshow(). Again we've merged in some listbox code from an earlier example, but we've also created a new local function switch_page(), which simply sets the selected_index attribute of our multi_page to the same as that of our listbox, and then we've configured the listbox.on_modified callback to call switch_page(). Now when the user selects an item in the listbox (updating listbox.selected_index and triggering listbox.on_modified), dialog.monsters_mp.selected_index is updated accordingly and therefore the visible page changes to the one associated with the selected unit.

Also note in preshow() we've added a new child to our monster_image identifier for both the listbox and the multi_page, a tooltip. When the user hovers the mouse over the image of one of our monsters, they'll see a popup message which we've added to our monster table. Try changing '''wml.tag.tooltip { id = "tooltip_large" }''' to '''wml.tag.tooltip { id = "tooltip }''' in the dialogDefinition to see a different tooltip style.

==Actions Have Consequences==

So far, our GUIs have only displayed some information on the screen, but at some point we're probably going to want to use a GUI to get input from the user. In this section we will look at return values that can be assigned to a widget based upon its state, and callbacks, which are functions invoked when something happens with a widget. As we will see, a button is a good example, as it can return a value or take an action, or both, when pressed. Earlier we saw how the selected_index attribute of some widgets, such as the listbox, can also be used as a sort of return value.

===Buttons===
{|
| colspan=2 | In this example, we'll create a couple buttons which provide the user a choice, use a handy confirmation popup to confirm that choice, and demonstrate how we get the results back where we can put them to use.
|-
| [[File:Basic return value.png|center|thumb|There can be only one]] || [[File:Basic return value_confirm.png|center|thumb|The user selected Alice, let's confirm this critical choice]]
|}

<syntaxhighlight lang=lua>
local function basic_return_value()

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "leader_lg",
fixed_height = true,
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" ..
_"Which unit shall lead your army?" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Alice" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/elves-wood/sylph.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 1
}
}
},
}
},
wml.tag.column {
wml.tag.spacer { width = 20 }
},
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Bob" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/human-loyalists/marshal.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 2
}
}
}
}
}
}
}
}
}
}
}
local user_chose = gui.show_dialog(dialogDefinition)
local leader
if user_chose == -1 then -- User closed the dialog by hitting the Enter key
leader = nil
end
if user_chose == -2 then -- User closed the dialog by hitting the Escape key
leader = nil
end

if user_chose == 1 then
leader = "Alice"
end
if user_chose == 2 then
leader = "Bob"
end

local confirmed_leader_choice

if leader ~= nil then
local query = _"You want " .. leader .. _" as your leader?"
confirmed_leader_choice = gui.confirm(query)
end

if confirmed_leader_choice then
wesnoth.message("Great!")
else
wesnoth.message("Fine, lead them yourself!")
end
end
</syntaxhighlight>

Here we've added a couple buttons, and assigned each of them a return value. When the user selects one of these buttons, the GUI is closed and the value of return_value is returned from gui.show_dialog(). We then use [https://wiki.wesnoth.org/LuaAPI/gui#gui.show_prompt gui.confirm()] which provides a very simple Yes/No popup and returns true or false, respectively. Other useful functions can be found on that page which provide handy alternatives to creating your own GUI for other simple user inputs.

The use of return_value is rather limited, as it only returns integers and can't be used with containers like listboxes. In more complex cases we'll need to turn to callback functions which are invoked when something happens to a widget, like clicking a button or a widget's value changing. Earlier, we saw an example of [[LuaAPI/types/widget#on_modified|widget.on_modified()]]. More examples of callbacks can be found at [[LuaAPI/types/widget#on_modified|that link]].

===Slider and Textbox===
{|
| Here we see a couple methods of getting more dynamic input from the user, a slider and a textbox presented in one silly example.
|-
| [[File:Slider and textbox.png|center|thumb|Two ways of getting input from the user]]
|}

<syntaxhighlight lang=lua>
function scrollbar_and_textbox()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = _"How much gold will you pay for this old rusty sword?"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.slider {
id = "gold_sl",
minimum_value = 0,
maximum_value =
wesnoth.sides[wesnoth.current.side].gold,
value = math.floor(
wesnoth.sides[wesnoth.current.side].gold/2)
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.text_box {
id = "gold_tb",
--hint_text = _ "Enter gold here",
--hint_image = "images/gold_pile.png",
label = tostring(math.floor(
wesnoth.sides[wesnoth.current.side].gold/2))
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
local function show_input()
wesnoth.interface.add_chat_message(_"You chose " ..
dialog.gold_sl.value .. _" with the slider")
wesnoth.interface.add_chat_message(_"You entered " ..
tostring(dialog.gold_tb.text) .. _" in the text_box")
end
-- this is a button, so we use on_button_click, not on_left_click
dialog.ok.on_button_click = show_input

dialog.gold_sl.on_modified = function()
dialog.gold_tb.text = tostring(dialog.gold_sl.value)
end
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We create a slider, with a range from 0 to the amount of gold possessed by the current side and an initial value in the middle, and a text box with the same initial value. We assign a function to our OK button which simply reports on the values provided by the user. For no reason whatsoever, we add a callback such that when the user adjusts the slider the value in the textbox is update to match the slider.

Note that the textbox returns text, even though it looks like we're expecting the user to input a natural number. Remember to validate those inputs.

You can use text_hint to place a caption in the box that will help the user understand what to enter in the box, and possibly an image as well. For example, in the search box in the recall menu uses '''hint_text = _ "Search", hint_image = "icons/action/zoomdefault_25.png~FL(horiz)"'''. Of course, you can't have a hint and a label in the same text_box at the same time, so in our example we've only included them as comments.

There is also a widget called a spinner, which is kind of like the combination of a text_box and a slider. As of the release of 1.18, it appears to be unfinished so the strange syntax needed to make it work is probably not the best thing to document, and we will omit it for now.

==Appearance==

'''This section needs help'''

===Borders===

Borders allow you to force unused space around a column, for example so that your widgets don't runtogether. You can specify the border to be one or more of top, bottom, left, right, or all. The border_size sets the amount of padding, in pixels.

<syntaxhighlight lang=lua>
wml.tag.column{
border = "left, right"
border_size = 25
}
</syntaxhighlight>

===Alignment===
{|
| colspan=2 |By default, the GUI will usually center widgets in their cells, which is not always what we want. In this example, we use horizontal_alignment to move widgets around a little.

In more complex cases, it may be useful to add [[GUIWidgetDefinitionWML#Spacer|spacers]] to help force alignment, or use linked_groups to force consistent alignment for objects within a grid.
|-
| [[File:Gui tutorial alignment without.png|center|thumb|Default alignment]] ||[[File:Gui tutorial alignment with.png|center|thumb|Showing off some alignment options]]
|}
<syntaxhighlight lang=lua>
local function basic_alignment()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = "Ralph"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "right",
wml.tag.label {
label = "Sam"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/troll-hero-attack-se-4.png" -- 122x102
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "left",
wml.tag.label {
label = "Jr"
}
},
wml.tag.column {
horizontal_alignment = "right",
wml.tag.image {
label = "units/trolls/whelp.png" -- 72x72
}
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

The screenshots show the output of this example with and without the horizontal_alignment lines included above.

A label allows you to set the text_alignment field (e.g. text_alignment = "left"). Note, however, this only aligns the text within the label. The label itself will probably be centered in the column, giving the false appearance that your text alignment is not working.

===Growth===

To keep your dialog nicely balanced, the GUI2 engine may need to grow rows and/or columns. You can control which columns, for example, grow and which do not, by setting some with grow_factor = 1, and others with grow_factor = 0 (do not grow). While grow factors of 0 and 1 are the most common, you can use other values to adjust the relative growth if you really need to, see [[GUILayout]] for the gory details.

It it sometimes useful to include a column with a [spacer] and a grow_factor (often the only column with grow_factor != 0) whose sole purpose is to keep your GUI aligned nicely as the layout engine does its evil.

To force a column to stretch to fit available space, use horizontal_grow = true. Note that horizontal_grow is not compatible with horizontal_alignment. There is also a vertical_grow parameter.

If you need to see every little detail about the layout process, start wesnoth with --log-debug=gui/layout. Good luck with that.

===Definitions===
Many widgets can be configured to have to a different appearance, for example in our tree_view example we changed the definition of a toggle_button from the default of a checkbox by setting definition = "tree_view_node". This option was found by looking at the id of a toggle_button_definition in .../data/gui/widget/toggle_button_tree_view_node.cfg:

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib
###
### Definition of a toggle button to be used in a tree view as node fold/unfold indicator
###
[toggle_button_definition]
id = "tree_view_node" # <--- we can use 'definition = "tree_view_node"' in a [toggle_button] to select this definition
description = "Fold/unfold status indicator of a tree view node."
</syntaxhighlight>

{|
|There are many other definitions for buttons and other widget types in that directory. It would be nice to have a list (linked here), but for now you'll just have to look around.

We can even create our own custom definitions using [[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition()]]. In this example, we copy from .../data/gui/widget/toggle_button_tree_view_node.cfg with a slight change so that our button turns red ( '''~BLEND(255,0,0,1)''' ) when focused.

In this example, we will use wesnoth.wml_actions to create the WML tag [add_widget_def_demo].

Note the first line, a common convention for creating an alias for wml.tag.
|-
|[[File:Gui tutorial custom widget.png|center|thumb|Different definition of buttons, including one of our own (right)]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag -- save ourselves some typing
function wesnoth.wml_actions.add_widget_def_demo()
local definition = {
id = "tree_view_node_custom",
description = "Fold/unfold status indicator of a tree view node (MODIFIED).",
T.resolution {
min_width = 25,
min_height = 19,
default_width = 25,
default_height = 19,
max_width = 25,
max_height = 19,
-- Unselected - note there's no tags for unselected/selected, that's simply determined by the order
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/fold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/fold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/fold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
-- Selected
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/unfold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
}
}
gui.add_widget_definition("toggle_button", "tree_view_node_custom", definition)

local dialogDefinition = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid {
T.row {
T.column {
T.tag.toggle_button {
definition = "default"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node_custom"
}
}
}
}
gui.show_dialog(dialogDefinition)
end

</syntaxhighlight>

See [[GUIWidgetDefinitionWML]] for more details on widget definitions.

You can also give the whole dialog a definition, like definition = "tooltip_large". There is no gui.add_window_definition(), however a window is technically a type of widget so it may be possible to create your own window definitions (please update this if you do).

===Panels===

===Canvases===
Part of panels? Sort of?

A canvas is a surface you can draw on. A dialog has them, as does a panel, and for these canvas 1 refers to the background, while canvas 2 refers to the foreground. Other widgets may have canvases that may have other meanings, or no canvases at all. See more at [[LuaAPI/gui/widget#set_canvas]].

Here's a fun little trick. Set your dialog background to be transparent:
<syntaxhighlight lang=lua>
local function preshow(dialog)
dialog:set_canvas(1, { } )
end
</syntaxhighlight>

Or, if you want an opaque GUI background with the screen behind it blurred like what you see behind the text of a [message], you can set your window definition to "message":
<syntaxhighlight lang=lua>
...
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
definition = "message",
...
</syntaxhighlight>

{|
|Here we take our [[#Progress Bar|progress bar]], and add a text overlay.

Note: either using text on a canvas is rather limited, or I just couldn't figure it out. For example, I could not get the text size any smaller, and any attempts to do so simply resulted in very blocky text. And the spaces were necessary so that the text wasn't stretched out. I also find it surprising that the progress bar does not have this feature inherently. So it's not a great example, but it should be enough to get you started using canvases. Be sure to visit the [[LuaAPI/gui/widget#set_canvas|link]] mentioned above for more options.
|-
|[[File:Gui tutorial canvas text.png|center|thumb|A progress bar in the background, with text in the foreground]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar_with_overlay()
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.grid {
T.row {
T.column {
T.panel { id = "panel",
T.grid {
T.row {
T.column {
T.button { id = "button",
label =_ "Press me"}
},
T.column {
T.progress_bar { id = "progress" }
},
T.column {
T.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
dialog.panel:set_canvas(2, { T.text { text_alignment = "center", font_size = 48,
text_markup = true, text = " " ..
dialog.progress.percentage .. "% " } } )
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

You may notice we added a panel and placed our text on the foreground canvas(2) on it, since the progress_bar itself does not support canvases.

===Placement===

You may have noticed that all of our dialogs are centered on the screen. This is the default. You can override this and place the dialog wherever you like by setting automatic_placement = false, along with x, y, width, and height at the top level of your dialog definition (next to tooltip =, etc).

'''This part about placement needs review'''
If you prefer, you may replace x and/or y with horizontal_placement and vertical_placement, such as horizontal_placement = "left". You can even set the placement values using WFL, for example horizontal_placement = "(gamemap_width / 3)" -- see [[#Using WFL with GUI2|Using WFL with GUI2]].

==Miscellaneous==

TODO: This stuff doesn't belong in a tutorial. It's worth documenting, but not here. Better to save these here for now than keep them on my laptop.

===Progress Bar===
{|
|A progress_bar is a graphical representation of a percent. In this example, we present the user with a puzzle. They must hit the button repeatedly before they can close the GUI. A progress_bar displays their current progress toward completion.
|-
|[[File:Gui tutorial progress bar.png|center|thumb|upright=2]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.button { id = "button",
label =_ "Press me"
}
},
wml.tag.column {
wml.tag.progress_bar { id = "progress" }
},
wml.tag.column {
wml.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end

gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

===Unit Preview Pane===

{|
|A unit_preview_pane takes a unit (or a unit type), and presents a graphical representation of the unit and its more important attributes, along with tooltips for additional details, in the same way that the recall menu does. Here we see an example of a unit which has picked up some items, including a weapon, which are affecting its stats.
|-
|[[File:Gui tutorial unit preview pane.png|center|thumb]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag

function wesnoth.wml_actions.recall_from_variable(cfg)
local from_array = cfg.from or wml.error(
"[recall_from_variable]: missing required from= ")
local to_var = cfg.to or wml.error(
"[recall_from_variable]: missing required to= ")
local unit_list = wml.array_access.get(from_array) or wml.error(
string.format("[recall_from_variable]: failed to fetch wml array %s",from_array))

local listboxItem = T.grid {
T.row {
T.column {
T.label { id = "available_unit",
linked_group = "available_unit"
}
}
}
}

local listbox_id = "available_units"
local listboxDefinition = T.listbox { id = listbox_id,
T.list_definition {
T.row {
T.column {
T.toggle_panel { listboxItem }
}
}
}
}
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.linked_group { id = "available_unit", fixed_width = true },
T.grid {
T.row { -- header
T.column {
T.grid {
T.row {
T.column {
border = "bottom",
border_size = 10,
T.label {
use_markup = true,
label = ""
.. _"Select unit to recall" .. ""
}
}
}
}
}
},
T.row { -- Body
T.column {
T.grid {
T.row {
T.column {
border = "right",
border_size = 40,
listboxDefinition
},
T.column {
T.unit_preview_pane { id = "unit_preview" }
}
}
}
}
},
T.row { -- Footer
T.column {
T.grid {
T.row {
T.column {
T.spacer { width = 400 }
},
T.column {
border = "top,right",
border_size = 10,
T.button { id = "ok",
label = _"OK"
}
}
}
}
}
}
}
}

local picked = 1

local function preshow(dialog)
local listbox = dialog[listbox_id]
for i,unit in ipairs(unit_list) do
listbox[i].available_unit.label = unit.name .. "(" ..
unit.language_name .. ")"
end
local function draw_unit()
wesnoth.units.to_recall(unit_list[listbox.selected_index])
local tmp = wesnoth.units.find_on_recall{ id =
unit_list[listbox.selected_index].id }[1]
dialog.unit_preview.unit = tmp
wesnoth.units.extract(tmp)
picked = listbox.selected_index
end
draw_unit()
listbox.on_modified = draw_unit
end

gui.show_dialog(dialogDefinition,preshow)

wml.variables[to_var] = picked - 1
end

</syntaxhighlight>

This should all be pretty self evident by now. We are provided with an array of stored units (from [store_unit] in WML). We create a listbox populated with units and we use the selected_index to determine which element in the table to send to unit_preview_pane. Since our input is an array of unit data, not actual units, we use [[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] to take the definition of one from our array and place it on the recall list (turning it into an actual unit), [[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] to fetch that unit in a form that the unit_preview_panel understands, and finally [[wesnoth.units.extract|wesnoth.units.extract]] to remove the unit from the recall list when we are done with it.

And of course we subtract one from the selected_index when we return our choice to WML, since lua arrays count from 1 and WML from 0.

The unit_preview_pane will also accept a unit_type instead of a specific unit.

==Appendix==

===Explore Your Options===

We've seen a lot of options that can be set to modify the behaviour of our dialogs, some on columns, some on widgets, etc. These are in the process of being documented [[GUIWidgetInstanceWML|here]], but if you would like to go straight to the source, the data Wesnoth uses to validate your configuration can be found in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui data/schema/gui] under your install directory.

Let's look at a scroll_label, for example. A scroll_label is a widget, so we look in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/widget_instances.cfg widget_instances.cfg] and find the following. Here we can see five parameters we can provide to our scroll_label (in addition to the ones available to all widgets, like id and definition, see the entry super=... which refers you to the widget_instance in the file [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/generic.cfg data/schema/gui/generic.cfg]), along with their types and default values. For example, we could set "link_aware = true", and if we do not we can assume that link_aware will be false. While this does not explain what these parameters do, the information provided in the schema directory is often helpful nonetheless.

<syntaxhighlight lang=wml>
[tag]
name="scroll_label"
min="0"
max="infinite"
super="$generic/widget_instance"
{DEFAULT_KEY "horizontal_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "vertical_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "wrap" bool true}
{DEFAULT_KEY "text_alignment" f_h_align "left"}
{DEFAULT_KEY "link_aware" bool false}
[/tag]
</syntaxhighlight>

We see that our scrollbars are of type scrollbar_mode. It would probably help if we knew what values are available to the scrollbar_mode. In [https://github.com/wesnoth/wesnoth/tree/master/data/schema/types/gui.cfg data/schema/types/gui.cfg] we find this:

<syntaxhighlight lang=wml>
[type]
name=scrollbar_mode
value="always|never|auto|initial_auto"
[/type]
</syntaxhighlight>

The variable types found in the schema files are described at [[GUIVariable]].

===Using WFL with GUI2===

If you look at the variable type descriptions at [[GUIVariable]] you may notice that many of them start with "f_" and have "or formula" in the description. This means that you can use [[Wesnoth_Formula_Language|Wesnoth Formula Language (WFL)]] formulas in these fields, with certain variables made available to you (which variables and what they mean can be challenging to ascertain, but you can generally figure it out by example).

Looking at [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/window.cfg data/schema/gui/window.cfg] we see that 'height' has type f_unsigned, which tells us that height is an unsigned integer, and that we can use a WFL formula to define it in a window_definition. In [https://github.com/wesnoth/wesnoth/tree/master/data/gui/themes/default/window/wml_message.cfg data/gui/window/wml_message.cfg] (data/gui/themes/default/window/wml_message.cfg starting around 1.19.2), we find the line '''height = "(screen_height - 30)"'''. This does exactly what it looks like, it sets the height of our window to 30 pixels less than the height of the screen.

===Useful Links===

[[LuaAPI/gui|LuaAPI/gui - Mostly about opening windows]] 
[[LuaAPI/types/widget|LuaAPI/types/widget - Widget attributes and callbacks]] 
[https://wiki.wesnoth.org/Category:GUI_WML_Reference GUI_WML_Reference] 
[https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui .../data/schema/gui/*.cfg] - Lists of valid options for various GUI objects 
[https://devdocs.wesnoth.org/layout_algorithm.html Layout Algorithm] - For windows, at least

===Credits===

The basic framework that composes the initial examples was lifted from LotI. It's a great place to find well written examples, but some of it is complex enough to be a little overwhelming when getting started.

Many examples, particularly tree view and multipage, are heavily derived from the World Conquest multiplayer campaign.

Sandbox/GUI/Getting Started

2024-09-01T16:21:49Z

White haired uncle: /* Placement */

So, it looks like I can't exclude this page/section from the search engine as I had hoped. I wanted to put this in a sandbox so that it wouldn't be published without some proper review.

==Introduction==

This guide is designed to help you get a simple Wesnoth GUI, implemented in lua, up and running while describing the basic building blocks along the way. It is written in a narrative format, where most examples build on previous examples, and therefore while not always necessary it may be desirable to read from start to finish. The reader, probably a UMC author, should have a basic knowledge of working with lua within Wesnoth.

Some would find creating a GUI in part or in full using WML simpler to follow, and those alternatives are available, for example [[LuaAPI/gui/example]], but we're using lua here. If you find WML easier to follow, you can always convert the lua tables that define the GUIs to WML using [[LuaAPI/wml#wml.tostring|wml.tostring]], for example:

<syntaxhighlight lang=lua>
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
</syntaxhighlight>

In some examples, instead of defining the entire GUI at once, we'll break out some parts into separate variables. If you try to view one in WML and get an error from wml.tostring() about expecting a WML table and not a table, try passing your variable(/table) inside a table:

<syntaxhighlight lang=lua>
print(wml.tostring({listboxItem}))
gui.show_lua_console()
</syntaxhighlight>

One distinct advantage of using WML to define your GUI layout is that you get better (any) validation. Invalid keys, and sometimes values, are often flagged in the log, unlike with lua where they are silently ignored. In the comments of our first GUI, below, is an example which loads a WML GUI configuration using [[LuaAPI/wml#wml.load|wml.load()]], validating against the GUI2 window schema.

===What is GUI2?===
Once upon a time, Wesnoth had a GUI system which is now commonly referred to as GUI1. As of 1.19, GUI1 has been almost completely replaced by GUI2. UMC authors will probably never encounter GUI1 and can simply use the terms GUI and GUI2 interchangeably, at least until GUI3 comes along.

Instead of spending a lot of time here giving an overview of what GUI2 is and what makes it great, and not so great, let's charge ahead so we can see it in action, and let readers who are interested look elsewhere(TODO: link) for a more formal definition. (TODO: is this the right approach for most readers?).

==Getting Started==

For example purposes, we'll create a directory in our campaign directory called lua containing a file called gui_tutorial.lua, and add a command in the prestart event for a scenario which will create a right-click menu option to invoke our new GUI. Of course there are other methods to invoke lua from WML, but this one will get us started. After all, we really just want to get something up on the screen ASAP, right?

===A most basic GUI===

{|
|[[File:Most basic gui.png|center|thumb|I can't believe this worked]]
|-
|In our prestart event, we create a simple menu item, which executes a single line of lua which calls the lua function most_basic_gui() which is found in gui_tutorial.lua:
|}

<syntaxhighlight lang=wml>
[set_menu_item]
id=most_basic_gui
description="Our first GUI"
[command]
[lua]
code=<<
wesnoth.require("~add-ons/<OUR_CAMPAIGN>/lua/gui_tutorial.lua").most_basic_gui()
>>
[/lua]
[/command]
[/set_menu_item]
</syntaxhighlight>

And create gui_tutorial.lua:
{| class="wikitable" style="margin:auto"
! !! The WML equivalent of dialogDefinition
|-
|
<syntaxhighlight lang=lua>
local function most_basic_gui()
local dialogDefinition = {
--click_dismiss = true, -- allow user to close dialog with click of a button
wml.tag.tooltip { id = "tooltip_large" }, -- required
wml.tag.helptip { id = "tooltip_large" }, -- required
wml.tag.grid { -- our most basic gui
wml.tag.row { -- a grid must include at least one row
wml.tag.column { -- a row needs a column
wml.tag.image { -- a column includes exactly one widget
label = "units/trolls/grunt.png"
}
}
}
}
}

local function preshow(dialog)
print(wml.tostring(dialogDefinition))
gui.show_lua_console()
end
gui.show_dialog(dialogDefinition,preshow)

-- Or, if you want to define the gui in WML, something like:
-- local dialog_wml = wml.load("~add-ons/GUI_Tutorial/most_basic_gui.cfg",
-- true, "schema/gui_window.cfg")
-- gui.show_dialog(wml.get_child(dialog_wml, 'resolution'))
end
return { most_basic_gui = most_basic_gui}
</syntaxhighlight>
|
<syntaxhighlight lang=wml>
[tooltip]
id="tooltip_large"
[/tooltip]
[helptip]
id="tooltip_large"
[/helptip]
[grid]
[row]
[column]
[image]
label="units/trolls/grunt.png"
[/image]
[/column]
[/row]
[/grid]

</syntaxhighlight>
|}

In the above file, we have just the single function to create our GUI, followed by a return command which makes our function most_basic_gui() available to the [[LuaAPI/wesnoth#wesnoth.require|wesnoth.require()]] function as most_basic_gui().

Our function creates a table containing the definition of a "dialog", and then passes that to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]]. It should be noted that gui.show_dialog does not provide synchronization, so if your GUI makes changes to the game state, you'll need to jump through some hoops or you'll break replays and multiplayer, but that's not something we need to care about at this point, so just be aware that you may need to deal with it in the future.

Our dialog definition at this point includes three parts. The first two are a tooltip and a helptip, which are required and define how tooltips (use id = "tooltip_large" or id = "tooltip" or id = "tooltip_transparent"), and helptips (rarely used, but must be included here, and yes their definitions are "tooltip" not "helptip") will look (as we will see later, this really should be definition = "tooltip", but in this case it's id = "tooltip"). The third part is a grid, which is basically a table, like in HTML or MySQL, with rows and columns. A grid always contains at least one row. A row contains at least one column (note that a column does NOT span rows, it is completely contained within a row). Inside a column is exactly one item, a cell which contains a [[GUIWidgetDefinitionWML|widget]], in this case we'll use an image (later we'll see what else we can put in a cell). Note that we don't actually define a cell in our code, it's just a term used to refer to the contents of a column.

The preshow function is optional. If included in the call to [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]], it is run before the GUI is displayed. In this case, we include it to display the dialog we created with lua in WML format. Near the end, in comments, we show how you would call [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] if you chose to define your dialog using WML. Note that what is shown here is the WML equivalent of our lua dialogDefinition, and not the complete WML you would need to use if you were to configure your GUI layout in WML.

Note: if you should try out the above, you'll have to hit escape or enter to close the GUI. Uncomment the "click_dismiss" line, and the user will be able to close the GUI with a mouse click.

===Adding a little flavor===

{|
|You may have noticed our GUI is missing a header and a way to close it when we're done admiring our work. Here we add a new first row to our grid, while demonstrating a couple formatting options: a border to put some distance between our grid cell and its neighbor, and the "use_markup = true" option to enable Pango support in our text.

Our third row adds an OK button at the bottom. You can associate actions with buttons to do all kinds of things, but here we just exploit the default behaviour to close the GUI.

Of course, we'll also have to modify our return to support the new function, and update our menu item(s) accordingly.
|-
|[[File:Most basic gui2.png|center|thumb|Adding header and a footer]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui2()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
gui.show_dialog(dialogDefinition)
end
return { most_basic_gui = most_basic_gui, most_basic_gui2 = most_basic_gui2 }
</syntaxhighlight>

===And a bit more===
{|

|And now a minor, but important change. We want to add a new text field next to the image in the body of our GUI. Obviously, we want to add a new column, but this is more difficult than when we added new rows in the previous example. The problem is that all rows (at a given level) in a grid must contain the same number of columns. We can't have two columns in the row that constitutes the body of our GUI, but only one in the header and one in the footer. To solve this problem, we replace our image widget with a new grid, which can use as many columns as we like (as long as they are the same within each row of our new grid). This new grid contains a row with two columns, but that is okay because the new grid itself is placed in a single column, which matches our single column header and footer (ok button), keeping the rows balanced.
|-
|[[File:Most basic gui3.png|center|thumb|Rows with different numbers of columns]]
|}
<syntaxhighlight lang=lua>
local function most_basic_gui3()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "helptip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column { -- This is the only column in this row,
-- to match the number of columns in
-- the rows of our header and footer
wml.tag.grid { -- A new grid, so we can use a different
-- number of columns
wml.tag.row {
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
},
wml.tag.column {
wml.tag.label {
label = "A troll"
}
}
}
}
}
},
wml.tag.row { -- A footer
wml.tag.column { -- An "OK" button, with no action assigned for now,
-- but it will close the GUI
wml.tag.button {
id = "ok",
label = "Ok"
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

While we see here just the simplest of examples, you can many levels of grids in grids, rows with multiple columns some of which containing grids, etc, to build complicated dialogs to your liking.

==Containers==

===Stacked Widget===

TODO

===Listbox===
{|
| Now we'd like to add some more monsters. Obviously, we could just add more rows, but what if we won't know until runtime how many and which ones? We could break up the definition of our dialog and add new rows dynamically, it's just a table after all, but fortunately we have a widget which handles this for us, a listbox. A listbox is kind of like an array, a collection of similar objects where the number of items can vary. We will tell the GUI where we want the box, and what each entry in the box will look like, and then at runtime we can add entries to the box.
|-
| [[File:Gui with listbox.png|center|thumb|Listbox with three items]]

<syntaxhighlight lang=lua>
local function gui_with_listbox()
local monsters = {
{ image = "units/trolls/grunt.png",
string = "A troll" },
{ image = "units/monsters/cuttlefish.png",
string = "A cuttlefish" },
{ image = "units/monsters/yeti.png",
string = "A yeti" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
}

local listboxDefinition = wml.tag.listbox { id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
listboxDefinition
}
},
wml.tag.row {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_label.label = monster.string
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We begin by creating a simple table which represents the data which will be presented in our listbox. In most cases, we probably wouldn't create that monster table here, but we need it for our example.

The variable listbox_id gives us an identifier for our listbox so we can reference it when we need to. We don't really need to use a variable here, it's just convenient.

We define the structure for the elements in our listbox, stored in listboxItem. Note that we've replaced the actual data with identifiers (e.g. 'units/trolls/grunt.png' becomes 'id = "monster_image"), since each element may have different data.

We define the listbox itself, specifying the identifier, and the definition of our listbox element (which looks a lot like a grid). The cell inside the column contains a variable which is just the listbox element definition we created above; it's not necessary to do this, we could have used one big table, but it's easier to read this way (IMO).

We replace the hardcoded data in our GUI body with our new listbox definition, again using a variable to make it easier to read.

We create a function, often called preshow(), which will be called for us as part of the drawing the GUI (see the new optional argument in [[LuaAPI/gui#gui.show_dialog|gui.show_dialog()]] -- there's also an optional postshow(), but we don't need it here). This is where we pull the data from our example table into the listbox. We create a listbox variable associated with the listbox, identified by the listbox_id we assigned earlier, inside the dialog which gui.show_dialog() passes to preshow(). Then we iterate through our data table, using each entry from that table to populate a listbox item.

Let's look at that last action a little more closely using an example.

<syntaxhighlight lang=lua>
listbox[i].monster_image.label = monster.image
</syntaxhighlight>

Which we can read as "In listbox element i of our listbox, for the image with identifier monster_image which we defined in our listboxItem, use the data from the corresponding index i in our example data table" (you don't see the index i for the monsters table here, but remember we're iterating using ipairs, we could have just as easily used listbox[i].monster_image.label = monsters[i].image). If you were to step through all of the variable substitutions, you'd see that for i=1, our dialogDefinition is basically the same thing as it was in the earlier examples, just supplied from a table instead of hardcoded (note that you can hardcode entries in a listbox in your dialog definition using the [list_data] tag, aka wml.tag.list_data, which we do not demonstrate here).

You will probably notice that our data does not line up nicely in the GUI. We will fix that later. We'll also demonstrate how the user can select an item in a listbox, and how you can identify which item that was using the selected_index variable of the listbox.

===Tree View===
====Simple Tree View====
{|
| You may have noticed that clicking on a listbox item in our listbox caused it to be highlighted with a box around the contents. This is because the items in a listbox are selectable. This will be useful when we want to add actions, but it looks a bit odd if we just want to present a list of data.

Also, most of the data had to be formatted the same for each item in the listbox. We could, perhaps, include custom markup in our labels, but the actual layout, like the number of columns per row, had to be the same for every item.

Another way to present a list of data is the tree view. Since a tree view supports multiple data types, we may need to create multiple definitions for the elements in our list. These are known as nodes. It will also be necessary to explicitly define which node to use for each element when we populate our tree view.
|-
| [[File:Basic tree view.png|center|thumb|Tree_views can hold multiple data types (only trolls have names here)]]
|}
<syntaxhighlight lang=lua line>
local function basic_tree_view()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", type = "Seamonsters" },
{ image = "units/monsters/yeti.png", label = "A yeti",
type = "Coolers" }
}

local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "trolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name",
linked_group = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
},
wml.tag.node {
id = "nottrolls_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "monster_name",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_image",
fixed_width = true
},
wml.tag.linked_group {
id = "monster_label",
fixed_width = true
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_tv:add_item_of_type("trolls_node")
dialog.monsters_tv[i].monster_name.label = monster.name -- only trolls have a name
else
dialog.monsters_tv:add_item_of_type("nottrolls_node")
end
-- All of our monsters have an image and a label
dialog.monsters_tv[i].monster_image.label = monster.image
dialog.monsters_tv[i].monster_label.label = monster.label
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

We have expanded our list of monsters to include three types of trolls. We have also given each troll a name. This is of course a rather simplistic example, we could have simply given each monster that is not a troll an empty name, but it as presented here our approach serves the purpose of demonstrating how we deal with multiple data types. Our new tree view contains a node for each type of data we will present. In preshow, we explicitly define each element in our list using add_item_of_type(), and populate the item accordingly. [Note: in our listbox example, we could have used add_item() to add items to the listbox, but chose not to since that section was already introducing a number of new concepts. But here, since we have multiple types of items we need to be able to specify the type of the item when we add one, hence we need to use add_item_of_type()].

You may also note the addition of a few linked_group lines. We'll cover linked groups in more detail later, but as used here they instruct the GUI that each column using the same node type needs to be aligned with the others. For example, all of our trolls line up nicely.

====Building a Tree====
{|
| colspan="2" |At this point, one may wonder about the name "tree view", since what he have seen doesn't look much like a tree. To make a tree-like structure, we'll demonstrate adding children to nodes. At the top level our (upside-down) tree will have two nodes, one for trolls and one for everything else. A toggle_button (a type of button which changes states when you push it) will allow us to expand the trolls node to expose its children, which are themselves nodes, though they only contain a label at this point.
|-
| [[File:Basic tree view2a.png|center|thumb|Tree_view with Trolls folded]] || [[File:Basic tree view2b.png|center|thumb|Tree_view with Trolls unfolded]]
|}
<syntaxhighlight lang=lua line>
local function building_a_tree()
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
}
},
wml.tag.column {
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Show me the " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
tree_view
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
-- You can refer to an object by its position

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[1].race_label.label = "Trolls"
-- dialog.monsters_tv[1].race_button.on_modified =
-- function()dialog.monsters_tv[1].unfolded =
-- dialog.monsters_tv[1].race_button.selected end

-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][1].monster_type.label = "Whelp"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][2].monster_type.label = "Shaman"
-- dialog.monsters_tv[1]:add_item_of_type("details_node")
-- dialog.monsters_tv[1][3].monster_type.label = "Troll"

-- dialog.monsters_tv:add_item_of_type("race_node")
-- dialog.monsters_tv[2].race_label.label = "Other scary things"
-- dialog.monsters_tv[2].race_button.visible = "hidden"

-- ... or you can refer to that object using the return value
-- from add_item_of_type
local troll_node = dialog.monsters_tv:add_item_of_type("race_node")
troll_node.race_label.label = "Trolls"
troll_node.race_button.on_modified =
function()
troll_node.unfolded = troll_node.race_button.selected
end
local item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Whelp"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Shaman"
item = troll_node:add_item_of_type("details_node")
item.monster_type.label = "Troll"

local not_troll_node =
dialog.monsters_tv:add_item_of_type("race_node")
not_troll_node.race_label.label = "Other scary things"
not_troll_node.race_button.visible = "hidden"

end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We define two nodes in our tree, a race_node for the top level, and a details_node for the children of a race_node. The rest of the interesting bits are in preshow().

We demonstrate two different ways of creating and accessing items, the first (commented out) just using the order in which they are created, while in the second we capture the result of add_item_of_type() in a variable we can use to refer to the newly defined object. The first method is shown primarily to demonstrate the structure of the resulting objects. The second method is perhaps easier to follow, and is almost necessary when you start doing things like dynamically deleting nodes, so it is in most cases a better practice (of course, you probably won't want to use the same variable for each node like we did, and perhaps not one local to the preview function).

We add a node, label it "Trolls", and add a callback to the button such that when the button is checked (selected), the children of the node will be visible (the node is "unfolded", a boolean value which defaults to false). Then we add three nodes as children of this node.

Our second node, "Other scary things" will remain empty for now, so we'll set the visible attribute on its button to "hidden" (which is like false, but with hidden the widget still takes up space).

{|
| This example is rather ugly, both in the hardwired code and the appearance of the resulting GUI, but it addresses a couple important aspects of how tree views work and how we might use them. Let's clean it up a bit. We'll add an indentation_step_size to the tree view, along with a spacer and [[#Alignment|horizontal_alignment]] to our details node, to make the labels line up nicely, and change the button [[#Definitions|definition]] to replace the checkbox with something that looks like it belongs there. We will look at methods for handling layout in more depth [[#Appearance|later]].
|-
| [[File:Basic tree view2c.png|center|thumb|Our tree_view with proper alignment]]

<syntaxhighlight lang=lua>
local tree_view = wml.tag.tree_view {
id = "monsters_tv",
indentation_step_size = 20,
wml.tag.node {
id = "race_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_button {
id = "race_button",
definition = "tree_view_node"
}
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "race_label",
}
}
}
}
},
wml.tag.node {
id = "details_node",
wml.tag.node_definition {
wml.tag.row {
wml.tag.column {
wml.tag.spacer { width = 40 }
},
wml.tag.column {
horizontal_alignment = "left",
grow_factor = 1,
wml.tag.label {
id = "monster_type",
}
}
}
}
}
}

</syntaxhighlight>

===Multi_page===
====Simple Multi_page====
{|
|-
Like a tree_view, a multi_page is a heterogeneous container which is dynamically populated, however, while a multi_page contains multiple elements (pages), only one page is displayed at any one time. Its purpose is perhaps best described by a couple of examples.
|-
[[File:Basic multipage.png|center|thumb|Multi_page showing active page]]
|}
<syntaxhighlight lang=lua>
local function basic_multipage()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll",
name = _"Bob", type = "Trolls" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp",
name = "Junior", type = "Trolls" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman",
name = _"Alice", type = "Trolls" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish",
type = "Seamonsters" },
{ image = "units/monsters/yeti.png",
label = "A yeti",
type = "Coolers" }
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image",
linked_group = "monster_image"
}
},
wml.tag.column {
wml.tag.label {
id = "monster_label",
linked_group = "monster_label"
}
}
}
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
multi_page
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}

local function preshow(dialog) -- Prepare the GUI before display
for i, monster in ipairs(monsters) do
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_label.label = monster.label
end
--dialog.monsters_mp.selected_index = 5
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

As you can see, the code for our basic multi_page GUI looks a lot like our basic tree_view GUI. The difference is what is displayed. While both the tree_view and the multi_page containers contain five items, with the multi_page, only the first one is displayed. More specifically, only the page associated with the selected_index attribute of the multi_page object, which defaults to 1, is displayed. If we were to uncomment the last line in preshow(), we would still see only one item, but it would be the fifth one we allocated. It's nice to know all our pages are in there somewhere, but this example is pretty useless. What we need is a way to select which page we want to see from within our GUI.

====A More Useful Multi_page====

{|
| colspan="2" | To demonstrate the usefulness of a multi_page, and highlight its difference from a tree_view, we'll add a listbox to allow us to select the page to view. We'll also need to add a little action to our GUI.
|-
| style="align:centered" |[[File:More useful multipage.png|center|thumb|User selected Troll]] || [[File:More useful multipage2.png|center|thumb|User selected Cuttlefish]]
|}

<syntaxhighlight lang=lua>
local function more_useful_multi_page()
local monsters = {
{ image = "units/trolls/grunt.png",
label = "A troll", name = _"Bob",
race = "Trolls", tip = "Your uncle" },
{ image = "units/trolls/whelp.png",
label = "A troll whelp", name = "Junior",
race = "Trolls", tip = "Your nephew" },
{ image = "units/trolls/shaman.png",
label = "A troll shaman", name = _"Alice",
race = "Trolls", tip = "Your auntie" },
{ image = "units/monsters/cuttlefish.png",
label = "A cuttlefish", race = "Seamonsters",
tip = "Not a fish" },
{ image = "units/monsters/yeti.png",
label = "A yeti", race = "Coolers",
tip = "ROAR!" }
}

local listbox_id = "monsters"

local listboxItem = wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
}
}
}

local listboxDefinition = wml.tag.listbox {
id = listbox_id,
wml.tag.list_definition {
wml.tag.row {
wml.tag.column {
wml.tag.toggle_panel {
listboxItem
}
}
}
}
}

local multi_page = wml.tag.multi_page {
id = "monsters_mp",
wml.tag.page_definition {
id = "trolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_name"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
}
},
wml.tag.page_definition {
id = "nottrolls_page",
wml.tag.row {
wml.tag.column {
wml.tag.image {
id = "monster_image"
}
},
},
wml.tag.row {
wml.tag.column {
wml.tag.label {
id = "monster_label"
}
}
},
}
}

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" .. _"Here there be " ..
"" ..
_"MONSTERS!" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
listboxDefinition
},
wml.tag.column {
wml.tag.spacer {
width = 30
}
},
wml.tag.column {
multi_page
},
}
}
}
},
wml.tag.row {
wml.tag.column { -- An "OK" button
wml.tag.button {
id = "ok",
label = _"OK"
},
}
}
}
}
local function preshow(dialog) -- Prepare the GUI before display
local listbox = dialog[listbox_id]
for i, monster in ipairs(monsters) do
listbox[i].monster_image.label = monster.image
listbox[i].monster_image.tooltip = monster.tip
if monster.type == "Trolls" then
dialog.monsters_mp:add_item_of_type("trolls_page")
dialog.monsters_mp[i].monster_name.label = monster.name
else
dialog.monsters_mp:add_item_of_type("nottrolls_page")
end
dialog.monsters_mp[i].monster_image.label = monster.image
dialog.monsters_mp[i].monster_image.tooltip = monster.tip
dialog.monsters_mp[i].monster_label.label = monster.label
end
local function switch_page()
dialog.monsters_mp.selected_index = listbox.selected_index
end
listbox.on_modified = switch_page
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

Most of this should look pretty familiar. We've simply taken the previous example and added a second column to our GUI using code from an earlier example to add a listbox. In addition, we altered the page layout slightly, and added a spacer column in the dialog definition to approve the appearance.

The interesting stuff is in preshow(). Again we've merged in some listbox code from an earlier example, but we've also created a new local function switch_page(), which simply sets the selected_index attribute of our multi_page to the same as that of our listbox, and then we've configured the listbox.on_modified callback to call switch_page(). Now when the user selects an item in the listbox (updating listbox.selected_index and triggering listbox.on_modified), dialog.monsters_mp.selected_index is updated accordingly and therefore the visible page changes to the one associated with the selected unit.

Also note in preshow() we've added a new child to our monster_image identifier for both the listbox and the multi_page, a tooltip. When the user hovers the mouse over the image of one of our monsters, they'll see a popup message which we've added to our monster table. Try changing '''wml.tag.tooltip { id = "tooltip_large" }''' to '''wml.tag.tooltip { id = "tooltip }''' in the dialogDefinition to see a different tooltip style.

==Actions Have Consequences==

So far, our GUIs have only displayed some information on the screen, but at some point we're probably going to want to use a GUI to get input from the user. In this section we will look at return values that can be assigned to a widget based upon its state, and callbacks, which are functions invoked when something happens with a widget. As we will see, a button is a good example, as it can return a value or take an action, or both, when pressed. Earlier we saw how the selected_index attribute of some widgets, such as the listbox, can also be used as a sort of return value.

===Buttons===
{|
| colspan=2 | In this example, we'll create a couple buttons which provide the user a choice, use a handy confirmation popup to confirm that choice, and demonstrate how we get the results back where we can put them to use.
|-
| [[File:Basic return value.png|center|thumb|There can be only one]] || [[File:Basic return value_confirm.png|center|thumb|The user selected Alice, let's confirm this critical choice]]
|}

<syntaxhighlight lang=lua>
local function basic_return_value()

local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.linked_group {
id = "leader_lg",
fixed_height = true,
},
wml.tag.grid {
wml.tag.row { -- A header
wml.tag.column {
border = "bottom",
border_size = 10,
wml.tag.label {
use_markup = true,
label = "" ..
_"Which unit shall lead your army?" .. ""
}
}
},
wml.tag.row { -- The body of our GUI
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Alice" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/elves-wood/sylph.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 1
}
}
},
}
},
wml.tag.column {
wml.tag.spacer { width = 20 }
},
wml.tag.column {
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label { label = "Bob" }
}
},
wml.tag.row {
wml.tag.column {
wml.tag.image {
linked_group = "leader_lg",
label = "units/human-loyalists/marshal.png"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
label = "Select",
return_value = 2
}
}
}
}
}
}
}
}
}
}
}
local user_chose = gui.show_dialog(dialogDefinition)
local leader
if user_chose == -1 then -- User closed the dialog by hitting the Enter key
leader = nil
end
if user_chose == -2 then -- User closed the dialog by hitting the Escape key
leader = nil
end

if user_chose == 1 then
leader = "Alice"
end
if user_chose == 2 then
leader = "Bob"
end

local confirmed_leader_choice

if leader ~= nil then
local query = _"You want " .. leader .. _" as your leader?"
confirmed_leader_choice = gui.confirm(query)
end

if confirmed_leader_choice then
wesnoth.message("Great!")
else
wesnoth.message("Fine, lead them yourself!")
end
end
</syntaxhighlight>

Here we've added a couple buttons, and assigned each of them a return value. When the user selects one of these buttons, the GUI is closed and the value of return_value is returned from gui.show_dialog(). We then use [https://wiki.wesnoth.org/LuaAPI/gui#gui.show_prompt gui.confirm()] which provides a very simple Yes/No popup and returns true or false, respectively. Other useful functions can be found on that page which provide handy alternatives to creating your own GUI for other simple user inputs.

The use of return_value is rather limited, as it only returns integers and can't be used with containers like listboxes. In more complex cases we'll need to turn to callback functions which are invoked when something happens to a widget, like clicking a button or a widget's value changing. Earlier, we saw an example of [[LuaAPI/types/widget#on_modified|widget.on_modified()]]. More examples of callbacks can be found at [[LuaAPI/types/widget#on_modified|that link]].

===Slider and Textbox===
{|
| Here we see a couple methods of getting more dynamic input from the user, a slider and a textbox presented in one silly example.
|-
| [[File:Slider and textbox.png|center|thumb|Two ways of getting input from the user]]
|}

<syntaxhighlight lang=lua>
function scrollbar_and_textbox()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = _"How much gold will you pay for this old rusty sword?"
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.slider {
id = "gold_sl",
minimum_value = 0,
maximum_value =
wesnoth.sides[wesnoth.current.side].gold,
value = math.floor(
wesnoth.sides[wesnoth.current.side].gold/2)
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.text_box {
id = "gold_tb",
--hint_text = _ "Enter gold here",
--hint_image = "images/gold_pile.png",
label = tostring(math.floor(
wesnoth.sides[wesnoth.current.side].gold/2))
}
}
},
wml.tag.row {
wml.tag.column {
wml.tag.button {
id = "ok",
label = _"OK"
}
}
}
}
}
local function preshow(dialog)
local function show_input()
wesnoth.interface.add_chat_message(_"You chose " ..
dialog.gold_sl.value .. _" with the slider")
wesnoth.interface.add_chat_message(_"You entered " ..
tostring(dialog.gold_tb.text) .. _" in the text_box")
end
-- this is a button, so we use on_button_click, not on_left_click
dialog.ok.on_button_click = show_input

dialog.gold_sl.on_modified = function()
dialog.gold_tb.text = tostring(dialog.gold_sl.value)
end
end
gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

We create a slider, with a range from 0 to the amount of gold possessed by the current side and an initial value in the middle, and a text box with the same initial value. We assign a function to our OK button which simply reports on the values provided by the user. For no reason whatsoever, we add a callback such that when the user adjusts the slider the value in the textbox is update to match the slider.

Note that the textbox returns text, even though it looks like we're expecting the user to input a natural number. Remember to validate those inputs.

You can use text_hint to place a caption in the box that will help the user understand what to enter in the box, and possibly an image as well. For example, in the search box in the recall menu uses '''hint_text = _ "Search", hint_image = "icons/action/zoomdefault_25.png~FL(horiz)"'''. Of course, you can't have a hint and a label in the same text_box at the same time, so in our example we've only included them as comments.

There is also a widget called a spinner, which is kind of like the combination of a text_box and a slider. As of the release of 1.18, it appears to be unfinished so the strange syntax needed to make it work is probably not the best thing to document, and we will omit it for now.

==Appearance==

'''This section needs help'''

===Borders===

Borders allow you to force unused space around a column, for example so that your widgets don't runtogether. You can specify the border to be one or more of top, bottom, left, right, or all. The border_size sets the amount of padding, in pixels.

<syntaxhighlight lang=lua>
wml.tag.column{
border = "left, right"
border_size = 25
}
</syntaxhighlight>

===Alignment===
{|
| colspan=2 |By default, the GUI will usually center widgets in their cells, which is not always what we want. In this example, we use horizontal_alignment to move widgets around a little.

In more complex cases, it may be useful to add [[GUIWidgetDefinitionWML#Spacer|spacers]] to help force alignment, or use linked_groups to force consistent alignment for objects within a grid.
|-
| [[File:Gui tutorial alignment without.png|center|thumb|Default alignment]] ||[[File:Gui tutorial alignment with.png|center|thumb|Showing off some alignment options]]
|}
<syntaxhighlight lang=lua>
local function basic_alignment()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.label {
label = "Ralph"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/grunt.png"
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "right",
wml.tag.label {
label = "Sam"
}
},
wml.tag.column {
wml.tag.image {
label = "units/trolls/troll-hero-attack-se-4.png" -- 122x102
}
}
},
wml.tag.row {
wml.tag.column {
horizontal_alignment = "left",
wml.tag.label {
label = "Jr"
}
},
wml.tag.column {
horizontal_alignment = "right",
wml.tag.image {
label = "units/trolls/whelp.png" -- 72x72
}
}
}
}
}
}
gui.show_dialog(dialogDefinition)
end
</syntaxhighlight>

The screenshots show the output of this example with and without the horizontal_alignment lines included above.

A label allows you to set the text_alignment field (e.g. text_alignment = "left"). Note, however, this only aligns the text within the label. The label itself will probably be centered in the column, giving the false appearance that your text alignment is not working.

===Growth===

To keep your dialog nicely balanced, the GUI2 engine may need to grow rows and/or columns. You can control which columns, for example, grow and which do not, by setting some with grow_factor = 1, and others with grow_factor = 0 (do not grow). While grow factors of 0 and 1 are the most common, you can use other values to adjust the relative growth if you really need to, see [[GUILayout]] for the gory details.

It it sometimes useful to include a column with a [spacer] and a grow_factor (often the only column with grow_factor != 0) whose sole purpose is to keep your GUI aligned nicely as the layout engine does its evil.

To force a column to stretch to fit available space, use horizontal_grow = true. Note that horizontal_grow is not compatible with horizontal_alignment. There is also a vertical_grow parameter.

If you need to see every little detail about the layout process, start wesnoth with --log-debug=gui/layout. Good luck with that.

===Definitions===
Many widgets can be configured to have to a different appearance, for example in our tree_view example we changed the definition of a toggle_button from the default of a checkbox by setting definition = "tree_view_node". This option was found by looking at the id of a toggle_button_definition in .../data/gui/widget/toggle_button_tree_view_node.cfg:

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib
###
### Definition of a toggle button to be used in a tree view as node fold/unfold indicator
###
[toggle_button_definition]
id = "tree_view_node" # <--- we can use 'definition = "tree_view_node"' in a [toggle_button] to select this definition
description = "Fold/unfold status indicator of a tree view node."
</syntaxhighlight>

{|
|There are many other definitions for buttons and other widget types in that directory. It would be nice to have a list (linked here), but for now you'll just have to look around.

We can even create our own custom definitions using [[LuaAPI/gui#gui.add_widget_definition|gui.add_widget_definition()]]. In this example, we copy from .../data/gui/widget/toggle_button_tree_view_node.cfg with a slight change so that our button turns red ( '''~BLEND(255,0,0,1)''' ) when focused.

In this example, we will use wesnoth.wml_actions to create the WML tag [add_widget_def_demo].

Note the first line, a common convention for creating an alias for wml.tag.
|-
|[[File:Gui tutorial custom widget.png|center|thumb|Different definition of buttons, including one of our own (right)]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag -- save ourselves some typing
function wesnoth.wml_actions.add_widget_def_demo()
local definition = {
id = "tree_view_node_custom",
description = "Fold/unfold status indicator of a tree view node (MODIFIED).",
T.resolution {
min_width = 25,
min_height = 19,
default_width = 25,
default_height = 19,
max_width = 25,
max_height = 19,
-- Unselected - note there's no tags for unselected/selected, that's simply determined by the order
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/fold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/fold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/fold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
-- Selected
T.state {
T.enabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png" }
}
},
T.disabled {
T.draw {
T.image { name = "buttons/unfold-arrow.png~GS()" }
}
},
T.focused {
T.draw {
T.image { name = "buttons/unfold-arrow.png~BLEND(255,0,0,1)" }
}
}
},
}
}
gui.add_widget_definition("toggle_button", "tree_view_node_custom", definition)

local dialogDefinition = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid {
T.row {
T.column {
T.tag.toggle_button {
definition = "default"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node"
}
},
T.column {
T.toggle_button {
definition = "tree_view_node_custom"
}
}
}
}
gui.show_dialog(dialogDefinition)
end

</syntaxhighlight>

See [[GUIWidgetDefinitionWML]] for more details on widget definitions.

You can also give the whole dialog a definition, like definition = "tooltip_large". There is no gui.add_window_definition(), however a window is technically a type of widget so it may be possible to create your own window definitions (please update this if you do).

===Panels===

===Canvases===
Part of panels? Sort of?

A canvas is a surface you can draw on. A dialog has them, as does a panel, and for these canvas 1 refers to the background, while canvas 2 refers to the foreground. Other widgets may have canvases that may have other meanings, or no canvases at all. See more at [[LuaAPI/gui/widget#set_canvas]].

Here's a fun little trick. Set your dialog background to be transparent:
<syntaxhighlight lang=lua>
local function preshow(dialog)
dialog:set_canvas(1, { } )
end
</syntaxhighlight>

Or, if you want an opaque GUI background with the screen behind it blurred like what you see behind the text of a [message], you can set your window definition to "message":
<syntaxhighlight lang=lua>
...
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
definition = "message",
...
</syntaxhighlight>

{|
|Here we take our [[#Progress Bar|progress bar]], and add a text overlay.

Note: either using text on a canvas is rather limited, or I just couldn't figure it out. For example, I could not get the text size any smaller, and any attempts to do so simply resulted in very blocky text. And the spaces were necessary so that the text wasn't stretched out. I also find it surprising that the progress bar does not have this feature inherently. So it's not a great example, but it should be enough to get you started using canvases. Be sure to visit the [[LuaAPI/gui/widget#set_canvas|link]] mentioned above for more options.
|-
|[[File:Gui tutorial canvas text.png|center|thumb|A progress bar in the background, with text in the foreground]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar_with_overlay()
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.grid {
T.row {
T.column {
T.panel { id = "panel",
T.grid {
T.row {
T.column {
T.button { id = "button",
label =_ "Press me"}
},
T.column {
T.progress_bar { id = "progress" }
},
T.column {
T.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
dialog.panel:set_canvas(2, { T.text { text_alignment = "center", font_size = 48,
text_markup = true, text = " " ..
dialog.progress.percentage .. "% " } } )
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end
gui.show_dialog(dialogDefinition,preshow)
end

</syntaxhighlight>

You may notice we added a panel and placed our text on the foreground canvas(2) on it, since the progress_bar itself does not support canvases.

===Placement===

You may have noticed that all of our dialogs are centered on the screen. This is the default. You can override this and place the dialog wherever you like by setting automatic_placement = false, along with x, y, width, and height at the top level of your dialog definition (next to tooltip =, etc).

'''This part about placement needs review'''
If you prefer, you may replace x and/or y with horizontal_placement and vertical_placement, such as horizontal_placement = "left". You can even set the placement values using WFL, for example horizontal_placement = "(gamemap_width / 3)" -- see [[#Using WFL with GUI2|Using WFL with GUI2]].

==Miscellaneous==

TODO: This stuff doesn't belong in a tutorial. It's worth documenting, but not here. Better to save these here for now than keep them on my laptop.

===Progress Bar===
{|
|A progress_bar is a graphical representation of a percent. In this example, we present the user with a puzzle. They must hit the button repeatedly before they can close the GUI. A progress_bar displays their current progress toward completion.
|-
|[[File:Gui tutorial progress bar.png|center|thumb|upright=2]]
|}
<syntaxhighlight lang=lua>
function wesnoth.wml_actions.progress_bar()
local dialogDefinition = {
wml.tag.tooltip { id = "tooltip_large" },
wml.tag.helptip { id = "tooltip_large" },
wml.tag.grid {
wml.tag.row {
wml.tag.column {
wml.tag.button { id = "button",
label =_ "Press me"
}
},
wml.tag.column {
wml.tag.progress_bar { id = "progress" }
},
wml.tag.column {
wml.tag.button { id = "ok",
label = _"Done"
}
}
}
}
}
local function preshow(dialog)
dialog.ok.enabled = false
dialog.button.on_button_click = function()
dialog.progress.percentage = dialog.progress.percentage + 10
if dialog.progress.percentage > 99 then
dialog.button.enabled = false
dialog.ok.enabled = true
end
end

gui.show_dialog(dialogDefinition,preshow)
end
</syntaxhighlight>

===Unit Preview Pane===

{|
|A unit_preview_pane takes a unit (or a unit type), and presents a graphical representation of the unit and its more important attributes, along with tooltips for additional details, in the same way that the recall menu does. Here we see an example of a unit which has picked up some items, including a weapon, which are affecting its stats.
|-
|[[File:Gui tutorial unit preview pane.png|center|thumb]]
|}
<syntaxhighlight lang=lua>
local T = wml.tag

function wesnoth.wml_actions.recall_from_variable(cfg)
local from_array = cfg.from or wml.error(
"[recall_from_variable]: missing required from= ")
local to_var = cfg.to or wml.error(
"[recall_from_variable]: missing required to= ")
local unit_list = wml.array_access.get(from_array) or wml.error(
string.format("[recall_from_variable]: failed to fetch wml array %s",from_array))

local listboxItem = T.grid {
T.row {
T.column {
T.label { id = "available_unit",
linked_group = "available_unit"
}
}
}
}

local listbox_id = "available_units"
local listboxDefinition = T.listbox { id = listbox_id,
T.list_definition {
T.row {
T.column {
T.toggle_panel { listboxItem }
}
}
}
}
local dialogDefinition = {
T.tooltip { id = "tooltip" },
T.helptip { id = "tooltip" },
T.linked_group { id = "available_unit", fixed_width = true },
T.grid {
T.row { -- header
T.column {
T.grid {
T.row {
T.column {
border = "bottom",
border_size = 10,
T.label {
use_markup = true,
label = ""
.. _"Select unit to recall" .. ""
}
}
}
}
}
},
T.row { -- Body
T.column {
T.grid {
T.row {
T.column {
border = "right",
border_size = 40,
listboxDefinition
},
T.column {
T.unit_preview_pane { id = "unit_preview" }
}
}
}
}
},
T.row { -- Footer
T.column {
T.grid {
T.row {
T.column {
T.spacer { width = 400 }
},
T.column {
border = "top,right",
border_size = 10,
T.button { id = "ok",
label = _"OK"
}
}
}
}
}
}
}
}

local picked = 1

local function preshow(dialog)
local listbox = dialog[listbox_id]
for i,unit in ipairs(unit_list) do
listbox[i].available_unit.label = unit.name .. "(" ..
unit.language_name .. ")"
end
local function draw_unit()
wesnoth.units.to_recall(unit_list[listbox.selected_index])
local tmp = wesnoth.units.find_on_recall{ id =
unit_list[listbox.selected_index].id }[1]
dialog.unit_preview.unit = tmp
wesnoth.units.extract(tmp)
picked = listbox.selected_index
end
draw_unit()
listbox.on_modified = draw_unit
end

gui.show_dialog(dialogDefinition,preshow)

wml.variables[to_var] = picked - 1
end

</syntaxhighlight>

This should all be pretty self evident by now. We are provided with an array of stored units (from [store_unit] in WML). We create a listbox populated with units and we use the selected_index to determine which element in the table to send to unit_preview_pane. Since our input is an array of unit data, not actual units, we use [[LuaAPI/wesnoth/units#wesnoth.units.to_recall|wesnoth.units.to_recall]] to take the definition of one from our array and place it on the recall list (turning it into an actual unit), [[LuaAPI/wesnoth/units#wesnoth.units.find_on_recall|wesnoth.units.find_on_recall]] to fetch that unit in a form that the unit_preview_panel understands, and finally [[wesnoth.units.extract|wesnoth.units.extract]] to remove the unit from the recall list when we are done with it.

And of course we subtract one from the selected_index when we return our choice to WML, since lua arrays count from 1 and WML from 0.

The unit_preview_pane will also accept a unit_type instead of a specific unit.

==Appendix==

===Explore Your Options===

We've seen a lot of options that can be set to modify the behaviour of our dialogs, some on columns, some on widgets, etc. These are in the process of being documented [[GUIWidgetInstanceWML|here]], but if you would like to go straight to the source, the data Wesnoth uses to validate your configuration can be found in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui data/schema/gui] under your install directory.

Let's look at a scroll_label, for example. A scroll_label is a widget, so we look in [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/widget_instances.cfg widget_instances.cfg] and find the following. Here we can see five parameters we can provide to our scroll_label (in addition to the ones available to all widgets, like id and definition, see the entry super=... which refers you to the widget_instance in the file [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/generic.cfg data/schema/gui/generic.cfg]), along with their types and default values. For example, we could set "link_aware = true", and if we do not we can assume that link_aware will be false. While this does not explain what these parameters do, the information provided in the schema directory is often helpful nonetheless.

<syntaxhighlight lang=wml>
[tag]
name="scroll_label"
min="0"
max="infinite"
super="$generic/widget_instance"
{DEFAULT_KEY "horizontal_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "vertical_scrollbar_mode" scrollbar_mode initial_auto}
{DEFAULT_KEY "wrap" bool true}
{DEFAULT_KEY "text_alignment" f_h_align "left"}
{DEFAULT_KEY "link_aware" bool false}
[/tag]
</syntaxhighlight>

We see that our scrollbars are of type scrollbar_mode. It would probably help if we knew what values are available to the scrollbar_mode. In [https://github.com/wesnoth/wesnoth/tree/master/data/schema/types/gui.cfg data/schema/types/gui.cfg] we find this:

<syntaxhighlight lang=wml>
[type]
name=scrollbar_mode
value="always|never|auto|initial_auto"
[/type]
</syntaxhighlight>

The variable types found in the schema files are described at [[GUIVariable]].

===Using WFL with GUI2===

If you look at the variable type descriptions at [[GUIVariable]] you may notice that many of them start with "f_" and have "or formula" in the description. This means that you can use [[Wesnoth_Formula_Language|Wesnoth Formula Language (WFL)]] formulas in these fields, with certain variables made available to you (which variables and what they mean can be challenging to ascertain, but you can generally figure it out by example).

Looking at [https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui/window.cfg data/schema/gui/window.cfg] we see that 'height' has type f_unsigned, which tells us that height is an unsigned integer, and that we can use a WFL formula to define it in a window_definition. In [https://github.com/wesnoth/wesnoth/tree/master/data/gui/themes/default/window/wml_message.cfg data/gui/window/wml_message.cfg] (data/gui/themes/default/window/wml_message.cfg starting around 1.19.2), we find the line '''height = "(screen_height - 30)"'''. This does exactly what it looks like, it sets the height of our window to 30 pixels less than the height of the screen.

===Useful Links===

[[LuaAPI/gui|LuaAPI/gui - Mostly about opening windows]] 
[[LuaAPI/types/widget|LuaAPI/types/widget - Widget attributes and callbacks]] 
[https://wiki.wesnoth.org/Category:GUI_WML_Reference GUI_WML_Reference] 
[https://github.com/wesnoth/wesnoth/tree/master/data/schema/gui .../data/schema/gui/*.cfg] - Lists of valid options for various GUI objects 
[https://devdocs.wesnoth.org/layout_algorithm.html Layout Algorithm] - For windows, at least

===Credits===

The basic framework that composes the initial examples was lifted from LotI. It's a great place to find well written examples, but some of it is complex enough to be a little overwhelming when getting started.

Many examples, particularly tree view and multipage, are heavily derived from the World Conquest multiplayer campaign.