Files
craft-libs/docs/ui-dialogs.md
T
aiongg be927e9393 Dialogs: hosted forms for Canvas Size, About, format options, Export As, Alert, Layer Style and the adjustment dialogs
Each opens on a DialogHost as a StackDialog that owns what its dialog edits
and binds the dialog's open state to its own field, so it opens again after
closing. HostedCanvasSize and HostedImageSize share SizingOutput::hosted.
HostedExportAs keeps its preview and save requests for the app as
HostedSaveForWeb does; HostedAbout keeps the activated link. HostedAlert
holds an Alert's content. HostedLayerStyle frames the Layer Style body in a
form dialog with side buttons and the Preview box, and queues the page's asks
as LayerStyleAsk. HostedAdjustDialog<V, E> frames any adjustment editor the
same way, resizable and remembered for Curves, with the editor's asks as E.

Stories open the hosted dialogs through a story host bound to the card's
open value (dialog::stories::hosted), so the card holds them behind its
button and story-render shows them open. Trials open each on a DialogHost
and check Escape, OK and the asks.
2026-11-13 02:26:58 +00:00

111 lines
8.5 KiB
Markdown

# Dialogs
`craft_ui::dialog` holds the dialog shells, the prompts, and the host that runs an app's dialogs and keeps their answers. craft-ui-panels defines it; craft-ui-canvas adds `FullWindowDialog` and its parts, and the `craft-ui` facade re-exports that combined module.
| Type | Is |
| --- | --- |
| `Dialog` | A dialog on its own layer: modal or modeless, movable by its title band, with a focus trap and a footer of buttons. |
| `DialogFrame` | The chrome every shell shares: title row, close action, footer region. |
| `FullWindowDialog` | A dialog over the whole window. |
| `BlockingOverlay` | A modal layer with no title, for work the window must not interrupt. |
| `Prompt` | A question with answers on the modal preset of `Dialog`. |
| `Alert`, `StandardPrompt`, `UnsavedChangesDialog`, `RecoveryDialog` | Configurations of `Prompt`. |
| `DialogHost` | Runs the open dialogs of a window and keeps their results. |
| `DialogStack` | Which open modal dialog takes the input. |
Form dialogs (`ParamDialog`, image size, properties, new document and others) build on these in `craft_ui::patterns::form_dialogs` (craft-ui-patterns).
## Dialog
`Dialog` is a container: build it, then `show(ui, body)`.
```rust
let shown = Dialog::new("Layer Properties")
.opened(Bind::bound(&mut state.properties_open))
.remember(PROPERTIES_KEY)
.close_on_enter(true)
.buttons([FooterButton::new("OK", DialogRole::Accept), FooterButton::new("Cancel", DialogRole::Cancel)])
.show(ui, |ui, cx| properties_body(ui, cx, &mut state.layer));
if shown.output.picked == Some(0) {
state.apply_properties();
}
```
- Open state: `opened` binds it to the app's value; without it the dialog keeps a session value that starts open. The close action, Escape and `BodyCx::request_close` write `false`.
- Buttons: each `FooterButton` has a `DialogRole` (`Accept`, `Destructive`, `Cancel`, `Other`) that sets its look and its place in the row: the accepting button is last on macOS and Linux and first on Windows. A click closes the dialog unless the button `stays_open`. `FooterButton::letter` gives it an access letter.
- Enter: with `close_on_enter`, Enter activates the enabled `Accept` button, so Enter and a click take the same path. Without such a button, Enter closes the dialog with `CloseReason::Enter`.
- Output: `DialogOutput::closed` is the `CloseReason` in the pass the dialog closed, `picked` is the index of the button clicked or activated, and `result(answer)` turns them into a `DialogResult`.
- Hooks: `close_guard` may refuse the close of a picked button, `on_pick` acts on a pick before the close is decided, and `settle_buttons` sets the buttons' state each pass after the body ran.
Other settings:
| Setting | Effect |
| --- | --- |
| `Dialog::prompt` | A prompt: centred, content capped, fixed in place, not remembered. |
| `modeless` | A tool window: no modal layer and no backdrop. |
| `viewport` | Shows the dialog in its own OS window, with the layer as the fallback where windows are unavailable. |
| `resizable` | Edge grips resize it; the size is saved with `remember`. |
| `remember` | Saves placement and size under a `SaveKey`. |
| `initial_focus` | What takes focus when it opens (`runtime::focus::Initial`). |
| `backdrop` | What is drawn behind a modal dialog (`runtime::overlay::Backdrop`). |
| `outer_gesture` | One undo step over the body's edits from open to close: OK commits it, every other close takes the edits back. Modal dialogs only. |
| `footer` | Content in a footer bar above the buttons. |
A modal dialog blocks input below it in every window, and a press outside does nothing.
## DialogHost
An app usually leaves its dialogs to the window's host. The `AppShell` of each window keeps one `DialogHost` and runs it after the body in every pass. A body reaches it with `BodyCx::dialogs`, which returns a `WindowDialogs` handle:
```rust
if let Some(dialogs) = cx.dialogs() {
dialogs.with(|host| {
if delete_asked {
host.open(StandardPrompt::confirm_delete([name], 1));
}
if let Some(DialogResult::Ok(answer)) = host.take::<StandardPrompt>() {
if answer.choice == PromptChoice::Proceed {
document.delete_layer();
}
}
});
}
```
A dialog on the host is a `StackDialog`: the app builds the value, `open`s it, and reads `take::<D>()` on a later pass. `StackDialog::show` shows one pass and returns `Some(DialogResult)` on the pass it finished; the host then removes it and keeps the result. `DialogResult<T>` is `Ok(T)` or `Cancel`.
Rules of the host:
- One modal at a time: the newest open dialog takes the input. `open_child` opens a dialog over its parent; it closes with the parent.
- One open dialog per type and `StackDialog::instance`. Opening a second one cancels the first and drops its untaken result. `open_unless_open` refuses while one is open.
- A result stays until it is taken or a dialog of the same type and instance opens.
- `enqueue` queues a startup modal by `StartupStage` (recovery, first-launch offer, warning, update). Each opens when the stack is empty, one at a time.
- `cancel::<D>()` closes a dialog from outside as Escape would, and `StackDialog::cancelled` lets it release what it holds.
- `get`, `get_mut` and `confirm::<D>()` reach the open dialog's value, so a script or a test sets fields and answers OK as a user would.
- Automation that doesn't know the dialog's type goes by id. `open_dialogs` lists the open dialogs with their `StackDialog::json_fields`; `set_json_field(ctx, id, field, value)` sets one as the user would (a prompt's answer is its `choice` field, one it has an enabled button for); `confirm_by_id` and `cancel_by_id` close it. A dialog type opts in by implementing `json_fields` and `set_json_field`; `HostedParamDialog`, `StandardPrompt` and `UnsavedChangesDialog` do. `craft_automation::dialogs` runs `ui.dialog.set`, `ui.dialog.confirm` and `ui.dialog.cancel` on a host and lists its dialogs for `ui.inspect`, so an app's control channel needs no code per dialog type.
- `take_keyed` returns the result with `StackDialog::key`, so a Cancel still names the command it answers.
- A hosted form owns what its dialog edits. What the dialog asks of the app while open (a preview, a path, a colour, a link) waits on the hosted value until the app takes it, and the app answers through the hosted value's methods. The hosted forms: `HostedParamDialog`, `HostedFormatOptions`, `HostedImageSize`, `HostedCanvasSize`, `HostedExportAs`, `HostedSaveForWeb`, `HostedAbout`, `HostedNewDocument`, `HostedGuideLayoutDialog`, `HostedNewGuideDialog`, `HostedPropertiesDialog` (ui-patterns), `HostedAlert` (ui-panels), `HostedLayerStyle` and `HostedAdjustDialog<V, E>` around any adjustment editor (craft-imaging).
- While the host runs its dialogs, or inside a `with` closure, `BodyCx::dialogs` returns `None`. A dialog that the host runs opens children through its own `DialogHost` value.
## DialogStack
`DialogStack` is the routing stack: `push(id, parent)`, `remove`, `remove_tree` (a parent and every dialog opened from it), `top`, `is_top`, `has_child`. `dialog_id(key)` gives a dialog its stable `DialogId`. The host keeps one; an app that shows a `Dialog` itself beside the host reads it with `DialogHost::stack`.
## Prompts
`Prompt::new(title, message)` takes `answers` (`FooterButton`s), and optionally `paragraph`, `lines`, `details` and `extras`. Escape and the close action give the escape answer: Cancel, else the first Other answer, else the default answer. Enter gives the Accept answer while that button is enabled. Both come back as `PromptOutput::picked`.
`StandardPrompt` is the set of confirmations every app asks the same way. Each one has the platform's button order and a letter on every answer, and Escape cancels:
| Constructor | Asks |
| --- | --- |
| `confirm_delete(names, count)` | Delete the items? |
| `changed_on_disk` | The document's file changed on disk: Replace or Cancel. |
| `replace_file` | A save would overwrite a file the save dialog did not ask about. |
| `trash_mask` | Trash a layer mask: Apply, Delete or Cancel. |
| `custom` | The app's own message and buttons. |
`dont_show_again` adds a check box. The answer is a `PromptAnswer`: its `choice` (`PromptChoice::Proceed`, `Alternate` or `Cancel`), `skip` (the box was ticked and the choice is Proceed; the app stores it) and the `tag` the app attached to say which question it answers.
`Alert` is a notice with one OK. `UnsavedChangesDialog` asks Save, Don't Save or Cancel for one document and answers an `UnsavedAnswer`. `RecoveryDialog` offers to recover documents an earlier run autosaved, and answers a `RecoveryAnswer`.