GUIWindowDefinitionWML

Window definition

The window definition define how the windows shown in the dialog look.

Addon connect

This shows the dialog for managing addons and connecting to the addon server.

ID (return value)	Type	Mandatory	Description
hostname	text_box	yes	This text contains the name of the server to connect to.
show_help	button	yes	Thus button shows the in-game help about add-ons management when triggered.
free to choose (2)	button	no	This button closes the dialog to display a dialog for removing installed add-ons.

Add-on description

Add-on description and details for the add-ons manager interface.

ID (return value)	Type	Mandatory	Description
image	control	yes	Label for displaying the add-on icon, in a 72x72 area.
title	control	yes	Dialog title label, corresponding to the add-on name.
type	control	yes	Label for displaying the add-on's type.
version	control	yes	Label for displaying the add-on version number.
status	control	yes	Label for displaying the current installation/upgradability status.
author	control	yes	Label for displaying the add-on author/maintainer name.
size	control	yes	Label for displaying the add-on package size.
downloads	control	yes	Label for displaying the add-on's download count.
description	control	yes	Text label for displaying the add-on's description. The control can be given a text, this text is shown when the addon has no description. If the addon has a description this field shows the description of the addon.
translations	control	yes	Label for displaying a list of translations provided by the add-on. Like the description it can also show a default text if no translations are available.
dependencies	control	yes	Label for displaying a list of dependencies of the add-on. Like the description it can also show a default text if no dependencies are defined.
updated	control	yes	Label displaying the add-on's last upload date.
created	control	yes	Label displaying the add-on's first upload date.
url	text_box	yes	Textbox displaying the add-on's feedback page URL if provided by the server.
url_go	button	yes	Button for launching a web browser to visit the add-on's feedback page URL if provided by the server.
url_copy	button	yes	Button for copying the add-on's feedback page URL to clipboard if provided by the server.

Add-on filter options

Advanced filtering options for the legacy (GUI1) Add-ons Manager dialog.

ID (return value)	Type	Mandatory	Description
statuses_list	listbox	yes	A listbox for displaying and selecting add-on installation status filter options.
toggle_all_displayed_types	button	yes	This button toggles the values for all the widgets used to control the following add-on display options.
show_unknown	toggle_button	yes	Whether to display add-ons of unknown type.
show_sp_campaigns	toggle_button	yes	Whether to display single-player campaign add-ons.
show_sp_scenarios	toggle_button	yes	Whether to display single-player scenario add-ons.
show_mp_campaigns	toggle_button	yes	Whether to display multiplayer campaign add-ons.
show_mp_scenarios	toggle_button	yes	Whether to display multiplayer scenario add-ons.
show_mp_maps	toggle_button	yes	Whether to display multiplayer map-pack add-ons.
show_mp_eras	toggle_button	yes	Whether to display multiplayer era add-ons.
show_mp_factions	toggle_button	yes	Whether to display multiplayer faction add-ons.
show_mp_mods	toggle_button	yes	Whether to display multiplayer mod add-ons.
show_media	toggle_button	yes	Whether to display author resource add-ons.
show_other	toggle_button	yes	Whether to display add-ons of indeterminate types.
sort_ascending	toggle_button	yes	Display add-ons in ascending order by default.
sort_descending	toggle_button	yes	Display add-ons in descending order by default.
sort_by_name	toggle_button	yes	Sort add-ons by name by default.
sort_by_last_updated	toggle_button	yes	Sort add-ons by last update time by default.
sort_by_first_upload	toggle_button	yes	Sort add-ons by creation time by default.

Addon list

This shows the dialog with the addons to install. This dialog is under construction and only used with --new-widgets.

ID (return value)	Type	Mandatory	Description
addons	listbox	yes	A listbox that will contain the info about all addons on the server.
name	control	no	The name of the addon.
version	control	no	The version number of the addon.
author	control	no	The author of the addon.
downloads	control	no	The number of times the addon has been downloaded.
size	control	no	The size of the addon.

