GUIWindowDefinitionWML

From The Battle for Wesnoth Wiki

Window definition

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

Community

This shows a dialog displaying community links.

ID (return value) Type Mandatory Description
forums button yes Links to the Wesnoth forums
discord button yes Links to the Wesnoth Discord server
irc button yes Links to a web client for the Wesnoth IRC channels
steam button yes Links to the Wesnoth Steam forums
reddit button yes Links to the Wesnoth sub-reddit
donate button yes Links to the SPI donation page for Wesnoth

Editor: Edit PBL

  • Dialog for editing an add-on's _server.pbl.
ID (return value) Type Mandatory Description
name text_box yes The name of the add-on displayed on the UI.
description scroll_text yes The add-on's description.
icon text_box yes The add-on's icon.
author text_box yes The author of the add-on. When using forum_auth, this must be a forum username.
version text_box yes The add-on's version.
dependencies text_box yes Other add-on IDs which this add-on depends on.
tags multimenu_button yes Tags for the add-on for searching in the add-ons manager.
type menu_button yes The type of the add-on.
forum_thread text_box yes The topic ID of this add-on's forum feedback thread.
forum_auth toggle_button yes Whether to use forum authentication when uploading or deleting the add-on.
secondary_authors text_box yes Any other forum usernames of people who are also allowed to upload updates for this add-on. Only works with forum_auth being enabled.
email text_box yes A contact email address. Requred when not using forum_auth.
password text_box yes The password to use when uploading the add-on. Requred when not using forum_auth.

Editor: Choose Add-on

Dialog for choosing the add-on to use in the editor.

ID (return value) Type Mandatory Description
existing_addons listbox yes A listbox that contains all available options for choosing an add-on

Editor: PBL Translations

Dialog for adding a translation while editing an add-on's _server.pbl.

ID (return value) Type Mandatory Description
language text_box yes The language code for this translation.
lang_title text_box yes The name of the language displayed on the UI.
description text_box yes The description of the translation.

Prompt

Dialog for getting a single text value from the player.

ID (return value) Type Mandatory Description
prompt_box text_box yes The text box to enter the value into.

Add-on Auth

This shows the dialog to provide a password when uploading an add-on.

ID (return value) Type Mandatory Description
password text_box yes The password used to verify the uploader.

MP Report

This shows a dialog to report players on the multiplayer server.

ID (return value) Type Mandatory Description
reportee text_box yes The person being reported.
report_reason text_box yes Why they're being reported.
occurrence_location menu_button yes Where in-game it happened.
additional_information text_box yes Any additional information to add.

Achievements

This shows a dialog displaying achievements.

ID (return value) Type Mandatory Description
selected_achievements_list menu_button yes Allows selecting achievements by what content they're for.
name label yes The user displayed name of the achievement.
description label yes The achievement's longer description.
icon image yes An icon to display to the left of the achievement.

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

Shows the list of addons on the server available for installation.

ID (return value) Type Mandatory Description
addons listbox yes A listbox that will contain the info about all addons on the server.
name label yes The name of the addon.
version_filter menu_button yes List allowing current or older versions to be selected.
author label yes The author of the addon.
downloads label yes The number of times the addon has been downloaded.
size label yes The size of the addon.
tags label yes Contents of the PblWML "tags" attribute.

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.

Debug 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
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

WML preprocessor/parser error report dialog.

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

This page was last edited on 27 April 2024, at 17:55.