improve documentation of PinchHandler

Change-Id: If7acf359731a046637248d9b415b9e865365a068
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>

5 files changed, 244 insertions, 12 deletions

diff --git a/src/quick/doc/images/touchpoints-pinchhandler.png b/src/quick/doc/images/touchpoints-pinchhandler.png
new file mode 100644
index 0000000000..1cf1393364
--- /dev/null
+++ b/src/quick/doc/images/touchpoints-pinchhandler.png
diff --git a/src/quick/doc/snippets/pointerHandlers/pinchHandler.qml b/src/quick/doc/snippets/pointerHandlers/pinchHandler.qml
new file mode 100644
index 0000000000..841e401da1
--- /dev/null
+++ b/src/quick/doc/snippets/pointerHandlers/pinchHandler.qml
@@ -0,0 +1,50 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation 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 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$
+**
+****************************************************************************/
+//![0]
+import QtQuick 2.8
+import Qt.labs.handlers 1.0
+
+Rectangle {
+    width: 400
+    height: 300
+    color: "lightsteelblue"
+    PinchHandler { }
+}
+//![0]
diff --git a/src/quick/doc/snippets/pointerHandlers/pinchHandlerDifferentTarget.qml b/src/quick/doc/snippets/pointerHandlers/pinchHandlerDifferentTarget.qml
new file mode 100644
index 0000000000..211c370da6
--- /dev/null
+++ b/src/quick/doc/snippets/pointerHandlers/pinchHandlerDifferentTarget.qml
@@ -0,0 +1,59 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation 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 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$
+**
+****************************************************************************/
+//![0]
+import QtQuick 2.8
+import Qt.labs.handlers 1.0
+
+Item {
+    width: 640
+    height: 480
+
+    Rectangle {
+        id: map
+        color: "aqua"
+        width: 400
+        height: 300
+    }
+
+    PinchHandler {
+        target: map
+    }
+}
+//![0]
diff --git a/src/quick/doc/snippets/pointerHandlers/pinchHandlerNullTarget.qml b/src/quick/doc/snippets/pointerHandlers/pinchHandlerNullTarget.qml
new file mode 100644
index 0000000000..b0139d7194
--- /dev/null
+++ b/src/quick/doc/snippets/pointerHandlers/pinchHandlerNullTarget.qml
@@ -0,0 +1,60 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation 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 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$
+**
+****************************************************************************/
+//![0]
+import QtQuick 2.8
+import Qt.labs.handlers 1.0
+
+Item {
+    width: 640
+    height: 480
+
+    PinchHandler {
+        id: handler
+        target: null
+    }
+
+    Text {
+        color: handler.active ? "darkgreen" : "black"
+        text: handler.rotation.toFixed(1) + " degrees\n" +
+              handler.translation.x.toFixed(1) + ", " + handler.translation.y.toFixed(1) + "\n" +
+              (handler.scale * 100).toFixed(1) + "%"
+    }
+}
+//![0]
diff --git a/src/quick/handlers/qquickpinchhandler.cpp b/src/quick/handlers/qquickpinchhandler.cpp
index 2cc5135147..3cd99fe1a2 100644
--- a/src/quick/handlers/qquickpinchhandler.cpp
+++ b/src/quick/handlers/qquickpinchhandler.cpp
@@ -55,11 +55,33 @@ Q_LOGGING_CATEGORY(lcPinchHandler, "qt.quick.handler.pinch")
 /*!
     \qmltype PinchHandler
     \instantiates QQuickPinchHandler
-    \inqmlmodule QtQuick
+    \inqmlmodule Qt.labs.handlers
     \ingroup qtquick-handlers
     \brief Handler for pinch gestures
 
-    PinchHandler is a handler that is used to interactively rotate and zoom an Item.
+    PinchHandler is a handler that interprets a multi-finger gesture to
+    interactively rotate, zoom, and drag an Item. Like other Pointer Handlers,
+    by default it is fully functional, and manipulates its \l target,
+    which is the Item within which it is declared.
+
+    \snippet pointerHandlers/pinchHandler.qml 0
+
+    It has properties to restrict the range of dragging, rotation, and zoom.
+
+    If it is declared within one Item but is assigned a different \l target, it
+    handles events within the bounds of the outer Item but manipulates the
+    \c target Item instead:
+
+    \snippet pointerHandlers/pinchHandlerDifferentTarget.qml 0
+
+    A third way to use it is to set \l target to \c null and react to property
+    changes in some other way:
+
+    \snippet pointerHandlers/pinchHandlerNullTarget.qml 0
+
+    \image touchpoints-pinchhandler.png
+
+    \sa PinchArea
 */
 
 QQuickPinchHandler::QQuickPinchHandler(QObject *parent)
@@ -85,6 +107,12 @@ QQuickPinchHandler::~QQuickPinchHandler()
 {
 }
 
+/*!
+    \qmlproperty real QtQuick::PinchHandler::minimumScale
+
+    The minimum acceptable \l {Item::scale}{scale} to be applied
+    to the \l target.
+*/
 void QQuickPinchHandler::setMinimumScale(qreal minimumScale)
 {
     if (m_minimumScale == minimumScale)
@@ -94,6 +122,12 @@ void QQuickPinchHandler::setMinimumScale(qreal minimumScale)
     emit minimumScaleChanged();
 }
 
