1 /* |
|
2 * Copyright (c) 2008-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 "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: Gesture helper interface |
|
15 * |
|
16 */ |
|
17 |
|
18 #ifndef _GESTUREOBSERVER_H_ |
|
19 #define _GESTUREOBSERVER_H_ |
|
20 |
|
21 #include <e32std.h> |
|
22 |
|
23 class CAlfControl; |
|
24 class CAlfVisual; |
|
25 |
|
26 namespace GestureHelper |
|
27 { |
|
28 |
|
29 /// flag that indicates gesture code is a holding code |
|
30 /// clients should use MGestureEvent::IsHolding |
|
31 const TInt EFlagHold = 0x10000000; |
|
32 |
|
33 enum TGestureCode |
|
34 { |
|
35 // states |
|
36 EGestureStart = 0x00000001, // gesture just started (user pressed stylus down) |
|
37 EGestureDrag = 0x00000002, // user moved stylus (may be holding or not holding) |
|
38 EGestureReleased = 0x00000003, // user lifted stylus while user was holding |
|
39 // gestures |
|
40 EGestureUnknown = 0x00000005, // gesture was not recognised |
|
41 // these codes are sent when user lifts stylus (if holding not started) |
|
42 EGestureTap = 0x00000006, |
|
43 EGestureDoubleTap = 0x00000007, // only if double tap is enabled |
|
44 // (via CGestureHelper::SetDoubleTapEnabled or |
|
45 // CGestureControl::SetDoubleTapEnabled) |
|
46 EGestureSwipeLeft = 0x00000008, |
|
47 EGestureSwipeRight = 0x00000009, |
|
48 EGestureSwipeUp = 0x0000000A, |
|
49 EGestureSwipeDown = 0x0000000B, |
|
50 |
|
51 // gestures related to advanced pointer events. These codes are sent if the platform supports advanced pointer events. |
|
52 // states |
|
53 EGestureMultiTouchStart = 0x0000000C, // multitouch gesture just started (user touched 2nd finger down) |
|
54 EGestureMultiTouchReleased = 0x0000000D, // user released 2nd touch point while still holding the first touch point |
|
55 // gestures |
|
56 EGesturePinch = 0x0000000E, // This event is sent when the pinch is recognised for |
|
57 // the first time or when the pinch distance is changing. |
|
58 |
|
59 // these codes are sent when user initiates holding by keeping stylus in |
|
60 // same place for a longer duration |
|
61 EGestureHoldLeft = EGestureSwipeLeft | EFlagHold, |
|
62 EGestureHoldRight = EGestureSwipeRight | EFlagHold, |
|
63 EGestureHoldUp = EGestureSwipeUp | EFlagHold, |
|
64 EGestureHoldDown = EGestureSwipeDown | EFlagHold |
|
65 }; |
|
66 |
|
67 /** |
|
68 * Point of float accuracy |
|
69 */ |
|
70 NONSHARABLE_STRUCT( TRealPoint ) |
|
71 { |
|
72 inline TRealPoint(); |
|
73 inline TRealPoint( const TRealPoint& aPoint ); |
|
74 inline TRealPoint( TReal aX, TReal aY ); |
|
75 inline TBool operator==( const TRealPoint& aPoint ) const; |
|
76 |
|
77 TReal32 iX; |
|
78 TReal32 iY; |
|
79 }; |
|
80 |
|
81 /** |
|
82 * a gesture event |
|
83 */ |
|
84 class MGestureEvent |
|
85 { |
|
86 public: |
|
87 /** X and Y axes, or both */ |
|
88 enum TAxis |
|
89 { |
|
90 EAxisBoth, |
|
91 EAxisHorizontal, |
|
92 EAxisVertical |
|
93 }; |
|
94 |
|
95 public: |
|
96 /** |
|
97 * @param aRelevantAxis indicates whether only x, y or both coordinates |
|
98 * should be considered when determining the code. For example, |
|
99 * if client specifies EAxisVertical as relevant axis, a swipe |
|
100 * to left and slightly up would result in an "swipe up" code, |
|
101 * and not "swipe left" code. If client specifies EAxisHorizontal |
|
102 * or EAxisBoth, "swipe left" code is returned. |
|
103 * @return gesture code |
|
104 */ |
|
105 virtual TGestureCode Code( TAxis aRelevantAxis ) const = 0; |
|
106 |
|
107 /** |
|
108 * @return ETrue if user has activated holding |
|
109 * (by keeping stylus in the same position for longer time) |
|
110 * EFalse if holding has not been activated |
|
111 */ |
|
112 virtual TBool IsHolding() const = 0; |
|
113 |
|
114 /** |
|
115 * @return position where gesture started, i.e., where stulys |
|
116 * was pressed down |
|
117 */ |
|
118 virtual TPoint StartPos() const = 0; |
|
119 |
|
120 /** |
|
121 * @return current position of the stylus |
|
122 */ |
|
123 virtual TPoint CurrentPos() const = 0; |
|
124 |
|
125 /** |
|
126 * @return speed of a swipe. unit is pixels per second. |
|
127 */ |
|
128 virtual TRealPoint Speed() const = 0; |
|
129 |
|
130 /** |
|
131 * Abstracts the algorithm to calculate speed during swipe and hold. This |
|
132 * algorithm (currently) assumes that max speed is achieved at the edges of an |
|
133 * area. |
|
134 * @param aEdges represents the coordinates of the rectange on which speed is |
|
135 * calculated. Speed will reach maximum if stylus is on the edge |
|
136 * or beyond the rect. In practise, the value should match the |
|
137 * area of the layout that contains the scrollable visuals. |
|
138 * For example, if the control area is the whole screen, the |
|
139 * rect should be the screen rect. |
|
140 * @returns the speed as a percentage between -100% and 100% |
|
141 */ |
|
142 virtual TRealPoint SpeedPercent( const TRect& aEdges ) const = 0; |
|
143 |
|
144 /** |
|
145 * @return Length of gesture from starting position |
|
146 * (start pos - current pos) |
|
147 */ |
|
148 virtual TPoint Distance() const = 0; |
|
149 |
|
150 /** |
|
151 * @return visual on which the gesture started |
|
152 * NULL if not known (e.g., AVKON-based client |
|
153 */ |
|
154 virtual CAlfVisual* Visual() const = 0; |
|
155 |
|
156 /** |
|
157 * Pinch distance |
|
158 * |
|
159 * Used only for pinch. Returns 0 for other gestures. |
|
160 * |
|
161 * @return The ratio of pinch end distance to pinch start distance * 100 |
|
162 * PinchPercent above 100 for zooming out and below hundred for zooming in |
|
163 */ |
|
164 virtual TInt PinchPercent() const = 0; |
|
165 |
|
166 /** |
|
167 * Centre point of the two touch points |
|
168 * |
|
169 * Used only for pinch. Returns TPoint(0,0) for other gestures. |
|
170 * |
|
171 * @return the centre point calculated using teh two touch down points |
|
172 * This point will remian the same for one multitouch gesture start to end. |
|
173 * This doesnt vary as the two points move away or closer. |
|
174 */ |
|
175 virtual TPoint PinchCentrePoint() const = 0; |
|
176 |
|
177 }; |
|
178 |
|
179 /** |
|
180 * Observer that will be notified when user makes gestures |
|
181 */ |
|
182 class MGestureObserver |
|
183 { |
|
184 public: |
|
185 /** |
|
186 * Handle the gesture event |
|
187 * @param aEvent event describing the gesture |
|
188 */ |
|
189 virtual void HandleGestureL( const MGestureEvent& aEvent ) = 0; |
|
190 }; |
|
191 |
|
192 /** |
|
193 * static class for finding a visual from a visual tree |
|
194 */ |
|
195 class HitTest |
|
196 { |
|
197 public: |
|
198 /** |
|
199 * @return the leaf-most visual is under aPos, or NULL if not found |
|
200 */ |
|
201 IMPORT_C static CAlfVisual* VisualByCoordinates( const CAlfControl& aControl, |
|
202 const TPoint& aPos ); |
|
203 }; |
|
204 |
|
205 // ---------------------------------------------------------------------------- |
|
206 // Default constructor for real point |
|
207 // ---------------------------------------------------------------------------- |
|
208 // |
|
209 inline TRealPoint::TRealPoint() |
|
210 : iX( 0 ), iY( 0 ) |
|
211 { |
|
212 } |
|
213 |
|
214 // ---------------------------------------------------------------------------- |
|
215 // Copy constructor for real point |
|
216 // ---------------------------------------------------------------------------- |
|
217 // |
|
218 inline TRealPoint::TRealPoint( const TRealPoint& aPoint ) |
|
219 : iX( aPoint.iX ), iY( aPoint.iY ) |
|
220 { |
|
221 } |
|
222 |
|
223 // ---------------------------------------------------------------------------- |
|
224 // Copy constructor for real point |
|
225 // ---------------------------------------------------------------------------- |
|
226 // |
|
227 inline TRealPoint::TRealPoint( TReal aX, TReal aY ) |
|
228 : iX( aX ), iY( aY ) |
|
229 { |
|
230 } |
|
231 |
|
232 // ---------------------------------------------------------------------------- |
|
233 // Default constructor for real point |
|
234 // ---------------------------------------------------------------------------- |
|
235 // |
|
236 inline TBool TRealPoint::operator==( const TRealPoint& aPoint ) const |
|
237 { |
|
238 return iX == aPoint.iX && iY == aPoint.iY; |
|
239 } |
|
240 |
|
241 |
|
242 } // namespace GestureHelper |
|
243 |
|
244 #endif // _GESTUREOBSERVER_H_ |
|