Introduction

Skinning in QuickGUI is easier than ever! In this tutorial we will learn how to create SkinType definitions, and how they are used by Widgets.

Skin Element Definition

The SkinElement definition describes how an image is used. All Skin Elements follow the same definition, as seen in this example:

SkinElement default 
          { 
              Border_Bottom 2 
              Border_Left 2 
              Border_Right 2 
              Border_Top 2 
              Texture qgui.button.png 
              TileBackground false 
              TileBorders true 
          }

The number after Border_Bottom represents the number of pixels representing the bottom border of the Image. In this case it is 2, so the last 2 rows of pixels represent the bottom border of the image. The same concept applies to the other border properties. Border values are used for resizing operations (on widgets that support resizing), as well as drawing operations. QuickGUI supports tiling of textures, and by outlining the designated border areas of a texture, QuickGUI can tile borders and/or backgrounds. Border thicknesses of 0 are perfectly acceptable.

Also important to mention is that empty SkinElements are supported:

SkinElement default 
          { 
          }

Any widget that uses the following SkinElement will be transparent. Please note that either all or none of the inner properties should be present. Only having a few of the inner properties will cause a crash when trying to build the SkinElement object.

Component Type Definition

ComponentType definitions are used in ComponentWidgets, or Widgets that are made up of other widgets. A good example of this is the ScrollBar, which has a button for a slider, and buttons to move the slider up/down or left/right. Here is an example of a ComponentType definition:

ComponentType left1
          {
              ClassName Button
              SkinType default.hscrollleft
          }

The ClassName refers to the Class of the widget. The SkinType refers to a SkinType defined for that class. This will be discussed next.

Skin Type Definition

The SkinType definition defines all SkinElements and ComponentTypes used by a Widget. The structure of the SkinType varies from Widget to Widget, and is defined in code by the Widget's class. For example, here is the SkinType definition for a Button:

void Button::registerSkinDefinition()
      {
          SkinDefinition* d = new SkinDefinition("Button");
          d->defineSkinElement(DEFAULT);
          d->defineSkinElement(OVER);
          d->defineSkinElement(DOWN);
          d->definitionComplete();
  
          SkinDefinitionManager::getSingleton().registerSkinDefinition("Button",d);
      }

All SkinTypes for Buttons must contain 3 SkinElements of ID "default", "over", and "down". If you try to create a SkinType that does not meet this definition, an exception will be thrown.

So what does the SkinType definition look like? Here is the default provided one with QuickGUI:

SkinType default 
      { 
          SkinElement default 
          { 
              Border_Bottom 2 
              Border_Left 2 
              Border_Right 2 
              Border_Top 2 
              Texture qgui.button.png 
              TileBackground false 
              TileBorders true 
          } 
  
          SkinElement down 
          { 
              Border_Bottom 2 
              Border_Left 2 
              Border_Right 2 
              Border_Top 2 
              Texture qgui.button.down.png 
              TileBackground false 
              TileBorders true 
          } 
  
          SkinElement over 
          { 
              Border_Bottom 2 
              Border_Left 2 
              Border_Right 2 
              Border_Top 2 
              Texture qgui.button.over.png 
              TileBackground false 
              TileBorders true 
          } 
  
      }

The last Skin Definition is the SkinClass.

Skin Class Definition

The SkinClass definition stores all SkinTypes for a given Widget. Here is an example of a SkinClass definition of a Horizontal ScrollBar:

SkinClass HScrollBar
  { 
      SkinType default 
      { 
          ComponentType left1
          {
              ClassName Button
              SkinType default.hscrollleft
          }
  
          ComponentType left2
          {
              ClassName Button
              SkinType default.hscrollleft
          }
  
          ComponentType right1
          {
              ClassName Button
              SkinType default.hscrollright
          }
  
          ComponentType right2
          {
              ClassName Button
              SkinType default.hscrollright
          }
  
          ComponentType slider
          {
              ClassName Button
              SkinType default.hslider
          }
  
          SkinElement bar
          { 
              Border_Bottom 1 
              Border_Left 1 
              Border_Right 1 
              Border_Top 1 
              Texture qgui.scrollbar.horizontal.png
              TileBackground false 
              TileBorders true 
          } 
      } 
  
  }

As referenced in the SkinClass definition above, we have to make sure there are Button SkinTypes of names "default.hscrollleft", "default.hscrollright", etc.

When creating or modifying SkinTypes and SkinElements, its important to know that all images and *.skinType files needs to be in an Ogre resource path to be recognized by Ogre, and used by QuickGUI. SkinTypes are applied using the following API:

Widget::setSkinType(const Ogre::String& skinTypeName);

Try experimenting with Skins and see what you come up with! Its very easy, and even easier to share SkinTypes with others!

Alias: QuickGUI_Artist_Tutorial_1