## ClutterGestureAction

ClutterGestureAction — Action for gesture gestures

## Synopsis

    struct              ClutterGestureAction;
    struct              ClutterGestureActionClass;
    ClutterAction *     clutter_gesture_action_new          (void);
    void                clutter_gesture_action_get_press_coords
                                                            (ClutterGestureAction *action,
                                                             guint device,
                                                             gfloat *press_x,
                                                             gfloat *press_y);
    void                clutter_gesture_action_get_motion_coords
                                                            (ClutterGestureAction *action,
                                                             guint device,
                                                             gfloat *motion_x,
                                                             gfloat *motion_y);
    void                clutter_gesture_action_get_release_coords
                                                            (ClutterGestureAction *action,
                                                             guint device,
                                                             gfloat *release_x,
                                                             gfloat *release_y);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterActorMeta
                   +----ClutterAction
                         +----ClutterGestureAction
                               +----ClutterSwipeAction

## 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 signals "gesture-begin", "gesture-motion" and "gesture-end".

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-motion", G_CALLBACK (on_gesture_motion), NULL);
    g_signal_connect (action, "gesture-end", G_CALLBACK (on_gesture_end), NULL);

## 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);
    };

The ClutterGestureClass structure contains only private data.

`gesture_begin` () | class handler for the "gesture-begin" signal
`gesture_progress` () | class handler for the "gesture-progres" signal
`gesture_end` () | class handler for the "gesture-end" signal
`gesture_cancel` () | class handler for 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_press_coords ()

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

Retrieves the coordinates, in stage space, of the press event that started the dragging for an specific pointer device

`action` : | a ClutterGestureAction
`device` : | currently unused, set to 0
`press_x` : | return location for the press event's X coordinate. [out]
`press_y` : | return location for the press event's Y coordinate. [out]

Since 1.8

### clutter_gesture_action_get_motion_coords ()

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

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

`action` : | a ClutterGestureAction
`device` : | currently unused, set to 0
`motion_x` : | return location for the latest motion event's X coordinate. [out]
`motion_y` : | return location for the latest motion event's Y coordinate. [out]

Since 1.8

### clutter_gesture_action_get_release_coords ()

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

Retrieves the coordinates, in stage space, of the point where the pointer device was last released.

`action` : | a ClutterGestureAction
`device` : | currently unused, set to 0
`release_x` : | return location for the X coordinate of the last release. [out]
`release_y` : | return location for the Y coordinate of the last release. [out]

Since 1.8

## 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