diff options
author | Shawn Rutledge <shawn.rutledge@qt.io> | 2021-07-13 15:36:31 +0200 |
---|---|---|
committer | Qt Cherry-pick Bot <cherrypick_bot@qt-project.org> | 2021-07-14 19:16:38 +0000 |
commit | 8cfdf56deba3da6bbbb0561224730e0d45d4b311 (patch) | |
tree | d2f840bd83add0831580c091f18d70d0110eab69 /src/quick/items/qquickitem.cpp | |
parent | 1ec362aa10149423aa1e71443d500dd87b39614f (diff) |
doc: Improve QQuickItem::containmentMask() docs
The Qt Quick docs weren't as explicit as possible; and the
\qmlproperty did not generate any C++ docs.
Amends bf74a908cb0591c2adc024a6f93d566c7348c125
Fixes: QTBUG-89375
Change-Id: Ib81796c1d7a00a7a48940c65137e4ed6a38a21ab
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>
(cherry picked from commit bcf3f29c6d26777c8db814477b8f3c3e19826234)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
Diffstat (limited to 'src/quick/items/qquickitem.cpp')
-rw-r--r-- | src/quick/items/qquickitem.cpp | 44 |
1 files changed, 35 insertions, 9 deletions
diff --git a/src/quick/items/qquickitem.cpp b/src/quick/items/qquickitem.cpp index f17b4110f9..dfc3ece60d 100644 --- a/src/quick/items/qquickitem.cpp +++ b/src/quick/items/qquickitem.cpp @@ -7868,22 +7868,48 @@ bool QQuickItem::contains(const QPointF &point) const \qmlproperty QObject* QtQuick::Item::containmentMask \since 5.11 This property holds an optional mask for the Item to be used in the - QtQuick::Item::contains method. - QtQuick::Item::contains main use is currently to determine whether - an input event has landed into the item or not. + QtQuick::Item::contains() method. Its main use is currently to determine + whether a \l {QPointerEvent}{pointer event} has landed into the item or not. By default the \l contains method will return true for any point - within the Item's bounding box. \c containmentMask allows for a - more fine-grained control. For example, the developer could - define and use an AnotherItem element as containmentMask, - which has a specialized contains method, like: + within the Item's bounding box. \c containmentMask allows for + more fine-grained control. For example, if a custom C++ + QQuickItem subclass with a specialized contains() method + is used as containmentMask: \code Item { id: item; containmentMask: AnotherItem { id: anotherItem } } \endcode - \e{item}'s contains method would then return true only if - \e{anotherItem}'s contains implementation returns true. + \e{item}'s contains method would then return \c true only if + \e{anotherItem}'s contains() implementation returns \c true. + + A \l Shape can be used in this way, to make an item react to + \l {QPointerEvent}{pointer events} only within a non-rectangular region, + as illustrated in the \l {Qt Quick Examples - Shapes}{Shapes example} + (see \c tapableTriangle.qml). +*/ +/*! + \property QQuickItem::containmentMask + \since 5.11 + This property holds an optional mask to be used in the contains() method, + which is mainly used for hit-testing each \l QPointerEvent. + + By default, \l contains() will return \c true for any point + within the Item's bounding box. But any QQuickItem, or any QObject + that implements a function of the form + \code + Q_INVOKABLE bool contains(const QPointF &point) const; + \endcode + can be used as a mask, to defer hit-testing to that object. + + \note contains() is called frequently during event delivery. + Deferring hit-testing to another object slows it down somewhat. + containmentMask() can cause performance problems if that object's + contains() method is not efficient. If you implement a custom + QQuickItem subclass, you can alternatively override contains(). + + \sa contains() */ QObject *QQuickItem::containmentMask() const { |