13.1.13.4.2. Controles de valor#

Estos son los controles que contienen un ajuste. Cada uno lleva un value, y Guardar escribe el value editado de vuelta en el control. La tabla de abajo es la correspondencia rápida entre el control y el tipo JSON que almacena; las secciones que siguen documentan cada clave.

Control	Guarda
checkbox	booleano, o entero `0`/`1`/`2`
combobox	el valor elegido, o su índice
radio	el valor elegido, o su índice
spinbox	entero
doublespinbox	número (punto flotante)
slider	entero
lineedit	cadena

Todos los controles de valor también aceptan las claves comunes (name, label, tooltip, enabled); consulta la descripción general. El label se muestra junto al control (en la casilla misma para una checkbox).

13.1.13.4.2.1. checkbox#

Un interruptor de activado/desactivado. Opcionalmente de tres estados, para ajustes que tienen un punto intermedio «sin definir».

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

Argumentos:

label (cadena) – el texto mostrado junto a la casilla. Solo texto sin formato (a diferencia de los demás controles, cuyas etiquetas admiten texto enriquecido).
tristate (booleano, predeterminado false) – permite un tercer estado, parcialmente marcado.
value – el estado inicial. Dos estados: un booleano. Tres estados: 0 (desactivado), 1 (parcial) o 2 (activado).

Guarda: un booleano para una casilla de dos estados; un entero 0, 1 o 2 para una casilla de tres estados.

13.1.13.4.2.2. combobox#

Un menú desplegable de opciones.

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

Argumentos:

options (arreglo de cadenas) – los elementos mostrados en el menú.
values (arreglo) – un arreglo paralelo opcional de los valores a guardar, uno por option. Con values, el menú muestra options[i] pero guarda values[i] – de modo que el usuario ve «QVGA» mientras el archivo almacena "qvga". Las entradas pueden ser de cualquier tipo JSON. Sin values, el control guarda en su lugar el índice del elemento seleccionado.
value – la selección inicial. Con values, la entrada igual a uno de los values. Sin values, el índice del elemento a seleccionar (predeterminado 0).

Guarda: la entrada correspondiente de values (cualquier tipo) cuando se proporciona values; de lo contrario, el índice seleccionado (entero).

13.1.13.4.2.3. radio#

Un conjunto de botones de opción – una sola elección visible a la vez, como un combobox pero dispuesto por completo.

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

Argumentos:

options (arreglo de cadenas) – un botón por entrada.
values (arreglo) – los valores opcionales a guardar, uno por option, exactamente como en combobox. Sin él, el control guarda el índice seleccionado.
value – la selección inicial, comparada con values o usada como índice, como en combobox.
orientation (cadena, predeterminado "vertical") – "horizontal" para disponer los botones en fila, de lo contrario en columna.

Guarda: la entrada correspondiente de values (cualquier tipo), o el índice seleccionado.

13.1.13.4.2.4. spinbox#

Un cuadro numérico para enteros, con flechas de subir/bajar.

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

Argumentos:

value (entero, predeterminado 0) – el número inicial.
min (entero, predeterminado 0 o value, el que sea menor) – el valor más bajo permitido.
max (entero, predeterminado 100 o value, el que sea mayor) – el valor más alto permitido.
step (entero, predeterminado 1) – el incremento de subir/bajar.
prefix (cadena) – texto mostrado antes del número, p. ej. "0x".
suffix (cadena) – texto mostrado después del número, p. ej. una unidad como " px".
base (entero, predeterminado 10) – la base de visualización; establécela en 16 para mostrar y editar el número en hexadecimal.
group_separator (booleano, predeterminado false) – agrupa los dígitos con separadores de miles.
special_value_text (cadena) – texto a mostrar en lugar del número cuando se encuentra en min, p. ej. mostrar «Off» en 0.

Guarda: un entero.

13.1.13.4.2.5. doublespinbox#

Un cuadro numérico para decimales.

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

Argumentos:

value (número, predeterminado 0) – el número inicial.
min (número, predeterminado 0 o value, el que sea menor) – el valor más bajo permitido.
max (número, predeterminado 100 o value, el que sea mayor) – el valor más alto permitido.
decimals (entero, predeterminado 2) – cuántos dígitos mostrar después del punto decimal.
step (número, predeterminado 1.0) – el incremento de subir/bajar.
prefix (cadena) – texto mostrado antes del número, p. ej. "max ".
suffix (cadena) – texto mostrado después del número, p. ej. una unidad como " %".
group_separator (booleano, predeterminado false) – separadores de miles.
special_value_text (cadena) – texto a mostrar cuando el número se encuentra en min.

