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