In XML files, widgets are declared in the following fashion :

<widget_name property1="value1" property2="value2" />

or, for widgets of "spawn" type, with children :

<widget_name property1="value1" property2="value2" >
<child1 />
<child2 />
</widget_name>

The first section of this document describes the widgets you can use; the second describes the properties widgets can take. Not all properties can be applied to all widgets, see the docs for a given widget and a given property for full information.

Widgets

This section describes the widgets you can use in STK's GUI XML files. The upper-case name starting with WTYPE_* is the internal name of the widget (see the WidgetType enum).

WTYPE_RIBBON

Names in XML files: "ribbon", "buttonbar", "tabs", "vertical-tabs"

Appears as an horizontal bar containing elements laid in a row, each being and icon and/or a label

The "ribbon" subcategory will behave a bit like a radio button group, i.e. one element must selected. Events are triggered as soon as a choice is selected (can be simply by hovering).
The "buttonbar" subcategory treats children buttons as action buttons, which means they can't have a 'selected' state, only focused or not (i.e. there is no selection that remains if you leave this area). Events are triggered only on enter/fire.
The "tabs" subcategory will show a tab bar. behaviour is same as normal ribbon, only looks are different. Orientation of tabs (up or down) is automatically inferred from on-screen position

Note: Ribbon widgets are of spawn type (<ribbon> ... </ribbon>) and may contain icon-buttons or buttons as children.; Property PROP_SQUARE can be set to tell the engine if the ribbon's contents are rectangular or not (this will affect the type of highlighting used); All elements within a ribbon must have an 'ID' property; Ribbons (e.g. tabs) can have their elements dynamically added at runtime, too. Just add no children to the ribbon in the XML file, and add them at runtime through the method for this.; The layout algorithm will reserve space for at most one line of text (if needed) for ribbon elements. If you have ribbon elements with long texts that spawn many lines, 1. give the word_wrap="true" property to the icon button widget in the XML file; 2. expect that the extra lines will not be accounted for in the sizing algorithms (i.e. extra lines will just expand over whatever is located under the ribbon)

WTYPE_SPINNER

Names in XML files: "spinner", "gauge"

A spinner component (lets you choose numbers).

Specify PROP_MIN_VALUE and PROP_MAX_VALUE to have control over values (default will be from 0 to 99). You can specify an icon; then, include a sprintf format string like i in the name, and at runtime the current number will be inserted into the given name to find the right file for each possible value the spinner can take. It may also display arbitrary text instead of numbers, though this cannot be achieve in the XML file; use the ->addLabel(...) method in code to do this. It can also display arbitrary text containing the value; just define the PROP_TEXT property to contain the text you want, including a format string i where the value should appear (a string that does not contain i will result in the same text being displayed in the spinner no matter the current value).

Note: The "gauge" variant behaves similarly, but a fill band shows how close to the max the value is.

WTYPE_BUTTON

Name in XML files: "button"

A plain text button.

WTYPE_ICON_BUTTON

Names in XML files: "icon-button", "icon"

A component with an image, and optional text to go under it.

Note: The "icon" variant will have no border and will not be clickable. PROP_ICON is mandatory for this component. There are three ways to place the texture within the allocated space; the default (and only way currently accessible through xml files) is to scale the texture to fit, while preserving its aspect ratio; other methods, currently only accessible through C++ code, are to stretch the texture to fill the area without caring for aspect ratio, and another to respect an aspect ratio other than the texture's (useful for track screenshots, which are 4:3 compressed to fit in a power-of-two 256x256 texture); Supports property PROP_FOCUS_ICON

WTYPE_CHECKBOX

Name in XML files: "checkbox"

A checkbox.

WTYPE_LABEL

Names in XML files: "label", "header" , "bright"

A plain label.

Supports properties PROP_WORD_WRAP and PROP_TEXT_ALIGN.

Note: The "header" variant uses a bigger and more colourful font.; The "bright" variant uses a more colourful font but is not bigger.