Add-on uninstall list

Dialog with a checkbox list for choosing installed add-ons to remove.

ID (return value)	Type	Mandatory	Description
addons_list	listbox	yes	A listbox containing add-on selection entries.
checkbox	toggle_button	yes	A toggle button allowing the user to mark/unmark the add-on.
name	control	no	The name of the add-on.

Campaign difficulty

The campaign mode difficulty menu.

ID (return value)	Type	Mandatory	Description
title	label	yes	Dialog title label.
message	scroll_label	no	Text label displaying a description or instructions.
listbox	listbox	yes	Listbox displaying user choices, defined by WML for each campaign.
icon	control	yes	Widget which shows a listbox item icon, first item markup column.
label	control	yes	Widget which shows a listbox item label, second item markup column.
description	control	yes	Widget which shows a listbox item description, third item markup column.

Campaign selection

This shows the dialog which allows the user to choose which campaign to play.

ID (return value)	Type	Mandatory	Description
campaign_list	listbox	yes	A listbox that contains all available campaigns.
icon	image	no	The icon for the campaign.
name	control	no	The name of the campaign.
victory	image	no	The icon to show when the user finished the campaign. The engine determines whether or not the user has finished the campaign and sets the visible flag for the widget accordingly.
campaign_details	multi_page	yes	A multi page widget that shows more details for the selected campaign.
image	image	no	The image for the campaign.
description	control	no	The description of the campaign.

Campaign settings

This shows the dialog which allows the user to select an era and modifications for the selected campaign, and to show dialogs for additional level configuration.

ID (return value)	Type	Mandatory	Description
title	label	yes	Dialog title label.
mp_configure	toggle_button	yes	Option to show the multiplayer configure dialog.
mp_connect	toggle_button	yes	Option to show the multiplayer connect dialog.
era_label	label	yes	The label for the era list.
era_list	listbox	yes	List of available eras.
era	label	no	The name of the era. One can be selected at a time.
mod_label	label	yes	The label for the modification list.
modification_list	listbox	yes	List of available modifications.
mod	toggle_button	no	The name of the modification. Each can be enabled or disabled.

Clock

This shows the dialog for keeping track of the drawing events related to the current time. (This window is used for debug purposes only.)

ID (return value)	Type	Mandatory	Description
hour_percentage	progress_bar	no	This shows the hours as a percentage, where 24 hours is 100%.
minute_percentage	progress_bar	no	This shows the minutes as a percentage, where 60 minutes is 100%.
second_percentage	progress_bar	no	This shows the seconds as a percentage, where 60 seconds is 100%.
hour	integer_selector	no	This shows the seconds since the beginning of the day. The control should have a minimum_value of 0 and a maximum_value of 86399 (246060 - 1).
minute	integer_selector	no	This shows the seconds since the beginning of the current hour. The control should have a minimum_value of 0 and a maximum_value of 3599 (6060 - 1).
minute	integer_selector	no	This shows the seconds since the beginning of the current minute. The control should have a minimum_value of 0 and a maximum_value of 59.
clock	control	no	A control which will have set three variables in its canvas: hour, the same value as the hour integer_selector. minute, the same value as the minute integer_selector. second, the same value as the second integer_selector. the control can then show the time in its own preferred format(s).

Core selection

This shows the dialog which allows the user to choose which core to play.

ID (return value)	Type	Mandatory	Description
core_list	listbox	yes	A listbox that contains all available cores.
icon	image	no	The icon for the core.
name	control	no	The name of the core.
core_details	multi_page	yes	A multi page widget that shows more details for the selected core.
image	image	no	The image for the core.
description	control	no	The description of the core.

Custom Schedules

This shows the dialog to modify tod schedules.

