2 * @defgroup Elm_Gesture_Layer Gesture Layer
5 * @image html gesture_layer_inheritance_tree.png
6 * @image latex gesture_layer_inheritance_tree.eps
10 * Use Gesture Layer to detect gestures.
11 * The advantage is that you don't have to implement
12 * gesture detection, just set callbacks of gesture state.
13 * By using gesture layer we make standard interface.
15 * In order to use Gesture Layer you start with @ref elm_gesture_layer_add
16 * with a parent object parameter.
17 * Next 'activate' gesture layer with a @ref elm_gesture_layer_attach
18 * call. Usually with same object as target (2nd parameter).
20 * Now you need to tell gesture layer what gestures you follow.
21 * This is done with @ref elm_gesture_layer_cb_set call.
22 * By setting the callback you actually saying to gesture layer:
23 * I would like to know when the gesture @ref Elm_Gesture_Type
24 * switches to state @ref Elm_Gesture_State.
26 * Next, you need to implement the actual action that follows the input
29 * Note that if you like to stop being reported about a gesture, just set
30 * all callbacks referring this gesture to NULL.
31 * (again with @ref elm_gesture_layer_cb_set)
33 * The information reported by gesture layer to your callback is depending
34 * on @ref Elm_Gesture_Type :
35 * @ref Elm_Gesture_Taps_Info is the info reported for tap gestures:
36 * @ref ELM_GESTURE_N_TAPS, @ref ELM_GESTURE_N_LONG_TAPS,
37 * @ref ELM_GESTURE_N_DOUBLE_TAPS, @ref ELM_GESTURE_N_TRIPLE_TAPS.
39 * @ref Elm_Gesture_Momentum_Info is info reported for momentum gestures:
40 * @ref ELM_GESTURE_MOMENTUM.
42 * @ref Elm_Gesture_Line_Info is the info reported for line gestures:
43 * (this also contains @ref Elm_Gesture_Momentum_Info internal structure)
44 * @ref ELM_GESTURE_N_LINES, @ref ELM_GESTURE_N_FLICKS.
45 * Note that we consider a flick as a line-gesture that should be completed
46 * in flick-time-limit as defined in @ref Config.
48 * @ref Elm_Gesture_Zoom_Info is the info reported for @ref ELM_GESTURE_ZOOM gesture.
50 * @ref Elm_Gesture_Rotate_Info is the info reported for @ref ELM_GESTURE_ROTATE gesture.
53 * Gesture Layer Tweaks:
55 * Note that line, flick, gestures can start without the need to remove fingers from surface.
56 * When user fingers rests on same-spot gesture is ended and starts again when fingers moved.
58 * Setting glayer_continues_enable to false in @ref Config will change this behavior
59 * so gesture starts when user touches (a *DOWN event) touch-surface
60 * and ends when no fingers touches surface (a *UP event).
62 * Supported elm_object common APIs.
63 * @li @ref elm_object_disabled_set
64 * @li @ref elm_object_disabled_get
71 * @enum _Elm_Gesture_Type
72 * Enum of supported gesture types.
74 enum _Elm_Gesture_Type
76 ELM_GESTURE_FIRST = 0,
78 ELM_GESTURE_N_TAPS, /**< N fingers single taps */
79 ELM_GESTURE_N_LONG_TAPS, /**< N fingers single long-taps */
80 ELM_GESTURE_N_DOUBLE_TAPS, /**< N fingers double-single taps */
81 ELM_GESTURE_N_TRIPLE_TAPS, /**< N fingers triple-single taps */
83 ELM_GESTURE_MOMENTUM, /**< Reports momentum in the direction of move */
85 ELM_GESTURE_N_LINES, /**< N fingers line gesture */
86 ELM_GESTURE_N_FLICKS, /**< N fingers flick gesture */
88 ELM_GESTURE_ZOOM, /**< Zoom */
89 ELM_GESTURE_ROTATE, /**< Rotate */
95 * @typedef Elm_Gesture_Type
96 * Convenient macro around #_Elm_Gesture_Type
98 typedef enum _Elm_Gesture_Type Elm_Gesture_Type;
101 * @enum _Elm_Gesture_State
102 * Enum of gesture states.
104 enum _Elm_Gesture_State
106 ELM_GESTURE_STATE_UNDEFINED = -1, /**< Gesture not STARTed */
107 ELM_GESTURE_STATE_START, /**< Gesture STARTed */
108 ELM_GESTURE_STATE_MOVE, /**< Gesture is ongoing */
109 ELM_GESTURE_STATE_END, /**< Gesture completed */
110 ELM_GESTURE_STATE_ABORT /**< Ongoing gesture was ABORTed */
114 * @typedef Elm_Gesture_State
115 * Convenient macro around #_Elm_Gesture_State
117 typedef enum _Elm_Gesture_State Elm_Gesture_State;
120 * @struct _Elm_Gesture_Taps_Info
121 * Struct holds taps info for user
123 struct _Elm_Gesture_Taps_Info
125 Evas_Coord x, y; /**< Holds center point between fingers */
126 unsigned int n; /**< Number of fingers tapped */
127 unsigned int timestamp; /**< event timestamp */
131 * @typedef Elm_Gesture_Taps_Info
132 * holds taps info for user
134 typedef struct _Elm_Gesture_Taps_Info Elm_Gesture_Taps_Info;
137 * @struct _Elm_Gesture_Momentum_Info
138 * Struct holds momentum info for user
139 * x1 and y1 are not necessarily in sync
140 * x1 holds x value of x direction starting point
141 * and same holds for y1.
142 * This is noticeable when doing V-shape movement
144 struct _Elm_Gesture_Momentum_Info /* Report line ends, timestamps, and momentum computed */
145 {Evas_Coord x1; /**< Final-swipe direction starting point on X */
146 Evas_Coord y1; /**< Final-swipe direction starting point on Y */
147 Evas_Coord x2; /**< Final-swipe direction ending point on X */
148 Evas_Coord y2; /**< Final-swipe direction ending point on Y */
150 unsigned int tx; /**< Timestamp of start of final x-swipe */
151 unsigned int ty; /**< Timestamp of start of final y-swipe */
153 Evas_Coord mx; /**< Momentum on X */
154 Evas_Coord my; /**< Momentum on Y */
156 unsigned int n; /**< Number of fingers */
160 * @typedef Elm_Gesture_Momentum_Info
161 * holds momentum info for user
163 typedef struct _Elm_Gesture_Momentum_Info Elm_Gesture_Momentum_Info;
166 * @struct _Elm_Gesture_Line_Info
167 * Struct holds line info for user
169 struct _Elm_Gesture_Line_Info /* Report line ends, timestamps, and momentum computed */
170 {Elm_Gesture_Momentum_Info momentum; /**< Line momentum info */
171 double angle; /**< Angle (direction) of lines */
175 * @typedef Elm_Gesture_Line_Info
176 * Holds line info for user
178 typedef struct _Elm_Gesture_Line_Info Elm_Gesture_Line_Info;
181 * @struct _Elm_Gesture_Zoom_Info
182 * Struct holds zoom info for user
184 struct _Elm_Gesture_Zoom_Info
186 Evas_Coord x, y; /**< Holds zoom center point reported to user */
187 Evas_Coord radius; /**< Holds radius between fingers reported to user */
188 double zoom; /**< Zoom value: 1.0 means no zoom */
189 double momentum; /**< Zoom momentum: zoom growth per second (NOT YET SUPPORTED) */
193 * @typedef Elm_Gesture_Zoom_Info
194 * Holds zoom info for user
196 typedef struct _Elm_Gesture_Zoom_Info Elm_Gesture_Zoom_Info;
199 * @struct _Elm_Gesture_Rotate_Info
200 * Struct holds rotation info for user
202 struct _Elm_Gesture_Rotate_Info
204 Evas_Coord x, y; /**< Holds zoom center point reported to user */
205 Evas_Coord radius; /**< Holds radius between fingers reported to user */
206 double base_angle; /**< Holds start-angle */
207 double angle; /**< Rotation value: 0.0 means no rotation */
208 double momentum; /**< Rotation momentum: rotation done per second (NOT YET SUPPORTED) */
212 * @typedef Elm_Gesture_Rotate_Info
213 * Holds rotation info for user
215 typedef struct _Elm_Gesture_Rotate_Info Elm_Gesture_Rotate_Info;
218 * @typedef Elm_Gesture_Event_Cb
219 * User callback used to stream gesture info from gesture layer
220 * @param data user data
221 * @param event_info gesture report info
222 * Returns a flag field to be applied on the causing event.
223 * You should probably return EVAS_EVENT_FLAG_ON_HOLD if your widget acted
224 * upon the event, in an irreversible way.
227 typedef Evas_Event_Flags (*Elm_Gesture_Event_Cb)(void *data, void *event_info);
230 * Use function to set callbacks to be notified about
231 * change of state of gesture.
232 * When a user registers a callback with this function
233 * this means this gesture has to be tested.
235 * When ALL callbacks for a gesture are set to NULL
236 * it means user isn't interested in gesture-state
237 * and it will not be tested.
239 * @param obj gesture-layer.
240 * @param idx The gesture you would like to track its state.
241 * @param cb callback function pointer.
242 * @param cb_type what event this callback tracks: START, MOVE, END, ABORT.
243 * @param data user info to be sent to callback (usually, Smart Data)
246 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);
249 * Call this function to get repeat-events settings.
251 * @param obj gesture-layer.
253 * @return repeat events settings.
254 * @see elm_gesture_layer_hold_events_set()
256 EAPI Eina_Bool elm_gesture_layer_hold_events_get(const Evas_Object *obj);
259 * This function is to make gesture-layer repeat events.
260 * Set this if you like to get the raw events only if gestures were not
262 * Clear this if you like gesture layer to forward events as testing gestures.
264 * @param obj gesture layer.
265 * @param hold_events hold events or not.
268 EAPI void elm_gesture_layer_hold_events_set(Evas_Object *obj, Eina_Bool hold_events);
271 * This function sets step-value for zoom action.
272 * Set step to any positive value.
273 * Cancel step setting by setting to 0
275 * @param obj gesture-layer.
276 * @param step new zoom step value.
278 * @see elm_gesture_layer_zoom_step_get()
280 EAPI void elm_gesture_layer_zoom_step_set(Evas_Object *obj, double step);
283 * This function returns step-value for zoom action.
285 * @param obj gesture-layer.
286 * @return zoom step value.
288 * @see elm_gesture_layer_zoom_step_set()
290 EAPI double elm_gesture_layer_zoom_step_get(const Evas_Object *obj);
293 * This function sets step-value for rotate action.
294 * Set step to any positive value.
295 * Cancel step setting by setting to 0
297 * @param obj gesture-layer.
298 * @param step new rotate step value.
301 EAPI void elm_gesture_layer_rotate_step_set(Evas_Object *obj, double step);
304 * This function returns step-value for rotate action.
306 * @param obj gesture-layer.
307 * @return rotate step value.
310 EAPI double elm_gesture_layer_rotate_step_get(const Evas_Object *obj);
313 * Attach a given gesture layer widget to an Evas object, thus setting
314 * the widget's @b target.
316 * @param obj A gesture layer to attach an object to.
317 * @param target Object to attach to @a obj (target)
319 * A gesture layer target may be whichever Evas object one
320 * chooses. This will be object @a obj will listen all mouse and key
321 * events from, to report the gestures made upon it back.
323 * @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise.
326 EAPI Eina_Bool elm_gesture_layer_attach(Evas_Object *obj, Evas_Object *target);
329 * Call this function to construct a new gesture-layer object.
331 * @param parent The gesture layer's parent widget.
333 * @return A new gesture layer object.
335 * This does not activate the gesture layer. You have to
336 * call elm_gesture_layer_attach() in order to 'activate' gesture-layer.
339 EAPI Evas_Object *elm_gesture_layer_add(Evas_Object *parent);
343 * This function sets the gesture layer line min length of an object
345 * @param obj gesture-layer.
346 * @param line_min_length the length.
349 EAPI void elm_gesture_layer_line_min_length_set(Evas_Object *obj, int line_min_length);
353 * This function returns the gesture layer line min length of an object
355 * @param obj gesture-layer.
356 * @return the length.
359 EAPI int elm_gesture_layer_line_min_length_get(const Evas_Object *obj);
363 * This function sets the gesture layer zoom distance tolerance of an object
365 * @param obj gesture-layer.
366 * @param zoom_distance_tolerance zoom distance tolerance
369 EAPI void elm_gesture_layer_zoom_distance_tolerance_set(Evas_Object *obj, Evas_Coord zoom_distance_tolerance);
373 * This function returns the gesture layer zoom distance tolerance of an object
375 * @param obj gesture-layer.
376 * @return zoom distance tolerance
379 EAPI Evas_Coord elm_gesture_layer_zoom_distance_tolerance_get(const Evas_Object *obj);
383 * This function sets the gesture layer line distance tolerance of an object
385 * @param obj gesture-layer.
386 * @param line_distance_tolerance line distance tolerance
389 EAPI void elm_gesture_layer_line_distance_tolerance_set(Evas_Object *obj, Evas_Coord line_distance_tolerance);
393 * This function returns the gesture layer line distance tolerance of an object
395 * @param obj gesture-layer.
396 * @return line distance tolerance
399 EAPI Evas_Coord elm_gesture_layer_line_distance_tolerance_get(const Evas_Object *obj);
403 * This function sets the gesture layer line angular tolerance of an object
405 * @param obj gesture-layer.
406 * @param line_angular_tolerance line angular tolerance
409 EAPI void elm_gesture_layer_line_angular_tolerance_set(Evas_Object *obj, double line_angular_tolerance);
413 * This function returns the gesture layer line angular tolerance of an object
415 * @param obj gesture-layer.
416 * @return line angular tolerance
419 EAPI double elm_gesture_layer_line_angular_tolerance_get(const Evas_Object *obj);
423 * This function sets the gesture layer zoom wheel factor of an object
425 * @param obj gesture-layer.
426 * @param zoom_wheel_factor zoom wheel factor
429 EAPI void elm_gesture_layer_zoom_wheel_factor_set(Evas_Object *obj, double zoom_wheel_factor);
433 * This function returns the gesture layer zoom wheel factor of an object
435 * @param obj gesture-layer.
436 * @return zoom wheel factor
439 EAPI double elm_gesture_layer_zoom_wheel_factor_get(const Evas_Object *obj);
443 * This function sets the gesture layer zoom finger factor of an object
445 * @param obj gesture-layer.
446 * @param zoom_finger_factor zoom finger factor
449 EAPI void elm_gesture_layer_zoom_finger_factor_set(Evas_Object *obj, double zoom_finger_factor);
453 * This function returns the gesture layer zoom finger factor of an object
455 * @param obj gesture-layer.
456 * @return zoom finger factor
459 EAPI double elm_gesture_layer_zoom_finger_factor_get(const Evas_Object *obj);
463 * This function sets the gesture layer rotate angular tolerance of an object
465 * @param obj gesture-layer.
466 * @param rotate_angular_tolerance rotate angular tolerance
469 EAPI void elm_gesture_layer_rotate_angular_tolerance_set(Evas_Object *obj, double rotate_angular_tolerance);
473 * This function returns the gesture layer rotate angular tolerance of an object
475 * @param obj gesture-layer.
476 * @return rotate angular tolerance
479 EAPI double elm_gesture_layer_rotate_angular_tolerance_get(const Evas_Object *obj);
483 * This function sets the gesture layer flick time limit (in ms) of an object
485 * @param obj gesture-layer.
486 * @param flick_time_limit_ms flick time limit (in ms)
489 EAPI void elm_gesture_layer_flick_time_limit_ms_set(Evas_Object *obj, unsigned int flick_time_limit_ms);
493 * This function returns the gesture layer flick time limit (in ms) of an object
495 * @param obj gesture-layer.
496 * @return flick time limit (in ms)
499 EAPI unsigned int elm_gesture_layer_flick_time_limit_ms_get(const Evas_Object *obj);
503 * This function sets the gesture layer long tap start timeout of an object
505 * @param obj gesture-layer.
506 * @param long_tap_start_timeout long tap start timeout
509 EAPI void elm_gesture_layer_long_tap_start_timeout_set(Evas_Object *obj, double long_tap_start_timeout);
513 * this function returns the gesture layer long tap start timeout of an object
515 * @param obj gesture-layer.
516 * @return long tap start timeout
519 EAPI double elm_gesture_layer_long_tap_start_timeout_get(const Evas_Object *obj);
523 * This function sets the gesture layer continues enable of an object
525 * @param obj gesture-layer.
526 * @param continues_enable continues enable
529 EAPI void elm_gesture_layer_continues_enable_set(Evas_Object *obj, Eina_Bool continues_enable);
533 * This function returns the gesture layer continues enable of an object
535 * @param obj gesture-layer.
536 * @return continues enable
539 EAPI Eina_Bool elm_gesture_layer_continues_enable_get(const Evas_Object *obj);
543 * This function sets the gesture layer double tap timeout of an object
545 * @param obj gesture-layer.
546 * @param double_tap_timeout double tap timeout
549 EAPI void elm_gesture_layer_double_tap_timeout_set(Evas_Object *obj, double double_tap_timeout);
553 * this function returns the gesture layer double tap timeout of an object
555 * @param obj gesture-layer.
556 * @return double tap timeout
559 EAPI double elm_gesture_layer_double_tap_timeout_get(const Evas_Object *obj);