TextInput

TextInput es la clase abstracta que concentra toda la lógica de edición compartida entre TextField (una línea) y TextArea (multilínea): cursor, selección, clipboard, foco/blink, atajos de teclado, navegación por flechas, long-touch con ActionSheet e integración con el teclado virtual. Las subclases implementan el mapeo espacial (1D vs 2D), desplazamiento, renderizado y máscaras.

No instancias TextInput directamente — instancias TextField o TextArea. Esta página es la visión general de lo que ambos heredan. Implementa UIConstants.TextInputComponent (setText/getText/isPassword/replaceText/keyboardHidden/getCursorPos/hasFocus).

🟡 · Paquete: dev.crossfly.ui · Extiende: Component · Implementa: UIConstants.TextInputComponent · Abstracta

Cuándo usar

Como tipo común al referenciar cualquier campo de entrada (TextInput campo = new TextField(...)).
Al escribir código que opera sobre cursor/selección/clipboard sin importar si es 1 o N líneas.

Cuándo NO usar

Para instanciar un campo concreto → usa TextField (1 línea) o TextArea (multilínea).

Jerarquía

Component → TextInput (abstracta) → TextField / TextArea. El constructor recibe la capacidad inicial del buffer: TextInput(int initialCapacity). Es isPressable() → true.

Estado interno (campos clave)

Campo	Tipo	Significado
`chars`	`StringBuffer`	buffer en bruto del texto
`text`	`String`	texto mostrado (actualizado por la subclase; inicia `""`)
`insertPos`	`int`	posición del cursor (inserción)
`startSelectPos`	`int`	inicio de la selección, o `-1` si no hay selección
`cursorShowing`	`boolean`	fase visible del blink del cursor
`keyboardCanOpen`	`boolean`	el teclado puede abrir en el próximo touch-up
`hasFocus`	`boolean`	tiene foco de teclado
`caption`	`String`	placeholder / caption flotante

Métodos heredados (cursor, selección, clipboard)

Método	Retorno	Qué hace
`setText(String)`	`void`*	define el texto (implementado por la subclase)
`getText()`	`String`	texto actual (con máscara en `TextField`)
`setCursorPos(int start, int end)`	`void`	define selección; si `start==end`, solo mueve el cursor
`setCursorPos(int pos)`	`void`	cursor sin selección
`getCursorPos()`	`int[]`	`[startSelectPos, insertPos]`
`getInsertPos()`	`int`	posición del cursor
`hasSelection()`	`boolean`	¿hay un intervalo seleccionado?
`getSelectionStart()` / `getSelectionEnd()`	`int`	min / max de las posiciones
`getTextBuffer()` / `getLength()`	`StringBuffer` / `int`	buffer en bruto / tamaño
`clipboardCopy()` / `clipboardCut()`	`void`	copia / corta la selección (vía `Device.clipboard*`)
`clipboardPaste()` / `clearText()`	`void`	abstractos — la subclase maneja máscara/`\n`
`mapKeys(String from, String to)`	`void`	remapeo carácter a carácter (lanza `IllegalArgumentException` si los tamaños difieren; `null`/`null` limpia)
`hasFocus()`	`boolean`	tiene foco de teclado
`restoreFocusAtEnd()`	`void`	reasigna foco y mueve el cursor al final (tras cerrar picker/keypad)

*setText retorna void en el contrato TextComponent; TextField.text(...)/TextArea.text(...) ofrecen variantes fluidas que retornan el propio campo.

Callbacks y eventos

Callback	Cuándo se dispara
`onAction(Action)` (heredado)	en `onTouchUp` (tras abrir el teclado)
`onFocus()` / `onBlur()`	ganancia / pérdida de foco (activa/desactiva cursor y blink)

No existe un onChange dedicado: para reaccionar a cambios, observa vía callback de acción o consulta getText().

Estados

focused: cursor activado y parpadeando (cursorShowing), el teclado/Keypad abre al toque; onFocus()/onBlur() controlan la transición.
selection: intervalo [startSelectPos, insertPos]; long-touch selecciona todo y abre el ActionSheet (Copy/Cut/Paste/Clear).
disabled / read-only: setEnabled(false) o editable=false en el estilo impiden la edición.

Teclas (heredadas de `onKeyDown`)

Ctrl+C / V / X → copiar / pegar / cortar; Ctrl+A → seleccionar todo.
Backspace / Delete → borra la selección o un carácter.
Left / Right / Home / End → mueve el cursor; con Shift extiende la selección.

Ejemplo completo (copiar, pegar y ejecutar)

package com.exemplo;

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

/** Pantalla principal ejecutable. Apunta el launcher (classname) y corre: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      // Referencia polimórfica: TextInput es la base abstracta de TextField/TextArea
      TextInput campo = new TextField("valor inicial");
      add(LAY_AUTO, (Component) campo);

      // Label de salida
      Label saida = new Label("Leia o campo com o botão");
      add(LAY_AUTO, saida);

      // No hay evento por tecla: lee getText() al enviar
      Button enviar = new Button("Enviar")
         .onAction(c -> saida.setText("Você digitou: " + campo.getText()));
      add(LAY_AUTO, enviar);
   }
}

Los fragmentos de abajo muestran solo el núcleo (lo que va dentro de onShow()). Para ejecutarlos, colócalos en el esqueleto MainWindow de arriba.

Ejemplo (usar el tipo base)

// Referencia polimórfica al campo concreto
TextInput campo = new TextField("valor inicial");
container.add(LAY_AUTO, (Component) campo);

// Operaciones comunes vía la base
if (campo.hasSelection())
   campo.clipboardCopy();
int[] sel = campo.getCursorPos();     // [start, insert]
campo.setCursorPos(campo.getLength()); // cursor al final

Buenas prácticas

Programa contra TextInput/UIConstants.TextInputComponent cuando el código no dependa del formato (1 vs N líneas).
Tras cerrar un picker/Keypad, llama a restoreFocusAtEnd() para devolver el foco correctamente.

Errores comunes

Intentar instanciar TextInput: es abstracta — usa TextField/TextArea.
Esperar que clipboardPaste()/clearText() funcionen en la base: son abstractos; el comportamiento viene de la subclase (máscara en TextField, \n en TextArea).

Véase también

Guía del área: ui/ · Recetas: cookbook/
Concepto (foco, eventos de entrada): concepts/
Componentes relacionados: TextField · TextArea · Keypad