2 * @defgroup Elm_Gesture_Layer Gesture Layer
5 * Use Gesture Layer to detect gestures.
6 * The advantage is that you don't have to implement
7 * gesture detection, just set callbacks of gesture state.
8 * By using gesture layer we make standard interface.
10 * In order to use Gesture Layer you start with @ref elm_gesture_layer_add
11 * with a parent object parameter.
12 * Next 'activate' gesture layer with a @ref elm_gesture_layer_attach
13 * call. Usually with same object as target (2nd parameter).
15 * Now you need to tell gesture layer what gestures you follow.
16 * This is done with @ref elm_gesture_layer_cb_set call.
17 * By setting the callback you actually saying to gesture layer:
19 * I would like to know when the gesture @ref Elm_Gesture_Types
21 * I would like to know when the gesture @ref Elm_Gesture_Type
22 >>>>>>> remotes/origin/upstream
23 * switches to state @ref Elm_Gesture_State.
25 * Next, you need to implement the actual action that follows the input
28 * Note that if you like to stop being reported about a gesture, just set
29 * all callbacks referring this gesture to NULL.
30 * (again with @ref elm_gesture_layer_cb_set)
32 * The information reported by gesture layer to your callback is depending
34 * on @ref Elm_Gesture_Types:
36 * on @ref Elm_Gesture_Type:
37 >>>>>>> remotes/origin/upstream
38 * @ref Elm_Gesture_Taps_Info is the info reported for tap gestures:
39 * @ref ELM_GESTURE_N_TAPS, @ref ELM_GESTURE_N_LONG_TAPS,
40 * @ref ELM_GESTURE_N_DOUBLE_TAPS, @ref ELM_GESTURE_N_TRIPLE_TAPS.
42 * @ref Elm_Gesture_Momentum_Info is info reported for momentum gestures:
43 * @ref ELM_GESTURE_MOMENTUM.
45 * @ref Elm_Gesture_Line_Info is the info reported for line gestures:
46 * (this also contains @ref Elm_Gesture_Momentum_Info internal structure)
47 * @ref ELM_GESTURE_N_LINES, @ref ELM_GESTURE_N_FLICKS.
48 * Note that we consider a flick as a line-gesture that should be completed
49 * in flick-time-limit as defined in @ref Config.
51 * @ref Elm_Gesture_Zoom_Info is the info reported for @ref ELM_GESTURE_ZOOM gesture.
53 * @ref Elm_Gesture_Rotate_Info is the info reported for @ref ELM_GESTURE_ROTATE gesture.
56 * Gesture Layer Tweaks:
58 * Note that line, flick, gestures can start without the need to remove fingers from surface.
59 * When user fingers rests on same-spot gesture is ended and starts again when fingers moved.
61 * Setting glayer_continues_enable to false in @ref Config will change this behavior
62 * so gesture starts when user touches (a *DOWN event) touch-surface
63 * and ends when no fingers touches surface (a *UP event).
65 * Supported elm_object common APIs.
66 * @li elm_object_disabled_set
67 * @li elm_object_disabled_get
72 * Enum of supported gesture types.
73 * @ingroup Elm_Gesture_Layer
77 ELM_GESTURE_FIRST = 0,
79 ELM_GESTURE_N_TAPS, /**< N fingers single taps */
80 ELM_GESTURE_N_LONG_TAPS, /**< N fingers single long-taps */
81 ELM_GESTURE_N_DOUBLE_TAPS, /**< N fingers double-single taps */
82 ELM_GESTURE_N_TRIPLE_TAPS, /**< N fingers triple-single taps */
85 ELM_GESTURE_MOMENTUM, /**< Reports momentum in the dircetion of move */
87 ELM_GESTURE_MOMENTUM, /**< Reports momentum in the direction of move */
88 >>>>>>> remotes/origin/upstream
90 ELM_GESTURE_N_LINES, /**< N fingers line gesture */
91 ELM_GESTURE_N_FLICKS, /**< N fingers flick gesture */
93 ELM_GESTURE_ZOOM, /**< Zoom */
94 ELM_GESTURE_ROTATE, /**< Rotate */
101 >>>>>>> remotes/origin/upstream
104 * @enum _Elm_Gesture_State
105 * Enum of gesture states.
106 * @ingroup Elm_Gesture_Layer
110 ELM_GESTURE_STATE_UNDEFINED = -1, /**< Gesture not STARTed */
111 ELM_GESTURE_STATE_START, /**< Gesture STARTed */
112 ELM_GESTURE_STATE_MOVE, /**< Gesture is ongoing */
113 ELM_GESTURE_STATE_END, /**< Gesture completed */
115 ELM_GESTURE_STATE_ABORT /**< Onging gesture was ABORTed */
117 ELM_GESTURE_STATE_ABORT /**< Ongoing gesture was ABORTed */
118 >>>>>>> remotes/origin/upstream
122 * @struct _Elm_Gesture_Taps_Info
123 * Struct holds taps info for user
124 * @ingroup Elm_Gesture_Layer
126 struct _Elm_Gesture_Taps_Info
128 Evas_Coord x, y; /**< Holds center point between fingers */
129 unsigned int n; /**< Number of fingers tapped */
130 unsigned int timestamp; /**< event timestamp */
134 * @typedef Elm_Gesture_Taps_Info
135 * holds taps info for user
136 * @ingroup Elm_Gesture_Layer
138 typedef struct _Elm_Gesture_Taps_Info Elm_Gesture_Taps_Info;
141 * @struct _Elm_Gesture_Momentum_Info
142 * Struct holds momentum info for user
143 * x1 and y1 are not necessarily in sync
144 * x1 holds x value of x direction starting point
145 * and same holds for y1.
146 * This is noticeable when doing V-shape movement
147 * @ingroup Elm_Gesture_Layer
149 struct _Elm_Gesture_Momentum_Info /* Report line ends, timestamps, and momentum computed */
150 {Evas_Coord x1; /**< Final-swipe direction starting point on X */
151 Evas_Coord y1; /**< Final-swipe direction starting point on Y */
152 Evas_Coord x2; /**< Final-swipe direction ending point on X */
153 Evas_Coord y2; /**< Final-swipe direction ending point on Y */
155 unsigned int tx; /**< Timestamp of start of final x-swipe */
156 unsigned int ty; /**< Timestamp of start of final y-swipe */
158 Evas_Coord mx; /**< Momentum on X */
159 Evas_Coord my; /**< Momentum on Y */
161 unsigned int n; /**< Number of fingers */
165 * @typedef Elm_Gesture_Momentum_Info
166 * holds momentum info for user
167 * @ingroup Elm_Gesture_Layer
169 typedef struct _Elm_Gesture_Momentum_Info Elm_Gesture_Momentum_Info;
172 * @struct _Elm_Gesture_Line_Info
173 * Struct holds line info for user
174 * @ingroup Elm_Gesture_Layer
176 struct _Elm_Gesture_Line_Info /* Report line ends, timestamps, and momentum computed */
177 {Elm_Gesture_Momentum_Info momentum; /**< Line momentum info */
178 double angle; /**< Angle (direction) of lines */
182 * @typedef Elm_Gesture_Line_Info
183 * Holds line info for user
184 * @ingroup Elm_Gesture_Layer
186 typedef struct _Elm_Gesture_Line_Info Elm_Gesture_Line_Info;
189 * @struct _Elm_Gesture_Zoom_Info
190 * Struct holds zoom info for user
191 * @ingroup Elm_Gesture_Layer
193 struct _Elm_Gesture_Zoom_Info
195 Evas_Coord x, y; /**< Holds zoom center point reported to user */
196 Evas_Coord radius; /**< Holds radius between fingers reported to user */
197 double zoom; /**< Zoom value: 1.0 means no zoom */
198 double momentum; /**< Zoom momentum: zoom growth per second (NOT YET SUPPORTED) */
202 * @typedef Elm_Gesture_Zoom_Info
203 * Holds zoom info for user
204 * @ingroup Elm_Gesture_Layer
206 typedef struct _Elm_Gesture_Zoom_Info Elm_Gesture_Zoom_Info;
209 * @struct _Elm_Gesture_Rotate_Info
210 * Struct holds rotation info for user
211 * @ingroup Elm_Gesture_Layer
213 struct _Elm_Gesture_Rotate_Info
215 Evas_Coord x, y; /**< Holds zoom center point reported to user */
216 Evas_Coord radius; /**< Holds radius between fingers reported to user */
217 double base_angle; /**< Holds start-angle */
218 double angle; /**< Rotation value: 0.0 means no rotation */
219 double momentum; /**< Rotation momentum: rotation done per second (NOT YET SUPPORTED) */
223 * @typedef Elm_Gesture_Rotate_Info
224 * Holds rotation info for user
225 * @ingroup Elm_Gesture_Layer
227 typedef struct _Elm_Gesture_Rotate_Info Elm_Gesture_Rotate_Info;
230 * @typedef Elm_Gesture_Event_Cb
231 * User callback used to stream gesture info from gesture layer
232 * @param data user data
233 * @param event_info gesture report info
234 * Returns a flag field to be applied on the causing event.
235 * You should probably return EVAS_EVENT_FLAG_ON_HOLD if your widget acted
236 * upon the event, in an irreversible way.
238 * @ingroup Elm_Gesture_Layer
240 typedef Evas_Event_Flags (*Elm_Gesture_Event_Cb)(void *data, void *event_info);
243 * Use function to set callbacks to be notified about
244 * change of state of gesture.
245 * When a user registers a callback with this function
246 * this means this gesture has to be tested.
248 * When ALL callbacks for a gesture are set to NULL
249 * it means user isn't interested in gesture-state
250 * and it will not be tested.
253 * @param obj Pointer to gesture-layer.
255 * @param obj gesture-layer.
256 >>>>>>> remotes/origin/upstream
257 * @param idx The gesture you would like to track its state.
258 * @param cb callback function pointer.
259 * @param cb_type what event this callback tracks: START, MOVE, END, ABORT.
260 * @param data user info to be sent to callback (usually, Smart Data)
262 * @ingroup Elm_Gesture_Layer
265 EAPI void elm_gesture_layer_cb_set(Evas_Object *obj, Elm_Gesture_Types idx, Elm_Gesture_State cb_type, Elm_Gesture_Event_Cb cb, void *data);
267 EAPI void elm_gesture_layer_cb_set(Evas_Object *obj, Elm_Gesture_Type idx, Elm_Gesture_State cb_type, Elm_Gesture_Event_Cb cb, void *data);
268 >>>>>>> remotes/origin/upstream
271 * Call this function to get repeat-events settings.
274 * @param obj Pointer to gesture-layer.
276 * @param obj gesture-layer.
277 >>>>>>> remotes/origin/upstream
279 * @return repeat events settings.
280 * @see elm_gesture_layer_hold_events_set()
281 * @ingroup Elm_Gesture_Layer
284 EAPI Eina_Bool elm_gesture_layer_hold_events_get(Evas_Object *obj);
287 * This function called in order to make gesture-layer repeat events.
288 * Set this of you like to get the raw events only if gestures were not detected.
289 * Clear this if you like gesture layer to fwd events as testing gestures.
291 * @param obj Pointer to gesture-layer.
292 * @param r Repeat: TRUE/FALSE
294 * @ingroup Elm_Gesture_Layer
296 EAPI void elm_gesture_layer_hold_events_set(Evas_Object *obj, Eina_Bool r);
298 EAPI Eina_Bool elm_gesture_layer_hold_events_get(const Evas_Object *obj);
301 * This function is to make gesture-layer repeat events.
302 * Set this if you like to get the raw events only if gestures were not
304 * Clear this if you like gesture layer to forward events as testing gestures.
306 * @param obj gesture layer.
307 * @param hold_events hold events or not.
309 * @ingroup Elm_Gesture_Layer
311 EAPI void elm_gesture_layer_hold_events_set(Evas_Object *obj, Eina_Bool hold_events);
312 >>>>>>> remotes/origin/upstream
315 * This function sets step-value for zoom action.
316 * Set step to any positive value.
318 * Cancel step setting by setting to 0.0
320 * @param obj Pointer to gesture-layer.
321 * @param s new zoom step value.
323 * @ingroup Elm_Gesture_Layer
325 EAPI void elm_gesture_layer_zoom_step_set(Evas_Object *obj, double s);
327 * Cancel step setting by setting to 0
329 * @param obj gesture-layer.
330 * @param step new zoom step value.
332 * @see elm_gesture_layer_zoom_step_get()
333 * @ingroup Elm_Gesture_Layer
335 EAPI void elm_gesture_layer_zoom_step_set(Evas_Object *obj, double step);
338 * This function returns step-value for zoom action.
340 * @param obj gesture-layer.
341 * @return zoom step value.
343 * @see elm_gesture_layer_zoom_step_set()
344 * @ingroup Elm_Gesture_Layer
346 EAPI double elm_gesture_layer_zoom_step_get(const Evas_Object *obj);
347 >>>>>>> remotes/origin/upstream
350 * This function sets step-value for rotate action.
351 * Set step to any positive value.
353 * Cancel step setting by setting to 0.0
355 * @param obj Pointer to gesture-layer.
356 * @param s new roatate step value.
358 * @ingroup Elm_Gesture_Layer
360 EAPI void elm_gesture_layer_rotate_step_set(Evas_Object *obj, double s);
363 * This function called to attach gesture-layer to an Evas_Object.
364 * @param obj Pointer to gesture-layer.
365 * @param t Pointer to underlying object (AKA Target)
367 * Cancel step setting by setting to 0
369 * @param obj gesture-layer.
370 * @param step new rotate step value.
372 * @ingroup Elm_Gesture_Layer
374 EAPI void elm_gesture_layer_rotate_step_set(Evas_Object *obj, double step);
377 * This function returns step-value for rotate action.
379 * @param obj gesture-layer.
380 * @return rotate step value.
382 * @ingroup Elm_Gesture_Layer
384 EAPI double elm_gesture_layer_rotate_step_get(const Evas_Object *obj);
387 * This function called to attach gesture-layer to an Evas_Object.
388 * @param obj gesture-layer.
389 * @param target Pointer to underlying object (AKA Target)
390 >>>>>>> remotes/origin/upstream
392 * @return TRUE, FALSE on success, failure.
394 * @ingroup Elm_Gesture_Layer
397 EAPI Eina_Bool elm_gesture_layer_attach(Evas_Object *obj, Evas_Object *t);
399 EAPI Eina_Bool elm_gesture_layer_attach(Evas_Object *obj, Evas_Object *target);
400 >>>>>>> remotes/origin/upstream
403 * Call this function to construct a new gesture-layer object.
404 * This does not activate the gesture layer. You have to
405 * call elm_gesture_layer_attach in order to 'activate' gesture-layer.
407 * @param parent the parent object.
410 * @return Pointer to new gesture-layer object.
412 * @return new gesture-layer object.
413 >>>>>>> remotes/origin/upstream
415 * @ingroup Elm_Gesture_Layer
417 EAPI Evas_Object *elm_gesture_layer_add(Evas_Object *parent);