63 |
64 |
64 The process of recognizing gestures involves filtering input events sent to specific |
65 The process of recognizing gestures involves filtering input events sent to specific |
65 objects, and modifying the associated QGesture objects to include relevant information |
66 objects, and modifying the associated QGesture objects to include relevant information |
66 about the user's input. |
67 about the user's input. |
67 |
68 |
68 Gestures are created when the framework calls createGesture() to handle user input |
69 Gestures are created when the framework calls create() to handle user input |
69 for a particular instance of a QWidget or QGraphicsObject subclass. A QGesture object |
70 for a particular instance of a QWidget or QGraphicsObject subclass. A QGesture object |
70 is created for each widget or item that is configured to use gestures. |
71 is created for each widget or item that is configured to use gestures. |
71 |
72 |
72 Once a QGesture has been created for a target object, the gesture recognizer will |
73 Once a QGesture has been created for a target object, the gesture recognizer will |
73 receive events for it in its filterEvent() handler function. |
74 receive events for it in its recognize() handler function. |
74 |
75 |
75 When a gesture is canceled, the reset() function is called, giving the recognizer the |
76 When a gesture is canceled, the reset() function is called, giving the recognizer the |
76 chance to update the appropriate properties in the corresponding QGesture object. |
77 chance to update the appropriate properties in the corresponding QGesture object. |
77 |
78 |
78 \section1 Supporting New Gestures |
79 \section1 Supporting New Gestures |
79 |
80 |
80 To add support for new gestures, you need to derive from QGestureRecognizer to create |
81 To add support for new gestures, you need to derive from QGestureRecognizer to create |
81 a custom recognizer class, construct an instance of this class, and register it with |
82 a custom recognizer class, construct an instance of this class, and register it with |
82 the application by calling QApplication::registerGestureRecognizer(). You can also |
83 the application by calling QGestureRecognizer::registerRecognizer(). You can also |
83 subclass QGesture to create a custom gesture class, or rely on dynamic properties |
84 subclass QGesture to create a custom gesture class, or rely on dynamic properties |
84 to express specific details of the gesture you want to handle. |
85 to express specific details of the gesture you want to handle. |
85 |
86 |
86 Your custom QGestureRecognizer subclass needs to reimplement the filterEvent() function |
87 Your custom QGestureRecognizer subclass needs to reimplement the recognize() |
87 to handle and filter the incoming input events for QWidget and QGraphicsObject subclasses. |
88 function to handle and filter the incoming input events for QWidget and |
88 Although the logic for gesture recognition is implemented in this function, you can |
89 QGraphicsObject subclasses. Although the logic for gesture recognition is |
89 store persistent information about the state of the recognition process in the QGesture |
90 implemented in this function, you can store persistent information about the |
90 object supplied. The filterEvent() function must return a value of Qt::GestureState that |
91 state of the recognition process in the QGesture object supplied. The |
91 indicates the state of recognition for a given gesture and target object. This determines |
92 recognize() function must return a value of QGestureRecognizer::Result that |
92 whether or not a gesture event will be delivered to a target object. |
93 indicates the state of recognition for a given gesture and target object. |
|
94 This determines whether or not a gesture event will be delivered to a target |
|
95 object. |
93 |
96 |
94 If you choose to represent a gesture by a custom QGesture subclass, you will need to |
97 If you choose to represent a gesture by a custom QGesture subclass, you will need to |
95 reimplement the createGesture() function to construct instances of your gesture class. |
98 reimplement the create() function to construct instances of your gesture class. |
96 Similarly, you may need to reimplement the reset() function if your custom gesture |
99 Similarly, you may need to reimplement the reset() function if your custom gesture |
97 objects need to be specially handled when a gesture is canceled. |
100 objects need to be specially handled when a gesture is canceled. |
98 |
101 |
99 \sa QGesture |
102 \sa QGesture |
100 */ |
103 */ |
101 |
104 |
102 /*! |
105 /*! |
103 \enum QGestureRecognizer::ResultFlags |
106 \enum QGestureRecognizer::ResultFlag |
104 |
107 |
105 This enum describes the result of the current event filtering step in |
108 This enum describes the result of the current event filtering step in |
106 a gesture recognizer state machine. |
109 a gesture recognizer state machine. |
107 |
110 |
108 The result consists of a state value (one of Ignore, NotGesture, |
111 The result consists of a state value (one of Ignore, MayBeGesture, |
109 MaybeGesture, GestureTriggered, GestureFinished) and an optional hint |
112 TriggerGesture, FinishGesture, CancelGesture) and an optional hint |
110 (ConsumeEventHint). |
113 (ConsumeEventHint). |
111 |
114 |
112 \value Ignore The event does not change the state of the recognizer. |
115 \value Ignore The event does not change the state of the recognizer. |
113 |
116 |
114 \value NotGesture The event made it clear that it is not a gesture. If the |
117 \value MayBeGesture The event changed the internal state of the recognizer, |
115 gesture recognizer was in GestureTriggered state before, then the gesture |
|
116 is canceled and the appropriate QGesture object will be delivered to the |
|
117 target as a part of a QGestureEvent. |
|
118 |
|
119 \value MaybeGesture The event changed the internal state of the recognizer, |
|
120 but it isn't clear yet if it is a gesture or not. The recognizer needs to |
118 but it isn't clear yet if it is a gesture or not. The recognizer needs to |
121 filter more events to decide. Gesture recognizers in the MaybeGesture state |
119 filter more events to decide. Gesture recognizers in the MayBeGesture state |
122 may be reset automatically if they take too long to recognize gestures. |
120 may be reset automatically if they take too long to recognize gestures. |
123 |
121 |
124 \value GestureTriggered The gesture has been triggered and the appropriate |
122 \value TriggerGesture The gesture has been triggered and the appropriate |
125 QGesture object will be delivered to the target as a part of a |
123 QGesture object will be delivered to the target as a part of a |
126 QGestureEvent. |
124 QGestureEvent. |
127 |
125 |
128 \value GestureFinished The gesture has been finished successfully and the |
126 \value FinishGesture The gesture has been finished successfully and the |
129 appropriate QGesture object will be delivered to the target as a part of a |
127 appropriate QGesture object will be delivered to the target as a part of a |
130 QGestureEvent. |
128 QGestureEvent. |
131 |
129 |
132 \value ConsumeEventHint This hint specifies that the gesture framework should |
130 \value CancelGesture The event made it clear that it is not a gesture. If |
133 consume the filtered event and not deliver it to the receiver. |
131 the gesture recognizer was in GestureTriggered state before, then the |
|
132 gesture is canceled and the appropriate QGesture object will be delivered |
|
133 to the target as a part of a QGestureEvent. |
|
134 |
|
135 \value ConsumeEventHint This hint specifies that the gesture framework |
|
136 should consume the filtered event and not deliver it to the receiver. |
134 |
137 |
135 \omitvalue ResultState_Mask |
138 \omitvalue ResultState_Mask |
136 \omitvalue ResultHint_Mask |
139 \omitvalue ResultHint_Mask |
137 |
140 |
138 \sa QGestureRecognizer::filterEvent() |
141 \sa QGestureRecognizer::recognize() |
139 */ |
142 */ |
140 |
143 |
141 /*! |
144 /*! |
142 Constructs a new gesture recognizer object. |
145 Constructs a new gesture recognizer object. |
143 */ |
146 */ |
176 { |
179 { |
177 if (gesture) { |
180 if (gesture) { |
178 QGesturePrivate *d = gesture->d_func(); |
181 QGesturePrivate *d = gesture->d_func(); |
179 d->state = Qt::NoGesture; |
182 d->state = Qt::NoGesture; |
180 d->hotSpot = QPointF(); |
183 d->hotSpot = QPointF(); |
181 d->targetObject = 0; |
184 d->isHotSpotSet = false; |
182 } |
185 } |
183 } |
186 } |
184 |
187 |
185 /*! |
188 /*! |
186 \fn QGestureRecognizer::filterEvent(QGesture *gesture, QObject *watched, QEvent *event) |
189 \fn QGestureRecognizer::recognize(QGesture *gesture, QObject *watched, QEvent *event) |
187 |
190 |
188 Handles the given \a event for the \a watched object, updating the state of the \a gesture |
191 Handles the given \a event for the \a watched object, updating the state of the \a gesture |
189 object as required, and returns a suitable Result for the current recognition step. |
192 object as required, and returns a suitable result for the current recognition step. |
190 |
193 |
191 This function is called by the framework to allow the recognizer to filter input events |
194 This function is called by the framework to allow the recognizer to filter input events |
192 dispatched to QWidget or QGraphicsObject instances that it is monitoring. |
195 dispatched to QWidget or QGraphicsObject instances that it is monitoring. |
193 |
196 |
194 The result reflects how much of the gesture has been recognized. The state of the |
197 The result reflects how much of the gesture has been recognized. The state of the |
195 \a gesture object is set depending on the result. |
198 \a gesture object is set depending on the result. |
196 |
199 |
197 \sa Qt::GestureState |
200 \sa QGestureRecognizer::Result |
198 */ |
201 */ |
|
202 |
|
203 /*! |
|
204 Registers the given \a recognizer in the gesture framework and returns a gesture ID |
|
205 for it. |
|
206 |
|
207 The application takes ownership of the \a recognizer and returns the gesture type |
|
208 ID associated with it. For gesture recognizers which handle custom QGesture |
|
209 objects (i.e., those which return Qt::CustomGesture in a QGesture::gestureType() |
|
210 function) the return value is a generated gesture ID with the Qt::CustomGesture |
|
211 flag set. |
|
212 |
|
213 \sa unregisterRecognizer(), QGestureRecognizer::create(), QGesture |
|
214 */ |
|
215 Qt::GestureType QGestureRecognizer::registerRecognizer(QGestureRecognizer *recognizer) |
|
216 { |
|
217 return QGestureManager::instance()->registerGestureRecognizer(recognizer); |
|
218 } |
|
219 |
|
220 /*! |
|
221 Unregisters all gesture recognizers of the specified \a type. |
|
222 |
|
223 \sa registerRecognizer() |
|
224 */ |
|
225 void QGestureRecognizer::unregisterRecognizer(Qt::GestureType type) |
|
226 { |
|
227 QGestureManager::instance()->unregisterGestureRecognizer(type); |
|
228 } |
199 |
229 |
200 QT_END_NAMESPACE |
230 QT_END_NAMESPACE |