13.1.13.4.2. Contrôles de valeur#

Ce sont les contrôles qui portent un paramètre. Chacun porte une value, et Save réécrit la value modifiée dans le contrôle. Le tableau ci-dessous est la table de correspondance rapide entre chaque contrôle et le type JSON qu’il enregistre ; les sections suivantes documentent chaque clé.

Contrôle	Enregistre
checkbox	booléen, ou entier `0`/`1`/`2`
combobox	la valeur choisie, ou son index
radio	la valeur choisie, ou son index
spinbox	entier
doublespinbox	nombre (virgule flottante)
slider	entier
lineedit	chaîne

Tous les contrôles de valeur acceptent également les clés communes (name, label, tooltip, enabled) ; voir la vue d’ensemble. Le label est affiché à côté du contrôle (sur la case elle-même pour une checkbox).

13.1.13.4.2.1. checkbox#

Un interrupteur marche/arrêt. Éventuellement à trois états, pour les paramètres dotés d’un état intermédiaire « non défini ».

{ "type": "checkbox", "name": "draw_overlays", "label": "Draw Overlays", "value": true }

Arguments :

label (string) – le texte affiché à côté de la case. Texte brut uniquement (contrairement aux autres contrôles, dont les libellés acceptent le texte enrichi).
tristate (boolean, par défaut false) – autorise un troisième état, partiellement coché.
value – l’état initial. À deux états : un booléen. À trois états : 0 (arrêt), 1 (partiel) ou 2 (marche).

Enregistre : un booléen pour une case à deux états ; un entier 0, 1 ou 2 pour une case à trois états.

13.1.13.4.2.2. combobox#

Un menu déroulant de choix.

{
  "type": "combobox",
  "name": "resolution",
  "label": "Resolution",
  "options": ["QQVGA", "QVGA", "VGA"],
  "values": ["qqvga", "qvga", "vga"],
  "value": "qvga"
}

Arguments :

options (array de chaînes) – les éléments affichés dans le menu.
values (array) – un tableau parallèle facultatif des valeurs à enregistrer, une par option. Avec values, le menu affiche options[i] mais enregistre values[i] – l’utilisateur voit donc « QVGA » tandis que le fichier stocke "qvga". Les entrées peuvent être de n’importe quel type JSON. Sans values, le contrôle enregistre à la place l”index de l’élément sélectionné.
value – la sélection initiale. Avec values, l’entrée égale à l’une des values. Sans values, l’index de l’élément à sélectionner (par défaut 0).

Enregistre : l’entrée values correspondante (n’importe quel type) lorsque values est fourni ; sinon l”index sélectionné (entier).

13.1.13.4.2.3. radio#

Un ensemble de boutons radio – un seul choix visible à la fois, comme un combobox mais présenté en entier.

{
  "type": "radio",
  "name": "mode",
  "label": "Mode",
  "options": ["Idle", "Track", "Record"],
  "values": ["idle", "track", "record"],
  "value": "idle",
  "orientation": "horizontal"
}

Arguments :

options (array de chaînes) – un bouton par entrée.
values (array) – les valeurs facultatives à enregistrer, une par option, exactement comme pour combobox. Sans lui, le contrôle enregistre l”index sélectionné.
value – la sélection initiale, comparée à values ou utilisée comme index, comme pour combobox.
orientation (string, par défaut "vertical") – "horizontal" pour disposer les boutons en ligne, sinon en colonne.

Enregistre : l’entrée values correspondante (n’importe quel type), ou l”index sélectionné.

13.1.13.4.2.4. spinbox#

Une zone de saisie numérique pour les entiers, avec des flèches haut/bas.

{
  "type": "spinbox",
  "name": "server_port",
  "label": "Port",
  "value": 8080,
  "min": 0,
  "max": 65535,
  "group_separator": true
}

Arguments :

value (integer, par défaut 0) – le nombre initial.
min (integer, par défaut 0 ou value, selon le plus petit) – la valeur la plus basse autorisée.
max (integer, par défaut 100 ou value, selon le plus grand) – la valeur la plus haute autorisée.
step (integer, par défaut 1) – l’incrément haut/bas.
prefix (string) – texte affiché avant le nombre, p. ex. "0x".
suffix (string) – texte affiché après le nombre, p. ex. une unité comme " px".
base (integer, par défaut 10) – la base d’affichage ; réglez sur 16 pour afficher et modifier le nombre en hexadécimal.
group_separator (boolean, par défaut false) – regroupe les chiffres avec des séparateurs de milliers.
special_value_text (string) – texte à afficher à la place du nombre lorsqu’il se situe à min, p. ex. afficher « Off » à 0.

Enregistre : un entier.

13.1.13.4.2.5. doublespinbox#

Une zone de saisie numérique pour les décimales.

{
  "type": "doublespinbox",
  "name": "sensitivity",
  "label": "Sensitivity",
  "value": 50.0,
  "min": 0,
  "max": 100,
  "step": 0.5,
  "decimals": 1,
  "suffix": " %"
}

Arguments :