ID (return value)	Type	Mandatory	Description
current_tod_name	text_box	yes	The name of the time of day(ToD).
current_tod_id	text_box	yes	The id of the time of day(ToD).
current_tod_image	image	yes	The image for the time of day(ToD).
current_tod_mask	image	yes	The image mask for the time of day(ToD).
current_tod_sonund	label	yes	The sound for the time of day(ToD).
next_tod	button	yes	Selects the next ToD.
prev_tod	button	yes	Selects the previous ToD.
lawful_bonus	slider	yes	Sets the Lawful Bonus for the current ToD.
tod_red	slider	yes	Sets the red component of the current ToD.
tod_green	slider	yes	Sets the green component of the current ToD.
tod_blue	slider	yes	Sets the blue component of the current ToD.

SP/MP Dependency Check: Confirm Change

Asks the user to confirm a change required to proceed. Currently used for enabling/disabling modifications

ID (return value)	Type	Mandatory	Description
message	label	yes	displays the details of the required changes
itemlist	scroll_label	yes	displays the list of affected items
cancel	button	yes	refuse to apply changes
ok	button	yes	agree to apply changes

SP/MP Dependency Check: Select New

Offers a list of compatible items if a currently selected one is incompatible. Currently used for switching era or map.

ID (return value)	Type	Mandatory	Description
message	label	yes	displays the details of the required changes
itemlist	listbox	yes	displays the available items to choose from
cancel	button	yes	refuse to apply any changes
ok	button	yes	select the chosen item

Edit label

Dialog for editing gamemap labels.

ID (return value)	Type	Mandatory	Description
title	label	yes	Dialog title label.
label	text_box	yes	Input field for the map label.
team_only_toggle	toggle_button	yes	Checkbox for whether to make the label visible to the player's team only or not.

Editor Edit label

Dialog for editing gamemap labels.

ID (return value)	Type	Mandatory	Description
title	label	yes	Dialog title label.
label	text_box	yes	Input field for the map label.
team_only_toggle	toggle_button	yes	Checkbox for whether to make the label visible to the player's team only or not.

Edit scenario

Dialog for editing gamemap scenarios.

ID (return value)	Type	Mandatory	Description
title	label	yes	Dialog title label.
label	text_box	yes	Input field for the map label.
team_only_toggle	toggle_button	yes	Checkbox for whether to make the label visible to the player's team only or not.

Edit side

Dialog for editing gamemap sides.

ID (return value)	Type	Mandatory	Description
title	label	yes	Dialog title label.
id	text_box	yes	Input field for the id.
team_only_toggle	toggle_button	yes	Checkbox for whether to make the label visible to the player's team only or not.

Editor generate map

This shows the dialog in the editor to select which random generator should be used to generate a map.

ID (return value)	Type	Mandatory	Description
generators_list	listbox	yes	Listbox displaying known map generators.
settings	button	yes	When clicked this button opens the generator settings dialog.
seed_textbox	text_box	yes	Allows entering a seed for the map generator.

Editor new map

This shows the dialog to generate a new map in the editor.

ID (return value)	Type	Mandatory	Description
width	integer_selector	yes	An integer selector to determine the width of the map to create.
height	integer_selector	yes	An integer selector to determine the height of the map to create.

Editor resize map

This shows the dialog to resize the current map.

ID (return value)	Type	Mandatory	Description
old_width	label	no	Shows the old width of the map.
old_height	label	no	Shows the old height of the map.
width	slider	yes	Determines the new width of the map.
height	slider	yes	Determines the new height of the map.
copy_edge_terrain	boolean_selector	yes	Determines whether the border terrains should be used to expand or not.
expand0	toggle_button	yes	Determines in which direction to expand, shows the north east marker.
expand1	toggle_button	yes	Determines in which direction to expand, shows the north marker.
expand2	toggle_button	yes	Determines in which direction to expand, shows the north west marker.
expand3	toggle_button	yes	Determines in which direction to expand, shows the east marker.
expand4	toggle_button	yes	Determines in which direction to expand, shows the center marker.
expand5	toggle_button	yes	Determines in which direction to expand, shows the west marker.
expand6	toggle_button	yes	Determines in which direction to expand, shows the south east marker.
expand7	toggle_button	yes	Determines in which direction to expand, shows the south marker.
expand8	toggle_button	yes	Determines in which direction to expand, shows the south west marker.

