Creating User Interfaces via XML

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
  
• Creating a view
  
• Creating custom views
  
• Defining Bitmaps
  
• Defining Fonts
  
• Defining Colors
  
• Defining Tags
  
• Defining Templates
  
• UI XML Attribute Definitions
  

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:

1. Create view factory methods for your custom views (look into viewcreator.cpp how this is done for the built in views)
2. 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)