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
  67 /**
  68  * @enum _Elm_Gesture_Type
  69  * Enum of supported gesture types.
  70  */
  71 enum _Elm_Gesture_Type
  72 {
  73    ELM_GESTURE_FIRST = 0,
  74
  75    ELM_GESTURE_N_TAPS, /**< N fingers single taps */
  76    ELM_GESTURE_N_LONG_TAPS, /**< N fingers single long-taps */
  77    ELM_GESTURE_N_DOUBLE_TAPS, /**< N fingers double-single taps */
  78    ELM_GESTURE_N_TRIPLE_TAPS, /**< N fingers triple-single taps */
  79
  80    ELM_GESTURE_MOMENTUM, /**< Reports momentum in the direction of move */
  81
  82    ELM_GESTURE_N_LINES, /**< N fingers line gesture */
  83    ELM_GESTURE_N_FLICKS, /**< N fingers flick gesture */
  84
  85    ELM_GESTURE_ZOOM, /**< Zoom */
  86    ELM_GESTURE_ROTATE, /**< Rotate */
  87
  88    ELM_GESTURE_LAST
  89 };
  90
  91 /**
  92  * @typedef Elm_Gesture_Type
  93  * Convenient macro around #_Elm_Gesture_Type
  94  */
  95 typedef enum _Elm_Gesture_Type Elm_Gesture_Type;
  96
  97 /**
  98  * @enum _Elm_Gesture_State
  99  * Enum of gesture states.
 100  */
 101 enum _Elm_Gesture_State
 102 {
 103    ELM_GESTURE_STATE_UNDEFINED = -1, /**< Gesture not STARTed */
 104    ELM_GESTURE_STATE_START, /**< Gesture STARTed     */
 105    ELM_GESTURE_STATE_MOVE, /**< Gesture is ongoing  */
 106    ELM_GESTURE_STATE_END, /**< Gesture completed   */
 107    ELM_GESTURE_STATE_ABORT /**< Ongoing gesture was ABORTed */
 108 };
 109
 110 /**
 111  * @typedef Elm_Gesture_State
 112  * Convenient macro around #_Elm_Gesture_State
 113  */
 114 typedef enum _Elm_Gesture_State Elm_Gesture_State;
 115
 116 /**
 117  * @struct _Elm_Gesture_Taps_Info
 118  * Struct holds taps info for user
 119  */
 120 struct _Elm_Gesture_Taps_Info
 121 {
 122    Evas_Coord   x, y; /**< Holds center point between fingers */
 123    unsigned int n; /**< Number of fingers tapped           */
 124    unsigned int timestamp; /**< event timestamp       */
 125 };
 126
 127 /**
 128  * @typedef Elm_Gesture_Taps_Info
 129  * holds taps info for user
 130  */
 131 typedef struct _Elm_Gesture_Taps_Info Elm_Gesture_Taps_Info;
 132
 133 /**
 134  * @struct _Elm_Gesture_Momentum_Info
 135  * Struct holds momentum info for user
 136  * x1 and y1 are not necessarily in sync
 137  * x1 holds x value of x direction starting point
 138  * and same holds for y1.
 139  * This is noticeable when doing V-shape movement
 140  */
 141 struct _Elm_Gesture_Momentum_Info /* Report line ends, timestamps, and momentum computed        */
 142 {Evas_Coord   x1; /**< Final-swipe direction starting point on X */
 143  Evas_Coord   y1; /**< Final-swipe direction starting point on Y */
 144  Evas_Coord   x2; /**< Final-swipe direction ending point on X   */
 145  Evas_Coord   y2; /**< Final-swipe direction ending point on Y   */
 146
 147  unsigned int tx; /**< Timestamp of start of final x-swipe */
 148  unsigned int ty; /**< Timestamp of start of final y-swipe */
 149
 150  Evas_Coord   mx; /**< Momentum on X */
 151  Evas_Coord   my; /**< Momentum on Y */
 152
 153  unsigned int n; /**< Number of fingers */
 154 };
 155
 156 /**
 157  * @typedef Elm_Gesture_Momentum_Info
 158  * holds momentum info for user
 159  */
 160 typedef struct _Elm_Gesture_Momentum_Info Elm_Gesture_Momentum_Info;
 161
 162 /**
 163  * @struct _Elm_Gesture_Line_Info
 164  * Struct holds line info for user
 165  */
 166 struct _Elm_Gesture_Line_Info   /* Report line ends, timestamps, and momentum computed      */
 167 {Elm_Gesture_Momentum_Info momentum; /**< Line momentum info */
 168  double                    angle; /**< Angle (direction) of lines  */
 169 };
 170
 171 /**
 172  * @typedef Elm_Gesture_Line_Info
 173  * Holds line info for user
 174  */
 175 typedef struct _Elm_Gesture_Line_Info Elm_Gesture_Line_Info;
 176
 177 /**
 178  * @struct _Elm_Gesture_Zoom_Info
 179  * Struct holds zoom info for user
 180  */
 181 struct _Elm_Gesture_Zoom_Info
 182 {
 183    Evas_Coord x, y; /**< Holds zoom center point reported to user  */
 184    Evas_Coord radius; /**< Holds radius between fingers reported to user */
 185    double     zoom; /**< Zoom value: 1.0 means no zoom             */
 186    double     momentum; /**< Zoom momentum: zoom growth per second (NOT YET SUPPORTED) */
 187 };
 188
 189 /**
 190  * @typedef Elm_Gesture_Zoom_Info
 191  * Holds zoom info for user
 192  */
 193 typedef struct _Elm_Gesture_Zoom_Info Elm_Gesture_Zoom_Info;
 194
 195 /**
 196  * @struct _Elm_Gesture_Rotate_Info
 197  * Struct holds rotation info for user
 198  */
 199 struct _Elm_Gesture_Rotate_Info
 200 {
 201    Evas_Coord x, y; /**< Holds zoom center point reported to user      */
 202    Evas_Coord radius; /**< Holds radius between fingers reported to user */
 203    double     base_angle; /**< Holds start-angle */
 204    double     angle; /**< Rotation value: 0.0 means no rotation         */
 205    double     momentum; /**< Rotation momentum: rotation done per second (NOT YET SUPPORTED) */
 206 };
 207
 208 /**
 209  * @typedef Elm_Gesture_Rotate_Info
 210  * Holds rotation info for user
 211  */
 212 typedef struct _Elm_Gesture_Rotate_Info Elm_Gesture_Rotate_Info;
 213
 214 /**
 215  * @typedef Elm_Gesture_Event_Cb
 216  * User callback used to stream gesture info from gesture layer
 217  * @param data user data
 218  * @param event_info gesture report info
 219  * Returns a flag field to be applied on the causing event.
 220  * You should probably return EVAS_EVENT_FLAG_ON_HOLD if your widget acted
 221  * upon the event, in an irreversible way.
 222  *
 223  */
 224 typedef Evas_Event_Flags (*Elm_Gesture_Event_Cb)(void *data, void *event_info);
 225
 226 /**
 227  * Use function to set callbacks to be notified about
 228  * change of state of gesture.
 229  * When a user registers a callback with this function
 230  * this means this gesture has to be tested.
 231  *
 232  * When ALL callbacks for a gesture are set to NULL
 233  * it means user isn't interested in gesture-state
 234  * and it will not be tested.
 235  *
 236  * @param obj gesture-layer.
 237  * @param idx The gesture you would like to track its state.
 238  * @param cb callback function pointer.
 239  * @param cb_type what event this callback tracks: START, MOVE, END, ABORT.
 240  * @param data user info to be sent to callback (usually, Smart Data)
 241  *
 242  */
 243 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);
 244
 245 /**
 246  * Call this function to get repeat-events settings.
 247  *
 248  * @param obj gesture-layer.
 249  *
 250  * @return repeat events settings.
 251  * @see elm_gesture_layer_hold_events_set()
 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  */
 265 EAPI void         elm_gesture_layer_hold_events_set(Evas_Object *obj, Eina_Bool hold_events);
 266
 267 /**
 268  * This function sets step-value for zoom action.
 269  * Set step to any positive value.
 270  * Cancel step setting by setting to 0
 271  *
 272  * @param obj gesture-layer.
 273  * @param step new zoom step value.
 274  *
 275  * @see elm_gesture_layer_zoom_step_get()
 276  */
 277 EAPI void         elm_gesture_layer_zoom_step_set(Evas_Object *obj, double step);
 278
 279 /**
 280  * This function returns step-value for zoom action.
 281  *
 282  * @param obj gesture-layer.
 283  * @return zoom step value.
 284  *
 285  * @see elm_gesture_layer_zoom_step_set()
 286  */
 287 EAPI double       elm_gesture_layer_zoom_step_get(const Evas_Object *obj);
 288
 289 /**
 290  * This function sets step-value for rotate action.
 291  * Set step to any positive value.
 292  * Cancel step setting by setting to 0
 293  *
 294  * @param obj gesture-layer.
 295  * @param step new rotate step value.
 296  *
 297  */
 298 EAPI void         elm_gesture_layer_rotate_step_set(Evas_Object *obj, double step);
 299
 300 /**
 301  * This function returns step-value for rotate action.
 302  *
 303  * @param obj gesture-layer.
 304  * @return rotate step value.
 305  *
 306  */
 307 EAPI double       elm_gesture_layer_rotate_step_get(const Evas_Object *obj);
 308
 309 /**
 310  * This function called to attach gesture-layer to an Evas_Object.
 311  * @param obj gesture-layer.
 312  * @param target Pointer to underlying object (AKA Target)
 313  *
 314  * @return TRUE, FALSE on success, failure.
 315  *
 316  */
 317 EAPI Eina_Bool    elm_gesture_layer_attach(Evas_Object *obj, Evas_Object *target);
 318
 319 /**
 320  * Call this function to construct a new gesture-layer object.
 321  * This does not activate the gesture layer. You have to
 322  * call elm_gesture_layer_attach in order to 'activate' gesture-layer.
 323  *
 324  * @param parent the parent object.
 325  *
 326  * @return new gesture-layer object.
 327  *
 328  */
 329 EAPI Evas_Object *elm_gesture_layer_add(Evas_Object *parent);
 330
 331 /**
 332  * @}
 333  */