WTYPE_BUBBLE is a variation of the plain label; the difference with a bubble widget is that it can be focused, and when focused it will expand to show more text, if the label is too long to be displayed in the allocated space.

WTYPE_SPACER

Name in XML files: "spacer"

Some blank space; not visible on screen.

WTYPE_DIV

Name sin XML files: "div", "box"

An invisible container.

Divs do not do much on themselves, but are useful to lay out children automatically (Supports property PROP_LAYOUT)
Divs can be nested.
Of spawn type (<div>...</div>, place children within)
Note
"box" is a variant that acts exactly the same but is visible on-screen

WTYPE_DYNAMIC_RIBBON

Names in XML files: "ribbon_grid", "scrollable_ribbon", "scrollable_toolbar"

Builds upon the basic Ribbon to be more dynamic (dynamics contents, possibly with scrolling, possibly multi-line)

NOT of spawn type (<ribbon_grid .../>), i.e. children are not specified in the XML file but programmatically at runtime.
PROP_CHILD_WIDTH and PROP_CHILD_HEIGHT are mandatory (so at least aspect ratio of elements that will later be added is known) An interesting aspect of PROP_CHILD_WIDTH and PROP_CHILD_HEIGHT is that you can use them to show textures to any aspect ratio you want (so you can e.g. save textures to a power-of-two size like 256x256, but then show it in 4:3 ratio).
Property PROP_SQUARE can be set to tell the engine if the ribbon's contents are rectangular or icons (this will affect the type of highlighting used).
Supports an optional label at the bottom if PROP_LABELS_LOCATION is set (see more on PROP_LABELS_LOCATION below).
Note
The "scrollable_ribbon" and "scrollable_toolbar" subtypes are single-line scrollable ribbons. The difference between both is that 'scrollable_ribbon' always has a value selected (like in a combo box, or radio buttons), while 'scrollable_toolbar' is a scrollable list of buttons that can be pressed to trigger actions.

WTYPE_MODEL_VIEW

Name in XML files: "model"

Displays a 3D model.

Note: Contents must be set programmatically.

WTYPE_LIST

Name in XML files: "list"

Displays a list.

Note: Contents must be set programmatically.

WTYPE_PROGRESS

Name in XML files: "progressbar"

Display a progress bar (e.g. for downloads).

Note: The value must be set programmatically.

WTYPE_TEXTBOX

Name in XML files: "textbox"

A text field where the user can type text

Properties

PROP_ID

Name in XML files: "id"

Gives a unique internal name to each object using this property. It will be used in events callbacks to determine what action occurred. Can be omitted on components that do not trigger events (e.g. labels)

PROP_TEXT

Name in XML files: "text" or "raw_text" ("text" is translated, "raw_text" is not)

gives text (a label) to the widget where supported. Ribbon-grids give a special meaning to this parameter, see ribbon-grid docs above.

PROP_ICON

Name in XML files: "icon"

give an icon to the widget. Property contents is the path to the file, by default relative to the /data directory of STK (several methods of IconButtonWidget and DynamicRibbon can enable you to use absolute paths if you wish, however).

Name in XML files: "focus_icon"

For icon buttons. A different icon to show when the item is focused.

PROP_TEXT_ALIGN, PROP_TEXT_VALIGN

Name in XML files: "text_align", "text_valign"

used exclusively by label components. Value can be "right" or "center" (left used if not specified) for "text_align", or "top"/"center"/"bottom" for valign.

PROP_WORD_WRAP

Name in XML files: "word_wrap"

used by label components and icon buttons. Value can be "true" to indicate that long text should spawn on multiple lines. Warning, in icon buttons, the space under the button's text may be rendered unclickable by the label widget overlapping other widgets under.

Line breaks are done on space characters; if one word is too long to fit on one line, then SHY (soft hyphen) characters are searched and breaks can be added there.

Note that for multiline labels, the layout engine is unable to guess their width and height on their own so you should explicitely give a width and height for labels that use this flag.

