# Campos de texto

> TextField — legenda flutuante, ícones, senha com toggle e leitura do valor.

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

# Campos de texto (`TextField`)

`TextField` é o campo de **uma linha**. API fluente para o essencial; o comportamento fino vem do
`TextFieldStyle`.

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

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.style.*;   // TextFieldStyle (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());

      // Campo de nome com legenda flutuante
      TextField nome = new TextField().caption("Nome");
      nome.<TextFieldStyle>getStyle().floatingCaption(true);
      add(LAY_AUTO, nome);

      // Campo de senha com botão de mostrar/ocultar
      TextField senha = new TextField().caption("Senha");
      senha.<TextFieldStyle>getStyle()
         .mode(EditMode.PASSWORD)
         .passwordToggle(true);
      add(LAY_AUTO, senha);

      // Rótulo onde o valor 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("Nome = " + nome.getText()));
      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
TextField nome = new TextField()
   .caption("Nome")                 // legenda flutuante
   .text("");                       // valor inicial
painel.add(LAY_AUTO, nome);

// ler o valor quando precisar (não há evento por tecla):
Button enviar = new Button("Enviar");
enviar.onAction(c -> Debug.log("Nome = " + nome.getText()));
```

## Construtores e fluent API
| Membro | Efeito |
|---|---|
| `new TextField()` / `new TextField("texto")` | campo vazio / com valor inicial |
| `.caption(String)` | legenda (flutua ao focar, se `floatingCaption`) |
| `.text(String)` / `setText(String)` | define o valor |
| `.leftIcon(Icon)` / `.rightIcon(Icon)` | ícones nas pontas |
| `.rightIcon(Icon, Action)` | ícone clicável (ex.: limpar) |
| `.keyboard(Keyboard)` | tipo de teclado (ver [Máscaras e teclados](/docs/ui/forms-and-input/masks-and-keyboards)) |
| `getText()` / `getTextWithoutMask()` | ler valor (com / sem máscara) |
| `clearText()` | limpar |

## Legenda flutuante
Habilite no estilo (`floatingCaption`) — a legenda sobe ao focar/preencher:
```java
TextField email = new TextField().caption("E-mail");
email.<TextFieldStyle>getStyle().floatingCaption(true);
```

## Senha com botão de mostrar/ocultar
```java
TextField senha = new TextField().caption("Senha");
senha.<TextFieldStyle>getStyle()
   .mode(EditMode.PASSWORD)     // mascara os caracteres
   .passwordToggle(true);       // adiciona o ícone de olho automaticamente
```
Com `passwordToggle(true)`, o ícone à direita alterna a visibilidade sozinho.

## Ícone de ação (ex.: limpar)
```java
TextField busca = new TextField().caption("Buscar")
   .rightIcon(new MaterialIcon(""), c -> busca.clearText());  // "close"
```

## Boas práticas
- Leia o valor com `getText()` no momento do envio; para dígitos crus use `getTextWithoutMask()`.
- Configure comportamento (`mode`, `maxLength`, `floatingCaption`) via `getStyle()` tipado
  (`campo.<TextFieldStyle>getStyle()...`).
- Limite o tamanho com `.maxLength(n)` no estilo quando fizer sentido.

## Erros comuns
- Procurar um `onChange`/`onTextChanged` — **não existe**; leia `getText()` quando precisar.
- Confundir `getText()` (com máscara) com `getTextWithoutMask()` (sem) ao salvar no banco.
- Definir `mode`/`mask` no componente — eles são setters do **estilo**.

## Veja também
- [Máscaras e teclados](/docs/ui/forms-and-input/masks-and-keyboards) · [Foco e validação](/docs/ui/forms-and-input/focus-and-validation) · [Áreas de texto](/docs/ui/forms-and-input/text-areas)
- Catálogo: [TextField](/docs/ui/widgets/textfield) · Referência: Capítulo 14