Theme Configuration
This document describes the XML file structure used to configure themes. Themes allow the user to alter a number of visual elements in order to customise the interface.
Contents
Locations & Naming
A theme may be defined in any of the usual XML configuration files, but it is also possible to create a single package containing the theme's configuration file(s) and any other resources, such as images and sounds. This facilitates the distribution of complete themes.
The package structure is in essence simply a directory. This directory may have any name, but it make sense to use the name of the theme. The configuration file, which must be named "theme.xml", is placed in the root of the directory. When a relative file path is found in the theme configuration, the application will automatically search for the file relative to the theme's directory. For example, suppose we have a theme named "foobar" with the following directory structure:
foobar/
+-theme.xml
+-images/
| +-arrow.png
| +-menu_texture.png
+-sounds/
+-boing.wav
If the image "arrow.png" is to be used, it can be specified as "images/arrow.png" instead of having to specify the full path. The theme directory itself must be placed either:
- In a subdirectory "themes" in the same directory as the main "config.xml" file.
- In a subdirectory "themes" in the data directory defined at compile time (on Unix-like systems this is usually either /usr/share/cabrio/themes or /usr/local/share/cabrio/themes, on Windows it is usually the "data" subdirectory of the directory containing "cabrio.exe").
Theme Definition
The basic structure follows the usual rule of having a <cabrio-config> root element. Under this a <themes> element is defined, and under this zero or more <theme> elements containing the theme definition:
<cabrio-config>
<themes>
<theme>
<background>
...
</background>
<font>
...
</font>
<sounds>
...
</sounds>
<menu>
...
</menu>
<submenu>
...
</submenu>
<game-selector>
...
</game-selector>
<snap>
...
</snap>
<hints>
...
</hints>
</theme>
...
</themes>
</cabrio-config>
Background
The <background> element is used to configure the background image as displayed on the main screen.
| Element | Data type | Description |
|---|---|---|
| image-file | String | Image file to be used as the default background. |
| rotation | Numeric | Speed at which the background should rotate. 1 is very slow, 1000 is very fast, 0 means no rotation. Use a negative value to rotate in the other direction. |
| transparency | Percentage | How transparent the background should be. 0% means completely opaque, 100% is invisible. |
Font
The <font> element is used to configure the font used for all text displayed by the application.
| Element | Data type | Description |
|---|---|---|
| font-file | String | Path to the TrueType font file used to render text for the interface. |
| size | Numeric | The base size of text in the interface. Different elements of the interface may internally scale this up or down. |
| color | RGB | The colour of all text. |
Sounds
The <sounds> element contains zero or more <sound> elements which are used to define the sound effects used by the interface. The <sound> element in turn supports the following subelements:
| Element | Data type | Description |
|---|---|---|
| name | String | Specifies which sound is being defined. May be any of:
|
| sound-file | String | The name of the sound file to use. |
Menu
The <menu> element is used to cusomise the main menu, from which filters/categories are selected.
| Element | Data type | Description |
|---|---|---|
| image-file | String | The image to be used as a background for the menu items. |
| item-width | Floating Point | The amount by which menu items should be scaled horizontally. |
| item-height | Floating Point | The amount by which menu items should be scaled horizontally. |
| font-scale | Floating Point | The amount by which text should be scaled. |
| zoom | Floating Point | The amount by which an item is scaled to indicate that it is selected. A value of "1.0" means no scaling. The default value of "1.2" results in the selected item being 20% larger than the others. |
| transparency | Percentage | The transparency of non-selected items. Zero means completely opaque, 100% is completely invisible. |
| primary-offset | Floating Point | How far the menu is offset from the centre of the screen on the axis perpendicular to its orientation, i.e. if the menu is horizontally oriented (landscape), the vertical (Y-axis) offset. |
| secondary-offset | Floating Point | How far the menu is offset from the centre of the screen on the axis equal to its orientation, i.e. if the menu is horizontally oriented (landscape), the horizontal (X-axis) offset. |
| items-visible | Integer | Maximum number of menu items which may be visible at one time. The actual number mey be lower, depending on how many menu items there are in total. |
| spacing | Floating Point/String | The spacing between menu items. If set to "auto", the spacing is determined automatically with regard to menu item sizes and orientation. |
| border | Percentage | The precentage of the width or height of a menu item that is considered the border. Text will not be displayed outside of this area. |
| orientation | String | The orientation of the menu, either "landscape" (horizontal) or "portrait" (vertical). |
| auto-hide | Boolean | When set to true, the menu is automatically hidden when control is passed to the game selector (and displayed again when control returns to the menu). |
Submenu
The <submenu> element is used to cusomise the submenu, from which filters/category values are selected.
| Element | Data type | Description |
|---|---|---|
| image-file | String | The image to be used as a background for the the submenu box items. |
| item-width | Floating Point | The amount by which the submenu box should be scaled horizontally. |
| item-height | Floating Point | The amount by which the submenu box should be scaled horizontally. |
| font-scale | Floating Point | The amount by which text should be scaled. |
| primary-offset | Floating Point | How far the submenu is vertically offset from the centre of the selected menu item. |
| secondary-offset | Floating Point | How far the submenu is horizontally offset from the centre of the selected menu item. |
Game Selector
The <game-selector> element configures the game selector and, optionally, the individual itmes ("tiles") it consists of.
| Element | Data type | Description |
|---|---|---|
| primary-offset | Floating Point | How far the game selector is offset from the centre of the screen on the axis perpendicular to its orientation, i.e. if the game selector is horizontally oriented (landscape), the vertical (Y-axis) offset. |
| secondary-offset | Floating Point | How far the game selector is offset from the centre of the screen on the axis equal to its orientation, i.e. if the game selector is horizontally oriented (landscape), the horizontal (X-axis) offset. |
| orientation | String | The orientation of the game selector, either "landscape" (horizontal) or "portrait" (vertical). |
| x-size | Floating Point | Amount by which the game selector should be scaled horizontally. Negative values have the effect of horizontally flipping the selector. |
| y-size | Floating Point | Amount by which the game selector should be scaled vertically. Negative values have the effect of vertically flipping the selector. |
| tile-size | Floating Point | Amount by which all tiles are scaled. |
| selected | Integer | Which of the tiles is considered to be displaying the selected game. This must match the <order> value of one tile. |
| tiles | - |
| Element | Data type | Description |
|---|---|---|
| order | Integer | Number by which game selectors are sorted to determine their order. The tile with the lowest <order> is first and subsequent tiles follow in ascending order. |
| x-position | Floating point | Horizontal offset of the tile from the centre of the screen. |
| y-position | Floating point | Vertical offset of the tile from the centre of the screen. |
| z-position | Floating point | Distance of the tile from the viewer. |
| x-angle | Floating point | Amount by which the tile is rotated in the X-axis. |
| y-angle | Floating point | Amount by which the tile is rotated in the Y-axis. |
| y-angle | Floating point | Amount by which the tile is rotated in the Z-axis. |
| transparency | Percentage | Transparency of the tile. Zero means completely opaque, 100% is completely invisible. |
Snap
This is the area used to display a screen shot of the current game. It may in the future be used to display other images (e.g. cabinets or control panels) or even videos.
| Element | Data type | Description |
|---|---|---|
| primary-offset | Floating Point | How far the snap is offset from the centre of the screen on the axis perpendicular to the screen orientation, i.e. if the screen is horizontally oriented (landscape), the vertical (Y-axis) offset. |
| secondary-offset | Floating Point | How far the snap is offset from the centre of the screen on the axis equal to the screen orientation, i.e. if the screen is horizontally oriented (landscape), the horizontal (X-axis) offset. |
| x-angle | Floating Point | Degrees by which the snap is rotated in the X-axis. |
| y-angle | Floating Point | Degrees by which the snap is rotated in the Y-axis. |
| z-angle | Floating Point | Degrees by which the snap shot is rotated in the Z-axis. |
| size | Floating Point | Amount by which the snap should be scaled. |
| fix-aspect-ratio | Boolean | When set to true, the snap is automatically stretched to the current screen aspect ratio. Orientation is preserved. |
| auto-hide | Boolean | When set to true, the snap is automatically hidden when control is passed to the menu selector (and displayed again when control returns to the game selector). |
Hints
This section configures the "hints" - the images and text used to prompt the user for input (i.e. the buttons and arrows).
| Element | Data type | Description |
|---|---|---|
| pulse | Boolean | When set to true, makes the hint images and text "pulse" by alternating slowly from transparent to opaque. |
| arrow-image | String | Image used for the arrow hint. The image should depict the arrow pointing upwards. It is rotated to produce the arrows pointing in other directions. |
| back-image | String | The image used for the "back" button. |
| select-image | String | The image used for the "select" button. |
| spacing | Floating Point/String | The spacing between button images when the game selector is active. |
Theme Overriding & Precedence
A theme can be overridden by specifying theme parameters in the <interface> section of "config.xml". Probably the easiest way to understand the mechanism is to follow the steps taken when determining which theme attributes should be applied.
- The default theme, hard-coded into the apllication is loaded into memory.
- The theme specified by name in the <interface> section of "config.xml" is read and any attributes specified overwrite their conterparts from the previous step.
- The <interface> section of "config.xml" is read and any attributes specified overwrite their conterparts from the previous step.
- The resulting theme attributes are applied.
Any of the elements listed above under <theme> may therefore also occur in the <interface> section of "config.xml", for example:
<cabrio-config>
<interface>
...
<theme>foobar</theme>
<menu>
<max_visible>5</max_visible>
</menu>
...
</interface>
...
</cabrio-config>
In the above configuration, the menu as defined in theme "foobar" will be used, but the <max_visible> parameter will be overridden with the values "5". As not other manu parameters are specified, these are inherited from the "foobar" theme. Of course, if the "foobar" theme doesn't specify a <max_visible> in its <menu> section (or indeed if there is no <menu> section at all!) the value will be inherited from the default hard-coded theme.
Note however that it is not possible to override individual game selector tiles, either by means of a user-defined theme or by using theme parameters in the <interface> section of "config.xml". If a <tiles> element is found, all tiles found up to that point are discarded and replaced with those specified in the subsequent <tile> elements.