1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \page gestures-overview.html
6 \title Gestures in Widgets and Graphics View
7 \startpage index.html Qt Reference Documentation
8 \ingroup qt-gui-concepts
10 \brief An overview of Qt support for Gesture programming
12 Qt includes a framework for gesture programming that has the ability
13 to form gestures from a series of events, independently of the input methods
14 used. A gesture could be a particular movement of a mouse, a touch screen
15 action, or a series of events from some other source. The nature of the input,
16 the interpretation of the gesture and the action taken are the choice of the
23 QGesture is the central class in Qt's gesture framework, providing a container
24 for information about gestures performed by the user. QGesture exposes
25 properties that give general information that is common to all gestures, and
26 these can be extended to provide additional gesture-specific information.
27 Common panning, pinching and swiping gestures are represented by specialized
28 classes: QPanGesture, QPinchGesture and QSwipeGesture.
30 Developers can also implement new gestures by subclassing and extending the
31 QGestureRecognizer class. Adding support for a new gesture involves implementing
32 code to recognize the gesture from input events. This is described in the
33 \l{Creating Your Own Gesture Recognizer} section.
35 \section1 Using Standard Gestures with Widgets
37 Gestures can be enabled for instances of QWidget and QGraphicsObject subclasses.
38 An object that accepts gesture input is referred to throughout the documentation
39 as a \e{target object}.
41 To enable a gesture for a target object, call its QWidget::grabGesture() or
42 QGraphicsObject::grabGesture() function with an argument describing the
43 required gesture type. The standard types are defined by the Qt::GestureType
44 enum and include many commonly used gestures.
46 \snippet gestures/imagegestures/imagewidget.cpp enable gestures
48 In the above code, the gestures are set up in the constructor of the target object
51 \section1 Handling Events
53 When the user performs a gesture, QGestureEvent events will be delivered to the
54 target object, and these can be handled by reimplementing the QWidget::event()
55 handler function for widgets or QGraphicsItem::sceneEvent() for graphics objects.
57 As one target object can subscribe to more than one gesture type, the QGestureEvent
58 can contain more than one QGesture, indicating several possible gestures are active
59 at the same time. It is then up to the widget to determine how to handle those
60 multiple gestures and choose if some should be canceled in favor of others.
62 Each QGesture contained within a QGestureEvent object can be accepted() or ignored()
63 individually, or all together. Additionally, you can query the individual QGesture
64 data objects (the state) using several getters.
66 \section2 Standard Procedure for Event Handling
68 A QGesture is by default accepted when it arrives at your widget. However, it is good
69 practice to always explicitly accept or reject a gesture. The general rule is that, if
70 you accept a gesture, you are using it. If you are ignoring it you are not interested
71 in it. Ignoring a gesture may mean it gets offered to another target object, or it will
74 Each QGesture has several states it goes through; there is a well defined way to change
75 the state, typically the user input is the cause of state changes (by starting and
76 stopping interaction, for instance) but the widget can also cause state changes.
78 The first time a particular QGesture is delivered to a widget or graphics item, it will
79 be in the Qt::GestureStarted state. The way you handle the gesture at this point
80 influences whether you can interact with it later.
83 \li Accepting the gesture means the widget acts on the gesture and there will follow
84 gestures with the Qt::GestureUpdatedstate.
85 \li Ignoring the gesture will mean the gesture will never be offered to you again.
86 It will be offered to a parent widget or item as well.
87 \li Calling setGestureCancelPolicy() on the gesture when it is in its starting state,
88 and is also accepted can cause other gestures to be canceled.
91 Using QGesture::CancelAllInContext to cancel a gesture will cause all gestures, in any
92 state, to be canceled unless they are explicitly accepted. This means that active
93 gestures on children will get canceled. It also means that gestures delivered in the
94 same QGestureEvent will get canceled if the widget ignores them. This can be a useful
95 way to filter out all gestures except the one you are interested in.
97 \section2 Example Event Handling
99 For convenience, the \l{Image Gestures Example} reimplements the general
100 \l{QWidget::}{event()} handler function and delegates gesture events to a
101 specialized gestureEvent() function:
103 \snippet gestures/imagegestures/imagewidget.cpp event handler
105 The gesture events delivered to the target object can be examined individually
106 and dealt with appropriately:
108 \snippet gestures/imagegestures/imagewidget.cpp gesture event handler
110 Responding to a gesture is simply a matter of obtaining the QGesture object
111 delivered in the QGestureEvent sent to the target object and examining the
112 information it contains.
114 \snippet gestures/imagegestures/imagewidget.cpp swipe function
116 Here, we examine the direction in which the user swiped the widget and modify
117 its contents accordingly.
120 \section1 Creating Your Own Gesture Recognizer
122 Adding support for a new gesture involves creating and registering a new gesture
123 recognizer. Depending on the recognition process for the gesture, it may also
124 involve creating a new gesture object.
126 To create a new recognizer, you need to subclass QGestureRecognizer to create a
127 custom recognizer class. There is one virtual function that you must reimplement
128 and two others that can be reimplemented as required.
130 \section2 Filtering Input Events
132 The \l{QGestureRecognizer::}{recognize()} function must be reimplemented.
133 This function handles and filters the incoming input events for the target objects
134 and determines whether or not they correspond to the gesture the recognizer is
137 Although the logic for gesture recognition is implemented in this function,
138 possibly using a state machine based on the Qt::GestureState enums, you can store
139 persistent information about the state of the recognition process in the QGesture
142 Your \l{QGestureRecognizer::}{recognize()} function must return a value of
143 QGestureRecognizer::Result that indicates the state of recognition for a given gesture and
144 target object. This determines whether or not a gesture event will be delivered
147 \section2 Custom Gestures
149 If you choose to represent a gesture by a custom QGesture subclass, you will need to
150 reimplement the \l{QGestureRecognizer::}{create()} function to construct
151 instances of your gesture class instead of standard QGesture instances. Alternatively,
152 you may want to use standard QGesture instances, but add additional dynamic properties
153 to them to express specific details of the gesture you want to handle.
155 \section2 Resetting Gestures
157 If you use custom gesture objects that need to be reset or otherwise specially
158 handled when a gesture is canceled, you need to reimplement the
159 \l{QGestureRecognizer::}{reset()} function to perform these special tasks.
161 Note that QGesture objects are only created once for each combination of target object
162 and gesture type, and they might be reused every time the user attempts to perform the
163 same gesture type on the target object. As a result, it can be useful to reimplement
164 the \l{QGestureRecognizer::}{reset()} function to clean up after each previous attempt
165 at recognizing a gesture.
168 \section1 Using a New Gesture Recognizer
170 To use a gesture recognizer, construct an instance of your QGestureRecognizer
171 subclass, and register it with the application with
172 QGestureRecognizer::registerRecognizer(). A recognizer for a given type of
173 gesture can be removed with QGestureRecognizer::unregisterRecognizer().
176 \section1 Further Reading
178 The \l{gestures/imagegestures}{Image Gestures Example} shows how to enable
179 gestures for a widget in a simple image viewer application.
181 \section2 Gestures in Qt Quick
183 Qt Quick does not have a generic global gesture recognizer; rather, individual
184 components can respond to touch events in their own ways. For example
185 the \l PinchArea handles two-finger gestures, \l Flickable is for flicking
186 content with a single finger, and \l MultiPointTouchArea can handle an
187 arbitrary number of touch points and allow the application developer to
188 write custom gesture recognition code.
191// TODO mention Sensor Gestures when qtsensors becomes a maintained module
1.10.0