Conditions let you write a single theme that adapts to the machine, the screen and the displayed system, instead of maintaining several variants. They are written with the if="…" attribute and evaluated on every theme load, therefore once per system.
The if attribute applies to almost every theme tag.
<include>:<include if="crt" path="./crt/theme.xml" />
<view>:<view name="system" if="arcade">
...
</view>
<image name="deco" extra="true" if="favorite" path="./art/heart.png" />
<image name="deco" extra="true" path="./art/background.png">
<path if="crt">./art/background-crt.png</path>
</image>
<variables> block or a <variable>, and on a <subset>.Each identifier evaluates to true or false, then combines with the boolean operators and, or and not. The short forms &, | and ! are equivalent; they may be glued to the identifier (qvga&!crt), whereas the long forms require spaces (qvga and not crt).
if="qvga and not crt"
if="qvga & !crt"
if="hd or fhd"
if="hd | fhd"
Evaluation happens left to right, with no precedence between and and or: each new identifier is combined with the result accumulated so far.
if="qvga or vga and not crt"
therefore reads as (qvga or vga) and not crt, and is not equivalent to:
if="not crt and qvga or vga"
which reads as (not crt and qvga) or vga.
To remove any ambiguity, use parentheses — the Recalbox 10 engine supports them:
if="(qvga or vga) and not crt"
if="console | (arcade & !virtual)"
An unknown identifier evaluates to false and an error is written to
themes.log. That is the first thing to check when a conditional block never shows up.
| Identifier | True when… |
|---|---|
crt |
a CRT adapter is plugged and active |
jamma |
an RGB JAMMA adapter is plugged and active |
overscan |
equivalent to crt and not jamma |
tate |
the screen is in vertical mode (TATE) |
tateleft |
the screen is in TATE, rotated left |
tateright |
the screen is in TATE, rotated right |
qvga |
screen height is 288 px or less |
vga |
screen height is between 289 and 576 px |
hd |
screen height is between 577 and 920 px |
fhd |
screen height is above 920 px |
| Identifier | True when… |
|---|---|
ispc |
the machine is an x86_64 PC |
ispi |
the machine is a Raspberry Pi |
isodroid |
the machine is an Odroid Go Advance / RG351x |
isanbernic |
the machine is an Anbernic RG353x |
| Identifier | True when… |
|---|---|
bartop |
Recalbox runs in bartop mode (or more restrictive) |
nomenu |
Recalbox runs in no-menu mode |
| Identifier | True when… |
|---|---|
virtual |
the system is a virtual system |
arcade |
the system is an arcade system |
port |
the system is the ports system |
console |
the system is a home console |
handheld |
the system is a handheld console |
computer |
the system is a home computer |
fantasy |
the system is a fantasy console |
engine |
the system is a game engine |
favorite |
the system is the favourites system |
lastplayed |
the system is the last played system |
tateleft,tateright,ispc,ispi,isodroid,isanbernic,bartopandnomenuwere added in Recalbox 10.x.
Two extra attributes test the presence of a file or folder on disk. They can be used alone or alongside if, and they accept variables.
| Attribute | Effect |
|---|---|
ifexists="path" |
the block is kept only if the path exists |
ifnotexists="path" |
the block is kept only if the path does not exist |
<image name="localLogo" extra="true" ifexists="${root}/${system.name}/local-logo.svg" path="${root}/${system.name}/local-logo.svg" />
<image name="defaultLogo" extra="true" ifnotexists="${root}/${system.name}/local-logo.svg" path="${system.logo}" />
In the detailed view, the showIf attribute restricts an object to a given kind of selected entry. It accepts one or more comma-separated values.
| Value | The object is only visible on… |
|---|---|
game |
a game |
folder |
a folder |
header |
a section header |
<image name="folderFrame" extra="true" showIf="folder" path="./art/folder.png" />
<text name="gameInfo" extra="true" showIf="game,header" text="${game.name}" />
<!-- every arcade system by manufacturer -->
if="arcade & virtual"
<!-- every kind of console -->
if="console | handheld | fantasy"
<!-- systems with no physical existence -->
if="fantasy | engine"
<!-- small screens, excluding CRT -->
if="(qvga | vga) & !crt"