# Hint

> Notificación efímera no modal (sustituye a Toast/ToolTip).

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

# Hint

`Hint` es la notificación efímera **no modal** de CrossFly: aparece típicamente cerca de la base de la pantalla, muestra un mensaje corto y desaparece sola tras un tiempo (con fade). No bloquea la interacción con el resto de la UI. Es el sustituto modernizado del antiguo `Toast` — **misma API** — y también cubre el caso del antiguo `ToolTip` (ambos eliminados del framework).

`Hint` **no extiende `Window`**: es una clase utilitaria con API **estática** que crea internamente una `ToastWindow`.

> 🟢 · **Paquete:** `dev.crossfly.ui` · **Extiende:** — (utilitario estático) · **Config:** campos estáticos

## Cuándo usar
- Feedback pasivo y breve: "¡Guardado!", "Fallo al conectar", "Copiado".
- Estado transitorio que no exige acción del usuario.

## Cuándo NO usar
- Algo que exige decisión/confirmación → usa [`Alert`](/docs/ui/widgets/alert) o [`ActionSheet`](/docs/ui/widgets/actionsheet).

## Apariencia
Cápsula redondeada oscura (por defecto `0xFF303030`, texto blanco) centrada horizontalmente, posicionada a ~85% de la altura de la pantalla. Aparece y desaparece con fade suave.

## 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 titulo = new Label("Toque para ver um Hint");
      add(LAY_AUTO, titulo);

      // Hint es estático: un Button dispara la notificación efímera en onAction
      Button salvar = new Button("Salvar")
         .onAction(c -> Hint.show("Salvo com sucesso!", 2000));
      add(LAY_AUTO, salvar);

      Button falhar = new Button("Simular erro")
         .onAction(c -> Hint.show("Falha ao conectar", 2500));
      add(LAY_AUTO, falhar);
   }
}
```

> 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
// Mensaje visible por 2 segundos, luego desaparece solo
Hint.show("Salvo com sucesso!", 2000);
```

## API de visualización (estática)
| Sobrecarga | Descripción |
|---|---|
| `Hint.show(String message, int delay)` | Posición/padding por defecto. |
| `Hint.show(String message, int delay, Window parentWindow)` | Define la ventana padre. |
| `Hint.show(String message, int delay, Window parentWindow, Relative at, Gap innerGap)` | Forma completa: posición vertical (`at`) y padding interno (`innerGap`). |

Las dos primeras delegan en la tercera con `null` en los campos ausentes.

| Parámetro | Tipo | Significado |
|---|---|---|
| `message` | `String` | Texto. **`null` oculta** el hint actual. |
| `delay` | `int` | Milisegundos visible. `INFINITE`/`INFINITE_NOANIM` lo mantienen en pantalla. |
| `parentWindow` | `Window` | Padre opcional; por defecto = ventana superior. |
| `at` | `Relative` | `START`(arriba) / `CENTER` / `END`(base) o valor relativo. `null` usa `position`. |
| `innerGap` | `Gap` | Padding interno. `null` usa `ingap` estático. |

## Configuración global (campos estáticos)
Toda la apariencia se controla mediante estáticos compartidos — **alterarlos afecta a todos los hints siguientes**.

| Campo | Tipo | Por defecto | Qué hace |
|---|---|---|---|
| `Hint.backColor` | `int` | `0xFF303030` | Color de fondo. |
| `Hint.foreColor` | `int` | `WHITE` | Color del texto. |
| `Hint.position` | `Relative` | `Relative.ofScreen(0.85f)` | Posición vertical por defecto. |
| `Hint.ingap` | `Gap` | `Gap.ofFont(0.7f, 0.35f, 0.7f, 0.35f)` | Padding interno por defecto. |
| `Hint.font` | `Font` | `Font.get().bold()` | Fuente del texto. |
| `Hint.fade` | `int` | `200` | Objetivo de alpha en el modo animado. |
| `Hint.INFINITE` | `int` | `Integer.MAX_VALUE` | Duración infinita **con** animación. |
| `Hint.INFINITE_NOANIM` | `int` | `Integer.MIN_VALUE` | Duración infinita **sin** animación. |

## Estados
- Auto-dismiss por tiempo cuando `delay` es finito.
- Persistente con `INFINITE`/`INFINITE_NOANIM` — debe cerrarse manualmente con `Hint.show(null, 0)`.
- Los hints **no se apilan**: uno nuevo sustituye al actual.

### Error arriba, en rojo, restaurando el estático
```java
Hint.backColor = 0xFFB00020;
Hint.show("Falha ao salvar", 2500, null, Relative.START, null);
Hint.backColor = 0xFF303030; // restaura el default para los próximos hints
```

### Hint persistente y eliminación manual
```java
Hint.show("Conectando...", Hint.INFINITE);
// ... cuando termine:
Hint.show(null, 0); // message == null oculta el hint actual
```

### Padding personalizado vía Gap
```java
Hint.show("Detalhes copiados", 1800, null, Relative.CENTER, Gap.ofFont(1f, 0.5f, 1f, 0.5f));
```

## Buenas prácticas
- Úsalo para feedback pasivo y breve; nunca para decisiones.
- Prefiere pasar `at`/`innerGap` en la llamada a mutar los estáticos, para ajustes puntuales.
- Al mutar un estático globalmente (ej.: `backColor`), **restáuralo** después para no filtrar estado.

## Errores comunes
- **`INFINITE` sin cerrar** — queda en pantalla para siempre; ciérralo con `Hint.show(null, ...)`.
- **Sin ventana en el tope** (pila vacía) — el hint simplemente no aparece.
- **Esperar que los hints se acumulen** — no; el nuevo sustituye al anterior.

## Migración (Toast/ToolTip eliminados)
`Toast.show(...)` migra 1:1 a `Hint.show(...)` (mismas firmas y estáticos). `ToolTip` no tiene sustituto directo (ya no hay press-and-hold) — usa `Hint` posicionado con `at`/`position` si necesitas una pista efímera.

## Ver también
- Guía del área: [`ui/`](/docs/ui) · Recetas: [`cookbook/`](/docs/cookbook)
- Componentes relacionados: [`Alert`](/docs/ui/widgets/alert) · [`ActionSheet`](/docs/ui/widgets/actionsheet)