# Label

> Componente no interactivo para mostrar texto (con word-wrap) y/o iconos de solo lectura.

Source: https://crossfly.dev/es/docs/ui/widgets/label — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# Label

`Label` es el widget de **visualización** más usado: muestra texto de solo lectura, con salto de línea automático (word-wrap), múltiples líneas (explícitas vía `\n` o automáticas) e iconos opcionales a la izquierda y/o a la derecha. No reacciona al toque — para acciones usa [`Button`](/docs/ui/widgets/button); para texto editable usa [`TextField`](/docs/ui/widgets/textfield)/[`TextArea`](/docs/ui/widgets/textarea).

El renderizado se delega al `Design` activo: el `Label` solo calcula coordenadas en `onLayout()` y expone campos públicos que el `Design` consume (fuente, colores y bordes vienen del `LabelStyle`).

> 🟢 · **Paquete:** `dev.crossfly.ui` · **Extiende:** `Component` · **Estilo:** `LabelStyle`

## Cuándo usar
- Títulos, subtítulos, leyendas y valores de solo lectura.
- Texto con icono informativo a la izquierda o a la derecha.
- Bloques de texto que necesitan quebrar en varias líneas.

## Cuándo NO usar
- Texto editable → usa [`TextField`](/docs/ui/widgets/textfield) / [`TextArea`](/docs/ui/widgets/textarea).
- Elemento tocable / clicable → usa [`Button`](/docs/ui/widgets/button) (el `Label` no responde al toque).

## Apariencia
El texto se renderiza dentro del área interna (tras `ingap`), alineado horizontal y verticalmente según `LabelStyle.textAlignH`/`textAlignV`. El icono izquierdo queda pegado al borde interno izquierdo; el derecho al borde interno derecho; el texto ocupa el espacio entre ellos.

``

## Ejemplo completo (copiar, pegar y ejecutar)
```java
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());

      // Label de solo lectura que será actualizado por el botón
      Label saida = new Label("Toque no botão abaixo");
      add(LAY_AUTO, saida);

      // Botón que muta el texto del Label (Label.setText es fluido y devuelve Label)
      Button ola = new Button("Dizer olá").onAction(c -> saida.setText("Olá, mundo!"));
      add(LAY_AUTO, ola);
   }
}
```

> Los fragmentos siguientes muestran **solo el núcleo** (lo que va dentro de `onShow()`). Para ejecutar, colócalos en el esqueleto `MainWindow` de arriba.

## Uso básico
```java
Label hello = new Label("Olá, mundo!");
container.add(LAY_AUTO, hello);
```

## Constructores
| Constructor | Descripción |
|---|---|
| `Label()` | label vacío (`text = ""`) |
| `Label(String text)` | label de texto |
| `Label(Icon onlIcon)` | label solo-icono (icono a la izquierda) |

## Propiedades y personalización
| Propiedad / método | Tipo | Por defecto | Qué hace |
|---|---|---|---|
| `setText(String)` | `Label` (fluido) | — | cambia el texto; invalida el layout **solo si** el valor cambió |
| `leftIcon(Icon)` | `Label` (fluido) | `null` | define el icono a la izquierda del texto |
| `rightIcon(Icon)` | `Label` (fluido) | `null` | define el icono a la derecha del texto |
| `text` | `String` (campo público) | `""` | contenido actual (puede contener `\n`) |
| estilo `.textAlign(Position, Position)` | `Position` | tema | alineación horizontal/vertical del texto |
| estilo `.backColor(int)` / `.borderColor(int)` | ARGB | tema | fondo/borde (usa `0` para transparente) |
| `getAutoWidth()` / `getAutoHeight(int)` | `int` | — | tamaños preferidos (usados por el layout) |
| `Label.wordWrap(String, Font, int)` *(static)* | `String[]` | — | utilitario de salto de línea por anchura |

> `setText(String)` devuelve `Label` (para fluidez), **no** `void` — por eso el `Label` no declara `implements TextComponent`, a pesar de exponer `setText`/`text`.

## Callbacks y eventos
Ninguno. `Label` no es interactivo — no dispara `onAction` ni eventos de toque.

## Estados
Sin estados de interacción (no hay `pressed`/`focused`). El visual cambia solo con el estilo aplicado o vía `setEnabled(false)` (apariencia deshabilitada, según el `Design`).

### Icono a la izquierda y subtítulo sin fondo
```java
// Label con ícono a la izquierda (Material "info")
Label info = new Label("Informação")
   .leftIcon(new MaterialIcon(""));
container.add(LAY_AUTO, info);

// Subtítulo alineado a la izquierda, sin fondo/borde
Label sub = new Label("Lista:").style(
   Styles.theme().label(LabelRole.SUBTITLE)
      .backColor(0)
      .borderColor(0)
      .textAlign(Position.START, Position.CENTER));
container.add(LAY_AUTO, sub);
```

### Multilínea (word-wrap + `\n` explícito)
```java
// Saltos explícitos
Label endereco = new Label("Rua das Flores, 123\nCentro\n01000-000");

// Word-wrap automático: dé ancho al Label (LAY_FILL) para que ocurra el salto
Label paragrafo = new Label(
   "Este texto longo quebra automaticamente em várias linhas quando "
 + "a largura disponível é menor que a largura do texto.");
container.add(LAY_FILL, paragrafo);
```

## Buenas prácticas
- Para word-wrap, garantiza que el layout dé **anchura** al `Label` (ej.: `add(LAY_FILL, label)` en un `VerticalLayout`). Sin anchura conocida, solo los `\n` explícitos se cuentan en la altura.
- Usa roles del tema (`LabelRole.TITLE`/`SUBTITLE`/…) en vez de hard-codear fuente/color.

## Errores comunes
- **Esperar word-wrap sin anchura definida:** si la anchura es `0`/desconocida en el cálculo de altura, solo los saltos `\n` explícitos cuentan. Dale anchura al `Label`.
- **Confundir `setText` con el contrato `TextComponent.setText`:** aquí `setText` devuelve `Label`, no `void`; el `Label` no implementa `TextComponent`.

## Ver también
- Guía del área: [`ui/`](/docs/ui) · Recetas: [`cookbook/`](/docs/cookbook)
- Concepto ("todo es `Component`"): [`concepts/`](/docs/concepts)
- Componentes relacionados: [`Button`](/docs/ui/widgets/button) · [`TextField`](/docs/ui/widgets/textfield) · [`ImageView`](/docs/ui/widgets/imageview)