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

source code of qtbase/src/widgets/kernel/qgesturerecognizer.cpp