13.1.13.4.2. Controles de valor#

Estes são os controles que armazenam uma configuração. Cada um carrega um value, e Save grava o value editado de volta no controle. A tabela abaixo é o mapa rápido do controle para o tipo JSON que ele armazena; as seções que se seguem documentam cada chave.

Controle	Salva
checkbox	boolean, ou inteiro `0`/`1`/`2`
combobox	o valor escolhido, ou seu índice
radio	o valor escolhido, ou seu índice
spinbox	inteiro
doublespinbox	número (ponto flutuante)
slider	inteiro
lineedit	string

Todos os controles de valor também aceitam as chaves comuns (name, label, tooltip, enabled); consulte a visão geral. O label é exibido ao lado do controle (na própria caixa no caso de um checkbox).

13.1.13.4.2.1. checkbox#

Um interruptor liga/desliga. Opcionalmente de três estados, para configurações que têm um meio “não definido”.

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

Argumentos:

label (string) – o texto exibido ao lado da caixa. Apenas texto simples (ao contrário dos outros controles, cujos labels aceitam texto formatado).
tristate (boolean, padrão false) – permite um terceiro estado, parcialmente marcado.
value – o estado inicial. Dois estados: um boolean. Tristate: 0 (desligado), 1 (parcial) ou 2 (ligado).

Salva: um boolean para uma caixa de dois estados; um inteiro 0, 1 ou 2 para uma caixa tristate.

13.1.13.4.2.2. combobox#

Um menu suspenso de opções.

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

Argumentos:

options (array de strings) – os itens exibidos no menu.
values (array) – um array paralelo opcional dos valores a salvar, um por option. Com values, o menu exibe options[i] mas salva values[i] – de modo que o usuário vê “QVGA” enquanto o arquivo armazena "qvga". As entradas podem ser de qualquer tipo JSON. Sem values, o controle salva o índice do item selecionado em vez disso.
value – a seleção inicial. Com values, a entrada igual a um dos values. Sem values, o índice do item a selecionar (padrão 0).

Salva: a entrada correspondente de values (qualquer tipo) quando values é fornecido; caso contrário, o índice selecionado (inteiro).

13.1.13.4.2.3. radio#

Um conjunto de botões de opção – uma escolha visível por vez, como um combobox mas exibido por completo.

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

Argumentos:

options (array de strings) – um botão por entrada.
values (array) – os valores opcionais a salvar, um por option, exatamente como para combobox. Sem ele, o controle salva o índice selecionado.
value – a seleção inicial, comparada com values ou usada como índice, como para combobox.
orientation (string, padrão "vertical") – "horizontal" para dispor os botões em uma linha, caso contrário, uma coluna.

Salva: a entrada correspondente de values (qualquer tipo), ou o índice selecionado.

13.1.13.4.2.4. spinbox#

Uma caixa numérica para inteiros, com setas para cima/baixo.

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

Argumentos:

value (inteiro, padrão 0) – o número inicial.
min (inteiro, padrão 0 ou value, o que for menor) – o menor valor permitido.
max (inteiro, padrão 100 ou value, o que for maior) – o maior valor permitido.
step (inteiro, padrão 1) – o incremento para cima/baixo.
prefix (string) – texto exibido antes do número, por exemplo "0x".
suffix (string) – texto exibido após o número, por exemplo uma unidade como " px".
base (inteiro, padrão 10) – a base de exibição; defina como 16 para mostrar e editar o número em hexadecimal.
group_separator (boolean, padrão false) – agrupa os dígitos com separadores de milhares.
special_value_text (string) – texto a exibir no lugar do número quando ele estiver em min, por exemplo, mostrar “Off” em 0.

Salva: um inteiro.

13.1.13.4.2.5. doublespinbox#

Uma caixa numérica para decimais.

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

Argumentos:

value (número, padrão 0) – o número inicial.
min (número, padrão 0 ou value, o que for menor) – o menor valor permitido.
max (número, padrão 100 ou value, o que for maior) – o maior valor permitido.
decimals (inteiro, padrão 2) – quantos dígitos exibir após o ponto decimal.
step (número, padrão 1.0) – o incremento para cima/baixo.
prefix (string) – texto exibido antes do número, por exemplo "max ".
suffix (string) – texto exibido após o número, por exemplo uma unidade como " %".
group_separator (boolean, padrão false) – separadores de milhares.
special_value_text (string) – texto a exibir quando o número estiver em min.

