|
1 /* |
|
2 * Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * |
|
5 * This program is free software: you can redistribute it and/or modify |
|
6 * it under the terms of the GNU Lesser General Public License as published by |
|
7 * the Free Software Foundation, version 2.1 of the License. |
|
8 * |
|
9 * This program is distributed in the hope that it will be useful, |
|
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of |
|
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
|
12 * GNU Lesser General Public License for more details. |
|
13 * |
|
14 * You should have received a copy of the GNU Lesser General Public License |
|
15 * along with this program. If not, |
|
16 * see "http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html/". |
|
17 * |
|
18 * Description: |
|
19 * |
|
20 */ |
|
21 #ifndef QSTMGESTURELISTENER_IF_H_ |
|
22 #define QSTMGESTURELISTENER_IF_H_ |
|
23 |
|
24 |
|
25 #include "qstmgesturelistener_if.h" |
|
26 #include "qstmgesture_if.h" |
|
27 |
|
28 namespace qstmUiEventEngine |
|
29 { |
|
30 class QStm_UiEventIf ; |
|
31 } |
|
32 |
|
33 namespace qstmGesture |
|
34 { |
|
35 |
|
36 // Forward declarations |
|
37 class QStm_GestureRecogniserIf ; |
|
38 |
|
39 /*! |
|
40 * QStm_GestureRecogniserIf defines the methods for the gesture recognisers |
|
41 * to be added to the gesture engine. |
|
42 * TODO: add rule based settings to position the gesture recognisers to the list. |
|
43 * The gesture recogniser order rules would be defined how? |
|
44 * - defining the order inside the application |
|
45 * - defining the order in some configuration file (maybe not) |
|
46 * |
|
47 * This requires: |
|
48 * - the gesture recognisers need to have an ID |
|
49 * - a type can also be defined if the rules can be set based on types. |
|
50 * |
|
51 * The gesture recognisers are arranged in a list so that the correct gesture recogniser |
|
52 * gets the opportunity to detect the gesture in time. An axample of a set of gesture recognisers |
|
53 * could be e.g. |
|
54 * |
|
55 * |---------------------------------------------| |
|
56 * | scrolling stop by tap -gesture recogniser | A is enabled only when needed, when enabled must precede all others |
|
57 * | | (note that locking partly can be used to achieve the same) |
|
58 * |---------------------------------------------| |
|
59 * | location specific: zoom + button tap gesture| B these must detect the location first |
|
60 * |---------------------------------------------| |
|
61 * | location specific: zoom - button tap gesture| B these must detect the location first |
|
62 * |---------------------------------------------| |
|
63 * | location specific: edge scroll gesture | B these must detect the location first |
|
64 * |---------------------------------------------| |
|
65 * | pinch zoom gesture | standard gesture, but application wide (spans windows) |
|
66 * | | C another requirement: disable all but me/restore state |
|
67 * | | so that other gestures will not meddle in while pinching |
|
68 * |---------------------------------------------| |
|
69 * | hover gesture | C standard gesture, needs to detect the EMove speed |
|
70 * |---------------------------------------------| |
|
71 * | pan gesture | C standard gesture, but must be after hover |
|
72 * |---------------------------------------------| |
|
73 * | tap/doubletap gesture | C standard gesture, order not that important, since |
|
74 * | | needs just to see certain events in history: touch/release |
|
75 * |---------------------------------------------| |
|
76 * |
|
77 * The order of gesture recognisers determine how the system behaves, so there must be an easy way |
|
78 * to define the order. The order could be defined either by specifying the IDs or just their types, if then the |
|
79 * order is not that important. TODO to study whether it would be a good idea to implement this so that |
|
80 * there are separate lists for the three different classes of gesture recognisers A, B and C; this might |
|
81 * make the implementation simpler. |
|
82 */ |
|
83 class QStm_GestureEngineIf |
|
84 { |
|
85 public: |
|
86 QStm_GestureEngineIf() {} |
|
87 /*! |
|
88 * add gesture to the end of the list of gestures |
|
89 */ |
|
90 virtual bool addGesture(const QStm_GestureRecogniserIf* newGesture) = 0 ; |
|
91 /*! |
|
92 * inset a gesture to specific position |
|
93 */ |
|
94 virtual bool insertGesture(const QStm_GestureRecogniserIf* newGesture, int position) = 0 ; |
|
95 |
|
96 virtual int findGesture(const QStm_GestureRecogniserIf* newGesture, int startPos = 0) const = 0; |
|
97 virtual int findGestureReverse(const QStm_GestureRecogniserIf* gesture, int astartPos) const = 0; |
|
98 virtual int findGesture(QStm_GestureUid uid, int startPos = 0) const = 0; |
|
99 virtual int findGestureReverse(QStm_GestureUid uid, int startPos) const = 0; |
|
100 virtual int gestureCount() const = 0; |
|
101 virtual QStm_GestureRecogniserIf* gestureAt(int idx) = 0; |
|
102 |
|
103 /*! |
|
104 * remove a gesture from the list |
|
105 */ |
|
106 virtual bool removeGesture(const QStm_GestureRecogniserIf* oldGesture) = 0 ; |
|
107 /*! |
|
108 * get the number of non-empty event streams. |
|
109 * Event streams correspond UI events generated by one touch pointer (=finger). |
|
110 * The low level state machine handles the necessary filtering etc. |
|
111 * so that it is safe to remove the event stream after UI Release event has been processed. |
|
112 */ |
|
113 virtual int activeStreamCount() const = 0 ; |
|
114 /*! |
|
115 * get the UI events of stream X |
|
116 * \param indexOfActiveStream defines which active stream is used. |
|
117 * Note that QStm_UiEventIf contains all the events from down up to the current event. |
|
118 * Assumption: the UI events contain the target "window handle", i.e. |
|
119 * the gesture recognition needs to be aware of all possible windows of the application. |
|
120 */ |
|
121 virtual const qstmUiEventEngine::QStm_UiEventIf* getUiEvents(int indexOfActiveStream) const = 0 ; |
|
122 /*! |
|
123 * Enable/disable logging |
|
124 */ |
|
125 virtual void enableLogging(bool aLoggingEnabled) = 0 ; |
|
126 }; |
|
127 |
|
128 /*! |
|
129 * Enumerated values for the gesture recogniser |
|
130 */ |
|
131 enum QStm_GestureRecognitionState |
|
132 { |
|
133 EGestureActive, /*! < gesture recognised and gesture notification sent */ |
|
134 ELockToThisGesture, /*! < gesture recognised, and only this recogniser called until release/this returns something else */ |
|
135 ENotMyGesture /*! < not this gesture, try the next one in the list */ |
|
136 }; |
|
137 |
|
138 /*! |
|
139 * The types of gesture recognisers. TODO to implement rule based gesture engine |
|
140 * where the recognisers can be added in any order, and the rules define the order of them. |
|
141 * The rules may define |
|
142 */ |
|
143 enum QStm_GestureRecogniserType |
|
144 { |
|
145 ECriticalGestureRecogniser, /*! < This kind of gestures should be at the beginning of the list */ |
|
146 ELocationSpecificGestureRecogniser, /*! < This kind of gestures should be at the next in the list */ |
|
147 EGenericGestureRecogniser /*! < This kind of gestures should be at the next in the list */ |
|
148 }; |
|
149 |
|
150 /*! |
|
151 * QStm_GestureRecogniserIf defines the interface needed to be implemented by every gesture recognition element. |
|
152 * The gesture recogniser gets the UI events and needs to determine whether they define the expected gesture. |
|
153 * |
|
154 */ |
|
155 class QStm_GestureRecogniserIf |
|
156 { |
|
157 public: |
|
158 QStm_GestureRecogniserIf() {} |
|
159 /*! |
|
160 * Virtual destuructor. |
|
161 */ |
|
162 virtual ~QStm_GestureRecogniserIf() {} |
|
163 /*! |
|
164 * Process the UI event. |
|
165 * \param numOfActiveStreams : indicates how many pointers are currently active. |
|
166 * \param ge the gesture engine. The Gesture recogniser uses this to get the current active events. |
|
167 * |
|
168 * \return EMaybeGesture if gesture was not yet recognised but can be possible (e.g. after first touch everyone returns this) |
|
169 * \return EGestureActive if gesture was recognised and a gesture notification was sent; this is then the active gesture |
|
170 * \return ENotMygesture if gesture can not be this one, e.g. TAP gesture after receiving Move UI event. |
|
171 * |
|
172 * Note that a gesture may take control only if it sends out a gesture notification. (or is it so?) |
|
173 * Until no gesture recogniser has sent a gesture notification, all recognisers who have not returned |
|
174 * ENotMyGesture are eligible, based on the order they are in the list. |
|
175 * |
|
176 * The gesture engine may be either in dynamic gestures mode or fixed gestures mode. |
|
177 * In dynamic gestures mode each time an UI event is processed, engine will call each |
|
178 * gesture recogniser until one of the recognisers returns EGestureActive. |
|
179 * |
|
180 * In fixed gestures mode the index of the gesture recogniser first returning EGestureActive is stored |
|
181 * and the subsequent UI events are processed so that only that recogniser is allowed to send gesture |
|
182 * notification. If it returns !=EGestureActive, it relinguishes the control. |
|
183 * |
|
184 */ |
|
185 virtual QStm_GestureRecognitionState recognise(int numOfActiveStreams, QStm_GestureEngineIf* ge) = 0 ; |
|
186 /*! |
|
187 * In dynamic gestures mode the gesture engine will call release of the recogniser |
|
188 * who lost activation status because a preceding recogniser in the list took control. |
|
189 * |
|
190 * Note that the recogniser must then do whatever (if anything) is needed to cancel the gesture. |
|
191 */ |
|
192 virtual void release(QStm_GestureEngineIf* ge) = 0 ; |
|
193 /*! |
|
194 * Enable or disable recogniser. E.g. if two gestures are related so that |
|
195 * a gesture ending recogniser needs to be activated to stop a t5imer driven |
|
196 * behaviour it is useful to add the recogniser to the top of the list |
|
197 * and then disable it until needed. |
|
198 */ |
|
199 virtual void enable(bool enableRecogniser) = 0 ; |
|
200 /*! |
|
201 * Get the state of the gesture recogniser, whether it is enabled or not |
|
202 * \return true, if the recogniser is enabled. |
|
203 */ |
|
204 virtual bool isEnabled() = 0 ; |
|
205 /*! |
|
206 * Return the type of the gesture recogniser |
|
207 */ |
|
208 virtual QStm_GestureUid gestureUid() const = 0; |
|
209 |
|
210 /*! |
|
211 * for testing purposes |
|
212 */ |
|
213 virtual void enableLogging(bool loggingEnabled) = 0 ; |
|
214 |
|
215 virtual void setOwner(void* owner) = 0; |
|
216 |
|
217 virtual QStm_GestureRecognitionState state() = 0; |
|
218 }; |
|
219 |
|
220 class QStm_GestureRecogniser : public QObject, public QStm_GestureRecogniserIf |
|
221 { |
|
222 public: |
|
223 virtual ~QStm_GestureRecogniser() |
|
224 { |
|
225 |
|
226 } |
|
227 /*! |
|
228 * MGestureRecogniserIf methods; partial implementation |
|
229 */ |
|
230 virtual void enable(bool enabled) |
|
231 { |
|
232 m_gestureEnabled = enabled ; |
|
233 } |
|
234 |
|
235 virtual bool isEnabled() |
|
236 { |
|
237 return m_gestureEnabled ; |
|
238 } |
|
239 |
|
240 virtual void enableLogging(bool loggingOn) |
|
241 { |
|
242 m_loggingenabled = loggingOn; |
|
243 } |
|
244 |
|
245 virtual void setOwner(void* owner) |
|
246 { |
|
247 m_powner = owner; |
|
248 } |
|
249 |
|
250 virtual QStm_GestureRecognitionState state() |
|
251 { |
|
252 return m_state; |
|
253 } |
|
254 |
|
255 protected: |
|
256 QStm_GestureRecogniser(QStm_GestureListenerIf* listener) : QStm_GestureRecogniserIf(), |
|
257 m_powner(listener->getOwner()), |
|
258 m_listener(listener), |
|
259 m_gestureEnabled(false), |
|
260 m_loggingenabled(false), |
|
261 m_state(ENotMyGesture) |
|
262 { |
|
263 |
|
264 } |
|
265 |
|
266 protected: |
|
267 void* m_powner ; // The owning control for this gesture |
|
268 QStm_GestureListenerIf* m_listener ; |
|
269 bool m_gestureEnabled ; |
|
270 bool m_loggingenabled ; |
|
271 QStm_GestureRecognitionState m_state; |
|
272 }; |
|
273 |
|
274 } // namespace |
|
275 |
|
276 |
|
277 #endif /* QSTMGESTURELISTENER_IF_H_ */ |