Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
gestures.qdoc
Go to the documentation of this file.
1
// Copyright (C) 2016 The Qt Company Ltd.
2
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4
/*!
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
9
10
\brief An overview of Qt support for Gesture programming
11
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
17
developer.
18
19
\section1 Overview
20
21
QGesture is the central class in Qt's gesture framework, providing a container
22
for information about gestures performed by the user. QGesture exposes
23
properties that give general information that is common to all gestures, and
24
these can be extended to provide additional gesture-specific information.
25
Common panning, pinching and swiping gestures are represented by specialized
26
classes: QPanGesture, QPinchGesture and QSwipeGesture.
27
28
Developers can also implement new gestures by subclassing and extending the
29
QGestureRecognizer class. Adding support for a new gesture involves implementing
30
code to recognize the gesture from input events. This is described in the
31
\l{Creating Your Own Gesture Recognizer} section.
32
33
\section1 Using Standard Gestures with Widgets
34
35
Gestures can be enabled for instances of QWidget and QGraphicsObject subclasses.
36
An object that accepts gesture input is referred to throughout the documentation
37
as a \e{target object}.
38
39
To enable a gesture for a target object, call its QWidget::grabGesture() or
40
QGraphicsObject::grabGesture() function with an argument describing the
41
required gesture type. The standard types are defined by the Qt::GestureType
42
enum and include many commonly used gestures.
43
44
\snippet gestures/imagegestures/imagewidget.cpp enable gestures
45
46
In the above code, the gestures are set up in the constructor of the target object
47
itself.
48
49
\section1 Handling Events
50
51
When the user performs a gesture, QGestureEvent events will be delivered to the
52
target object, and these can be handled by reimplementing the QWidget::event()
53
handler function for widgets or QGraphicsItem::sceneEvent() for graphics objects.
54
55
As one target object can subscribe to more than one gesture type, the QGestureEvent
56
can contain more than one QGesture, indicating several possible gestures are active
57
at the same time. It is then up to the widget to determine how to handle those
58
multiple gestures and choose if some should be canceled in favor of others.
59
60
Each QGesture contained within a QGestureEvent object can be accepted() or ignored()
61
individually, or all together. Additionally, you can query the individual QGesture
62
data objects (the state) using several getters.
63
64
\section2 Standard Procedure for Event Handling
65
66
A QGesture is by default accepted when it arrives at your widget. However, it is good
67
practice to always explicitly accept or reject a gesture. The general rule is that, if
68
you accept a gesture, you are using it. If you are ignoring it you are not interested
69
in it. Ignoring a gesture may mean it gets offered to another target object, or it will
70
get canceled.
71
72
Each QGesture has several states it goes through; there is a well defined way to change
73
the state, typically the user input is the cause of state changes (by starting and
74
stopping interaction, for instance) but the widget can also cause state changes.
75
76
The first time a particular QGesture is delivered to a widget or graphics item, it will
77
be in the Qt::GestureStarted state. The way you handle the gesture at this point
78
influences whether you can interact with it later.
79
80
\list
81
\li Accepting the gesture means the widget acts on the gesture and there will follow
82
gestures with the Qt::GestureUpdatedstate.
83
\li Ignoring the gesture will mean the gesture will never be offered to you again.
84
It will be offered to a parent widget or item as well.
85
\li Calling setGestureCancelPolicy() on the gesture when it is in its starting state,
86
and is also accepted can cause other gestures to be canceled.
87
\endlist
88
89
Using QGesture::CancelAllInContext to cancel a gesture will cause all gestures, in any
90
state, to be canceled unless they are explicitly accepted. This means that active
91
gestures on children will get canceled. It also means that gestures delivered in the
92
same QGestureEvent will get canceled if the widget ignores them. This can be a useful
93
way to filter out all gestures except the one you are interested in.
94
95
\section2 Example Event Handling
96
97
For convenience, the \l{Image Gestures Example} reimplements the general
98
\l{QWidget::}{event()} handler function and delegates gesture events to a
99
specialized gestureEvent() function:
100
101
\snippet gestures/imagegestures/imagewidget.cpp event handler
102
103
The gesture events delivered to the target object can be examined individually
104
and dealt with appropriately:
105
106
\snippet gestures/imagegestures/imagewidget.cpp gesture event handler
107
108
Responding to a gesture is simply a matter of obtaining the QGesture object
109
delivered in the QGestureEvent sent to the target object and examining the
110
information it contains.
111
112
\snippet gestures/imagegestures/imagewidget.cpp swipe function
113
114
Here, we examine the direction in which the user swiped the widget and modify
115
its contents accordingly.
116
117
118
\section1 Creating Your Own Gesture Recognizer
119
120
Adding support for a new gesture involves creating and registering a new gesture
121
recognizer. Depending on the recognition process for the gesture, it may also
122
involve creating a new gesture object.
123
124
To create a new recognizer, you need to subclass QGestureRecognizer to create a
125
custom recognizer class. There is one virtual function that you must reimplement
126
and two others that can be reimplemented as required.
127
128
\section2 Filtering Input Events
129
130
The \l{QGestureRecognizer::}{recognize()} function must be reimplemented.
131
This function handles and filters the incoming input events for the target objects
132
and determines whether or not they correspond to the gesture the recognizer is
133
looking for.
134
135
Although the logic for gesture recognition is implemented in this function,
136
possibly using a state machine based on the Qt::GestureState enums, you can store
137
persistent information about the state of the recognition process in the QGesture
138
object supplied.
139
140
Your \l{QGestureRecognizer::}{recognize()} function must return a value of
141
QGestureRecognizer::Result that indicates the state of recognition for a given gesture and
142
target object. This determines whether or not a gesture event will be delivered
143
to a target object.
144
145
\section2 Custom Gestures
146
147
If you choose to represent a gesture by a custom QGesture subclass, you will need to
148
reimplement the \l{QGestureRecognizer::}{create()} function to construct
149
instances of your gesture class instead of standard QGesture instances. Alternatively,
150
you may want to use standard QGesture instances, but add additional dynamic properties
151
to them to express specific details of the gesture you want to handle.
152
153
\section2 Resetting Gestures
154
155
If you use custom gesture objects that need to be reset or otherwise specially
156
handled when a gesture is canceled, you need to reimplement the
157
\l{QGestureRecognizer::}{reset()} function to perform these special tasks.
158
159
Note that QGesture objects are only created once for each combination of target object
160
and gesture type, and they might be reused every time the user attempts to perform the
161
same gesture type on the target object. As a result, it can be useful to reimplement
162
the \l{QGestureRecognizer::}{reset()} function to clean up after each previous attempt
163
at recognizing a gesture.
164
165
166
\section1 Using a New Gesture Recognizer
167
168
To use a gesture recognizer, construct an instance of your QGestureRecognizer
169
subclass, and register it with the application with
170
QGestureRecognizer::registerRecognizer(). A recognizer for a given type of
171
gesture can be removed with QGestureRecognizer::unregisterRecognizer().
172
173
174
\section1 Further Reading
175
176
The \l{gestures/imagegestures}{Image Gestures Example} shows how to enable
177
gestures for a widget in a simple image viewer application.
178
179
\section2 Gestures in Qt Quick
180
181
Qt Quick does not have a generic global gesture recognizer; rather, individual
182
components can respond to touch events in their own ways. For example
183
the \l PinchArea handles two-finger gestures, \l Flickable is for flicking
184
content with a single finger, and \l MultiPointTouchArea can handle an
185
arbitrary number of touch points and allow the application developer to
186
write custom gesture recognition code.
187
*/
188
189
// TODO mention Sensor Gestures when qtsensors becomes a maintained module
qtbase
src
widgets
doc
src
gestures.qdoc
Generated on Sat Sep 28 2024 01:05:48 for Qt by
1.12.0