Standardize WheelDelta to v120 convention across all platforms #3533
Description
Summary
SKTouchEventArgs.WheelDelta currently has no documented unit contract. Only Windows MAUI passes meaningful values (raw ±120 per notch). All other platforms either hardcode 0 or don't handle wheel events at all.
We need to standardize WheelDelta across all platforms to use the v120 convention: 120 units = 1 discrete mouse wheel notch. This is the same standard used by both Windows (WHEEL_DELTA = 120) and Linux (libinput v120 API). The number 120 was chosen for its high divisibility (factors: 1,2,3,4,5,6,8,10,12,15,20,24,30,40,60,120), enabling clean subdivision for high-resolution scroll hardware.
Proposed Standard
Unit: v120
WheelDelta = number of v120 units, where 120 = one discrete mouse wheel notch.
Sign Convention
- Positive = scroll up (away from user)
- Negative = scroll down (toward user)
- Matches Windows convention
Discrete Scroll (mouse wheel)
- One notch MUST produce exactly ±120
- High-resolution mice may produce sub-120 values (e.g., 30, 60)
- Consumers should accumulate until ±120 for line-based scrolling, or use raw values for smooth/pixel scrolling
Fine/Precise Scroll (trackpad, Magic Mouse, high-res mice)
- Values scale proportionally: small gesture → small integer value
- Always integer (platform handler rounds to nearest)
- No dead zone: any detectable movement produces at least ±1
- Sub-120 values represent fractional notches (e.g., 60 = half a notch)
Current State & Sub-Issues
| Platform | Status | Native API | Raw per notch | Sub-issue |
|---|---|---|---|---|
| Windows MAUI | ✅ Already correct | MouseWheelDelta |
±120 (int) | N/A |
| Blazor WASM | ❌ Not implemented | WheelEvent.deltaY + deltaMode |
~100px / ~3 lines | #3534 |
| Android MAUI | ❌ Not implemented | MotionEvent.AXIS_VSCROLL |
±1.0 (float) | #3535 |
| macOS MAUI | ❌ Not implemented | NSEvent.scrollingDeltaY |
±1.0 (CGFloat) | #3536 |
| iOS/iPadOS + Mac Catalyst | ❌ Not implemented | UIPanGestureRecognizer |
Points (CGPoint) | #3537 |
| Tizen MAUI | ❌ Not implemented | Wheel.Z |
±1 (int) | #3538 |
| WPF / WinForms | ❌ No touch handler | MouseWheelEventArgs.Delta / MouseEventArgs.Delta |
±120 (int) | #3539 |
| GTK3/4 (Linux) | ❌ No scroll handler (GTK4 view merged in #3527) | EventControllerScroll / libinput v120 |
±1.0 / ±120 | #3540 |
Normalization Summary
| Platform | Formula | Mouse notch → | Trackpad micro → |
|---|---|---|---|
| Windows | passthrough | 120 | Sub-120 |
| macOS | round(scrollingDeltaY × 120) |
120 | ~12-60 |
| iOS/iPadOS | round(translationDelta × scale) |
~120 | proportional |
| Android | round(axisValue × 120) |
120 | ~12-60 |
| Tizen | -Z × 120 |
120 | N/A |
| Browser (pixel) | round(-deltaY × 1.2) |
~120 | ~1-5 |
| Browser (line) | round(-deltaY × 40) |
~120 | ~40 |
| Browser (page) | round(-deltaY × 120) |
~120 | N/A |
| WPF/WinForms | passthrough | 120 | Sub-120 |
| GTK | round(-dy × 120) |
120 | ~12-60 |
| Linux (libinput) | passthrough | 120 | Sub-120 |
Implementation Priority
- Blazor WASM (Add wheel support to Blazor WASM views with v120 normalization #3534) — No wheel support; add with v120 normalization
- Android (Add wheel support to Android MAUI views with v120 normalization #3535) — Most common platform missing wheel, simple
AXIS_VSCROLL × 120 - macOS (Add wheel support to macOS MAUI views with v120 normalization #3536) — Important for desktop,
scrollingDeltaY × 120 - iOS/iPadOS + Mac Catalyst (Add wheel support to iOS/iPadOS and Mac Catalyst MAUI views with v120 normalization #3537) — Follows macOS, needs
UIPanGestureRecognizer - Tizen (Add wheel support to Tizen MAUI views with v120 normalization #3538) — Lower priority
- WPF / WinForms (Add wheel support to WPF and Windows Forms views with v120 normalization #3539) — Requires touch handler infrastructure first
- GTK3/4 (Add wheel support to GTK3/GTK4 views with v120 normalization #3540) — GTK4 view exists (Add SkiaSharp.Views.Gtk4 using GirCore.Gtk-4.0 bindings #3527), needs scroll event controller