TextField

TextField is the single-line text input. On top of the TextInput base, it adds: a mask engine (date, currency, custom), password mode (with a show/hide toggle), clickable left/right icons, horizontal scrolling and an optional floating caption. The input behavior is defined by EditMode (NORMAL/DATE/CURRENCY/NUMERIC/TIME/PASSWORD), which also chooses the default keyboard.

🟡 · Package: dev.crossfly.ui · Extends: TextInput · Style: TextFieldStyle (distinct default and focused)

When to use

• Any single-line input: name, email, password, numeric/monetary values, date, time.
• Fields with a mask (ZIP code, phone, date) or with a clickable icon (clear, search, password eye).

When NOT to use

• Multi-line text (notes, comments) → use TextArea.
• Choice among fixed options → use Dropdown / Option (see ui/).

Appearance

Box with background/border from the TextFieldStyle, text on a single line, optional icons at the ends and, optionally, a floating caption (floatingCaption) that rises above the field when it has focus or content.

``

Complete example (copy, paste and run)

package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;

/** Runnable main screen. Point the launcher (classname) and run: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      // Single-line field with floating caption
      TextField nome = new TextField().caption("Nome");
      add(LAY_AUTO, nome);

      // Output label
      Label saida = new Label("Digite seu nome e toque em Enviar");
      add(LAY_AUTO, saida);

      // There is no onChange per key: read getText() on submit
      Button enviar = new Button("Enviar")
         .onAction(c -> saida.setText("Olá, " + nome.getText() + "!"));
      add(LAY_AUTO, enviar);
   }
}

The snippets below show only the core (what goes inside onShow()). To run them, place them in the MainWindow skeleton above.

Basic usage

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

Constructors

EditMode (edit mode)

setMode(mode) or setMode(mode, maskedEdit) set the mode; maskedEdit=true enables mask auto-formatting.

Properties and customization

Callbacks and events

There is no dedicated onChange — react via the action or query getText()/getTextWithoutMask().

States

• focused: textFieldFocused(...) style, blinking cursor, keyboard/picker opens on tap; caption rises if floatingCaption.
• password: with passwordToggle, the right icon toggles PASSWORD↔NORMAL (show/hide), updating the default and focused styles.
• disabled / read-only: setEnabled(false) or editable=false prevent editing.

Password field with a show/hide toggle

TextField senha = new TextField().caption("Senha");
senha.setMode(EditMode.PASSWORD);
senha.style(Styles.theme()
   .field(FieldRole.PASSWORD, State.NORMAL)
   .passwordToggle(true));   // creates the "eye" icon automatically
container.add(LAY_AUTO, senha);

Date with mask + 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"));
// Tapping opens the DatePicker; on selection, the field is filled.
container.add(LAY_AUTO, data);

ZIP code with validation and a clear icon

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();   // only the 8 digits

Best practices

• For a mask, enable maskedEdit (setMode(mode, true)) and set the mask in the style — setting the mask alone without maskedEdit does not auto-format.
• Use getTextWithoutMask() when persisting/validating (clean digits) and getText() when displaying.
• Prefer the correct EditMode/Keyboard to open the ideal keyboard for each field.

Common mistakes

• Setting a mask but forgetting maskedEdit: the text is not formatted. Use setMode(mode, true).
• Reading getText() expecting clean digits: it returns with separators; use getTextWithoutMask().
• passwordToggle without password mode: the toggle already implies password by default, but confirm EditMode.PASSWORD / FieldRole.PASSWORD for the correct look.

See also

• Area guide: ui/ · Recipes: cookbook/
• Concept (mask/validation/focus — in depth): concepts/
• Related components: TextInput · TextArea · Keypad