doc: Improve the Input Handlers index page

- Document the exclusive/passive grab concepts better
- Mention gesturePolicy's impact on grab behavior in the TapHandler docs too
- More links
- Add a couple of snippets illustrating simple use cases with handlers
- Don't bother mentioning Qt.labs.handlers anymore

Task-number: QTBUG-68110
Change-Id: I5e6f538c2bc8cafef679f535a5248b218b4a8068
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit aade6857d12b2c9cd5552d25f4d084a5fcd25f7d)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

3 files changed, 133 insertions, 17 deletions

diff --git a/src/quick/doc/snippets/pointerHandlers/hoverTapKeyButton.qml b/src/quick/doc/snippets/pointerHandlers/hoverTapKeyButton.qml
new file mode 100644
index 0000000000..1564aa16b5
--- /dev/null
+++ b/src/quick/doc/snippets/pointerHandlers/hoverTapKeyButton.qml
@@ -0,0 +1,73 @@
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+//![0]
+import QtQuick 2.12
+
+Rectangle {
+    id: button
+    signal clicked
+
+    width: 150; height: 50; radius: 3
+    color: tapHandler.pressed ? "goldenrod" : hoverHandler.hovered ? "wheat" : "beige"
+    border.color: activeFocus ? "brown" : "transparent"
+    focus: true
+
+    HoverHandler {
+        id: hoverHandler
+    }
+
+    TapHandler {
+        id: tapHandler
+        onTapped: button.clicked()
+    }
+
+    Keys.onEnterPressed: button.clicked()
+}
+//![0]
diff --git a/src/quick/doc/src/concepts/inputhandlers/qtquickhandlers-index.qdoc b/src/quick/doc/src/concepts/inputhandlers/qtquickhandlers-index.qdoc
index 2ac9860e6f..bf889a9066 100644
--- a/src/quick/doc/src/concepts/inputhandlers/qtquickhandlers-index.qdoc
+++ b/src/quick/doc/src/concepts/inputhandlers/qtquickhandlers-index.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2018 The Qt Company Ltd.
+** Copyright (C) 2021 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -30,20 +30,21 @@
     \title Qt Quick Input Handlers
     \brief A module with a set of QML elements that handle events from input devices in a user interface.
 
-    Qt Quick Input Handlers are a set of QML types used to handle events from
-    keyboard, touch, mouse, and stylus devices in a UI. In contrast to event-handling
-    items, such as \l MouseArea and \l Flickable, input handlers are explicitly non-visual,
-    require less memory and are intended to be used in greater numbers: one
-    handler instance per aspect of interaction. Each input handler instance
-    handles certain events on behalf of its \c parent Item. Thus the visual and
+    Qt Quick Input Handlers are a set of QML types used to handle
+    \l {QInputEvent}{events} from keyboard, touch, mouse, and stylus
+    \l {QInputDevice}{devices} in a UI. In contrast to event-handling
+    items, such as \l MouseArea and \l Flickable, input handlers are explicitly
+    non-visual, require less memory and are intended to be used in greater
+    numbers: one handler instance per aspect of interaction. Each input handler
+    instance handles certain events on behalf of its
+    \l {QQuickPointerHandler::parent()}{parent} Item. Thus the visual and
     behavioral concerns are better separated, and the behavior is built up by
     finer-grained composition.
 
-    In Qt 5.10, these handlers were introduced in a separate Qt.labs.handlers module.
-    Now they are included with Qt Quick since 5.12.  The pre-existing
-    \l Keys attached property is similar in concept, so we refer to the
-    pointing-device-oriented handlers plus \c Keys together as the set of Input Handlers.
-    We expect to offer more attached-property use cases in future versions of Qt.
+    The pre-existing \l Keys attached property is similar in concept, so we
+    refer to the pointing-device-oriented handlers plus \c Keys together as the
+    set of Input Handlers. We expect to offer more attached-property use cases
+    in future versions of Qt.
 
     \section1 Input Handlers
 
@@ -60,7 +61,44 @@
         \li Each Item can have unlimited Handlers
     \endlist
 
