diff options
authorShawn Rutledge <shawn.rutledge@qt.io>2020-09-30 13:51:59 +0200
committerShawn Rutledge <shawn.rutledge@qt.io>2021-01-04 18:03:52 +0000
commite203a185cfab199a89a33b903096d6d0023a8a88 (patch)
parent35614462443c100b6753b335b58a134fed4b5c35 (diff)
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: Shawn Rutledge <shawn.rutledge@qt.io>
1 files changed, 29 insertions, 5 deletions
diff --git a/src/quick/items/qquickitem.cpp b/src/quick/items/qquickitem.cpp
index ddd67522b9..e02df00595 100644
--- a/src/quick/items/qquickitem.cpp
+++ b/src/quick/items/qquickitem.cpp
@@ -1,9 +1,9 @@
-** 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.
+** This file is part of the QtQuick module of the Qt Toolkit.fset
** Commercial License Usage
@@ -1883,7 +1883,23 @@ void QQuickItemPrivate::updateSubFocusItem(QQuickItem *scope, bool focus)
- \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 all the event's touch points.
+ 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.
Key handling is available to all Item-based visual types via the \l Keys
attached property. The \e Keys attached property provides basic signals
@@ -7301,7 +7317,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);
@@ -7310,7 +7328,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)