macOS: Teach QWheelEvent to handle a new ScrollMomentum phase

We detect if there's an upcoming momentum phase using the same trick
used by e.g. Mozilla in their event handling: https://tinyurl.com/yd8lcs4l,
and as recommended by an Apple engineer: https://tinyurl.com/y8yytlgv

The event is not guaranteed to be in the queue, but in practice it seems
to be. If this assumption fails we can add a wait timeout to the event
search instead of using [NSDate distantPast] as a timeout (which only
looks at queued events).

When the momentum phase is detected, QWheelEvent::phase will have the
new ScrollMomentum value, and the phase transitions will be
ScrollBegin -> ScrollUpdate -> ScrollMomentum -> ScrollEnd.

We no longer send ScrollEnd to signify that the user's fingers have
been lifted off the trackpad; rather, the first event with ScrollMomentum
phase means that the fingers have been lifted and macOS is now sending
simulated-momentum events.

This means ScrollEnd is a reliable indicator that the entire scroll
gesture (both the user interaction and the momentum) has ended.

If the ScrollMomentum phase is skipped, it means the user's fingers
came to rest before being lifted, so there is no momentum. In that case
the transitions will be ScrollBegin -> ScrollUpdate -> ScrollEnd.

Task-number: QTBUG-63026
Task-number: QTBUG-65160
Change-Id: I80191a472f6fa892387004c199166a6350124274
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>

1 files changed, 41 insertions, 23 deletions

diff --git a/src/plugins/platforms/cocoa/qnsview_mouse.mm b/src/plugins/platforms/cocoa/qnsview_mouse.mm
index 1de256825a..65bc9f837d 100644
--- a/src/plugins/platforms/cocoa/qnsview_mouse.mm
+++ b/src/plugins/platforms/cocoa/qnsview_mouse.mm
@@ -566,6 +566,42 @@
     NSTimeInterval timestamp = [theEvent timestamp];
     ulong qt_timestamp = timestamp * 1000;
 
+    Qt::ScrollPhase phase = Qt::NoScrollPhase;
+    if (theEvent.phase == NSEventPhaseMayBegin || theEvent.phase == NSEventPhaseBegan) {
+        // MayBegin is likely to happen. We treat it the same as an actual begin,
+        // and follow it with an update when the actual begin is delivered.
+        phase = m_scrolling ? Qt::ScrollUpdate : Qt::ScrollBegin;
+        m_scrolling = true;
+    } else if (theEvent.phase == NSEventPhaseStationary || theEvent.phase == NSEventPhaseChanged) {
+        phase = Qt::ScrollUpdate;
+    } else if (theEvent.phase == NSEventPhaseEnded) {
+        // A scroll event phase may be followed by a momentum phase after the user releases
+        // the finger, and in that case we don't want to send a Qt::ScrollEnd until after
+        // the momentum phase has ended. Unfortunately there isn't any guaranteed way of
+        // knowing whether or not a NSEventPhaseEnded will be followed by a momentum phase.
+        // The best we can do is to look at the event queue and hope that the system has
+        // had time to emit a momentum phase event.
+        if ([NSApp nextEventMatchingMask:NSScrollWheelMask untilDate:[NSDate distantPast]
+                inMode:@"QtMomementumEventSearchMode" dequeue:NO].momentumPhase == NSEventPhaseBegan) {
+            Q_ASSERT(pixelDelta.isNull() && angleDelta.isNull());
+            return; // Ignore this event, as it has a delta of 0,0
+        }
+        phase = Qt::ScrollEnd;
+        m_scrolling = false;
+    } else if (theEvent.momentumPhase == NSEventPhaseBegan) {
+        Q_ASSERT(!pixelDelta.isNull() && !angleDelta.isNull());
+        phase = Qt::ScrollUpdate; // Send as update, it has a delta
+    } else if (theEvent.momentumPhase == NSEventPhaseChanged) {
+        phase = Qt::ScrollMomentum;
+    } else if (theEvent.phase == NSEventPhaseCancelled
+            || theEvent.momentumPhase == NSEventPhaseEnded
+            || theEvent.momentumPhase == NSEventPhaseCancelled) {
+        phase = Qt::ScrollEnd;
+        m_scrolling = false;
+    } else {
+        Q_ASSERT(theEvent.momentumPhase != NSEventPhaseStationary);
+    }
+
     // Prevent keyboard modifier state from changing during scroll event streams.
     // A two-finger trackpad flick generates a stream of scroll events. We want
     // the keyboard modifier state to be the state at the beginning of the
@@ -573,34 +609,16 @@
     // mid-stream. One example of this happening would be when pressing cmd
     // after scrolling in Qt Creator: not taking the phase into account causes
     // the end of the event stream to be interpreted as font size changes.
-    NSEventPhase momentumPhase = [theEvent momentumPhase];
-    if (momentumPhase == NSEventPhaseNone)
+    if (theEvent.momentumPhase == NSEventPhaseNone)
         m_currentWheelModifiers = [QNSView convertKeyModifiers:[theEvent modifierFlags]];
 
-    NSEventPhase phase = [theEvent phase];
-    Qt::ScrollPhase ph = Qt::ScrollUpdate;
-
-    // MayBegin is likely to happen.  We treat it the same as an actual begin.
-    if (phase == NSEventPhaseMayBegin) {
-        m_scrolling = true;
-        ph = Qt::ScrollBegin;
-    } else if (phase == NSEventPhaseBegan) {
-        // If MayBegin did not happen, Began is the actual beginning.
-        if (!m_scrolling)
-            ph = Qt::ScrollBegin;
-        m_scrolling = true;
-    } else if (phase == NSEventPhaseEnded || phase == NSEventPhaseCancelled ||
-               momentumPhase == NSEventPhaseEnded || momentumPhase == NSEventPhaseCancelled) {
-        ph = Qt::ScrollEnd;
-        m_scrolling = false;
-    } else if (phase == NSEventPhaseNone && momentumPhase == NSEventPhaseNone) {
-        ph = Qt::NoScrollPhase;
-    }
     // "isInverted": natural OS X scrolling, inverted from the Qt/other platform/Jens perspective.
     bool isInverted  = [theEvent isDirectionInvertedFromDevice];
 
-    qCDebug(lcQpaMouse) << "scroll wheel @ window pos" << qt_windowPoint << "delta px" << pixelDelta << "angle" << angleDelta << "phase" << ph << (isInverted ? "inverted" : "");
-    QWindowSystemInterface::handleWheelEvent(m_platformWindow->window(), qt_timestamp, qt_windowPoint, qt_screenPoint, pixelDelta, angleDelta, m_currentWheelModifiers, ph, source, isInverted);
+    qCDebug(lcQpaMouse) << "scroll wheel @ window pos" << qt_windowPoint << "delta px" << pixelDelta
+            << "angle" << angleDelta << "phase" << phase << (isInverted ? "inverted" : "");
+    QWindowSystemInterface::handleWheelEvent(m_platformWindow->window(), qt_timestamp, qt_windowPoint,
+            qt_screenPoint, pixelDelta, angleDelta, m_currentWheelModifiers, phase, source, isInverted);
 }
 #endif // QT_CONFIG(wheelevent)