## ClutterGestureAction

ClutterGestureAction — Action for gesture gestures

## Synopsis

    struct              ClutterGestureAction;
    struct              ClutterGestureActionClass;
    ClutterAction *     clutter_gesture_action_new          (void);
    const ClutterEvent * clutter_gesture_action_get_last_event
                                                            (ClutterGestureAction *action,
                                                             guint point);
    void                clutter_gesture_action_get_press_coords
                                                            (ClutterGestureAction *action,
                                                             guint point,
                                                             gfloat *press_x,
                                                             gfloat *press_y);
    void                clutter_gesture_action_get_motion_coords
                                                            (ClutterGestureAction *action,
                                                             guint point,
                                                             gfloat *motion_x,
                                                             gfloat *motion_y);
    gfloat              clutter_gesture_action_get_motion_delta
                                                            (ClutterGestureAction *action,
                                                             guint point,
                                                             gfloat *delta_x,
                                                             gfloat *delta_y);
    void                clutter_gesture_action_get_release_coords
                                                            (ClutterGestureAction *action,
                                                             guint point,
                                                             gfloat *release_x,
                                                             gfloat *release_y);
    gfloat              clutter_gesture_action_get_velocity (ClutterGestureAction *action,
                                                             guint point,
                                                             gfloat *velocity_x,
                                                             gfloat *velocity_y);
    gint                clutter_gesture_action_get_n_touch_points
                                                            (ClutterGestureAction *action);
    void                clutter_gesture_action_set_n_touch_points
                                                            (ClutterGestureAction *action,
                                                             gint nb_points);
    guint               clutter_gesture_action_get_n_current_points
                                                            (ClutterGestureAction *action);
    ClutterEventSequence * clutter_gesture_action_get_sequence
                                                            (ClutterGestureAction *action,
                                                             guint point);
    ClutterInputDevice * clutter_gesture_action_get_device  (ClutterGestureAction *action,
                                                             guint point);
    void                clutter_gesture_action_cancel       (ClutterGestureAction *action);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterActorMeta
                   +----ClutterAction
                         +----ClutterGestureAction
                               +----ClutterPanAction
                               +----ClutterRotateAction
                               +----ClutterSwipeAction
                               +----ClutterTapAction
                               +----ClutterZoomAction

## Signals

      "gesture-begin"                                  : Run Last
      "gesture-cancel"                                 : Run Last
      "gesture-end"                                    : Run Last
      "gesture-progress"                               : Run Last

## Description

ClutterGestureAction is a sub-class of ClutterAction that implements the logic for recognizing gesture gestures. It listens for low level events such as ClutterButtonEvent and ClutterMotionEvent on the stage to raise the "gesture-begin", "gesture-progress", and "gesture-end" signals.

To use ClutterGestureAction you just need to apply it to a ClutterActor using `clutter_actor_add_action()` and connect to the signals:

    1
    2
    3
    4
    5
    6
    7

    ClutterAction *action = clutter_gesture_action_new ();

    clutter_actor_add_action (actor, action);

    g_signal_connect (action, "gesture-begin", G_CALLBACK (on_gesture_begin), NULL);
    g_signal_connect (action, "gesture-progress", G_CALLBACK (on_gesture_progress), NULL);
    g_signal_connect (action, "gesture-end", G_CALLBACK (on_gesture_end), NULL);

### Creating Gesture actions

A ClutterGestureAction provides four separate states that can be used to recognize or ignore gestures when writing a new action class:

    1
    2
    3
    4
    5

    Prepare -> Cancel
    Prepare -> Begin -> Cancel
    Prepare -> Begin -> End
    Prepare -> Begin -> Progress -> Cancel
    Prepare -> Begin -> Progress -> End

Each ClutterGestureAction starts in the "prepare" state, and calls the `ClutterGestureActionClass.gesture_prepare()` virtual function; this state can be used to reset the internal state of a ClutterGestureAction subclass, but it can also immediately cancel a gesture without going through the rest of the states.

The "begin" state follows the "prepare" state, and calls the `ClutterGestureActionClass.gesture_begin()` virtual function. This state signals the start of a gesture recognizing process. From the "begin" state the gesture recognition process can successfully end, by going to the "end" state; it can continue in the "progress" state, in case of a continuous gesture; or it can be terminated, by moving to the "cancel" state.

In case of continuous gestures, the ClutterGestureAction will use the "progress" state, calling the `ClutterGestureActionClass.gesture_progress()` virtual function; the "progress" state will continue until the end of the gesture, in which case the "end" state will be reached, or until the gesture is cancelled, in which case the "cancel" gesture will be used instead.

