Rename QNativeGestureEvent::deltas() to delta(); clarify docs

In QPanGesture this is called delta().
OTOH we have QWheelEvent::pixelDeltas().
Delta is a vector, and there's only one (with two components).

Native gestures hold incremental values: e.g. the pinch gesture event
provides an incremental amount of either zooming or rotation (so most
events have QNativeGestureEvent::value() very close to 0).
It's the same with the pan gesture's delta().

Add better docs for swipe and pan gestures.

Change-Id: Ia147c7c9a22e084c3700b1620dec46427d792bd1
Reviewed-by: Povilas Kanapickas <povilas@radix.lt>
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>

1 files changed, 39 insertions, 14 deletions

diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp
index 85602a9dd0..f7532d4481 100644
--- a/src/gui/kernel/qevent.cpp
+++ b/src/gui/kernel/qevent.cpp
@@ -2734,8 +2734,10 @@ QTabletEvent::~QTabletEvent()
     \ingroup events
 
     Native gesture events are generated by the operating system, typically by
-    interpreting touch events. Gesture events are high-level events such
-    as zoom or rotate.
+    interpreting trackpad touch events. Gesture events are high-level events
+    such as zoom, rotate or pan. Several types hold incremental values: that is,
+    value() and delta() provide the difference from the previous event to the
+    current event.
 
     \table
     \header
@@ -2745,7 +2747,7 @@ QTabletEvent::~QTabletEvent()
     \row
         \li Qt::ZoomNativeGesture
         \li Magnification delta in percent.
-        \li \macos: Two-finger pinch.
+        \li \macos and Wayland: Two-finger pinch.
     \row
         \li Qt::SmartZoomNativeGesture
         \li Boolean magnification state.
@@ -2753,10 +2755,17 @@ QTabletEvent::~QTabletEvent()
     \row
         \li Qt::RotateNativeGesture
         \li Rotation delta in degrees.
-        \li \macos: Two-finger rotate.
+        \li \macos and Wayland: Two-finger rotate.
+    \row
+        \li Qt::SwipeNativeGesture
+        \li Swipe angle in degrees.
+        \li \macos: Configurable in trackpad settings.
+    \row
+        \li Qt::PanNativeGesture
+        \li Displacement delta in pixels.
+        \li Wayland: Three or more fingers moving as a group, in any direction.
     \endtable
 
-
     In addition, BeginNativeGesture and EndNativeGesture are sent before and after
     gesture event streams:
 
@@ -2766,7 +2775,20 @@ QTabletEvent::~QTabletEvent()
         ZoomNativeGesture
         EndNativeGesture
 
-    \sa Qt::NativeGestureType, QGestureEvent
+    The event stream may include interleaved gestures of different types:
+    for example the two-finger pinch gesture generates a stream of Zoom and
+    Rotate events, and PanNativeGesture may sometimes be interleaved with
+    those, depending on the platform.
+
+    Other types are standalone events: SmartZoomNativeGesture and
+    SwipeNativeGesture occur only once each time the gesture is detected.
+
+    \note On a touchpad, moving two fingers as a group (the two-finger flick gesture)
+    is usually reserved for scrolling; in that case, Qt generates QWheelEvents.
+    This is the reason that three or more fingers are needed to generate a
+    PanNativeGesture.
+
+    \sa Qt::NativeGestureType, QGestureEvent, QWheelEvent
 */
 
 /*!
@@ -2826,7 +2848,7 @@ QNativeGestureEvent::QNativeGestureEvent(Qt::NativeGestureType type, const QPoin
                                          quint64 sequenceId)
     : QSinglePointEvent(QEvent::NativeGesture, device, localPos, scenePos, globalPos, Qt::NoButton,
                         Qt::NoButton, Qt::NoModifier),
-      m_sequenceId(sequenceId), m_deltas(deltas), m_realValue(value), m_gestureType(type), m_fingerCount(fingerCount)
+      m_sequenceId(sequenceId), m_delta(deltas), m_realValue(value), m_gestureType(type), m_fingerCount(fingerCount)
 {
     Q_ASSERT(fingerCount < 16); // we store it in 4 bits unsigned
 }
@@ -2854,18 +2876,21 @@ QNativeGestureEvent::~QNativeGestureEvent() = default;
     \since 5.2
 
     Returns the gesture value. The value should be interpreted based on the
-    gesture type. For example, a Zoom gesture provides a scale factor while a Rotate
+    gesture type. For example, a Zoom gesture provides a scale factor delta while a Rotate
     gesture provides a rotation delta.
 
     \sa QNativeGestureEvent, gestureType()
 */
 
 /*!
-    \fn QNativeGestureEvent::deltas() const
+    \fn QNativeGestureEvent::delta() const
     \since 6.2
 
-    Returns the distance moved. A Pan gesture provides the distance in pixels by which
-    the target widget, item or viewport contents should be moved.
+    Returns the distance moved since the previous event, in pixels.
+    A Pan gesture provides the distance in pixels by which the target widget,
+    item or viewport contents should be moved.
+
+    \sa QPanGesture::delta()
 */
 
 /*!
@@ -4181,9 +4206,9 @@ QT_WARNING_POP
         QtDebugUtils::formatQPoint(dbg, ne->position());
         if (!qIsNull(ne->value()))
             dbg << ", value=" << ne->value();
-        if (!ne->deltas().isNull()) {
-            dbg << ", deltas=";
-            QtDebugUtils::formatQPoint(dbg, ne->deltas());
+        if (!ne->delta().isNull()) {
+            dbg << ", delta=";
+            QtDebugUtils::formatQPoint(dbg, ne->delta());
         }
         dbg << ')';
     }