104 lines
4.3 KiB
Diff
104 lines
4.3 KiB
Diff
From e203a185cfab199a89a33b903096d6d0023a8a88 Mon Sep 17 00:00:00 2001
|
|
From: Shawn Rutledge <shawn.rutledge@qt.io>
|
|
Date: Wed, 30 Sep 2020 13:51:59 +0200
|
|
Subject: [PATCH 24/28] 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>
|
|
---
|
|
src/quick/items/qquickitem.cpp | 34 +++++++++++++++++++++++++++++-----
|
|
1 file 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
|
|
**
|
|
** $QT_BEGIN_LICENSE:LGPL$
|
|
** Commercial License Usage
|
|
@@ -1883,7 +1883,23 @@ 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 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)
|
|
{
|
|
Q_D(QQuickItem);
|
|
--
|
|
2.31.1
|
|
|