13.1.13.4.2. Kontrolki wartości#

To są kontrolki, które przechowują ustawienie. Każda niesie value, a Zapisz zapisuje edytowaną value z powrotem do kontrolki. Poniższa tabela to szybka mapa od kontrolki do typu JSON, który ona przechowuje; kolejne sekcje dokumentują każdy klucz.

Kontrolka	Zapisuje
checkbox	boolean lub liczba całkowita `0`/`1`/`2`
combobox	wybrana wartość lub jej indeks
radio	wybrana wartość lub jej indeks
spinbox	liczba całkowita
doublespinbox	liczba (zmiennoprzecinkowa)
slider	liczba całkowita
lineedit	ciąg znaków

Wszystkie kontrolki wartości akceptują również wspólne klucze (name, label, tooltip, enabled); zobacz przegląd. Etykieta label jest wyświetlana obok kontrolki (na samym polu w przypadku kontrolki checkbox).

13.1.13.4.2.1. checkbox#

Przełącznik włącz/wyłącz. Opcjonalnie trójstanowy, dla ustawień, które mają środkowy stan „nieustawiony”.

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

Argumenty:

label (string) – tekst wyświetlany obok pola. Tylko zwykły tekst (w przeciwieństwie do pozostałych kontrolek, których etykiety przyjmują tekst sformatowany).
tristate (boolean, domyślnie false) – zezwala na trzeci, częściowo zaznaczony stan.
value – stan początkowy. Dwustanowy: wartość boolean. Trójstanowy: 0 (wyłączony), 1 (częściowy) lub 2 (włączony).

Zapisuje: wartość boolean dla pola dwustanowego; liczbę całkowitą 0, 1 lub 2 dla pola trójstanowego.

13.1.13.4.2.2. combobox#

Rozwijane menu wyboru.

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

Argumenty:

options (tablica ciągów znaków) – elementy wyświetlane w menu.
values (array) – opcjonalna równoległa tablica wartości do zapisania, po jednej na option. Z values menu pokazuje options[i], ale zapisuje values[i] – więc użytkownik widzi „QVGA”, podczas gdy plik przechowuje "qvga". Wpisy mogą być dowolnego typu JSON. Bez values kontrolka zapisuje zamiast tego indeks wybranego elementu.
value – początkowy wybór. Z values wpis równy jednej z wartości values. Bez values indeks elementu do zaznaczenia (domyślnie 0).

Zapisuje: pasujący wpis values (dowolnego typu), gdy podano values; w przeciwnym razie wybrany indeks (liczba całkowita).

13.1.13.4.2.3. radio#

Zestaw przycisków opcji – jeden wybór widoczny naraz, jak combobox, ale rozłożony w całości.

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

Argumenty:

options (tablica ciągów znaków) – jeden przycisk na wpis.
values (array) – opcjonalne wartości do zapisania, po jednej na option, dokładnie jak dla combobox. Bez niej kontrolka zapisuje wybrany indeks.
value – początkowy wybór, dopasowany do values lub użyty jako indeks, jak dla combobox.
orientation (string, domyślnie "vertical") – "horizontal", aby ułożyć przyciski w rzędzie, w przeciwnym razie w kolumnie.

Zapisuje: pasujący wpis values (dowolnego typu) lub wybrany indeks.

13.1.13.4.2.4. spinbox#

Pole liczbowe dla liczb całkowitych, ze strzałkami w górę/w dół.

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

Argumenty:

value (liczba całkowita, domyślnie 0) – liczba początkowa.
min (liczba całkowita, domyślnie 0 lub value, w zależności od tego, która jest mniejsza) – najniższa dozwolona wartość.
max (liczba całkowita, domyślnie 100 lub value, w zależności od tego, która jest większa) – najwyższa dozwolona wartość.
step (liczba całkowita, domyślnie 1) – krok w górę/w dół.
prefix (string) – tekst wyświetlany przed liczbą, np. "0x".
suffix (string) – tekst wyświetlany po liczbie, np. jednostka taka jak " px".
base (liczba całkowita, domyślnie 10) – podstawa wyświetlania; ustaw na 16, aby wyświetlać i edytować liczbę szesnastkowo.
group_separator (boolean, domyślnie false) – grupuje cyfry separatorami tysięcy.
special_value_text (string) – tekst wyświetlany zamiast liczby, gdy znajduje się ona na min, np. wyświetlanie „Off” przy 0.

Zapisuje: liczbę całkowitą.

13.1.13.4.2.5. doublespinbox#

Pole liczbowe dla liczb dziesiętnych.

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

Argumenty:

value (liczba, domyślnie 0) – liczba początkowa.
min (liczba, domyślnie 0 lub value, w zależności od tego, która jest mniejsza) – najniższa dozwolona wartość.
max (liczba, domyślnie 100 lub value, w zależności od tego, która jest większa) – najwyższa dozwolona wartość.
decimals (liczba całkowita, domyślnie 2) – ile cyfr wyświetlać po przecinku dziesiętnym.
step (liczba, domyślnie 1.0) – krok w górę/w dół.
prefix (string) – tekst wyświetlany przed liczbą, np. "max ".
suffix (string) – tekst wyświetlany po liczbie, np. jednostka taka jak " %".
group_separator (boolean, domyślnie false) – separatory tysięcy.
special_value_text (string) – tekst wyświetlany, gdy liczba znajduje się na min.

