src/lib/elm_gesture_layer.h

   1 /**
   2  * @defgroup Elm_Gesture_Layer Gesture Layer
   3  * @ingroup Elementary
   4  *
   5  * @image html gesture_layer_inheritance_tree.png
   6  * @image latex gesture_layer_inheritance_tree.eps
   7  *
   8  * Gesture Layer Usage:
   9  *
  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.
  14  *
  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).
  19  *
  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.
  25  *
  26  * Next, you need to implement the actual action that follows the input
  27  * in your callback.
  28  *
  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)
  32  *
  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.
  38  *
  39  * @ref Elm_Gesture_Momentum_Info is info reported for momentum gestures:
  40  * @ref ELM_GESTURE_MOMENTUM.
  41  *
  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.
  47  *
  48  * @ref Elm_Gesture_Zoom_Info is the info reported for @ref ELM_GESTURE_ZOOM gesture.
  49  *
  50  * @ref Elm_Gesture_Rotate_Info is the info reported for @ref ELM_GESTURE_ROTATE gesture.
  51  *
  52  *
  53  * Gesture Layer Tweaks:
  54  *
  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.
  57  *
  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).
  61  *
  62  * Supported elm_object common APIs.
  63  * @li @ref elm_object_disabled_set
  64  * @li @ref elm_object_disabled_get
  65  *
  66  * @{
  67  *
  68  */
  69
  70 /**
  71  * @enum _Elm_Gesture_Type
  72  * Enum of supported gesture types.
  73  */
  74 enum _Elm_Gesture_Type
  75 {
  76    ELM_GESTURE_FIRST = 0,
  77
  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 */
  82
  83    ELM_GESTURE_MOMENTUM, /**< Reports momentum in the direction of move */
  84
  85    ELM_GESTURE_N_LINES, /**< N fingers line gesture */
  86    ELM_GESTURE_N_FLICKS, /**< N fingers flick gesture */
  87
  88    ELM_GESTURE_ZOOM, /**< Zoom */
  89    ELM_GESTURE_ROTATE, /**< Rotate */
  90
  91    ELM_GESTURE_LAST
  92 };
  93
  94 /**
  95  * @typedef Elm_Gesture_Type
  96  * Convenient macro around #_Elm_Gesture_Type
  97  */
  98 typedef enum _Elm_Gesture_Type Elm_Gesture_Type;
  99
 100 /**
 101  * @enum _Elm_Gesture_State
 102  * Enum of gesture states.
 103  */
 104 enum _Elm_Gesture_State
 105 {
 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 */
 111 };
 112
 113 /**
 114  * @typedef Elm_Gesture_State
 115  * Convenient macro around #_Elm_Gesture_State
 116  */
 117 typedef enum _Elm_Gesture_State Elm_Gesture_State;
 118
 119 /**
 120  * @struct _Elm_Gesture_Taps_Info
 121  * Struct holds taps info for user
 122  */
 123 struct _Elm_Gesture_Taps_Info
 124 {
 125    Evas_Coord   x, y; /**< Holds center point between fingers */
 126    unsigned int n; /**< Number of fingers tapped           */
 127    unsigned int timestamp; /**< event timestamp       */
 128 };
 129
 130 /**
 131  * @typedef Elm_Gesture_Taps_Info
 132  * holds taps info for user
 133  */
 134 typedef struct _Elm_Gesture_Taps_Info Elm_Gesture_Taps_Info;
 135
 136 /**
 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
 143  */
 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   */
 149
 150  unsigned int tx; /**< Timestamp of start of final x-swipe */
 151  unsigned int ty; /**< Timestamp of start of final y-swipe */
 152
 153  Evas_Coord   mx; /**< Momentum on X */
 154  Evas_Coord   my; /**< Momentum on Y */
 155
 156  unsigned int n; /**< Number of fingers */
 157 };
 158
 159 /**
 160  * @typedef Elm_Gesture_Momentum_Info
 161  * holds momentum info for user
 162  */
 163 typedef struct _Elm_Gesture_Momentum_Info Elm_Gesture_Momentum_Info;
 164
 165 /**
 166  * @struct _Elm_Gesture_Line_Info
 167  * Struct holds line info for user
 168  */
 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  */
 172 };
 173
 174 /**
 175  * @typedef Elm_Gesture_Line_Info
 176  * Holds line info for user
 177  */
 178 typedef struct _Elm_Gesture_Line_Info Elm_Gesture_Line_Info;
 179
 180 /**
 181  * @struct _Elm_Gesture_Zoom_Info
 182  * Struct holds zoom info for user
 183  */
 184 struct _Elm_Gesture_Zoom_Info
 185 {
 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) */
 190 };
 191
 192 /**
 193  * @typedef Elm_Gesture_Zoom_Info
 194  * Holds zoom info for user
 195  */
 196 typedef struct _Elm_Gesture_Zoom_Info Elm_Gesture_Zoom_Info;
 197
 198 /**
 199  * @struct _Elm_Gesture_Rotate_Info
 200  * Struct holds rotation info for user
 201  */
 202 struct _Elm_Gesture_Rotate_Info
 203 {
 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) */
 209 };
 210
 211 /**
 212  * @typedef Elm_Gesture_Rotate_Info
 213  * Holds rotation info for user
 214  */
 215 typedef struct _Elm_Gesture_Rotate_Info Elm_Gesture_Rotate_Info;
 216
 217 /**
 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.
 225  *
 226  */
 227 typedef Evas_Event_Flags (*Elm_Gesture_Event_Cb)(void *data, void *event_info);
 228
 229 /**
 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.
 234  *
 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.
 238  *
 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)
 244  *
 245  */
 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);
 247
 248 /**
 249  * Call this function to get repeat-events settings.
 250  *
 251  * @param obj gesture-layer.
 252  *
 253  * @return repeat events settings.
 254  * @see elm_gesture_layer_hold_events_set()
 255  */
 256 EAPI Eina_Bool    elm_gesture_layer_hold_events_get(const Evas_Object *obj);
 257
 258 /**
 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
 261  * detected.
 262  * Clear this if you like gesture layer to forward events as testing gestures.
 263  *
 264  * @param obj gesture layer.
 265  * @param hold_events hold events or not.
 266  *
 267  */
 268 EAPI void         elm_gesture_layer_hold_events_set(Evas_Object *obj, Eina_Bool hold_events);
 269
 270 /**
 271  * This function sets step-value for zoom action.
 272  * Set step to any positive value.
 273  * Cancel step setting by setting to 0
 274  *
 275  * @param obj gesture-layer.
 276  * @param step new zoom step value.
 277  *
 278  * @see elm_gesture_layer_zoom_step_get()
 279  */
 280 EAPI void         elm_gesture_layer_zoom_step_set(Evas_Object *obj, double step);
 281
 282 /**
 283  * This function returns step-value for zoom action.
 284  *
 285  * @param obj gesture-layer.
 286  * @return zoom step value.
 287  *
 288  * @see elm_gesture_layer_zoom_step_set()
 289  */
 290 EAPI double       elm_gesture_layer_zoom_step_get(const Evas_Object *obj);
 291
 292 /**
 293  * This function sets step-value for rotate action.
 294  * Set step to any positive value.
 295  * Cancel step setting by setting to 0
 296  *
 297  * @param obj gesture-layer.
 298  * @param step new rotate step value.
 299  *
 300  */
 301 EAPI void         elm_gesture_layer_rotate_step_set(Evas_Object *obj, double step);
 302
 303 /**
 304  * This function returns step-value for rotate action.
 305  *
 306  * @param obj gesture-layer.
 307  * @return rotate step value.
 308  *
 309  */
 310 EAPI double       elm_gesture_layer_rotate_step_get(const Evas_Object *obj);
 311
 312 /**
 313  * Attach a given gesture layer widget to an Evas object, thus setting
 314  * the widget's @b target.
 315  *
 316  * @param obj A gesture layer to attach an object to.
 317  * @param target Object to attach to @a obj (target)
 318  *
 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.
 322  *
 323  * @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise.
 324  *
 325  */
 326 EAPI Eina_Bool    elm_gesture_layer_attach(Evas_Object *obj, Evas_Object *target);
 327
 328 /**
 329  * Call this function to construct a new gesture-layer object.
 330  *
 331  * @param parent The gesture layer's parent widget.
 332  *
 333  * @return A new gesture layer object.
 334  *
 335  * This does not activate the gesture layer. You have to
 336  * call elm_gesture_layer_attach() in order to 'activate' gesture-layer.
 337  *
 338  */
 339 EAPI Evas_Object *elm_gesture_layer_add(Evas_Object *parent);
 340
 341 /**
 342  * @since 1.8
 343  * This function sets the gesture layer line min length of an object
 344  *
 345  * @param obj gesture-layer.
 346  * @param line_min_length the length.
 347  *
 348  */
 349 EAPI void elm_gesture_layer_line_min_length_set(Evas_Object *obj, int line_min_length);
 350
 351 /**
 352  * @since 1.8
 353  * This function returns the gesture layer line min length of an object
 354  *
 355  * @param obj gesture-layer.
 356  * @return the length.
 357  *
 358  */
 359 EAPI int elm_gesture_layer_line_min_length_get(const Evas_Object *obj);
 360
 361 /**
 362  * @since 1.8
 363  * This function sets the gesture layer zoom distance tolerance of an object
 364  *
 365  * @param obj gesture-layer.
 366  * @param zoom_distance_tolerance zoom distance tolerance
 367  *
 368  */
 369 EAPI void elm_gesture_layer_zoom_distance_tolerance_set(Evas_Object *obj, Evas_Coord zoom_distance_tolerance);
 370
 371 /**
 372  * @since 1.8
 373  * This function returns the gesture layer zoom distance tolerance of an object
 374  *
 375  * @param obj gesture-layer.
 376  * @return zoom distance tolerance
 377  *
 378  */
 379 EAPI Evas_Coord elm_gesture_layer_zoom_distance_tolerance_get(const Evas_Object *obj);
 380
 381 /**
 382  * @since 1.8
 383  * This function sets the gesture layer line distance tolerance of an object
 384  *
 385  * @param obj gesture-layer.
 386  * @param line_distance_tolerance line distance tolerance
 387  *
 388  */
 389 EAPI void elm_gesture_layer_line_distance_tolerance_set(Evas_Object *obj, Evas_Coord line_distance_tolerance);
 390
 391 /**
 392  * @since 1.8
 393  * This function returns the gesture layer line distance tolerance of an object
 394  *
 395  * @param obj gesture-layer.
 396  * @return line distance tolerance
 397  *
 398  */
 399 EAPI Evas_Coord elm_gesture_layer_line_distance_tolerance_get(const Evas_Object *obj);
 400
 401 /**
 402  * @since 1.8
 403  * This function sets the gesture layer line angular tolerance of an object
 404  *
 405  * @param obj gesture-layer.
 406  * @param line_angular_tolerance line angular tolerance
 407  *
 408  */
 409 EAPI void elm_gesture_layer_line_angular_tolerance_set(Evas_Object *obj, double line_angular_tolerance);
 410
 411 /**
 412  * @since 1.8
 413  * This function returns the gesture layer line angular tolerance of an object
 414  *
 415  * @param obj gesture-layer.
 416  * @return line angular tolerance
 417  *
 418  */
 419 EAPI double elm_gesture_layer_line_angular_tolerance_get(const Evas_Object *obj);
 420
 421 /**
 422  * @since 1.8
 423  * This function sets the gesture layer zoom wheel factor of an object
 424  *
 425  * @param obj gesture-layer.
 426  * @param zoom_wheel_factor zoom wheel factor
 427  *
 428  */
 429 EAPI void elm_gesture_layer_zoom_wheel_factor_set(Evas_Object *obj, double zoom_wheel_factor);
 430
 431 /**
 432  * @since 1.8
 433  * This function returns the gesture layer zoom wheel factor of an object
 434  *
 435  * @param obj gesture-layer.
 436  * @return zoom wheel factor
 437  *
 438  */
 439 EAPI double elm_gesture_layer_zoom_wheel_factor_get(const Evas_Object *obj);
 440
 441 /**
 442  * @since 1.8
 443  * This function sets the gesture layer zoom finger factor of an object
 444  *
 445  * @param obj gesture-layer.
 446  * @param zoom_finger_factor zoom finger factor
 447  *
 448  */
 449 EAPI void elm_gesture_layer_zoom_finger_factor_set(Evas_Object *obj, double zoom_finger_factor);
 450
 451 /**
 452  * @since 1.8
 453  * This function returns the gesture layer zoom finger factor of an object
 454  *
 455  * @param obj gesture-layer.
 456  * @return zoom finger factor
 457  *
 458  */
 459 EAPI double elm_gesture_layer_zoom_finger_factor_get(const Evas_Object *obj);
 460
 461 /**
 462  * @since 1.8
 463  * This function sets the gesture layer rotate angular tolerance of an object
 464  *
 465  * @param obj gesture-layer.
 466  * @param rotate_angular_tolerance rotate angular tolerance
 467  *
 468  */
 469 EAPI void elm_gesture_layer_rotate_angular_tolerance_set(Evas_Object *obj, double rotate_angular_tolerance);
 470
 471 /**
 472  * @since 1.8
 473  * This function returns the gesture layer rotate angular tolerance of an object
 474  *
 475  * @param obj gesture-layer.
 476  * @return rotate angular tolerance
 477  *
 478  */
 479 EAPI double elm_gesture_layer_rotate_angular_tolerance_get(const Evas_Object *obj);
 480
 481 /**
 482  * @since 1.8
 483  * This function sets the gesture layer flick time limit (in ms) of an object
 484  *
 485  * @param obj gesture-layer.
 486  * @param flick_time_limit_ms flick time limit (in ms)
 487  *
 488  */
 489 EAPI void elm_gesture_layer_flick_time_limit_ms_set(Evas_Object *obj, unsigned int flick_time_limit_ms);
 490
 491 /**
 492  * @since 1.8
 493  * This function returns the gesture layer flick time limit (in ms) of an object
 494  *
 495  * @param obj gesture-layer.
 496  * @return flick time limit (in ms)
 497  *
 498  */
 499 EAPI unsigned int elm_gesture_layer_flick_time_limit_ms_get(const Evas_Object *obj);
 500
 501 /**
 502  * @since 1.8
 503  * This function sets the gesture layer long tap start timeout of an object
 504  *
 505  * @param obj gesture-layer.
 506  * @param long_tap_start_timeout long tap start timeout
 507  *
 508  */
 509 EAPI void elm_gesture_layer_long_tap_start_timeout_set(Evas_Object *obj, double long_tap_start_timeout);
 510
 511 /**
 512  * @since 1.8
 513  * this function returns the gesture layer long tap start timeout of an object
 514  *
 515  * @param obj gesture-layer.
 516  * @return long tap start timeout
 517  *
 518  */
 519 EAPI double elm_gesture_layer_long_tap_start_timeout_get(const Evas_Object *obj);
 520
 521 /**
 522  * @since 1.8
 523  * This function sets the gesture layer continues enable of an object
 524  *
 525  * @param obj gesture-layer.
 526  * @param continues_enable continues enable
 527  *
 528  */
 529 EAPI void elm_gesture_layer_continues_enable_set(Evas_Object *obj, Eina_Bool continues_enable);
 530
 531 /**
 532  * @since 1.8
 533  * This function returns the gesture layer continues enable of an object
 534  *
 535  * @param obj gesture-layer.
 536  * @return continues enable
 537  *
 538  */
 539 EAPI Eina_Bool elm_gesture_layer_continues_enable_get(const Evas_Object *obj);
 540
 541 /**
 542  * @since 1.8
 543  * This function sets the gesture layer double tap timeout of an object
 544  *
 545  * @param obj gesture-layer.
 546  * @param double_tap_timeout double tap timeout
 547  *
 548  */
 549 EAPI void elm_gesture_layer_double_tap_timeout_set(Evas_Object *obj, double double_tap_timeout);
 550
 551 /**
 552  * @since 1.8
 553  * this function returns the gesture layer double tap timeout of an object
 554  *
 555  * @param obj gesture-layer.
 556  * @return double tap timeout
 557  *
 558  */
 559 EAPI double elm_gesture_layer_double_tap_timeout_get(const Evas_Object *obj);
 560
 561 /**
 562  * @}
 563  */