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

Properties

  "n-touch-points"           gint                  : Read / Write

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

Property Details

The "n-touch-points" property

  "n-touch-points"           gint                  : Read / Write

Number of touch points to trigger a gesture action.

Allowed values: >= 1

Default value: 1

Since 1.16

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

Generated by GTK-Doc V1.19.1