From de540c283d96630c189df9c9be37f68ad8285056 Mon Sep 17 00:00:00 2001 From: Shawn Rutledge Date: Tue, 13 Jul 2021 13:06:11 +0200 Subject: [PATCH] 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 Reviewed-by: Volker Hilsheimer --- src/corelib/global/qnamespace.qdoc | 7 ++- src/gui/kernel/qevent.cpp | 53 +++++++++++++++++------ src/gui/kernel/qevent.h | 4 +- src/gui/kernel/qguiapplication.cpp | 2 +- src/gui/kernel/qwindowsysteminterface.cpp | 8 ++-- src/gui/kernel/qwindowsysteminterface.h | 4 +- src/gui/kernel/qwindowsysteminterface_p.h | 2 +- 7 files changed, 52 insertions(+), 28 deletions(-) diff --git a/src/corelib/global/qnamespace.qdoc b/src/corelib/global/qnamespace.qdoc index 17396432d5..0ad279f16c 100644 --- a/src/corelib/global/qnamespace.qdoc +++ b/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. - Similar to a click-and-drag mouse movement. + \value PanNativeGesture Specifies the displacement delta in pixels. \value ZoomNativeGesture Specifies the magnification delta in percent. \value SmartZoomNativeGesture Boolean magnification state. - \value RotateNativeGesture Rotation delta in degrees. - \value SwipeNativeGesture Sent after a swipe movements. + \value RotateNativeGesture Specifies the rotation delta in degrees. + \value SwipeNativeGesture Sent after a swipe movement. */ 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 << ')'; } diff --git a/src/gui/kernel/qevent.h b/src/gui/kernel/qevent.h index 374e94bf35..9796886ae1 100644 --- a/src/gui/kernel/qevent.h +++ b/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; diff --git a/src/gui/kernel/qguiapplication.cpp b/src/gui/kernel/qguiapplication.cpp index e6bc471ec7..f41c37c771 100644 --- a/src/gui/kernel/qguiapplication.cpp +++ b/src/gui/kernel/qguiapplication.cpp @@ -2760,7 +2760,7 @@ void QGuiApplicationPrivate::processGestureEvent(QWindowSystemInterfacePrivate:: const QPointingDevice *device = static_cast(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); } diff --git a/src/gui/kernel/qwindowsysteminterface.cpp b/src/gui/kernel/qwindowsysteminterface.cpp index 70db73b5d3..355ebb87ec 100644 --- a/src/gui/kernel/qwindowsysteminterface.cpp +++ b/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, - Qt::NativeGestureType type, qreal value, const QPointF &deltas, - const QPointF &local, const QPointF &global, int fingerCount) +bool QWindowSystemInterface::handleGestureEventWithValueAndDelta(QWindow *window, ulong timestamp, const QPointingDevice *device, + Qt::NativeGestureType type, qreal value, const QPointF &delta, + 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 diff --git a/src/gui/kernel/qwindowsysteminterface.h b/src/gui/kernel/qwindowsysteminterface.h index b8cb06e545..cb368d489a 100644 --- a/src/gui/kernel/qwindowsysteminterface.h +++ b/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, - const QPointF &deltas, const QPointF &local, const QPointF &global, int fingerCount = 2); + static bool handleGestureEventWithValueAndDelta(QWindow *window, ulong timestamp, const QPointingDevice *device, Qt::NativeGestureType type, qreal value, + const QPointF &delta, const QPointF &local, const QPointF &global, int fingerCount = 2); #endif // QT_NO_GESTURES static void handlePlatformPanelEvent(QWindow *window); diff --git a/src/gui/kernel/qwindowsysteminterface_p.h b/src/gui/kernel/qwindowsysteminterface_p.h index 0729c1ea39..323fa92ce0 100644 --- a/src/gui/kernel/qwindowsysteminterface_p.h +++ b/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;