Add platform-agnostic gesture recognition system (SKGestureDetector + SKGestureTracker)

docs/docs/gesture-configuration.md

@@ -0,0 +1,123 @@
+# Configuration & Customization
+
+This page covers how to configure gesture thresholds, enable/disable features, read transform state, and programmatically control `SKGestureTracker`. For the quick-start guide, see [Gestures](gestures.md).
+
+## Options
+
+Configure thresholds and behavior through `SKGestureTrackerOptions`:
+
+```csharp
+var options = new SKGestureTrackerOptions
+{
+    // Detection thresholds (inherited from SKGestureDetectorOptions)
+    TouchSlop = 8f,           // Pixels to move before pan starts (default: 8)
+    DoubleTapSlop = 40f,      // Max distance between double-tap taps (default: 40)
+    FlingThreshold = 200f,    // Min velocity (px/s) to trigger fling (default: 200)
+    LongPressDuration = 500,  // Milliseconds to hold for long press (default: 500)
+
+    // Scale limits
+    MinScale = 0.1f,          // Minimum zoom level (default: 0.1)
+    MaxScale = 10f,           // Maximum zoom level (default: 10)
+
+    // Double-tap zoom
+    DoubleTapZoomFactor = 2f, // Scale multiplier on double tap (default: 2)
+    ZoomAnimationDuration = 250, // Animation duration in ms (default: 250)
+    ZoomAnimationInterval = 16,  // Frame interval for zoom animation in ms (~60fps) (default: 16)
+
+    // Scroll zoom
+    ScrollZoomFactor = 0.1f,  // Zoom per scroll unit (default: 0.1)
+
+    // Fling animation
+    FlingFriction = 0.08f,    // Velocity decay per frame (default: 0.08)
+    FlingMinVelocity = 5f,    // Stop threshold in px/s (default: 5)
+    FlingFrameInterval = 16,  // Frame interval in ms (~60fps) (default: 16)
+};
+
+var tracker = new SKGestureTracker(options);
+```
+
+You can also modify options at runtime:
+
+```csharp
+tracker.Options.MinScale = 0.5f;
+tracker.Options.MaxScale = 20f;
+tracker.Options.DoubleTapZoomFactor = 3f;
+```
+
+## Feature Toggles
+
+Enable or disable individual gesture types at runtime. Feature toggles can be set at construction time or modified later:
+
+```csharp
+// Configure at construction time via options
+var options = new SKGestureTrackerOptions
+{
+    IsTapEnabled = true,
+    IsPanEnabled = true,
+    IsPinchEnabled = false,
+    IsRotateEnabled = false,
+};
+var tracker = new SKGestureTracker(options);
+
+// Or toggle at runtime
+tracker.IsTapEnabled = false;
+tracker.IsDoubleTapEnabled = false;
+tracker.IsLongPressEnabled = false;
+tracker.IsPanEnabled = false;
+tracker.IsPinchEnabled = false;
+tracker.IsRotateEnabled = false;
+tracker.IsFlingEnabled = false;
+tracker.IsDoubleTapZoomEnabled = false;
+tracker.IsScrollZoomEnabled = false;
+tracker.IsHoverEnabled = false;
+```
+
+When a gesture is disabled, the tracker suppresses its events. The underlying detector still recognizes the gesture, so you can re-enable it at runtime without losing state.
+
+## Reading Transform State
+
+```csharp
+float scale = tracker.Scale;       // Current zoom level
+float rotation = tracker.Rotation; // Current rotation in degrees
+SKPoint offset = tracker.Offset;   // Current pan offset
+SKMatrix matrix = tracker.Matrix;  // Combined transform matrix
+```
+
+## Programmatic Transform Control
+
+You can set the transform directly without any touch input:
+
+```csharp
+// Reset everything back to identity
+tracker.Reset();
+
+// Set all values at once
+tracker.SetTransform(scale: 2f, rotation: 45f, offset: new SKPoint(100, 50));
+
+// Set individual components
+tracker.SetScale(1.5f);
+tracker.SetScale(2f, pivot: new SKPoint(400, 300));  // Scale around a specific point
+tracker.SetRotation(0f);
+tracker.SetRotation(45f, pivot: new SKPoint(400, 300));  // Rotate around a specific point
+tracker.SetOffset(SKPoint.Empty);
+```
+
+### Animated Zoom
+
+Use `ZoomTo` to animate a zoom by a given factor with a smooth ease-out curve:
+
+```csharp
+// Zoom in by 3x at the center of the view
+tracker.ZoomTo(factor: 3f, focalPoint: new SKPoint(400, 300));
+
+// Check animation state
+bool animating = tracker.IsZoomAnimating;
+```
+
+The animation duration and frame interval are controlled by `ZoomAnimationDuration` and `ZoomAnimationInterval` in the options.
+
+## See Also
+
+- [Gestures — Quick Start](gestures.md)
+- [Gesture Events](gesture-events.md)
+- [API Reference — SKGestureTrackerOptions](xref:SkiaSharp.Extended.SKGestureTrackerOptions)

docs/docs/gesture-events.md

