La balise <include> insère un autre fichier de thème à l'endroit où elle est déclarée. C'est le moyen de découper un thème en morceaux réutilisables — une palette de couleurs, une disposition, un jeu d'icônes — et de proposer des variantes que l'utilisateur choisit dans les menus.
Le chemin s'écrit indifféremment en attribut ou en contenu de balise :
<include path="./commun/couleurs.xml" />
<include>./commun/couleurs.xml</include>
Un fichier inclus est un fichier de thème complet : il commence par <theme> et se termine par </theme>.
Les <include> se placent en dehors des <view>, à la racine du <theme>.
Les propriétés définies dans le fichier appelant écrasent celles du fichier inclus ; les autres sont conservées. Les <include> étant traités avant les <view> du fichier courant, c'est toujours le fichier appelant qui a le dernier mot.
commun/couleurs.xml :
<theme>
<view name="detailed">
<text name="md_description" fontPath="./polices/maPolice.ttf" color="00FF00" />
</view>
</theme>
snes/theme.xml :
<theme>
<include path="./../commun/couleurs.xml" />
<view name="detailed">
<text name="md_description" color="FF0000" />
</view>
</theme>
Résultat : la description utilise maPolice.ttf (venue de l'inclusion) et la couleur FF0000 (venue du fichier appelant).
| Propriété | Rôle |
|---|---|
path |
Chemin du fichier à inclure. Peut aussi être écrit comme contenu de la balise |
subset |
Nom du groupe d'options auquel appartient cette variante |
name |
Nom de la variante à l'intérieur du groupe. Obligatoire dès que subset est présent |
if, ifexists, ifnotexists |
Conditions d'inclusion |
En donnant un subset et un name à plusieurs <include>, vous créez une option de thème : Recalbox n'inclut que le fichier correspondant au choix de l'utilisateur, et propose la liste des name dans MENU PRINCIPAL > OPTIONS DE L'INTERFACE > THÈME.
<theme>
<include name="Sombre" subset="colorset" path="./couleurs/sombre.xml" />
<include name="Clair" subset="colorset" path="./couleurs/clair.xml" />
<include name="Rétro" subset="colorset" path="./couleurs/retro.xml" />
<include name="Carrousel" subset="systemview" path="./vues/carrousel.xml" />
<include name="Liste" subset="systemview" path="./vues/liste.xml" />
</theme>
Le name doit être unique à l'intérieur d'un même subset. Le choix de l'utilisateur est mémorisé dans recalbox.conf, par thème.
Les groupes historiquement reconnus sont colorset, iconset, menu, systemview et gamelistview, mais n'importe quel nom de groupe fonctionne : déclarez-le avec la balise <subset> pour lui donner un libellé lisible et une aide dans le menu.
Si vous n'ajoutez pas de
<subset>correspondant, le groupe apparaît quand même dans les menus, mais sous son nom technique.
Le chemin d'un <include> accepte les variables, ce qui permet un fichier par système avec une seule ligne :
<include path="${root}/${system.name}/reglages.xml" ifexists="${root}/${system.name}/reglages.xml" />
Les blocs <variables> sont interprétés avant les inclusions : une variable définie dans un fichier est utilisable dans tous les fichiers qu'il inclut.