1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page gestures-overview.html
\title Gestures Programming
\startpage index.html Qt Reference Documentation
\ingroup technology-apis
\ingroup qt-gui-concepts
\brief An overview of Qt support for Gesture programming.
Qt includes a framework for gesture programming that has the ability
to form gestures from a series of events, independently of the input methods
used. A gesture could be a particular movement of a mouse, a touch screen
action, or a series of events from some other source. The nature of the input,
the interpretation of the gesture and the action taken are the choice of the
developer.
\tableofcontents
\section1 Overview
QGesture is the central class in Qt's gesture framework, providing a container
for information about gestures performed by the user. QGesture exposes
properties that give general information that is common to all gestures, and
these can be extended to provide additional gesture-specific information.
Common panning, pinching and swiping gestures are represented by specialized
classes: QPanGesture, QPinchGesture and QSwipeGesture.
Developers can also implement new gestures by subclassing and extending the
QGestureRecognizer class. Adding support for a new gesture involves implementing
code to recognize the gesture from input events. This is described in the
\l{Creating Your Own Gesture Recognizer} section.
\section1 Using Standard Gestures with Widgets
Gestures can be enabled for instances of QWidget and QGraphicsObject subclasses.
An object that accepts gesture input is referred to throughout the documentation
as a \e{target object}.
To enable a gesture for a target object, call its QWidget::grabGesture() or
QGraphicsObject::grabGesture() function with an argument describing the
required gesture type. The standard types are defined by the Qt::GestureType
enum and include many commonly used gestures.
\snippet examples/gestures/imagegestures/imagewidget.cpp enable gestures
In the above code, the gestures are set up in the constructor of the target object
itself.
\section1 Handling Events
When the user performs a gesture, QGestureEvent events will be delivered to the
target object, and these can be handled by reimplementing the QWidget::event()
handler function for widgets or QGraphicsItem::sceneEvent() for graphics objects.
As one target object can subscribe to more than one gesture type, the QGestureEvent
can contain more than one QGesture, indicating several possible gestures are active
at the same time. It is then up to the widget to determine how to handle those
multiple gestures and choose if some should be canceled in favor of others.
Each QGesture contained within a QGestureEvent object can be accepted() or ignored()
individually, or all together. Additionally, you can query the individual QGesture
data objects (the state) using several getters.
\section2 Standard Procedure for Event Handling
A QGesture is by default accepted when it arrives at your widget. However, it is good
practice to always explicitly accept or reject a gesture. The general rule is that, if
you accept a gesture, you are using it. If you are ignoring it you are not interested
in it. Ignoring a gesture may mean it gets offered to another target object, or it will
get canceled.
Each QGesture has several states it goes through; there is a well defined way to change
the state, typically the user input is the cause of state changes (by starting and
stopping interaction, for instance) but the widget can also cause state changes.
The first time a particular QGesture is delivered to a widget or graphics item, it will
be in the Qt::GestureStarted state. The way you handle the gesture at this point
influences whether you can interact with it later.
\list
\o Accepting the gesture means the widget acts on the gesture and there will follow
gestures with the Qt::GestureUpdatedstate.
\o Ignoring the gesture will mean the gesture will never be offered to you again.
It will be offered to a parent widget or item as well.
\o Calling setGestureCancelPolicy() on the gesture when it is in its starting state,
and is also accepted can cause other gestures to be canceled.
\endlist
Using QGesture::CancelAllInContext to cancel a gesture will cause all gestures, in any
state, to be canceled unless they are explicitly accepted. This means that active
gestures on children will get canceled. It also means that gestures delivered in the
same QGestureEvent will get canceled if the widget ignores them. This can be a useful
way to filter out all gestures except the one you are interested in.
\section2 Example Event Handling
For convenience, the \l{Image Gestures Example} reimplements the general
\l{QWidget::}{event()} handler function and delegates gesture events to a
specialized gestureEvent() function:
\snippet examples/gestures/imagegestures/imagewidget.cpp event handler
The gesture events delivered to the target object can be examined individually
and dealt with appropriately:
\snippet examples/gestures/imagegestures/imagewidget.cpp gesture event handler
Responding to a gesture is simply a matter of obtaining the QGesture object
delivered in the QGestureEvent sent to the target object and examining the
information it contains.
\snippet examples/gestures/imagegestures/imagewidget.cpp swipe function
Here, we examine the direction in which the user swiped the widget and modify
its contents accordingly.
\section1 Creating Your Own Gesture Recognizer
Adding support for a new gesture involves creating and registering a new gesture
recognizer. Depending on the recognition process for the gesture, it may also
involve creating a new gesture object.
To create a new recognizer, you need to subclass QGestureRecognizer to create a
custom recognizer class. There is one virtual function that you must reimplement
and two others that can be reimplemented as required.
\section2 Filtering Input Events
The \l{QGestureRecognizer::}{recognize()} function must be reimplemented.
This function handles and filters the incoming input events for the target objects
and determines whether or not they correspond to the gesture the recognizer is
looking for.
Although the logic for gesture recognition is implemented in this function,
possibly using a state machine based on the Qt::GestureState enums, you can store
persistent information about the state of the recognition process in the QGesture
object supplied.
Your \l{QGestureRecognizer::}{recognize()} function must return a value of
QGestureRecognizer::Result that indicates the state of recognition for a given gesture and
target object. This determines whether or not a gesture event will be delivered
to a target object.
\section2 Custom Gestures
If you choose to represent a gesture by a custom QGesture subclass, you will need to
reimplement the \l{QGestureRecognizer::}{create()} function to construct
instances of your gesture class instead of standard QGesture instances. Alternatively,
you may want to use standard QGesture instances, but add additional dynamic properties
to them to express specific details of the gesture you want to handle.
\section2 Resetting Gestures
If you use custom gesture objects that need to be reset or otherwise specially
handled when a gesture is canceled, you need to reimplement the
\l{QGestureRecognizer::}{reset()} function to perform these special tasks.
Note that QGesture objects are only created once for each combination of target object
and gesture type, and they might be reused every time the user attempts to perform the
same gesture type on the target object. As a result, it can be useful to reimplement
the \l{QGestureRecognizer::}{reset()} function to clean up after each previous attempt
at recognizing a gesture.
\section1 Using a New Gesture Recognizer
To use a gesture recognizer, construct an instance of your QGestureRecognizer
subclass, and register it with the application with
QGestureRecognizer::registerRecognizer(). A recognizer for a given type of
gesture can be removed with QGestureRecognizer::unregisterRecognizer().
\section1 Further Reading
The \l{gestures/imagegestures}{Image Gestures Example} shows how to enable
gestures for a widget in a simple image viewer application.
*/
|