+/*!
+    \qmlproperty real QtQuick::PinchHandler::maximumScale
+
+    The maximum acceptable \l {Item::scale}{scale} to be applied
+    to the \l target.
+*/
 void QQuickPinchHandler::setMaximumScale(qreal maximumScale)
 {
     if (m_maximumScale == maximumScale)
@@ -103,6 +137,12 @@ void QQuickPinchHandler::setMaximumScale(qreal maximumScale)
     emit maximumScaleChanged();
 }
 
+/*!
+    \qmlproperty real QtQuick::PinchHandler::minimumRotation
+
+    The minimum acceptable \l {Item::rotation}{rotation} to be applied
+    to the \l target.
+*/
 void QQuickPinchHandler::setMinimumRotation(qreal minimumRotation)
 {
     if (m_minimumRotation == minimumRotation)
@@ -112,6 +152,12 @@ void QQuickPinchHandler::setMinimumRotation(qreal minimumRotation)
     emit minimumRotationChanged();
 }
 
+/*!
+    \qmlproperty real QtQuick::PinchHandler::maximumRotation
+
+    The maximum acceptable \l {Item::rotation}{rotation} to be applied
+    to the \l target.
+*/
 void QQuickPinchHandler::setMaximumRotation(qreal maximumRotation)
 {
     if (m_maximumRotation == maximumRotation)
@@ -121,6 +167,20 @@ void QQuickPinchHandler::setMaximumRotation(qreal maximumRotation)
     emit maximumRotationChanged();
 }
 
+/*!
+    \qmlproperty real QtQuick::PinchHandler::pinchOrigin
+
+    The point to be held in place, around which the \l target is scaled and
+    rotated.
+
+    \value FirstPoint
+        the first touch point, wherever the first finger is pressed
+    \value PinchCenter
+        the centroid between all the touch points at the time when the
+        PinchHandler becomes \l active
+    \value TargetCenter
+        the center of the \l target
+*/
 void QQuickPinchHandler::setPinchOrigin(QQuickPinchHandler::PinchOrigin pinchOrigin)
 {
     if (m_pinchOrigin == pinchOrigin)
@@ -131,10 +191,10 @@ void QQuickPinchHandler::setPinchOrigin(QQuickPinchHandler::PinchOrigin pinchOri
 }
 
 /*!
-    \qmlproperty real QQuickPinchHandler::minimumX
+    \qmlproperty real QtQuick::PinchHandler::minimumX
 
     The minimum acceptable x coordinate of the centroid
- */
+*/
 void QQuickPinchHandler::setMinimumX(qreal minX)
 {
     if (m_minimumX == minX)
@@ -144,10 +204,10 @@ void QQuickPinchHandler::setMinimumX(qreal minX)
 }
 
 /*!
-    \qmlproperty real QQuickPinchHandler::maximumX
+    \qmlproperty real QtQuick::PinchHandler::maximumX
 
     The maximum acceptable x coordinate of the centroid
- */
+*/
 void QQuickPinchHandler::setMaximumX(qreal maxX)
 {
     if (m_maximumX == maxX)
@@ -157,10 +217,10 @@ void QQuickPinchHandler::setMaximumX(qreal maxX)
 }
 
 /*!
-    \qmlproperty real QQuickPinchHandler::minimumY
+    \qmlproperty real QtQuick::PinchHandler::minimumY
 
     The minimum acceptable y coordinate of the centroid
- */
+*/
 void QQuickPinchHandler::setMinimumY(qreal minY)
 {
     if (m_minimumY == minY)
@@ -170,10 +230,10 @@ void QQuickPinchHandler::setMinimumY(qreal minY)
 }
 
 /*!
-    \qmlproperty real QQuickPinchHandler::maximumY
+    \qmlproperty real QtQuick::PinchHandler::maximumY
 
     The maximum acceptable y coordinate of the centroid
- */
+*/
 void QQuickPinchHandler::setMaximumY(qreal maxY)
 {
     if (m_maximumY == maxY)
@@ -183,7 +243,7 @@ void QQuickPinchHandler::setMaximumY(qreal maxY)
 }
 
 /*!
-    \qmlproperty QQuickPinchHandler::minimumTouchPoints
+    \qmlproperty int QtQuick::PinchHandler::minimumTouchPoints
 
     The pinch begins when this number of fingers are pressed.
     Until then, PinchHandler tracks the positions of any pressed fingers,
@@ -192,7 +252,10 @@ void QQuickPinchHandler::setMaximumY(qreal maxY)
 */
 
 /*!
-    \qmlproperty QQuickPinchHandler::active
+    \qmlproperty bool QtQuick::PinchHandler::active
+
+    This property is true when all the constraints (epecially \l minimumTouchPoints)
+    are satisfied and the \l target, if any, is being manipulated.
 */
 
 void QQuickPinchHandler::onActiveChanged()