PointHandler: fix and improve the docs

The qml module tag did not make it clear that it's in Qt.labs.handlers,
not officially part of QtQuick yet.

Some features needed better explanations.  A snippet is helpful.

Change-Id: Ie6a57510390bb376f20f5c1d98d8fc4c148af71b
Reviewed-by: Jan Arve Sæther <jan-arve.saether@qt.io>

2 files changed, 131 insertions, 25 deletions

diff --git a/src/quick/doc/snippets/pointerHandlers/pointHandler.qml b/src/quick/doc/snippets/pointerHandlers/pointHandler.qml
new file mode 100644
index 0000000000..262eb607b6
--- /dev/null
+++ b/src/quick/doc/snippets/pointerHandlers/pointHandler.qml
@@ -0,0 +1,79 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 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$
+**
+****************************************************************************/
+//![0]
+import QtQuick 2.10
+import QtQuick.Window 2.2
+import Qt.labs.handlers 1.0
+
+Window {
+    width: 480
+    height: 320
+    visible: true
+
+    Item {
+        id: glassPane
+        z: 10000
+        anchors.fill: parent
+
+        PointHandler {
+            id: handler
+            acceptedDevices: PointerDevice.TouchScreen | PointerDevice.TouchPad
+            target: Rectangle {
+                parent: glassPane
+                color: "red"
+                visible: handler.active
+                x: handler.point.position.x - width / 2
+                y: handler.point.position.y - height / 2
+                width: 20; height: width; radius: width / 2
+            }
+        }
+    }
+}
+//![0]
diff --git a/src/quick/handlers/qquickpointhandler.cpp b/src/quick/handlers/qquickpointhandler.cpp
index d40837c43e..ed03685252 100644
--- a/src/quick/handlers/qquickpointhandler.cpp
+++ b/src/quick/handlers/qquickpointhandler.cpp
@@ -46,40 +46,67 @@ QT_BEGIN_NAMESPACE
 /*!
     \qmltype PointHandler
     \instantiates QQuickPointHandler
-    \inqmlmodule QtQuick
+    \inherits SinglePointHandler
+    \inqmlmodule Qt.labs.handlers
     \ingroup qtquick-handlers
-    \brief Handler for reacting to a single touchpoint
+    \brief Handler for reacting to a single touchpoint.
 
     PointHandler can be used to show feedback about a touchpoint or the mouse
-    position, or to otherwise react to pointer events. By being only a passive
-    grabber, it has the ability to keep oversight of all movements, and its
-    grab cannot be stolen even when other gestures are detected and exclusive
-    grabs occur.
+    position, or to otherwise react to pointer events.
+
+    When a press event occurs, each instance of PointHandler chooses a single
+    point which is not yet "taken" at that moment: if the press occurs within
+    the bounds of the \l parent, and no sibling PointHandler within the same
+    \l parent has yet acquired a passive grab on that point, and if the other
+    constraints such as \l acceptedMouseButtons, \l acceptedDevices etc. are
+    satisfied, it's eligible, and the PointHandler then acquires a passive
+    grab. In this way, the \l parent acts like an exclusive group: there can be
+    multiple instances of PointHandler, and the set of pressed touchpoints will
+    be distributed among them. Each PointHandler which has chosen a point to
+    track has its \l active property \c true. It then continues to track its
+    chosen point until release: the properties of the \l point will be kept
+    up-to-date. Any Item can bind to these properties, and thereby follow the
+    point's movements.
+
+    By being only a passive grabber, it has the ability to keep independent
+    oversight of all movements. The passive grab cannot be stolen or overridden
+    even when other gestures are detected and exclusive grabs occur.
 
     If your goal is orthogonal surveillance of eventpoints, an older
     alternative was QObject::installEventFilter(), but that has never been a
-    built-in QtQuick feature: it requires a custom C++ QQuickItem subclass.
-    PointHandler is more efficient than that, because only pointer events will
-    be delivered to it, during the course of normal event delivery in
-    QQuickWindow, whereas an event filter needs to filter all events of all
+    built-in QtQuick feature: it requires some C++ code, such as a QQuickItem
+    subclass. PointHandler is more efficient than that, because only pointer
+    events will be delivered to it, during the course of normal event delivery
+    in QQuickWindow; whereas an event filter needs to filter all QEvents of all
     types, and thus sets itself up as a potential event delivery bottleneck.
 
     One possible use case is to add this handler to a transparent Item which is
-    on top of the rest of the scene, so that when a point is freshly pressed,
-    it will be delivered to that Item and its handlers first, providing the
-    opportunity to take the passive grab as early as possible. Then such an
-    item (like a pane of glass over the whole UI) also becomes a good parent
-    for other Items which visualize the kind of reactive feedback which must
-    always be on top; and likewise it can be the parent for popups, popovers,
-    dialogs and so on. For example, a declared Window can have an Item with a
-    high Z value so that it stays on top. It can also be helpful for your
-    main.cpp to use QQmlContext::setContextProperty() to make the "glass pane"
-    accessible by ID to the entire UI, so that other Items and PointHandlers
-    can be reparented to it.
-
-    Inside a PointHandler you can declare a \l target Item, but PointHandler
-    will not automatically manipulate it in any way. The target Item can bind to
-    properties of the PointHandler. In this way it can follow a point's movements.
+    on top of the rest of the scene (by having a high \l z value), so that when
+    a point is freshly pressed, it will be delivered to that Item and its
+    handlers first, providing the opportunity to take the passive grab as early
+    as possible. Such an item (like a pane of glass over the whole UI) can be a
+    convenient parent for other Items which visualize the kind of reactive
+    feedback which must always be on top; and likewise it can be the parent for
+    popups, popovers, dialogs and so on. If it will be used in that way, it can
+    be helpful for your main.cpp to use QQmlContext::setContextProperty() to
+    make the "glass pane" accessible by ID to the entire UI, so that other
+    Items and PointHandlers can be reparented to it.
+
+    \snippet pointerHandlers/pointHandler.qml 0
+
+    Like all pointer handlers, a PointHandler has a \l target property, which
+    may be used as a convenient place to put a point-tracking Item; but
+    PointHandler will not automatically manipulate the \c target item in any way.
+    You need to use bindings to make it react to the \l point.
+
+    \note On macOS, PointHandler does not react to the trackpad by default.
+    That is because macOS can provide either native gesture recognition, or raw
+    touchpoints, but not both. We prefer to use the native gesture event in
+    PinchHandler, so we do not want to disable it by enabling touch. However
+    MultiPointTouchArea does enable touch, thus disabling native gesture
+    recognition within the entire window; so it's an alternative if you only
+    want to react to all the touchpoints but do not require the smooth
+    native-gesture experience.
 
     \sa MultiPointTouchArea
 */