View source for UI Style Guide

=User Interface Style Guide=

This is a draft style guide covering the Wesnoth game user interface. For general C coding guidelines, see [[CodingStandards]]. For WML coding, see the [[WML Style Guide]]. There are some typography issues also covered in this guide, but please cross-refer to the [[Typography Style Guide]] as well. 

The Wesnoth UI (user interface) has a mixed setup. Part of it is hard-coded within the game's source code, which means you need to be able to at least read C program code to understand what is going on. The remainder is stored in a variety of WML files, which are easier for non-programmers to read and can be altered without having to recompile the program. With the ongoing Wesnoth GUI2 project http://forums.wesnoth.org/viewtopic.php?f=2&t=29640&hilit=GUI2&start=0 this setup will be simplified, making custom 'skins' easier to create. Note that this guide may change significantly once the version 2 GUI comes fully on-line. 

==General Principles==

The guiding principle of UI design is to make sure that all windows and icons follow the same style. Buttons and icons are consistent, sliders are always used in the same circumstances for the same reasons, and so on. There are also cases where Wesnoth may deliberately break the theoretical ideal; those are documented here, along with the reasons for doing so.

===UI Style Violations===

The game currently has a small number of areas where the UI intentionally breaks 'best practice'. The two main ones are the 'Languages' button on the main screen, and the 'Advanced Preferences' tab.

'Languages' should really be stored as a sub-menu under the 'Preferences' button, but instead we put it in the main Wesnoth window to make it easier for non-English speakers to find and change the game's language settings.

'Advanced Preferences' is a scrolling menu with a multi-purpose checkbox which changes its function depending on which advanced preference is selected. This is a coding shortcut to handle a growing number of custom options without having to create the several extra preferences windows that would otherwise be needed.

A minor niggle is that some of the buttons in the Wesnoth main menu ought to be marked with ellipses because they open sub-windows.

==For C Programmers==

===Locations of Important Files===

'''Note:''' This list varies slightly from release to release
(to follow)

===Window Titles===

Window titles use '''title case''', which means all words are capitalised except for articles, prepositions, and conjunctions. In the standard UI, window titles are in larger text in a gold colour:(Image to follow)
Window titles should be short and declarative, no more than 3-5 words. Do '''not''' use a window title for a question.

For example, do not use 'Are You Sure You Want to Delete This File?' as a title. Instead, the title should be 'Delete File', or similar, and the ''subhead'' should contain the question.

If the 'window' is a non-interactive progress bar, a window title is not required.

If the window is usually non-interactive, but does have a Cancel button, give it a short title.

Example:
 Title: Loading Addons
 Subhead: Loading [programmatically generated name of the add-on currently being processed]

Code sample:(to follow)

===Window Subheads===

Window subheads usually contain a single sentence, in larger than usual white text. The subhead should tell the user what to do, or ask them a direct question. When giving an instruction, ideally the first word should be 'Choose', 'Select', 'Delete', 'Load', 'Save', 'Confirm' or similar, and if there's a button the user has to click in order to do whatever-it-is, the verb on the button should match the imperative word used in the subhead.

If you are asking the user a question, use a question mark. If you are giving the user an instruction, use an imperative form and end with an colon. If you are giving the user information about what the computer is doing, end with an ellipsis.

Examples:
 Title: Language
 Subhead: Choose your preferred language:

 Title: Load Game
 Subhead: Choose the game to load:

 Title: Delete Game
 Subhead: Do you really want to delete this game?

 Title: [None]
 Subhead: Loading files and creating cache...

===Typography Summary===

Within the UI, there are only a handful of special characters needed. Use the correct Unicode symbol for the minus sign − U+2212 (8722) when listing ToD penalties and resistances, and the en dash – U+2013 (8211) when listing weapon damage/strikes values. These corrections are already in progress throughout the game. Other symbols, such as sexed quotation marks are unlikely to be needed anywhere; refer to the [[Typography Style Guide]] if necessary. We do not currently plan to use the ellipis character … U+2026 (8230), so three dots continues to remain acceptable for an ellipsis. If you want to use more than three dots, to indicate progress, it would be preferable to use a proper progress bar. Otherwise, start with three dots and add extras one at a time.

===Buttons===

A button should say what it does with a single verb. The current preferred list of button words is as follows:

* Back
* Cancel
* Delete
* Load
* Next
* Save
* Select
* (more to follow)

Please avoid using 'OK' in favour of a specific word indicating what will happen when the button is clicked.

If clicking a button will open a new window, add an unspaced ellipsis, except on the Wesnoth main menu, where ellipses are never used because it looks untidy.

===Sliders===

A slider should include a text label on the left describing the value it contains, followed by a colon. The label should be in '''sentence case'''. On the right, the current numeric slider value should be given, ''with units'', if any. The labels and the values should be left-aligned; the sliders should all be vertically aligned with one another. The existing UI widgets library already handles the alignment issues for you. Use the floating tooltip function to explain what the slider is for, the units, and the maximum, minimum and default permissible values. Where the function of the slider is glaringly obvious, you can just provide the minimum, maximum and default values.

Examples:

 Players:    ====|========= 3
 Map width:  ========|===== 50 hexes
 Map height: ======|======= 40 hexes
 Hilliness:  ===|========== 40

===Checkboxes===

Checkbox labels use '''sentence case'''. Use the floating tooltip function to explain what the checkbox is for, if it isn't obvious, and the default value. Do ''not'' just paraphrase the checkbox label text, instead try to answer the question of what a player actually sees when the option is turned on.

Example:

Do '''not''' use:
 _X_ Floating labels
 Tooltip: Turns on floating labels

Instead use:
 _X_ Floating labels
 Tooltip: Show floating text above a unit when it is damaged or healed

===Text Boxes===

===Menus===

The game's pull-down menus use '''title case'''. The key shortcut for a function is pulled from the hotkeys configuration file. Related functions should be grouped together. Frequently-used or important functions should be near the top of the list, 'dangerous' functions should be moved to the end of the list. 'Quit' is considered dangerous, which is why it is moved as far wy from the top of the menu as possible. As far as possible, try to ensure that accidentally missing the menu option you wanted to select by one row is harmless. Where no more obvious order is apparent, list items in alphabetical order.

===Tooltips===

Tooltips use sentence case, but the last sentence in any tooltip does not have a full stop. Try to add a tooltip to every button. At the very minimum, the tooltip should show either the default value, the current value, or the minimum and maximum values, depending on what is most useful. Where a button or checkbox's function is not immediately obvious, phrase the tooltip to describe what happens when the option is turned '''on'''.

Tooltips should contain no more than one or two lines of text.

Examples:

 name=_"Ping Timeout (seconds)"
 description=_"How long to wait for a ping reply before giving up. 0 means wait indefinitely"

 name=_"Auto-open Whisper Windows in Lobby"
 description="When you are sent a whisper message, it appears in a pop-up window"

(WML code)

===Default Values===

While it might be nice to display the default value for every checkbox, widget and so on a player might alter, this can make the tooltips needlessly untidy. The recommended practice is not to mindlessly add this information to every tooltip, but to provide it wherever a changed setting could cause unexpected behaviour, or wherever the original value is hard to retrieve. For example, it's easy to tell whether 'Floating Labels' is on or off. On the other hand, the name (and possibly port number) for the default add-on server should be stored in the tooltip, so that a user can restore it if necessary.

==For WML Coders==

===Locations of Important Files===

'''Note:''' This list varies slightly from release to release

===Window titles