/****************************************************************************
**
** 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: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$
**
****************************************************************************/

/*!
    \page qtquickhandlers-index.html
    \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
    \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.

    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

    \annotatedlist qtquick-input-handlers

    \section1 Key Features

    Some of the key features are:

    \list
        \li Handle keystrokes within the focused Item
        \li Handle gestures such as tapping or dragging regardless which device it comes from
        \li Handle gestures from different classes of devices in different ways
        \li Each Item can have unlimited Handlers
    \endlist

    \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

     \list
      \li \l{Qt Quick}
     \endlist
*/