Editor set starting position

Map editor dialog for setting player starting positions.

ID (return value)	Type	Mandatory	Description
listbox	listbox	yes	Listbox displaying player choices.
player	control	yes	Widget which shows a player item label.
location	control	yes	Widget which shows the coordinates to the current starting position for a player if it exists.
ok	button	yes	OK button.
cancel	button	yes	Cancel button.

Folder Create

Dialog for providing the name of a new folder to create. Used by the file dialog.

ID (return value)	Type	Mandatory	Description
name	text_box	yes	Input field for the new folder name.

Formula debugger

This shows the debugger for the formulas.

ID (return value)	Type	Mandatory	Description
stack	control	yes	A stack.
execution	control	yes	Execution trace label.
state	control	yes	The state.
step	button	yes	Button to step into the execution.
stepout	button	yes	Button to step out of the execution.
next	button	yes	Button to execute the next statement.
continue	button	yes	Button to continue the execution.

Game cache options

A Preferences subdialog including a report on the location and size of the game's WML cache, buttons to copy its path to clipboard or browse to it, and the possibility of clearing stale files from the cache or purging it entirely.

ID (return value)	Type	Mandatory	Description
path	text_box	yes	Cache dir path.
copy	button	yes	Copies the cache path to clipboard.
browse	button	yes	Browses to the cache path using the platform's file management application.
size	label	yes	Current total size of the cache dir's contents.
clean	button	yes	Cleans the cache, erasing stale files not used by the Wesnoth version presently running the dialog.
purge	button	yes	Purges the cache in its entirety.

Delete a savegame

This shows the dialog to confirm deleting a savegame file.

ID (return value)	Type	Mandatory	Description
dont_ask_again	boolean_selector	yes	A checkbox to not show this dialog again.

Load a game

This shows the dialog to select and load a savegame file.

ID (return value)	Type	Mandatory	Description
txtFilter	text	yes	The filter for the listbox items.
savegame_list	listbox	yes	List of savegames.
filename	control	yes	Name of the savegame.
date	control	no	Date the savegame was created.
preview_pane	widget	yes	Container widget or grid that contains the items for a preview. The visible status of this container depends on whether or not something is selected.
minimap	minimap	yes	Minimap of the selected savegame.
imgLeader	image	yes	The image of the leader in the selected savegame.
lblScenario	label	yes	The name of the scenario of the selected savegame.
lblSummary	label	yes	Summary of the selected savegame.

Save a game

This shows the dialog to create a savegame file.

ID (return value)	Type	Mandatory	Description
lblTitle	label	yes	The title of the window.
txtFilename	text_box	yes	The name of the savefile.

Game paths

Dialog displaying the various paths used by the game to locate resource and configuration files.

There are several item types used to build widget ids in this dialog. All references to TYPE below refer to the following suffixes: datadir, config, userdata, saves, addons, cache.

ID (return value)	Type	Mandatory	Description
path_TYPE	text_box	yes	Textbox containing the filesystem path for the given item.
copy_TYPE	button	yes	Copies the given item's path to clipboard.
browse_TYPE	button	yes	Launches the default file browser on the given item's path.

Gamestate inspector

This shows the gamestate inspector

ID (return value)	Type	Mandatory	Description
inspector_name	control	yes	Name of the inspector.
stuff_list	control	yes	List of various stuff that can be viewed.
inspect	control	yes	The state of the variable or event.
copy	button	yes	A button to copy the state to clipboard.

Joystick settings

Joystick configuration dialog.

Empty table.

Language selection

This shows the dialog to select the language to use. When the dialog is closed with the OK button it also updates the selected language in the preferences.

