Vos propres variables : <variables>

Ce qui s’écrit dans le fichier : la balise, les règles de nom, la portée.

Cette page décrit ce qui s’écrit dans le fichier. Pour les créer sans écrire une ligne de XML, voyez Vos variables sur mesure, dans « Les données dynamiques ».

C’est le mécanisme le plus utile d’un thème un peu sérieux, et pourtant le moins connu.

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

Ensuite, partout dans le thème :

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

Changez la valeur en un seul endroit, tout le thème suit. C’est ce qui rend les options de couleur possibles : un fichier de surcouche redéfinit la variable, et rien d’autre.

Les règles

• name et value sont obligatoires tous les deux ; sans l’un des deux, la ligne est ignorée et signalée dans le journal ;
• un name vide est refusé ;
• une variable peut en contenir une autre, y compris une variable de Recalbox :

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

• le bloc <variables> accepte une condition, et chaque <variable> aussi :

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

• on peut avoir plusieurs blocs <variables>, dans n’importe quel fichier ;
• une variable redéfinie plus loin écrase la précédente — comme les composants.

⚠️ Le bloc se déclare tout en haut

<variables> vaut pour tout ce qui est lu APRÈS lui.

Recalbox remplace chaque ${nom} à mesure qu’il lit les fichiers. Une variable déclarée au sommet du thème vaut donc partout ; déclarée au milieu, elle ne vaut que pour la suite.

D’où la règle, valable pour tous les thèmes : le bloc des variables en premier, avant les vues, avant tout le reste.

Une variable redéfinie plus loin remplace la précédente pour la suite de la lecture — c’est ce qui permet à un choix d’option de recolorer tout un thème, à condition d’être chargé avant les vues. Voir Déclarer une option.

Où les déclarer

Dans theme.xml, avant les <include> qui s’en servent : le moteur lit les variables d’un fichier avant d’en traiter les inclusions.

L’usage, repris du thème officiel, est de leur donner leur propre fichier — variables.xml — inclus en tout premier :

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