13.1.13.4.2. Controlos de valor#

Estes são os controlos que guardam uma definição. Cada um transporta um value, e Guardar escreve o value editado de volta no controlo. A tabela abaixo é o mapa rápido do controlo para o tipo JSON que armazena; as secções seguintes documentam cada chave.

Controlo

Guarda

checkbox

boolean, ou inteiro 0/1/2

combobox

o valor escolhido, ou o seu índice

radio

o valor escolhido, ou o seu índice

spinbox

inteiro

doublespinbox

número (vírgula flutuante)

slider

inteiro

lineedit

string

Todos os controlos de valor também aceitam as chaves comuns (name, label, tooltip, enabled); consulte a descrição geral. O label é apresentado ao lado do controlo (na própria caixa no caso de uma checkbox).

13.1.13.4.2.1. checkbox#

Um interruptor ligado/desligado. Opcionalmente de três estados, para definições que têm um estado intermédio «por definir».

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

Argumentos:

  • label (string) – o texto mostrado junto à caixa. Apenas texto simples (ao contrário dos outros controlos, cujas etiquetas aceitam texto formatado).

  • tristate (boolean, predefinição false) – permite um terceiro estado, parcialmente marcado.

  • value – o estado inicial. Dois estados: um boolean. Três estados: 0 (desligado), 1 (parcial), ou 2 (ligado).

Guarda: um boolean para uma caixa de dois estados; um inteiro 0, 1, ou 2 para uma caixa de três estados.

13.1.13.4.2.2. combobox#

Um menu pendente 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 mostrados no menu.

  • values (array) – um array paralelo opcional dos valores a guardar, um por cada option. Com values, o menu mostra options[i] mas guarda values[i] – por isso o utilizador vê «QVGA» enquanto o ficheiro armazena "qvga". As entradas podem ser de qualquer tipo JSON. Sem values, o controlo guarda antes o índice do item selecionado.

  • value – a seleção inicial. Com values, a entrada igual a um dos values. Sem values, o índice do item a selecionar (predefinição 0).

Guarda: a entrada values correspondente (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 de cada vez, como um combobox mas apresentado 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 cada entrada.

  • values (array) – os valores opcionais a guardar, um por cada option, exatamente como em combobox. Sem ele, o controlo guarda o índice selecionado.

  • value – a seleção inicial, comparada com values ou usada como índice, como em combobox.

  • orientation (string, predefinição "vertical") – "horizontal" para dispor os botões numa linha, caso contrário numa coluna.

Guarda: a entrada values correspondente (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, predefinição 0) – o número inicial.

  • min (inteiro, predefinição 0 ou value, o que for menor) – o valor mais baixo permitido.

  • max (inteiro, predefinição 100 ou value, o que for maior) – o valor mais alto permitido.

  • step (inteiro, predefinição 1) – o incremento para cima/baixo.

  • prefix (string) – texto mostrado antes do número, por exemplo "0x".

  • suffix (string) – texto mostrado depois do número, por exemplo uma unidade como " px".

  • base (inteiro, predefinição 10) – a base de apresentação; defina como 16 para mostrar e editar o número em hexadecimal.

  • group_separator (boolean, predefinição false) – agrupa os dígitos com separadores de milhares.

  • special_value_text (string) – texto a mostrar no lugar do número quando este está em min, por exemplo mostrar «Off» em 0.

Guarda: 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, predefinição 0) – o número inicial.

  • min (número, predefinição 0 ou value, o que for menor) – o valor mais baixo permitido.

  • max (número, predefinição 100 ou value, o que for maior) – o valor mais alto permitido.

  • decimals (inteiro, predefinição 2) – quantos dígitos mostrar depois da vírgula decimal.

  • step (número, predefinição 1.0) – o incremento para cima/baixo.

  • prefix (string) – texto mostrado antes do número, por exemplo "max ".

  • suffix (string) – texto mostrado depois do número, por exemplo uma unidade como " %".

  • group_separator (boolean, predefinição false) – separadores de milhares.

  • special_value_text (string) – texto a mostrar quando o número está em min.

