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.
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 two main areas where the UI intentionally breaks 'best practice'. These 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.
For C Programmers
Locations of Important Files
Note: This list varies slightly from release to release (to follow)
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.
Title: Loading Addons Subhead: Loading [programmatically generated name of the add-on currently being processed]
Code sample:(to follow)
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.
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...
Within the UI, there are only a handful of special characters needed. Use the
For WML Coders
Locations of Important Files
Note: This list varies slightly from release to release