Salva: um número (ponto flutuante).

13.1.13.4.2.6. slider#

Um slider horizontal com uma leitura numérica ao vivo ao lado dele.

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

Argumentos:

value (inteiro, padrão 0) – a posição inicial.
min (inteiro, padrão 0 ou value, o que for menor) – a extremidade inferior da trilha.
max (inteiro, padrão 100 ou value, o que for maior) – a extremidade superior da trilha.
step (inteiro, padrão 1) – o incremento do teclado e do arraste; os arrastes se ajustam ao múltiplo mais próximo.
prefix (string) – texto exibido antes da leitura numérica ao lado do slider, por exemplo "x".
suffix (string) – texto exibido após a leitura, por exemplo " %".
ticks (inteiro) – o espaçamento das marcas desenhadas sob a trilha.

Salva: um inteiro.

13.1.13.4.2.7. lineedit#

Um campo de texto de linha única, para nomes, senhas, endereços e similares.

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

Argumentos:

value (string, padrão "") – o texto inicial.
placeholder (string) – texto de dica em cinza exibido enquanto o campo está vazio.
max_length (inteiro) – o número máximo de caracteres que o campo aceitará.
mask (string) – uma máscara de entrada que fixa o layout do que pode ser digitado, por exemplo "000.000.000.000;_" para um endereço IPv4. Consulte Input masks abaixo.
regex (string) – uma expressão regular que toda a entrada deve corresponder. Consulte Regular expressions abaixo.
clear_button (boolean, padrão false) – exibe um pequeno botão de limpar dentro do campo.
password (boolean, padrão false) – oculta o texto como pontos e adiciona um botão de olho para revelá-lo.

Salva: uma string.

Uma mask e um regex ambos restringem o que o campo aceitará, de ângulos opostos – uma máscara fixa o layout do texto, um regex restringe seu conteúdo. Um campo com um dos dois é o único controle que pode bloquear um Save: se seu texto estiver incompleto ou não corresponder, o editor lista o campo pelo seu label e se recusa a salvar até que seja corrigido ou limpo. Use no máximo um dos dois em um campo.

13.1.13.4.2.7.1. Máscaras de entrada#

Uma mask fixa o campo caractere por caractere: os separadores são desenhados para o usuário, que apenas preenche os espaços em branco. Cada caractere da máscara representa uma posição de entrada:

9 – um dígito obrigatório; 0 – um dígito opcional.
A / a – uma letra obrigatória / opcional.
N / n – uma letra ou dígito obrigatório / opcional.
X / x – um caractere obrigatório / opcional de qualquer tipo.
H / h – um dígito hexadecimal obrigatório / opcional.
> / < – coloca em maiúsculas / minúsculas as letras que se seguem; ! interrompe a conversão.

Qualquer outro caractere – o . em 000.000.000.000, um - em um número de série – é um separador literal: ele é colocado automaticamente e pulado conforme o usuário digita. Para usar um caractere da máscara como literal, coloque uma barra invertida antes dele.

Um ; perto do final define o espaço reservado exibido para posições não preenchidas: "000.000.000.000;_" exibe um campo vazio como ___.___.___.___. Deixe-o de fora e os espaços em branco serão espaços. Enquanto qualquer posição obrigatória ainda estiver vazia, a entrada está incompleta, o que bloqueia o Save.

13.1.13.4.2.7.2. Expressões regulares#

Um regex verifica o conteúdo em vez do layout, e é a melhor opção quando a regra é “estes caracteres, este padrão” em vez de um campo fixo. Toda a entrada deve corresponder – a expressão é ancorada em ambas as extremidades, portanto "[A-Za-z0-9-]+" significa apenas letras, dígitos e traços do início ao fim, não meramente “contém um”.

A verificação é executada a cada tecla pressionada. Um caractere é aceito enquanto o texto ainda puder crescer até uma correspondência completa, e rejeitado no momento em que não puder, de modo que o usuário nunca consegue digitar até chegar a algo inválido. O campo conta como válido – e o Save é permitido – apenas quando toda a expressão corresponde; uma entrada parcial no caminho até lá permanece no lugar, mas bloqueia o Save até que esteja completa.

Para construir e testar um padrão, regex101.com explica cada parte conforme você digita – defina seu flavor como PCRE2, a sintaxe que o editor usa.