src/lib/elm_gesture_layer.h

   1 /**
   2  * @defgroup Elm_Gesture_Layer Gesture Layer
   3  * Gesture Layer Usage:
   4  *
   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.
   9  *
  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).
  14  *
  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:
  18 <<<<<<< HEAD
  19  * I would like to know when the gesture @ref Elm_Gesture_Types
  20 =======
  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.
  24  *
  25  * Next, you need to implement the actual action that follows the input
  26  * in your callback.
  27  *
  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)
  31  *
  32  * The information reported by gesture layer to your callback is depending
  33 <<<<<<< HEAD
  34  * on @ref Elm_Gesture_Types:
  35 =======
  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.
  41  *
  42  * @ref Elm_Gesture_Momentum_Info is info reported for momentum gestures:
  43  * @ref ELM_GESTURE_MOMENTUM.
  44  *
  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.
  50  *
  51  * @ref Elm_Gesture_Zoom_Info is the info reported for @ref ELM_GESTURE_ZOOM gesture.
  52  *
  53  * @ref Elm_Gesture_Rotate_Info is the info reported for @ref ELM_GESTURE_ROTATE gesture.
  54  *
  55  *
  56  * Gesture Layer Tweaks:
  57  *
  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.
  60  *
  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).
  64  *
  65  * Supported elm_object common APIs.
  66  * @li elm_object_disabled_set
  67  * @li elm_object_disabled_get
  68  *
  69  */
  70
  71 /**
  72  * Enum of supported gesture types.
  73  * @ingroup Elm_Gesture_Layer
  74  */
  75 typedef enum
  76 {
  77    ELM_GESTURE_FIRST = 0,
  78
  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 */
  83
  84 <<<<<<< HEAD
  85    ELM_GESTURE_MOMENTUM, /**< Reports momentum in the dircetion of move */
  86 =======
  87    ELM_GESTURE_MOMENTUM, /**< Reports momentum in the direction of move */
  88 >>>>>>> remotes/origin/upstream
  89
  90    ELM_GESTURE_N_LINES, /**< N fingers line gesture */
  91    ELM_GESTURE_N_FLICKS, /**< N fingers flick gesture */
  92
  93    ELM_GESTURE_ZOOM, /**< Zoom */
  94    ELM_GESTURE_ROTATE, /**< Rotate */
  95
  96    ELM_GESTURE_LAST
  97 <<<<<<< HEAD
  98 } Elm_Gesture_Types;
  99 =======
 100 } Elm_Gesture_Type;
 101 >>>>>>> remotes/origin/upstream
 102
 103 /**
 104  * @enum _Elm_Gesture_State
 105  * Enum of gesture states.
 106  * @ingroup Elm_Gesture_Layer
 107  */
 108 typedef enum
 109 {
 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   */
 114 <<<<<<< HEAD
 115    ELM_GESTURE_STATE_ABORT /**< Onging gesture was ABORTed */
 116 =======
 117    ELM_GESTURE_STATE_ABORT /**< Ongoing gesture was ABORTed */
 118 >>>>>>> remotes/origin/upstream
 119 } Elm_Gesture_State;
 120
 121 /**
 122  * @struct _Elm_Gesture_Taps_Info
 123  * Struct holds taps info for user
 124  * @ingroup Elm_Gesture_Layer
 125  */
 126 struct _Elm_Gesture_Taps_Info
 127 {
 128    Evas_Coord   x, y; /**< Holds center point between fingers */
 129    unsigned int n; /**< Number of fingers tapped           */
 130    unsigned int timestamp; /**< event timestamp       */
 131 };
 132
 133 /**
 134  * @typedef Elm_Gesture_Taps_Info
 135  * holds taps info for user
 136  * @ingroup Elm_Gesture_Layer
 137  */
 138 typedef struct _Elm_Gesture_Taps_Info Elm_Gesture_Taps_Info;
 139
 140 /**
 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
 148  */
 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   */
 154
 155  unsigned int tx; /**< Timestamp of start of final x-swipe */
 156  unsigned int ty; /**< Timestamp of start of final y-swipe */
 157
 158  Evas_Coord   mx; /**< Momentum on X */
 159  Evas_Coord   my; /**< Momentum on Y */
 160
 161  unsigned int n; /**< Number of fingers */
 162 };
 163
 164 /**
 165  * @typedef Elm_Gesture_Momentum_Info
 166  * holds momentum info for user
 167  * @ingroup Elm_Gesture_Layer
 168  */
 169 typedef struct _Elm_Gesture_Momentum_Info Elm_Gesture_Momentum_Info;
 170
 171 /**
 172  * @struct _Elm_Gesture_Line_Info
 173  * Struct holds line info for user
 174  * @ingroup Elm_Gesture_Layer
 175  */
 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  */
 179 };
 180
 181 /**
 182  * @typedef Elm_Gesture_Line_Info
 183  * Holds line info for user
 184  * @ingroup Elm_Gesture_Layer
 185  */
 186 typedef struct _Elm_Gesture_Line_Info Elm_Gesture_Line_Info;
 187
 188 /**
 189  * @struct _Elm_Gesture_Zoom_Info
 190  * Struct holds zoom info for user
 191  * @ingroup Elm_Gesture_Layer
 192  */
 193 struct _Elm_Gesture_Zoom_Info
 194 {
 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) */
 199 };
 200
 201 /**
 202  * @typedef Elm_Gesture_Zoom_Info
 203  * Holds zoom info for user
 204  * @ingroup Elm_Gesture_Layer
 205  */
 206 typedef struct _Elm_Gesture_Zoom_Info Elm_Gesture_Zoom_Info;
 207
 208 /**
 209  * @struct _Elm_Gesture_Rotate_Info
 210  * Struct holds rotation info for user
 211  * @ingroup Elm_Gesture_Layer
 212  */
 213 struct _Elm_Gesture_Rotate_Info
 214 {
 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) */
 220 };
 221
 222 /**
 223  * @typedef Elm_Gesture_Rotate_Info
 224  * Holds rotation info for user
 225  * @ingroup Elm_Gesture_Layer
 226  */
 227 typedef struct _Elm_Gesture_Rotate_Info Elm_Gesture_Rotate_Info;
 228
 229 /**
 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.
 237  *
 238  * @ingroup Elm_Gesture_Layer
 239  */
 240 typedef Evas_Event_Flags (*Elm_Gesture_Event_Cb)(void *data, void *event_info);
 241
 242 /**
 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.
 247  *
 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.
 251  *
 252 <<<<<<< HEAD
 253  * @param obj Pointer to gesture-layer.
 254 =======
 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)
 261  *
 262  * @ingroup Elm_Gesture_Layer
 263  */
 264 <<<<<<< HEAD
 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);
 266 =======
 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
 269
 270 /**
 271  * Call this function to get repeat-events settings.
 272  *
 273 <<<<<<< HEAD
 274  * @param obj Pointer to gesture-layer.
 275 =======
 276  * @param obj gesture-layer.
 277 >>>>>>> remotes/origin/upstream
 278  *
 279  * @return repeat events settings.
 280  * @see elm_gesture_layer_hold_events_set()
 281  * @ingroup Elm_Gesture_Layer
 282  */
 283 <<<<<<< HEAD
 284 EAPI Eina_Bool    elm_gesture_layer_hold_events_get(Evas_Object *obj);
 285
 286 /**
 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.
 290  *
 291  * @param obj Pointer to gesture-layer.
 292  * @param r Repeat: TRUE/FALSE
 293  *
 294  * @ingroup Elm_Gesture_Layer
 295  */
 296 EAPI void         elm_gesture_layer_hold_events_set(Evas_Object *obj, Eina_Bool r);
 297 =======
 298 EAPI Eina_Bool    elm_gesture_layer_hold_events_get(const Evas_Object *obj);
 299
 300 /**
 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
 303  * detected.
 304  * Clear this if you like gesture layer to forward events as testing gestures.
 305  *
 306  * @param obj gesture layer.
 307  * @param hold_events hold events or not.
 308  *
 309  * @ingroup Elm_Gesture_Layer
 310  */
 311 EAPI void         elm_gesture_layer_hold_events_set(Evas_Object *obj, Eina_Bool hold_events);
 312 >>>>>>> remotes/origin/upstream
 313
 314 /**
 315  * This function sets step-value for zoom action.
 316  * Set step to any positive value.
 317 <<<<<<< HEAD
 318  * Cancel step setting by setting to 0.0
 319  *
 320  * @param obj Pointer to gesture-layer.
 321  * @param s new zoom step value.
 322  *
 323  * @ingroup Elm_Gesture_Layer
 324  */
 325 EAPI void         elm_gesture_layer_zoom_step_set(Evas_Object *obj, double s);
 326 =======
 327  * Cancel step setting by setting to 0
 328  *
 329  * @param obj gesture-layer.
 330  * @param step new zoom step value.
 331  *
 332  * @see elm_gesture_layer_zoom_step_get()
 333  * @ingroup Elm_Gesture_Layer
 334  */
 335 EAPI void         elm_gesture_layer_zoom_step_set(Evas_Object *obj, double step);
 336
 337 /**
 338  * This function returns step-value for zoom action.
 339  *
 340  * @param obj gesture-layer.
 341  * @return zoom step value.
 342  *
 343  * @see elm_gesture_layer_zoom_step_set()
 344  * @ingroup Elm_Gesture_Layer
 345  */
 346 EAPI double       elm_gesture_layer_zoom_step_get(const Evas_Object *obj);
 347 >>>>>>> remotes/origin/upstream
 348
 349 /**
 350  * This function sets step-value for rotate action.
 351  * Set step to any positive value.
 352 <<<<<<< HEAD
 353  * Cancel step setting by setting to 0.0
 354  *
 355  * @param obj Pointer to gesture-layer.
 356  * @param s new roatate step value.
 357  *
 358  * @ingroup Elm_Gesture_Layer
 359  */
 360 EAPI void         elm_gesture_layer_rotate_step_set(Evas_Object *obj, double s);
 361
 362 /**
 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)
 366 =======
 367  * Cancel step setting by setting to 0
 368  *
 369  * @param obj gesture-layer.
 370  * @param step new rotate step value.
 371  *
 372  * @ingroup Elm_Gesture_Layer
 373  */
 374 EAPI void         elm_gesture_layer_rotate_step_set(Evas_Object *obj, double step);
 375
 376 /**
 377  * This function returns step-value for rotate action.
 378  *
 379  * @param obj gesture-layer.
 380  * @return rotate step value.
 381  *
 382  * @ingroup Elm_Gesture_Layer
 383  */
 384 EAPI double       elm_gesture_layer_rotate_step_get(const Evas_Object *obj);
 385
 386 /**
 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
 391  *
 392  * @return TRUE, FALSE on success, failure.
 393  *
 394  * @ingroup Elm_Gesture_Layer
 395  */
 396 <<<<<<< HEAD
 397 EAPI Eina_Bool    elm_gesture_layer_attach(Evas_Object *obj, Evas_Object *t);
 398 =======
 399 EAPI Eina_Bool    elm_gesture_layer_attach(Evas_Object *obj, Evas_Object *target);
 400 >>>>>>> remotes/origin/upstream
 401
 402 /**
 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.
 406  *
 407  * @param parent the parent object.
 408  *
 409 <<<<<<< HEAD
 410  * @return Pointer to new gesture-layer object.
 411 =======
 412  * @return new gesture-layer object.
 413 >>>>>>> remotes/origin/upstream
 414  *
 415  * @ingroup Elm_Gesture_Layer
 416  */
 417 EAPI Evas_Object *elm_gesture_layer_add(Evas_Object *parent);