GUIToolkit
Contents
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.
The engine has two parts:
- Widget definition, which defines how a widget looks. (Reference)
- Window definition, which defines how a certain window looks and it uses the widget definitions. (Reference)
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.
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"
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.
- GUIToolkitWML - Describes the basics of the engine.
- 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