Eine Option deklarieren: `<subset>`

Die genaue Syntax, in zwei Schritten.

Eine Option wird in zwei Schritten gebaut: man deklariert sie, dann listet man ihre Auswahlmöglichkeiten auf.

1. Die Gruppe deklarieren

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

Attribut	Aufgabe
`subset`	die Kennung der Gruppe — sie verbindet die Auswahlmöglichkeiten miteinander
`title`	die Beschriftung, die der Benutzer im Menü liest
`help`	der Erklärungssatz unter der Beschriftung

title und help akzeptieren ein Sprachsuffix: title.fr, title.es… Die Version ohne Suffix dient als Rückfall.

2. Die Auswahlmöglichkeiten auflisten

Jede Auswahl ist ein <include>, das dasselbe subset trägt:

<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	Aufgabe
`subset`	zu welcher Gruppe diese Auswahl gehört
`name`	die Beschriftung der Auswahl in der Liste (übersetzbar: `name.fr`)

Die Auswahl „keine“

Ein leeres <include> ergibt die Option „keine“ — nützlich, um das Theme in seinem Ursprungszustand zu lassen:

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

Eine Auswahl nur auf bestimmten Bildschirmen anbieten

<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>

Der Benutzer sieht nur die für seine Hardware relevanten Auswahlmöglichkeiten. So erscheint der Retro-Filter nicht auf einem Röhrenbildschirm, der ihn nicht braucht.

Der Inhalt einer Auswahldatei

Es ist eine gewöhnliche Theme-Datei, die nur neu definiert, was sich ändert:

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

Drei nützliche Zeilen, und das ganze Theme wird rot — vorausgesetzt, das Theme wurde auf Variablen aufgebaut statt auf fest geschriebenen Farben.

⚠️ Die Optionen werden VOR den Ansichten geladen. Eine Variable gilt für das, was nach ihr gelesen wird: dort muss die Auswahl durchlaufen, damit die Ansichten davon profitieren.

Die Reihenfolge, die in theme.xml zu schreiben ist:

<theme name="Mon Thème" …>
  <include>${root}/variables.xml</include>      <!-- 1. die Standardwerte -->
  <include>${root}/options.xml</include>        <!-- 2. die Auswahl definiert sie neu -->
  <include>${root}/views/system.xml</include>   <!-- 3. die Ansichten, die sie verwenden -->
</theme>

Was passiert, wenn die Person die Auswahl wechselt

Recalbox liest das ganze Theme neu — alle Dateien, ab theme.xml, mit der neuen aktiven Auswahl. Deshalb erscheint in diesem Moment kurz „Theme wird aktualisiert…“.

Eine Option, die nur Farben ändert, definiert ausschließlich Variablen neu. Das ist die kürzeste Art, einen Farbsatz zu schreiben — und der Hauptgrund, <variables> zu verwenden.