13.1.13.4.2. Елементи керування зі значеннями#

Це елементи керування, що зберігають налаштування. Кожен з них містить value, і Save записує відредаговане value назад в елемент керування. Таблиця нижче – це швидке зіставлення елемента керування з типом JSON, який він зберігає; наступні розділи документують кожен ключ.

Елемент керування	Зберігає
checkbox	булеве значення або ціле число `0`/`1`/`2`
combobox	вибране значення або його індекс
radio	вибране значення або його індекс
spinbox	ціле число
doublespinbox	число (з рухомою комою)
slider	ціле число
lineedit	рядок

Усі елементи керування значеннями також приймають спільні ключі (name, label, tooltip, enabled); див. огляд. label відображається поряд з елементом керування (на самому полі для checkbox).

13.1.13.4.2.1. checkbox#

Перемикач увімкнення/вимкнення. За бажанням тристановий, для налаштувань, що мають «невстановлену» середину.

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

Аргументи:

label (рядок) – текст, що відображається поруч з рамкою. Лише звичайний текст (на відміну від інших елементів керування, підписи яких приймають форматований текст).
tristate (булеве значення, за замовчуванням false) – дозволити третій, частково позначений стан.
value – початковий стан. Двостановий: булеве значення. Тристановий: 0 (вимкнено), 1 (частково) або 2 (увімкнено).

Зберігає: булеве значення для двостанової рамки; ціле число 0, 1 або 2 для тристанової рамки.

13.1.13.4.2.2. combobox#

Розкривне меню варіантів.

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

Аргументи:

options (масив рядків) – елементи, що відображаються в меню.
values (масив) – необов’язковий паралельний масив значень для збереження, по одному на option. З values меню показує options[i], але зберігає values[i] – тож користувач бачить «QVGA», тоді як файл зберігає "qvga". Записи можуть бути будь-якого типу JSON. Без values елемент керування натомість зберігає індекс вибраного елемента.
value – початковий вибір. З values – запис, що дорівнює одному зі значень values. Без values – індекс елемента для вибору (за замовчуванням 0).

Зберігає: відповідний запис values (будь-який тип), коли задано values; інакше вибраний індекс (ціле число).

13.1.13.4.2.3. radio#

Набір радіокнопок – видно один вибір за раз, як combobox, але викладений повністю.

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

Аргументи:

options (масив рядків) – одна кнопка на запис.
values (масив) – необов’язкові значення для збереження, по одному на option, точно як для combobox. Без нього елемент керування зберігає вибраний індекс.
value – початковий вибір, зіставлений зі значеннями values або використаний як індекс, як для combobox.
orientation (рядок, за замовчуванням "vertical") – "horizontal", щоб викласти кнопки в ряд, інакше – у стовпець.

Зберігає: відповідний запис values (будь-який тип) або вибраний індекс.

13.1.13.4.2.4. spinbox#

Поле для цілих чисел зі стрілками вгору/вниз.

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

Аргументи:

value (ціле число, за замовчуванням 0) – початкове число.
min (ціле число, за замовчуванням 0 або value, залежно від того, що менше) – найменше допустиме значення.
max (ціле число, за замовчуванням 100 або value, залежно від того, що більше) – найбільше допустиме значення.
step (ціле число, за замовчуванням 1) – крок збільшення/зменшення.
prefix (рядок) – текст, що відображається перед числом, наприклад "0x".
suffix (рядок) – текст, що відображається після числа, наприклад одиниця виміру, така як " px".
base (ціле число, за замовчуванням 10) – основа відображення; встановіть 16, щоб показувати та редагувати число у шістнадцятковому вигляді.
group_separator (булеве значення, за замовчуванням false) – групувати цифри роздільниками тисяч.
special_value_text (рядок) – текст для відображення замість числа, коли воно перебуває на min, наприклад показати «Off» при 0.

Зберігає: ціле число.

13.1.13.4.2.5. doublespinbox#

Поле для десяткових чисел.

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

Аргументи:

value (число, за замовчуванням 0) – початкове число.
min (число, за замовчуванням 0 або value, залежно від того, що менше) – найменше допустиме значення.
max (число, за замовчуванням 100 або value, залежно від того, що більше) – найбільше допустиме значення.
decimals (ціле число, за замовчуванням 2) – скільки цифр показувати після десяткової коми.
step (число, за замовчуванням 1.0) – крок збільшення/зменшення.
prefix (рядок) – текст, що відображається перед числом, наприклад "max ".
suffix (рядок) – текст, що відображається після числа, наприклад одиниця виміру, така як " %".
group_separator (булеве значення, за замовчуванням false) – роздільники тисяч.
special_value_text (рядок) – текст для відображення, коли число перебуває на min.

