# Dialogs and modals

> Alert, ActionSheet and Hint — how to open them, get the response and configure appearance.

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

# Dialogs and modals

Dialogs are **popup windows** stacked on top of the current screen. In CrossFly the three main ones are
`Alert` (confirmation), `ActionSheet` (list of actions) and `Hint` (ephemeral notice, the old "Toast").

## ⚠️ `Alert`/`ActionSheet` respond through the BUTTONS, not through `onAnswer`
They extend `Window` (not `Picker`), so **`show(callback)` returns no value**. The user's
choice arrives through the **button callback** (`buttonAction`). (See [Returning values](/docs/ui/navigation/returning-results).)

## Complete example (copy, paste and run)
```java
package com.exemplo;

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

/** Runnable main screen. Point the launcher (classname) and run: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      // Alert — buttons in the constructor (0 = Cancel, 1 = Delete); action by index.
      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));   // Cancel (0) just closes
         // popup: sizes and dims the background via fluent WindowStyle
         a.getStyle().widthRatio(0.85f).fadeBackground(128).transition(UIConstants.Transition.FADE);
         a.show();
      });
      add(LAY_AUTO, excluir);

      // ActionSheet — 1st argument is the cancel text.
      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));   // index 0 = Email
         sheet.buttonAction(1, x -> Hint.show("Enviado por SMS", 2000));      // index 1 = Message
         sheet.show();
      });
      add(LAY_AUTO, compartilhar);

      // Hint — ephemeral notice (delay in ms).
      Button avisar = new Button("Mostrar aviso");
      avisar.onAction(c -> Hint.show("Salvo com sucesso", 2000));
      add(LAY_AUTO, avisar);
   }
}
```
> The snippets below show **only the core** (what goes inside `onShow()`). To run them, place them in the `MainWindow` skeleton above.

## Alert (confirm / notify)
The button texts go in the **constructor**; each button's action is wired by **index** with `buttonAction`:
```java
// buttons: index 0 = "Cancel", index 1 = "Delete"
Alert a = new Alert("Excluir", "Confirma a exclusão deste item?", "Cancelar", "Excluir");
a.buttonAction(1, c -> excluirItem());   // action comes from here, NOT from show(cb); Cancel just closes
a.show();
```

## ActionSheet (choose an action)
It also receives the texts in the constructor (the **first** argument is the cancel text):
```java
ActionSheet sheet = new ActionSheet("Cancelar", "E-mail", "Mensagem");
sheet.buttonAction(0, c -> enviarPorEmail());   // index 0 = "Email"
sheet.buttonAction(1, c -> enviarPorSMS());     // index 1 = "Message"
sheet.cancelAction(c -> {});                     // optional: action on cancel
sheet.show();
```

## Hint (ephemeral notice — replaces Toast/ToolTip)
```java
Hint.show("Salvo com sucesso", 2000);     // disappears on its own
```

## Configure popup appearance — `WindowStyle`
A popup is sized/positioned by the window's `WindowStyle`. Useful fields:

| Field | Effect |
|---|---|
| `widthRatio` / `heightRatio` | size as a fraction of the screen |
| `yRatio` / `xAbs` / `yAbs` | position |
| `fadeBackground` | darkens the background behind the popup |
| `canHide` | tapping outside closes the popup |
| `canMove` | user can drag it |
| `transition` / `transitionDuration` | entrance/exit animation (default `NONE`, `0.5s`) |

```java
getStyle().widthRatio = 0.85f;                       // 85% of the width
getStyle().fadeBackground = true;                     // dimmed background
getStyle().transition = UIConstants.Transition.FADE;  // appears with fade
```

## Best practices
- Clear button labels ("Delete" instead of "OK"); put the destructive action last.
- Prefer `Hint` over `Alert` for non-blocking confirmations.

## Common mistakes
- **`alert.show(cb)` expecting the `cb` to fire** — it doesn't; wire the action with `buttonAction(i, callback)`.
- Calling `addButton(...)`/`addOption(...)` — they don't exist; the texts go in the **constructor** and the actions by **index**.
- Stacking several popups on the same event.

## See also
- [Returning values](/docs/ui/navigation/returning-results) · [The window stack](/docs/ui/navigation/the-window-stack)
- Catalog: [Alert](/docs/ui/widgets/alert) · [ActionSheet](/docs/ui/widgets/actionsheet) · [Hint](/docs/ui/widgets/hint)