¶ Introduction
Themes have a certain folders and files structure. Everything is described below.
All the files that make up a theme are in XML format. This is a simple language to use. It uses classic tags such as <tag></tag> or self-closing tags <tag />.
¶ Legend
: new
: deprectaed, to not use anymore, will be removed in a future version
¶ Lots of folders...
Every theme is made up of lots of folders.
¶ System
For each system available in Recalbox, you have a folder containing all the images corresponding to that system.
¶ Basic systems
¶ Basic virtual systems
¶ Virtual systems by genre
¶ Arcade virtual systems by manufacturer
¶ ... And a few files
At the root of any theme, you'll find a file called theme.xml. This contains information about general objects such as menu configuration, help bar, etc.
In each system seen above, you'll have an xml file (the file name will depend on your preference) which will contain system information such as information texts and the colors of the 4 vertical bars on the right of your screen with the default theme.
¶ File structure
Recalbox accepts two ways of writing XML files for themes.
Old way:
<theme>
<include>path/to/include1</include>
<include>path/to/include2</include>
...
<include>path/to/includeX</include>
<view name="...">
<object>
<property1>value</property1>
<property2>value</property2>
...
<propertyX>value</propertyX>
</object>
...
</view>
...
<view name="...">
<object>
...
</object>
...
</view>
</theme>
New way:
<theme>
<include>path/to/include1</include>
<include>path/to/include2</include>
...
<include>path/to/includeX</include>
<view name="...">
<object property1="value" property2="value" propertyX="value" />
...
</view>
...
<view name="...">
<object>
...
</object>
...
</view>
</theme>
The documentation presented here will focus on the new way of designing themes. The exact content is described in the other theme tutorials.
¶ How does it work?
Each system loads and reinterprets the theme. The theme should be considered as an entity that will be loaded and completely reinterpreted in the following cases:
- Once at startup, for what we internally call the “main” theme. From this instance, we will extract everything that is general and does not concern the systems, such as menu descriptors, for example.
- Once per system X. Here, the theme is completely reloaded and, above all, reinterpreted. This means that the system variables change each time, tests may give different results, etc.
¶ How <theme> and <view> tags work
¶ Tag <theme>
For this example, any xml file for the theme begins between the <theme></theme> tags.
¶ Properties
Tthis tag can contain 5 properties:
¶ name
- Required: ❌
The name property indicates the theme name. This can be different from the theme folder name. This name will be visible in the list of available themes.
Example:
name=“My own theme”
Without this property, the theme folder name will be used.
¶ recalbox
- Required: ❌
The recalbox property indicates the minimum version of Recalbox the theme can be used with. This allows you to indicate whether the theme is compatible with the version of Recalbox installed.
Example:
recalbox=“9.2”
Without this property, the theme can be used on any version of Recalbox.
¶ version
- Required: ❌
The version property indicates the version of the theme. If this information exists, it will be visible in the list of available themes.
Example:
version=“3.1”
Without this property, the theme version will not be displayed in the theme list.
¶ compatibility
- Required: ❌
The compatibility property indicates the type of screen the theme is compatible with. The theme can be compatible with a single screen type or several.
List of possible values:
hdmi: HDMI screenscrt: CRT screensjamma: JAMMA screenstate: TATE vertical screens
Example:
compatibility=“hdmi,jamma”
Without this property, the theme will be considered hdmi compatible only.
¶ resolutions
- Required: ❌
The resolutions property is used to indicate the resolution ranges with which the theme is compatible. It can contain several values.
List of possible values:
qvga: QVGA resolutions (<= 288p)vga: VGA resolutions (<= 576p)hd: HD resolutions (<= 920p)fhd: Full HD resolutions (> 920p)
Example:
resolutions=“hd,fhd”
Without this property, the theme will be considered hd, fhd compatible only.
¶ Tag formatVersion
The formatVersion tag is used to indicate the version of the content format governing the theme.
formatVersion="5"
¶ Tag <view>
The <view></view> tag and its child objects are described in the objects page.