GUIToolkit

An Example of a Dialog, created using Wesnoth's new GUI toolkit, GUI2

Introduction to GUI2

This is a new toolkit aiming to make it possible to make the look of Wesnoth fully skinnable. As such, it separates the actual appearance and layout of the user interface (defined using WML) and the control logic (such as event handling, done using C++ or Lua). The C++ or Lua code is also reponsible for actually loading the WML and showing the widget on the screen.

This is being used in Wesnoth the make it easier to optimize for different screen resolutions, and to simplify and make it easier to maintain GUI code.

Initially released with Wesnoth 1.6, it is now the default and being used for the majority of dialogs as of Wesnoth 1.18.

The engine has two parts:

• Widget definition, which defines how a widget looks and how it is laid out, if it contains multiple widgets inside (containers, see below). (Reference)
• Window definition, which defines how a certain window looks and how it uses the widget definitions. (Reference)

Basic Structure

The basic structure of a WML file that defines a dialog consists of a toplevel [window] tag, with one or more nested [resolution] tags, inside which the actual content of the window resides. The multiple resolution tags allow the designer to specify various interfaces for various screen sizes and resolutions. So a basic template for a WML file that defines the layout of an user interface would be :

[window]
    # Window attributes/keys
    # such as id and description
    
    [resolution]
        # Resolution keys
        
        # Tooltip and Helptip subtags, mandatory
        # just specifying an id is enough.
        [tooltip]
            id = "tooltip"
        [/tooltip]
        
        [helptip]
            id = "tooltip"
        [/helptip]
        
        # the main contents
        [grid]
        [/grid]
    [/resolution]
    
    # More resolution tags can be added here
    # to support different layouts for different
    # screen resolutions.
[/window]

Layouting

Wesnoth's UI toolkit, GUI2, has a rather simple layout system. Instead of allowing dialogs to specify exact coordinates, it only deals with relative sizes and locations. It is based on a grid based system, with complicated layouts being specified by multiple levels of nested [grid]s.

The UI is constructed from various UI widgets. Some of them can contain other widgets, such as window or grid, so we will call them Container-type widgets or just Containers for short, and we will use Simple Widgets to refer to the rest of them, which cannot contain other widgets inside themselves. There can also be a third type, a Widget that contains other widgets inside it, but these group of widgets behave as a cohesive group that performs a specific task, examples being scroll_label or the spinner. We will call this third type Compound Widgets.

There are 5 keys relevant to positioning widgets in a GUI2 container:

• grow_factor
• horizontal_grow
• vertical_grow
• horizontal_alignment
• vertical_alignment

Where these keys can be used are detailed below. Usually, they are used inside a [row] or [column].

It is to be kept in mind that GUI2 functions on a grid system. Each grid is made up of rows, and every row must have the same number of columns. The columns may contain either other grids or widgets, such as buttons.

[grid]
    [row]
    # row keys here
        [column]
        # column keys here
        # the widget or a subgrid goes here
            [button]
            # button keys
            [/button]
        [/column]
        # More columns here
    [/row]
    # More rows here
[/grid]

Now, let's talk about each of the above keys:

grow_factor

This key can be present in either rows or cells, as so:

[row]
    grow_factor = 1
[/row]

Or

[column]
    grow_factor = 1
[/column]

Growth factors control the relative growth size of the row or column. It's important to remember that the grow_factor of a row controls vertically growth, while the grow_factor of a column controls horizontal growth.

For example, if two columns were positioned next to each other, the first with a growth factor of 0 and the second with 1, the second column would grow at a regular rate, while the first would not grow at all. This holds true for rows, and it is important to get grow_factor values right. An easy way to remember how to use this key is to assign it a value of 0 if you want that row or column to grow much less relative to another.

Keep in mind, this key only controls the growth of the rows and columns themselves. Control over the widgets' sizes is dictated by the remaining keys.

horizontal_grow and vertical_grow

Boolean keys that decide whether the contained widgets grow or not. Mutually exclusive with horizontal_alignment and vertical_alignment.

horizontal_alignment and vertical_alignment

String keys that set the alignment of the contained widget. Possible values :

horizontal_alignment : "left", "center", "right"

vertical_alignment : "top", "center", "bottom"

Widget Definitions

Definitions determine the appearance and internal layout (for compound widgets and containers) of an widget. Think of them as a theme for an widget. Each widget has at least one definition, default plus several more. They are defined using a tag like [<widget>_definition] (replace <widget> with the name of the widget. For example, [button] has its definitions defined inside correponding [button_definition] tags. To use a particular definition, the definition key is used, when a widget is specified in a wml file. Put the definition's name on the right hand side of this key. If the definition key is not present, the engine assumes the definition default.

Example :

A Label with definition "title"

[label]
    id = button1
    label = _ "A Title"
    definition = title
[/label]

Links

• GUIWidgetInstanceWML - Reference for the various widgets and the keys that can be used with them.

• GUIVariable - Documents the types of GUI2 variables available.

• GUILayout - Describes how to place widgets in a window.

• GUIWindowDefinitionWML - Describes the windows available and which widgets the engine 'knows' about.

• GUIWidgetDefinitionWML - Describes the widget definitions available.

• GUIToolkitWML - Reference of various tags, such as [resolution], that are not described in GUIWidgetInstanceWML or anywhere else.

• GUICanvasWML - Describes how the drawing system works. Useful if you want to use the [drawing] widget to show some custom drawing or if you're building a new widget definition (aka a new theme for a widget.)

Todo list

Here's a(n incomplete) list of items which still need to be done.

• The layout engine can still have problems with not finding a solution and stop.
  • Make sure labels buttons etc can shrink and show ellipses to shrink small enough
  • Optimize the shrink algorithm
• The code for the events is not entirely to my liking and I want to look at using signals instead, events are there bug not yet used everywhere.
• EasyCoding#GUI2_related_features
• Improve the markup for the text
• Convert more dialogs