# Hint

> Notificação efêmera não-modal (substitui Toast/ToolTip).

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

# Hint

`Hint` é a notificação efêmera **não-modal** do CrossFly: aparece tipicamente perto da base da tela, mostra uma mensagem curta e some sozinha após um tempo (com fade). Não bloqueia a interação com o resto da UI. É o substituto modernizado do antigo `Toast` — **mesma API** — e também cobre o caso do antigo `ToolTip` (ambos removidos do framework).

`Hint` **não estende `Window`**: é uma classe utilitária com API **estática** que cria internamente uma `ToastWindow`.

> 🟢 · **Pacote:** `dev.crossfly.ui` · **Estende:** — (utilitário estático) · **Config:** campos estáticos

## Quando usar
- Feedback passivo e breve: "Salvo!", "Falha ao conectar", "Copiado".
- Status transitório que não exige ação do usuário.

## Quando NÃO usar
- Algo que exige decisão/confirmação → use [`Alert`](/docs/ui/widgets/alert) ou [`ActionSheet`](/docs/ui/widgets/actionsheet).

## Aparência
Cápsula arredondada escura (default `0xFF303030`, texto branco) centralizada horizontalmente, posicionada a ~85% da altura da tela. Surge e some com fade suave.

## Exemplo completo (copiar, colar e rodar)
```java
package com.exemplo;

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

/** Tela principal executável. Aponte o launcher (classname) e rode: 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 é estático: um Button dispara a notificação efêmera no 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);
   }
}
```

> Os trechos abaixo mostram **só o miolo** (o que vai dentro de `onShow()`). Para rodar, coloque-os no esqueleto `MainWindow` acima.

## Uso básico
```java
// Mensagem visível por 2 segundos, depois some sozinha
Hint.show("Salvo com sucesso!", 2000);
```

## API de exibição (estática)
| Sobrecarga | Descrição |
|---|---|
| `Hint.show(String message, int delay)` | Posição/padding default. |
| `Hint.show(String message, int delay, Window parentWindow)` | Define a janela-pai. |
| `Hint.show(String message, int delay, Window parentWindow, Relative at, Gap innerGap)` | Forma completa: posição vertical (`at`) e padding interno (`innerGap`). |

As duas primeiras delegam à terceira com `null` nos campos ausentes.

| Parâmetro | Tipo | Significado |
|---|---|---|
| `message` | `String` | Texto. **`null` oculta** o hint atual. |
| `delay` | `int` | Milissegundos visível. `INFINITE`/`INFINITE_NOANIM` mantêm na tela. |
| `parentWindow` | `Window` | Pai opcional; default = janela do topo. |
| `at` | `Relative` | `START`(topo) / `CENTER` / `END`(base) ou valor relativo. `null` usa `position`. |
| `innerGap` | `Gap` | Padding interno. `null` usa `ingap` estático. |

## Configuração global (campos estáticos)
Toda a aparência é controlada por estáticos compartilhados — **alterá-los afeta todos os hints seguintes**.

| Campo | Tipo | Default | O que faz |
|---|---|---|---|
| `Hint.backColor` | `int` | `0xFF303030` | Cor de fundo. |
| `Hint.foreColor` | `int` | `WHITE` | Cor do texto. |
| `Hint.position` | `Relative` | `Relative.ofScreen(0.85f)` | Posição vertical default. |
| `Hint.ingap` | `Gap` | `Gap.ofFont(0.7f, 0.35f, 0.7f, 0.35f)` | Padding interno default. |
| `Hint.font` | `Font` | `Font.get().bold()` | Fonte do texto. |
| `Hint.fade` | `int` | `200` | Alvo de alpha no modo animado. |
| `Hint.INFINITE` | `int` | `Integer.MAX_VALUE` | Duração infinita **com** animação. |
| `Hint.INFINITE_NOANIM` | `int` | `Integer.MIN_VALUE` | Duração infinita **sem** animação. |

## Estados
- Auto-dismiss por tempo quando `delay` é finito.
- Persistente com `INFINITE`/`INFINITE_NOANIM` — precisa ser fechado manualmente com `Hint.show(null, 0)`.
- Hints **não empilham**: um novo substitui o atual.

### Erro no topo, em vermelho, restaurando o estático
```java
Hint.backColor = 0xFFB00020;
Hint.show("Falha ao salvar", 2500, null, Relative.START, null);
Hint.backColor = 0xFF303030; // restaura o default para os próximos hints
```

### Hint persistente e remoção manual
```java
Hint.show("Conectando...", Hint.INFINITE);
// ... quando terminar:
Hint.show(null, 0); // message == null oculta o hint atual
```

### Padding customizado via Gap
```java
Hint.show("Detalhes copiados", 1800, null, Relative.CENTER, Gap.ofFont(1f, 0.5f, 1f, 0.5f));
```

## Boas práticas
- Use para feedback passivo e breve; nunca para decisões.
- Prefira passar `at`/`innerGap` na chamada a mutar os estáticos, para ajustes pontuais.
- Ao mutar um estático globalmente (ex.: `backColor`), **restaure** depois para não vazar estado.

## Erros comuns
- **`INFINITE` sem fechar** — fica na tela para sempre; feche com `Hint.show(null, ...)`.
- **Sem janela no topo** (pilha vazia) — o hint simplesmente não aparece.
- **Esperar que hints se acumulem** — não; o novo substitui o anterior.

## Migração (Toast/ToolTip removidos)
`Toast.show(...)` migra 1:1 para `Hint.show(...)` (mesmas assinaturas e estáticos). `ToolTip` não tem substituto direto (não há mais press-and-hold) — use `Hint` posicionado com `at`/`position` se precisar de dica efêmera.

## Veja também
- Guia da área: [`ui/`](/docs/ui) · Receitas: [`cookbook/`](/docs/cookbook)
- Componentes relacionados: [`Alert`](/docs/ui/widgets/alert) · [`ActionSheet`](/docs/ui/widgets/actionsheet)