Tous les fichiers qui composent un thème sont au format XML, un langage à balises classiques (<balise></balise> ou <balise />).
Un thème est un dossier placé dans /recalbox/share/themes/. À sa racine se trouve obligatoirement un fichier theme.xml : c'est ce fichier qui identifie le dossier comme un thème.
/recalbox/share/themes/
mon-theme/
theme.xml <- obligatoire, point d'entrée
default/
theme.xml <- thème de repli pour les systèmes sans dossier dédié
snes/
theme.xml
logo.svg
megadrive/
theme.xml
art/
police.ttf
fond.png
Le nom des sous-dossiers de systèmes n'est pas libre : il doit correspondre au dossier de thème déclaré par chaque système. Les quatre pages suivantes listent ces noms, extraits de la définition des systèmes de Recalbox 10.1 :
Pour chaque système, Recalbox cherche le fichier à charger dans cet ordre, et s'arrête au premier trouvé :
<theme>/<dossier-du-systeme>/theme.xml<theme>/default/theme.xml<theme>/theme.xmlUn dossier default/ est donc le moyen le plus simple de couvrir tous les systèmes que vous n'avez pas personnalisés un par un.
Recalbox accepte deux écritures équivalentes pour les propriétés : en balises enfants (ancienne écriture) ou en attributs (écriture recommandée, bien plus compacte).
Ancienne écriture :
<theme>
<include>chemin/a/inclure.xml</include>
<view name="system">
<image name="deco" extra="true">
<pos>0 0</pos>
<size>1 1</size>
<path>./art/fond.png</path>
</image>
</view>
</theme>
Écriture recommandée :
<theme>
<include path="chemin/a/inclure.xml" />
<view name="system">
<image name="deco" extra="true" pos="0 0" size="1 1" path="./art/fond.png" />
</view>
</theme>
Les deux écritures peuvent être mélangées dans un même objet : un attribut donne la valeur par défaut, une balise enfant peut la remplacer sous condition.
<image name="deco" extra="true" path="./art/fond.png">
<path if="crt">./art/fond-crt.png</path>
</image>
Le thème n'est pas chargé une fois pour toutes : il est rechargé et réinterprété intégralement dans les cas suivants.
Les blocs <variables> sont interprétés en tout premier, avant même les <include>.
<theme>Tout fichier XML de thème commence par <theme> et se termine par </theme>. Cette balise accepte cinq attributs, tous facultatifs, mais qui n'ont de sens que dans le theme.xml de la racine du thème.
nameNom affiché du thème, qui peut différer du nom du dossier. Sans cet attribut, c'est le nom du dossier qui est affiché.
<theme name="Mon propre thème">
versionVersion du thème. Si elle est présente, elle est affichée entre parenthèses derrière le nom dans la liste des thèmes.
<theme version="3.1">
recalboxVersion minimale de Recalbox nécessaire au thème. Recalbox 10.1 considère qu'un thème déclarant moins de 9.2 est trop ancien et prévient l'utilisateur avant de l'activer. Sans cet attribut, aucune vérification n'est faite.
<theme recalbox="10.0">
compatibilityTypes d'affichage supportés par le thème, séparés par des virgules.
| Valeur | Signification |
|---|---|
hdmi |
Écrans HDMI |
crt |
Écrans CRT (RGB DUAL) |
jamma |
Bornes JAMMA (RGB JAMMA) |
tate |
Écrans verticaux (TATE) |
<theme compatibility="hdmi,jamma">
Sans cet attribut, le thème est considéré comme compatible hdmi uniquement. Si l'utilisateur est en mode TATE et que le thème ne déclare pas tate, un avertissement s'affiche à l'activation.
resolutionsTranches de résolution supportées, séparées par des virgules.
| Valeur | Hauteur d'écran |
|---|---|
qvga |
jusqu'à 288 px |
vga |
de 289 à 576 px |
hd |
de 577 à 920 px |
fhd |
plus de 920 px |
<theme resolutions="hd,fhd">
Sans cet attribut, le thème est considéré comme compatible hd,fhd.
authorNom de l'auteur du thème, remonté par le gestionnaire de thèmes.
<theme author="Votre pseudo">
formatVersion
formatVersionest un vestige de l'ancien moteur de thèmes. Recalbox 10.1 ne la lit plus du tout : vous pouvez la supprimer de vos fichiers.
Le contenu des balises <view> et la liste des objets utilisables sont décrits dans la page des objets.