diff options
author | Mitch Curtis <mitch.curtis@qt.io> | 2021-07-13 15:49:40 +0200 |
---|---|---|
committer | Shawn Rutledge <shawn.rutledge@qt.io> | 2021-07-27 15:39:42 +0200 |
commit | 382d2bfe5f261c269ccf4b970c826003c90d57ae (patch) | |
tree | 3b7a26294547ce9a1113294000428043bc89785f | |
parent | 64777c3ed9dc66e3510ce2139538b93ad68e9fbb (diff) |
Doc: add example snippets for containmentMask
This shows how to use non-rectangular shapes for hit tests,
as well as how to define the contains function in QML.
Task-number: QTBUG-89380
Pick-to: 5.15 6.1 6.2
Change-Id: I93c686d840b292816a788c05a0a76fafa338d5f8
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>
-rw-r--r-- | src/quick/doc/images/containmentMask-circle.gif | bin | 0 -> 9926 bytes | |||
-rw-r--r-- | src/quick/doc/images/containmentMask-shape.gif | bin | 0 -> 11261 bytes | |||
-rw-r--r-- | src/quick/doc/snippets/qml/item/containmentMask-circle-js.qml | 71 | ||||
-rw-r--r-- | src/quick/doc/snippets/qml/item/containmentMask-shape.qml | 80 | ||||
-rw-r--r-- | src/quick/items/qquickitem.cpp | 24 |
5 files changed, 171 insertions, 4 deletions
diff --git a/src/quick/doc/images/containmentMask-circle.gif b/src/quick/doc/images/containmentMask-circle.gif Binary files differnew file mode 100644 index 0000000000..80abce625f --- /dev/null +++ b/src/quick/doc/images/containmentMask-circle.gif diff --git a/src/quick/doc/images/containmentMask-shape.gif b/src/quick/doc/images/containmentMask-shape.gif Binary files differnew file mode 100644 index 0000000000..e7989352eb --- /dev/null +++ b/src/quick/doc/images/containmentMask-shape.gif diff --git a/src/quick/doc/snippets/qml/item/containmentMask-circle-js.qml b/src/quick/doc/snippets/qml/item/containmentMask-circle-js.qml new file mode 100644 index 0000000000..2d97bcdafa --- /dev/null +++ b/src/quick/doc/snippets/qml/item/containmentMask-circle-js.qml @@ -0,0 +1,71 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +import QtQml 2.12 +import QtQuick 2.12 + +//![0] +Rectangle { + id: circle + width: 100; height: width + radius: width / 2 + color: tapHandler.pressed ? "tomato" : hoverHandler.hovered ? "darkgray" : "lightgray" + + TapHandler { id: tapHandler } + HoverHandler { id: hoverHandler } + + containmentMask: QtObject { + property alias radius: circle.radius + function contains(point: point) : bool { + return (Math.pow(point.x - radius, 2) + Math.pow(point.y - radius, 2)) < Math.pow(radius, 2) + } + } +} +//![0] diff --git a/src/quick/doc/snippets/qml/item/containmentMask-shape.qml b/src/quick/doc/snippets/qml/item/containmentMask-shape.qml new file mode 100644 index 0000000000..a3da217e73 --- /dev/null +++ b/src/quick/doc/snippets/qml/item/containmentMask-shape.qml @@ -0,0 +1,80 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +import QtQuick 2.12 +import QtQuick.Shapes 1.12 + +//![0] +Rectangle { + width: 90; height: 100 + color: hoverHandler.hovered ? "wheat" : "lightgray" + containmentMask: shape + + HoverHandler { id: hoverHandler } + + Shape { + id: shape + containsMode: Shape.FillContains + + ShapePath { + fillColor: "lightsteelblue" + startX: 10; startY: 20 + PathArc { + x: 10; y: 80 + radiusX: 40; radiusY: 40 + useLargeArc: true + } + PathLine { + x: 10; y: 20 + } + } + } +} +//![0] diff --git a/src/quick/items/qquickitem.cpp b/src/quick/items/qquickitem.cpp index 253ed09821..cdaf4773f1 100644 --- a/src/quick/items/qquickitem.cpp +++ b/src/quick/items/qquickitem.cpp @@ -8118,10 +8118,26 @@ bool QQuickItem::contains(const QPointF &point) const \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). + A \l Shape can be used as a mask, to make an item react to + \l {QPointerEvent}{pointer events} only within a non-rectangular region: + + \table + \row + \li \image containmentMask-shape.gif + \li \snippet qml/item/containmentMask-shape.qml 0 + \endtable + + It is also possible to define the contains method in QML. For example, + to create a circular item that only responds to events within its + actual bounds: + + \table + \row + \li \image containmentMask-circle.gif + \li \snippet qml/item/containmentMask-circle-js.qml 0 + \endtable + + \sa {Qt Quick Examples - Shapes} */ /*! \property QQuickItem::containmentMask |