# LabelItem e CheckLabelItem

> Cards prontos de item de lista — só rótulo (SINGLE) ou checkbox + rótulo (MULTIPLE).

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

# LabelItem e CheckLabelItem

`LabelItem` e `CheckLabelItem` são "cards" de item de lista prontos, no pacote `dev.crossfly.ui.listitem`. Ambos estendem `Component` e são usados internamente pelo [`ListView`](/docs/ui/widgets/listview):

- **`LabelItem`** — um único `Label` com quebra de linha. Usado no modo `SINGLE`.
- **`CheckLabelItem`** — um `Option` (check) + `Label`. Usado no modo `MULTIPLE`.

Normalmente você **não** os instancia diretamente — o `ListView` cria o tipo certo conforme o `ItemType`. Use-os quando montar uma lista à mão e quiser a mesma aparência/comportamento de card.

> 🟡 · **Pacote:** `dev.crossfly.ui.listitem` · **Estendem:** `Component` · **Estilo:** `ComponentStyle` (card) + `LabelStyle` (rótulo)

## Quando usar
- Construir uma lista manualmente (fora do `ListView`) reaproveitando o visual de card padrão.
- Um item clicável isolado com aparência consistente com as listas do framework.

## Quando NÃO usar
- Lista de seleção pronta → deixe o [`ListView`](/docs/ui/widgets/listview) criar os itens por você.
- Linha rica com imagem/múltiplos campos → monte um `Component` próprio (ou use `itemFactory` do `ListView`).

## Aparência
Card com fundo/borda do tema de seleção (`selectionCardBackColor`/`selectionCardBorderColor`), `pressable`, com gaps padrão. `LabelItem` mostra o texto alinhado START/CENTER; `CheckLabelItem` põe o check à esquerda (largura automática) e o label ocupando 90%.

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

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.listitem.*;   // LabelItem, CheckLabelItem

/** 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());

      // Lista montada à mão reaproveitando o visual de card padrão.
      Component lista = new Component();
      lista.setLayout(new GridLayout(Position.CENTER, Position.START));
      lista.setScrollable(ScrollDirection.VERTICAL);

      String[] linhas = {"Alpha", "Beta", "Gamma"};
      for (int i = 0; i < linhas.length; i++) {
         LabelItem item = new LabelItem(linhas[i], i);
         final int idx = i;
         item.onAction(e -> System.out.println("selecionou " + idx));
         lista.add(.95f, item);
      }

      CheckLabelItem termos = new CheckLabelItem("Aceito os termos", linhas.length);
      termos.onAction(e -> { termos.toggle(); System.out.println(termos.isChecked()); });
      lista.add(.95f, termos);

      add(LAY_FILL, lista);   // listas usam LAY_FILL (absorvem a altura)
   }
}
```

> 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
// LabelItem — item clicável de rótulo único
LabelItem item = new LabelItem("Linha", 0);
item.onAction(e -> System.out.println("clicou " + item.index));
layout.add(.95f, item);

// CheckLabelItem — item com checkbox
CheckLabelItem c = new CheckLabelItem("Aceito os termos", 0);
c.onAction(e -> { c.toggle(); System.out.println(c.isChecked()); });
layout.add(.95f, c);
```

### LabelItem
| Construtor | Descrição |
|---|---|
| `LabelItem(String text, int index)` | Estilos padrão |
| `LabelItem(String text, int index, ComponentStyle cardStyle, LabelStyle labelStyle)` | Estilos customizados |

### CheckLabelItem
| Construtor | Descrição |
|---|---|
| `CheckLabelItem(String text, int index)` | Estilo padrão |
| `CheckLabelItem(String text, int index, ComponentStyle cardStyle)` | Estilo de card customizado |

Os campos `text` e `index` são `public final`.

## Propriedades e personalização
| Membro | Classe | O que faz |
|---|---|---|
| `text` (final) | ambos | Texto do item |
| `index` (final) | ambos | Índice do item na lista |
| `getAutoHeight()` | ambos | Altura preferida (rótulo/check + ingap) |
| `isChecked()` | `CheckLabelItem` | Estado atual do check |
| `setChecked(boolean)` | `CheckLabelItem` | Define o estado |
| `toggle()` | `CheckLabelItem` | Alterna o estado |
| `getCheck()` | `CheckLabelItem` | Acesso ao `Option` interno |
| `defaultItemStyle()` (static) | ambos | Estilo de card reutilizável (selection card, `pressable`) |
| `defaultLabelStyle()` (static) | `LabelItem` | Estilo de rótulo reutilizável |

## Callbacks e eventos
| Callback | Quando dispara |
|---|---|
| `onAction(Action)` | Ao tocar o card (herdado de `Component`) |

Em `CheckLabelItem`, o toque **não** alterna o check sozinho — chame `toggle()` no seu callback (é o que o `ListView` faz internamente).

## Estados
- **pressed** — ambos são `pressable` por padrão (feedback ao toque).
- **checked** — só `CheckLabelItem`: controlado por `setChecked`/`toggle`, consultável com `isChecked`.

### Lista manual reutilizando o visual de card
```java
Component lista = new Component();
lista.setLayout(new GridLayout(Position.CENTER, Position.START));
lista.setScrollable(ScrollDirection.VERTICAL);
String[] linhas = {"Alpha", "Beta", "Gamma"};
for (int i = 0; i < linhas.length; i++) {
   LabelItem item = new LabelItem(linhas[i], i);
   final int idx = i;
   item.onAction(e -> System.out.println("selecionou " + idx));
   lista.add(.95f, item);
}
layout.add(LAY_FILL, lista);
```

### CheckLabelItem com card customizado
```java
ComponentStyle card = CheckLabelItem.defaultItemStyle()
   .copy()
   .backColor(0xFFF5F5F5);
CheckLabelItem opt = new CheckLabelItem("Receber notificações", 0, card);
opt.setChecked(true);
opt.onAction(e -> { opt.toggle(); });
layout.add(.95f, opt);
```

## Boas práticas
- Reaproveite `defaultItemStyle()` / `defaultLabelStyle()` (com `.copy()`) para manter a coesão visual com as listas do framework.
- Adicione os itens com largura `.95f` num `GridLayout(CENTER, START)` para reproduzir o espaçamento do `ListView`.

## Erros comuns
- **Esperar que `CheckLabelItem` alterne o check no toque automaticamente** — chame `toggle()` no `onAction`.
- **Instanciar estes itens quando já usa `ListView`** — o `ListView` já cria o tipo correto pelo `ItemType`.

## Veja também
- Guia da área: [`ui/`](/docs/ui) · Receitas: [`cookbook/`](/docs/cookbook)
- Componentes relacionados: [`ListView`](/docs/ui/widgets/listview) · [`ListViewWindow`](/docs/ui/widgets/listviewwindow)