PROP_MIN_VALUE, PROP_MAX_VALUE

Name in XML files: "min_value", "max_value"

used to specify a minimum and maximum value for numeric widgets (c.f. spinner)

PROP_X, PROP_Y

Name in XML files: "x", "y"

sets the position (location) of a widget, relative to its parent (container <div> or screen if none). A plain number will be interpreted as an aabsolute position in pixels. A '' sign may be added to the given number to mean that the location is specified in terms of a percentage of parent size (parent size means the parent <div> or the whole screen if none). A negative value can also be passed to start coordinate from right and/or bottom, instead of starting from top-left corner as usual. Note that in many cases, it is not necessary to manually set a position. Div layouts will often manage that for you (see PROP_LAYOUT). Other widgets will also automatically manage the position and size of their children, for instance ribbons.

PROP_WIDTH, PROP_HEIGHT

Name in XML files: "width", "height"

give dimensions to the widget. A plain number will be interpreted as an absolute position in pixels. A '' sign may be added to the given number to mean that the size is specified in terms of a percentage of parent size (parent size means the parent <div> or the whole screen if none). Note that in many cases, it is not necessary to manually a size. Div layouts will often manage that for you (see PROP_LAYOUT). In addition, sizes are automatically calculated for widgets made of icons and/or text like labels and plain icons. Other widgets will also automatically manage the position and size of their children, for instance ribbons.

Another possible value is "fit", which will make a <div> fit to its contents.

Another possible value is "font", which will use the size of the font (useful to insert widgets inside text)

PROP_MAX_WIDTH, PROP_MAX_HEIGHT

Names in XML files: "max_width", "max_height"

The maximum size a widget can take; especially useful when using percentages and proportions.

PROP_CHILD_WIDTH, PROP_CHILD_HEIGHT

Names in XML files: "child_width", "child_height"

Used exclusively by the ribbon grid widget. See docs for this widget above.

PROP_LAYOUT

Name in XML files: "layout"

Valid on 'div' containers. Value can be "horizontal-row" or "vertical-row". This means x and y coordinates of all children will automatically be calculated at runtime, so they are laid in a row. Width and height can be set absolutely as usual, but can also be determined dynamically according to available screen space. Also see PROP_ALIGN and PROP_PROPORTION to known more about controlling layouts. Note that all components within a layed-out div will ignore all x/y coordinates you may give them as parameter.

PROP_ALIGN

Name in XML files: "align"

For widgets located inside a vertical-row layout div : Changes how the x coord of the widget is determined. Value can be "left", "center" or "right".

For widgets located inside a horizontal-row layout div : Changes how the y coord of the widget is determined. Value can be "top", "center" or "bottom".

Note: If you want to horizontally center widgets in a horizontal-row layout, or vertically center widgets in a vertical-row layout, this property is not what you're looking for; instead, add a stretching spacer before and after the widget(s) you want to center.; When applied to a label widget, this property will center the text widget within its parent. To align the text inside the label widget, see PROP_TEXT_ALIGN, PROP_TEXT_VALIGN

PROP_PROPORTION

Name in XML files: "proportion"

Helps determining widget size dynamically (according to available screen space) in layed-out divs. In a vertical row layout, proportion sets the height of the item. In an horizontal row, it sets the width of the item. Proportions are always evaluated relative to the proportions of other widgets in the same div. If one div contains 4 widgets, and their proportions are 1-2-1-1, it means the second must take twice as much space as the 3 others. In this case, 10-20-10-10 would do the exact same effect. 1-1-1-1 would mean all take 1/4 of the available space. Note that it is allowed to mix absolute widget sizes and proportions; in this case, widgets with absolute size are evaluated first, and the dynamically-sized ones split the remaining space according to their proportions.

PROP_SQUARE

Name in XML files: "square_items"

Valid on Ribbons or RibbonGrids. Can be "true" (omitting it means "false"). Indicates whether the contents use rectangular icons as opposed to "round" icons (this will affect the type of focus/highlighting used)

