13.1.13.4.2. Controlli di valore#

Questi sono i controlli che contengono un’impostazione. Ciascuno porta un value, e Save riscrive il value modificato nel controllo. La tabella qui sotto è la mappa rapida dal controllo al tipo JSON che memorizza; le sezioni che seguono documentano ogni chiave.

Controllo

Salva

checkbox

boolean, o intero 0/1/2

combobox

il valore scelto, o il suo indice

radio

il valore scelto, o il suo indice

spinbox

intero

doublespinbox

numero (virgola mobile)

slider

intero

lineedit

stringa

Tutti i controlli di valore accettano anche le chiavi comuni (name, label, tooltip, enabled); vedere la panoramica. Il label è mostrato accanto al controllo (sulla casella stessa per un checkbox).

13.1.13.4.2.1. checkbox#

Un interruttore acceso/spento. Facoltativamente a tre stati, per le impostazioni che hanno uno stato intermedio «non impostato».

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

Argomenti:

  • label (string) – il testo mostrato accanto alla casella. Solo testo semplice (a differenza degli altri controlli, le cui etichette accettano rich text).

  • tristate (boolean, predefinito false) – consente un terzo stato, parzialmente selezionato.

  • value – lo stato iniziale. A due stati: un boolean. A tre stati: 0 (spento), 1 (parziale) o 2 (acceso).

Salva: un boolean per una casella a due stati; un intero 0, 1 o 2 per una casella a tre stati.

13.1.13.4.2.2. combobox#

Un menù a discesa di scelte.

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

Argomenti:

  • options (array di stringhe) – gli elementi mostrati nel menù.

  • values (array) – un array parallelo facoltativo dei valori da salvare, uno per ciascuna option. Con values, il menù mostra options[i] ma salva values[i] – così l’utente vede «QVGA» mentre il file memorizza "qvga". Le voci possono essere di qualsiasi tipo JSON. Senza values, il controllo salva invece l”indice dell’elemento selezionato.

  • value – la selezione iniziale. Con values, la voce uguale a uno dei values. Senza values, l’indice dell’elemento da selezionare (predefinito 0).

Salva: la voce values corrispondente (qualsiasi tipo) quando values è fornito; altrimenti l”indice selezionato (intero).

13.1.13.4.2.3. radio#

Un insieme di pulsanti di scelta – una scelta visibile alla volta, come una combobox ma disposta per intero.

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

Argomenti:

  • options (array di stringhe) – un pulsante per ciascuna voce.

  • values (array) – i valori facoltativi da salvare, uno per ciascuna option, esattamente come per combobox. Senza di esso, il controllo salva l”indice selezionato.

  • value – la selezione iniziale, confrontata con values o usata come indice, come per combobox.

  • orientation (string, predefinito "vertical") – "horizontal" per disporre i pulsanti in una riga, altrimenti in una colonna.

Salva: la voce values corrispondente (qualsiasi tipo), o l”indice selezionato.

13.1.13.4.2.4. spinbox#

Una casella numerica per interi, con frecce su/giù.

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

Argomenti:

  • value (integer, predefinito 0) – il numero iniziale.

  • min (integer, predefinito 0 o value, a seconda di quale sia minore) – il valore minimo consentito.

  • max (integer, predefinito 100 o value, a seconda di quale sia maggiore) – il valore massimo consentito.

  • step (integer, predefinito 1) – l’incremento su/giù.

  • prefix (string) – testo mostrato prima del numero, ad esempio "0x".

  • suffix (string) – testo mostrato dopo il numero, ad esempio un’unità come " px".

  • base (integer, predefinito 10) – la base di visualizzazione; imposta a 16 per mostrare e modificare il numero in esadecimale.

  • group_separator (boolean, predefinito false) – raggruppa le cifre con separatori delle migliaia.

  • special_value_text (string) – testo da mostrare al posto del numero quando si trova a min, ad esempio mostrare «Off» a 0.

Salva: un intero.

13.1.13.4.2.5. doublespinbox#

Una casella numerica per i decimali.

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

Argomenti:

  • value (number, predefinito 0) – il numero iniziale.

  • min (number, predefinito 0 o value, a seconda di quale sia minore) – il valore minimo consentito.

  • max (number, predefinito 100 o value, a seconda di quale sia maggiore) – il valore massimo consentito.

  • decimals (integer, predefinito 2) – quante cifre mostrare dopo la virgola decimale.

  • step (number, predefinito 1.0) – l’incremento su/giù.

  • prefix (string) – testo mostrato prima del numero, ad esempio "max ".

  • suffix (string) – testo mostrato dopo il numero, ad esempio un’unità come " %".

  • group_separator (boolean, predefinito false) – separatori delle migliaia.

  • special_value_text (string) – testo da mostrare quando il numero si trova a min.

