diff --git a/crates/ui-egui/src/dialogs.rs b/crates/ui-egui/src/dialogs.rs index 9e54eb12f6..f2c72aa852 100644 --- a/crates/ui-egui/src/dialogs.rs +++ b/crates/ui-egui/src/dialogs.rs @@ -537,10 +537,10 @@ fn hidden_controls(d: &Dialog) -> &'static [&'static str] { Some(DialogKind::Preferences) => &["__category", "__search", "__smartGuides", "__snapToGrid", "__taskBar"], // The section shown, the sheet the preview shows and the preset name being typed. Some(DialogKind::Print | DialogKind::PrintPreset) => &["__savePresetAs", "__section", "__sheet"], - // The section shown, All or a range of artboards, the two password checkboxes and the - // preset name being typed. + // The section shown, All or a range of artboards, the bleed link, the two password + // checkboxes and the preset name being typed. Some(DialogKind::SavePdf | DialogKind::PdfPreset) => { - &["__allArtboards", "__requireOpenPassword", "__restrictPermissions", "__savePresetAs", "__section"] + &["__allArtboards", "__bleedLinked", "__requireOpenPassword", "__restrictPermissions", "__savePresetAs", "__section"] } // The selected rows and Randomize's seed. Some(DialogKind::Recolor) => &["__seed", "__sel"], @@ -658,8 +658,9 @@ pub(crate) fn parent(d: &Dialog) -> Option { /// `ui.dialog.set` changed `field` of the open dialog from `old`: a choice that sets other fields /// sets them as choosing it in the dialog does (Export for Screens' `exportPreset`), a change /// to Export for Screens' sub-folder controls ends an applied preset's item folders, as it does in -/// the dialog, and Transform Each's Relative / Absolute keeps the Scale fields' size. A value -/// Composite Fonts' Show Sample can't take is refused. +/// the dialog, and Transform Each's Relative / Absolute keeps the Scale fields' size. Save PDF's +/// bleed link links the bleed as its button does. A value Composite Fonts' Show Sample or Save +/// PDF's bleed link can't take is refused. pub(crate) fn field_set(app: &mut VectorcraftApp, field: &str, old: Option<&Value>) -> Result<(), String> { if app.ui.dialog.as_ref().is_some_and(|d| d.kind == transform_each::KIND) { transform_each::field_set(app, field, old); @@ -668,6 +669,9 @@ pub(crate) fn field_set(app: &mut VectorcraftApp, field: &str, old: Option<&Valu if let Some(d) = app.ui.dialog.as_ref().filter(|d| d.kind == composite_fonts::KIND) { return composite_fonts::field_set(d, field); } + if let Some(d) = app.ui.dialog.as_mut().filter(|d| d.kind == save_pdf::KIND || d.kind == save_pdf::PRESET_KIND) { + return save_pdf::field_set(d, field, old); + } let Some(d) = app.ui.dialog.as_mut().filter(|d| d.kind == export_for_screens::KIND) else { return Ok(()) }; match field { "exportPreset" => export_for_screens::preset_set(app), diff --git a/crates/ui-egui/src/dialogs/save_pdf.rs b/crates/ui-egui/src/dialogs/save_pdf.rs index af047a4cc2..bac2d72d7e 100644 --- a/crates/ui-egui/src/dialogs/save_pdf.rs +++ b/crates/ui-egui/src/dialogs/save_pdf.rs @@ -522,10 +522,12 @@ fn apply_preset(app: &mut VectorcraftApp, d: &mut Dialog, name: &str) { const OPTION_FLAGS: [&str; 2] = ["__requireOpenPassword", "__restrictPermissions"]; /// Replace every option with `settings` (from [`settings_fields`]), the password checkboxes -/// included. The preset, the artboard choice, the path and the other UI-only fields (the section, -/// the Save Preset name) stay. +/// included, and let the bleed link follow the new values. The preset, the artboard choice, the +/// path and the other UI-only fields (the section, the Save Preset name) stay. fn replace_settings(d: &mut Dialog, settings: Map) { - d.fields.retain(|k, _| matches!(k.as_str(), "preset" | "range" | "path") || (k.starts_with("__") && !OPTION_FLAGS.contains(&k.as_str()))); + d.fields.retain(|k, _| { + matches!(k.as_str(), "preset" | "range" | "path") || (k.starts_with("__") && !OPTION_FLAGS.contains(&k.as_str()) && k != BLEED_LINKED) + }); d.fields.extend(settings); } @@ -656,25 +658,102 @@ pub(super) fn marks_and_bleeds(app: &VectorcraftApp, ui: &mut egui::Ui, d: &mut flag(ui, d, "bleed.useDocument", tl!("Use document bleed settings"), true); // With the document's bleed the fields show it (Document Setup's `[top, bottom, left, right]`). let document = (get(d, "bleed.useDocument").as_bool() == Some(true)).then(|| app.session.active().map_or([0.0; 4], |s| s.doc.setup.bleed)); - egui::Grid::new("pdf-bleed").num_columns(4).spacing([10.0, 6.0]).show(ui, |ui| { - for pair in [ - [(0, "bleed.top", tl!("Top:")), (1, "bleed.bottom", tl!("Bottom:"))], - [(2, "bleed.left", tl!("Left:")), (3, "bleed.right", tl!("Right:"))], - ] { - for (i, p, label) in pair { - ui.label(label); - match document { - Some(b) => { - ui.add_enabled_ui(false, |ui| widgets::num_field(ui, p, b.get(i).copied(), unit, 80.0)); + // Save PDF and the PDF preset editor link the four sides; Print's Marks and Bleed doesn't. + let pdf = d.kind == KIND || d.kind == PRESET_KIND; + ui.horizontal(|ui| { + egui::Grid::new("pdf-bleed").num_columns(4).spacing([10.0, 6.0]).show(ui, |ui| { + for pair in [ + [(0, "bleed.top", tl!("Top:")), (1, "bleed.bottom", tl!("Bottom:"))], + [(2, "bleed.left", tl!("Left:")), (3, "bleed.right", tl!("Right:"))], + ] { + for (i, p, label) in pair { + ui.label(label); + match document { + Some(b) => { + ui.add_enabled_ui(false, |ui| widgets::num_field(ui, p, b.get(i).copied(), unit, 80.0)); + } + None if pdf => { + if let Some(x) = widgets::num_field(ui, p, get(d, p).as_f64(), unit, 80.0) { + edit_bleed(d, i, x); + } + } + None => length(ui, d, p, unit, true), } - None => length(ui, d, p, unit, true), } + ui.end_row(); + } + }); + if pdf { + let linked = bleed_linked(d); + let tip = if linked { tl!("Make the bleed values differ") } else { tl!("Make all bleed settings the same") }; + // With the document's bleed the link is grayed out and keeps its state for the custom values. + let clicked = ui + .add_enabled_ui(document.is_none(), |ui| widgets::icon_button(ui, if linked { "link" } else { "link-2-off" }, tip, linked, 24.0)) + .inner + .clicked(); + if clicked { + link_bleed(d, !linked); } - ui.end_row(); } }); } +/// The custom bleed's sides in Save PDF and the PDF preset editor, `[top, bottom, left, right]`. +const BLEED_SIDES: [&str; 4] = ["bleed.top", "bleed.bottom", "bleed.left", "bleed.right"]; +/// The field holding whether the link keeps the four custom bleed values the same. Without it, +/// the sides are linked when they are equal (a preset's, or ones `ui.dialog.set` set). +const BLEED_LINKED: &str = "__bleedLinked"; + +/// Whether the custom bleed's sides are linked. +fn bleed_linked(d: &Dialog) -> bool { + d.fields.get(BLEED_LINKED).and_then(Value::as_bool).unwrap_or_else(|| { + let top = get(d, BLEED_SIDES[0]).as_f64(); + BLEED_SIDES[1..].iter().all(|p| get(d, p).as_f64() == top) + }) +} + +/// Link (every side takes the top's value) or unlink (the sides keep their values) the bleed. +fn link_bleed(d: &mut Dialog, on: bool) { + d.fields.insert(BLEED_LINKED.into(), json!(on)); + if on { + let top = get(d, BLEED_SIDES[0]).as_f64().unwrap_or(0.0); + for p in &BLEED_SIDES[1..] { + set(d, p, json!(top)); + } + } +} + +/// Side `side` of the custom bleed was edited to `value`: linked, every side takes it. +fn edit_bleed(d: &mut Dialog, side: usize, value: f64) { + if bleed_linked(d) { + for p in BLEED_SIDES { + set(d, p, json!(value)); + } + } else if let Some(p) = BLEED_SIDES.get(side) { + set(d, p, json!(value)); + } +} + +/// `ui.dialog.set` set `field` of Save PDF or the PDF preset editor: `__bleedLinked` links or +/// unlinks the bleed as its button does, and must be true or false; a new `bleed` drops the link's +/// state, so the link follows the values set. +pub(super) fn field_set(d: &mut Dialog, field: &str, old: Option<&Value>) -> Result<(), String> { + match field { + BLEED_LINKED => match d.fields.get(BLEED_LINKED).cloned() { + Some(Value::Bool(on)) => { + link_bleed(d, on); + Ok(()) + } + v => Err(format!("{BLEED_LINKED} must be true or false, not {}", v.unwrap_or(Value::Null))), + }, + "bleed" if d.fields.get("bleed") != old => { + d.fields.remove(BLEED_LINKED); + Ok(()) + } + _ => Ok(()), + } +} + /// A dropdown of names such as colour profiles or flattener presets (`names`, the first one /// standing for "" at `path`), showing the name at `path` (one that isn't among them too). The /// first `builtins` entries are ours (translated); the others (profiles, saved presets) are names. diff --git a/crates/ui-egui/src/dialogs/save_pdf/tests.rs b/crates/ui-egui/src/dialogs/save_pdf/tests.rs index 91442f111c..05b1b101d4 100644 --- a/crates/ui-egui/src/dialogs/save_pdf/tests.rs +++ b/crates/ui-egui/src/dialogs/save_pdf/tests.rs @@ -443,6 +443,177 @@ fn marks_and_bleeds_reach_the_pdf() { assert!(ellipse, "the non-printing layer is included"); } +/// The four custom bleed values, `[top, bottom, left, right]`. +fn bleed_of(d: &Dialog) -> [f64; 4] { + BLEED_SIDES.map(|p| get(d, p).as_f64().unwrap_or(f64::NAN)) +} + +/// Headless frames of the dialog layer with an accessibility tree, as a 1280 × 900 window. +struct LinkFrames(egui::Context); + +impl LinkFrames { + fn new() -> Self { + let ctx = egui::Context::default(); + ctx.enable_accesskit(); + theme::install_fonts(&ctx); + Self(ctx) + } + + fn run(&self, app: &mut VectorcraftApp, events: Vec) -> egui::FullOutput { + let screen = egui::Rect::from_min_size(egui::Pos2::ZERO, egui::vec2(1280.0, 900.0)); + let input = egui::RawInput { events, screen_rect: Some(screen), ..Default::default() }; + let mut out = self.0.run_ui(input, |ui| super::super::show(app, ui.ctx())); + out.textures_delta.clear(); + out + } + + /// The bleed link's button once the dialog has settled: its name, whether it shows pressed, + /// whether it is grayed out, and its center. + fn link(&self, app: &mut VectorcraftApp) -> (String, bool, bool, egui::Pos2) { + self.run(app, vec![]); + let out = self.run(app, vec![]); + let nodes = &out.platform_output.accesskit_update.as_ref().expect("an accessibility tree").nodes; + let names = ["Make the bleed values differ", "Make all bleed settings the same"]; + let mut found = nodes.iter().filter(|(_, n)| n.role() == egui::accesskit::Role::Button && n.label().is_some_and(|l| names.contains(&l))); + let (_, n) = found.next().expect("a bleed link button"); + assert!(found.next().is_none(), "one bleed link button"); + let b = n.bounds().expect("bounds"); + let pressed = n.toggled() == Some(egui::accesskit::Toggled::True) || n.is_selected() == Some(true); + let center = egui::pos2((b.x0 + b.x1) as f32 * 0.5, (b.y0 + b.y1) as f32 * 0.5); + (n.label().unwrap_or_default().to_string(), pressed, n.is_disabled(), center) + } + + fn click(&self, app: &mut VectorcraftApp, at: egui::Pos2) { + let press = |pressed| egui::Event::PointerButton { pos: at, button: egui::PointerButton::Primary, pressed, modifiers: egui::Modifiers::NONE }; + self.run(app, vec![egui::Event::PointerMoved(at), press(true)]); + self.run(app, vec![press(false)]); + } +} + +/// The link button beside the custom bleed values: the built-in presets' equal sides open linked, +/// an edit to one side sets all four while linked and only that one while unlinked, and linking +/// again gives every side the top's value. The link isn't an export option, and the linked values +/// reach the PDF's page boxes. +#[test] +fn the_bleed_link_keeps_the_four_sides_the_same() { + let (mut app, written, _) = app(); + app.run("ui.savePdfDialog", json!({"path": "/tmp/bleed.pdf"})).unwrap(); + set_field(&mut app, "__section", json!("Marks and Bleeds")); + let f = LinkFrames::new(); + let (name, pressed, disabled, at) = f.link(&mut app); + assert_eq!((name.as_str(), pressed, disabled), ("Make the bleed values differ", true, false), "equal sides open linked"); + edit_bleed(app.ui.dialog.as_mut().unwrap(), 2, 6.0); + assert_eq!(bleed_of(app.ui.dialog.as_ref().unwrap()), [6.0; 4], "linked: the left value sets all four"); + + f.click(&mut app, at); + let (name, pressed, ..) = f.link(&mut app); + assert_eq!((name.as_str(), pressed), ("Make all bleed settings the same", false), "the click unlinks"); + let d = app.ui.dialog.as_mut().unwrap(); + assert_eq!(d.fields.get(BLEED_LINKED), Some(&json!(false))); + edit_bleed(d, 1, 9.0); + edit_bleed(d, 3, 2.0); + assert_eq!(bleed_of(d), [6.0, 9.0, 6.0, 2.0], "unlinked: each side is its own"); + edit_bleed(d, 0, 4.0); + assert_eq!(bleed_of(d), [4.0, 9.0, 6.0, 2.0]); + + let (.., at) = f.link(&mut app); + f.click(&mut app, at); + let (name, pressed, ..) = f.link(&mut app); + assert_eq!((name.as_str(), pressed), ("Make the bleed values differ", true), "the click links again"); + let d = app.ui.dialog.as_ref().unwrap(); + assert_eq!(bleed_of(d), [4.0; 4], "linking gives every side the top's value"); + let p = params(d); + assert_eq!(p["bleed"], json!({"useDocument": false, "top": 4.0, "bottom": 4.0, "left": 4.0, "right": 4.0})); + assert!(p.get(BLEED_LINKED).is_none() && preset_params(d).get(BLEED_LINKED).is_none(), "the link is the dialog's own"); + + super::super::confirm(&mut app).unwrap(); + let bytes = &written.borrow()[0].1; + let page = &vectorcraft_pdf::info(bytes, None).unwrap().pages[0]; + let bleed = page.boxes.iter().find(|(b, _)| *b == vectorcraft_pdf::CropTo::Bleed).expect("a bleed box").1; + let trim = page.boxes.iter().find(|(b, _)| *b == vectorcraft_pdf::CropTo::Trim).expect("a trim box").1; + assert_eq!((trim.x0 - bleed.x0, trim.y0 - bleed.y0, bleed.x1 - trim.x1, bleed.y1 - trim.y1), (4.0, 4.0, 4.0, 4.0)); +} + +/// A preset whose four bleed values differ opens unlinked; choosing a preset or Reset sets the link +/// from that preset's values rather than keeping the one shown before. +#[test] +fn presets_and_reset_set_the_bleed_link_from_their_values() { + let (mut app, _, _) = app(); + app.run("pdf.preset.save", json!({"name": "Uneven", "bleed": {"top": 3, "bottom": 5, "left": 3, "right": 3}})).unwrap(); + app.run("ui.savePdfDialog", json!({"preset": "Uneven"})).unwrap(); + let d = app.ui.dialog.as_ref().unwrap(); + assert!(!bleed_linked(d), "unequal sides open unlinked"); + assert_eq!(bleed_of(d), [3.0, 5.0, 3.0, 3.0], "opening leaves the values as they are"); + + let mut d = d.clone(); + link_bleed(&mut d, true); + apply_preset(&mut app, &mut d, "Uneven"); + assert!(!bleed_linked(&d) && bleed_of(&d) == [3.0, 5.0, 3.0, 3.0], "choosing the preset takes its values and its link"); + apply_preset(&mut app, &mut d, pdf::DEFAULT_PRESET); + assert!(bleed_linked(&d), "the default preset's sides are equal"); + link_bleed(&mut d, false); + app.ui.dialog = Some(d); + app.run("ui.dialogReset", json!({})).unwrap(); + assert!(bleed_linked(app.ui.dialog.as_ref().unwrap()), "Reset sets the link from the preset's values"); + + // The preset editor has the same link. + open_preset(&mut app, &json!({"name": "Uneven"})).unwrap(); + set_field(&mut app, "__section", json!("Marks and Bleeds")); + let f = LinkFrames::new(); + let (name, pressed, disabled, at) = f.link(&mut app); + assert_eq!((name.as_str(), pressed, disabled), ("Make all bleed settings the same", false, false)); + f.click(&mut app, at); + assert_eq!(bleed_of(app.ui.dialog.as_ref().unwrap()), [3.0; 4]); +} + +/// With Use Document Bleed Settings on, the fields show the document's bleed and the link is +/// grayed out; the custom values and the link stay as they were for when it is turned off. +#[test] +fn the_document_bleed_grays_the_link_and_keeps_the_custom_values() { + let (mut app, _, _) = app(); + app.run("document.setup", json!({"bleed": 9})).unwrap(); + app.run("ui.savePdfDialog", json!({"bleed": {"top": 3, "bottom": 5, "left": 3, "right": 3}})).unwrap(); + set_field(&mut app, "__section", json!("Marks and Bleeds")); + set_field(&mut app, "bleed.useDocument", json!(true)); + let f = LinkFrames::new(); + let (name, pressed, disabled, at) = f.link(&mut app); + assert_eq!((name.as_str(), pressed, disabled), ("Make all bleed settings the same", false, true)); + f.click(&mut app, at); + let d = app.ui.dialog.as_ref().unwrap(); + assert!(!d.fields.contains_key(BLEED_LINKED), "a grayed-out link does not change"); + assert_eq!(bleed_of(d), [3.0, 5.0, 3.0, 3.0]); + set_field(&mut app, "bleed.useDocument", json!(false)); + let (name, _, disabled, _) = f.link(&mut app); + assert_eq!((name.as_str(), disabled), ("Make all bleed settings the same", false)); +} + +/// `ui.dialog.set` can set the link (`__bleedLinked`) as its button does, refuses a value other +/// than true or false, and a new `bleed` lets the link follow its values. +#[test] +fn ui_dialog_set_links_the_bleed() { + let (mut app, _, _) = app(); + app.run("ui.savePdfDialog", json!({"bleed": {"top": 3, "bottom": 5, "left": 3, "right": 3}})).unwrap(); + let set = |app: &mut VectorcraftApp, field: &str, value: Value| { + let d = app.ui.dialog.as_mut().unwrap(); + assert!(super::super::accepts_field(d, field), "{field}"); + let old = d.fields.get(field).cloned(); + super::super::set_field(d, field.into(), value); + super::super::field_set(app, field, old.as_ref()) + }; + set(&mut app, BLEED_LINKED, json!(true)).unwrap(); + assert_eq!(bleed_of(app.ui.dialog.as_ref().unwrap()), [3.0; 4], "linking gives every side the top's value"); + for bad in [json!("yes"), json!(1), Value::Null] { + let e = set(&mut app, BLEED_LINKED, bad.clone()).unwrap_err(); + assert!(e.contains("__bleedLinked must be true or false"), "{bad}: {e}"); + } + set(&mut app, BLEED_LINKED, json!(false)).unwrap(); + set(&mut app, "bleed", json!({"top": 1, "bottom": 1, "left": 1, "right": 1})).unwrap(); + let d = app.ui.dialog.as_ref().unwrap(); + assert!(!d.fields.contains_key(BLEED_LINKED) && bleed_linked(d), "equal values set are linked"); + set(&mut app, "bleed", json!({"top": 1, "bottom": 2, "left": 1, "right": 1})).unwrap(); + assert!(!bleed_linked(app.ui.dialog.as_ref().unwrap()), "unequal values set are unlinked"); +} + #[test] fn option_labels_read_well() { assert_eq!(option_label("compression.color.abovePpi"), "Compression › Color › Above Ppi"); diff --git a/docs/control-protocol.md b/docs/control-protocol.md index adac088a13..dbfb47a35a 100644 --- a/docs/control-protocol.md +++ b/docs/control-protocol.md @@ -102,7 +102,7 @@ the two can still win that race. | `ui.click` / `ui.drag` | `{x, y, button?, count?, shift?, alt?, ctrl?, cmd?}` / `{x, y, toX, toY, steps?, count?, button?, shift?, alt?, ctrl?, cmd?}` | egui pointer input; see synthetic input budgets above | | `ui.wheel` | `{x, y, dy?, dx?, unit?: "line"\|"point", shift?, alt?, cmd?}` | a mouse wheel turn over screen point (x, y): `dy` notches up (+) or down, `dx` sideways. Over the canvas the wheel scrolls, Cmd-wheel (Ctrl on Windows and Linux) scrolls sideways and Alt-wheel (Option on the Mac) zooms about the pointer (with the `ctrlWheelScrollsSideways` preference off, Cmd-wheel zooms too); with the `zoomWithMouseWheel` preference the wheel and Alt-wheel zoom about the pointer, Shift-wheel scrolls up and down and Cmd-wheel (Ctrl on Windows and Linux) sideways. Over a focused numeric field (click it first) each notch steps its value as Up/Down do (Shift: ten, Cmd/Ctrl: a tenth) and the panel stays put; over anything else in a panel the wheel scrolls it. Over the canvas, the wheel preferences in `docs/mcp.md` change what these keys do | | `ui.set` | `{brightness?, panel?, rulers?, outline?, grid?, smartGuides?, boundingBox?, controlBar?, imageTracePreview?}` | `outline`: View › Outline for the active document only (each document has its own, a document opens in Preview, and `ui.inspect` shows it as `view.outline`; an error without a document). `imageTracePreview`: the Image Trace panel's Preview (`ui.inspect` shows it as `ui.image_trace_preview`) | -| `ui.dialog.set` / `.confirm` / `.cancel` | `{field, value, action?}` or `{fields: [{field, value}…], action?}` | fill and submit the open dialog. `ui.dialog.set` takes the fields the dialog has (`ui.inspect`) other than its `__` fields, the `__` fields that are controls of the dialog (such as `__section` and `__allArtboards` in Save PDF, `__constrain` in Transform Each and the shape dialogs, and `__search` and `__category` in Preferences; Save PDF's and Print's `__savePresetAs`, the preset name, only while Save Preset… asks for it, since OK then saves a preset), `discard` on a dialog with a discard button, `preview` on one with a live preview, the fields that the dialog reads but adds only when a control changes (such as `searchFolder`, or `copy` in the Transform dialogs), and the fields it passes to the command it runs: every parameter of the `command` dialog's command (`ui.paramDialog`), and the `textureImage` that Load Texture… sets in the Glass, Texturizer and Rough Pastels effects; any other field is an error that lists the dialog's fields, and the dialog stays as it was. Any other `__` field, held or not, holds what the dialog's OK acts on (such as the `__command` and `__params` of a `confirm` or `command` dialog) or the dialog's own state: setting it is the error "the `` dialog cannot set protected field ``", and the dialog stays as it was. `fields` sets the list (at most 256 items) in order (a missing `value` is `null`) and checks every item first: when one is refused, the call is an error and no field changes. `action: "confirm"` or `"cancel"` on `ui.dialog.set` then confirms or cancels the same dialog in the same request, as `ui.dialog.confirm` and `ui.dialog.cancel` do, and the reply is `{dialog, result}`: the dialog after the fields were set and the reply to confirm (`null` for cancel); any other `action` is an error and no field changes | +| `ui.dialog.set` / `.confirm` / `.cancel` | `{field, value, action?}` or `{fields: [{field, value}…], action?}` | fill and submit the open dialog. `ui.dialog.set` takes the fields the dialog has (`ui.inspect`) other than its `__` fields, the `__` fields that are controls of the dialog (such as `__section`, `__allArtboards` and `__bleedLinked` in Save PDF, `__constrain` in Transform Each and the shape dialogs, and `__search` and `__category` in Preferences; Save PDF's and Print's `__savePresetAs`, the preset name, only while Save Preset… asks for it, since OK then saves a preset), `discard` on a dialog with a discard button, `preview` on one with a live preview, the fields that the dialog reads but adds only when a control changes (such as `searchFolder`, or `copy` in the Transform dialogs), and the fields it passes to the command it runs: every parameter of the `command` dialog's command (`ui.paramDialog`), and the `textureImage` that Load Texture… sets in the Glass, Texturizer and Rough Pastels effects; any other field is an error that lists the dialog's fields, and the dialog stays as it was. Any other `__` field, held or not, holds what the dialog's OK acts on (such as the `__command` and `__params` of a `confirm` or `command` dialog) or the dialog's own state: setting it is the error "the `` dialog cannot set protected field ``", and the dialog stays as it was. `fields` sets the list (at most 256 items) in order (a missing `value` is `null`) and checks every item first: when one is refused, the call is an error and no field changes. `action: "confirm"` or `"cancel"` on `ui.dialog.set` then confirms or cancels the same dialog in the same request, as `ui.dialog.confirm` and `ui.dialog.cancel` do, and the reply is `{dialog, result}`: the dialog after the fields were set and the reply to confirm (`null` for cancel); any other `action` is an error and no field changes | | `ui.screenshot` | `{path?, data?}` | capture the window (PNG), written to `path`; `data: true` sends it back as `pngBase64` too. The inline PNG is capped at 64 MiB: with a `path` the file is still written and `pngBase64` is omitted when the image is larger, while a path-less `data: true` request fails if either the raw RGBA image or the encoded PNG exceeds the cap. Needs a presented frame: with the screen locked or the window minimized/covered it fails after ~8 s with an explanatory error | | `ui.render` | `{path?, scale?, artboard?, data?, traceViews?}` | render an artboard headlessly (PNG with the pixels of `app.export {format: "png", background: "white"}` at the same scale; `artboard`: its 0-based index, default the first; `traceViews: true`: Image Trace objects draw in their View, as on the canvas, instead of their tracing result): written to `path`, else (or with `data: true` as well) sent back as `pngBase64` | | `ui.resize` | `{width?, height?}` | request the window's inner size; omitted or null `width` and `height` default to 1440 and 900. Returns `null` | @@ -110,7 +110,7 @@ the two can still win that race. | `app.open` / `app.save` / `app.export` / `app.quit` | `{path, importer?, params?}` / `{path?}` / `{path?, format?, artboard?, range?, scale?, …}` | `app.open` reads every format `document.open` reads (see `document.formats`) and returns its result (`{index, title, format, warnings, …}`; `warnings` say what didn't come in as it was, such as an EPS shown as its preview image and why its PostScript couldn't be read), or null when a dialog asks first or a library loads. The status bar (`ui.inspect` → `ui.status`), after a line about the document's linked files when there is one (Missing linked files below), counts the `warnings` and names the first that says reading the file left something out (the notes that make Save ask before writing over it), else the first; with several, hovering it lists them in that order, as many as fit in the window (at most 30), then how many more. After `app.save`, and `app.export` with a `path`, the status bar counts the reply's `warnings` and names the first, and with several, hovering it lists them in the reply's order (a save's notes start with what the format loses). With `importer` (an importer plug-in's format id, `plugin.`) it runs `file.openWith`: the file opens with that importer, also when a built-in format reads its extension, with the importer's parameters `params` (their defaults when omitted; no dialog asks for them). Without `importer`, `params` go to the importer that opens the file, and a built-in format does not read them. `app.export` encodes through the engine's `document.export` (same options; the document keeps its path) and writes `path` through the host; without `path` it returns `{dataBase64, format, bytes}`, as headless mode does. It refuses a key that no format takes, and an unknown key inside a PDF or EPS option object, before it writes anything (`docs/mcp.md`, Parameter keys). It accepts a key that only another format takes and does not use it: the reply's `warnings` and the status bar name the key ("`quality` was not used: PDF files don't read it"). `app.save` refuses a key that no save format takes, beside the path or in `options`, the same way. `app.quit`, `file.close` and `file.closeAll` first open a `saveChanges` dialog for each modified document (they return `{"pending": "saveChanges"}`): `ui.dialog.confirm` saves, `ui.dialog.set {field: "discard", value: true}` then confirm discards, `ui.dialog.cancel` cancels the whole close or quit | | `app.export` with `useArtboards` | `{path, useArtboards: true, range? \| artboards?, …}` | Export As: PNG, JPEG and WebP write one file per chosen artboard (default all; SVG does so for a `range`), `-.`, and return `{path, files: [path…]}`; a PDF keeps them as pages of `path`. `useArtboards: false` covers the bounds of the visible art. The menu's Export As… is `file.exportAs`: the `exportAs` dialog (`format`, `useArtboards`, `all`, `range`), then a save dialog and the format's options: `pngOptions` / `jpgOptions` / `webpOptions`, `svgOptions`, or `savePdf` for a PDF | | `ui.dialog.*` on `gradientStop` | `{field: "color" \| "opacity" \| "location", value}` | double-clicking a stop on the Gradient tool's annotator opens its popover (fields `index`, `x`, `y`, `tab`); set `color` (hex), `opacity` or `location` (percentages) and `ui.dialog.confirm` to apply them to the selected stop. `gradient.selectStop {index}` picks the stop the annotator, the panels and Delete/←/→ (`ui.key`) act on | -| `engine.execute` `ui.savePdfDialog` | `{path?, preset?, range?, …document.exportPdf options}` | opens the Save PDF dialog (`file.export.pdf` with no params opens it too). Its fields are the `document.exportPdf` options: set `compatibility` with `ui.dialog.set {field: "compatibility", value: "1.5"}`, a whole section with `{field: "compression", value: {…}}`, the artboards with `__allArtboards: false` and `range`, the visible section with `__section` (General, Compression, Marks and Bleeds, Output, Advanced, Security, Summary). `useArtboards: false` opens it for one page of the visible art's bounds, as Export As with Use Artboards off does: the dialog has no Artboards section and its `__artBounds` field is true. `ui.dialog.confirm` writes `path` (else asks for one), returns `{path, bytes, warnings}` and opens the file when `viewAfterSaving` is set. With `useArtboards: false` it writes the page as `app.export` does and returns `{path, warnings}`, or `{background: true, status}` while Background Export writes it | +| `engine.execute` `ui.savePdfDialog` | `{path?, preset?, range?, …document.exportPdf options}` | opens the Save PDF dialog (`file.export.pdf` with no params opens it too). Its fields are the `document.exportPdf` options: set `compatibility` with `ui.dialog.set {field: "compatibility", value: "1.5"}`, a whole section with `{field: "compression", value: {…}}`, the artboards with `__allArtboards: false` and `range`, the visible section with `__section` (General, Compression, Marks and Bleeds, Output, Advanced, Security, Summary), and the bleed link with `__bleedLinked` (true gives every side the top value; any value other than true or false is an error; setting `bleed` turns the link on when its four sides are equal and off when they differ). `useArtboards: false` opens it for one page of the visible art's bounds, as Export As with Use Artboards off does: the dialog has no Artboards section and its `__artBounds` field is true. `ui.dialog.confirm` writes `path` (else asks for one), returns `{path, bytes, warnings}` and opens the file when `viewAfterSaving` is set. With `useArtboards: false` it writes the page as `app.export` does and returns `{path, warnings}`, or `{background: true, status}` while Background Export writes it | | `file.save` / `file.saveAs` / `file.saveCopy` / `file.saveAsTemplate` (via `engine.execute`) | `{path?, format?, options?, svg?}` | Save writes the document's own file in its own format (a document opened from or saved as SVG/PDF saves as that again; the result's `warnings` say what the format loses). With `path` the file is written at once (Save As or a Copy to an SVG path without SVG options first opens SVG Options, below). Without one (never saved, a converted older file, Save As, a Copy, a Template) the app shows a save panel with one file type per save format (`vectorcraft`, `template`, `pdf`, `svg`, `svgz`, `ai`; for a Template, `template` and `ait`), then the format's options: SVG opens the `svgOptions` dialog (below; returns `{"pending": "svgOptions", "path"}`), PDF the `savePdf` dialog (its `__save` field names the save command); `ui.dialog.confirm` finishes the save. A name typed in the panel without the file type's extension gets it, and a name the panel returns with the extension of a format the panel does not list has it replaced (in a native save, `card.png` and `card.ait` are saved as `card.vectorcraft`, and `notes.v2`, whose extension names no format, is saved as `notes.v2.vectorcraft`); when a file of that name exists, which the panel did not ask about, the save (and every export or other write through a save panel) answers `cancelled` and opens a `replaceFile` dialog (fields `message`, `detail`, `path`): `ui.dialog.confirm` writes that file, `ui.dialog.cancel` writes nothing. A save or export that writes other files beside that path (a file per artboard, linked images, image maps) checks them before it writes anything: when any of them exists, it writes nothing and opens a `replaceFiles` dialog (fields `message`, `detail` (each file's name when there are several), `files`, `__command`, `__params`; the reply is `{"pending": "replaceFiles"}`, or comes once a Background Save or Export ends): `ui.dialog.confirm` runs the save or export again and replaces them, `ui.dialog.cancel` writes nothing; a dialog open when a background job asks stays open, and the question follows it. A save does not ask about the files the document's last Save or Save As in this session wrote. On the web a `saveOptions` dialog (fields `path`, `format`) first names the file and picks the format. `file.formatOptions {format?}` reads the options a save would use. `file.revert` opens a `confirm` dialog (`{"pending": "confirm"}`); `ui.dialog.confirm` reloads the saved file in the same tab. Location refusals return `READ_ONLY_LOCATION: ` without a fallback panel for automation; see [Save location errors](#save-location-errors). | | SVG Options (`engine.execute` of `file.export.svg`, `file.saveAs`, `file.saveCopy`) | `{}` / `{path?, svg?: {…}}` | `file.export.svg` without params, and Save As or Save a Copy to an `.svg`/`.svgz` path without SVG options, open the `svgOptions` dialog (`ui.dialog.set` its fields: `styling`, `outlineText`, `images`, `objectIds`, `decimals`, `minify`, `responsive`, `fewerTspans`, `metadata`, `preserveEditing`, `useArtboards`, `allArtboards`, `range`, `showCode`, `profile` (`svg11`/`tiny12`), `encoding` (`utf8`/`utf16`/`latin1`), `embedFonts`; `ui.dialog.confirm` exports or saves and remembers the choices). With `svg: {…}` (the `document.formats` SVG options) they run directly. `app.save {path?, svg?}` takes the same options; a document saved as SVG saves as SVG again with the same options | | `engine.execute` `file.place` | `{paths?}` / `{path \| name+dataBase64, …file.place params}` | with no file, picks files and opens the `place` dialog; with `paths`, opens it for them (fields `files`, `link`, `template`, `replace`; `__replace` says whether Replace applies, `__info` describes each file). `ui.dialog.confirm` places one file centered in the view (or in place of the selected object) and loads the place cursor with several (`file.place.queue`). In the desktop app the dialog reads its files off the UI thread: `__info` is empty until they are read, `ui.dialog.confirm` returns `{background: true, status}`, `ui.inspect` lists the files still being read in `placing`, and the file is placed (or the cursor loaded) once it is read. With a file, it runs `file.place` centered in the view, at once. Files dropped on the window with no document open open. On the web, files dropped on the canvas are placed at the drop point (linked; Shift embeds) and files dropped off it (the tab bar) open, as in Illustrator; desktop drops carry no pointer position, so documents (native, SVG, PDF, `.ai`, EPS, DXF, EMF/WMF) open as tabs of their own and pictures and text are placed in the middle of the view. Swatch libraries and color books (`.vcswatches`, `.gpl`, `.ase`, `.acb`), graphic style libraries (`.vcstyles`), Libraries panel files (`.vclibrary`), presets (`.vcflattener`, `.vcpdfpresets`, `.vcprintpresets`, `.vcperspective`, `.vcexportpresets`), plug-ins (`.wasm`) and shortcut sets (`.kys`, in Import Shortcut Set) open wherever they are dropped, as File › Open opens them. With the cursor loaded (`ui.inspect` → `tool: "place"`, `toolOptions: {count, current, name, names}`), `ui.pointer` clicks and drags place files (in the desktop app each file is read off the UI thread and placed once it is read, and `ui.inspect` lists it in `placing` until then) and `ui.key` ←/→/↑/↓ and Escape cycle and discard them | diff --git a/docs/target-app-parity.md b/docs/target-app-parity.md index ef83de54ad..b8f63883df 100644 --- a/docs/target-app-parity.md +++ b/docs/target-app-parity.md @@ -2009,6 +2009,7 @@ Moved from the ROADMAP's "Shipped so far" on 2026-10-10. Update it when a featur PDF export and `.ai` saves write a page with a side longer than 14,400 pt with a `UserUnit` (PDF 1.6), its longer side divided by 14,400 and rounded up to the next thousandth, so that no side is longer than 14,400 units (ISO 32000-1, Annex C.2); a PDF 1.5 file with such a page is written as PDF 1.6 with PDF 1.5's encryption, PDF/X files and PDF 1.3 and 1.4 files write it in points (in PDF 1.3 and 1.4, a page past 32,767 pt that needs a real number past 32,767 is refused with an error naming it), a page whose short side is 3 pt or longer but would be under 3 units at that `UserUnit` gets a smaller one that keeps the short side at 3 units, and the export's warnings give each such page's size and how it is written (#6382). The Save PDF dialog's "Write pages longer than 200 in at full size in points" (`longPagesInPoints`, on by default; `.ai` saves leave it off) writes such pages in points without a `UserUnit` at every PDF version, in files without a PDF/X or PDF/A standard, so readers that ignore `UserUnit` show them at full size. Export As PDF with Use Artboards off also opens the Save PDF dialog, without its Artboards section, and writes one page of the visible art's bounds with the dialog's options (`document.exportPdf {useArtboards: false}`; `crates/ui-egui/src/dialogs/tests_export.rs`, `crates/engine/src/cmd/fileio/tests_pdf.rs`). While Alt (Option on macOS) is held, the Save PDF dialog's Cancel button reads Reset, which puts every option back to the chosen preset's settings, passwords included, and leaves the dialog open; letting the key go shows Cancel again (`ui.dialogReset`). [The help page](https://help.adobe.com/archive/en_US/illustrator/cs3/illustrator_cs3_help.pdf#page=283) says that holding Alt or Option and clicking Reset returns the options to their defaults. Resetting to the chosen preset's settings, and keeping the preset, path, artboard range and section, are VectorCraft's own rules (`crates/ui-egui/src/dialogs/save_pdf/tests.rs`, `crates/ui-egui/src/dialogs/tests.rs`). + The Save PDF dialog and the PDF preset editor have a link button beside the four bleed values in Marks and Bleeds: while it is on, editing one value sets the other three to it. [The help page](https://web.archive.org/web/20220911143322/https://helpx.adobe.com/pdf/cs6/illustrator_reference.pdf#page=249) describes this button for the PDF dialog. VectorCraft's own rules: the link opens on when the four values are equal and off when they differ, also after choosing a preset or Reset; turning it on gives every side the top value; turning it off leaves the values as they are; with Use Document Bleed Settings on, the button is grayed out and the custom values and link stay as they were. The link is not a PDF option or a preset setting; `ui.dialog.set` sets it as `__bleedLinked` (`crates/ui-egui/src/dialogs/save_pdf/tests.rs`). `document.exportSelection` run without params (a shortcut) takes the same route after its save panel: a picked PDF opens the Save PDF dialog without its Artboards section, and SVG, the raster formats, EPS, DXF, text and exporter plug-ins with parameters open their options, whose OK writes the selection alone, cropped to it, with the chosen options (`crates/ui-egui/src/dialogs/tests_export_selection.rs`). A `.ai` export with Use Artboards off writes one page of the visible art's bounds without the native document or the editing copy for other apps, with a warning, so the file does not reopen with one artboard in place of the document's; without PDF content it is refused (`crates/engine/src/cmd/fileio/tests_pdfedit.rs`). That page, and an HP-GL plot of the art's bounds, are measured on the art the file draws: non-printing layers the PDF or `.ai` file leaves out do not make it larger, and nor do the non-printing layers, objects at 0% opacity, placed images, clear gradient meshes and unpainted paths a plot leaves out; Export As refuses an HP-GL plot of nothing it draws before the save dialog (`crates/engine/src/cmd/fileio/tests_pdf.rs`, `crates/engine/src/cmd/fileio/tests_hpgl.rs`, `crates/ui-egui/src/dialogs/tests_export.rs`).