make TabletMove hover events conditional on QWidget::tabletTracking

This adds the tabletTracking property in the same way that mouseTracking already
existed: there is a WA_TabletTracking attribute, and a TabletTrackingChange event
to notify when it changes.  So for widget applications it's an opt-in feature.
QtQuick applications don't yet make use of tablet events, but when they do
in the future, we don't yet have a mechanism to turn the move events off;
it remains to be seen whether that will be necessary.

[ChangeLog][QtWidget] QWidget now has a tabletTracking property, analogous
to mouseTracking, which will enable TabletMove events while the stylus is
hovering, even if no button is pressed.  This allows applications to show
feedback based on the other tablet event properties such as rotation and tilt.

Task-number: QTBUG-26116
Change-Id: Ie96e8acad882b167e967796cdd17f1ad747a2771
Reviewed-by: Andy Shaw <andy.shaw@qt.io>

6 files changed, 51 insertions, 1 deletions

diff --git a/examples/widgets/widgets/tablet/tabletcanvas.cpp b/examples/widgets/widgets/tablet/tabletcanvas.cpp
index ba797500e9..03e05e42f6 100644
--- a/examples/widgets/widgets/tablet/tabletcanvas.cpp
+++ b/examples/widgets/widgets/tablet/tabletcanvas.cpp
@@ -67,6 +67,7 @@ TabletCanvas::TabletCanvas()
     resize(500, 500);
     initPixmap();
     setAutoFillBackground(true);
+    setAttribute(Qt::WA_TabletTracking);
 }
 
 void TabletCanvas::initPixmap()
diff --git a/src/corelib/global/qnamespace.h b/src/corelib/global/qnamespace.h
index c3833c6bd1..da44c01594 100644
--- a/src/corelib/global/qnamespace.h
+++ b/src/corelib/global/qnamespace.h
@@ -472,6 +472,8 @@ public:
 
         WA_AlwaysStackOnTop = 128,
 
+        WA_TabletTracking = 129,
+
         // Add new attributes before this line
         WA_AttributeCount
     };
diff --git a/src/corelib/global/qnamespace.qdoc b/src/corelib/global/qnamespace.qdoc
index 8da06f71f7..b8588b3f98 100644
--- a/src/corelib/global/qnamespace.qdoc
+++ b/src/corelib/global/qnamespace.qdoc
@@ -1139,6 +1139,9 @@
     \value WA_StyleSheet Indicates that the widget is styled using a
     \l{Qt Style Sheets}{style sheet}.
 
+    \value WA_TabletTracking Indicates that the widget has tablet
+    tracking enabled. See QWidget::tabletTracking.
+
     \value WA_TranslucentBackground Indicates that the widget should have a
     translucent background, i.e., any non-opaque regions of the widgets will be
     translucent because the widget will have an alpha channel. Setting this
diff --git a/src/corelib/kernel/qcoreevent.h b/src/corelib/kernel/qcoreevent.h
index 7e962f816e..ac974ba411 100644
--- a/src/corelib/kernel/qcoreevent.h
+++ b/src/corelib/kernel/qcoreevent.h
@@ -284,6 +284,8 @@ public:
 
         Pointer = 218,                          // QQuickPointerEvent; ### Qt 6: QPointerEvent
 
+        TabletTrackingChange = 219,             // tablet tracking state has changed
+
         // 512 reserved for Qt Jambi's MetaCall event
         // 513 reserved for Qt Jambi's DeleteOnMainThread event
 
diff --git a/src/widgets/kernel/qwidget.cpp b/src/widgets/kernel/qwidget.cpp
index 2cb259468d..70bc407587 100644
--- a/src/widgets/kernel/qwidget.cpp
+++ b/src/widgets/kernel/qwidget.cpp
@@ -6387,6 +6387,24 @@ void QWidget::setWindowRole(const QString &role)
     \sa mouseMoveEvent()
 */
 