PROP_EXTEND_LABEL

Name in XML files: "extend_label"

How many pixels the label is allowed to expand beyond the boundaries of the widget itself. Currently only allowed on icon widgets.

PROP_LABELS_LOCATION

Name in XML files: "label_location"

In dynamic ribbons : Decides where the label is. Value can be "each", "bottom", or "none" (if ommitted, "none" is the default). "each" means that every item has its own label. "bottom" means there is a single label for all at the bottom, that displays the name of the current item.

In non-dynamic ribbons, you can also use value "hover" which will make the label only visible when the icon is hovered with the mouse.

PROP_MAX_ROWS

Name in XML files: "max_rows"

Currently used for ribbon grids only. Indicates the maximum amount of rows this ribbon can have.

PROP_WRAP_AROUND

Name in XML files: "wrap_around"

Currently used for spinners only. Value can be "true" or "false"

PROP_DIV_PADDING

Name in XML files: "padding"

Used on divs, indicate by how many pixels to pad contents

PROP_KEEP_SELECTION

Name in XML files: "keep_selection"

Used on lists, indicates that the list should keep showing the selected item even when it doesn't have the focus

PROP_COLOR_SLIDER

Name in XML files: "color_slider"

Used for gauges only, to indicate if it is a color slider. Value can be "true" or "false"

Using the engine in code

The first thing to do is to derive a class of your own from AbstractStateManager. There are a few callbacks you will need to override. Once it's done, you have all AbstractStateManager methods ready to be used to push/pop/set menus on the screen stack. Once you have instanciated your state manager class, call GUIEngine::init and pass it as argument. One of the most important callbacks is 'eventCallback', which will be called everytime something happens. Events are generally a widget state change. In this case, a pointer to the said widget is passed along its name, so you get its new state and/or act.

When you have described the general layout of a Screen in a XML file, as described above, you may use it in the code by creating a class deriving from GUIEngine::Screen, passing the name of the XML file to the constructor of the base class. The derived class will most notably be used for event callbacks, to allowcreating interactive menus. The derived class must also implement the Screen::init and Screen::tearDown methods, that will be called, respectively, when a menu is entered/left. For simple menus, it is not unexpected that those methods do nothing. For init and tearDown the corresponding function in Screen must be called. Note that init is called after the irrlicht elements have been added on screen; if you wish to alter elements BEFORE they are actually added, use either Screen::loadedFromFile or Screen::beforeAddingWidget ; the difference is that the first is called once only upon loading, whereas the second is called every time the menu is visited.

Summary of callbacks, in order :

(Load the Screen from file : Screen::loadFromFile is called automatically the first time you reference this screen through the StateManager)
Screen::loadedFromFile is called (implement it if you need it)
(Ask to visit the screen through the StateManager)
Screen::beforeAddingWidget (implement it if you need it)
Widget::add is called automatically on each Widget of the screen
Screen::init (implement it if you need it)
(Ask to leave the Screen through the StateManager)
Screen::tearDown (implement it if you need it)
Widget::elementRemoved is called automatically on each Widget of the screen

Widget::m_properties contains all the widget properties as loaded from the XML file. They are generally only read from the Widget::add method, so if you alter a property after 'add()' was called it will not appear on screen.

Note that the same instance of your object may be entered/left more than once, so make sure that one instance of your object can be used several times if the same screen is visited several times.

