Skin Configuration

This section is for people who wish to create or customize their own skins to control the appearance and layout of Rapid Evolution.

Everything you see when using Rapid Evolution is controlled by an XML configuration file called a “skin”. This configuration file lets you control many UI aspects:

• colors
• fonts
• icons
• location of elements
• language / locale preferences
• attributes of individual elements
• …and more!

For examples of what can be done with skins, please see the available skins section.

First, you must understand a few things about the XML file format. XML can be viewed/modified in any text editor, but it is recommended to have an XML capable editor. There are several free XML editors available over the net if you search.

XML does NOT do anything!! Maybe it is a little hard to understand, but XML does not DO anything. XML was created to structure, store, and transport information.

All you really need to know for RE2 purposes is that you can describe a nested set of elements, in a tree hierarchy. Elements are identified by “tags”. Every element must consist of a start and end tag. The general format is:

<tag_name>
...
</tag_name>

The information between the start and end tags describes the element. “Attributes” can also describe the element, which are name-value pairs placed within the start tag as follows:

<tag_name attribute_1="somevalue" attribute_2="somevalue">
...
</tag_name>

If there is no information between the start and end tags, you can abbreviate as follows (notice the forward slash toward the end):

<tag_name attribute_1="somevalue" attribute_2="somevalue"/>

Here is a more concrete example of a theoretical playlist which illustrates nested data:

<playlist title="party mix">
   <song title="tonight"/>
   <song title="dance all night"/>
   <song title="pleasure zone"/>
</playlist>

The general XML format describing a skin is:

<rapid-evolution-ui>
   <settings>
   ...
   </settings>
   <template-definitions>
   ...
   </template-definitions>
   <frame id="main_frame">
   ...
   </frame>
</rapid-evolution-ui>

The elements within these sections will vary, depending on the skin. One thing to keep in mind is elements under these sections will all require a unique “id” attribute. This attribute must remain the same to link the user interface with the actual functionality. In other words, above the frame element must have the attribute “id” to be “main_frame”, as that is what RE2 looks for to open when it is started. Here is a description of the different sections:

a) settings: Here you will define default values and messages. Tags in this section will be of the following type:

• border
• color
• dialog-message
• font
• icon
• margin
• message
• size

b) template-definitions: Here you will define reusable sets of related elements. As usual, an example is easiest to understand:

<rapid-evolution-ui>
   ...
   <template-definitions>
      <template id="input_combo">
         <field id="input"/>
         <button id="submit"/>
      </template>
      ...
   </template-definitions>
   <frame id="main_frame">
      <template id="input_combo" namespace="my_combo"/>
      ...
   </frame>
</rapid-evolution-ui>

The namespace element is necessary to provide uniqueness to the elements being added. The above frame section, when translated, would actually look like:

<rapid-evolution-ui>
   ...
   <frame id="main_frame">
      <field id="my_combo_input"/>
      <button id="my_combo_submit"/>
      ...
   </frame>
</rapid-evolution-ui>

You will want to use templates to define UI elements which appear multiple times. It is an easy way to maintain consistency and avoid having to having write repeating information.

c) frame: This is the root window element of RE2, and what is made visible when the application is run. This is where you will define the layout of all visual elements. Tags in this section will be of the following type (click for details):

• button
• checkbox
• colorchooser
• combobox
• condition
• dialog
• field
• label
• list
• panel
• progressbar
• radiobutton
• scrollpanel
• slider
• spinner
• splitpanel
• tabbedpanel
• table
• textarea
• toolbar

The position of UI elements are described in relation to each other, known as a relative layout. This is necessary to control the position and location of elements when a window is resized. The location of an element is described as a set of constraints, which are relations to other elements. For example, you might place a button 5 pixels to the right of a particular field, and aligned vertically (with the same field). The XML code would look like this:

<button id="my_button"...>
   <location>
      <constraint attribute="left" relative_id="some_field" relative_attribute="right" relative_position="5"/>
      <constraint attribute="vertical_center" relative_id="some_field" relative_attribute="vertical_center" relative_position="0"/>
   </location>
</button>

The following table describes the constraint attributes:

For each component, there will be 2-4 constraints. Normally you will have 2 constraints per axis, unless you define either “vertical_center” or “horizontal_center”, in which case by using the component's size the exact position can be determined. If there are not enough constraints to determine the position, then the component will be under-constrained. If there are too many constraints to satisfy, then the component will be over-constrainted. Both of these conditions will produce errors describing the problem.

The location element can be placed within a condition element to allow different constraints depending on the value of a checkbox. Here is the format to use:

<button id="my_button"...>
   <condition id="id of checkbox">
      <true>
         <location>
            <constraint attribute="left" relative_id="some_field" relative_attribute="right" relative_position="5"/>
            <constraint attribute="vertical_center" relative_id="some_field" relative_attribute="vertical_center" relative_position="0"/>
         </location>
      </true>
      <false>
         <location>
            <constraint attribute="right" relative_id="some_field" relative_attribute="left" relative_position="-5"/>
            <constraint attribute="vertical_center" relative_id="some_field" relative_attribute="vertical_center" relative_position="0"/>
         </location>
      </false>
   </condition>

All skins are located under the “skins” directory. It is recommended that you create a copy of an existing skin, such as default.xml, then modify it. If you plan to incorporated images, icons or other related files it is best to create a subdirectory under “skins” to contain all of the files. Finally, there are many settings options that could cause unexpected behavior if removed, such as removing a message definition which RE2 needs to display, so this should be done with care.

If you have any questions or problems, please visit the mixshare forum!