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
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
|
/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtWidgets module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** 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 Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
#include "qgesturerecognizer.h"
#include "private/qgesture_p.h"
#include "private/qgesturemanager_p.h"
#ifndef QT_NO_GESTURES
QT_BEGIN_NAMESPACE
/*!
\class QGestureRecognizer
\since 4.6
\brief The QGestureRecognizer class provides the infrastructure for gesture recognition.
\ingroup gestures
\inmodule QtWidgets
Gesture recognizers are responsible for creating and managing QGesture objects and
monitoring input events sent to QWidget and QGraphicsObject subclasses.
QGestureRecognizer is the base class for implementing custom gestures.
Developers that only need to provide gesture recognition for standard gestures do not
need to use this class directly. Instances will be created behind the scenes by the
framework.
For an overview of gesture handling in Qt and information on using gestures
in your applications, see the \l{Gestures in Widgets and Graphics View} document.
\section1 Recognizing Gestures
The process of recognizing gestures involves filtering input events sent to specific
objects, and modifying the associated QGesture objects to include relevant information
about the user's input.
Gestures are created when the framework calls create() to handle user input
for a particular instance of a QWidget or QGraphicsObject subclass. A QGesture object
is created for each widget or item that is configured to use gestures.
Once a QGesture has been created for a target object, the gesture recognizer will
receive events for it in its recognize() handler function.
When a gesture is canceled, the reset() function is called, giving the recognizer the
chance to update the appropriate properties in the corresponding QGesture object.
\section1 Supporting New Gestures
To add support for new gestures, you need to derive from QGestureRecognizer to create
a custom recognizer class, construct an instance of this class, and register it with
the application by calling QGestureRecognizer::registerRecognizer(). You can also
subclass QGesture to create a custom gesture class, or rely on dynamic properties
to express specific details of the gesture you want to handle.
Your custom QGestureRecognizer subclass needs to reimplement the recognize()
function to handle and filter the incoming input events for QWidget and
QGraphicsObject subclasses. Although the logic for gesture recognition is
implemented in this function, you can store persistent information about the
state of the recognition process in the QGesture object supplied. The
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.
If you choose to represent a gesture by a custom QGesture subclass, you will need to
reimplement the create() function to construct instances of your gesture class.
Similarly, you may need to reimplement the reset() function if your custom gesture
objects need to be specially handled when a gesture is canceled.
\sa QGesture
*/
/*!
\enum QGestureRecognizer::ResultFlag
This enum describes the result of the current event filtering step in
a gesture recognizer state machine.
The result consists of a state value (one of Ignore, MayBeGesture,
TriggerGesture, FinishGesture, CancelGesture) and an optional hint
(ConsumeEventHint).
\value Ignore The event does not change the state of the recognizer.
\value MayBeGesture The event changed the internal state of the recognizer,
but it isn't clear yet if it is a gesture or not. The recognizer needs to
filter more events to decide. Gesture recognizers in the MayBeGesture state
may be reset automatically if they take too long to recognize gestures.
\value TriggerGesture The gesture has been triggered and the appropriate
QGesture object will be delivered to the target as a part of a
QGestureEvent.
\value FinishGesture The gesture has been finished successfully and the
appropriate QGesture object will be delivered to the target as a part of a
QGestureEvent.
\value CancelGesture The event made it clear that it is not a gesture. If
the gesture recognizer was in GestureTriggered state before, then the
gesture is canceled and the appropriate QGesture object will be delivered
to the target as a part of a QGestureEvent.
\value ConsumeEventHint This hint specifies that the gesture framework
should consume the filtered event and not deliver it to the receiver.
\omitvalue ResultState_Mask
\omitvalue ResultHint_Mask
\sa QGestureRecognizer::recognize()
*/
/*!
Constructs a new gesture recognizer object.
*/
QGestureRecognizer::QGestureRecognizer()
{
}
/*!
Destroys the gesture recognizer.
*/
QGestureRecognizer::~QGestureRecognizer()
{
}
/*!
This function is called by Qt to create a new QGesture object for the
given \a target (QWidget or QGraphicsObject).
Reimplement this function to create a custom QGesture-derived gesture
object if necessary.
The application takes ownership of the created gesture object.
*/
QGesture *QGestureRecognizer::create(QObject *target)
{
Q_UNUSED(target);
return new QGesture;
}
/*!
This function is called by the framework to reset a given \a gesture.
Reimplement this function to implement additional requirements for custom QGesture
objects. This may be necessary if you implement a custom QGesture whose properties
need special handling when the gesture is reset.
*/
void QGestureRecognizer::reset(QGesture *gesture)
{
if (gesture) {
QGesturePrivate *d = gesture->d_func();
d->state = Qt::NoGesture;
d->hotSpot = QPointF();
d->sceneHotSpot = QPointF();
d->isHotSpotSet = false;
}
}
/*!
\fn QGestureRecognizer::Result QGestureRecognizer::recognize(QGesture *gesture, QObject *watched, QEvent *event)
Handles the given \a event for the \a watched object, updating the state of the \a gesture
object as required, and returns a suitable result for the current recognition step.
This function is called by the framework to allow the recognizer to filter input events
dispatched to QWidget or QGraphicsObject instances that it is monitoring.
The result reflects how much of the gesture has been recognized. The state of the
\a gesture object is set depending on the result.
\sa QGestureRecognizer::Result
*/
/*!
Registers the given \a recognizer in the gesture framework and returns a gesture ID
for it.
The application takes ownership of the \a recognizer and returns the gesture type
ID associated with it. For gesture recognizers which handle custom QGesture
objects (i.e., those which return Qt::CustomGesture in a QGesture::gestureType()
function) the return value is a generated gesture ID with the Qt::CustomGesture
flag set.
\sa unregisterRecognizer(), QGestureRecognizer::create(), QGesture
*/
Qt::GestureType QGestureRecognizer::registerRecognizer(QGestureRecognizer *recognizer)
{
return QGestureManager::instance()->registerGestureRecognizer(recognizer);
}
/*!
Unregisters all gesture recognizers of the specified \a type.
\sa registerRecognizer()
*/
void QGestureRecognizer::unregisterRecognizer(Qt::GestureType type)
{
QGestureManager::instance()->unregisterGestureRecognizer(type);
}
QT_END_NAMESPACE
#endif // QT_NO_GESTURES
|
