Using Themes/skins

TGUI 0.7 is no longer supported, use a newer TGUI version instead.

In the creating widgets tutorial you were shown that you can just create a widget without needing any resources.

tgui::EditBox::Ptr editBox = tgui::EditBox::create();

But you can of course completely change the look of your widgets. The first thing to do it creating a theme object. The following line will create the theme object based on the Black.txt theme file that is shipped with TGUI.

tgui::Theme::Ptr theme = tgui::Theme::create("TGUI/widgets/Black.txt");

The theme object now contains all the information needed to load your widgets. You choose the widget to load by passing the name of the section in the theme file. Unless you e.g. have multiple edit box skins in the same file you will most likely just use the name of the widget like it is done in Black.txt. To load the edit box you can now just write this:

tgui::EditBox::Ptr editBox = theme->load("EditBox");

In the line above there are two things that should be noted. First of all, the "EditBox" string is case-insensitive, you can just as well use "editbox". Secondly, the load function can return any widget. To do that it returns a WidgetConverter object which gets implicitly converted to any widget type that you assign it to. If you would try to assign it to a wrong type then an exception will be thrown.

Theme file contents

Above I have explained how to load sections from the theme file, but how do these theme files actually look? The theme files that are shipped with TGUI will contains sections like these:

EditBox {
    Property1: Value1;
    Property2: Value2;

That explains the "EditBox" string that you passed to the load function of the theme. But what if you want to create multiple edit box sections in the same file? The sections have to contain two parts in such case: the type of the widget and the name of the section.

EditBox.MySectionName {
    Property1: Value1;
    Property2: Value2;

The original "EditBox" section was actually being translated to "EditBox.EditBox" behind the scenes. Don't forget that the "EditBox.MySectionName" section should be loaded like this:

tgui::EditBox::Ptr editBox = theme->load("MySectionName");

More to come

There are many more things that can be said about the themes, but they will be added to this tutorial later. For now you will have to take a look at the documentation if you want to e.g. change the look of all your widgets with just one function call on the theme object.