# Áreas de texto

> TextArea — entrada de várias linhas, rolagem e ícones por linha.

Source: https://crossfly.dev/pt/docs/ui/forms-and-input/text-areas — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# Áreas de texto (`TextArea`)

`TextArea` é o campo de **várias linhas** — mesma base (`TextInput`) do `TextField`, com quebra de
linha, rolagem vertical e ícones por linha.

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

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.style.*;   // TextAreaStyle (config comportamental)

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

      // Área multi-linha: precisa de altura explícita.
      // Aqui via fração de container (40% da altura); alternativa: autoHeight no estilo.
      TextArea obs = new TextArea().caption("Observações");
      add(0.4f, obs);

      // Rótulo onde o conteúdo lido será exibido
      Label resultado = new Label("");
      add(LAY_AUTO, resultado);

      // NÃO há callback por tecla: leia getText() no envio
      Button enviar = new Button("Enviar");
      enviar.onAction(c -> resultado.setText("Chars = " + obs.getText().length()));
      add(LAY_AUTO, enviar);
   }
}
```

> 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
TextArea obs = new TextArea()
   .caption("Observações")
   .text("");
painel.add(0.5f, obs);   // ocupa 50% da altura do container (VerticalLayout)

// ler o conteúdo:
String texto = obs.getText();
```

## Construtores e fluent API
| Membro | Efeito |
|---|---|
| `new TextArea()` / `new TextArea("texto")` | vazio / com valor inicial |
| `.caption(String)` | legenda |
| `.text(String)` / `setText(String)` | define o conteúdo |
| `.rightIcons(Icon...)` | ícones à direita, um por linha de ação |
| `.rightIconAction(int linha, Action)` | ação de um ícone específico |
| `getText()` / `clearText()` | ler / limpar |
| `scrollToTop()` · `scrollToBottom()` · `scrollToLine(int)` | rolagem programática |

## Dimensionar
Diferente do `TextField` (altura de uma linha), o `TextArea` precisa de **altura explícita** — dê uma
fração num `VerticalLayout` ou `autoHeight` no estilo:
```java
obs.getStyle().autoHeight(Relative.ofFont(6f));   // ~6 linhas de altura
```

## Boas práticas
- Reserve altura suficiente (fração de container ou `autoHeight`) — senão vira um campo de 1 linha.
- Use `scrollToBottom()` ao anexar texto (ex.: log/chat) para manter a última linha visível.

## Erros comuns
- Não definir altura → a área fica minúscula.
- Esperar rolagem horizontal — `TextArea` quebra linha; use `TextField` para uma linha rolável.

## Veja também
- [Campos de texto](/docs/ui/forms-and-input/text-fields) · [Foco e validação](/docs/ui/forms-and-input/focus-and-validation)
- Catálogo: [TextArea](/docs/ui/widgets/textarea) · Referência: Capítulo 14