TextArea

TextArea es la entrada de texto de múltiples líneas. Sobre la base TextInput, añade: word-wrap, estructura de líneas, desplazamiento vertical, mapeo de coordenadas 2D y layout multilínea. Soporta íconos a la derecha (uno por línea visible) y un modo read-only desplazable (para mostrar texto largo que el usuario solo recorre).

A diferencia de TextField, el TextArea no tiene máscara ni modo contraseña; ENTER inserta salto de línea y getText() preserva los \n.

🟡 · Paquete: dev.crossfly.ui · Extiende: TextInput · Estilo: TextAreaStyle

Cuándo usar

Observaciones, comentarios, descripciones, direcciones — cualquier texto de varias líneas.
Mostrar un bloque largo desplazable (con editable=false).

Cuándo NO usar

Entrada de una línea (nombre, e-mail, valor) → usa TextField.
Máscara / modo contraseña → usa TextField (el TextArea no los soporta).

Apariencia

Rectángulo con fondo/borde del TextAreaStyle, texto dividido en líneas (word-wrap en el ancho interno), con desplazamiento vertical cuando el contenido excede la altura. La altura preferida viene de rowCount (número de líneas visibles) × altura de línea + ingap. Los íconos a la derecha, cuando se definen, ocupan una columna propia, uno por línea visible.

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

      // Campo multilínea; LAY_FILL da altura al área desplazable
      TextArea obs = new TextArea().caption("Observações");
      add(LAY_FILL, obs);

      // Label de salida
      Label saida = new Label("Escreva algo e toque em Enviar");
      add(LAY_AUTO, saida);

      // No hay onChange por tecla: lee getText() al enviar (preserva los \n)
      Button enviar = new Button("Enviar")
         .onAction(c -> saida.setText("Você escreveu " + obs.getText().length() + " caracteres"));
      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.

Uso básico

TextArea obs = new TextArea().caption("Observações");
container.add(0.4f, obs);
// ...
String texto = obs.getText();   // preserva los \n

Constructores

Constructor	Descripción
`TextArea()`	vacío
`TextArea(String text)`	con texto inicial (`\r\n`/`\r` normalizados a `\n`)

Propiedades y personalización

Propiedad / método	Tipo	Por defecto	Qué hace
`text(String)` / `setText(String)`	`TextArea` / `void`	—	define el texto (normaliza saltos; cursor al inicio)
`getText()`	`String`	—	texto en bruto, preservando `\n`
`caption(String)`	`TextArea` (fluido)	`null`	placeholder
`rightIcons(Icon...)`	`TextArea` (fluido)	—	íconos a la derecha, uno por línea visible
`rightIconAction(int row, Action)`	`TextArea` (fluido)	—	acción del ícono de la línea `row` (0-based)
`clearText()`	`void`	—	limpia todo el texto
`getNumberOfTextLines()`	`int`	—	total de líneas lógicas (word-wrapped)
`scrollToTop()` / `scrollToBottom()` / `scrollToLine(int)`	`void`	—	desplazamiento programático
estilo `.rowCount(int)`	`int`	—	nº de líneas visibles (define la altura preferida)
estilo `.maxLength(int)`	`int`	`0` (ilimitado)	límite de caracteres
estilo `.validChars(String)`	`String`	`null`	caracteres permitidos (`\n` siempre aceptado)
estilo `.editable(false)`	`boolean`	`true`	read-only desplazable
estilo `.spaceBetweenLines(int)`	`int`	—	espacio extra entre líneas

Callbacks y eventos

Callback	Cuándo se dispara
`onAction(Action)` (heredado)	en `onTouchUp`, tras abrir el teclado
`onFocus()` / `onBlur()` (heredados)	ganancia / pérdida de foco
`rightIconAction(row, Action)`	al tocar (y soltar sobre) el ícono de esa línea

Estados

focused: cursor parpadeando, el teclado abre al toque; las flechas ↑/↓ navegan entre líneas.
selection: selección 2D por arrastre; long-touch selecciona todo y abre el ActionSheet.
read-only (editable=false): sin cursor/edición; el arrastre desplaza el contenido; la rueda del ratón también desplaza.

Campo de observaciones con límite

TextArea obs = new TextArea().caption("Observações");
obs.style(Styles.theme()
   .textArea(State.NORMAL)
   .rowCount(4)
   .maxLength(500));
container.add(LAY_AUTO, obs);

Bloque de texto solo-lectura, desplazable

TextArea termos = new TextArea(textoDosTermos);
termos.style(Styles.theme()
   .textArea(State.NORMAL)
   .editable(false)      // solo desplazar, sin editar
   .rowCount(8));
container.add(LAY_FILL, termos);
termos.scrollToTop();

Líneas con ícono de acción a la derecha

TextArea lista = new TextArea("Item A\nItem B\nItem C");
lista.rightIcons(
   new MaterialIcon(""),   // "delete" en la línea 0
   new MaterialIcon(""),
   new MaterialIcon(""));
lista.rightIconAction(0, c -> removerLinha(0));
container.add(0.3f, lista);

Buenas prácticas

Define rowCount en el estilo para controlar la altura visible; combínalo con LAY_AUTO en el layout.
Para mostrar texto largo sin edición, usa editable(false) — el arrastre pasa a desplazar en vez de seleccionar.
Usa getText() para persistir (preserva \n); la normalización de \r\n ya se hace en la entrada.

Errores comunes

Esperar máscara o modo contraseña: el TextArea no los soporta — usa TextField.
Definir demasiados rightIcons: solo se dibujan hasta visibleRows (nº de líneas visibles); los íconos más allá de eso se ignoran.

Véase también

Guía del área: ui/ · Recetas: cookbook/
Concepto (foco, selección, scroll): concepts/
Componentes relacionados: TextInput · TextField · Keypad