# Diálogos e modais

> Alert, ActionSheet e Hint — como abrir, obter a resposta e configurar aparência.

Source: https://crossfly.dev/pt/docs/ui/navigation/dialogs-and-modals — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# Diálogos e modais

Diálogos são **janelas popup** empilhadas sobre a tela atual. No CrossFly os três principais são
`Alert` (confirmação), `ActionSheet` (lista de ações) e `Hint` (aviso efêmero, o antigo "Toast").

## ⚠️ `Alert`/`ActionSheet` respondem pelos BOTÕES, não por `onAnswer`
Eles estendem `Window` (não `Picker`), então **`show(callback)` não retorna valor**. A escolha do
usuário chega pelo **callback do botão** (`buttonAction`). (Ver [Retornar valores](/docs/ui/navigation/returning-results).)

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

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

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

      // Alert — botões no construtor (0 = Cancelar, 1 = Excluir); ação por índice.
      Button excluir = new Button("Excluir item");
      excluir.onAction(c -> {
         Alert a = new Alert("Excluir", "Confirma a exclusão deste item?", "Cancelar", "Excluir");
         a.buttonAction(1, x -> Hint.show("Item excluído", 2000));   // Cancelar (0) só fecha
         // popup: dimensiona e escurece o fundo via WindowStyle fluente
         a.getStyle().widthRatio(0.85f).fadeBackground(128).transition(UIConstants.Transition.FADE);
         a.show();
      });
      add(LAY_AUTO, excluir);

      // ActionSheet — 1º argumento é o texto de cancelar.
      Button compartilhar = new Button("Compartilhar");
      compartilhar.onAction(c -> {
         ActionSheet sheet = new ActionSheet("Cancelar", "E-mail", "Mensagem");
         sheet.buttonAction(0, x -> Hint.show("Enviado por e-mail", 2000));   // índice 0 = E-mail
         sheet.buttonAction(1, x -> Hint.show("Enviado por SMS", 2000));      // índice 1 = Mensagem
         sheet.show();
      });
      add(LAY_AUTO, compartilhar);

      // Hint — aviso efêmero (delay em ms).
      Button avisar = new Button("Mostrar aviso");
      avisar.onAction(c -> Hint.show("Salvo com sucesso", 2000));
      add(LAY_AUTO, avisar);
   }
}
```
> Os trechos abaixo mostram **só o miolo** (o que vai dentro de `onShow()`). Para rodar, coloque-os no esqueleto `MainWindow` acima.

## Alert (confirmar / avisar)
Os textos dos botões vão no **construtor**; a ação de cada um é ligada por **índice** com `buttonAction`:
```java
// botões: índice 0 = "Cancelar", índice 1 = "Excluir"
Alert a = new Alert("Excluir", "Confirma a exclusão deste item?", "Cancelar", "Excluir");
a.buttonAction(1, c -> excluirItem());   // ação vem daqui, NÃO de show(cb); Cancelar só fecha
a.show();
```

## ActionSheet (escolher uma ação)
Também recebe os textos no construtor (o **primeiro** argumento é o texto de cancelar):
```java
ActionSheet sheet = new ActionSheet("Cancelar", "E-mail", "Mensagem");
sheet.buttonAction(0, c -> enviarPorEmail());   // índice 0 = "E-mail"
sheet.buttonAction(1, c -> enviarPorSMS());     // índice 1 = "Mensagem"
sheet.cancelAction(c -> {});                     // opcional: ação ao cancelar
sheet.show();
```

## Hint (aviso efêmero — substitui Toast/ToolTip)
```java
Hint.show("Salvo com sucesso", 2000);     // some sozinho
```

## Configurar aparência do popup — `WindowStyle`
Um popup é dimensionado/posicionado pelo `WindowStyle` da janela. Campos úteis:

| Campo | Efeito |
|---|---|
| `widthRatio` / `heightRatio` | tamanho como fração da tela |
| `yRatio` / `xAbs` / `yAbs` | posição |
| `fadeBackground` | escurece o fundo atrás do popup |
| `canHide` | tocar fora fecha o popup |
| `canMove` | usuário pode arrastar |
| `transition` / `transitionDuration` | animação de entrada/saída (padrão `NONE`, `0.5s`) |

```java
getStyle().widthRatio = 0.85f;                       // 85% da largura
getStyle().fadeBackground = true;                     // fundo escurecido
getStyle().transition = UIConstants.Transition.FADE;  // aparece com fade
```

## Boas práticas
- Rótulos de botão claros ("Excluir" em vez de "OK"); ação destrutiva por último.
- Prefira `Hint` a `Alert` para confirmações não bloqueantes.

## Erros comuns
- **`alert.show(cb)` esperando o `cb` disparar** — não dispara; ligue a ação com `buttonAction(i, callback)`.
- Chamar `addButton(...)`/`addOption(...)` — não existem; os textos vão no **construtor** e as ações por **índice**.
- Empilhar vários popups sobre o mesmo evento.

## Veja também
- [Retornar valores](/docs/ui/navigation/returning-results) · [A pilha de janelas](/docs/ui/navigation/the-window-stack)
- Catálogo: [Alert](/docs/ui/widgets/alert) · [ActionSheet](/docs/ui/widgets/actionsheet) · [Hint](/docs/ui/widgets/hint)