src/lib/elm_gesture_layer.h

   1 /**
   2  * @defgroup Elm_Gesture_Layer Gesture Layer
   3  * @ingroup Elementary
   4  *
   5  * Gesture Layer Usage:
   6  *
   7  * Use Gesture Layer to detect gestures.
   8  * The advantage is that you don't have to implement
   9  * gesture detection, just set callbacks of gesture state.
  10  * By using gesture layer we make standard interface.
  11  *
  12  * In order to use Gesture Layer you start with @ref elm_gesture_layer_add
  13  * with a parent object parameter.
  14  * Next 'activate' gesture layer with a @ref elm_gesture_layer_attach
  15  * call. Usually with same object as target (2nd parameter).
  16  *
  17  * Now you need to tell gesture layer what gestures you follow.
  18  * This is done with @ref elm_gesture_layer_cb_set call.
  19  * By setting the callback you actually saying to gesture layer:
  20  * I would like to know when the gesture @ref Elm_Gesture_Type
  21  * switches to state @ref Elm_Gesture_State.
  22  *
  23  * Next, you need to implement the actual action that follows the input
  24  * in your callback.
  25  *
  26  * Note that if you like to stop being reported about a gesture, just set
  27  * all callbacks referring this gesture to NULL.
  28  * (again with @ref elm_gesture_layer_cb_set)
  29  *
  30  * The information reported by gesture layer to your callback is depending
  31  * on @ref Elm_Gesture_Type:
  32  * @ref Elm_Gesture_Taps_Info is the info reported for tap gestures:
  33  * @ref ELM_GESTURE_N_TAPS, @ref ELM_GESTURE_N_LONG_TAPS,
  34  * @ref ELM_GESTURE_N_DOUBLE_TAPS, @ref ELM_GESTURE_N_TRIPLE_TAPS.
  35  *
  36  * @ref Elm_Gesture_Momentum_Info is info reported for momentum gestures:
  37  * @ref ELM_GESTURE_MOMENTUM.
  38  *
  39  * @ref Elm_Gesture_Line_Info is the info reported for line gestures:
  40  * (this also contains @ref Elm_Gesture_Momentum_Info internal structure)
  41  * @ref ELM_GESTURE_N_LINES, @ref ELM_GESTURE_N_FLICKS.
  42  * Note that we consider a flick as a line-gesture that should be completed
  43  * in flick-time-limit as defined in @ref Config.
  44  *
  45  * @ref Elm_Gesture_Zoom_Info is the info reported for @ref ELM_GESTURE_ZOOM gesture.
  46  *
  47  * @ref Elm_Gesture_Rotate_Info is the info reported for @ref ELM_GESTURE_ROTATE gesture.
  48  *
  49  *
  50  * Gesture Layer Tweaks:
  51  *
  52  * Note that line, flick, gestures can start without the need to remove fingers from surface.
  53  * When user fingers rests on same-spot gesture is ended and starts again when fingers moved.
  54  *
  55  * Setting glayer_continues_enable to false in @ref Config will change this behavior
  56  * so gesture starts when user touches (a *DOWN event) touch-surface
  57  * and ends when no fingers touches surface (a *UP event).
  58  *
  59  * Supported elm_object common APIs.
  60  * @li @ref elm_object_disabled_set
  61  * @li @ref elm_object_disabled_get
  62  *
  63  */
  64
  65 /**
  66  * Enum of supported gesture types.
  67  * @ingroup Elm_Gesture_Layer
  68  */
  69 typedef enum
  70 {
  71    ELM_GESTURE_FIRST = 0,
  72
  73    ELM_GESTURE_N_TAPS, /**< N fingers single taps */
  74    ELM_GESTURE_N_LONG_TAPS, /**< N fingers single long-taps */
  75    ELM_GESTURE_N_DOUBLE_TAPS, /**< N fingers double-single taps */
  76    ELM_GESTURE_N_TRIPLE_TAPS, /**< N fingers triple-single taps */
  77
  78    ELM_GESTURE_MOMENTUM, /**< Reports momentum in the direction of move */
  79
  80    ELM_GESTURE_N_LINES, /**< N fingers line gesture */
  81    ELM_GESTURE_N_FLICKS, /**< N fingers flick gesture */
  82
  83    ELM_GESTURE_ZOOM, /**< Zoom */
  84    ELM_GESTURE_ROTATE, /**< Rotate */
  85
  86    ELM_GESTURE_LAST
  87 } Elm_Gesture_Type;
  88
  89 /**
  90  * @enum _Elm_Gesture_State
  91  * Enum of gesture states.
  92  * @ingroup Elm_Gesture_Layer
  93  */
  94 typedef enum
  95 {
  96    ELM_GESTURE_STATE_UNDEFINED = -1, /**< Gesture not STARTed */
  97    ELM_GESTURE_STATE_START, /**< Gesture STARTed     */
  98    ELM_GESTURE_STATE_MOVE, /**< Gesture is ongoing  */
  99    ELM_GESTURE_STATE_END, /**< Gesture completed   */
 100    ELM_GESTURE_STATE_ABORT /**< Ongoing gesture was ABORTed */
 101 } Elm_Gesture_State;
 102
 103 /**
 104  * @struct _Elm_Gesture_Taps_Info
 105  * Struct holds taps info for user
 106  * @ingroup Elm_Gesture_Layer
 107  */
 108 struct _Elm_Gesture_Taps_Info
 109 {
 110    Evas_Coord   x, y; /**< Holds center point between fingers */
 111    unsigned int n; /**< Number of fingers tapped           */
 112    unsigned int timestamp; /**< event timestamp       */
 113 };
 114
 115 /**
 116  * @typedef Elm_Gesture_Taps_Info
 117  * holds taps info for user
 118  * @ingroup Elm_Gesture_Layer
 119  */
 120 typedef struct _Elm_Gesture_Taps_Info Elm_Gesture_Taps_Info;
 121
 122 /**
 123  * @struct _Elm_Gesture_Momentum_Info
 124  * Struct holds momentum info for user
 125  * x1 and y1 are not necessarily in sync
 126  * x1 holds x value of x direction starting point
 127  * and same holds for y1.
 128  * This is noticeable when doing V-shape movement
 129  * @ingroup Elm_Gesture_Layer
 130  */
 131 struct _Elm_Gesture_Momentum_Info /* Report line ends, timestamps, and momentum computed        */
 132 {Evas_Coord   x1; /**< Final-swipe direction starting point on X */
 133  Evas_Coord   y1; /**< Final-swipe direction starting point on Y */
 134  Evas_Coord   x2; /**< Final-swipe direction ending point on X   */
 135  Evas_Coord   y2; /**< Final-swipe direction ending point on Y   */
 136
 137  unsigned int tx; /**< Timestamp of start of final x-swipe */
 138  unsigned int ty; /**< Timestamp of start of final y-swipe */
 139
 140  Evas_Coord   mx; /**< Momentum on X */
 141  Evas_Coord   my; /**< Momentum on Y */
 142
 143  unsigned int n; /**< Number of fingers */
 144 };
 145
 146 /**
 147  * @typedef Elm_Gesture_Momentum_Info
 148  * holds momentum info for user
 149  * @ingroup Elm_Gesture_Layer
 150  */
 151 typedef struct _Elm_Gesture_Momentum_Info Elm_Gesture_Momentum_Info;
 152
 153 /**
 154  * @struct _Elm_Gesture_Line_Info
 155  * Struct holds line info for user
 156  * @ingroup Elm_Gesture_Layer
 157  */
 158 struct _Elm_Gesture_Line_Info   /* Report line ends, timestamps, and momentum computed      */
 159 {Elm_Gesture_Momentum_Info momentum; /**< Line momentum info */
 160  double                    angle; /**< Angle (direction) of lines  */
 161 };
 162
 163 /**
 164  * @typedef Elm_Gesture_Line_Info
 165  * Holds line info for user
 166  * @ingroup Elm_Gesture_Layer
 167  */
 168 typedef struct _Elm_Gesture_Line_Info Elm_Gesture_Line_Info;
 169
 170 /**
 171  * @struct _Elm_Gesture_Zoom_Info
 172  * Struct holds zoom info for user
 173  * @ingroup Elm_Gesture_Layer
 174  */
 175 struct _Elm_Gesture_Zoom_Info
 176 {
 177    Evas_Coord x, y; /**< Holds zoom center point reported to user  */
 178    Evas_Coord radius; /**< Holds radius between fingers reported to user */
 179    double     zoom; /**< Zoom value: 1.0 means no zoom             */
 180    double     momentum; /**< Zoom momentum: zoom growth per second (NOT YET SUPPORTED) */
 181 };
 182
 183 /**
 184  * @typedef Elm_Gesture_Zoom_Info
 185  * Holds zoom info for user
 186  * @ingroup Elm_Gesture_Layer
 187  */
 188 typedef struct _Elm_Gesture_Zoom_Info Elm_Gesture_Zoom_Info;
 189
 190 /**
 191  * @struct _Elm_Gesture_Rotate_Info
 192  * Struct holds rotation info for user
 193  * @ingroup Elm_Gesture_Layer
 194  */
 195 struct _Elm_Gesture_Rotate_Info
 196 {
 197    Evas_Coord x, y; /**< Holds zoom center point reported to user      */
 198    Evas_Coord radius; /**< Holds radius between fingers reported to user */
 199    double     base_angle; /**< Holds start-angle */
 200    double     angle; /**< Rotation value: 0.0 means no rotation         */
 201    double     momentum; /**< Rotation momentum: rotation done per second (NOT YET SUPPORTED) */
 202 };
 203
 204 /**
 205  * @typedef Elm_Gesture_Rotate_Info
 206  * Holds rotation info for user
 207  * @ingroup Elm_Gesture_Layer
 208  */
 209 typedef struct _Elm_Gesture_Rotate_Info Elm_Gesture_Rotate_Info;
 210
 211 /**
 212  * @typedef Elm_Gesture_Event_Cb
 213  * User callback used to stream gesture info from gesture layer
 214  * @param data user data
 215  * @param event_info gesture report info
 216  * Returns a flag field to be applied on the causing event.
 217  * You should probably return EVAS_EVENT_FLAG_ON_HOLD if your widget acted
 218  * upon the event, in an irreversible way.
 219  *
 220  * @ingroup Elm_Gesture_Layer
 221  */
 222 typedef Evas_Event_Flags (*Elm_Gesture_Event_Cb)(void *data, void *event_info);
 223
 224 /**
 225  * Use function to set callbacks to be notified about
 226  * change of state of gesture.
 227  * When a user registers a callback with this function
 228  * this means this gesture has to be tested.
 229  *
 230  * When ALL callbacks for a gesture are set to NULL
 231  * it means user isn't interested in gesture-state
 232  * and it will not be tested.
 233  *
 234  * @param obj gesture-layer.
 235  * @param idx The gesture you would like to track its state.
 236  * @param cb callback function pointer.
 237  * @param cb_type what event this callback tracks: START, MOVE, END, ABORT.
 238  * @param data user info to be sent to callback (usually, Smart Data)
 239  *
 240  * @ingroup Elm_Gesture_Layer
 241  */
 242 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);
 243
 244 /**
 245  * Call this function to get repeat-events settings.
 246  *
 247  * @param obj gesture-layer.
 248  *
 249  * @return repeat events settings.
 250  * @see elm_gesture_layer_hold_events_set()
 251  * @ingroup Elm_Gesture_Layer
 252  */
 253 EAPI Eina_Bool    elm_gesture_layer_hold_events_get(const Evas_Object *obj);
 254
 255 /**
 256  * This function is to make gesture-layer repeat events.
 257  * Set this if you like to get the raw events only if gestures were not
 258  * detected.
 259  * Clear this if you like gesture layer to forward events as testing gestures.
 260  *
 261  * @param obj gesture layer.
 262  * @param hold_events hold events or not.
 263  *
 264  * @ingroup Elm_Gesture_Layer
 265  */
 266 EAPI void         elm_gesture_layer_hold_events_set(Evas_Object *obj, Eina_Bool hold_events);
 267
 268 /**
 269  * This function sets step-value for zoom action.
 270  * Set step to any positive value.
 271  * Cancel step setting by setting to 0
 272  *
 273  * @param obj gesture-layer.
 274  * @param step new zoom step value.
 275  *
 276  * @see elm_gesture_layer_zoom_step_get()
 277  * @ingroup Elm_Gesture_Layer
 278  */
 279 EAPI void         elm_gesture_layer_zoom_step_set(Evas_Object *obj, double step);
 280
 281 /**
 282  * This function returns step-value for zoom action.
 283  *
 284  * @param obj gesture-layer.
 285  * @return zoom step value.
 286  *
 287  * @see elm_gesture_layer_zoom_step_set()
 288  * @ingroup Elm_Gesture_Layer
 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  * @ingroup Elm_Gesture_Layer
 301  */
 302 EAPI void         elm_gesture_layer_rotate_step_set(Evas_Object *obj, double step);
 303
 304 /**
 305  * This function returns step-value for rotate action.
 306  *
 307  * @param obj gesture-layer.
 308  * @return rotate step value.
 309  *
 310  * @ingroup Elm_Gesture_Layer
 311  */
 312 EAPI double       elm_gesture_layer_rotate_step_get(const Evas_Object *obj);
 313
 314 /**
 315  * This function called to attach gesture-layer to an Evas_Object.
 316  * @param obj gesture-layer.
 317  * @param target Pointer to underlying object (AKA Target)
 318  *
 319  * @return TRUE, FALSE on success, failure.
 320  *
 321  * @ingroup Elm_Gesture_Layer
 322  */
 323 EAPI Eina_Bool    elm_gesture_layer_attach(Evas_Object *obj, Evas_Object *target);
 324
 325 /**
 326  * Call this function to construct a new gesture-layer object.
 327  * This does not activate the gesture layer. You have to
 328  * call elm_gesture_layer_attach in order to 'activate' gesture-layer.
 329  *
 330  * @param parent the parent object.
 331  *
 332  * @return new gesture-layer object.
 333  *
 334  * @ingroup Elm_Gesture_Layer
 335  */
 336 EAPI Evas_Object *elm_gesture_layer_add(Evas_Object *parent);