PhotoCraft's UI moves onto the shared craft UI framework in storytold/craft-libs (next branch): shell, dock and panels, hosted dialogs, keyboard, focus, IME and pointer routing, the canvas's view commands, themes and tokens. The engine, document model, file formats, commands and automation stay. PhotoCraft pins storytold/craft-libs next.
10 KiB
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 |