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>

src/corelib/global/qnamespace.qdoc

@@ -3123,12 +3123,11 @@
 
     \value BeginNativeGesture Sent before gesture event stream.
     \value EndNativeGesture   Sent after gesture event stream.
-    \value PanNativeGesture   Sent after a panning gesture.
+    \value PanNativeGesture   Specifies the displacement delta in pixels.
-                              Similar to a click-and-drag mouse movement.
     \value ZoomNativeGesture  Specifies the magnification delta in percent.
     \value SmartZoomNativeGesture Boolean magnification state.
-    \value RotateNativeGesture    Rotation delta in degrees.
+    \value RotateNativeGesture    Specifies the rotation delta in degrees.
-    \value SwipeNativeGesture     Sent after a swipe movements.
+    \value SwipeNativeGesture     Sent after a swipe movement.
 
 */
 

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
+    interpreting trackpad touch events. Gesture events are high-level events
-    as zoom or rotate.
+    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
+    Returns the distance moved since the previous event, in pixels.
-    the target widget, item or viewport contents should be moved.
+    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()) {
+        if (!ne->delta().isNull()) {
-            dbg << ", deltas=";
+            dbg << ", delta=";
-            QtDebugUtils::formatQPoint(dbg, ne->deltas());
+            QtDebugUtils::formatQPoint(dbg, ne->delta());
         }
         dbg << ')';
     }

src/gui/kernel/qevent.h

@@ -424,7 +424,7 @@ public:
     Qt::NativeGestureType gestureType() const { return m_gestureType; }
     int fingerCount() const { return m_fingerCount; }
     qreal value() const { return m_realValue; }
-    QPointF deltas() const { return m_deltas.toPointF(); }
+    QPointF delta() const { return m_delta.toPointF(); }
 
 #if QT_DEPRECATED_SINCE(6, 0)
 #ifndef QT_NO_INTEGER_EVENT_COORDINATES
@@ -443,7 +443,7 @@ public:
 
 protected:
     quint64 m_sequenceId;
-    QVector2D m_deltas;
+    QVector2D m_delta;
     qreal m_realValue;
     Qt::NativeGestureType m_gestureType;
     quint32 m_fingerCount : 4;

src/gui/kernel/qguiapplication.cpp

@@ -2760,7 +2760,7 @@ void QGuiApplicationPrivate::processGestureEvent(QWindowSystemInterfacePrivate::
 
     const QPointingDevice *device = static_cast<const QPointingDevice *>(e->device);
     QNativeGestureEvent ev(e->type, device, e->fingerCount, e->pos, e->pos, e->globalPos, (e->intValue ? e->intValue : e->realValue),
-                           e->deltas, e->sequenceId);
+                           e->delta, e->sequenceId);
     ev.setTimestamp(e->timestamp);
     QGuiApplication::sendSpontaneousEvent(e->window, &ev);
 }

src/gui/kernel/qwindowsysteminterface.cpp

@@ -1056,14 +1056,14 @@ bool QWindowSystemInterface::handleGestureEventWithRealValue(QWindow *window, ul
     return QWindowSystemInterfacePrivate::handleWindowSystemEvent(e);
 }
 
-bool QWindowSystemInterface::handleGestureEventWithValueAndDeltas(QWindow *window, ulong timestamp, const QPointingDevice *device,
+bool QWindowSystemInterface::handleGestureEventWithValueAndDelta(QWindow *window, ulong timestamp, const QPointingDevice *device,
-                                                                  Qt::NativeGestureType type, qreal value, const QPointF &deltas,
+                                                                 Qt::NativeGestureType type, qreal value, const QPointF &delta,
-                                                                  const QPointF &local, const QPointF &global, int fingerCount)
+                                                                 const QPointF &local, const QPointF &global, int fingerCount)
 {
     QWindowSystemInterfacePrivate::GestureEvent *e =
             new QWindowSystemInterfacePrivate::GestureEvent(window, timestamp, type, device, fingerCount, local, global);
     e->realValue = value;
-    e->deltas = deltas;
+    e->delta = delta;
     return QWindowSystemInterfacePrivate::handleWindowSystemEvent(e);
 }
 #endif // QT_NO_GESTURES

src/gui/kernel/qwindowsysteminterface.h

@@ -298,8 +298,8 @@ public:
                                    const QPointF &local, const QPointF &global, int fingerCount = 0);
     static bool handleGestureEventWithRealValue(QWindow *window, ulong timestamp, const QPointingDevice *device, Qt::NativeGestureType type,
                                                 qreal value, const QPointF &local, const QPointF &global, int fingerCount = 2);
-    static bool handleGestureEventWithValueAndDeltas(QWindow *window, ulong timestamp, const QPointingDevice *device, Qt::NativeGestureType type, qreal value,
+    static bool handleGestureEventWithValueAndDelta(QWindow *window, ulong timestamp, const QPointingDevice *device, Qt::NativeGestureType type, qreal value,
-                                                     const QPointF &deltas, const QPointF &local, const QPointF &global, int fingerCount = 2);
+                                                    const QPointF &delta, const QPointF &local, const QPointF &global, int fingerCount = 2);
 #endif // QT_NO_GESTURES
 
     static void handlePlatformPanelEvent(QWindow *window);

src/gui/kernel/qwindowsysteminterface_p.h

@@ -458,7 +458,7 @@ public:
         Qt::NativeGestureType type;
         QPointF pos;
         QPointF globalPos;
-        QPointF deltas;
+        QPointF delta;
         int fingerCount;
         // Mac
         qreal realValue;