Зберігає: число (з рухомою комою).

13.1.13.4.2.6. slider#

Горизонтальний повзунок із живим числовим показом поруч.

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

Аргументи:

value (ціле число, за замовчуванням 0) – початкова позиція.
min (ціле число, за замовчуванням 0 або value, залежно від того, що менше) – нижній кінець доріжки.
max (ціле число, за замовчуванням 100 або value, залежно від того, що більше) – верхній кінець доріжки.
step (ціле число, за замовчуванням 1) – крок для клавіатури та перетягування; перетягування прив’язуються до найближчого кратного.
prefix (рядок) – текст, що відображається перед числовим показом поруч з повзунком, наприклад "x".
suffix (рядок) – текст, що відображається після показу, наприклад " %".
ticks (ціле число) – відстань між позначками, намальованими під доріжкою.

Зберігає: ціле число.

13.1.13.4.2.7. lineedit#

Однорядкове текстове поле, для імен, паролів, адрес тощо.

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

Аргументи:

value (рядок, за замовчуванням "") – початковий текст.
placeholder (рядок) – сірий підказковий текст, що відображається, поки поле порожнє.
max_length (ціле число) – максимальна кількість символів, яку прийме поле.
mask (рядок) – вхідна маска, що фіксує компонування того, що можна ввести, наприклад "000.000.000.000;_" для адреси IPv4. Див. Input masks нижче.
regex (рядок) – регулярний вираз, якому має відповідати весь запис. Див. Regular expressions нижче.
clear_button (булеве значення, за замовчуванням false) – показати невелику кнопку очищення всередині поля.
password (булеве значення, за замовчуванням false) – приховати текст крапками та додати кнопку-око для його показу.

Зберігає: рядок.

І mask, і regex обмежують те, що прийме поле, але з протилежних боків – маска фіксує компонування тексту, а регулярний вираз обмежує його вміст. Поле з будь-яким із них – єдиний елемент керування, що може заблокувати Save: якщо його текст неповний або не відповідає, редактор перелічує поле за його label і відмовляється зберігати, поки його не виправлено або не очищено. Використовуйте не більше одного з двох на полі.

13.1.13.4.2.7.1. Вхідні маски#

mask фіксує поле посимвольно: роздільники малюються за користувача, який лише заповнює пропуски. Кожен символ маски позначає одну позицію вводу:

9 – обов’язкова цифра; 0 – необов’язкова цифра.
A / a – обов’язкова / необов’язкова літера.
N / n – обов’язкова / необов’язкова літера або цифра.
X / x – обов’язковий / необов’язковий символ будь-якого виду.
H / h – обов’язкова / необов’язкова шістнадцяткова цифра.
> / < – перетворює наступні літери у верхній / нижній регістр; ! зупиняє перетворення.

Будь-який інший символ – . у 000.000.000.000, - у серійному номері – є буквальним роздільником: він розміщується автоматично і пропускається, поки користувач набирає. Щоб використати символ маски як буквальний, поставте перед ним зворотну скісну риску.

; ближче до кінця задає заповнювач, що відображається для незаповнених позицій: "000.000.000.000;_" показує порожнє поле як ___.___.___.___. Пропустіть його, і пропуски будуть пробілами. Поки будь-яка обов’язкова позиція залишається порожньою, запис неповний, що блокує Save.

13.1.13.4.2.7.2. Регулярні вирази#

regex перевіряє вміст, а не компонування, і краще підходить, коли правило – це «ці символи, цей шаблон», а не фіксоване поле. Весь запис має відповідати – вираз прив’язаний з обох кінців, тож "[A-Za-z0-9-]+" означає лише літери, цифри та дефіси від початку до кінця, а не просто «містить один».

Перевірка виконується при кожному натисканні клавіші. Символ приймається, доки текст ще може вирости до повної відповідності, і відхиляється в мить, коли це стає неможливим, тож користувач ніколи не зможе набрати щось недійсне. Поле вважається дійсним – і Save дозволено – лише коли весь вираз відповідає; частковий запис на шляху до цього залишається на місці, але блокує Save, поки не буде завершений.

Щоб побудувати та перевірити шаблон, regex101.com пояснює кожну частину під час набору – встановіть його різновид на PCRE2, синтаксис, який використовує редактор.