ID (return value)	Type	Mandatory	Description
language_list	listbox	yes	This listbox contains the list with available languages.
free to choose	control	no	Show the name of the language in the current row.

Lobby sounds options

A Preferences subdialog permitting to configure the sounds and notifications generated in response to various mp lobby / game events.

ID (return value)	Type	Mandatory	Description
_label	label	yes	Item name.
_sound	toggle_button	yes	Toggles whether to play the item sound.
_notif	toggle_button	yes	Toggles whether to give a notification.
_lobby	toggle_button	yes	Toggles whether to take actions for this item when in the lobby.

Change control dialog

This shows the multiplayer change control dialog.

ID (return value)	Type	Mandatory	Description
sides_list	listbox	yes	List of sides participating in the MP game.
nicks_list	listbox	yes	List of nicks of all clients playing or observing the MP game.

Multiplayer command wrapper

This shows a dialog that provides a graphical front-end to various commands in the multiplayer lobby

ID (return value)	Type	Mandatory	Description
message	text_box	no	Text to send as a private message.
reason	text_box	no	The reason for a ban.
time	text_box	no	The time the ban lasts.
user_label	label	no	The label to show which user has been selected.
send_message	button	yes	Execute /msg.
add_friend	button	yes	Execute /friend.
add_ignore	button	yes	Execute /ignore.
remove	button	yes	Execute /remove.
status	button	yes	Execute /query status.
kick	button	yes	Execute /query kick.
ban	button	yes	Execute /query kban.
mod_options	grid	yes	Grid containing the status/kick/ban options. This grid and its children are hidden when these options are unavailable.

Multiplayer connect

This shows the dialog to the MP server to connect to.

ID (return value)	Type	Mandatory	Description
start_table	text_box	yes	The name of the server to connect to.
list	button	no	Shows a dialog with a list of predefined servers to connect to.

Create Game: Set Password

Dialog for setting a join password for MP games.

ID (return value)	Type	Mandatory	Description
password	text_box	yes	Input field for the game password.

Host Networked Game prompt

This shows the dialog to confirm deleting a savegame file.

ID (return value)	Type	Mandatory	Description
do_not_show_again	boolean_selector	yes	A checkbox to not show this dialog again.

Join Game: Password Prompt

Dialog for entering a password for joining a password-protected MP game.

ID (return value)	Type	Mandatory	Description
password	text_box	yes	Input field for the game password.

Multiplayer connect

This shows the dialog to log in to the MP server

ID (return value)	Type	Mandatory	Description
user_name	text_box	yes	The login user name.
password	text_box	yes	The password.
remember_password	toggle_button	no	A toggle button to offer to remember the password in the preferences.
password_reminder	button	no	Request a password reminder.
change_username	button	no	Use a different username.
login_label	button	no	Displays the information received from the server.

MP method selection

This shows the dialog to select the kind of MP game the user wants to play.

ID (return value)	Type	Mandatory	Description
user_name	text_box	yes	This text contains the name the user on the MP server. This widget will get a fixed maximum length by the engine.
method_list	listbox	yes	The list with possible game methods.

Multiplayer server list

This shows the dialog with a list of predefined multiplayer servers.

ID (return value)	Type	Mandatory	Description
server_list	listbox	yes	Listbox with the predefined servers to connect to.
name	control	no	Widget which shows the name of the server.
address	control	yes	The address/host_name of the server.

Rename unit

Dialog for renaming units in-game.

ID (return value)	Type	Mandatory	Description
name	text_box	yes	Input field for the unit name.

Screenshot notification

Notification dialog used after saving a game or map screenshot to display information about it for the user.

ID (return value)	Type	Mandatory	Description
path	text_box	yes	Read-only textbox containing the screenshot path.
filesize	label	no	Optional label to display the file size.
copy	button	yes	Button to copy the path to clipboard.
open	button	yes	Button to open the screnshot using the default application.
browse_dir	button	yes	Button to browse the screenshots directory in the file manager.

Simple item selector

A simple one-column listbox with OK and Cancel buttons.

