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 ограничивают то, что примет поле, с противоположных сторон – маска фиксирует компоновку текста, регулярное выражение ограничивает его содержимое. Поле с любым из них – единственный элемент управления, который может заблокировать сохранение: если его текст неполон или не соответствует, редактор перечисляет поле по его 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;_" показывает пустое поле как ___.___.___.___. Опустите его – и пропуски будут пробелами. Пока любая обязательная позиция всё ещё пуста, запись неполна, что блокирует сохранение.

13.1.13.4.2.7.2. Регулярные выражения#

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

Проверка выполняется при каждом нажатии клавиши. Символ принимается, пока текст ещё может вырасти до полного соответствия, и отклоняется в тот момент, когда уже не может, поэтому пользователь никогда не сможет набрать что-то недопустимое. Поле считается допустимым – и сохранение разрешено – только когда всё выражение соответствует; частичная запись на пути к этому остаётся на месте, но блокирует сохранение, пока не будет завершена.

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