# Label

> Componente não interativo para exibir texto (com word-wrap) e/ou ícones read-only.

Source: https://crossfly.dev/pt/docs/ui/widgets/label — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# Label

`Label` é o widget de **exibição** mais usado: mostra texto somente-leitura, com quebra automática de linha (word-wrap), múltiplas linhas (explícitas via `\n` ou automáticas) e ícones opcionais à esquerda e/ou à direita. Não reage a toque — para ações use [`Button`](/docs/ui/widgets/button); para texto editável use [`TextField`](/docs/ui/widgets/textfield)/[`TextArea`](/docs/ui/widgets/textarea).

A renderização é delegada ao `Design` ativo: o `Label` apenas calcula coordenadas em `onLayout()` e expõe campos públicos que o `Design` consome (fonte, cores e bordas vêm do `LabelStyle`).

> 🟢 · **Pacote:** `dev.crossfly.ui` · **Estende:** `Component` · **Estilo:** `LabelStyle`

## Quando usar
- Títulos, subtítulos, legendas e valores read-only.
- Texto com ícone informativo à esquerda ou à direita.
- Blocos de texto que precisam quebrar em várias linhas.

## Quando NÃO usar
- Texto editável → use [`TextField`](/docs/ui/widgets/textfield) / [`TextArea`](/docs/ui/widgets/textarea).
- Elemento tocável / clicável → use [`Button`](/docs/ui/widgets/button) (o `Label` não responde a toque).

## Aparência
O texto é renderizado dentro da área interna (após `ingap`), alinhado horizontal e verticalmente conforme `LabelStyle.textAlignH`/`textAlignV`. O ícone esquerdo fica colado à borda interna esquerda; o direito à borda interna direita; o texto ocupa o espaço entre eles.

``

## Exemplo completo (copiar, colar e rodar)
```java
package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;

/** Tela principal executável. Aponte o launcher (classname) e rode: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      // Label somente-leitura que será atualizado pelo botão
      Label saida = new Label("Toque no botão abaixo");
      add(LAY_AUTO, saida);

      // Botão que muta o texto do Label (Label.setText é fluente e retorna Label)
      Button ola = new Button("Dizer olá").onAction(c -> saida.setText("Olá, mundo!"));
      add(LAY_AUTO, ola);
   }
}
```

> Os trechos abaixo mostram **só o miolo** (o que vai dentro de `onShow()`). Para rodar, coloque-os no esqueleto `MainWindow` acima.

## Uso básico
```java
Label hello = new Label("Olá, mundo!");
container.add(LAY_AUTO, hello);
```

## Construtores
| Construtor | Descrição |
|---|---|
| `Label()` | label vazio (`text = ""`) |
| `Label(String text)` | label de texto |
| `Label(Icon onlIcon)` | label somente-ícone (ícone à esquerda) |

## Propriedades e personalização
| Propriedade / método | Tipo | Padrão | O que faz |
|---|---|---|---|
| `setText(String)` | `Label` (fluente) | — | troca o texto; invalida o layout **só se** o valor mudou |
| `leftIcon(Icon)` | `Label` (fluente) | `null` | define o ícone à esquerda do texto |
| `rightIcon(Icon)` | `Label` (fluente) | `null` | define o ícone à direita do texto |
| `text` | `String` (campo público) | `""` | conteúdo atual (pode conter `\n`) |
| estilo `.textAlign(Position, Position)` | `Position` | tema | alinhamento horizontal/vertical do texto |
| estilo `.backColor(int)` / `.borderColor(int)` | ARGB | tema | fundo/borda (use `0` para transparente) |
| `getAutoWidth()` / `getAutoHeight(int)` | `int` | — | tamanhos preferidos (usados pelo layout) |
| `Label.wordWrap(String, Font, int)` *(static)* | `String[]` | — | utilitário de quebra de linha por largura |

> `setText(String)` retorna `Label` (para fluência), **não** `void` — por isso o `Label` não declara `implements TextComponent`, apesar de expor `setText`/`text`.

## Callbacks e eventos
Nenhum. `Label` é não interativo — não dispara `onAction` nem eventos de toque.

## Estados
Sem estados de interação (não há `pressed`/`focused`). O visual muda apenas com o estilo aplicado ou via `setEnabled(false)` (aparência desabilitada, conforme o `Design`).

### Ícone à esquerda e subtítulo sem fundo
```java
// Label com ícone à esquerda (Material "info")
Label info = new Label("Informação")
   .leftIcon(new MaterialIcon(""));
container.add(LAY_AUTO, info);

// Subtítulo alinhado à esquerda, sem fundo/borda
Label sub = new Label("Lista:").style(
   Styles.theme().label(LabelRole.SUBTITLE)
      .backColor(0)
      .borderColor(0)
      .textAlign(Position.START, Position.CENTER));
container.add(LAY_AUTO, sub);
```

### Multilinha (word-wrap + `\n` explícito)
```java
// Quebras explícitas
Label endereco = new Label("Rua das Flores, 123\nCentro\n01000-000");

// Word-wrap automático: dê largura ao Label (LAY_FILL) para a quebra ocorrer
Label paragrafo = new Label(
   "Este texto longo quebra automaticamente em várias linhas quando "
 + "a largura disponível é menor que a largura do texto.");
container.add(LAY_FILL, paragrafo);
```

## Boas práticas
- Para word-wrap, garanta que o layout dê **largura** ao `Label` (ex.: `add(LAY_FILL, label)` num `VerticalLayout`). Sem largura conhecida, apenas os `\n` explícitos são contados na altura.
- Use papéis do tema (`LabelRole.TITLE`/`SUBTITLE`/…) em vez de hard-codar fonte/cor.

## Erros comuns
- **Esperar word-wrap sem largura definida:** se a largura é `0`/desconhecida no cálculo de altura, só as quebras `\n` explícitas contam. Dê largura ao `Label`.
- **Confundir `setText` com o contrato `TextComponent.setText`:** aqui `setText` retorna `Label`, não `void`; o `Label` não implementa `TextComponent`.

## Veja também
- Guia da área: [`ui/`](/docs/ui) · Receitas: [`cookbook/`](/docs/cookbook)
- Conceito ("tudo é `Component`"): [`concepts/`](/docs/concepts)
- Componentes relacionados: [`Button`](/docs/ui/widgets/button) · [`TextField`](/docs/ui/widgets/textfield) · [`ImageView`](/docs/ui/widgets/imageview)