Zapisuje: liczbę (zmiennoprzecinkową).

13.1.13.4.2.6. slider#

Poziomy suwak z bieżącym odczytem liczbowym obok niego.

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

Argumenty:

value (liczba całkowita, domyślnie 0) – pozycja początkowa.
min (liczba całkowita, domyślnie 0 lub value, w zależności od tego, która jest mniejsza) – dolny koniec ścieżki.
max (liczba całkowita, domyślnie 100 lub value, w zależności od tego, która jest większa) – górny koniec ścieżki.
step (liczba całkowita, domyślnie 1) – krok klawiatury i przeciągania; przeciągnięcia przyciągają do najbliższej wielokrotności.
prefix (string) – tekst wyświetlany przed odczytem liczbowym obok suwaka, np. "x".
suffix (string) – tekst wyświetlany po odczycie, np. " %".
ticks (liczba całkowita) – odstęp między znacznikami rysowanymi pod ścieżką.

Zapisuje: liczbę całkowitą.

13.1.13.4.2.7. lineedit#

Jednowierszowe pole tekstowe, na nazwy, hasła, adresy i tym podobne.

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

Argumenty:

value (string, domyślnie "") – tekst początkowy.
placeholder (string) – szary tekst podpowiedzi wyświetlany, gdy pole jest puste.
max_length (liczba całkowita) – maksymalna liczba znaków, jaką pole przyjmie.
mask (string) – maska wejściowa, która ustala układ tego, co można wpisać, np. "000.000.000.000;_" dla adresu IPv4. Zobacz Input masks poniżej.
regex (string) – wyrażenie regularne, do którego musi pasować cały wpis. Zobacz Regular expressions poniżej.
clear_button (boolean, domyślnie false) – wyświetla mały przycisk czyszczenia wewnątrz pola.
password (boolean, domyślnie false) – ukrywa tekst jako kropki i dodaje przycisk oka, aby go ujawnić.

Zapisuje: ciąg znaków.

Zarówno mask, jak i regex ograniczają to, co pole przyjmie, ale z przeciwnych stron – maska ustala układ tekstu, wyrażenie regularne ogranicza jego zawartość. Pole z którymkolwiek z nich to jedyna kontrolka, która może zablokować Zapisz: jeśli jego tekst jest niekompletny lub nie pasuje, edytor wymienia pole po jego label i odmawia zapisu, dopóki nie zostanie poprawione lub wyczyszczone. Używaj na polu co najwyżej jednego z tych dwóch.

13.1.13.4.2.7.1. Maski wejściowe#

mask ustala pole znak po znaku: separatory są rysowane za użytkownika, który wypełnia tylko puste miejsca. Każdy znak maski oznacza jedną pozycję wejściową:

9 – wymagana cyfra; 0 – opcjonalna cyfra.
A / a – wymagana / opcjonalna litera.
N / n – wymagana / opcjonalna litera lub cyfra.
X / x – wymagany / opcjonalny znak dowolnego rodzaju.
H / h – wymagana / opcjonalna cyfra szesnastkowa.
> / < – zamienia następujące litery na wielkie / małe; ! zatrzymuje konwersję.

Każdy inny znak – . w 000.000.000.000, - w numerze seryjnym – jest dosłownym separatorem: jest umieszczany automatycznie i pomijany podczas wpisywania przez użytkownika. Aby użyć znaku maski jako dosłownego, umieść przed nim ukośnik wsteczny.

; blisko końca ustawia symbol zastępczy wyświetlany dla niewypełnionych pozycji: "000.000.000.000;_" pokazuje puste pole jako ___.___.___.___. Pomiń go, a puste miejsca będą spacjami. Dopóki jakakolwiek wymagana pozycja jest wciąż pusta, wpis jest niekompletny, co blokuje Zapisz.

13.1.13.4.2.7.2. Wyrażenia regularne#

regex sprawdza zawartość, a nie układ, i lepiej pasuje, gdy regułą jest „te znaki, ten wzorzec”, a nie stałe pole. Cały wpis musi pasować – wyrażenie jest zakotwiczone na obu końcach, więc "[A-Za-z0-9-]+" oznacza wyłącznie litery, cyfry i myślniki od początku do końca, a nie jedynie „zawiera jeden”.

Sprawdzanie odbywa się przy każdym naciśnięciu klawisza. Znak jest akceptowany, dopóki tekst mógłby jeszcze rozrosnąć się do pełnego dopasowania, i odrzucany w chwili, gdy nie mógłby, więc użytkownik nigdy nie może wpisać czegoś nieprawidłowego. Pole liczy się jako prawidłowe – a Zapisz jest dozwolony – dopiero gdy całe wyrażenie pasuje; częściowy wpis w drodze do tego pozostaje na miejscu, ale blokuje Zapisz, dopóki nie będzie kompletny.

Aby zbudować i przetestować wzorzec, regex101.com objaśnia każdą część w miarę pisania – ustaw jego wariant na PCRE2, składnię, której używa edytor.