Déclarer une option : `<subset>`

La syntaxe exacte, en deux temps.

Une option se construit en deux temps : on la déclare, puis on liste ses choix.

1. Déclarer le groupe

<subset subset="colorTheme"
        title="THEME : Colors"      title.fr="THÈME : Couleurs"
        help="Choose the color set"  help.fr="Choisissez la palette" />

Attribut	Rôle
`subset`	l’identifiant du groupe — c’est lui qui relie les choix entre eux
`title`	le libellé lu par l’utilisateur dans le menu
`help`	la phrase d’explication sous le libellé

title et help acceptent un suffixe de langue : title.fr, title.es… La version sans suffixe sert de repli.

2. Lister les choix

Chaque choix est un <include> qui porte le même subset :

<include subset="colorTheme" name="Blue"  name.fr="Bleu">${root}/options/couleurs/bleu.xml</include>
<include subset="colorTheme" name="Green" name.fr="Vert">${root}/options/couleurs/vert.xml</include>
<include subset="colorTheme" name="Red"   name.fr="Rouge">${root}/options/couleurs/rouge.xml</include>

Attribut	Rôle
`subset`	à quel groupe ce choix appartient
`name`	le libellé du choix dans la liste (traduisible : `name.fr`)

Le choix « aucun »

Un <include> vide donne l’option « aucun » — utile pour laisser le thème dans son état d’origine :

<include subset="shader" name="None" name.fr="Aucun"></include>

Ne proposer un choix que sur certains écrans

<include subset="systemView" if="(hd | fhd) and !tate"
         name="Vertical left" name.fr="Vertical gauche">${root}/_views/vertical.xml</include>
<include subset="systemView" if="crt | jamma"
         name="Horizontal">${root}/_views/horizontal.xml</include>

L’utilisateur ne voit que les choix pertinents pour son matériel. C’est ainsi que le filtre rétro n’apparaît pas sur un écran cathodique, qui n’en a pas besoin.

Le contenu d’un fichier de choix

C’est un fichier de thème ordinaire, qui ne redéfinit que ce qui change :

<?xml version="1.0" encoding="UTF-8"?>
<theme>
  <variables>
    <variable name="CouleurPrincipale" value="7C2E44" />
  </variables>
</theme>

Trois lignes utiles, et tout le thème passe au rouge — à condition d’avoir bâti le thème sur des variables plutôt que sur des couleurs écrites en dur.

⚠️ Les options se chargent AVANT les vues. Une variable vaut pour ce qui est lu après elle : c’est là que le choix doit passer pour que les vues en profitent.

L’ordre à écrire dans theme.xml :

<theme name="Mon Thème" …>
  <include>${root}/variables.xml</include>      <!-- 1. les valeurs par défaut -->
  <include>${root}/options.xml</include>        <!-- 2. le choix les redéfinit -->
  <include>${root}/views/system.xml</include>   <!-- 3. les vues, qui les emploient -->
</theme>

Ce qui se passe quand la personne change de choix

Recalbox relit le thème en entier — tous les fichiers, depuis theme.xml, avec le nouveau choix actif. C’est pour cela qu’un bref « Mise à jour du thème… » s’affiche à ce moment-là.

Une option qui ne change que des couleurs redéfinit uniquement des variables. C’est la façon la plus courte d’écrire un jeu de couleurs — et la principale raison de se servir de <variables>.