1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtWidgets module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include "qgesturerecognizer.h"
41
42#include "private/qgesture_p.h"
43#include "private/qgesturemanager_p.h"
44#include "private/qapplication_p.h"
45
46#ifndef QT_NO_GESTURES
47
48QT_BEGIN_NAMESPACE
49
50/*!
51 \class QGestureRecognizer
52 \since 4.6
53 \brief The QGestureRecognizer class provides the infrastructure for gesture recognition.
54 \ingroup gestures
55 \inmodule QtWidgets
56
57 Gesture recognizers are responsible for creating and managing QGesture objects and
58 monitoring input events sent to QWidget and QGraphicsObject subclasses.
59 QGestureRecognizer is the base class for implementing custom gestures.
60
61 Developers that only need to provide gesture recognition for standard gestures do not
62 need to use this class directly. Instances will be created behind the scenes by the
63 framework.
64
65 For an overview of gesture handling in Qt and information on using gestures
66 in your applications, see the \l{Gestures in Widgets and Graphics View} document.
67
68 \section1 Recognizing Gestures
69
70 The process of recognizing gestures involves filtering input events sent to specific
71 objects, and modifying the associated QGesture objects to include relevant information
72 about the user's input.
73
74 Gestures are created when the framework calls create() to handle user input
75 for a particular instance of a QWidget or QGraphicsObject subclass. A QGesture object
76 is created for each widget or item that is configured to use gestures.
77
78 Once a QGesture has been created for a target object, the gesture recognizer will
79 receive events for it in its recognize() handler function.
80
81 When a gesture is canceled, the reset() function is called, giving the recognizer the
82 chance to update the appropriate properties in the corresponding QGesture object.
83
84 \section1 Supporting New Gestures
85
86 To add support for new gestures, you need to derive from QGestureRecognizer to create
87 a custom recognizer class, construct an instance of this class, and register it with
88 the application by calling QGestureRecognizer::registerRecognizer(). You can also
89 subclass QGesture to create a custom gesture class, or rely on dynamic properties
90 to express specific details of the gesture you want to handle.
91
92 Your custom QGestureRecognizer subclass needs to reimplement the recognize()
93 function to handle and filter the incoming input events for QWidget and
94 QGraphicsObject subclasses. Although the logic for gesture recognition is
95 implemented in this function, you can store persistent information about the
96 state of the recognition process in the QGesture object supplied. The
97 recognize() function must return a value of QGestureRecognizer::Result that
98 indicates the state of recognition for a given gesture and target object.
99 This determines whether or not a gesture event will be delivered to a target
100 object.
101
102 If you choose to represent a gesture by a custom QGesture subclass, you will need to
103 reimplement the create() function to construct instances of your gesture class.
104 Similarly, you may need to reimplement the reset() function if your custom gesture
105 objects need to be specially handled when a gesture is canceled.
106
107 \sa QGesture
108*/
109
110/*!
111 \enum QGestureRecognizer::ResultFlag
112
113 This enum describes the result of the current event filtering step in
114 a gesture recognizer state machine.
115
116 The result consists of a state value (one of Ignore, MayBeGesture,
117 TriggerGesture, FinishGesture, CancelGesture) and an optional hint
118 (ConsumeEventHint).
119
120 \value Ignore The event does not change the state of the recognizer.
121
122 \value MayBeGesture The event changed the internal state of the recognizer,
123 but it isn't clear yet if it is a gesture or not. The recognizer needs to
124 filter more events to decide. Gesture recognizers in the MayBeGesture state
125 may be reset automatically if they take too long to recognize gestures.
126
127 \value TriggerGesture The gesture has been triggered and the appropriate
128 QGesture object will be delivered to the target as a part of a
129 QGestureEvent.
130
131 \value FinishGesture The gesture has been finished successfully and the
132 appropriate QGesture object will be delivered to the target as a part of a
133 QGestureEvent.
134
135 \value CancelGesture The event made it clear that it is not a gesture. If
136 the gesture recognizer was in GestureTriggered state before, then the
137 gesture is canceled and the appropriate QGesture object will be delivered
138 to the target as a part of a QGestureEvent.
139
140 \value ConsumeEventHint This hint specifies that the gesture framework
141 should consume the filtered event and not deliver it to the receiver.
142
143 \omitvalue ResultState_Mask
144 \omitvalue ResultHint_Mask
145
146 \sa QGestureRecognizer::recognize()
147*/
148
149/*!
150 Constructs a new gesture recognizer object.
151*/
152QGestureRecognizer::QGestureRecognizer()
153{
154}
155
156/*!
157 Destroys the gesture recognizer.
158*/
159QGestureRecognizer::~QGestureRecognizer()
160{
161}
162
163/*!
164 This function is called by Qt to create a new QGesture object for the
165 given \a target (QWidget or QGraphicsObject).
166
167 Reimplement this function to create a custom QGesture-derived gesture
168 object if necessary.
169
170 The application takes ownership of the created gesture object.
171*/
172QGesture *QGestureRecognizer::create(QObject *target)
173{
174 Q_UNUSED(target);
175 return new QGesture;
176}
177
178/*!
179 This function is called by the framework to reset a given \a gesture.
180
181 Reimplement this function to implement additional requirements for custom QGesture
182 objects. This may be necessary if you implement a custom QGesture whose properties
183 need special handling when the gesture is reset.
184*/
185void QGestureRecognizer::reset(QGesture *gesture)
186{
187 if (gesture) {
188 QGesturePrivate *d = gesture->d_func();
189 d->state = Qt::NoGesture;
190 d->hotSpot = QPointF();
191 d->sceneHotSpot = QPointF();
192 d->isHotSpotSet = false;
193 }
194}
195
196/*!
197 \fn QGestureRecognizer::Result QGestureRecognizer::recognize(QGesture *gesture, QObject *watched, QEvent *event)
198
199 Handles the given \a event for the \a watched object, updating the state of the \a gesture
200 object as required, and returns a suitable result for the current recognition step.
201
202 This function is called by the framework to allow the recognizer to filter input events
203 dispatched to QWidget or QGraphicsObject instances that it is monitoring.
204
205 The result reflects how much of the gesture has been recognized. The state of the
206 \a gesture object is set depending on the result.
207
208 \sa QGestureRecognizer::Result
209*/
210
211/*!
212 Registers the given \a recognizer in the gesture framework and returns a gesture ID
213 for it.
214
215 The application takes ownership of the \a recognizer and returns the gesture type
216 ID associated with it. For gesture recognizers which handle custom QGesture
217 objects (i.e., those which return Qt::CustomGesture in a QGesture::gestureType()
218 function) the return value is a generated gesture ID with the Qt::CustomGesture
219 flag set.
220
221 \sa unregisterRecognizer(), QGestureRecognizer::create(), QGesture
222*/
223Qt::GestureType QGestureRecognizer::registerRecognizer(QGestureRecognizer *recognizer)
224{
225 return QGestureManager::instance()->registerGestureRecognizer(recognizer);
226}
227
228/*!
229 Unregisters all gesture recognizers of the specified \a type.
230
231 \sa registerRecognizer()
232*/
233void QGestureRecognizer::unregisterRecognizer(Qt::GestureType type)
234{
235 auto qAppPriv = QApplicationPrivate::instance();
236 if (!qAppPriv)
237 return;
238 if (!qAppPriv->gestureManager)
239 return;
240 QGestureManager::instance()->unregisterGestureRecognizer(type);
241}
242
243QT_END_NAMESPACE
244
245#endif // QT_NO_GESTURES
246