GUIToolkit

Introduction

This is a new toolkit aiming to make it possible to make the look of Wesnoth fully skinnable. This will be used in Wesnoth the make it easier to optimize for different screen resolutions. The initial work in progress version has been released with Wesnoth 1.6. Since the development isn't done yet, these pages reflect the state of the trunk.

The engine has two parts:

• Widget definition, which defines how a widget looks.
• Window definition, which defines how a certain window looks and it uses the widget definitions.

GUILayoutGuide

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.

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

• grow_factor
• horizontal_grow
• horizontal_alignment
• vertical_grow
• vertical_alignment

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.

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

grow_factor

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

[row] grow_factor = 1

Or

[column] grow_factor = 1

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.

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

Links

• GUIWidgetsWML - the various widgets, the options which can be used when a widget is "instantiated" in a window definition, and the types of GUI2 variables available.
• GUILayout - describes how to place widgets in a window.
• GUIWindowDefinitionWML - describes the windows available and which widgets the 'know' about.
• GUIToolkitWML - describes the basics of the engine.
• GUICanvasWML - describes what to draw on a widget.