PointerHandler: add grabPermissions, enforce in setExclusiveGrab

As soon as we enable the concept that PointerHandlers can use passive
grabs to lurk, monitor all movements, and then steal the passive grab,
they can fight over the grab. For example if there are two items with
PinchHandlers, and two or more touches occur within bounds for both,
then each update event can cause the other PinchHandler to steal the
grabs and become active.

So we replace stealing with negotiation: the handler which wants to
take over the grab checks its own flags to see whether that's allowed,
and the handler which is about to lose its grab also has the right
to approve or deny the takeover (just as QQuickItem has had
keepMouseGrab and keepTouchGrab for a long time.)  Additionally,
if one handler wants to cancel another handler's grab without
taking over (simply set the grabber to null), it must be approved.

A single-point handler can simply call setExclusiveGrab, with the
expectation that permission may be granted or denied.  A multi-point
handler only wants to grab all points if grabbing all of them will
be allowed, otherwise grab none; so it calls canGrab on each point
to check beforehand.  Thus, when two handlers are competing for the
same grabs, one or both can be prevented from stealing from each other,
or from Handlers in general, or from Items, or some combination.

Change-Id: I5c733b2b8995ce686da0be42244394eeee82a268
Reviewed-by: Jan Arve Sæther <jan-arve.saether@qt.io>

4 files changed, 160 insertions, 19 deletions

