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; para texto editável use TextField/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 / TextArea.
• Elemento tocável / clicável → use 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)

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

Label hello = new Label("Olá, mundo!");
container.add(LAY_AUTO, hello);

Construtores

Propriedades e personalização

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

// 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)

// 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/ · Receitas: cookbook/
• Conceito (“tudo é Component”): concepts/
• Componentes relacionados: Button · TextField · ImageView