Clutter Reference Manual: ClutterGestureAction

## ClutterGestureAction ClutterGestureAction — Action for gesture gestures |

## Functions

ClutterAction * | clutter_gesture_action_new ()
const ClutterEvent * | clutter_gesture_action_get_last_event ()
void | clutter_gesture_action_get_press_coords ()
void | clutter_gesture_action_get_motion_coords ()
gfloat | clutter_gesture_action_get_motion_delta ()
void | clutter_gesture_action_get_release_coords ()
gfloat | clutter_gesture_action_get_velocity ()
gint | clutter_gesture_action_get_n_touch_points ()
void | clutter_gesture_action_set_n_touch_points ()
guint | clutter_gesture_action_get_n_current_points ()
ClutterEventSequence * | clutter_gesture_action_get_sequence ()
ClutterInputDevice * | clutter_gesture_action_get_device ()
void | clutter_gesture_action_get_threshold_trigger_distance ()
void | clutter_gesture_action_set_threshold_trigger_distance ()
void | clutter_gesture_action_set_threshold_trigger_edge ()
ClutterGestureTriggerEdge | clutter_gesture_action_get_threshold_trigger_edge ()
void | clutter_gesture_action_cancel ()

## Properties

gint | n-touch-points | Read / Write
gfloat | threshold-trigger-distance-x | Read / Write / Construct Only
gfloat | threshold-trigger-distance-y | Read / Write / Construct Only
ClutterGestureTriggerEdge | threshold-trigger-edge | Read / Write / Construct Only

## Signals

gboolean | gesture-begin | Run Last
void | gesture-cancel | Run Last
void | gesture-end | Run Last
gboolean | gesture-progress | Run Last

## Types and Values

struct | ClutterGestureAction
struct | ClutterGestureActionClass
enum | ClutterGestureTriggerEdge

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── ClutterActorMeta
                ╰── ClutterAction
                    ╰── ClutterGestureAction
                        ├── ClutterPanAction
                        ├── ClutterRotateAction
                        ├── ClutterSwipeAction
                        ├── ClutterTapAction
                        ╰── ClutterZoomAction

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

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

## Functions

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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_get_threshold_trigger_distance ()

    void
    clutter_gesture_action_get_threshold_trigger_distance
                                   (ClutterGestureAction *action,
                                    float *x,
                                    float *y);

Retrieves the threshold trigger distance of the gesture `action` , as set using `clutter_gesture_action_set_threshold_trigger_distance()`.

#### Parameters

action | a ClutterGestureAction |
x | The return location for the horizontal distance, or `NULL`. | [out][allow-none]
y | The return location for the vertical distance, or `NULL`. | [out][allow-none]

Since 1.18

### clutter_gesture_action_set_threshold_trigger_distance ()

    void
    clutter_gesture_action_set_threshold_trigger_distance
                                   (ClutterGestureAction *action,
                                    float x,
                                    float y);

Sets the threshold trigger distance for the gesture drag threshold, if any.

This function should only be called by sub-classes of ClutterGestureAction during their construction phase.

#### Parameters

action | a ClutterGestureAction |
x | the distance on the horizontal axis |
y | the distance on the vertical axis |

Since 1.18

### clutter_gesture_action_set_threshold_trigger_edge ()

    void
    clutter_gesture_action_set_threshold_trigger_edge
                                   (ClutterGestureAction *action,
                                    ClutterGestureTriggerEdge edge);

Sets the edge trigger for the gesture drag threshold, if any.

This function should only be called by sub-classes of ClutterGestureAction during their construction phase.

#### Parameters

action | a ClutterGestureAction |
edge | the `ClutterGestureTriggerEdge` |

Since 1.18

### clutter_gesture_action_get_threshold_trigger_edge ()

    ClutterGestureTriggerEdge
    clutter_gesture_action_get_threshold_trigger_edge
                                   (ClutterGestureAction *action);

Retrieves the edge trigger of the gesture `action` , as set using `clutter_gesture_action_set_threshold_trigger_edge()`.

#### Parameters

action | a ClutterGestureAction |

#### Returns

the edge trigger

Since 1.20

### clutter_gesture_action_cancel ()

    void
    clutter_gesture_action_cancel (ClutterGestureAction *action);

Cancel a ClutterGestureAction before it begins

#### Parameters

action | a ClutterGestureAction |

Since 1.12

## Types and Values

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

#### Members

`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

### enum ClutterGestureTriggerEdge

Enum passed to the `clutter_gesture_action_set_threshold_trigger_edge()` function.

#### Members

CLUTTER_GESTURE_TRIGGER_EDGE_NONE | Tell ClutterGestureAction that the gesture must begin immediately and there's no drag limit that will cause its cancellation; |
CLUTTER_GESTURE_TRIGGER_EDGE_AFTER | Tell ClutterGestureAction that it needs to wait until the drag threshold has been exceeded before considering that the gesture has begun; |
CLUTTER_GESTURE_TRIGGER_EDGE_BEFORE | Tell ClutterGestureAction that the gesture must begin immediately and that it must be cancelled once the drag exceed the configured threshold. |

Since 1.18

## Property Details

### The `“n-touch-points”` property

      “n-touch-points”           gint

Number of touch points to trigger a gesture action.

Flags: Read / Write

Allowed values: >= 1

Default value: 1

Since 1.16

### The `“threshold-trigger-distance-x”` property

      “threshold-trigger-distance-x” gfloat

The horizontal trigger distance to be used by the action to either emit the “gesture-begin” signal or to emit the “gesture-cancel” signal.

A negative value will be interpreted as the default drag threshold.

Flags: Read / Write / Construct Only

Allowed values: >= -1

Default value: -1

Since 1.18

### The `“threshold-trigger-distance-y”` property

      “threshold-trigger-distance-y” gfloat

The vertical trigger distance to be used by the action to either emit the “gesture-begin” signal or to emit the “gesture-cancel” signal.

A negative value will be interpreted as the default drag threshold.

Flags: Read / Write / Construct Only

Allowed values: >= -1

Default value: -1

Since 1.18

### The `“threshold-trigger-edge”` property

      “threshold-trigger-edge”   ClutterGestureTriggerEdge

The trigger edge to be used by the action to either emit the “gesture-begin” signal or to emit the “gesture-cancel” signal.

Flags: Read / Write / Construct Only

Default value: CLUTTER_GESTURE_TRIGGER_EDGE_NONE

Since 1.18

## Signal Details

### The `“gesture-begin”` signal

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

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

#### Parameters

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.

Flags: Run Last

Since 1.8

### The `“gesture-cancel”` signal

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

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.

#### Parameters

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

Flags: Run Last

Since 1.8

### The `“gesture-end”` signal

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

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.

#### Parameters

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

Flags: Run Last

Since 1.8

### The `“gesture-progress”` signal

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

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

#### Parameters

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.

Flags: Run Last

Since 1.8