Note: The use of XML as description format is deprecated (since Version 4.10).

VSTGUI and XML

It is possible to create VSTGUI based interfaces via a XML description.

Example XML file

First let us see a simple example of XML text describing a VSTGUI view hierarchy:

<?xml version="1.0" encoding="UTF-8"?>
<vstgui-ui-description version="1">
  <bitmaps>
    <bitmap name="background" path="background.png"/>
    <bitmap name="slider-handle" path="slider-handle.png"/>
    <bitmap name="slider-background" path="slider-background.png"/>
  </bitmaps>

  <fonts>
    <font name="labelfont" font-name="Arial" size="11" bold="false" italic="false"/>
  </fonts>

  <colors>
    <color name="labelcolor" red="255" green="0" blue="255" alpha="255"/>
  </colors>

  <control-tags>
    <control-tag name="tag 1" tag="0"/>
    <control-tag name="tag 2" tag="1"/>
  </control-tags>

  <template name="MyEditor" size="500, 320" background-color="#000000DD" minSize="500, 320" maxSize="1000, 320" autosize="left right">
    <view class="CViewContainer" origin="10, 10" size="480, 90" background-color="#FFFFFF22" autosize="left right">
      <view class="CTextLabel" title="Test Label" origin="10, 10" size="80,20" transparent="true" font-color="labelcolor" font="labelfont"/>
      <view class="CSlider" control-tag="tag 1" origin="110, 10" size="260,20" handle-offset="3,3" bitmap="slider-background" handle-bitmap="slider-handle" autosize="left right"/>
      <view class="CTextEdit" control-tag="tag 2" origin="390, 10" size="80,20" back-color="slider-back" frame-color="slider-frame" font-color="labelcolor" font="labelfont" autosize="right"/>
    </view>
  </template>
</vstgui-ui-description>

Creating a view

You need to write a XML text file like the one in the example shown above. On Mac OS X this xml file must be placed into the Resources folder of the bundle and on Windows it must be declared in the .rc file. To use the xml file to create views you have to write this code :

UIDescription description ("myview.xml");
if (description.parse ())
{
  CView* view = description.createView ("MyEditor", 0);
}

If view is non-null it was successfully created and you can add it to your CFrame object.

Creating custom views

If you want to create your own custom views, you have two options:

Create view factory methods for your custom views (look into viewcreator.cpp how this is done for the built in views)
Inherit a class from VSTGUI::IController and provide the view in the VSTGUI::IController::createView method. An instance of this class must be passed as second argument to the createView method of VSTGUI::UIDescription.

Defining Bitmaps

Any bitmap you want to use with your views must be declared inside the bitmaps tag. Recognized attributes for the bitmap tag are:

name
you refer to this name later on when you want to use this bitmap
path
the path to the bitmap (On Mac OS X this is the path inside the Resource directory of the bundle and on Windows this is the name used in the .rc file)

Example:

<bitmaps>
  <bitmap name="background" path="background.png"/>
</bitmaps>

Defining Fonts

Any font you want to use with your views must be declared inside the fonts tag. Recognized attributes for the font tag are:

name
you refer to this name later on when you want to use this font
font-name
the system font name
size
size of the font
bold
true or false
italic
true or false
underline
true or false

Example:

<fonts>
  <font name="labelfont" font-name="Arial" size="11" bold="false" italic="false"/>
</fonts>

Defining Colors

You can define global colors within the colors tag. Recognized attributes for the color tag are:

name
you refer to this name later on when you want to use this color
red
the red value of this color in the range from 0 to 255
green
the green value of this color in the range from 0 to 255
blue
the blue value of this color in the range from 0 to 255
alpha
the alpha value of this color in the range from 0 to 255
rgb
the red, green and blue values in hex notation known from HTML and CSS: #0055BB (the alpha value of this color is always 255, and it overrides any previous attribute)
rgba
the red, green, blue and alpha values in hex notation known from HTML and CSS: #005566FF (any previous attribute will be ignored)

Example:

<colors>
  <color name="labelcolor" rgba="#005566FF"/>
  <color name="labelcolor2" rgb="#005566"/>
  <color name="labelcolor3" red="0" green="85" blue="102" alpha="255"/>
  <color name="labelcolor4" green="85" blue="102"/>
  <!-- by the way, these colors have all the same rgba values -->
</colors>

Colors can also be declared within the view tag for any color tag with one of the two hex notations.

Defining Tags

VSTGUI controls are identified by tags. In the control-tags tag you map control tags to names. Recognized attributes in the control-tag tag are:

name
you refer to this name later on when you want to use this control tag
tag
an integer tag or a tag defined like 'abcd'

Example:

<control-tags>
  <control-tag name="tag 1" tag="0"/>
  <control-tag name="tag 2" tag="'abcd'"/>
</control-tags>

Defining Templates

Templates are the main views in XML. You can have more than one. Per default the template tag will create a CViewContainer view, but you can use the class attribute to create any view class you want. (If the template should have subviews, the class must be an inherited class from CViewContainer like CScrollView)