Guarda: um número (vírgula flutuante).

13.1.13.4.2.6. slider#

Um slider horizontal com uma leitura numérica em tempo real ao seu lado.

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

Argumentos:

  • value (inteiro, predefinição 0) – a posição inicial.

  • min (inteiro, predefinição 0 ou value, o que for menor) – o extremo inferior da barra.

  • max (inteiro, predefinição 100 ou value, o que for maior) – o extremo superior da barra.

  • step (inteiro, predefinição 1) – o incremento do teclado e do arrasto; os arrastos ajustam-se ao múltiplo mais próximo.

  • prefix (string) – texto mostrado antes da leitura numérica ao lado do slider, por exemplo "x".

  • suffix (string) – texto mostrado depois da leitura, por exemplo " %".

  • ticks (inteiro) – o espaçamento das marcas desenhadas sob a barra.

Guarda: um inteiro.

13.1.13.4.2.7. lineedit#

Um campo de texto de uma só linha, para nomes, palavras-passe, endereços e afins.

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

Argumentos:

  • value (string, predefinição "") – o texto inicial.

  • placeholder (string) – texto de sugestão cinzento mostrado enquanto o campo está vazio.

  • max_length (inteiro) – o número máximo de carateres que o campo aceita.

  • mask (string) – uma máscara de entrada que fixa a disposição do que pode ser escrito, 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 tem de corresponder. Consulte Regular expressions abaixo.

  • clear_button (boolean, predefinição false) – mostra um pequeno botão de limpar dentro do campo.

  • password (boolean, predefinição false) – oculta o texto como pontos e adiciona um botão de olho para o revelar.

Guarda: uma string.

Uma mask e uma regex restringem ambas o que o campo aceita, mas por ângulos opostos – uma máscara fixa a disposição do texto, uma regex restringe o seu conteúdo. Um campo com uma delas é o único controlo que pode bloquear um Guardar: se o seu texto estiver incompleto ou não corresponder, o editor lista o campo pelo seu label e recusa guardar até este ser corrigido ou limpo. Use no máximo uma das duas num campo.

13.1.13.4.2.7.1. Máscaras de entrada#

Uma mask fixa o campo caráter a caráter: os separadores são desenhados para o utilizador, que apenas preenche os espaços em branco. Cada caráter 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 caráter obrigatório / opcional de qualquer tipo.

  • H / h – um dígito hexadecimal obrigatório / opcional.

  • > / < – converte para maiúsculas / minúsculas as letras seguintes; ! interrompe a conversão.

Qualquer outro caráter – o . em 000.000.000.000, um - num número de série – é um separador literal: é colocado automaticamente e ignorado à medida que o utilizador escreve. Para usar um caráter de máscara como literal, coloque uma barra invertida antes dele.

Um ; perto do fim define o marcador mostrado nas posições por preencher: "000.000.000.000;_" mostra um campo vazio como ___.___.___.___. Se o omitir, os espaços em branco são espaços. Enquanto qualquer posição obrigatória estiver por preencher, a entrada está incompleta, o que bloqueia o Guardar.

13.1.13.4.2.7.2. Expressões regulares#

Uma regex verifica o conteúdo em vez da disposição, e é a melhor escolha quando a regra é «estes carateres, este padrão» em vez de um campo fixo. Toda a entrada tem de corresponder – a expressão está ancorada em ambas as extremidades, pelo que "[A-Za-z0-9-]+" significa apenas letras, dígitos e traços do início ao fim, e não meramente «contém um».

A verificação é executada a cada tecla premida. Um caráter é aceite enquanto o texto ainda puder crescer até uma correspondência completa, e rejeitado no momento em que já não puder, de modo que o utilizador nunca consegue escrever algo inválido. O campo é considerado válido – e o Guardar é permitido – apenas quando toda a expressão corresponde; uma entrada parcial a caminho disso mantém-se no lugar mas bloqueia o Guardar até estar completa.

Para construir e testar um padrão, regex101.com explica cada parte à medida que escreve – defina o seu sabor para PCRE2, a sintaxe que o editor usa.