Guarda: un número (punto flotante).

13.1.13.4.2.6. slider#

Un deslizador horizontal con una lectura numérica en vivo a su lado.

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

Argumentos:

value (entero, predeterminado 0) – la posición inicial.
min (entero, predeterminado 0 o value, el que sea menor) – el extremo inferior de la barra.
max (entero, predeterminado 100 o value, el que sea mayor) – el extremo superior de la barra.
step (entero, predeterminado 1) – el incremento por teclado y por arrastre; los arrastres se ajustan al múltiplo más cercano.
prefix (cadena) – texto mostrado antes de la lectura numérica junto al deslizador, p. ej. "x".
suffix (cadena) – texto mostrado después de la lectura, p. ej. " %".
ticks (entero) – el espaciado de las marcas dibujadas bajo la barra.

Guarda: un entero.

13.1.13.4.2.7. lineedit#

Un campo de texto de una sola línea, para nombres, contraseñas, direcciones y similares.

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

Argumentos:

value (cadena, predeterminado "") – el texto inicial.
placeholder (cadena) – texto de sugerencia en gris que se muestra mientras el campo está vacío.
max_length (entero) – la cantidad máxima de caracteres que aceptará el campo.
mask (cadena) – una máscara de entrada que fija la disposición de lo que se puede escribir, p. ej. "000.000.000.000;_" para una dirección IPv4. Consulta Input masks más abajo.
regex (cadena) – una expresión regular con la que debe coincidir toda la entrada. Consulta Regular expressions más abajo.
clear_button (booleano, predeterminado false) – muestra un pequeño botón de borrado dentro del campo.
password (booleano, predeterminado false) – oculta el texto con puntos y añade un botón de ojo para revelarlo.

Guarda: una cadena.

Tanto una mask como una regex restringen lo que aceptará el campo, desde ángulos opuestos – una máscara fija la disposición del texto, una regex restringe su contenido. Un campo con cualquiera de las dos es el único control que puede bloquear un Guardar: si su texto está incompleto o no coincide, el editor enumera el campo por su label y se niega a guardar hasta que se corrija o se borre. Usa como mucho una de las dos en un campo.

13.1.13.4.2.7.1. Máscaras de entrada#

Una mask fija el campo carácter por carácter: los separadores se dibujan para el usuario, que solo rellena los huecos. Cada carácter de la máscara representa una posición de entrada:

9 – un dígito obligatorio; 0 – un dígito opcional.
A / a – una letra obligatoria / opcional.
N / n – una letra o dígito obligatorio / opcional.
X / x – un carácter obligatorio / opcional de cualquier tipo.
H / h – un dígito hexadecimal obligatorio / opcional.
> / < – convierte a mayúsculas / minúsculas las letras que siguen; ! detiene la conversión.

Cualquier otro carácter – el . en 000.000.000.000, un - en un número de serie – es un separador literal: se coloca automáticamente y se omite mientras el usuario escribe. Para usar un carácter de máscara como literal, ponle una barra invertida delante.

Un ; cerca del final establece el marcador de posición mostrado para las posiciones sin rellenar: "000.000.000.000;_" muestra un campo vacío como ___.___.___.___. Omítelo y los huecos serán espacios. Mientras alguna posición required siga vacía, la entrada está incompleta, lo que bloquea el guardado.

13.1.13.4.2.7.2. Expresiones regulares#

Una regex comprueba el contenido en lugar de la disposición, y encaja mejor cuando la regla es «estos caracteres, este patrón» en lugar de un campo fijo. Toda la entrada debe coincidir – la expresión está anclada en ambos extremos, de modo que "[A-Za-z0-9-]+" significa solo letras, dígitos y guiones de principio a fin, no simplemente «contiene uno».

La comprobación se ejecuta con cada pulsación de tecla. Un carácter se acepta mientras el texto aún pueda llegar a una coincidencia completa, y se rechaza en cuanto ya no pueda, de modo que el usuario nunca puede llegar escribiendo a algo inválido. El campo cuenta como válido – y se permite Guardar – solo una vez que toda la expresión coincide; una entrada parcial de camino a ello permanece en su sitio pero bloquea el guardado hasta que esté completa.

Para construir y probar un patrón, regex101.com explica cada parte a medida que escribes – establece su variante en PCRE2, la sintaxis que usa el editor.