fix(input): cursors follow the pointer while dragging and snap on drop

include/plot/plot/plot.hpp

@@ -388,19 +388,44 @@ class Plot {
   // --- cursors and measurements -----------------------------------------
 
   /// Moves a **vertical** cursor along x, and invalidates the measurements that depend
-  /// on cursors. A `SnapMode::NearestSample` cursor is pulled onto the nearest sample of
-  /// the first visible trace on its x axis.
+  /// on cursors. With the default `CursorPlacement::Snapped`, a `SnapMode::NearestSample`
+  /// cursor is pulled onto the nearest sample of the first visible trace on its x axis;
+  /// with `CursorPlacement::Free` the value is stored verbatim, whatever the snap, and the
+  /// grid is applied later by `snap_cursor()`.
+  ///
+  /// The two are the two things a caller does with this method: place a marker
+  /// programmatically (default -- snap now), or move it under a pointer for the length of
+  /// a gesture (`Free`). `input::Controller::move_cursor()` is the second, so **the value
+  /// this stores while that drag runs, and the value `cursor(id).x` reports, is the free
+  /// pointer position, not the snapped one** -- the snap is committed once, on release
+  /// (`snap_cursor()`, from `Controller::end_drag()`). A caller reading `cursor(id).x`
+  /// mid-drag reads what the user sees under the pointer; after the drop it reads the
+  /// snapped result. A host that wants the cursor to *hop* between samples as it is
+  /// dragged -- the old behaviour -- calls this without `Free` on every motion.
   ///
   /// A horizontal ruler's `x` is not a coordinate of its: this is *ignored* for one, so
   /// the dead field of an orientation can never be written behind its back (see
   /// CursorOrientation). `set_cursor_y()` is the ruler's half of the pair.
-  void set_cursor_x(u32 id, f64 x);
+  void set_cursor_x(u32 id, f64 x, CursorPlacement placement = CursorPlacement::Snapped);
   /// Sets the snap of a **vertical** cursor, re-placing it under the new rule at once.
   /// Ignored for a horizontal ruler, whose snap is `HRulerSnap` -- see
   /// `set_cursor_h_snap()`.
   void set_cursor_snap(u32 id, SnapMode mode);
 
-  /// Moves a **horizontal** ruler along y, re-placing it under its own snap rule.
+  /// Applies a cursor's own snap rule to the coordinate it already holds: the nearest
+  /// sample for a `SnapMode::NearestSample` marker, the nearest y tick for a
+  /// `HRulerSnap::NearestTick` ruler, and nothing for a `Free` cursor of either
+  /// orientation. The one act `input::Controller::end_drag()` commits a cursor drag with,
+  /// so the drop lands on the grid -- the same shape as `snap_region()`, which a region
+  /// drag ends with, and the reason both orientations snap on drop rather than
+  /// continuously.
+  void snap_cursor(u32 id);
+
+  /// Moves a **horizontal** ruler along y, re-placing it under its own snap rule unless
+  /// `CursorPlacement::Free` is passed -- in which case the value is stored verbatim and
+  /// the snap waits for `snap_cursor()`, exactly as `set_cursor_x()`'s `Free` does for a
+  /// marker. The two orientations therefore snap at the *same* moment of a gesture (the
+  /// drop), not one continuously and the other on release.
   ///
   /// Ignored for a vertical cursor -- `y` is not its coordinate -- and stored verbatim for
   /// a ruler, exactly as `set_cursor_x()` stores a `Free` cursor's x: a y outside the axis'
@@ -409,7 +434,7 @@ class Plot {
   /// that has left the axes has no data under it, so `input::Controller` keeps a dragged
   /// ruler on its axis' range rather than storing a coordinate no pointer could reach
   /// (see `Controller::move_cursor()`).
-  void set_cursor_y(u32 id, f64 y);
+  void set_cursor_y(u32 id, f64 y, CursorPlacement placement = CursorPlacement::Snapped);
   /// Sets the snap of a **horizontal** ruler: `NearestTick` pulls its y onto the nearest
   /// tick of its y axis' tick set -- majors and minors alike, the one list the axis
   /// refreshed -- and `Free` leaves it where it is.