# Componentes de dashboard

> O que é um componente de dashboard: o catálogo de tipos, os endereços que eles vinculam, como uma leitura é desenhada, e as seções de propriedade que todo tipo compartilha.

Um **componente** é um item num dashboard: um retângulo de células da grade que desenha
alguma coisa. A maioria dos componentes lê o espaço de endereços ao vivo e o apresenta,
alguns escrevem nele, e alguns só desenham. Você coloca um pela área **Adicionar** do
trilho de ferramentas do [editor de dashboard](view-editor), arrastando-o para uma célula
exata ou clicando nele para tomar a primeira livre, e ele abre em Propriedades para você
configurar.

Todo tipo tem uma página de referência própria, listada em [O catálogo](#the-catalog) e na
lista deste grupo. Esta página guarda o que todos eles têm em comum: os endereços que
vinculam, como uma leitura é desenhada, e as seções de propriedade que se repetem em todo
tipo. Qual papel pode pressionar um controle, e a marca de trava que um componente ganha
quando o papel autenticado não pode, estão em [View e dashboards](home).

## O catálogo {#the-catalog}

A paleta Adicionar agrupa o catálogo por categoria, e as categorias dizem o que cada
família faz. **Exibição** é tudo o que relata: os mostradores simples e as tabelas, as
lâmpadas, e os gráficos que acompanham pontos ao longo do tempo ou os comparam lado a lado.
**Controle** é a família dedicada a escrever: cada componente dela existe para pôr um valor
num ponto. Ela não é a única superfície que um operador pressiona, no entanto. **Alarme**
traz o registro de pendências para uma tela, e o aviso dele é reconhecido dali, por linha e
em lote. **Mídia**
coloca figuras, marcas da biblioteca e arte industrial. **Estrutura** agrupa uma região
atrás do resto da tela.

| Categoria | Componentes |
|---|---|
| Exibição | [Rótulo](component-label) · [Valor](component-value) · [Tabela de pontos](component-point-table) · [LED de estado](component-status-led) · [Gráfico de linhas](component-line-chart) · [Gráfico de barras](component-bar-chart) · [Gráfico de pizza](component-pie-chart) · [Medidor](component-gauge) · [Cartão de KPI](component-kpi-card) · [Progresso](component-progress) |
| Controle | [Interruptor](component-toggle) · [Entrada](component-input) · [Botão](component-button) · [Seletor](component-selector) · [Controle deslizante de setpoint](component-setpoint-slider) · [Teclas de passo](component-step-keys) |
| Alarme | [Aviso de alarme](component-alarm-banner) |
| Mídia | [Imagem](component-image) · [Ícone](component-icon) · [Símbolo](component-symbol) |
| Estrutura | [Moldura](component-frame) |

Três páginas deste grupo descrevem partes do [painel de unidade](view-unit-panels), não
componentes: o aviso do [Intertravamento](component-interlock), a
[Lista de ocorrências](component-occurrence-list) e a
[Linha do tempo de comentários](component-comment-timeline). O painel de unidade os desenha para
a própria unidade; eles nunca são colocados numa tela, e a paleta Adicionar não os oferece.

As figuras, as marcas e a arte que os tipos de Mídia desenham vêm da biblioteca da própria
estação, na página da Logic: [A biblioteca de recursos](logic-assets) guarda as imagens, os
ícones e as cores, e os [Símbolos](assets-symbols) guardam o catálogo de que um
[Símbolo](component-symbol) é escolhido, com os terminais entre os quais as ligações dele
são desenhadas.

## Endereços e leituras ao vivo {#addresses-and-live-readings}

Os componentes ao vivo se vinculam a **endereços**: nomes com raiz dentro do espaço de
endereços ao vivo da estação, o mesmo espaço que a Logic lê (veja a
[página da Logic](logic)). Um endereço nomeia um ponto, onde quer que ele more:

| Formato do endereço | O que ele nomeia |
|---|---|
| `Connector.<Driver>.<Device>.<Tag>` | O valor de engenharia de uma tag do Connector, com as pastas do dispositivo entre o driver e o dispositivo quando ele está arquivado em alguma (veja a [página do Connector](connector)) |
| `Variables.<name>` | Uma variável da Logic (de memória ou calculada) |
| `Alarms.<name>` | O estado ativo de um alarme |
| `Assets.Icons.<name>` | Uma marca da biblioteca de ícones |
| `Process.<Model>.<Unit>.…` | Os pontos de execução de uma unidade: leituras, `Commands.*`, `Next.<field>`, `Commands.Comment` |

Os campos de endereço são texto livre com sugestões: a lista é tirada da lista de pontos ao
vivo, limitada a 50 linhas, estreitada para a categoria de valor que o campo consome (um
medidor sugere números, um interruptor é encabeçado por pontos booleanos, um controle de escrita
lista só o que pode ser escrito), e toda linha é marcada com o tipo dela. Você sempre pode
digitar um endereço que a lista não oferece, inclusive um que ainda não existe. Assim que um
campo nomeia um ponto, o editor mostra **o que aquele ponto lê neste momento** sob o campo:
a confirmação que um componente sem número próprio a desenhar não consegue dar. Numa tela
definida num modelo do Process, os canais abstratos do modelo encabeçam toda lista; escolher
um deles vincula o canal e deixa a unidade para ser respondida quando uma unidade abrir a
tela.

O canvas atualiza os componentes dele a partir do espaço de endereços a cada 150 ms na
janela da própria estação e a cada 400 ms num navegador remoto, sobre os valores que a
varredura da lógica publica. Duas regras valem para todo componente ao vivo:

- **Nunca um valor velho.** Um ponto que para de ler cai para o texto de espera do próprio
  componente (o traço de lacuna, uma lâmpada vazada, uma lacuna no gráfico), nunca para o
  último número.
- **Uma marca de leitura ruim só.** Um componente cujo ponto vinculado *não consegue ler* (o
  endereço não resolve para nada, ou o ponto responde com qualidade ruim) ganha uma marca
  compartilhada: um contorno tracejado de atenção em volta da célula e um pequeno `!` dentro
  de um círculo no canto superior direito. Todo tipo ganha a mesma marca, então ela é
  aprendida uma vez só. Um ponto resolvido que responde com qualidade boa e *sem valor* não é
  uma falha (uma bancada entre execuções, um contador fora de um ciclo), então o componente
  mantém o texto de espera discreto dele e a marca continua apagada. Um endereço **sem
  vínculo** não é culpa de ninguém: uma tela ainda em montagem nunca se lê como uma tela de
  avisos.

## Exibição de valores {#value-display}

Quão grande uma leitura é desenhada é governado por um contrato só, compartilhado por toda
superfície de texto do canvas (mostradores, legendas, faces de tecla, palavras de estado):

- Toda superfície é **automática** (a célula decide o tamanho, limitada pela largura que as
  declarações da superfície reservam: dígitos, casas decimais, unidade, ou as palavras
  escritas) ou **declarada**, um tamanho em pontos que você dá (de 9 a 144). Um tamanho
  declarado é literal: ele desenha naquele tamanho em qualquer célula e nunca é reduzido para
  o conteúdo caber. Nada no tamanho jamais segue o valor que por acaso chegou, então um número
  que oscila entre quatro e seis caracteres nunca mexe no texto.
- **Um número nunca é desenhado cortado.** Onde ele não pode ser mostrado inteiro (mais
  dígitos do que o campo declara, ou um tamanho declarado mais largo que a célula) a
  superfície desenha `####`, a marca da planilha e do DCS para um campo estreito demais para
  o valor dele, com a leitura inteira na dica.
- **O texto livre é cortado com reticências**, com o texto inteiro na dica. As palavras nunca
  ganham a marca do número.
- Um ponto que **não está lendo** é um fato diferente ainda: o traço de lacuna, mais a marca
  compartilhada de leitura ruim onde o silêncio é falha de verdade. A ausência de uma leitura
  e a ausência de espaço nunca tomam emprestada a marca uma da outra.
- Os números se apoiam à direita do campo deles, em algarismos tabulares, para que colunas de
  leituras se alinhem consigo mesmas.

O piso de legibilidade de 11 px vale em todo lugar, e o botão compartilhado de **Escala do
conteúdo** multiplica o tamanho resolvido: para baixo sempre mostra (ainda com o piso), para
cima cresce só até onde a linha ainda cabe sem corte.

## As seções de propriedade compartilhadas {#the-shared-property-sections}

Selecionar um componente abre as propriedades dele. As seções nomeadas para o próprio tipo do
componente vêm primeiro (o conteúdo dele, os dados dele, o formato dele) e estão documentadas
na página daquele componente. Em volta delas, todo componente compartilha as mesmas seções. O
painel que as desenha, a leitura ao vivo sob todo campo de endereço e os controles que se
repetem entre os tipos (tamanho do mostrador, Lê-se como, as faixas da Escala, a caixa de
ferramentas do gráfico) estão descritos em [O editor de dashboard](view-editor).

**Identificação** nomeia o componente para quem edita a tela: o nome encabeça o painel de
propriedades, rotula a linha na lista Componentes e responde à busca dela. Nada o desenha na
tela do operador; isso é o título da Aparência.

**Aparência** é a caixa do componente:

| Campo | O que ele faz | Valores | Padrão |
|---|---|---|---|
| Mostrar a moldura | Desenha o contorno do próprio componente. | ligado / desligado | desligado |
| Espessura da moldura (px) | Quão pesado é esse contorno. Um px é a borda de um cartão; um traço mais pesado distingue um grupo do que está em volta sem uma segunda cor. | de 1 a 4 | 1 |
| Mostrar o fundo | Preenche o retângulo do componente com o par de cores, tornando-o um cartão. Desligado, a grade aparece através dele. | ligado / desligado | desligado |
| Cor do fundo | O preenchimento como um par, uma metade por tema, as duas metades editadas de uma vez, porque o tema em vigor decide qual metade está na tela. | `#RRGGBB` cada | `#FFFFFF` claro · `#2B2B2B` escuro |
| Título (canto) | O rótulo de canto do próprio componente, o que o cartão *é*, acima do que o tipo desenha. Em branco significa nenhuma linha de legenda. | Texto livre | vazio |
| Tamanho do título (px) | Em branco deixa cada cartão dimensionar o título dele a partir da célula; um tamanho declarado é literal e é o que faz os títulos de uma tela inteira concordarem. O que deixa de caber é cortado com reticências, com o título inteiro na dica. | de 11 a 96, ou em branco | em branco (Automático) |
| Cor do título | O par de tinta do título. Sem toque nenhum, o título segue o tom discreto do próprio tema. | `#RRGGBB` cada | `#6B6B6B` claro · `#A0A0A0` escuro |
| Escala do conteúdo | Quanto da caixa o conteúdo toma: a célula que você desenhou já dimensiona o conteúdo, e este botão o regula dentro da célula sem redesenhar a grade. A arte responde geometricamente, um mostrador tipograficamente. | de 0,25 a 3 | 1 |

**Posição e camada** guarda os numéricos X / Y / L / A, a camada (Z) e o par **Trazer para a
frente** / **Enviar para trás**. **Avançado** aparece só nos tipos que têm extras pouco
usados. **Ações** duplica ou remove o componente.

Segure **Ctrl** para selecionar vários componentes e editar o que eles compartilham: os
campos de Aparência se espalham pela seleção inteira (um campo em que os membros discordam
diz "Misto"), os comandos de camada mantêm a ordem relativa do lote, e Duplicar/Remover agem
sobre todos eles. Os campos por tipo exigem um componente só.