doc: explain QQItem event delivery, handlers, setAcceptTouchEvents()

We quietly recommended calling setAcceptTouchEvents() in the Qt 5.10
release notes in any Item subclass that wants to receive touch events,
and in the docs for setAcceptTouchEvents() itself; but the message about
the impending behavior change might not have been obvious enough.
In Qt 6 it becomes mandatory, so clearer docs will hopefully help to
stave off bogus bug reports.

We also never had a great overview of event handling from an Item's
perspective; now it's a little better.

Followup to ab91e7fa02a562d80fd0747f28a60e00c3b45a01 and
a97759a336c597327cb82eebc9f45c793aec32c9

[ChangeLog][QtQuick][QQuickItem] When subclassing QQuickItem, you
should call setAcceptTouchEvents(true) if you need the item to receive
touch events. It will be required in Qt 6.

Task-number: QTBUG-87018
Task-number: QTBUG-87082
Change-Id: I1c7a43979e3665778d61949c9d37c1d085ed594b
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
(cherry picked from commit 7c648280bb53c4276ba4ae2abf26d070fedde71a)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

1 files changed, 32 insertions, 4 deletions

diff --git a/src/quick/items/qquickitem.cpp b/src/quick/items/qquickitem.cpp
index ccd1168278..b5f58c7712 100644
--- a/src/quick/items/qquickitem.cpp
+++ b/src/quick/items/qquickitem.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2021 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the QtQuick module of the Qt Toolkit.
@@ -1887,7 +1887,27 @@ void QQuickItemPrivate::updateSubFocusItem(QQuickItem *scope, bool focus)
     \endqml
 
 
-    \section2 Key Handling
+    \section2 Event Handling
+
+    All Item-based visual types can use \l {Qt Quick Input Handlers}{Input Handlers}
+    to handle incoming input events (subclasses of QInputEvent), such as mouse,
+    touch and key events. This is the preferred declarative way to handle events.
+
+    An alternative way to handle touch events is to subclass QQuickItem, call
+    setAcceptTouchEvents() in the constructor, and override touchEvent().
+    \l {QEvent::setAccepted()}{Accept} the entire event to stop delivery to
+    items underneath, and to exclusively grab for all the event's touch points.
+    Use QPointerEvent::setExclusiveGrabber() to grab only certain touchpoints,
+    and allow the event to be delivered further.
+
+    Likewise, a QQuickItem subclass can call setAcceptedMouseButtons()
+    to register to receive mouse button events, setAcceptHoverEvents()
+    to receive hover events (mouse movements while no button is pressed),
+    and override the virtual functions mousePressEvent(), mouseMoveEvent(), and
+    mouseReleaseEvent(). Those can also accept the event to prevent further
+    delivery and get an implicit grab at the same time; or explicitly
+    \l {QPointerEvent::setExclusiveGrabber()}{grab} the single QEventPoint
+    that the QMouseEvent carries.
 
     Key handling is available to all Item-based visual types via the \l Keys
     attached property.  The \e Keys attached property provides basic signals
@@ -7318,7 +7338,9 @@ bool QQuickItem::isAncestorOf(const QQuickItem *child) const
     If an item does not accept the mouse button for a particular mouse event,
     the mouse event will not be delivered to the item and will be delivered
     to the next item in the item hierarchy instead.
-  */
+
+    \sa acceptTouchEvents()
+*/
 Qt::MouseButtons QQuickItem::acceptedMouseButtons() const
 {
     Q_D(const QQuickItem);
@@ -7327,7 +7349,13 @@ Qt::MouseButtons QQuickItem::acceptedMouseButtons() const
 
 /*!
     Sets the mouse buttons accepted by this item to \a buttons.
-  */
+
+    \note In Qt 5, calling setAcceptedMouseButtons() implicitly caused
+    an item to receive touch events as well as mouse events; but it was
+    recommended to call setAcceptTouchEvents() to subscribe for them.
+    In Qt 6, it is necessary to call setAcceptTouchEvents() to continue
+    to receive them.
+*/
 void QQuickItem::setAcceptedMouseButtons(Qt::MouseButtons buttons)
 {
     Q_D(QQuickItem);