ID (return value)	Type	Mandatory	Description
title	label	yes	Dialog title label.
message	control	yes	Text label displaying a description or instructions.
listbox	listbox	yes	Listbox displaying user choices.
item	control	yes	Widget which shows a listbox item label.
ok	button	yes	OK button.
cancel	button	yes	Cancel button.

Theme list

Dialog for selecting a GUI theme.

ID (return value)	Type	Mandatory	Description
themes	listbox	yes	Listbox displaying user choices.
name	control	yes	Widget which shows a theme item name.
description	control	yes	Widget which shows a theme item description.

Tip float

Generic window to show a floating tip window. The class has several subclasses using the same format. For example there will be tooltips and helptips, both using this class.

ID (return value)	Type	Mandatory	Description
label	control	yes	This text contains the message to show in the tip.

In the canvas of the windows used in this dialog the following variables are defined:

Variable	type	description
mouse_x	unsigned	The x coordinate of the mouse pointer when the window was created.
mouse_y	unsigned	The y coordinate of the mouse pointer when the window was created.

Title screen

This shows the title screen.

ID (return value)	Type	Mandatory	Description
tutorial	button	yes	The button to start the tutorial.
campaign	button	yes	The button to start a campaign.
multiplayer	button	yes	The button to start multiplayer mode.
load	button	yes	The button to load a saved game.
editor	button	yes	The button to start the editor.
addons	button	yes	The button to start managing the addons.
cores	button	yes	The button to start managing the cores.
language	button	yes	The button to select the game language.
credits	button	yes	The button to show Wesnoth's contributors.
quit	button	yes	The button to quit Wesnoth.
tips	multi_page	yes	A multi_page to hold all tips, when this widget is used the area of the tips doesn't need to be resized when the next or previous button is pressed.
tip	label	no	Shows the text of the current tip.
source	label	no	The source (the one who's quoted or the book referenced) of the current tip.
next_tip	button	yes	The button show the next tip of the day.
previous_tip	button	yes	The button show the previous tip of the day.
logo	progress_bar	no	A progress bar to "animate" the Wesnoth logo.
revision_number	control	no	A widget to show the version number when the version number is known.

Unit attack

This shows the dialog for attacking units.

ID (return value)	Type	Mandatory	Description
attacker_portrait	image	no	Shows the portrait of the attacking unit.
attacker_icon	image	no	Shows the icon of the attacking unit.
attacker_name	control	no	Shows the name of the attacking unit.
defender_portrait	image	no	Shows the portrait of the defending unit.
defender_icon	image	no	Shows the icon of the defending unit.
defender_name	control	no	Shows the name of the defending unit.
weapon_list	listbox	yes	The list with weapons to choose from.
attacker_weapon	control	no	The weapon for the attacker to use.
defender_weapon	control	no	The weapon for the defender to use.

Unit create

This shows the debug-mode dialog to create new units on the map.

ID (return value)	Type	Mandatory	Description
male_toggle	toggle_button	yes	Option button to select the "male" gender for created units.
female_toggle	toggle_button	yes	Option button to select the "female" gender for created units.
unit_type_list	listbox	yes	Listbox displaying existing unit types sorted by name and race.
unit_type	control	yes	Widget which shows the unit type name label.
race	control	yes	Widget which shows the unit race name label.

WML error

Dialog used to report WML parser or preprocessor errors.

ID (return value)	Type	Mandatory	Description
summary	control	yes	Label used for displaying a brief summary of the error(s).
files	control	yes	Label used to display the list of affected add-ons or files, if applicable. It is hidden otherwise. It is recommended to place it after the summary label.
post_summary	control	yes	Label used for displaying instructions for reporting the error. It is recommended to place it after the file list label. It may be hidden if empty.
details	control	yes	Full report of the parser or preprocessor error(s) found.
copy	button	yes	Button that the user can click on to copy the error report to the system clipboard.

Settings manager

This shows the settings manager