The <include> tag inserts another theme file where it is declared. It is how you split a theme into reusable pieces — a colour palette, a layout, an icon set — and how you offer variants the user selects from the menus.
The path can be written either as an attribute or as the tag content:
<include path="./common/colors.xml" />
<include>./common/colors.xml</include>
An included file is a complete theme file: it starts with <theme> and ends with </theme>.
<include> tags live outside <view> blocks, at the root of <theme>.
Properties defined in the calling file override those from the included file; the others are kept. Since <include> tags are processed before the current file's <view> blocks, the calling file always has the final say.
common/colors.xml:
<theme>
<view name="detailed">
<text name="md_description" fontPath="./fonts/myFont.ttf" color="00FF00" />
</view>
</theme>
snes/theme.xml:
<theme>
<include path="./../common/colors.xml" />
<view name="detailed">
<text name="md_description" color="FF0000" />
</view>
</theme>
Result: the description uses myFont.ttf (from the include) and colour FF0000 (from the calling file).
| Property | Purpose |
|---|---|
path |
Path of the file to include. Can also be written as the tag content |
subset |
Name of the option group this variant belongs to |
name |
Name of the variant inside the group. Mandatory as soon as subset is present |
if, ifexists, ifnotexists |
Conditions for inclusion |
By giving a subset and a name to several <include> tags, you create a theme option: Recalbox only includes the file matching the user's choice, and offers the list of name values in MAIN MENU > USER INTERFACE SETTINGS > THEME.
<theme>
<include name="Dark" subset="colorset" path="./colors/dark.xml" />
<include name="Light" subset="colorset" path="./colors/light.xml" />
<include name="Retro" subset="colorset" path="./colors/retro.xml" />
<include name="Carousel" subset="systemview" path="./views/carousel.xml" />
<include name="List" subset="systemview" path="./views/list.xml" />
</theme>
The name must be unique within a given subset. The user's choice is stored in recalbox.conf, per theme.
Historically recognised groups are colorset, iconset, menu, systemview and gamelistview, but any group name works: declare it with the <subset> tag to give it a readable label and a help text in the menu.
If you do not add a matching
<subset>, the group still appears in the menus, but under its technical name.
The path of an <include> accepts variables, which allows one file per system in a single line:
<include path="${root}/${system.name}/settings.xml" ifexists="${root}/${system.name}/settings.xml" />
<variables> blocks are interpreted before includes: a variable defined in a file is usable in every file it includes.