TextField

TextField é a entrada de texto de uma linha. Sobre a base TextInput, adiciona: motor de máscara (data, moeda, customizada), modo senha (com toggle mostrar/ocultar), ícones esquerdo/direito clicáveis, rolagem horizontal e um caption flutuante opcional. O comportamento de entrada é definido por EditMode (NORMAL/DATE/CURRENCY/NUMERIC/TIME/PASSWORD), que também escolhe o teclado padrão.

🟡 · Pacote: dev.crossfly.ui · Estende: TextInput · Estilo: TextFieldStyle (default e focused distintos)

Quando usar

Qualquer entrada de uma linha: nome, e-mail, senha, valores numéricos/monetários, data, hora.
Campos com máscara (CEP, telefone, data) ou com ícone clicável (limpar, buscar, olho de senha).

Quando NÃO usar

Texto de múltiplas linhas (observações, comentários) → use TextArea.
Escolha entre opções fixas → use Dropdown / Option (ver ui/).

Aparência

Caixa com fundo/borda do TextFieldStyle, texto numa linha, ícones opcionais nas pontas e, opcionalmente, um caption flutuante (floatingCaption) que sobe acima do campo quando há foco ou conteúdo.

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

      // Campo de uma linha com caption flutuante
      TextField nome = new TextField().caption("Nome");
      add(LAY_AUTO, nome);

      // Label de saída
      Label saida = new Label("Digite seu nome e toque em Enviar");
      add(LAY_AUTO, saida);

      // Não há onChange por tecla: leia getText() no envio
      Button enviar = new Button("Enviar")
         .onAction(c -> saida.setText("Olá, " + 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

TextField nome = new TextField().caption("Nome");
container.add(LAY_AUTO, nome);
// ...
String valor = nome.getText();

Construtores

Construtor	Descrição
`TextField()`	vazio
`TextField(String text)`	com texto inicial (`null` = vazio)

`EditMode` (modo de edição)

`EditMode`	Teclado padrão	Observações
`NORMAL`	`DEFAULT`	texto comum; pode ter máscara customizada
`DATE`	`DATE`	abre `DatePicker`; máscara de data
`CURRENCY`	`CALCULATOR`	moeda/decimal, máscara da direita p/ esquerda
`NUMERIC`	`NUMERIC`	numérico (no desktop cai para `KEYPAD`)
`TIME`	`TIME`	abre `TimePicker`
`PASSWORD`	`DEFAULT`	exibe `passwordChar` no lugar dos caracteres

setMode(mode) ou setMode(mode, maskedEdit) definem o modo; maskedEdit=true ativa a auto-formatação por máscara.

Propriedades e personalização

Propriedade / método	Tipo	Padrão	O que faz
`text(String)` / `setText(String)`	`TextField` / `void`	—	define o texto (normaliza máscara/moeda; cursor ao fim)
`getText()`	`String`	—	texto exibido (com máscara, se ativa)
`getTextWithoutMask()`	`String`	—	valor “limpo” (só dígitos / decimal formatado)
`caption(String)`	`TextField` (fluente)	`null`	caption flutuante / placeholder
`setMode(EditMode[, boolean])`	`void`	`NORMAL`	modo de edição (+ máscara)
`keyboard(Keyboard)` / `setKeyboard(Keyboard)`	`TextField` / `void`	por `EditMode`	tipo de teclado
`leftIcon(Icon[, Action])` / `rightIcon(Icon[, Action])`	`TextField` (fluente)	`null`	ícones (com ação opcional)
`leftIconAction(Action)` / `rightIconAction(Action)`	`TextField` (fluente)	—	ação de ícone (separada)
`isPassword()`	`boolean`	—	está em modo senha?
`clearText()`	`void`	—	limpa texto, máscara e cache
estilo `.mask(String)`	`char[]`	—	máscara (`9`=dígito, resto literal): `"99/99/9999"`
estilo `.validChars(String)`	`String`	`null`	caracteres permitidos
estilo `.maxLength(int)`	`int`	`0` (ilimitado)	limite de caracteres
estilo `.passwordToggle(true)`	`boolean`	`false`	cria o ícone “olho” mostrar/ocultar
estilo `.floatingCaption(true)`	`boolean`	—	caption sobe ao focar/preencher
`getDefaultCurrencyMask(int)` (static)	`char[]`	—	máscara de moeda (separadores de `LocaleFormats`)

Callbacks e eventos

Callback	Quando dispara
`onAction(Action)` (herdado)	em `onTouchUp`, após abrir o teclado
`onFocus()` / `onBlur()` (herdados)	ganho / perda de foco
`leftIconAction` / `rightIconAction`	ao tocar (e soltar sobre) o ícone correspondente

Não há onChange dedicado — reaja via ação ou consulte getText()/getTextWithoutMask().

Estados

focused: estilo textFieldFocused(...), cursor piscando, teclado/picker abre no toque; caption sobe se floatingCaption.
password: com passwordToggle, o ícone direito alterna PASSWORD↔NORMAL (mostrar/ocultar), atualizando os estilos default e focused.
disabled / read-only: setEnabled(false) ou editable=false impedem edição.

Campo de senha com toggle mostrar/ocultar

TextField senha = new TextField().caption("Senha");
senha.setMode(EditMode.PASSWORD);
senha.style(Styles.theme()
   .field(FieldRole.PASSWORD, State.NORMAL)
   .passwordToggle(true));   // cria o ícone "olho" automaticamente
container.add(LAY_AUTO, senha);

Data com máscara + DatePicker

TextField data = new TextField().caption("Data");
data.setMode(EditMode.DATE, true);          // maskedEdit = true
data.style(Styles.theme()
   .field(FieldRole.NORMAL, State.NORMAL)
   .mask("99/99/9999"));
// Tocar abre o DatePicker; ao selecionar, o campo é preenchido.
container.add(LAY_AUTO, data);

CEP com validação e ícone de limpar

TextField cep = new TextField().caption("CEP");
cep.style(Styles.theme()
   .field(FieldRole.NORMAL, State.NORMAL)
   .mask("99999-999")
   .validChars("0123456789"));
cep.rightIcon(new MaterialIcon(""), c -> cep.clearText());  // "close"
container.add(LAY_AUTO, cep);

String limpo = cep.getTextWithoutMask();   // só os 8 dígitos

Boas práticas

Para máscara, ative maskedEdit (setMode(mode, true)) e defina a mask no estilo — só definir a máscara sem maskedEdit não auto-formata.
Use getTextWithoutMask() ao persistir/validar (dígitos limpos) e getText() ao exibir.
Prefira EditMode/Keyboard corretos para abrir o teclado ideal em cada campo.

Erros comuns

Definir mask mas esquecer maskedEdit: o texto não é formatado. Use setMode(mode, true).
Ler getText() esperando dígitos limpos: ele retorna com separadores; use getTextWithoutMask().
passwordToggle sem modo senha: o toggle já implica senha por padrão, mas confirme EditMode.PASSWORD / FieldRole.PASSWORD para o visual correto.

Veja também

Guia da área: ui/ · Receitas: cookbook/
Conceito (máscara/validação/foco — aprofundamento): concepts/
Componentes relacionados: TextInput · TextArea · Keypad