| Top |  |
 |
 |
 |
Functions
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.
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.
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 |
||
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 |
||
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 |
||
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] |
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 |
||
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 |
||
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.
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.
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.
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.
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 |
||
point |
the touch point index, with 0 being the first touch point received by the action |
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 |
||
x |
The return location for the horizontal distance, or |
[out][allow-none] |
y |
The return location for the vertical distance, or |
[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.
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.
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().
Since: 1.20
clutter_gesture_action_cancel ()
void
clutter_gesture_action_cancel (ClutterGestureAction *action);
Cancel a ClutterGestureAction before it begins
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
class handler for the “gesture-begin” signal |
||
class handler for the “gesture-progress” signal |
||
class handler for the “gesture-end” signal |
||
class handler for the “gesture-cancel” signal |
||
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
|
Tell ClutterGestureAction that the gesture must begin immediately and there's no drag limit that will cause its cancellation; |
||
|
Tell ClutterGestureAction that it needs to wait until the drag threshold has been exceeded before considering that the gesture has begun; |
||
|
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 |
|
user_data |
user data set when the signal handler was connected. |
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 |
|
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 |
|
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 |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
Since: 1.8