## Details

### struct ClutterGestureAction

    struct ClutterGestureAction;

The ClutterGestureAction structure contains only private data and should be accessed using the provided API

Since 1.8

### struct ClutterGestureActionClass

    struct ClutterGestureActionClass {
      gboolean (* gesture_begin)    (ClutterGestureAction  *action,
                                     ClutterActor          *actor);
      gboolean (* gesture_progress) (ClutterGestureAction  *action,
                                     ClutterActor          *actor);
      void     (* gesture_end)      (ClutterGestureAction  *action,
                                     ClutterActor          *actor);
      void     (* gesture_cancel)   (ClutterGestureAction  *action,
                                     ClutterActor          *actor);
      gboolean (* gesture_prepare)  (ClutterGestureAction  *action,
                                     ClutterActor          *actor);
    };

The ClutterGestureClass structure contains only private data.

`gesture_begin` () | class handler for the "gesture-begin" signal
`gesture_progress` () | class handler for the "gesture-progress" signal
`gesture_end` () | class handler for the "gesture-end" signal
`gesture_cancel` () | class handler for the "gesture-cancel" signal
`gesture_prepare` () | virtual function called before emitting the "gesture-cancel" signal

Since 1.8

### clutter_gesture_action_new ()

    ClutterAction *     clutter_gesture_action_new          (void);

Creates a new ClutterGestureAction instance.

Returns : | the newly created ClutterGestureAction

Since 1.8

### clutter_gesture_action_get_last_event ()

    const ClutterEvent * clutter_gesture_action_get_last_event
                                                            (ClutterGestureAction *action,
                                                             guint point);

Retrieves a reference to the last ClutterEvent for a touch point. Call `clutter_event_copy()` if you need to store the reference somewhere.

`action` : | a ClutterGestureAction
`point` : | index of a point currently active
Returns : | the last ClutterEvent for a touch point. [transfer none]

Since 1.14

### clutter_gesture_action_get_press_coords ()

    void                clutter_gesture_action_get_press_coords
                                                            (ClutterGestureAction *action,
                                                             guint point,
                                                             gfloat *press_x,
                                                             gfloat *press_y);

Retrieves the coordinates, in stage space, of the press event that started the dragging for a specific touch point.

`action` : | a ClutterGestureAction
`point` : | the touch point index, with 0 being the first touch point received by the action
`press_x` : | return location for the press event's X coordinate. [out][allow-none]
`press_y` : | return location for the press event's Y coordinate. [out][allow-none]

Since 1.8

### clutter_gesture_action_get_motion_coords ()

    void                clutter_gesture_action_get_motion_coords
                                                            (ClutterGestureAction *action,
                                                             guint point,
                                                             gfloat *motion_x,
                                                             gfloat *motion_y);

Retrieves the coordinates, in stage space, of the latest motion event during the dragging.

`action` : | a ClutterGestureAction
`point` : | the touch point index, with 0 being the first touch point received by the action
`motion_x` : | return location for the latest motion event's X coordinate. [out][allow-none]
`motion_y` : | return location for the latest motion event's Y coordinate. [out][allow-none]

Since 1.8

### clutter_gesture_action_get_motion_delta ()

    gfloat              clutter_gesture_action_get_motion_delta
                                                            (ClutterGestureAction *action,
                                                             guint point,
                                                             gfloat *delta_x,
                                                             gfloat *delta_y);

Retrieves the incremental delta since the last motion event during the dragging.

`action` : | a ClutterGestureAction
`point` : | the touch point index, with 0 being the first touch point received by the action
`delta_x` : | return location for the X axis component of the incremental motion delta. [out][allow-none]
`delta_y` : | return location for the Y axis component of the incremental motion delta. [out][allow-none]
Returns : | the distance since last motion event

Since 1.12

### clutter_gesture_action_get_release_coords ()

    void                clutter_gesture_action_get_release_coords
                                                            (ClutterGestureAction *action,
                                                             guint point,
                                                             gfloat *release_x,
                                                             gfloat *release_y);

Retrieves the coordinates, in stage space, where the touch point was last released.

`action` : | a ClutterGestureAction
`point` : | the touch point index, with 0 being the first touch point received by the action
`release_x` : | return location for the X coordinate of the last release. [out][allow-none]
`release_y` : | return location for the Y coordinate of the last release. [out][allow-none]

Since 1.8

### clutter_gesture_action_get_velocity ()

    gfloat              clutter_gesture_action_get_velocity (ClutterGestureAction *action,
                                                             guint point,
                                                             gfloat *velocity_x,
                                                             gfloat *velocity_y);

