# Overlays

Dialogs, popovers, menus, tooltips and toasts draw over the page. Dialogs, popovers and menus take focus while open and hand it back when they close; tooltips and toasts leave focus alone.

## Drawing over the page

`primitives::raise(id, child)` draws `child` over the page. At the top of the tree it draws after everything else. Inside something raised, it lays out on its own and draws last there, so a list opened in a dialog lies over the dialog. Ely's overlays raise themselves; an app calls `raise` only for an overlay of its own.

## Dialogs

`Dialog::new(id, title, on_close)` is a card over a scrim. Render it while it is open, and set the open flag false in `on_close`.

| Call | Does |
| --- | --- |
| `.detail(text)` | A line under the title. |
| `.child(..)` | The owner's content. |
| `.action(\|close\| ..)` | A button in the row at the bottom, in the order given. The closure gets the dialog's close; a button that ends the dialog calls it. |
| `.fullscreen()` | Fills the window below its title bar, under a bar with the title and a close button. |

Escape, a press on the scrim and a fullscreen dialog's close button all run `on_close`. Tab stays inside the dialog, and focus returns to what held it before, on every way out. The card fits the window; its body scrolls and its actions stay. `AlertDialog`, `ConfirmDialog` and `PromptDialog` build on `Dialog`.

## Popovers

`Popover::new(id, label, content)` is a button that opens a panel under it, or over it when only above has room. A press outside or Escape closes it, and Tab stays inside. `content` runs only while the panel is open. `Popover::with_opener` opens the panel from an element of the app's own.

## Toasts

A window keeps one `Toaster`, an entity, and renders one `ToastViewport::new(id, &toaster)`. Anything that holds the entity pushes to it.

| Call | Does |
| --- | --- |
| `toaster.push(toast, cx)` | Shows the toast and returns its id. Past four toasts, the oldest leaves. |
| `toaster.dismiss(id, cx)` | Sends a toast away early. |
| `Toast::new(title)` | Stays 5 seconds. |
| `.body(text)`, `.severity(Severity::Success)` | A line of detail; a color and icon for info, success, warning or danger. |
| `.action(label, handler)` | A button that runs `handler`, then sends the toast away. |
| `.undo(handler)` | An Undo button and a line that runs out with the time left. |
| `.stay(None)` | Stays until closed. `Some(Duration::ZERO)` panics. |

## A popover, a dialog and a toast

The example opens a popover of details and a dialog that asks before it deletes. Its Delete button closes the dialog and pushes a toast.

```rust example=overlays
```