1// Copyright (C) 2021 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \page qtquickhandlers-index.html
6 \title Qt Quick Input Handlers
7 \brief A module with a set of QML elements that handle events from input devices in a user interface.
9 Qt Quick Input Handlers are a set of QML types used to handle
10 \l {QInputEvent}{events} from keyboard, touch, mouse, and stylus
11 \l {QInputDevice}{devices} in a UI. In contrast to event-handling
12 items, such as \l MouseArea and \l Flickable, input handlers are explicitly
13 non-visual, require less memory and are intended to be used in greater
14 numbers: one handler instance per aspect of interaction. Each input handler
15 instance handles certain events on behalf of its
16 \l {QQuickPointerHandler::parent()}{parent} Item. Thus the visual and
17 behavioral concerns are better separated, and the behavior is built up by
18 finer-grained composition.
20 The \l {Qt Quick Examples - Pointer Handlers} demonstrates some use cases for these.
22 The pre-existing \l Keys attached property is similar in concept, so we
23 refer to the pointing-device-oriented handlers plus \c Keys together as the
24 set of Input Handlers. We expect to offer more attached-property use cases
25 in future versions of Qt.
27 \section1 Input Handlers
29 \annotatedlist qtquick-input-handlers
31 \section1 Key Features
33 Some of the key features are:
36 \li Handle keystrokes within the focused Item
37 \li Handle gestures such as tapping or dragging regardless which device it comes from
38 \li Handle gestures from different classes of devices in different ways
39 \li Each Item can have unlimited Handlers
42 \section1 Handlers Manipulating Items
44 Some Handlers add interactivity simply by being declared inside an Item:
46 \snippet pointerHandlers/dragHandler.qml 0
48 \section1 Handler Properties and Signals
50 All Handlers have properties that can be used in bindings, and signals that
51 can be handled to react to input:
53 \snippet pointerHandlers/hoverTapKeyButton.qml 0
55 \section1 Pointer Grab
57 An important concept with Pointer Handlers is the type of grabs that they
58 perform. The only kind of grab an Item can take is the exclusive grab: for
59 example if you call \l QPointerEvent::setExclusiveGrabber(), the following
60 mouse moves and mouse release event will be sent only to that object. (As a
61 workaround to this exclusivity, see \l QQuickItem::setFiltersChildMouseEvents()
62 and \l QQuickItem::childMouseEventFilter().) However Pointer Handlers have
63 an additional mechanism available: the
64 \l {QPointerEvent::addPassiveGrabber()} {passive grab}. Mouse and touch
65 \l {QEventPoint::state()}{press} events are delivered by visiting all the
66 Items in top-down Z order: first each Item's child Handlers, and then the
67 \l {QQuickItem::event()}{Item} itself. At the time a press event is
68 delivered, a Handler can take either a passive or an exclusive grab
69 depending on its needs. If it takes a passive grab, it is guaranteed to
70 receive the updates and the release, even if other Items or Handlers in the
71 scene take any kind of grab, passive or exclusve. Some Handlers (such as
72 PointHandler) can work only with passive grabs; others require exclusive
73 grabs; and others can "lurk" with passive grabs until they detect that a
74 gesture is being performed, and then make the transition from passive to
75 exclusive grab. TapHandler's grabbing behavior is
76 \l {TapHandler::gesturePolicy}{configurable}.
78 When a grab transition is requested, \l PointerHandler::grabPermissions,
79 \l QQuickItem::keepMouseGrab() and \l QQuickItem::keepTouchGrab() control
80 whether the transition will be allowed.
82 \section1 Related Information
1.10.0