Retrieves the velocity, in stage pixels per millisecond, of the latest motion event during the dragging.

`action` : | a ClutterGestureAction
`point` : | the touch point index, with 0 being the first touch point received by the action
`velocity_x` : | return location for the latest motion event's X velocity. [out][allow-none]
`velocity_y` : | return location for the latest motion event's Y velocity. [out][allow-none]

Since 1.12

### clutter_gesture_action_get_n_touch_points ()

    gint                clutter_gesture_action_get_n_touch_points
                                                            (ClutterGestureAction *action);

Retrieves the number of requested points to trigger the gesture.

`action` : | a ClutterGestureAction
Returns : | the number of points to trigger the gesture.

Since 1.12

### clutter_gesture_action_set_n_touch_points ()

    void                clutter_gesture_action_set_n_touch_points
                                                            (ClutterGestureAction *action,
                                                             gint nb_points);

Sets the number of points needed to trigger the gesture.

`action` : | a ClutterGestureAction
`nb_points` : | a number of points

Since 1.12

### clutter_gesture_action_get_n_current_points ()

    guint               clutter_gesture_action_get_n_current_points
                                                            (ClutterGestureAction *action);

Retrieves the number of points currently active.

`action` : | a ClutterGestureAction
Returns : | the number of points currently active.

Since 1.12

### clutter_gesture_action_get_sequence ()

    ClutterEventSequence * clutter_gesture_action_get_sequence
                                                            (ClutterGestureAction *action,
                                                             guint point);

Retrieves the ClutterEventSequence of a touch point.

`action` : | a ClutterGestureAction
`point` : | index of a point currently active
Returns : | the ClutterEventSequence of a touch point. [transfer none]

Since 1.12

### clutter_gesture_action_get_device ()

    ClutterInputDevice * clutter_gesture_action_get_device  (ClutterGestureAction *action,
                                                             guint point);

Retrieves the ClutterInputDevice of a touch point.

`action` : | a ClutterGestureAction
`point` : | the touch point index, with 0 being the first touch point received by the action
Returns : | the ClutterInputDevice of a touch point. [transfer none]

Since 1.12

### clutter_gesture_action_cancel ()

    void                clutter_gesture_action_cancel       (ClutterGestureAction *action);

Cancel a ClutterGestureAction before it begins

`action` : | a ClutterGestureAction

Since 1.12

## Signal Details

### The `"gesture-begin"` signal

    gboolean            user_function                      (ClutterGestureAction *action,
                                                            ClutterActor         *actor,
                                                            gpointer              user_data)      : Run Last

The ::gesture_begin signal is emitted when the ClutterActor to which a ClutterGestureAction has been applied starts receiving a gesture.

`action` : | the ClutterGestureAction that emitted the signal
`actor` : | the ClutterActor attached to the `action`
`user_data` : | user data set when the signal handler was connected.
Returns : | `TRUE` if the gesture should start, and `FALSE` if the gesture should be ignored.

Since 1.8

### The `"gesture-cancel"` signal

    void                user_function                      (ClutterGestureAction *action,
                                                            ClutterActor         *actor,
                                                            gpointer              user_data)      : Run Last

The ::gesture-cancel signal is emitted when the ongoing gesture gets cancelled from the "gesture-progress" signal handler.

This signal is emitted if and only if the "gesture-begin" signal has been emitted first.

`action` : | the ClutterGestureAction that emitted the signal
`actor` : | the ClutterActor attached to the `action`
`user_data` : | user data set when the signal handler was connected.

Since 1.8

### The `"gesture-end"` signal

    void                user_function                      (ClutterGestureAction *action,
                                                            ClutterActor         *actor,
                                                            gpointer              user_data)      : Run Last

The ::gesture-end signal is emitted at the end of the gesture gesture, when the pointer's button is released

This signal is emitted if and only if the "gesture-begin" signal has been emitted first.

`action` : | the ClutterGestureAction that emitted the signal
`actor` : | the ClutterActor attached to the `action`
`user_data` : | user data set when the signal handler was connected.

Since 1.8

### The `"gesture-progress"` signal

    gboolean            user_function                      (ClutterGestureAction *action,
                                                            ClutterActor         *actor,
                                                            gpointer              user_data)      : Run Last

The ::gesture-progress signal is emitted for each motion event after the "gesture-begin" signal has been emitted.

`action` : | the ClutterGestureAction that emitted the signal
`actor` : | the ClutterActor attached to the `action`
`user_data` : | user data set when the signal handler was connected.
Returns : | `TRUE` if the gesture should continue, and `FALSE` if the gesture should be cancelled.

Since 1.8