Salva: un numero (virgola mobile).

13.1.13.4.2.6. slider#

Uno slider orizzontale con una lettura numerica in tempo reale accanto.

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

Argomenti:

  • value (integer, predefinito 0) – la posizione iniziale.

  • min (integer, predefinito 0 o value, a seconda di quale sia minore) – l’estremità inferiore della barra.

  • max (integer, predefinito 100 o value, a seconda di quale sia maggiore) – l’estremità superiore della barra.

  • step (integer, predefinito 1) – l’incremento da tastiera e da trascinamento; i trascinamenti si agganciano al multiplo più vicino.

  • prefix (string) – testo mostrato prima della lettura numerica accanto allo slider, ad esempio "x".

  • suffix (string) – testo mostrato dopo la lettura, ad esempio " %".

  • ticks (integer) – la spaziatura delle tacche disegnate sotto la barra.

Salva: un intero.

13.1.13.4.2.7. lineedit#

Un campo di testo a riga singola, per nomi, password, indirizzi e simili.

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

Argomenti:

  • value (string, predefinito "") – il testo iniziale.

  • placeholder (string) – testo suggerimento in grigio mostrato mentre il campo è vuoto.

  • max_length (integer) – il numero massimo di caratteri che il campo accetterà.

  • mask (string) – una maschera di input che fissa il layout di ciò che può essere digitato, ad esempio "000.000.000.000;_" per un indirizzo IPv4. Vedi Input masks più avanti.

  • regex (string) – un’espressione regolare a cui l’intera voce deve corrispondere. Vedi Regular expressions più avanti.

  • clear_button (boolean, predefinito false) – mostra un piccolo pulsante di cancellazione all’interno del campo.

  • password (boolean, predefinito false) – nasconde il testo come puntini e aggiunge un pulsante a forma di occhio per rivelarlo.

Salva: una stringa.

Sia una mask che una regex limitano ciò che il campo accetterà, ma da angolazioni opposte – una maschera fissa il layout del testo, una regex ne vincola il contenuto. Un campo con l’una o l’altra è l’unico controllo che può bloccare un salvataggio: se il suo testo è incompleto o non corrisponde, l’editor elenca il campo tramite la sua label e rifiuta di salvare finché non viene corretto o svuotato. Usa al massimo una delle due su un campo.

13.1.13.4.2.7.1. Maschere di input#

Una mask fissa il campo carattere per carattere: i separatori sono già disegnati per l’utente, che deve solo riempire gli spazi vuoti. Ogni carattere della maschera rappresenta una posizione di input:

  • 9 – una cifra obbligatoria; 0 – una cifra facoltativa.

  • A / a – una lettera obbligatoria / facoltativa.

  • N / n – una lettera o cifra obbligatoria / facoltativa.

  • X / x – un carattere obbligatorio / facoltativo di qualsiasi tipo.

  • H / h – una cifra esadecimale obbligatoria / facoltativa.

  • > / < – converte in maiuscolo / minuscolo le lettere che seguono; ! interrompe la conversione.

Qualsiasi altro carattere – il . in 000.000.000.000, un - in un numero di serie – è un separatore letterale: viene posizionato automaticamente e saltato mentre l’utente digita. Per usare un carattere di maschera come letterale, anteponigli una barra rovesciata.

Un ; verso la fine imposta il segnaposto mostrato per le posizioni non riempite: "000.000.000.000;_" mostra un campo vuoto come ___.___.___.___. Se lo ometti, gli spazi vuoti sono spazi. Finché una qualsiasi posizione obbligatoria è ancora vuota, la voce è incompleta, il che blocca il salvataggio.

13.1.13.4.2.7.2. Espressioni regolari#

Una regex controlla il contenuto piuttosto che il layout, ed è più adatta quando la regola è «questi caratteri, questo pattern» invece di un campo fisso. L’intera voce deve corrispondere – l’espressione è ancorata a entrambe le estremità, quindi "[A-Za-z0-9-]+" significa solo lettere, cifre e trattini dall’inizio alla fine, non semplicemente «ne contiene uno».

Il controllo viene eseguito a ogni pressione di tasto. Un carattere viene accettato finché il testo può ancora evolvere in una corrispondenza completa, e rifiutato nel momento in cui non può più, così l’utente non può mai digitare qualcosa di non valido. Il campo è considerato valido – e il salvataggio è consentito – solo quando l’intera espressione corrisponde; una voce parziale in via di completamento rimane al suo posto ma blocca il salvataggio finché non è completa.

Per costruire e testare un pattern, regex101.com spiega ogni parte mentre digiti – imposta il suo flavor su PCRE2, la sintassi usata dall’editor.