|
1 /* |
|
2 * Copyright (c) 2008 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 the License "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 #ifndef RT_UIEVENT_H_ |
|
19 #define RT_UIEVENT_H_ |
|
20 |
|
21 // INCLUDES |
|
22 #include <browser_platform_variant.hrh> |
|
23 #include <coemain.h> |
|
24 #include <aknutils.h> |
|
25 #include <e32property.h> |
|
26 #include <w32std.h> |
|
27 |
|
28 #if defined(BRDO_MULTITOUCH_ENABLED_FF) |
|
29 #define ADVANCED_POINTER_EVENTS |
|
30 #endif |
|
31 |
|
32 namespace stmUiEventEngine |
|
33 { |
|
34 |
|
35 #if defined(ADVANCED_POINTER_EVENTS) |
|
36 static const TInt KMaxNumberOfPointers(2) ; // How many pointer we have in multi-touch case |
|
37 #else |
|
38 static const TInt KMaxNumberOfPointers(1) ; // How many pointer we have in single touch case |
|
39 #endif |
|
40 |
|
41 /*! |
|
42 * Event code generated from the state machine |
|
43 */ |
|
44 enum TUiEventCode |
|
45 { |
|
46 ETouch = 0x01, |
|
47 EHold = 0x02, |
|
48 EMove = 0x03, |
|
49 ERelease= 0x04, |
|
50 ENull = 0x05 |
|
51 }; |
|
52 |
|
53 /*! |
|
54 * Shape of the Area |
|
55 */ |
|
56 enum TAreaShape |
|
57 { |
|
58 ERectangle = 1, |
|
59 ECircle, |
|
60 EEllipse |
|
61 }; |
|
62 |
|
63 // for testingg/debugging purposes - string name og the code |
|
64 const char* EventName(TUiEventCode aCode); |
|
65 |
|
66 /*! |
|
67 * Interface class for Speed in X-Y direction |
|
68 */ |
|
69 class MUiEventSpeed |
|
70 { |
|
71 public: |
|
72 virtual float speedX() const __SOFTFP = 0; |
|
73 virtual float speedY() const __SOFTFP = 0; |
|
74 }; |
|
75 |
|
76 /*! |
|
77 * Utility class to wrap number for (already evaluated) speed values. |
|
78 */ |
|
79 NONSHARABLE_CLASS(TUiEventSpeed): public MUiEventSpeed |
|
80 { |
|
81 public: |
|
82 TUiEventSpeed(float speedX, float speedY): m_speedX(speedX),m_speedY(speedY) {} |
|
83 virtual float speedX() const __SOFTFP { return m_speedX; } |
|
84 virtual float speedY() const __SOFTFP { return m_speedY; } |
|
85 float m_speedX; |
|
86 float m_speedY; |
|
87 }; |
|
88 |
|
89 /*! |
|
90 * The UI event interface, UI events are touch, hold, move and release. |
|
91 * Note that currently the interface is not OS agnostic enough. It is using |
|
92 * TPoint, TTimeIntervalMicroSeconds etc. types which should be replaced |
|
93 * with some standard types/classes. |
|
94 */ |
|
95 class MUiEvent: public MUiEventSpeed |
|
96 { |
|
97 public: |
|
98 /*! |
|
99 * The starting position of the gesture in _screen_ coordinates |
|
100 */ |
|
101 virtual const TPoint& StartPos() const = 0; |
|
102 /*! |
|
103 * Current position in _screen_ coordinates |
|
104 */ |
|
105 virtual const TPoint& CurrentXY() const = 0 ; |
|
106 /*! |
|
107 * Previous position in _screen_ coordinates |
|
108 */ |
|
109 virtual const TPoint& PreviousXY() const = 0 ; |
|
110 /*! |
|
111 * Time difference between this and previous UI event |
|
112 */ |
|
113 virtual TTimeIntervalMicroSeconds StateTransition() const = 0 ; |
|
114 /*! |
|
115 * true, if the UI event was generated because of timer expiration |
|
116 */ |
|
117 virtual bool TimerExpired() const = 0; |
|
118 /*! |
|
119 * The UI event code |
|
120 */ |
|
121 virtual TUiEventCode Code()const = 0 ; |
|
122 /*! |
|
123 * Target identifier (in practice the CCoeControl* of the window) |
|
124 */ |
|
125 virtual void* Target() const = 0 ; |
|
126 /*! |
|
127 * The index of the UI event. In single touch this is always 0 |
|
128 */ |
|
129 virtual int Index() const = 0 ; |
|
130 /*! |
|
131 * Next event in the gesture (with the same index) |
|
132 */ |
|
133 virtual MUiEvent* previousEvent() const = 0 ; |
|
134 /*! |
|
135 * Count of events in gesture |
|
136 */ |
|
137 virtual int countOfEvents() const = 0 ; |
|
138 /*! |
|
139 * Timestamp |
|
140 */ |
|
141 virtual TInt64 timestamp() const = 0 ; |
|
142 /*! |
|
143 * Speed. Speed is calculated based on the previous event. |
|
144 */ |
|
145 virtual float speedX() const __SOFTFP = 0 ; |
|
146 /*! |
|
147 * Speed. Speed is calculated based on the previous event. |
|
148 */ |
|
149 virtual float speedY() const __SOFTFP = 0 ; |
|
150 }; |
|
151 |
|
152 /** |
|
153 * Observer that will be notified when UI events have been recognised |
|
154 */ |
|
155 class MUiEventObserver |
|
156 { |
|
157 public: |
|
158 /** |
|
159 * Handle the UI event |
|
160 * \param aEvent event describing the event |
|
161 */ |
|
162 virtual void HandleUiEventL( const MUiEvent& aEvent ) = 0; |
|
163 }; |
|
164 |
|
165 /*! The state machine interface. |
|
166 * |
|
167 * To be OS agnostic TPointerEvent, TRect etc. should be replaced with |
|
168 * something else. |
|
169 */ |
|
170 class MStateMachine |
|
171 { |
|
172 public: |
|
173 /*! |
|
174 * \return the rectangle containing the touch area. |
|
175 * The shape of the touch area can be either rectangle, circle or ellipse. |
|
176 * getTouchArea returns the current touch area, so it may be of zero size. |
|
177 * During touch timer the method will return the TouchTimeArea, after that it |
|
178 * will return the TouchArea. |
|
179 */ |
|
180 virtual TRect getTouchArea(TInt aPointerNumber = 0) = 0 ; |
|
181 /*! |
|
182 * \param fingersize_mm defines the width of the rectangle or the diameter of the circle/ellipse |
|
183 * used for the touch area during touch timer running. If the initial touch is a "sloppy" one, |
|
184 * there is very easily an extra move event detected during touch time. On the other hand |
|
185 * after touch has been detected, the touch area should not be too big, just something suitable to |
|
186 * filter minor movements out. The proposed solution is to define two touch areas: one to be used |
|
187 * while touch timer is running, and another used after touch has been detected. |
|
188 * The TouchTimeArea can be a bit larger to allow sloppy touch, then the TouchArea can be smaller to |
|
189 * filter minor movements out. |
|
190 */ |
|
191 virtual void setTouchTimeArea(long fingersize_mm) = 0 ; |
|
192 /*! |
|
193 * \param fingersize_mm defines the width of the rectangle or the diameter of the circle/ellipse |
|
194 * used for the touch area. |
|
195 */ |
|
196 virtual void setTouchArea(long fingersize_mm) = 0 ; |
|
197 /*! |
|
198 * get the touch area shape, either rectangle, circle or ellipse |
|
199 */ |
|
200 virtual TAreaShape getTouchAreaShape() = 0 ; |
|
201 /*! |
|
202 * set the touch area shape, either rectangle, circle or ellipse. This is the same for both of |
|
203 * the touch areas. |
|
204 */ |
|
205 virtual void setTouchAreaShape(const TAreaShape shape) = 0 ; |
|
206 /*! |
|
207 * get the touch timeout. Touch timeout is the time after the first down event |
|
208 * until the Touch UI event is generated. Touch timeout makes it possible to |
|
209 * calculate an average of the first few points detected before generating the Touch UI event. |
|
210 */ |
|
211 virtual unsigned int getTouchTimeout() = 0 ; |
|
212 /*! |
|
213 * Set the touch timeout. |
|
214 */ |
|
215 virtual void setTouchTimeout(unsigned int) = 0 ; |
|
216 /*! |
|
217 * \return the rectangle containing the hold area. |
|
218 * The shape of the hold area can be either rectangle, circle or ellipse. |
|
219 * getholdArea returns the current hold area, so it may be of zero size. |
|
220 */ |
|
221 virtual TRect getHoldArea(TInt aPointerNumber = 0) = 0 ; |
|
222 /*! |
|
223 * \param fingersize_mm defines the width of the rectangle or the diameter of the circle/ellipse |
|
224 * used for the hold area. Hold area defines an area so that if the touch coordinates stay |
|
225 * inside that area for the duration of hold timeout the Hold UI event is generated. |
|
226 */ |
|
227 virtual void setHoldArea(long fingersize_mm) = 0 ; |
|
228 /*! |
|
229 * get the hold area shape, either rectangle, circle or ellipse |
|
230 */ |
|
231 virtual TAreaShape getHoldAreaShape() = 0 ; |
|
232 /*! |
|
233 * set the hold area shape, either rectangle, circle or ellipse |
|
234 */ |
|
235 virtual void setHoldAreaShape(const TAreaShape shape) = 0 ; |
|
236 /*! |
|
237 * get the hold timeout. The timeout defines how long the touch coordinates need to stay |
|
238 * inside hold area before Hold UI event is generated. |
|
239 */ |
|
240 virtual unsigned int getHoldTimeout() = 0 ; |
|
241 /*! |
|
242 * Set the hold timeout. |
|
243 */ |
|
244 virtual void setHoldTimeout(unsigned int a) = 0 ; |
|
245 /*! |
|
246 * get the touch suppress timeout. This timeout defines how long it will take to generate |
|
247 * the Release UI event after UP event during the touch timeout. This timeout is rather short |
|
248 * but will cause the filtering of accidental UP/DOWN events during if they are close together. |
|
249 */ |
|
250 virtual unsigned int getTouchSuppressTimeout() = 0 ; |
|
251 /*! |
|
252 * Set the touch suppress timeout. |
|
253 */ |
|
254 virtual void setTouchSuppressTimeout(unsigned int a) = 0 ; |
|
255 /*! |
|
256 * get the move suppress timeout. This timeout is used after Move UI event has been generated to |
|
257 * filter accidental UP/DOWN events. Using light touch it is possible to cause accidental UP/DOWN |
|
258 * events with the timespan can be over 120 ms when the direction of movement changes. |
|
259 */ |
|
260 virtual unsigned int getMoveSuppressTimeout() = 0 ; |
|
261 /*! |
|
262 * set the move suppress timeout. |
|
263 */ |
|
264 virtual void setMoveSuppressTimeout(unsigned int a) = 0 ; |
|
265 /*! |
|
266 * add UI event observer. The generated UI events will be sent to the observers. |
|
267 * \return false, if the max number of observers (=5) has been reached. |
|
268 */ |
|
269 virtual bool addUiEventObserver(MUiEventObserver* observer) = 0 ; |
|
270 /*! |
|
271 * remove the UI event observer. |
|
272 */ |
|
273 virtual bool removeUiEventObserver(MUiEventObserver* observer) = 0 ; |
|
274 /*! |
|
275 * \return true, of the message being processed did not generate UI event |
|
276 */ |
|
277 virtual bool wasLastMessageFiltered(TInt aPointerNumber = 0) = 0 ; |
|
278 /*! |
|
279 * enable capacitive UP message. If it is enabled, UP suppression is not used |
|
280 * but the UP event causes immediate Release UI event. |
|
281 */ |
|
282 virtual void enableCapacitiveUp(bool enable) = 0 ; |
|
283 /*! |
|
284 * enable or disable debug logging of the state machine |
|
285 * \param aEnable : logging enabled |
|
286 */ |
|
287 virtual void enableLogging(bool aEnable) = 0 ; |
|
288 /*! |
|
289 * add "window handles" to the list of targets which should be included |
|
290 * in the gesture recognition. This way it is possible to drop the messges |
|
291 * which are not of interest from the gesture recognition point of view. |
|
292 * This is used when only the gesture recognition is used so that the UI events are |
|
293 * not passed to the application. |
|
294 */ |
|
295 // virtual void addGestureTarget(void* aTarget) = 0 ; |
|
296 |
|
297 /*! |
|
298 * Setting the Y adjustment useful in capacitive touch |
|
299 * Note that there are problems with the adjustment if done at this level, |
|
300 * the most proper place would be the window server. |
|
301 */ |
|
302 virtual void enableYadjustment(bool aEnable) = 0 ; |
|
303 |
|
304 /// Get the number of supported touch pointers |
|
305 virtual int getNumberOfPointers() = 0; |
|
306 }; |
|
307 |
|
308 } // namespace |
|
309 #endif /* RT_UIEVENT_H_ */ |