# Botão

> A tecla de comando: escreve um valor predefinido, dispara um comando de execução de unidade, abre outro dashboard ou executa uma ação da Logic.

**Botão** é a tecla de comando da paleta. Um clique faz a única coisa que o componente
declara, a *ação* dele, e o painel de propriedades então pede só os campos daquela ação, para
que nenhum campo fique na tela sob uma regra escondida sobre quando ele conta. É um componente
de *Controle*; um novo ocupa 3 × 1 células.

Qualquer que seja a ação, o botão carrega a aparência dele: um par de cores e um ícone
opcional. Num painel de operação o botão é a peça para a qual a mão do operador vai, e a cor e
a marca são o que torna um deles encontrável de relance.

## Conteúdo {#content}

| Campo | O que ele faz | Valores | Padrão |
|---|---|---|---|
| Rótulo | A legenda na tecla. Vazio recai no que a ação escolhida aponta: o último segmento do endereço do ponto escrito, o nome do dashboard de destino, ou o nome da ação da Logic vinculada, e "(sem ponto)", "(sem dashboard)", "(sem ação)" ou "(ausente)" enquanto não há o que nomear. | Texto livre | vazio |

## Ação {#action}

| Campo | O que ele faz | Valores | Padrão |
|---|---|---|---|
| Ao clicar | O que o clique faz. Todo campo abaixo pertence à ação escolhida. | `Escrever um valor` · `Executar um comando de unidade` · `Abrir outro dashboard` · `Executar uma ação da Logic` | `Escrever um valor` |

### Escrever um valor {#write-a-value}

| Campo | O que ele faz | Valores | Padrão |
|---|---|---|---|
| Ponto | O ponto escrito. A lista é estreitada para o que pode mesmo ser escrito: variáveis de memória e tags que não são somente leitura. | Texto livre; sugestões de pontos escrevíveis | vazio |
| Valor escrito | O literal predefinido enviado a cada clique. Ele é lido primeiro contra o tipo do próprio ponto, então um valor que o ponto não pode guardar é recusado na linha de resposta do botão e nunca chega à fila. | Texto livre | `true` |