value (number, par défaut 0) – le nombre initial.
min (number, par défaut 0 ou value, selon le plus petit) – la valeur la plus basse autorisée.
max (number, par défaut 100 ou value, selon le plus grand) – la valeur la plus haute autorisée.
decimals (integer, par défaut 2) – combien de chiffres afficher après la virgule.
step (number, par défaut 1.0) – l’incrément haut/bas.
prefix (string) – texte affiché avant le nombre, p. ex. "max ".
suffix (string) – texte affiché après le nombre, p. ex. une unité comme " %".
group_separator (boolean, par défaut false) – séparateurs de milliers.
special_value_text (string) – texte à afficher lorsque le nombre se situe à min.

Enregistre : un nombre (virgule flottante).

13.1.13.4.2.6. slider#

Un slider horizontal avec un affichage numérique en direct à côté.

{
  "type": "slider",
  "name": "brightness",
  "label": "Brightness",
  "value": 50,
  "min": 0,
  "max": 100,
  "step": 1,
  "suffix": " %",
  "ticks": 25
}

Arguments :

value (integer, par défaut 0) – la position initiale.
min (integer, par défaut 0 ou value, selon le plus petit) – l’extrémité basse de la glissière.
max (integer, par défaut 100 ou value, selon le plus grand) – l’extrémité haute de la glissière.
step (integer, par défaut 1) – l’incrément au clavier et au glissement ; les glissements s’alignent sur le multiple le plus proche.
prefix (string) – texte affiché avant l’affichage numérique à côté du slider, p. ex. "x".
suffix (string) – texte affiché après l’affichage, p. ex. " %".
ticks (integer) – l’espacement des graduations tracées sous la glissière.

Enregistre : un entier.

13.1.13.4.2.7. lineedit#

Un champ de texte sur une seule ligne, pour les noms, mots de passe, adresses et autres.

{
  "type": "lineedit",
  "name": "hostname",
  "label": "Hostname",
  "value": "openmv-cam",
  "placeholder": "letters, digits, dashes",
  "regex": "[A-Za-z0-9-]+",
  "clear_button": true
}

Arguments :

value (string, par défaut "") – le texte initial.
placeholder (string) – texte indicatif gris affiché tant que le champ est vide.
max_length (integer) – le nombre maximal de caractères que le champ acceptera.
mask (string) – un masque de saisie qui fixe la disposition de ce qui peut être tapé, p. ex. "000.000.000.000;_" pour une adresse IPv4. Voir Input masks ci-dessous.
regex (string) – une expression régulière que la totalité de la saisie doit satisfaire. Voir Regular expressions ci-dessous.
clear_button (boolean, par défaut false) – affiche un petit bouton d’effacement à l’intérieur du champ.
password (boolean, par défaut false) – masque le texte sous forme de points et ajoute un bouton en forme d’œil pour le révéler.

Enregistre : une chaîne.

Un mask et une regex restreignent tous deux ce que le champ acceptera, mais sous des angles opposés – un masque fixe la disposition du texte, une regex en contraint le contenu. Un champ doté de l’un ou l’autre est le seul contrôle capable de bloquer un Save : si son texte est incomplet ou ne correspond pas, l’éditeur énumère le champ par son label et refuse d’enregistrer tant qu’il n’est pas corrigé ou vidé. N’utilisez au plus qu’un seul des deux sur un champ.

13.1.13.4.2.7.1. Masques de saisie#

Un mask fixe le champ caractère par caractère : les séparateurs sont tracés pour l’utilisateur, qui n’a plus qu’à remplir les blancs. Chaque caractère de masque représente une position de saisie :

9 – un chiffre requis ; 0 – un chiffre facultatif.
A / a – une lettre requise / facultative.
N / n – une lettre ou un chiffre requis / facultatif.
X / x – un caractère quelconque requis / facultatif.
H / h – un chiffre hexadécimal requis / facultatif.
> / < – met en majuscules / minuscules les lettres qui suivent ; ! arrête la conversion.

Tout autre caractère – le . dans 000.000.000.000, un - dans un numéro de série – est un séparateur littéral : il est placé automatiquement et sauté au fur et à mesure que l’utilisateur tape. Pour utiliser un caractère de masque comme littéral, faites-le précéder d’une barre oblique inverse.

Un ; vers la fin définit le caractère de remplissage affiché pour les positions non renseignées : "000.000.000.000;_" affiche un champ vide sous la forme ___.___.___.___. Omettez-le et les blancs sont des espaces. Tant qu’une position requise reste vide, la saisie est incomplète, ce qui bloque le Save.

13.1.13.4.2.7.2. Expressions régulières#

Une regex vérifie le contenu plutôt que la disposition, et convient mieux lorsque la règle est « ces caractères, ce motif » plutôt qu’un champ fixe. La totalité de la saisie doit correspondre – l’expression est ancrée aux deux extrémités, si bien que "[A-Za-z0-9-]+" signifie uniquement des lettres, des chiffres et des tirets du début à la fin, et non simplement « en contient un ».

La vérification s’exécute à chaque frappe. Un caractère est accepté tant que le texte pourrait encore évoluer vers une correspondance complète, et rejeté dès qu’il ne le peut plus, de sorte que l’utilisateur ne peut jamais aboutir par la saisie à quelque chose d’invalide. Le champ est considéré comme valide – et le Save est autorisé – seulement une fois que l’expression entière correspond ; une saisie partielle en cours de route reste en place mais bloque le Save jusqu’à ce qu’elle soit complète.

Pour construire et tester un motif, regex101.com explique chaque partie au fur et à mesure de la saisie – réglez sa variante sur PCRE2, la syntaxe qu’utilise l’éditeur.