Add contains method to QQuickItem public API

This method can be overwritten in order to provide fine grained control
over the mouse events handled by the item.

Change-Id: I23cb61958d3ac0b2f5091c47fa9e0ed07dc5e5d0
Reviewed-by: Martin Jones <martin.jones@nokia.com>

9 files changed, 461 insertions, 0 deletions

diff --git a/examples/quick/maskedmousearea/images/cloud_1.png b/examples/quick/maskedmousearea/images/cloud_1.png
new file mode 100644
index 0000000000..87c54af253
--- /dev/null
+++ b/examples/quick/maskedmousearea/images/cloud_1.png
diff --git a/examples/quick/maskedmousearea/images/cloud_2.png b/examples/quick/maskedmousearea/images/cloud_2.png
new file mode 100644
index 0000000000..981bbd2630
--- /dev/null
+++ b/examples/quick/maskedmousearea/images/cloud_2.png
diff --git a/examples/quick/maskedmousearea/images/moon.png b/examples/quick/maskedmousearea/images/moon.png
new file mode 100644
index 0000000000..0a8037dd85
--- /dev/null
+++ b/examples/quick/maskedmousearea/images/moon.png
diff --git a/examples/quick/maskedmousearea/main.cpp b/examples/quick/maskedmousearea/main.cpp
new file mode 100644
index 0000000000..407497e640
--- /dev/null
+++ b/examples/quick/maskedmousearea/main.cpp
@@ -0,0 +1,57 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the examples of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** 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 Nokia Corporation and its Subsidiary(-ies) 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$
+**
+****************************************************************************/
+
+#include <QGuiApplication>
+#include <QQuickView>
+
+#include "maskedmousearea.h"
+
+
+int main(int argc, char* argv[])
+{
+    QGuiApplication app(argc,argv);
+    QQuickView view;
+
+    qmlRegisterType<MaskedMouseArea>("Example", 1, 0, "MaskedMouseArea");
+
+    view.setSource(QUrl::fromLocalFile("maskedmousearea.qml"));
+    view.show();
+    return app.exec();
+}
diff --git a/examples/quick/maskedmousearea/maskedmousearea.cpp b/examples/quick/maskedmousearea/maskedmousearea.cpp
new file mode 100644
index 0000000000..3f872a66f6
--- /dev/null
+++ b/examples/quick/maskedmousearea/maskedmousearea.cpp
@@ -0,0 +1,141 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the examples of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** 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 Nokia Corporation and its Subsidiary(-ies) 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$
+**
+****************************************************************************/
+
+#include "maskedmousearea.h"
+
+#include <QStyleHints>
+#include <QGuiApplication>
+
+
+MaskedMouseArea::MaskedMouseArea(QQuickItem *parent)
+    : QQuickItem(parent),
+      m_pressed(false),
+      m_alphaThreshold(0.0),
+      m_containsMouse(false)
+{
+    setAcceptHoverEvents(true);
+    setAcceptedMouseButtons(Qt::LeftButton);
+}
+
+void MaskedMouseArea::setPressed(bool pressed)
+{
+    if (m_pressed != pressed) {
+        m_pressed = pressed;
+        emit pressedChanged();
+    }
+}
+
+void MaskedMouseArea::setContainsMouse(bool containsMouse)
+{
+    if (m_containsMouse != containsMouse) {
+        m_containsMouse = containsMouse;
+        emit containsMouseChanged();
+    }
+}
+
+void MaskedMouseArea::setMaskSource(const QUrl &source)
+{
+    if (m_maskSource != source) {
+        m_maskSource = source;
+        m_maskImage = QImage(source.toLocalFile());
+        emit maskSourceChanged();
+    }
+}
+
+void MaskedMouseArea::setAlphaThreshold(qreal threshold)
+{
+    if (m_alphaThreshold != threshold) {
+        m_alphaThreshold = threshold;
+        emit alphaThresholdChanged();
+    }
+}
+
+bool MaskedMouseArea::contains(const QPointF &point) const
+{
+    if (!QQuickItem::contains(point) || m_maskImage.isNull())
+        return false;
+
+    QPoint p = point.toPoint();
+
+    if (p.x() < 0 || p.x() >= m_maskImage.width() ||
+        p.y() < 0 || p.y() >= m_maskImage.height())
+        return false;
+
+    qreal r = qBound<int>(0, m_alphaThreshold * 255, 255);
+    return qAlpha(m_maskImage.pixel(p)) > r;
+}
+
+void MaskedMouseArea::mousePressEvent(QMouseEvent *event)
+{
+    setPressed(true);
+    m_pressPoint = event->pos();
+    emit pressed();
+}
+
+void MaskedMouseArea::mouseReleaseEvent(QMouseEvent *event)
+{
+    setPressed(false);
+    emit released();
+
+    const int threshold = qApp->styleHints()->startDragDistance();
+    const bool isClick = (threshold >= qAbs(event->x() - m_pressPoint.x()) &&
+                          threshold >= qAbs(event->y() - m_pressPoint.y()));
+
+    if (isClick)
+        emit clicked();
+}
+
+void MaskedMouseArea::mouseUngrabEvent()
+{
+    setPressed(false);
+    emit canceled();
+}
+
+void MaskedMouseArea::hoverEnterEvent(QHoverEvent *event)
+{
+    Q_UNUSED(event);
+    setContainsMouse(true);
+}
+
+void MaskedMouseArea::hoverLeaveEvent(QHoverEvent *event)
+{
+    Q_UNUSED(event);
+    setContainsMouse(false);
+}
diff --git a/examples/quick/maskedmousearea/maskedmousearea.h b/examples/quick/maskedmousearea/maskedmousearea.h
new file mode 100644
index 0000000000..045d02d6f0
--- /dev/null
+++ b/examples/quick/maskedmousearea/maskedmousearea.h
@@ -0,0 +1,98 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the examples of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** 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 Nokia Corporation and its Subsidiary(-ies) 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$
+**
+****************************************************************************/
+
+#ifndef MASKEDMOUSEAREA_H
+#define MASKEDMOUSEAREA_H
+
+#include <QImage>
+#include <QQuickItem>
+
+
+class MaskedMouseArea : public QQuickItem
+{
+    Q_OBJECT
+    Q_PROPERTY(bool pressed READ isPressed NOTIFY pressedChanged)
+    Q_PROPERTY(bool containsMouse READ containsMouse NOTIFY containsMouseChanged)
+    Q_PROPERTY(QUrl maskSource READ maskSource WRITE setMaskSource NOTIFY maskSourceChanged)
+    Q_PROPERTY(qreal alphaThreshold READ alphaThreshold WRITE setAlphaThreshold NOTIFY alphaThresholdChanged)
+
+public:
+    MaskedMouseArea(QQuickItem *parent = 0);
+
+    bool contains(const QPointF &point) const;
+
+    bool isPressed() const { return m_pressed; }
+    bool containsMouse() const { return m_containsMouse; }
+
+    QUrl maskSource() const { return m_maskSource; }
+    void setMaskSource(const QUrl &source);
+
+    qreal alphaThreshold() const { return m_alphaThreshold; }
+    void setAlphaThreshold(qreal threshold);
+
+signals:
+    void pressed();
+    void released();
+    void clicked();
+    void canceled();
+    void pressedChanged();
+    void maskSourceChanged();
+    void containsMouseChanged();
+    void alphaThresholdChanged();
+
+protected:
+    void setPressed(bool pressed);
+    void setContainsMouse(bool containsMouse);
+    void mousePressEvent(QMouseEvent *event);
+    void mouseReleaseEvent(QMouseEvent *event);
+    void hoverEnterEvent(QHoverEvent *event);
+    void hoverLeaveEvent(QHoverEvent *event);
+    void mouseUngrabEvent();
+
+private:
+    bool m_pressed;
+    QUrl m_maskSource;
+    QImage m_maskImage;
+    QPointF m_pressPoint;
+    qreal m_alphaThreshold;
+    bool m_containsMouse;
+};
+
+#endif
diff --git a/examples/quick/maskedmousearea/maskedmousearea.pro b/examples/quick/maskedmousearea/maskedmousearea.pro
new file mode 100644
index 0000000000..53e14aaa4b
--- /dev/null
+++ b/examples/quick/maskedmousearea/maskedmousearea.pro
@@ -0,0 +1,14 @@
+TEMPLATE = app
+
+QT += quick qml
+
+HEADERS += maskedmousearea.h
+
+SOURCES += main.cpp \
+           maskedmousearea.cpp
+
+target.path = $$[QT_INSTALL_EXAMPLES]/qtdeclarative/qtquick/maskedmousearea
+qml.files = maskedmousearea.qml images
+qml.path = $$[QT_INSTALL_EXAMPLES]/qtdeclarative/qtquick/maskedmousearea
+INSTALLS += target qml
+
diff --git a/examples/quick/maskedmousearea/maskedmousearea.qml b/examples/quick/maskedmousearea/maskedmousearea.qml
new file mode 100644
index 0000000000..82d351b04f
--- /dev/null
+++ b/examples/quick/maskedmousearea/maskedmousearea.qml
@@ -0,0 +1,135 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the examples of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** 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 Nokia Corporation and its Subsidiary(-ies) 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.0
+import Example 1.0
+
+Rectangle {
+    height: 480
+    width: 320
+    color: "black"
+
+    Text {
+        text: qsTr("CLICK AND HOVER")
+        opacity: 0.6
+        color: "white"
+        font.pixelSize: 20
+        anchors.top: parent.top
+        anchors.horizontalCenter: parent.horizontalCenter
+        anchors.topMargin: 50
+    }
+
+    Image {
+        id: moon
+        smooth: true
+        anchors.centerIn: parent
+        scale: moonArea.pressed ? 1.1 : 1.0
+        opacity: moonArea.containsMouse ? 1.0 : 0.7
+        source: Qt.resolvedUrl("images/moon.png")
+
+        MaskedMouseArea {
+            id: moonArea
+            anchors.fill: parent
+            alphaThreshold: 0.4
+            maskSource: moon.source
+        }
+
+        Behavior on opacity {
+            NumberAnimation { duration: 200 }
+        }
+        Behavior on scale {
+            NumberAnimation { duration: 100 }
+        }
+    }
+
+    Image {
+        id: rightCloud
+        anchors {
+            centerIn: moon
+            verticalCenterOffset: 30
+            horizontalCenterOffset: 80
+        }
+        smooth: true
+        scale: rightCloudArea.pressed ? 1.1 : 1.0
+        opacity: rightCloudArea.containsMouse ? 1.0 : 0.7
+        source: Qt.resolvedUrl("images/cloud_2.png")
+
+        MaskedMouseArea {
+            id: rightCloudArea
+            anchors.fill: parent
+            alphaThreshold: 0.4
+            maskSource: rightCloud.source
+        }
+
+        Behavior on opacity {
+            NumberAnimation { duration: 200 }
+        }
+        Behavior on scale {
+            NumberAnimation { duration: 100 }
+        }
+    }
+
+    Image {
+        id: leftCloud
+        anchors {
+            centerIn: moon
+            verticalCenterOffset: 40
+            horizontalCenterOffset: -80
+        }
+        smooth: true
+        scale: leftCloudArea.pressed ? 1.1 : 1.0
+        opacity: leftCloudArea.containsMouse ? 1.0 : 0.7
+        source: Qt.resolvedUrl("images/cloud_1.png")
+
+        MaskedMouseArea {
+            id: leftCloudArea
+            anchors.fill: parent
+            alphaThreshold: 0.4
+            maskSource: leftCloud.source
+        }
+
+        Behavior on opacity {
+            NumberAnimation { duration: 200 }
+        }
+        Behavior on scale {
+            NumberAnimation { duration: 100 }
+        }
+    }
+}
diff --git a/examples/quick/maskedmousearea/maskedmousearea.qmlproject b/examples/quick/maskedmousearea/maskedmousearea.qmlproject
new file mode 100644
index 0000000000..709c19866f
--- /dev/null
+++ b/examples/quick/maskedmousearea/maskedmousearea.qmlproject
@@ -0,0 +1,16 @@
+import QmlProject 1.1
+
+Project {
+    mainFile: "maskedmousearea.qml"
+
+    /* Include .qml, .js, and image files from current directory and subdirectories */
+    QmlFiles {
+        directory: "."
+    }
+    JavaScriptFiles {
+        directory: "."
+    }
+    ImageFiles {
+        directory: "."
+    }
+}