A escrita passa pelo funil único da lógica da estação e é registrada no diário como toda outra
escrita. Quem espera o equipamento é o botão, não a Lógica, então a linha de resposta diz
"Escrito" só depois que o valor foi aceito; qualquer outra coisa põe ali a recusa nas palavras
de quem recusou, as da própria estação para o que ela resolveu antes de enviar ("'Cmd' não foi
escrito: o equipamento não está conectado.") e as do equipamento para o que aconteceu no fio.
Um valor que uma escrita mais nova no mesmo ponto ultrapassou antes de ele ser enviado aparece
como "'Cmd' foi substituído por um valor mais novo antes de ser enviado."

Sobre uma tag com o estágio **Limites** habilitado, um valor fixo fora desses limites é
recusado na linha de resposta com uma razão que nomeia esses limites, e nada é
escrito: do contrário a tag o tomaria na borda, e o botão confirmaria um valor que a planta
nunca recebeu.

Sobre um ponto que guarda inteiros (uma tag de tipo inteiro cuja Escala e Calibração deixam o valor como está, ou uma variável de memória que guarda inteiros), um valor fixo com fração é recusado na linha de resposta em vez de arredondado ("Este ponto aceita um inteiro, então 2.5 não é escrito nele."), e nada é escrito.

### Executar um comando de unidade {#run-a-unit-command}

| Campo | O que ele faz | Valores | Padrão |
|---|---|---|---|
| Comando | Um ponto de comando de execução de unidade (`Process.<Model>.<Unit>.Commands.*`). Disparar o comando é a instrução inteira: não há valor a escrever. | Texto livre; a lista oferece os pontos de comando de execução da unidade | vazio |

Um ponto de comando informa "pode executar agora", então o botão se desabilita enquanto o
comando não se aplica; um Iniciar com o runtime bloqueado ainda mostra a razão do bloqueio. O
toque executa o comando contra a unidade, atribuído ao operador autenticado, e a linha de
resposta nomeia o comando que rodou.

### Abrir outro dashboard {#open-another-dashboard}

| Campo | O que ele faz | Valores | Padrão |
|---|---|---|---|
| Dashboard | A tela de destino. O seletor lista os dashboards da estação; telas definidas num modelo do Process não são oferecidas, porque elas só abrem a partir de uma unidade. | `(nenhum)` ou um dashboard | `(nenhum)` |

Trocar de tela é um gesto de operação: um painel rodando em tela cheia continua em tela cheia
quando o operador chega. A referência é frouxa: uma tela que foi excluída, ou que o papel
autenticado não vê, não desabilita mais nada; o toque responde "Esse dashboard está
indisponível." na linha do próprio botão, em vez de quebrar a tela.

### Executar uma ação da Logic {#run-a-logic-action}

| Campo | O que ele faz | Valores | Padrão |
|---|---|---|---|
| Ação | A ação da Logic vinculada (veja a [página da Logic](logic)). | `(nenhum)` ou uma ação | `(nenhum)` |

A ação roda na faixa das ações, registrada no diário como vinda do dashboard. A linha de
resposta relata o resultado: "Concluído · 12 ms", ou o erro da própria ação. Uma ação excluída
ou desabilitada desabilita o botão, em vez de quebrá-lo.

## Cor e ícone {#color-and-icon}

Lidos qualquer que seja a ação:

| Campo | O que ele faz | Valores | Padrão |
|---|---|---|---|
| Cor do botão | A face da tecla, como um par, uma metade por tema, as duas na tela ao mesmo tempo, porque o tema em vigor decide qual metade pinta. Um hex digitado pela metade é recusado e os campos voltam às cores em vigor. O que uma cor significa é a sua convenção; o aplicativo não lê nenhuma. | `#RRGGBB` cada | `#FFFFFF` claro · `#2B2B2B` escuro |
| Ícone | Marca opcional antes da legenda, escolhida na biblioteca de ícones do aplicativo (cerca de 2.770 marcas), com busca por nome ou palavra-chave ("em inglês: play, stop, warning…"). A célula `—` é a escolha de nenhum ícone. | Glifo do catálogo ou nenhum | nenhum |

A tinta da legenda é **derivada**, nunca escrita: sobre cada metade da face o aplicativo
escolhe qual dos dois tons de texto dele tem o melhor contraste, então nenhuma cor que você
escolha consegue deixar a legenda ilegível. A legenda se dimensiona pelo contrato de exibição
compartilhado: o que a tecla não comporta é cortado com reticências, com a legenda inteira na
dica.

## Permissões e a trava {#permissions-and-the-lock}

Toda ação exige a permissão do papel para operar dashboards. O que um toque exige além disso se
lê do *alvo* dele, não do tipo: só **Executar um comando de unidade** alcança uma mudança no
Process e exige, além disso, a permissão de executar procedimentos. Um toque que o papel
autenticado não pode fazer desenha a marca de trava compartilhada com a razão na dica do
componente (veja a [página de dashboards](home)); a autorização é reconferida no clique. A
linha de resposta passageira expira depois de alguns segundos. Numa célula sem linha para ela e
sem título de canto sobre a tecla (um botão de uma linha numa grade densa), a resposta toma o
lugar da legenda na tecla enquanto aparece: fica sobre a legenda num tom mais discreto da
própria tinta da legenda, uma recusa na tinta de erro, com a resposta inteira na dica. O ícone e
a tecla ficam onde estão, e a legenda volta quando a resposta expira (veja a
[página de dashboards](home#commands-permissions-and-the-lock-mark)).

As seções compartilhadas Aparência, Identificação, Posição e camada e Ações estão descritas na
[página de componentes](components#the-shared-property-sections).