+/*!
+    \property QWidget::tabletTracking
+    \brief whether tablet tracking is enabled for the widget
+    \since 5.9
+
+    If tablet tracking is disabled (the default), the widget only
+    receives tablet move events when the stylus is in contact with
+    the tablet, or at least one stylus button is pressed,
+    while the stylus is being moved.
+
+    If tablet tracking is enabled, the widget receives tablet move
+    events even while hovering in proximity.  This is useful for
+    monitoring position as well as the auxiliary properties such
+    as rotation and tilt, and providing feedback in the UI.
+
+    \sa tabletEvent()
+*/
+
 
 /*!
     Sets the widget's focus proxy to widget \a w. If \a w is 0, the
@@ -8788,6 +8806,9 @@ bool QWidget::event(QEvent *event)
 #endif
 #ifndef QT_NO_TABLETEVENT
     case QEvent::TabletMove:
+        if (static_cast<QTabletEvent *>(event)->buttons() == Qt::NoButton && !testAttribute(Qt::WA_TabletTracking))
+            break;
+        Q_FALLTHROUGH();
     case QEvent::TabletPress:
     case QEvent::TabletRelease:
         tabletEvent((QTabletEvent*)event);
@@ -9020,6 +9041,7 @@ bool QWidget::event(QEvent *event)
     case QEvent::IconTextChange:
     case QEvent::ModifiedChange:
     case QEvent::MouseTrackingChange:
+    case QEvent::TabletTrackingChange:
     case QEvent::ParentChange:
     case QEvent::LocaleChange:
     case QEvent::MacSizeChange:
@@ -9425,7 +9447,13 @@ void QWidget::wheelEvent(QWheelEvent *event)
 
     The default implementation ignores the event.
 
-    \sa QEvent::ignore(), QEvent::accept(), event(),
+    If tablet tracking is switched off, tablet move events only occur if the
+    stylus is in contact with the tablet, or at least one stylus button is
+    pressed, while the stylus is being moved. If tablet tracking is switched on,
+    tablet move events occur even while the stylus is hovering in proximity of
+    the tablet, with no buttons pressed.
+
+    \sa QEvent::ignore(), QEvent::accept(), event(), setTabletTracking(),
     QTabletEvent
 */
 
@@ -11194,6 +11222,10 @@ void QWidget::setAttribute(Qt::WidgetAttribute attribute, bool on)
         QEvent e(QEvent::MouseTrackingChange);
         QApplication::sendEvent(this, &e);
         break; }
+    case Qt::WA_TabletTracking: {
+        QEvent e(QEvent::TabletTrackingChange);
+        QApplication::sendEvent(this, &e);
+        break; }
     case Qt::WA_NativeWindow: {
         d->createTLExtra();
         if (on)
diff --git a/src/widgets/kernel/qwidget.h b/src/widgets/kernel/qwidget.h
index 4c80038a4f..1c378924a0 100644
--- a/src/widgets/kernel/qwidget.h
+++ b/src/widgets/kernel/qwidget.h
@@ -161,6 +161,7 @@ class Q_WIDGETS_EXPORT QWidget : public QObject, public QPaintDevice
     Q_PROPERTY(QCursor cursor READ cursor WRITE setCursor RESET unsetCursor)
 #endif
     Q_PROPERTY(bool mouseTracking READ hasMouseTracking WRITE setMouseTracking)
+    Q_PROPERTY(bool tabletTracking READ hasTabletTracking WRITE setTabletTracking)
     Q_PROPERTY(bool isActiveWindow READ isActiveWindow)
     Q_PROPERTY(Qt::FocusPolicy focusPolicy READ focusPolicy WRITE setFocusPolicy)
     Q_PROPERTY(bool focus READ hasFocus)
@@ -328,6 +329,9 @@ public:
     bool hasMouseTracking() const;
     bool underMouse() const;
 
+    void setTabletTracking(bool enable);
+    bool hasTabletTracking() const;
+
     void setMask(const QBitmap &);
     void setMask(const QRegion &);
     QRegion mask() const;
@@ -809,6 +813,12 @@ inline bool QWidget::hasMouseTracking() const
 inline bool QWidget::underMouse() const
 { return testAttribute(Qt::WA_UnderMouse); }
 
+inline void QWidget::setTabletTracking(bool enable)
+{ setAttribute(Qt::WA_TabletTracking, enable); }
+
+inline bool QWidget::hasTabletTracking() const
+{ return testAttribute(Qt::WA_TabletTracking); }
+
 inline bool QWidget::updatesEnabled() const
 { return !testAttribute(Qt::WA_UpdatesDisabled); }