-    \omit TODO actual overview with snippets and stuff \endomit
+    \section1 Handlers Manipulating Items
+
+    Some Handlers add interactivity simply by being declared inside an Item:
+
+    \snippet pointerHandlers/dragHandler.qml 0
+
+    \section1 Handler Properties and Signals
+
+    All Handlers have properties that can be used in bindings, and signals that
+    can be handled to react to input:
+
+    \snippet pointerHandlers/hoverTapKeyButton.qml 0
+
+    \section1 Pointer Grab
+
+    An important concept with Pointer Handlers is the type of grabs that they
+    perform. The only kind of grab an Item can take is the exclusive grab: for
+    example if you call \l QPointerEvent::setExclusiveGrabber(), the following
+    mouse moves and mouse release event will be sent only to that object. (As a
+    workaround to this exclusivity, see \l QQuickItem::setFiltersChildMouseEvents()
+    and \l QQuickItem::childMouseEventFilter().) However Pointer Handlers have
+    an additional mechanism available: the
+    \l {QPointerEvent::addPassiveGrabber()} {passive grab}. Mouse and touch
+    \l {QEventPoint::state()}{press} events are delivered by visiting all the
+    Items in top-down Z order: first each Item's child Handlers, and then the
+    \l {QQuickItem::event()}{Item} itself. At the time a press event is
+    delivered, a Handler can take either a passive or an exclusive grab
+    depending on its needs. If it takes a passive grab, it is guaranteed to
+    receive the updates and the release, even if other Items or Handlers in the
+    scene take any kind of grab, passive or exclusve. Some Handlers (such as
+    PointHandler) can work only with passive grabs; others require exclusive
+    grabs; and others can "lurk" with passive grabs until they detect that a
+    gesture is being performed, and then make the transition from passive to
+    exclusive grab.
+
+    When a grab transition is requested, \l PointerHandler::grabPermissions,
+    \l QQuickItem::keepMouseGrab() and \l QQuickItem::keepTouchGrab() control
+    whether the transition will be allowed.
 
     \section1 Related Information
 
diff --git a/src/quick/handlers/qquicktaphandler.cpp b/src/quick/handlers/qquicktaphandler.cpp
index 52e84aa649..04c9558e0a 100644
--- a/src/quick/handlers/qquicktaphandler.cpp
+++ b/src/quick/handlers/qquicktaphandler.cpp
@@ -209,6 +209,8 @@ void QQuickTapHandler::timerEvent(QTimerEvent *event)
     If the spatial constraint is violated, \l pressed transitions immediately
     from true to false, regardless of the time held.
 
+    The \c gesturePolicy also affects grab behavior as described below.
+
     \value TapHandler.DragThreshold
            (the default value) The event point must not move significantly.
            If the mouse, finger or stylus moves past the system-wide drag
@@ -217,11 +219,13 @@ void QQuickTapHandler::timerEvent(QTimerEvent *event)
            can be useful whenever TapHandler needs to cooperate with other
            input handlers (for example \l DragHandler) or event-handling Items
            (for example QtQuick Controls), because in this case TapHandler
-           will not take the exclusive grab, but merely a passive grab.
+           will not take the exclusive grab, but merely a
+           \l {QPointerEvent::addPassiveGrabber()}{passive grab}.
 
     \value TapHandler.WithinBounds
            If the event point leaves the bounds of the \c parent Item, the tap
-           gesture is canceled. The TapHandler will take the exclusive grab on
+           gesture is canceled. The TapHandler will take the
+           \l {QPointerEvent::setExclusiveGrabber}{exclusive grab} on
            press, but will release the grab as soon as the boundary constraint
            is no longer satisfied.
 
@@ -232,8 +236,9 @@ void QQuickTapHandler::timerEvent(QTimerEvent *event)
            typical behavior for button widgets: you can cancel a click by
            dragging outside the button, and you can also change your mind by
            dragging back inside the button before release. Note that it's
-           necessary for TapHandler take the exclusive grab on press and retain
-           it until release in order to detect this gesture.
+           necessary for TapHandler to take the
+           \l {QPointerEvent::setExclusiveGrabber}{exclusive grab} on press
+           and retain it until release in order to detect this gesture.
 */
 void QQuickTapHandler::setGesturePolicy(QQuickTapHandler::GesturePolicy gesturePolicy)
 {