Dialogs
Modal parameter windows hosted by the craft framework's DialogHost. They mirror Photoshop: no
dimmed backdrop, canvas pan/zoom under an open dialog, Tab cycles text and number fields only, Esc
cancels, Enter confirms when OK is enabled. Automation drives the same field map as the UI
(ui.dialog.* in control-protocol.md).
Architecture
| Piece | Location | Role |
|---|---|---|
| Hosted-dialog glue | crates/ui-egui/src/dialogs.rs |
run, take_results, TAKERS, PROMPTS, PARAM_FAMILIES, confirm, cancel, open_command_dialog, move_memories |
| Dialog host | app.framework.dialogs (DialogHost) |
Draws every open dialog, stacks them, routes OK, Cancel and Esc, keeps the results until taken |
| Chrome | framework DialogFrame |
Title, close box, footer buttons in platform order, FocusPolicy::DIALOG with initial: FirstField |
| Parameter dialogs | framework HostedParamDialog over ParamDialog |
Rows from a Param list, remembered values, Alt+Cancel → Reset (alt_resets, reset_to), own undo history |
| Prompts | framework StandardPrompt |
Question with Proceed / Alternate / Cancel and "Don't show again" |
| Menu / command entry | dialogs::open_command_dialog |
Picks a dedicated opener, the adjustment editor, the schema dialog, or a bare command form |
| Filters | filter_dialog.rs |
Schema from engine params, live preview, the generic family |
| Adjustments | adjust_dialog.rs |
Shared editors with Properties; preview via adjust_preview |
| Family modules | one module per dialog family | open, and either owns + run (a parameter family), answer (a prompt) or take (its own results) |
Frame. dialogs::run(app, ui) runs once per pass. It syncs the guide edit, shows the command
palette, feeds the filter preview, runs the host, then calls take_results. The host applies only a
pass's own input and every result is taken once, so a second pass in one frame acts on nothing twice.
Results. take_results(app, ctx) runs after every host pass and at once after confirm,
cancel and an automation ui.dialog.set, so an answer acts inside the request that caused it.
In order it runs:
params::take: each finishedHostedParamDialoggoes to the firstPARAM_FAMILIESrow whoseowns(key)is true. OK calls the row'srun; Cancel calls itscancelhook. Then held OKs and the dialogs' requests are answered (see below).prompts_take: each finishedStandardPromptanswer goes to thePROMPTSrows in order until one returns true. Only anOkcarries an answer; a prompt's own Cancel button answersOkwithPromptChoice::Cancel. The host keeps one plain result per dialog type, so onlyprompts_taketakesStandardPromptresults.- Each
TAKERSentry: the family modules that take their own dialog types.
Field contract. A dialog's values are its DialogFields, keyed by parameter. Keys never start
with __. Automation sets them through DialogHost::set_json_field.
Parameter families (dialogs::params)
| Item | Role |
|---|---|
ParamFamily |
owns, run, and optional check, listing, footer, cancel, document |
PARAM_FAMILIES |
Every family in match order; the generic filter family is last and owns every engine command |
open_param(app, key, fields, captured, build) |
Opens the dialog with history, remembered values under photocraft.<key> and the active document's canvas for droppers; captured is the per-open state the family reads with params::captured and take drops |
answer_held |
Runs a family's check on a held OK and answers the dialog; a refusal shows under the rows |
answer_requests |
Colour rows open the Color Picker as a child (color_picker_ui::open_for_request) and its OK comes back through answer_for; Browse rows pick through host.files(); droppers arm through canvas_input; files rows ask the family's listing; footer buttons go to footer |
confirm(app, ctx, id) answers a dialog with OK and takes the results; a refused held OK comes back
as the error text. cancel(app, ctx, id) cancels and takes the results. cancel_for_closed cancels
the dialogs whose family reports a closed document from the captured value.
Remembered values
A parameter dialog remembers its values in the remembered settings section under
photocraft.<key> (Remembered). move_memories(prefs, host) runs once before the first frame and
moves the old Preferences.dialogs entries there. It applies three parts in order:
- Keep: the keys the engine reads (
ui.layersPanelOptions,file.print, the Save for Web memory) and every don't-show-again key. - Route: a key a library crate names (
filter.cameraRaw.scope,image.adjustments.<kind>,shape.create.<kind>). - Generic: every other entry moves to
photocraft.<key>, nulls dropped.
Command routing
open_command_dialog(app, command, label) returns the new dialog's id or the opener's refusal text.
First match wins:
| Command | Opener |
|---|---|
view.newGuideLayout |
guide_layout_ui::open |
edit.stroke |
stroke_ui::open |
| Equalize, when it asks | equalize_ui::open |
| New Group fronts | new_group_ui::open |
select.colorRange |
color_range_ui::open |
slice.set, slice.divide |
slice_ui::open_options, slice_ui::open_divide |
image.adjustments.* |
adjust_dialog::open |
| commands with a parameter schema | filter_dialog::open |
| anything else | a bare command form that the generic filter family runs |
Other dedicated families open from their menu, tool or panel code with their own open.
Parallel modal systems
| System | Location | When |
|---|---|---|
| Unsaved changes | discard_ui.rs |
Close, Close Others/All, Exit—Save / Don't Save / Cancel, where on macOS ⌘D is Don't Save too (#11282); Revert—Revert / Cancel, with no Don't Save for ⌘D to press |
| Shell dialog | control.rs, ui.inspect id "shell" |
Workspace, custom pixel aspect, show-extras options |
| Camera Raw | camera_raw_ui.rs |
Separate OS window on desktop; see control-protocol § Camera Raw |
| Nested pickers | color_picker_ui |
Open as a child of the dialog that asked; the parent closes them |
Rules
Architecture and commands
- Thin UI, engine command on OK. A family's
runcalls the engine command; one history step unless the command itself batches. - Register in the glue. A parameter family adds a
PARAM_FAMILIESrow; a prompt adds aPROMPTSrow; a module with its own dialog type adds aTAKERSrow. Add the opener toopen_command_dialogwhen it is menu-driven. - Extend existing paths first. Filters →
filter_dialog; adjustments →adjust_dialog; a command form with rows →ParamDialog::command. - The field map is the automation contract. Anything agents must drive lives in named fields, not in local egui state.
- Remember last-used values through
ParamResult::rememberafter the command succeeds.
Chrome and layout
- Footer buttons come from the framework
DialogFrame: platform order, the default action in the corner. - Dialogs are sized from their content by the framework.
- Transparent backdrop: no dimming; previews are judged at true contrast.
- Placement is remembered by the framework; the first open is centred.
- Stacking: only the top dialog is interactive; a child opens over its parent and closes with it.
Keyboard and focus
- Tab / ⇧Tab move between text and number fields (
FocusPolicy::DIALOGwithinitial: FirstField), with select-all on keyboard arrival. - Open on first value: value-first dialogs focus their first field.
- Enter confirms when OK is enabled.
- Esc on the top dialog with no popup open cancels. Click outside does not dismiss. Esc ignores Alt.
- Alt turns Cancel into Reset when the dialog has
alt_resets; Reset restoresreset_toor the opening values.
Canvas and preview
- Live preview for filters and adjustments uses
filter_preview/adjust_preview; a family's Cancel handling clears it. - Under-dialog canvas: a dialog with
ParamDialog::canvaskeeps the canvas view usable under the modal layer; droppers sample it throughcanvas_input.
Labels and i18n
- Titles: command forms use the command's catalogued label; fixed dialogs use
tl!. - User-visible strings:
tl!("…").
Confirm / cancel safety
- Child dialogs first: a parent's OK is refused while a child picker is open; cancelling a parent closes its children.
- Validate before close through the family's
check. - Disable OK when required input is missing.
- Cancel side effects (guide edit, live preview, Actions record) run from the family's
takeorcancelhook on a Cancel result.
Testing
- egui_kittest: open the dialog,
run_steps, press keys, assert the dialog's fields.dialogs::testing::{confirm, cancel}answer a dialog from a test. - Filter preview:
dialogs/tests.rscovers preview persistence across background jobs.
Anti-patterns
- No panics in
runorcheckon bad input; return the refusal. - No hard-coded colours or radii; use the framework theme tokens and components.
- Do not skip
take_resultsafter a programmatic confirm or cancel. - Do not expect click-outside-to-close.
Adding a command dialog (checklist)
- Choose the path:
adjust_dialog,filter_dialog, a bare command form, or a new family module. open: build theDialogFieldsand callparams::open_param(app, key, fields, captured, build).run(app, ctx, result): call the engine command, thenresult.remember(ctx).- Add the
PARAM_FAMILIESrow (before the generic filter family) and, when menu-driven, theopen_command_dialogarm. - Cancel work (preview, record): set the row's
cancelhook. - Tests: open, set fields through
set_json_field,dialogs::testing::confirm, assert the engine or family state.
Known gaps
- “Dialog module” is any UI whose family is routed from
dialogs.rs, not only files named*dialog*. - Numeric field parity (units in expressions, scrubby labels) is tracked in
ui-parity.md(Navigation / numeric fields), not duplicated here.
Revision history
| Date | Change |
|---|---|
| 2026-11-06 | New Guide / Edit Selected Guides: Position Tab focus and exact edit-position handling |
| 2026-10-11 | Initial doc from dialog codebase audit |