856f865cf98d
control.rs
//! PhotoCraft's control methods, for agents, tests and (soon) MCP: the method table that
//! craft-automation's control channel runs.
//!
//! A transport thread (TCP in the desktop app, a channel in tests) sends [`ControlRequest`]s;
//! between frames the UI thread hands each to [`handle`], which answers with a [`Reply`] that the
//! channel settles (`app/control.rs`). Desktop only, as craft-automation's channel is.
//!
//! Methods:
//! - `engine.execute {command, params}`: run any engine or UI command by id
//! - `engine.commands`: list commands with enablement
//! - `ui.inspect`: full UI state (tool, panels, views, dialogs, windows, window size, `rects`);
//! `dialogs` lists the framework `DialogHost`'s dialogs in their one stack order (top last);
//! `rects` maps each canvas, hosted dialog and the task bar's id to its last on-screen rect;
//! the menu tree is `ui.menu.list`
//! - `ui.set {tool?, panels?, dock?, dockTabs?, dockWidth?, colorPanel?, maskTarget?, vectorMaskTarget?, filterMaskTarget?, selectionMode?, zoom?, center?, rotation?, fit?, theme?, brushSection?, brushTab?, brushesView?, brushPicker?, brushPickerName?, brushPickerStroke?, brushPickerTip?, brushPickerScale?, brushSize?, statusInfo?, marqueeStyle?, marqueeSize?, actionsPanel?, presetBrowsers?, toolbarColumns?, recentView?}`:
//! change UI state; any other field is an error ([`UI_SET_FIELDS`])
//! - `ui.dialog.open {kind, fields?}` / `ui.dialog.set {dialog, field, value}` / `ui.dialog.confirm {dialog, wait?}` / `ui.dialog.cancel {dialog}`:
//! `dialog` is an id as `ui.inspect` lists it, or `"top"` for the top hosted dialog
//! - `ui.dialog.apply {dialog}`: commit Preferences changes without closing the dialog
//! - `ui.notice.post {title, lines?, tone?}`: show a notice; replies `{id}`
//! - `ui.window.open {document?}` / `ui.window.close {window}`: extra document windows
//! - `ui.pointer {events: [{kind: down|move|up, x, y, pressure?, tiltX?, tiltY?, rotation?}], tool?, modifiers?, button?}`: drive the active tool in document coordinates (the open full-window workspace's tool while one is open). The events are queued for the canvas, which takes them on its next pass; the reply does not wait for them (`button: "secondary"` opens the tool's canvas context menu (the pasteboard colour menu outside the image) or Brush Preset picker, or erases with Preferences › Tools › Right-click with painting tools = erase)
//! - `ui.click {x, y, coordinates?, button?, count?, hold?, modifiers?}` / `ui.move {x, y, coordinates?, rest?, modifiers?}` /
//! `ui.wheel {x, y, coordinates?, dx?, dy?, modifiers?}` / `ui.release {button?, key?, x?, y?, coordinates?}`: synthetic
//! pointer input in screen points, or document points with `coordinates: "document"` (the main canvas maps them);
//! `hold` leaves the last press down until `ui.release`, `rest` waits for a hover to rest before the reply
//! (`count` at most [`MAX_CLICKS`], `x` and `y` within ±[`MAX_SCREEN_POINT`]; craft-automation's `synthetic`)
//! - `ui.key {key, hold?, command?, shift?, alt?, ctrl?}` / `ui.type {text}`: synthetic keyboard input
//! - `ui.capsLock {on}`: hold Caps Lock on or off for the canvas (`null` returns to the keyboard's state)
//! - The synthetic input methods reject unknown fields, wrong types, unknown enum values and
//! out-of-range numbers before acting, naming the parameter (#2449)
//! - `ui.resize {width, height}`: resize the main window
//! - `ui.gpu.simulateLoss {error?, destroy?}`: act as if the wgpu device was lost (or, with
//! `error: true`, reported an error): the app switches to the CPU renderer for the rest of the
//! session, as on a real loss. For testing the fallback; returns whether a GPU canvas was active.
//! `destroy: true` destroys the window's real device instead, as a driver reset does: the app
//! saves its unsaved documents for recovery and closes (#3438); returns `destroyed`
//! - `ui.screenshot {path?, focus?, window?}`: capture the main window, or the document window `window` (PNG).
//! Raises the window first (default) because occluded macOS windows stop rendering
//! - `ui.focus`: bring the main window to the front
//! - `app.open {path}` / `app.save {path}`: relative file I/O under the automation roots; reply with `warnings`
//! - `app.quit`
//! - `jobs.list` / `jobs.cancel {job?}`: background jobs (#210) with progress; cancel one (or all).
//! `engine.execute`, `ui.menu.invoke` and `ui.dialog.confirm` wait for a command that runs as a
//! job unless `wait: false` (then the reply is `{job, pending: true}`)
pub use craft::automation::{ControlRequest, ControlResponse, REPLY_DEADLINE, Reply};
use serde_json::{Value, json};
use crate::PhotocraftApp;
use crate::state::Tool;
pub(crate) mod dialogs;
mod dispatch;
mod inspect;
mod params;
pub use craft::automation::synthetic::{MAX_CLICKS, MAX_SCREEN_POINT};
use dispatch::dispatch;
pub use inspect::inspect;
pub use params::UI_SET_FIELDS;
#[cfg(test)]
use params::screen_point;
/// Run a command the way automation does (script events off). Long commands may run as
/// background jobs: by default the reply waits for the job's result (backward compatible); with
/// `wait` false it is `{job, pending: true}` at once.
fn run_waiting(app: &mut PhotocraftApp, wait: bool, run: impl FnOnce(&mut PhotocraftApp) -> Result<Value, String>) -> Reply {
let events_enabled = app.session.prefs().script_events.enabled;
if events_enabled {
app.session.edit_prefs(|prefs| prefs.script_events.enabled = false);
}
app.jobs.last_started = None;
let result = run(app);
if events_enabled {
app.session.edit_prefs(|prefs| prefs.script_events.enabled = true);
}
match (result, app.jobs.last_started.take()) {
(Ok(_), Some(job)) if wait => Reply::AfterJob(job.0),
// A dialog's confirm has no value of its own: the job it started is its reply.
(Ok(Value::Null), Some(job)) => Reply::from_result(Ok(json!({"job": job.0, "pending": true}))),
(result, _) => Reply::from_result(result),
}
}
/// The methods that only hand the window input (it reaches a region as a hand's does) or only read: every other method
/// may change what a settling region shows, so it counts as a command run (`PhotocraftApp::commands_run`).
const INPUT_OR_READ: &[&str] = &[
"engine.commands",
"jobs.list",
"ui.capsLock",
"ui.click",
"ui.inspect",
"ui.key",
"ui.menu.list",
"ui.move",
"ui.pointer",
"ui.release",
"ui.screenshot",
"ui.type",
"ui.wheel",
];
pub fn handle(app: &mut PhotocraftApp, ctx: &egui::Context, req: &ControlRequest) -> Reply {
if !INPUT_OR_READ.contains(&req.method.as_str()) {
app.commands_run += 1;
ctx.request_repaint();
}
let saved = app.session.authorize;
if let Some(gate) = app.services.automation_authorize {
app.session.authorize = Some(gate);
}
let outcome = dispatch(app, ctx, req);
app.session.authorize = saved;
outcome
}
#[cfg(test)]
mod tests;
pub(super) const METHODS: &[&str] = &[
"app.open",
"app.quit",
"app.save",
"engine.commands",
"engine.execute",
"jobs.cancel",
"jobs.list",
"ui.capsLock",
"ui.click",
"ui.context.choose",
"ui.dialog.apply",
"ui.dialog.cancel",
"ui.dialog.confirm",
"ui.dialog.open",
"ui.dialog.set",
"ui.focus",
"ui.gpu.simulateLoss",
"ui.inspect",
"ui.key",
"ui.menu.invoke",
"ui.menu.list",
"ui.move",
"ui.notice.post",
"ui.pointer",
"ui.release",
"ui.resize",
"ui.screenshot",
"ui.set",
"ui.type",
"ui.wheel",
"ui.window.close",
"ui.window.open",
];
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.