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:

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

ClutterGestureAction

Functions

Properties

Signals

Types and Values

Object Hierarchy

Description

Creating Gesture actions

Functions

clutter_gesture_action_new ()

Returns

clutter_gesture_action_get_last_event ()

Parameters

Returns

clutter_gesture_action_get_press_coords ()

Parameters

clutter_gesture_action_get_motion_coords ()

Parameters

clutter_gesture_action_get_motion_delta ()

Parameters

Returns

clutter_gesture_action_get_release_coords ()

Parameters

clutter_gesture_action_get_velocity ()

Parameters

clutter_gesture_action_get_n_touch_points ()

Parameters

Returns

clutter_gesture_action_set_n_touch_points ()

Parameters

clutter_gesture_action_get_n_current_points ()

Parameters

Returns

clutter_gesture_action_get_sequence ()

Parameters

Returns

clutter_gesture_action_get_device ()

Parameters

Returns

clutter_gesture_action_get_threshold_trigger_distance ()

Parameters

clutter_gesture_action_set_threshold_trigger_distance ()

Parameters

clutter_gesture_action_set_threshold_trigger_edge ()

Parameters

clutter_gesture_action_get_threshold_trigger_edge ()

Parameters

Returns

clutter_gesture_action_cancel ()

Parameters

Types and Values

struct ClutterGestureAction

struct ClutterGestureActionClass

Members

enum ClutterGestureTriggerEdge

Members

Property Details

The “n-touch-points” property

The “threshold-trigger-distance-x” property

The “threshold-trigger-distance-y” property

The “threshold-trigger-edge” property

Signal Details

The “gesture-begin” signal

Parameters

Returns

The “gesture-cancel” signal

Parameters

The “gesture-end” signal

Parameters

The “gesture-progress” signal

Parameters

Returns

The `“n-touch-points”` property

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

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

The `“threshold-trigger-edge”` property

The `“gesture-begin”` signal

The `“gesture-cancel”` signal

The `“gesture-end”` signal

The `“gesture-progress”` signal