docs(print): explain interactive positioning coordinates and safeguards

This commit is contained in:
FartmanAndBurps committed 2026-10-21 14:36:49 +01:00
1 parent 755ca9e2a0
commit a0c6af075c
4 files changed
+42 -3

No files matched your search

+10 -1
View File
@@ -493,7 +493,16 @@ pub struct PrintLayout {
/// Symmetric safety bound for manual Top/Left offsets, shared with the dialog (inches).
pub const MAX_POSITION_INCHES: f64 = 10000.0;
/// The print layout for `doc` with Print parameters `p` (used by the dialog's preview too).
/// Resolves the shared preview/PDF layout without changing `doc`.
///
/// Paper and image bounds use points (72 per inch), with the image origin at bottom-left.
/// Manual `top`/`left` are inches from the paper's top-left; negative values place artwork
/// off-page. Center ignores these offsets. Scale to Fit preserves the aspect ratio and uses
/// the available paper area after the existing mark margins, overriding percentage scale.
/// Emulsion Down is recorded for rendering; the returned rectangle is not yet mirrored.
///
/// Returns an error for malformed manual offsets or offsets beyond [`MAX_POSITION_INCHES`],
/// nonfinite geometry, geometry magnitudes above 1e9, or nonpositive image dimensions.
pub fn layout(doc: &Document, p: &Value, cmd: &str) -> Result<PrintLayout> {
let (pw, ph) = paper(p, cmd)?;
let dpi = f64::from(doc.resolution_dpi.max(1.0));
+4
View File
@@ -1,6 +1,8 @@
use super::*;
use photocraft_doc::{Knot, NamedPath, Path, Subpath};
/// Compares signed-offset layout with actual PDF image operators and whole-page mirroring
/// across scale/fit/orientation cases, while checking the source document stays unchanged.
#[test]
fn negative_print_positions_match_pdf_without_changing_the_document() {
let dir = tmp("negative-position");
@@ -39,6 +41,8 @@ fn negative_print_positions_match_pdf_without_changing_the_document() {
}
}
/// Checks inclusive signed inch limits, malformed manual offsets and overflow-prone scale
/// or paper inputs at the shared layout boundary, without invoking a printer.
#[test]
fn print_position_and_geometry_bounds_reject_malformed_inputs() {
let s = session("rgb", 8);
+22 -2
View File
@@ -840,10 +840,14 @@ fn length_field(ui: &mut egui::Ui, label: &str, pt: &mut f64, units: &str) -> bo
length_field_prec(ui, label, pt, units, 0)
}
/// Edits a point-valued length in the selected units, with the requested decimal precision.
/// Retains the nonnegative 0..=10000 display-unit range used by existing size fields.
fn length_field_prec(ui: &mut egui::Ui, label: &str, pt: &mut f64, units: &str, decimals: u32) -> bool {
length_field_range(ui, label, pt, units, decimals, 0.0..=10000.0)
}
/// Edits a length stored in print points (72 per inch), returning true for a finite edit.
/// `range` is in the displayed `units`; a signed range permits negative Top/Left offsets.
fn length_field_range(ui: &mut egui::Ui, label: &str, pt: &mut f64, units: &str, decimals: u32, range: std::ops::RangeInclusive<f32>) -> bool {
let t = Tokens::get(ui.ctx());
let k = unit_pt(units);
@@ -923,8 +927,14 @@ fn browse_pdf(app: &mut PhotocraftApp, id: u64, suggested: &str) {
}
}
/// Both the pointer and the painter use egui points, including on Retina displays.
/// Applying pixels_per_point here would count the display scale a second time.
/// Converts total displacement from a fixed drag-start layout into manual inch offsets.
/// Resolving Center before the drag avoids a jump; each update replaces the offsets rather
/// than accumulating movement. Emulsion Down reverses horizontal layout-space movement.
///
/// `delta` and the painter use egui points, including on Retina displays; the scale is egui
/// points per print point (1/72 inch). Applying pixels_per_point would count HiDPI twice.
/// Invalid scales or nonfinite displacement/offsets return false without changing fields.
/// Accepted offsets are clamped to the engine's safety bound and Center is disabled.
fn drag_print_position(f: &mut Map<String, Value>, start: photocraft_engine::print_cmds::PrintLayout, delta: egui::Vec2, points_per_print_point: f32) -> bool {
if !points_per_print_point.is_finite() || points_per_print_point <= 0.0 || !delta.is_finite() {
return false;
@@ -943,12 +953,18 @@ fn drag_print_position(f: &mut Map<String, Value>, start: photocraft_engine::pri
true
}
/// Maps the engine's bottom-left print-point rectangle into top-left egui coordinates.
/// `k` is egui points per print point; Emulsion Down mirrors placement across the page,
/// matching the PDF page transform. Returns the full image bounds for the caller to clip.
fn print_preview_image(l: photocraft_engine::print_cmds::PrintLayout, page: egui::Rect, k: f32) -> egui::Rect {
let (x, y, w, h) = l.rect;
let x = if l.emulsion_down { l.paper.0 - x - w } else { x };
egui::Rect::from_min_size(egui::pos2(page.left() + x as f32 * k, page.bottom() - (y + h) as f32 * k), egui::vec2(w as f32 * k, h as f32 * k))
}
/// Draws the print controls and paper-clipped preview using the engine's shared layout.
/// Dragging the visible image updates dialog offsets live from a fixed gesture origin;
/// the position row stays present while centered so switching to manual cannot move the page.
fn print_body(app: &mut PhotocraftApp, ui: &mut egui::Ui, f: &mut Map<String, Value>, id: u64) {
let t = Tokens::get(ui.ctx());
let Some(doc) = app.session.active().map(|d| d.doc.clone()) else { return };
@@ -1298,6 +1314,8 @@ pub(crate) fn print_status(app: &mut PhotocraftApp, r: &Value) {
mod tests {
use super::*;
/// Checks no-jump centering and nonaccumulating screen displacement against shared layout
/// across fit, percentage scaling, orientation and mirroring combinations.
#[test]
fn print_drag_uses_the_resolved_layout_and_screen_points_without_accumulation() {
let (app, _) = app();
@@ -1334,6 +1352,8 @@ mod tests {
}
}
/// Checks rejected pointer geometry leaves fields untouched and extreme finite drags
/// clamp both inch offsets to the same safety limits as numeric positioning.
#[test]
fn print_drag_rejects_nonfinite_input_and_bounds_offsets() {
let (app, _) = app();
@@ -28,6 +28,8 @@ fn harness(app: PhotocraftApp) -> Harness<'static, PhotocraftApp> {
harness_at_scale(app, 1.0)
}
/// Builds the real dialog at an explicit physical-pixels-per-egui-point ratio so pointer
/// events remain in egui points while exercising both standard and Retina display scales.
fn harness_at_scale(app: PhotocraftApp, pixels_per_point: f32) -> Harness<'static, PhotocraftApp> {
let mut h = Harness::builder().with_size(vec2(1000.0, 900.0)).with_pixels_per_point(pixels_per_point).with_max_steps(64).build_ui_state(show, app);
PhotocraftApp::setup_context(&h.ctx, Default::default());
@@ -67,6 +69,8 @@ fn fields(h: &Harness<'_, PhotocraftApp>, id: u64) -> Map<String, Value> {
h.state().ui.dialogs.iter().find(|d| d.id == id).unwrap().fields.clone()
}
/// Finds the thumbnail's painted mesh bounds, rather than the earlier interaction bounds,
/// so drag assertions detect visible lag in the same frame as a Center transition.
fn painted_image(h: &Harness<'_, PhotocraftApp>) -> egui::Rect {
let active = h.state().session.active().unwrap();
let key = egui::Id::new(("print-thumb", active.doc.id.0, active.revision));
@@ -81,6 +85,8 @@ fn painted_image(h: &Harness<'_, PhotocraftApp>) -> egui::Rect {
.expect("the print image must be painted")
}
/// Exercises live painted movement at 1x/2x display scale, signed numeric entry and pointer
/// capture off-page and back, then verifies Center restores the shared layout's placement.
#[test]
fn preview_drag_and_negative_fields_work_at_standard_and_retina_scale() {
for pixels_per_point in [1.0, 2.0] {