diff --git a/src/quick/handlers/qquickmultipointhandler.cpp b/src/quick/handlers/qquickmultipointhandler.cpp
index ff4914394c..b126b93211 100644
--- a/src/quick/handlers/qquickmultipointhandler.cpp
+++ b/src/quick/handlers/qquickmultipointhandler.cpp
@@ -298,17 +298,18 @@ void QQuickMultiPointHandler::acceptPoints(const QVector<QQuickEventPoint *> &po
 
 bool QQuickMultiPointHandler::grabPoints(QVector<QQuickEventPoint *> points)
 {
-    bool canGrab = true;
+    bool allowed = true;
     for (QQuickEventPoint* point : points) {
-        auto grabber = point->grabberItem();
-        if (grabber && (grabber->keepMouseGrab() || grabber->keepTouchGrab()))
-            canGrab = false;
+        if (!canGrab(point)) {
+            allowed = false;
+            break;
+        }
     }
-    if (canGrab) {
+    if (allowed) {
         for (QQuickEventPoint* point : points)
             setExclusiveGrab(point);
     }
-    return canGrab;
+    return allowed;
 }
 
 QT_END_NAMESPACE
diff --git a/src/quick/handlers/qquickpointerhandler.cpp b/src/quick/handlers/qquickpointerhandler.cpp
index faebdf3621..64bf1a8a8b 100644
--- a/src/quick/handlers/qquickpointerhandler.cpp
+++ b/src/quick/handlers/qquickpointerhandler.cpp
@@ -42,6 +42,7 @@
 QT_BEGIN_NAMESPACE
 
 Q_LOGGING_CATEGORY(lcPointerHandlerDispatch, "qt.quick.handler.dispatch")
+Q_LOGGING_CATEGORY(lcPointerHandlerGrab, "qt.quick.handler.grab")
 Q_LOGGING_CATEGORY(lcPointerHandlerActive, "qt.quick.handler.active")
 
 /*!
@@ -67,6 +68,7 @@ QQuickPointerHandler::QQuickPointerHandler(QObject *parent)
   , m_targetExplicitlySet(false)
   , m_hadKeepMouseGrab(false)
   , m_hadKeepTouchGrab(false)
+  , m_grabPermissions(CanTakeOverFromItems | CanTakeOverFromHandlersOfDifferentType | ApprovesTakeOverByAnything)
 {
 }
 
@@ -94,7 +96,7 @@ QQuickPointerHandler::~QQuickPointerHandler()
 */
 void QQuickPointerHandler::onGrabChanged(QQuickPointerHandler *grabber, QQuickEventPoint::GrabState stateChange, QQuickEventPoint *point)
 {
-    qCDebug(lcPointerHandlerDispatch) << point << stateChange << grabber;
+    qCDebug(lcPointerHandlerGrab) << point << stateChange << grabber;
     Q_ASSERT(point);
     if (grabber == this) {
         bool wasCanceled = false;
@@ -145,7 +147,7 @@ void QQuickPointerHandler::onGrabChanged(QQuickPointerHandler *grabber, QQuickEv
 */
 void QQuickPointerHandler::setPassiveGrab(QQuickEventPoint *point, bool grab)
 {
-    qCDebug(lcPointerHandlerDispatch) << point << grab;
+    qCDebug(lcPointerHandlerGrab) << point << grab;
     if (grab) {
         point->setGrabberPointerHandler(this, false);
     } else {
@@ -153,14 +155,124 @@ void QQuickPointerHandler::setPassiveGrab(QQuickEventPoint *point, bool grab)
     }
 }
 
-void QQuickPointerHandler::setExclusiveGrab(QQuickEventPoint *point, bool grab)
+/*!
+    Check whether it's OK to take an exclusive grab of the \a point.
+
+    The default implementation will call approveGrabTransition() to check this
+    handler's \l grabPermissions. If grabbing can be done only by taking over
+    the exclusive grab from an Item, approveGrabTransition() checks the Item's
+    \l keepMouseGrab or \l keepTouchGrab flags appropriately. If grabbing can
+    be done only by taking over another handler's exclusive grab, canGrab()
+    also calls approveGrabTransition() on the handler which is about to lose
+    its grab. Either one can deny the takeover.
+*/
+bool QQuickPointerHandler::canGrab(QQuickEventPoint *point)
 {
-    // TODO m_hadKeepMouseGrab m_hadKeepTouchGrab
-    qCDebug(lcPointerHandlerDispatch) << point << grab;
-    // Don't allow one handler to cancel another's grab, unless it is stealing it for itself
-    if (!grab && point->grabberPointerHandler() != this)
+    QQuickPointerHandler *existingPhGrabber = point->grabberPointerHandler();
+    return approveGrabTransition(point, this) &&
+        (existingPhGrabber ? existingPhGrabber->approveGrabTransition(point, this) : true);
+}
+
+/*!
+    Check this handler's rules to see if \l proposedGrabber will be allowed to take
+    the exclusive grab.  This function may be called twice: once on the instance which
+    will take the grab, and once on the instance which would thereby lose its grab,
+    in case of a takeover scenario.
+*/
+bool QQuickPointerHandler::approveGrabTransition(QQuickEventPoint *point, QObject *proposedGrabber)
+{
+    bool allowed = false;
+    if (proposedGrabber == this) {
+        QObject* existingGrabber = point->exclusiveGrabber();
+        allowed = (existingGrabber == nullptr) || ((m_grabPermissions & CanTakeOverFromAnything) == CanTakeOverFromAnything);
+        if (existingGrabber) {
+            if (QQuickPointerHandler *existingPhGrabber = point->grabberPointerHandler()) {
+                if (!allowed && (m_grabPermissions & CanTakeOverFromHandlersOfDifferentType) &&
+                        existingPhGrabber->metaObject()->className() != metaObject()->className())
+                    allowed = true;
+                if (!allowed && (m_grabPermissions & CanTakeOverFromHandlersOfSameType) &&
+                        existingPhGrabber->metaObject()->className() == metaObject()->className())
+                    allowed = true;
+            } else if ((m_grabPermissions & CanTakeOverFromItems)) {
+                QQuickItem * existingItemGrabber = point->grabberItem();
+                if (existingItemGrabber && !((existingItemGrabber->keepMouseGrab() && point->pointerEvent()->asPointerMouseEvent()) ||
+                                             (existingItemGrabber->keepTouchGrab() && point->pointerEvent()->asPointerTouchEvent())))
+                    allowed = true;
+            }
+        }
+    } else {
+        // proposedGrabber is different: that means this instance will lose its grab
+        if (proposedGrabber) {
+            if ((m_grabPermissions & ApprovesTakeOverByAnything) == ApprovesTakeOverByAnything)
+                allowed = true;
+            if (!allowed && (m_grabPermissions & ApprovesTakeOverByHandlersOfDifferentType) &&
+                    proposedGrabber->metaObject()->className() != metaObject()->className())
+                allowed = true;
+            if (!allowed && (m_grabPermissions & ApprovesTakeOverByHandlersOfSameType) &&
+                    proposedGrabber->metaObject()->className() == metaObject()->className())
+                allowed = true;
+            if (!allowed && (m_grabPermissions & ApprovesTakeOverByItems) && proposedGrabber->inherits("QQuickItem"))
+                allowed = true;
+        } else {
+            if (!allowed && (m_grabPermissions & ApprovesCancellation))
+                allowed = true;
+        }
+    }
+    qCDebug(lcPointerHandlerGrab) << "point" << hex << point->pointId() << "permission" <<
+            QMetaEnum::fromType<GrabPermissions>().valueToKeys(grabPermissions()) <<
+            ':' << this << (allowed ? "approved to" : "denied to") << proposedGrabber;
+    return allowed;
+}
+
+/*!
+    \qmlproperty bool QtQuick::PointerHandler::grabPermission
+
+    This property specifies the permissions when this handler's logic decides
+    to take over the exclusive grab, or when it is asked to approve grab
+    takeover or cancellation by another handler.
+
+    The default is
+    \c {CanTakeOverFromItems | CanTakeOverFromHandlersOfDifferentType | ApprovesTakeOverByAnything}
+    which allows most takeover scenarios but avoids e.g. two PinchHandlers fighting
+    over the same touchpoints.
+*/
+void QQuickPointerHandler::setGrabPermissions(GrabPermissions grabPermission)
+{
+    if (m_grabPermissions == grabPermission)
         return;
-    point->setGrabberPointerHandler(grab ? this : nullptr, true);
+
+    m_grabPermissions = grabPermission;
+    emit grabPermissionChanged();
+}
+
+/*!
+    \internal
+    Acquire or give up the exclusive grab of the given \a point, according to
+    the \a grab state, and subject to the rules: canGrab(), and the rule not to
+    relinquish another handler's grab. Returns true if permission is granted,
+    or if the exclusive grab has already been acquired or relinquished as
+    specified. Returns false if permission is denied either by this handler or
+    by the handler or item from which this handler would take over
+*/
+bool QQuickPointerHandler::setExclusiveGrab(QQuickEventPoint *point, bool grab)
+{
+    if ((grab && point->exclusiveGrabber() == this) || (!grab && point->exclusiveGrabber() != this))
+        return true;
+    // TODO m_hadKeepMouseGrab m_hadKeepTouchGrab
+    bool allowed = true;
+    if (grab) {
+        allowed = canGrab(point);
+    } else {
+        QQuickPointerHandler *existingPhGrabber = point->grabberPointerHandler();
+        // Ask before allowing one handler to cancel another's grab
+        if (existingPhGrabber && existingPhGrabber != this && !existingPhGrabber->approveGrabTransition(point, nullptr))
+            allowed = false;
+    }
+    qCDebug(lcPointerHandlerGrab) << point << (grab ? "grab" : "ungrab") << (allowed ? "allowed" : "forbidden") <<
+        point->exclusiveGrabber() << "->" << (grab ? this : nullptr);
+    if (allowed)
+        point->setGrabberPointerHandler(grab ? this : nullptr, true);
+    return allowed;
 }
 
 /*!
@@ -169,7 +281,7 @@ void QQuickPointerHandler::setExclusiveGrab(QQuickEventPoint *point, bool grab)
 */
 void QQuickPointerHandler::cancelAllGrabs(QQuickEventPoint *point)
 {
-    qCDebug(lcPointerHandlerDispatch) << point;
+    qCDebug(lcPointerHandlerGrab) << point;
     point->cancelAllGrabs(this);
 }
 
diff --git a/src/quick/handlers/qquickpointerhandler_p.h b/src/quick/handlers/qquickpointerhandler_p.h
index 24a058275d..9a77dd714a 100644
--- a/src/quick/handlers/qquickpointerhandler_p.h
+++ b/src/quick/handlers/qquickpointerhandler_p.h
@@ -67,11 +67,27 @@ class Q_QUICK_PRIVATE_EXPORT QQuickPointerHandler : public QObject
     Q_PROPERTY(bool active READ active NOTIFY activeChanged)
     Q_PROPERTY(QQuickItem * target READ target WRITE setTarget NOTIFY targetChanged)
     Q_PROPERTY(QQuickItem * parent READ parentItem CONSTANT)
+    Q_PROPERTY(GrabPermissions grabPermissions READ grabPermissions WRITE setGrabPermissions NOTIFY grabPermissionChanged)
 
 public:
     explicit QQuickPointerHandler(QObject *parent = 0);
     virtual ~QQuickPointerHandler();
 
+    enum GrabPermission {
+        TakeOverForbidden = 0x0,
+        CanTakeOverFromHandlersOfSameType = 0x01,
+        CanTakeOverFromHandlersOfDifferentType= 0x02,
+        CanTakeOverFromItems = 0x04,
+        CanTakeOverFromAnything = 0x0F,
+        ApprovesTakeOverByHandlersOfSameType = 0x10,
+        ApprovesTakeOverByHandlersOfDifferentType= 0x20,
+        ApprovesTakeOverByItems = 0x40,
+        ApprovesCancellation = 0x80,
+        ApprovesTakeOverByAnything = 0xF0
+    };
+    Q_DECLARE_FLAGS(GrabPermissions, GrabPermission)
+    Q_FLAG(GrabPermissions)
+
 public:
     bool enabled() const { return m_enabled; }
     void setEnabled(bool enabled);
@@ -85,11 +101,15 @@ public:
 
     void handlePointerEvent(QQuickPointerEvent *event);
 
+    GrabPermissions grabPermissions() const { return static_cast<GrabPermissions>(m_grabPermissions); }
+    void setGrabPermissions(GrabPermissions grabPermissions);
+
 Q_SIGNALS:
     void enabledChanged();
     void activeChanged();
     void targetChanged();
     void grabChanged(QQuickEventPoint *point);
+    void grabPermissionChanged();
     void canceled(QQuickEventPoint *point);
 
 protected:
@@ -99,8 +119,10 @@ protected:
     void setActive(bool active);
     virtual void onActiveChanged() { }
     virtual void onGrabChanged(QQuickPointerHandler *grabber, QQuickEventPoint::GrabState stateChange, QQuickEventPoint *point);
+    virtual bool canGrab(QQuickEventPoint *point);
+    virtual bool approveGrabTransition(QQuickEventPoint *point, QObject *proposedGrabber);
     void setPassiveGrab(QQuickEventPoint *point, bool grab = true);
-    void setExclusiveGrab(QQuickEventPoint *point, bool grab = true);
+    bool setExclusiveGrab(QQuickEventPoint *point, bool grab = true);
     void cancelAllGrabs(QQuickEventPoint *point);
     QPointF eventPos(const QQuickEventPoint *point) const;
     bool parentContains(const QQuickEventPoint *point) const;
@@ -113,11 +135,15 @@ private:
     bool m_targetExplicitlySet : 1;
     bool m_hadKeepMouseGrab : 1;    // some handlers override target()->setKeepMouseGrab(); this remembers previous state
     bool m_hadKeepTouchGrab : 1;    // some handlers override target()->setKeepTouchGrab(); this remembers previous state
+    uint m_reserved : 19;
+    uint8_t m_grabPermissions : 8;
 
     friend class QQuickEventPoint;
     friend class QQuickWindowPrivate;
 };
 
+Q_DECLARE_OPERATORS_FOR_FLAGS(QQuickPointerHandler::GrabPermissions)
+
 QT_END_NAMESPACE
 
 QML_DECLARE_TYPE(QQuickPointerHandler)
diff --git a/src/quick/items/qquickevents.cpp b/src/quick/items/qquickevents.cpp
index 35ace7592f..10b656d111 100644
--- a/src/quick/items/qquickevents.cpp
+++ b/src/quick/items/qquickevents.cpp
@@ -765,10 +765,12 @@ QObject *QQuickEventPoint::exclusiveGrabber() const
 */
 void QQuickEventPoint::setExclusiveGrabber(QObject *grabber)
 {
-    if (QQuickPointerHandler *phGrabber = qmlobject_cast<QQuickPointerHandler *>(grabber))
+    if (QQuickPointerHandler *phGrabber = qmlobject_cast<QQuickPointerHandler *>(grabber)) {
         setGrabberPointerHandler(phGrabber, true);
-    else
-        setGrabberItem(static_cast<QQuickItem *>(grabber));
+    } else if (QQuickPointerHandler *existingPhGrabber = grabberPointerHandler()) {
+        if (existingPhGrabber->approveGrabTransition(this, grabber))
+            setGrabberItem(static_cast<QQuickItem *>(grabber));
+    }
 }
 
 /*!