Your own variables: <variables>

What goes in the file: the tag, the naming rules, the scope.

This page describes what goes in the file. To create them without writing a line of XML, see Your custom variables, in “Dynamic data”.

It is the most useful mechanism of any serious theme, and yet the least known.

<variables>
  <variable name="CouleurPrincipale" value="2E447C" />
  <variable name="PoliceTitre"       value="${root}/data/fonts/Exo2.otf" />
  <variable name="Alpha50"           value="80" />
</variables>

Then, anywhere in the theme:

<box name="fond">
  <color>${CouleurPrincipale}</color>
</box>
<text name="titre">
  <fontPath>${PoliceTitre}</fontPath>
  <color>${CouleurPrincipale}${Alpha50}</color>
</text>

Change the value in one place, the whole theme follows. That is what makes color options possible: an overlay file redefines the variable, and nothing else.

The rules

• name and value are both mandatory; without either, the line is ignored and reported in the log;
• an empty name is rejected;
• a variable can contain another one, including a Recalbox variable:

  <variable name="CheminLogo" value="${root}/data/logos/${system.name}.svg" />

• the <variables> block accepts a condition, and each <variable> too:

  <variables if="crt">
    <variable name="TailleTitre" value="0.09" />
  </variables>

• you can have several <variables> blocks, in any file;
• a variable redefined further down overwrites the previous one — like components.

⚠️ The block goes at the very top

<variables> applies to everything read AFTER it.

Recalbox replaces each ${nom} as it reads the files. A variable declared at the top of the theme therefore applies everywhere; declared in the middle, it only applies to what follows.

Hence the rule, valid for all themes: the variables block first, before the views, before everything else.

A variable redefined later replaces the previous one for the rest of the reading — that is what lets an option choice recolor a whole theme, provided it is loaded before the views. See Declaring an option.

Where to declare them

In theme.xml, before the <include> tags that use them: the engine reads a file's variables before processing its includes.

The custom, taken from the official theme, is to give them their own file — variables.xml — included first of all:

<include>${root}/variables.xml</include>