Document the Pointer Handlers example

Animated gifs were captured with byzanz-record, then converted to webp:
gif2webp -lossy -min_size -q 40 -m 6 -mt -metadata none in.gif -o out.webp

Fixes: QTBUG-96915
Change-Id: Iee2f4ef774de7862d93c7e4cdf7b2b5e0553bec4
Reviewed-by: Oliver Eftevaag <oliver.eftevaag@qt.io>
Reviewed-by: Doris Verria <doris.verria@qt.io>
(cherry picked from commit 024794255d7d1df10fa5239cb70212c9703ff60f)
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>

20 files changed, 198 insertions, 8 deletions

diff --git a/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-fakeflickable.jpg b/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-fakeflickable.jpg
new file mode 100644
index 0000000000..5149665a07
--- /dev/null
+++ b/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-fakeflickable.jpg
diff --git a/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-fling.webp b/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-fling.webp
new file mode 100644
index 0000000000..4b8794971e
--- /dev/null
+++ b/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-fling.webp
diff --git a/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-joystick.jpg b/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-joystick.jpg
new file mode 100644
index 0000000000..c9d167b1e7
--- /dev/null
+++ b/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-joystick.jpg
diff --git a/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-map.webp b/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-map.webp
new file mode 100644
index 0000000000..b96b0cf90a
--- /dev/null
+++ b/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-map.webp
diff --git a/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-mixer.webp b/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-mixer.webp
new file mode 100644
index 0000000000..f263458d12
--- /dev/null
+++ b/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-mixer.webp
diff --git a/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-multibutton.webp b/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-multibutton.webp
new file mode 100644
index 0000000000..1d13805c64
--- /dev/null
+++ b/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-multibutton.webp
diff --git a/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-pinchhandler.webp b/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-pinchhandler.webp
new file mode 100644
index 0000000000..89f61251ab
--- /dev/null
+++ b/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-pinchhandler.webp
diff --git a/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-pointhandler.webp b/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-pointhandler.webp
new file mode 100644
index 0000000000..1a0ac33d0c
--- /dev/null
+++ b/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-pointhandler.webp
diff --git a/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-taphandler.webp b/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-taphandler.webp
new file mode 100644
index 0000000000..162e97ea15
--- /dev/null
+++ b/examples/quick/pointerhandlers/doc/images/pointerhandlers-example-taphandler.webp
diff --git a/examples/quick/pointerhandlers/doc/src/pointerhandlers.qdoc b/examples/quick/pointerhandlers/doc/src/pointerhandlers.qdoc
new file mode 100644
index 0000000000..7d19d47219
--- /dev/null
+++ b/examples/quick/pointerhandlers/doc/src/pointerhandlers.qdoc
@@ -0,0 +1,184 @@
+/****************************************************************************
+**
+** Copyright (C) 2023 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example pointerhandlers
+    \title Pointer Handlers Example
+    \ingroup qtquickexamples
+    \meta tags {quick, input handlers}
+    \brief Shows how to use \l {Qt Quick Input Handlers} in interactive components.
+
+    \l {Qt Quick Controls} contains pre-built components that are sufficient
+    for many kinds of user interfaces; but you may sometimes find a need to
+    write such components "from scratch". In that case, you will need to make
+    substantial use of Pointer Handlers. This is a collection of small examples
+    that show how to implement some common and less-common interaction patterns.
+
+    If you build the example as an executable, you can choose pages from a
+    top-level ListView. The \c TouchpointFeedbackSprite and \c MouseFeedbackSprite
+    components show how to use PointHandler to provide feedback about what the
+    user is doing with the pointing devices: these components are always
+    visible throughout the example, and do not interfere with interaction
+    anywhere else. These components are handy for reuse if you ever need to do
+    a video or live demonstration of a user interface.
+
+    Alternatively, some of the individual QML files can be run on the command
+    line with the \l {QML Runtime Tool}{qml tool}, as a quick reminder to see
+    how a particular kind of component can be built.
+
+    \section1 TapHandler
+
+    \image pointerhandlers-example-taphandler.webp
+
+    The "tap" page shows how to detect touchscreen taps, long-presses, and
+    mouse clicks with different buttons. You can also try out the different
+    \l {TapHandler::}{gesturePolicy} values.
+
+    \section2 Multi-tap Buttons
+
+    On this page are three custom \c Button components, with different
+    \l {TapHandler::}{gesturePolicy} values: one button requires you
+    to keep your finger or mouse within the button during the whole time
+    from press to release; one will execute even if you drag outside
+    the button and then drag back in before releasing; and one will
+    exit its pressed state if you drag a little past the
+    \l {QStyleHints::startDragDistance}{system-wide drag threshold}.
+    If you try this example on a touchscreen, you should be able to interact
+    with all three buttons at the same time with different fingers.
+
+    \image pointerhandlers-example-multibutton.webp
+
+    \section1 PointHandler
+
+    On the "single point handler" page, PointHandler provides feedback from
+    some of the properties that can be found in \l SinglePointHandler::point
+    and \l handlerPoint::device. If you have built the example as
+    an executable, you will see this feedback at the same time as the feedback
+    from the PointHandlers in the main pointerhandlers.qml file.
+
+    \image pointerhandlers-example-pointhandler.webp
+
+    The "tablet canvas" page uses PointHandler to uniquely detect different
+    \l {QPointingDevice::PointerType}{types of pointing devices}, so that if
+    you have a drawing tablet connected to your computer, you can draw on the
+    Canvas item with different types of stylus: pen, airbrush or marker. You
+    can "erase" strokes with the stylus eraser (done here by drawing on top
+    with the background color). Several \l {HoverHandler}{HoverHandlers}
+    provide feedback about which type of stylus or eraser is detected.
+
+    \section1 HoverHandler
+
+    The "hover sidebar" page shows how to detect when the mouse is hovering a
+    button component and its container at the same time. The propagation can be
+    disabled by setting the \l HoverHandler::blocking property. You can try out
+    all combinations of HoverHandler and MouseArea here, to compare how they
+    handle hover detection. And one more HoverHandler is used to show the
+    current mouse position in scene coordinates.
+
+    You can also verify that the HoverHandler on the animated "platform"
+    is hovered whenever it slides under the mouse cursor.
+
+    \section1 DragHandler
+
+    The "joystick" page simply has a \l DragHandler dragging an \l Image.
+    A \l State with \l AnchorChanges unlocks the \l anchors so that dragging is
+    possible; and an \l AnchorAnimation animates the knob's return to the
+    center position when released.
+
+    \image pointerhandlers-example-joystick.jpg
+
+    The "fling animation" page demonstrates one use of the
+    DragHandler::centroid::velocity property, which simply makes the value from
+    QEventPoint::velocity() available in QML. The \c MomentumAnimation component
+    that is used in this example shows one way to simulate phyics (momentum and
+    friction) without resorting to heavier solutions.
+
+    \image pointerhandlers-example-fling.webp
+
+    \section1 PinchHandler
+
+    The "pinch" page demonstrates multiple PinchHandlers: some require two
+    fingers and some require three, to perform the usual scaling, rotation and
+    translation, with constraints managed via PinchHandler's axis min and max
+    properties. One of the PinchHandler instances is used to manipulate
+    different \l Rectangle properties rather than position, scale and rotation.
+    Various PinchHandler properties are bound in various ways. You should be
+    able to manipulate each instance uniquely. Some items also have
+    DragHandlers and TapHandlers.
+
+    \image pointerhandlers-example-pinchhandler.webp
+
+    \section1 Interoperability
+
+    \section2 Sliders
+
+    The "mixer" page demonstrates the use of multiple handlers inside a
+    ListView delegate. You can interact with multiple \c Slider components
+    simultaneously, and you can flick the ListView sideways.
+
+    \list
+    \li A DragHandler allows you to start dragging anywhere along the "track"
+    where the slider knob can slide. Because the default \l{DragHandler::}{snapMode}
+    is \c DragHandler.SnapAuto, the knob will \e snap into a position centered
+    under the mouse or touchpoint after you have dragged past the
+    \l {QStyleHints::startDragDistance}{system-wide drag threshold}.
+
+    \li A WheelHandler directly adjusts the \c y property of the knob \l Image.
+
+    \li A BoundaryRule prevents either the DragHandler or the WheelHandler from
+    dragging the knob too far.
+
+    \li A TapHandler provides one more gesture than a typical \c Slider component
+    would have: you can tap on the knob.
+    \endlist
+
+    \image pointerhandlers-example-mixer.webp
+
+    \section2 Map
+
+    The "map" page demonstrates dragging, transformation and re-scaling an
+    \l {Qt SVG}{SVG} \l Image. You should be able to zoom into a particular
+    location on the map; and if the zoom level is changed substantially,
+    \l Image::sourceSize is changed to request the SVG to be re-rendered at a
+    different resolution. Dragging vertically with two fingers activates a
+    DragHandler that manipulates a \l Rotation transform to tilt the map.
+
+    \image pointerhandlers-example-map.webp
+
+    \section2 Fake Flickable
+
+    The "fake Flickable" page contains an attempt to reproduce much of the
+    functionality of \l Flickable using discrete pointer handlers and
+    animations. Flickable is a complex component, but here you can see one way
+    of separating the individual behaviors that it provides, in case you would
+    like to have only part of the functionality without the complexity.
+
+    There's also a slide-out "drawer" component holding a few more
+    pointer-handler-powered controls.
+
+    \image pointerhandlers-example-fakeflickable.jpg
+*/
diff --git a/src/labs/animation/qquickboundaryrule.cpp b/src/labs/animation/qquickboundaryrule.cpp
index d4a5be2c25..6b8a0fb400 100644
--- a/src/labs/animation/qquickboundaryrule.cpp
+++ b/src/labs/animation/qquickboundaryrule.cpp
@@ -146,7 +146,7 @@ void QQuickBoundaryReturnJob::updateState(QAbstractAnimationJob::State newState,
 
     Note that a property cannot have more than one assigned BoundaryRule.
 
-    \sa {Animation and Transitions in Qt Quick}, {Qt Quick Examples - Animation#Behaviors}{Behavior example}, {Qt QML}
+    \sa {Animation and Transitions in Qt Quick}, {Qt Quick Examples - Animation#Behaviors}{Behavior example}, {Qt QML}, {Pointer Handlers Example}
 */
 
 QQuickBoundaryRule::QQuickBoundaryRule(QObject *parent)
diff --git a/src/quick/doc/src/concepts/inputhandlers/qtquickhandlers-index.qdoc b/src/quick/doc/src/concepts/inputhandlers/qtquickhandlers-index.qdoc
index cca6b27ecf..7a05583a82 100644
--- a/src/quick/doc/src/concepts/inputhandlers/qtquickhandlers-index.qdoc
+++ b/src/quick/doc/src/concepts/inputhandlers/qtquickhandlers-index.qdoc
@@ -41,6 +41,8 @@
     behavioral concerns are better separated, and the behavior is built up by
     finer-grained composition.
 
+    The \l {Pointer Handlers Example} demonstrates some use cases for these.
+
     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
diff --git a/src/quick/handlers/qquickdraghandler.cpp b/src/quick/handlers/qquickdraghandler.cpp
index a689d2b216..79d0ecf990 100644
--- a/src/quick/handlers/qquickdraghandler.cpp
+++ b/src/quick/handlers/qquickdraghandler.cpp
@@ -88,7 +88,7 @@ Q_LOGGING_CATEGORY(lcDragHandler, "qt.quick.handler.drag")
 
     At this time, drag-and-drop is not yet supported.
 
-    \sa Drag, MouseArea
+    \sa Drag, MouseArea, {Pointer Handlers Example}
 */
 
 QQuickDragHandler::QQuickDragHandler(QQuickItem *parent)
diff --git a/src/quick/handlers/qquickhoverhandler.cpp b/src/quick/handlers/qquickhoverhandler.cpp
index d324f7f399..29ade6fdf8 100644
--- a/src/quick/handlers/qquickhoverhandler.cpp
+++ b/src/quick/handlers/qquickhoverhandler.cpp
@@ -67,7 +67,7 @@ Q_LOGGING_CATEGORY(lcHoverHandler, "qt.quick.handler.hover")
     The \l cursorShape property allows changing the cursor whenever
     \l hovered changes to \c true.
 
-    \sa MouseArea, PointHandler
+    \sa MouseArea, PointHandler, {Pointer Handlers Example}
 */
 
 QQuickHoverHandler::QQuickHoverHandler(QQuickItem *parent)
diff --git a/src/quick/handlers/qquickpinchhandler.cpp b/src/quick/handlers/qquickpinchhandler.cpp
index b89291ba1e..c5e25eb145 100644
--- a/src/quick/handlers/qquickpinchhandler.cpp
+++ b/src/quick/handlers/qquickpinchhandler.cpp
@@ -92,7 +92,7 @@ Q_LOGGING_CATEGORY(lcPinchHandler, "qt.quick.handler.pinch")
     but if it's a disallowed number, it does not scale or rotate
     its \l target, and the \l active property remains \c false.
 
-    \sa PinchArea, QPointerEvent::pointCount(), QNativeGestureEvent::fingerCount()
+    \sa PinchArea, QPointerEvent::pointCount(), QNativeGestureEvent::fingerCount(), {Pointer Handlers Example}
 */
 
 QQuickPinchHandler::QQuickPinchHandler(QQuickItem *parent)
diff --git a/src/quick/handlers/qquickpointhandler.cpp b/src/quick/handlers/qquickpointhandler.cpp
index 67e47588c4..d6f0641a00 100644
--- a/src/quick/handlers/qquickpointhandler.cpp
+++ b/src/quick/handlers/qquickpointhandler.cpp
@@ -111,7 +111,7 @@ QT_BEGIN_NAMESPACE
     want to react to all the touchpoints but do not require the smooth
     native-gesture experience.
 
-    \sa MultiPointTouchArea
+    \sa MultiPointTouchArea, {Pointer Handlers Example}
 */
 
 QQuickPointHandler::QQuickPointHandler(QQuickItem *parent)
diff --git a/src/quick/handlers/qquicktaphandler.cpp b/src/quick/handlers/qquicktaphandler.cpp
index db124fb474..cbadab4fd3 100644
--- a/src/quick/handlers/qquicktaphandler.cpp
+++ b/src/quick/handlers/qquicktaphandler.cpp
@@ -84,7 +84,7 @@ int QQuickTapHandler::m_touchMultiTapDistanceSquared(-1);
     QStyleHints::touchDoubleTapDistance() with touch, and the time between
     taps must not exceed QStyleHints::mouseDoubleClickInterval().
 
-    \sa MouseArea
+    \sa MouseArea, {Pointer Handlers Example}
 */
 
 QQuickTapHandler::QQuickTapHandler(QQuickItem *parent)
@@ -292,6 +292,8 @@ void QQuickTapHandler::timerEvent(QTimerEvent *event)
             \snippet pointerHandlers/tapHandlerButtonReleaseWithinBounds.qml 1
     \endtable
 
+    The \l {Pointer Handlers Example} demonstrates some use cases for these.
+
     \note If you find that TapHandler is reacting in cases that conflict with
     some other behavior, the first thing you should try is to think about which
     \c gesturePolicy is appropriate. If you cannot fix it by changing \c gesturePolicy,
diff --git a/src/quick/handlers/qquickwheelhandler.cpp b/src/quick/handlers/qquickwheelhandler.cpp
index b3e7cf6b8e..d1de81e00f 100644
--- a/src/quick/handlers/qquickwheelhandler.cpp
+++ b/src/quick/handlers/qquickwheelhandler.cpp
@@ -81,7 +81,7 @@ Q_LOGGING_CATEGORY(lcWheelHandler, "qt.quick.handler.wheel")
     WheelHandler handles only a rotating mouse wheel by default; this
     can be changed by setting acceptedDevices.
 
-    \sa MouseArea, Flickable
+    \sa MouseArea, Flickable, {Pointer Handlers Example}
 */
 
 QQuickWheelHandler::QQuickWheelHandler(QQuickItem *parent)
diff --git a/src/quick/items/context2d/qquickcanvasitem.cpp b/src/quick/items/context2d/qquickcanvasitem.cpp
index 5800f47a23..bd65a84fc3 100644
--- a/src/quick/items/context2d/qquickcanvasitem.cpp
+++ b/src/quick/items/context2d/qquickcanvasitem.cpp
@@ -288,7 +288,7 @@ QQuickCanvasItemPrivate::~QQuickCanvasItemPrivate()
     QPainter instead of the more expensive and likely less performing
     JavaScript and Context2D approach.
 
-    \sa Context2D QQuickPaintedItem
+    \sa Context2D, QQuickPaintedItem, {Pointer Handlers Example}
 */
 
 QQuickCanvasItem::QQuickCanvasItem(QQuickItem *parent)
diff --git a/src/quick/items/qquickimage.cpp b/src/quick/items/qquickimage.cpp
index 8fafc7564a..50762b4b7b 100644
--- a/src/quick/items/qquickimage.cpp
+++ b/src/quick/items/qquickimage.cpp
@@ -494,6 +494,8 @@ qreal QQuickImage::paintedHeight() const
 
     \note \e {Changing this property dynamically causes the image source to be reloaded,
     potentially even from the network, if it is not in the disk cache.}
+
+    \sa {Pointer Handlers Example}
 */
 
 /*!