@@ -0,0 +1,175 @@
+# Gesture Events
+
+This page covers all gesture events raised by `SKGestureTracker`, with code examples for each. For the quick-start guide and architecture overview, see [Gestures](gestures.md).
+
+## Tap, Double Tap, Long Press
+
+Single finger gestures detected after the finger lifts (or after a timeout for long press).
+
+```csharp
+tracker.TapDetected += (s, e) =>
+{
+    // e.Location — where the tap occurred
+    // e.TapCount — always 1 for single tap
+};
+
+tracker.DoubleTapDetected += (s, e) =>
+{
+    // Two taps within DoubleTapSlop distance and timing
+    // By default, also triggers a zoom animation (see Double Tap Zoom below)
+    // Set e.Handled = true to prevent the zoom
+};
+
+tracker.LongPressDetected += (s, e) =>
+{
+    // Finger held down without moving for LongPressDuration (default 500ms)
+    // e.Location — where the press occurred
+    // e.Duration — how long the finger was held
+};
+```
+
+## Pan
+
+Single finger drag. The tracker automatically updates its internal offset.
+
+```csharp
+tracker.PanDetected += (s, e) =>
+{
+    // e.Location — current position
+    // e.PreviousLocation — previous position
+    // e.Delta — movement since last event
+    // e.Velocity — current velocity in pixels/second
+};
+```
+
+## Pinch (Scale)
+
+Two finger pinch gesture. The tracker automatically updates its internal scale, clamped to `MinScale`/`MaxScale`.
+
+```csharp
+tracker.PinchDetected += (s, e) =>
+{
+    // e.ScaleDelta — relative scale change (>1 = spread, <1 = pinch)
+    // e.FocalPoint — midpoint between the two fingers
+    // e.PreviousFocalPoint — previous midpoint
+};
+```
+
+## Rotate
+
+Two finger rotation. The tracker automatically updates its internal rotation.
+
+```csharp
+tracker.RotateDetected += (s, e) =>
+{
+    // e.RotationDelta — change in degrees
+    // e.FocalPoint — center of rotation
+};
+```
+
+## Fling
+
+Momentum-based animation after a fast pan. The tracker runs a fling animation that decays over time.
+
+```csharp
+tracker.FlingDetected += (s, e) =>
+{
+    // Fling started — e.Velocity.X, e.Velocity.Y in px/s
+};
+
+tracker.FlingUpdated += (s, e) =>
+{
+    // Called each frame during fling animation
+};
+
+tracker.FlingCompleted += (s, e) =>
+{
+    // Fling animation finished
+};
+```
+
+## Drag (App-Level Object Dragging)
+
+The tracker provides a drag lifecycle derived from pan events. Use this to move objects within your canvas (e.g., stickers, nodes in a graph editor).
+
+```csharp
+tracker.DragStarted += (s, e) =>
+{
+    if (HitTest(e.Location) is { } item)
+    {
+        selectedItem = item;
+        e.Handled = true; // Prevents pan from updating the transform
+    }
+};
+
+tracker.DragUpdated += (s, e) =>
+{
+    if (selectedItem != null)
+    {
+        // Convert screen delta to content coordinates
+        var inverse = tracker.Matrix; inverse.TryInvert(out inverse);
+        var contentDelta = inverse.MapVector(e.Delta.X, e.Delta.Y);
+        selectedItem.Position += contentDelta;
+        e.Handled = true;
+    }
+};
+
+tracker.DragEnded += (s, e) =>
+{
+    selectedItem = null;
+};
+```
+
+When `DragStarted` or `DragUpdated` sets `Handled = true`, the tracker skips its normal pan offset update **and** suppresses fling after release.
+
+## Scroll (Mouse Wheel)
+
+Mouse wheel zoom. Call `ProcessMouseWheel` to feed wheel events.
+
+```csharp
+tracker.ScrollDetected += (s, e) =>
+{
+    // e.Location — mouse position
+    // e.Delta.X, e.Delta.Y — scroll amounts
+};
+```
+
+## Hover
+
+Mouse movement without any buttons pressed. Useful for cursor-based UI feedback.
+
+```csharp
+tracker.HoverDetected += (s, e) =>
+{
+    // e.Location — current mouse position
+};
+```
+
+## Double Tap Zoom
+
+By default, double-tapping zooms in by `DoubleTapZoomFactor` (2×). Double-tapping again at max scale resets to 1×. The zoom animates smoothly over `ZoomAnimationDuration` milliseconds.
+
+To use double tap for your own logic instead, set `e.Handled = true` in your `DoubleTapDetected` handler, or disable it entirely:
+
+```csharp
+tracker.IsDoubleTapZoomEnabled = false;
+```
+
+## Lifecycle Events
+
+```csharp
+// Fired when the first finger touches down (once per gesture sequence)
+tracker.GestureStarted += (s, e) => { /* gesture began */ };
+
+// Fired when all fingers lift
+tracker.GestureEnded += (s, e) => { /* gesture ended */ };
+
+// Fired whenever the transform matrix changes (pan, zoom, rotate, fling frame)
+tracker.TransformChanged += (s, e) => canvas.Invalidate();
+```
+
+## See Also
+
+- [Gestures — Quick Start](gestures.md)
+- [Configuration & Customization](gesture-configuration.md)
+- [API Reference — SKGestureTracker](xref:SkiaSharp.Extended.SKGestureTracker)