|
1 /* |
|
2 * Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 #ifndef QSTMUIEVENT_IF_H_ |
|
20 #define QSTMUIEVENT_IF_H_ |
|
21 |
|
22 #include <QtCore> |
|
23 #include "qstmgesturedefs.h" |
|
24 |
|
25 namespace qstmUiEventEngine |
|
26 { |
|
27 static const int KMaxNumberOfPointers(5) ; // How many of these should we have in multi-touch case |
|
28 |
|
29 enum QStm_UiEventCode |
|
30 { |
|
31 ETouch = 0x01, |
|
32 EHold = 0x02, |
|
33 EMove = 0x03, |
|
34 ERelease= 0x04, |
|
35 ENull = 0x05 |
|
36 }; |
|
37 |
|
38 enum QStm_AreaShape |
|
39 { |
|
40 ERectangle = 1, |
|
41 ECircle, |
|
42 EEllipse |
|
43 }; |
|
44 |
|
45 // for testingg/debugging purposes - string name og the code |
|
46 const char* event_name(QStm_UiEventCode aCode); |
|
47 |
|
48 |
|
49 struct QStm_PlatformPointerEvent |
|
50 { |
|
51 enum PEType |
|
52 { |
|
53 EButton1Down, |
|
54 EButton1Up, |
|
55 EButton2Down, |
|
56 EButton2Up, |
|
57 EButton3Down, |
|
58 EButton3Up, |
|
59 EDrag, |
|
60 EMove, |
|
61 EButtonRepeat, |
|
62 ESwitchOn, |
|
63 }; |
|
64 PEType m_type; |
|
65 unsigned int m_modifiers; |
|
66 QPoint m_position; |
|
67 int m_pointerNumber; |
|
68 void* m_target; |
|
69 QTime m_time; |
|
70 }; |
|
71 |
|
72 class QStm_UiEventSpeedIf |
|
73 { |
|
74 public: |
|
75 QStm_UiEventSpeedIf() {} |
|
76 virtual float speed() const /*__SOFTFP*/ = 0; |
|
77 virtual QPointF speedVec() const = 0; |
|
78 }; |
|
79 |
|
80 /*! |
|
81 * Utility class to wrap number for (already evaluated) speed values. |
|
82 */ |
|
83 class QStm_UiEventSpeed : public QStm_UiEventSpeedIf |
|
84 { |
|
85 public: |
|
86 QStm_UiEventSpeed(): m_speed(0), m_speedVec(QPointF(0.0, 0.0)) {} |
|
87 QStm_UiEventSpeed(float speed): m_speed(speed), m_speedVec(QPointF(0.0, 0.0)) {} |
|
88 QStm_UiEventSpeed(float speed, QPointF speedVec): m_speed(speed), m_speedVec(speedVec) {} |
|
89 virtual float speed() const /*__SOFTFP*/ { return m_speed; } |
|
90 virtual void setSpeed(float speed) { m_speed = speed; } |
|
91 |
|
92 virtual QPointF speedVec() const { return m_speedVec; } |
|
93 virtual void setSpeedVec(QPointF speedVec) { m_speedVec = speedVec; } |
|
94 |
|
95 float m_speed; |
|
96 QPointF m_speedVec; |
|
97 }; |
|
98 |
|
99 /*! |
|
100 * The UI event interface, UI events are touch, hold, move and release. |
|
101 * Note that currently the interface is not OS agnostic enough. It is using |
|
102 * TPoint, TTimeIntervalMicroSeconds etc. types which should be replaced |
|
103 * with some standard types/classes. |
|
104 */ |
|
105 class QStm_UiEventIf : public QStm_UiEventSpeed |
|
106 { |
|
107 public: |
|
108 QStm_UiEventIf() : QStm_UiEventSpeed() {} |
|
109 |
|
110 /*! |
|
111 * The starting position of the gesture in _screen_ coordinates |
|
112 */ |
|
113 virtual const QPoint& startPos() const = 0; |
|
114 /*! |
|
115 * Current position in _screen_ coordinates |
|
116 */ |
|
117 virtual const QPoint& currentXY() const = 0 ; |
|
118 /*! |
|
119 * Previous position in _screen_ coordinates |
|
120 */ |
|
121 virtual const QPoint& previousXY() const = 0 ; |
|
122 /*! |
|
123 * Time difference between this and previous UI event |
|
124 */ |
|
125 virtual long stateTransition() const = 0 ; |
|
126 /*! |
|
127 * true, if the UI event was generated because of timer expiration |
|
128 */ |
|
129 virtual bool timerExpired() const = 0; |
|
130 /*! |
|
131 * The UI event code |
|
132 */ |
|
133 virtual QStm_UiEventCode code() const = 0 ; |
|
134 /*! |
|
135 * Target identifier (in practice the CCoeControl* of the window) |
|
136 */ |
|
137 virtual void* target() const = 0 ; |
|
138 /*! |
|
139 * The index of the UI event. In single touch this is always 0 |
|
140 */ |
|
141 virtual int index() const = 0 ; |
|
142 /*! |
|
143 * Next event in the gesture (with the same index) |
|
144 */ |
|
145 virtual QStm_UiEventIf* previousEvent() const = 0 ; |
|
146 /*! |
|
147 * Count of events in gesture |
|
148 */ |
|
149 virtual int countOfEvents() const = 0 ; |
|
150 /*! |
|
151 * Timestamp |
|
152 */ |
|
153 virtual QTime timestamp() const = 0 ; |
|
154 /*! |
|
155 * Speed. Speed is calculated based on the previous event. |
|
156 */ |
|
157 virtual float speed() const /*__SOFTFP */ = 0 ; |
|
158 |
|
159 virtual void setSpeed(float speed) = 0; |
|
160 |
|
161 virtual QPointF speedVec() const = 0; |
|
162 virtual void setSpeedVec(QPointF speedVec) = 0; |
|
163 virtual QEvent::Type mapToMouseEventType() = 0; |
|
164 virtual QEvent::Type mapToTouchEventType() = 0; |
|
165 |
|
166 }; |
|
167 |
|
168 /** |
|
169 * Observer that will be notified when UI events have been recognised |
|
170 */ |
|
171 class QStm_UiEventObserverIf |
|
172 { |
|
173 public: |
|
174 QStm_UiEventObserverIf() {}; |
|
175 /** |
|
176 * Handle the UI event |
|
177 * \param aEvent event describing the event |
|
178 */ |
|
179 virtual void handleUiEvent( const QStm_UiEventIf& aEvent ) = 0; |
|
180 }; |
|
181 |
|
182 /*! The state machine interface. |
|
183 * |
|
184 * To be OS agnostic TPointerEvent, TRect etc. should be replaced with |
|
185 * something else. |
|
186 */ |
|
187 class QStm_StateMachineIf |
|
188 { |
|
189 public: |
|
190 /*! |
|
191 * \return the rectangle containing the touch area. |
|
192 * The shape of the touch area can be either rectangle, circle or ellipse. |
|
193 * getTouchArea returns the current touch area, so it may be of zero size. |
|
194 * During touch timer the method will return the TouchTimeArea, after that it |
|
195 * will return the TouchArea. |
|
196 */ |
|
197 virtual QRect getTouchArea(int pointerNumber = 0) = 0 ; |
|
198 /*! |
|
199 * \param fingersize_mm defines the width of the rectangle or the diameter of the circle/ellipse |
|
200 * used for the touch area during touch timer running. If the initial touch is a "sloppy" one, |
|
201 * there is very easily an extra move event detected during touch time. On the other hand |
|
202 * after touch has been detected, the touch area should not be too big, just something suitable to |
|
203 * filter minor movements out. The proposed solution is to define two touch areas: one to be used |
|
204 * while touch timer is running, and another used after touch has been detected. |
|
205 * The TouchTimeArea can be a bit larger to allow sloppy touch, then the TouchArea can be smaller to |
|
206 * filter minor movements out. |
|
207 */ |
|
208 virtual void setTouchTimeArea(long fingersize_mm) = 0 ; |
|
209 /*! |
|
210 * \param fingersize_mm defines the width of the rectangle or the diameter of the circle/ellipse |
|
211 * used for the touch area. |
|
212 */ |
|
213 virtual void setTouchArea(long fingersize_mm) = 0 ; |
|
214 /*! |
|
215 * get the touch area shape, either rectangle, circle or ellipse |
|
216 */ |
|
217 virtual QStm_AreaShape getTouchAreaShape() = 0 ; |
|
218 /*! |
|
219 * set the touch area shape, either rectangle, circle or ellipse. This is the same for both of |
|
220 * the touch areas. |
|
221 */ |
|
222 virtual void setTouchAreaShape(const QStm_AreaShape shape) = 0 ; |
|
223 /*! |
|
224 * get the touch timeout. Touch timeout is the time after the first down event |
|
225 * until the Touch UI event is generated. Touch timeout makes it possible to |
|
226 * calculate an average of the first few points detected before generating the Touch UI event. |
|
227 */ |
|
228 virtual unsigned int getTouchTimeout() = 0 ; |
|
229 /*! |
|
230 * Set the touch timeout. |
|
231 */ |
|
232 virtual void setTouchTimeout(unsigned int) = 0 ; |
|
233 /*! |
|
234 * \return the rectangle containing the hold area. |
|
235 * The shape of the hold area can be either rectangle, circle or ellipse. |
|
236 * getholdArea returns the current hold area, so it may be of zero size. |
|
237 */ |
|
238 virtual QRect getHoldArea(int pointerNumber = 0) = 0 ; |
|
239 /*! |
|
240 * \param fingersize_mm defines the width of the rectangle or the diameter of the circle/ellipse |
|
241 * used for the hold area. Hold area defines an area so that if the touch coordinates stay |
|
242 * inside that area for the duration of hold timeout the Hold UI event is generated. |
|
243 */ |
|
244 virtual void setHoldArea(long fingersize_mm) = 0 ; |
|
245 /*! |
|
246 * get the hold area shape, either rectangle, circle or ellipse |
|
247 */ |
|
248 virtual QStm_AreaShape getHoldAreaShape() = 0 ; |
|
249 /*! |
|
250 * set the hold area shape, either rectangle, circle or ellipse |
|
251 */ |
|
252 virtual void setHoldAreaShape(const QStm_AreaShape shape) = 0 ; |
|
253 /*! |
|
254 * get the hold timeout. The timeout defines how long the touch coordinates need to stay |
|
255 * inside hold area before Hold UI event is generated. |
|
256 */ |
|
257 virtual unsigned int getHoldTimeout() = 0 ; |
|
258 /*! |
|
259 * Set the hold timeout. |
|
260 */ |
|
261 virtual void setHoldTimeout(unsigned int a) = 0 ; |
|
262 /*! |
|
263 * get the touch suppress timeout. This timeout defines how long it will take to generate |
|
264 * the Release UI event after UP event during the touch timeout. This timeout is rather short |
|
265 * but will cause the filtering of accidental UP/DOWN events during if they are close together. |
|
266 */ |
|
267 virtual unsigned int getTouchSuppressTimeout() = 0 ; |
|
268 /*! |
|
269 * Set the touch suppress timeout. |
|
270 */ |
|
271 virtual void setTouchSuppressTimeout(unsigned int a) = 0 ; |
|
272 /*! |
|
273 * get the move suppress timeout. This timeout is used after Move UI event has been generated to |
|
274 * filter accidental UP/DOWN events. Using light touch it is possible to cause accidental UP/DOWN |
|
275 * events with the timespan can be over 120 ms when the direction of movement changes. |
|
276 */ |
|
277 virtual unsigned int getMoveSuppressTimeout() = 0 ; |
|
278 /*! |
|
279 * set the move suppress timeout. |
|
280 */ |
|
281 virtual void setMoveSuppressTimeout(unsigned int a) = 0 ; |
|
282 /*! |
|
283 * add UI event observer. The generated UI events will be sent to the observers. |
|
284 * \return false, if the max number of observers (=5) has been reached. |
|
285 */ |
|
286 virtual bool addUiEventObserver(QStm_UiEventObserverIf* observer) = 0 ; |
|
287 /*! |
|
288 * remove the UI event observer. |
|
289 */ |
|
290 virtual bool removeUiEventObserver(QStm_UiEventObserverIf* observer) = 0 ; |
|
291 /*! |
|
292 * \return true, of the message being processed did not generate UI event |
|
293 */ |
|
294 virtual bool wasLastMessageFiltered(int pointerNumber = 0) = 0 ; |
|
295 /*! |
|
296 * enable capacitive UP message. If it is enabled, UP suppression is not used |
|
297 * but the UP event causes immediate Release UI event. |
|
298 */ |
|
299 virtual void enableCapacitiveUp(bool enable) = 0 ; |
|
300 /*! |
|
301 * enable or disable debug logging of the state machine |
|
302 * \param aEnable : logging enabled |
|
303 */ |
|
304 virtual void enableLogging(bool aEnable) = 0 ; |
|
305 /*! |
|
306 * add "window handles" to the list of targets which should be included |
|
307 * in the gesture recognition. This way it is possible to drop the messges |
|
308 * which are not of interest from the gesture recognition point of view. |
|
309 * This is used when only the gesture recognition is used so that the UI events are |
|
310 * not passed to the application. |
|
311 */ |
|
312 // virtual void addGestureTarget(void* aTarget) = 0 ; |
|
313 |
|
314 /*! |
|
315 * Setting the Y adjustment useful in capacitive touch |
|
316 * Note that there are problems with the adjustment if done at this level, |
|
317 * the most proper place would be the window server. |
|
318 */ |
|
319 virtual void enableYadjustment(bool aEnable) = 0 ; |
|
320 |
|
321 // Get the number of supported touch pointers |
|
322 virtual int getNumberOfPointers() = 0; |
|
323 |
|
324 /* |
|
325 virtual void setPointerBuffer(TPoint* aBufferPtr, int aBufSize) = 0; |
|
326 |
|
327 virtual TPoint* getPointerBuffer() = 0; |
|
328 |
|
329 virtual int getPointerBufferSize() = 0; |
|
330 */ |
|
331 virtual void setMoveTolerance(long fingersize_mm) = 0; |
|
332 |
|
333 }; |
|
334 |
|
335 } // namespace |
|
336 |
|
337 #endif /* QSTMUIEVENT_IF_H_ */ |