clarify further exclusive vs. passive grabs

Add documentation to the grab-related event and eventpoint methods.
Rename "grabber" functions which relate only to the exclusive grab,
in cases where it would otherwise be ambiguous.
And a few other documentation changes.

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

1 files changed, 9 insertions, 2 deletions

diff --git a/src/quick/items/qquickitem.cpp b/src/quick/items/qquickitem.cpp
index 9b91b4bda4..7adf455ac6 100644
--- a/src/quick/items/qquickitem.cpp
+++ b/src/quick/items/qquickitem.cpp
@@ -5091,7 +5091,14 @@ void QQuickItemPrivate::deliverShortcutOverrideEvent(QKeyEvent *event)
     }
 }
 
-bool QQuickItemPrivate::handlePointerEvent(QQuickPointerEvent *event, bool avoidGrabber)
+/*!
+    \internal
+    Deliver the \a event to all PointerHandlers which are in the pre-determined
+    eventDeliveryTargets() vector.  If \a avoidExclusiveGrabber is true, it skips
+    delivery to any handler which is the exclusive grabber of any point within this event
+    (because delivery to exclusive grabbers is handled separately).
+*/
+bool QQuickItemPrivate::handlePointerEvent(QQuickPointerEvent *event, bool avoidExclusiveGrabber)
 {
     Q_Q(QQuickItem);
     bool delivered = false;
@@ -5099,7 +5106,7 @@ bool QQuickItemPrivate::handlePointerEvent(QQuickPointerEvent *event, bool avoid
     if (extra.isAllocated()) {
         for (QQuickPointerHandler *handler : extra->pointerHandlers) {
             qCDebug(lcPointerHandlerDispatch) << "   delivering" << event << "to" << handler << "on" << q;
-            if ((!avoidGrabber || !event->hasGrabber(handler)) && !eventDeliveryTargets.contains(handler)) {
+            if ((!avoidExclusiveGrabber || !event->hasExclusiveGrabber(handler)) && !eventDeliveryTargets.contains(handler)) {
                 handler->handlePointerEvent(event);
                 delivered = true;
                 eventDeliveryTargets.append(handler);