Note that the same instance of your object may be unloaded then loaded back later. It is thus important to do set-up in the Screen::loadedFromFile callback rather than in the constructor (after the creation of Screen object, it may be unloaded then loaded back at will, this is why it's important to not rely on the constructor to perform set-up).

Do not delete a Screen manually, since the GUIEngine caches them; deleting a Screen will only result in dangling pointers in the GUIEngine. Instead, let the GUIEngine do the cleanup itself on shutdown, or on e.g. resolution change.

You can also explore the various methods in Screen to discover more optional callbacks you can use.

You can also create dialogs by deriving from ModalDialog in a very similar way.

Inside the GUI Engine

Widget

SuperTuxKart's GUIEngine::Widget class is a wrapper for the underlying irrlicht classes. This is needed for a couple reasons :

irrlicht widgets do not do everything we want; so many STK widgets act as composite widgets (create multiple irrlicht widgets and adds logic so they behave as a whole to the end-user)
STK widgets have a longer life-span than their underlying irrlicht counterparts. This is simply an optimisation measure to prevent having to seek the file to disk everytime a screen switch occurs.

Each widget contains one (or several) irr::gui::IGUIElement instances that represent the irrlicht widget that is added to the IGUIEnvironment if the widget is currently shown; if a widget is not currently shown on screen (in irrlicht's IGUIEnvironment), then its underlying IGUIElement pointer will be NULL but the widget continues to exist and remains ready to re-create its underlying irrlicht widget when the screen it is part of is added again. The method add() is used to tell a widget to create its irrlicht counterpart in the IGUIEnvironment - but note that unless you start handling stuff manually you do NOT need to invoke add() on each widget manually, since the parent GUIEngine::Screen object will do it automatically when it is shown. When the irrlicht IGUIEnvironment is cleared (when irrlicht widgets are removed), it is very important to tell the Widgets that their pointer to their \cIGUIElement counterpart is no more valid; this is done by calling elementRemoved() - but again unless you do manual manipulation of the widget tree, the GUIEngine::Screen object will take care of this for you.

So, before trying to access the underlying irrlicht element of a GUIEngine::Widget, it is thus important to check if the GUIEngine::Widget is currently added to the irr IGUIEnvironment. This can be done by calling ->getIrrlichtElement() and checking if the result is NULL (if non-null, the widget is currently added to the screen). Of course, in some circumstances, the check can be skipped because the widget is known to be currently visible.

VERY IMPORTANT: some methods should only be called before Screen::init, and some methods should only be called after Screen::init. Unfortunately the documentation does not always make this clear at this point :( A good hint is that methods that make calls on a IGUIElement* need to be called after init(), the others needs to be called before.

Screen

This class holds a tree of GUIEngine::Widget instances. It takes care of creating the tree from a XML file upon loading (with the help of others, for instane the GUIEngine::LayoutManager); it handles calling add() on each of its GUIEngine::Widget children when being added - so that the corresponding IGUIElement irrlicht widgets are added to the irrlicht scene. It also takes care of telling its GUIEngine::Widget children when their irrlicht IGUIElement counterpart was removed from the IGUIEnvironment so that they don't carry dangling pointers.

The default behavior of the GUIEngine::Screen object will be just fine for most basic purposes, but if you want to build highly dynamic screens, you may need to get your hands dirty. Take a look at GUIEngine::Screen::manualRemoveWidget() and GUIEngine::Screen::manualAddWidget() if you wish to dynamically modify the STK widget tree at runtime. If you get into this, be very careful about the relationship between the STK widget tree and the irrlicht widget tree. If you manualRemoveWidget() a STK widget that is currently visible on screen, this does not remove its associated irrlicht widget; call widget->getIrrlichtElement()->remove() for that. When you removed a widget from a Screen you are also responsible to call Widget::elementRemoved() on them to avoid dangling pointers. Similarly, a GUIEngine::Widget that is not inside a GUIEngine::Screen when the screen is added will not have its add() method be called automatically (so, for instance, if you manualAddWidget() a widget after a Screen was shown, you will also need to call ->add() on the widget so that it is added to the irrlicht GUI environment).

As a final note, note that the GUIEngine::Skin depends on both the irrlicht widget and the STK widget to render widgets properly. So adding an irrlicht IGUIElement without having its SuperTuxKart GUIEngine::Widget accessible through the current GUIEngine::Screen (or a modal dialog) may result in rendering glitches.

Table of Contents