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