![]() |
![]() |
![]() |
Clutter Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
struct ClutterDragAction; struct ClutterDragActionClass; ClutterAction * clutter_drag_action_new (void
); void clutter_drag_action_set_drag_threshold (ClutterDragAction *action
,guint x_threshold
,guint y_threshold
); void clutter_drag_action_get_drag_threshold (ClutterDragAction *action
,guint *x_threshold
,guint *y_threshold
); void clutter_drag_action_set_drag_handle (ClutterDragAction *action
,ClutterActor *handle
); ClutterActor * clutter_drag_action_get_drag_handle (ClutterDragAction *action
); enum ClutterDragAxis; void clutter_drag_action_set_drag_axis (ClutterDragAction *action
,ClutterDragAxis axis
); ClutterDragAxis clutter_drag_action_get_drag_axis (ClutterDragAction *action
); void clutter_drag_action_get_press_coords (ClutterDragAction *action
,gfloat *press_x
,gfloat *press_y
); void clutter_drag_action_get_motion_coords (ClutterDragAction *action
,gfloat *motion_x
,gfloat *motion_y
);
GObject +----GInitiallyUnowned +----ClutterActorMeta +----ClutterAction +----ClutterDragAction
"drag-axis" ClutterDragAxis : Read / Write "drag-handle" ClutterActor* : Read / Write "x-drag-threshold" guint : Read / Write "y-drag-threshold" guint : Read / Write
ClutterDragAction is a sub-class of ClutterAction that implements all the necessary logic for dragging actors.
The simplest usage of ClutterDragAction consists in adding it to a ClutterActor and setting it as reactive; for instance, the following code:
1 2 |
clutter_actor_add_action (actor, clutter_drag_action_new ()); clutter_actor_set_reactive (actor, TRUE); |
will automatically result in the actor moving to follow the pointer whenever the pointer's button is pressed over the actor and moved across the stage.
The ClutterDragAction will signal the begin and the end of a dragging through the "drag-begin" and "drag-end" signals, respectively. Each pointer motion during a drag will also result in the "drag-motion" signal to be emitted.
It is also possible to set another ClutterActor as the dragged actor
by calling clutter_drag_action_set_drag_handle()
from within a handle
of the "drag-begin" signal. The drag handle must be
parented and exist between the emission of "drag-begin"
and "drag-end".
ClutterDragAction is available since Clutter 1.4
struct ClutterDragAction;
The ClutterDragAction structure contains only private data and should be accessed using the provided API
Since 1.4
struct ClutterDragActionClass { void (* drag_begin) (ClutterDragAction *action, ClutterActor *actor, gfloat event_x, gfloat event_y, ClutterModifierType modifiers); void (* drag_motion) (ClutterDragAction *action, ClutterActor *actor, gfloat delta_x, gfloat delta_y); void (* drag_end) (ClutterDragAction *action, ClutterActor *actor, gfloat event_x, gfloat event_y, ClutterModifierType modifiers); };
The ClutterDragActionClass structure contains only private data
class handler of the "drag-begin" signal | |
class handler of the "drag-motion" signal | |
class handler of the "drag-end" signal |
Since 1.4
ClutterAction * clutter_drag_action_new (void
);
Creates a new ClutterDragAction instance
Returns : |
the newly created ClutterDragAction |
Since 1.4
void clutter_drag_action_set_drag_threshold (ClutterDragAction *action
,guint x_threshold
,guint y_threshold
);
Sets the horizontal and vertical drag thresholds that must be
cleared by the pointer before action
can begin the dragging
|
a ClutterDragAction |
|
a distance on the horizontal axis, in pixels |
|
a distance on the vertical axis, in pixels |
Since 1.4
void clutter_drag_action_get_drag_threshold (ClutterDragAction *action
,guint *x_threshold
,guint *y_threshold
);
Retrieves the values set by clutter_drag_action_set_drag_threshold()
|
a ClutterDragAction |
|
return location for the horizontal drag threshold value, in pixels. [out] |
|
return location for the vertical drag threshold value, in pixels. [out] |
Since 1.4
void clutter_drag_action_set_drag_handle (ClutterDragAction *action
,ClutterActor *handle
);
Sets the actor to be used as the drag handle
|
a ClutterDragHandle |
|
a ClutterActor |
Since 1.4
ClutterActor * clutter_drag_action_get_drag_handle (ClutterDragAction *action
);
Retrieves the drag handle set by clutter_drag_action_set_drag_handle()
|
a ClutterDragAction |
Returns : |
a ClutterActor, used as the drag
handle, or NULL if none was set. [transfer none]
|
Since 1.4
typedef enum { /*< prefix=CLUTTER_DRAG >*/ CLUTTER_DRAG_AXIS_NONE = 0, CLUTTER_DRAG_X_AXIS, CLUTTER_DRAG_Y_AXIS } ClutterDragAxis;
The axis of the constraint that should be applied on the dragging action
No constraint | |
Set a constraint on the X axis | |
Set a constraint on the Y axis |
Since 1.4
void clutter_drag_action_set_drag_axis (ClutterDragAction *action
,ClutterDragAxis axis
);
Restricts the dragging action to a specific axis
|
a ClutterDragAction |
|
the axis to constraint the dragging to |
Since 1.4
ClutterDragAxis clutter_drag_action_get_drag_axis (ClutterDragAction *action
);
Retrieves the axis constraint set by clutter_drag_action_set_drag_axis()
|
a ClutterDragAction |
Returns : |
the axis constraint |
Since 1.4
void clutter_drag_action_get_press_coords (ClutterDragAction *action
,gfloat *press_x
,gfloat *press_y
);
Retrieves the coordinates, in stage space, of the press event that started the dragging
|
a ClutterDragAction |
|
return location for the press event's X coordinate. [out] |
|
return location for the press event's Y coordinate. [out] |
Since 1.4
void clutter_drag_action_get_motion_coords (ClutterDragAction *action
,gfloat *motion_x
,gfloat *motion_y
);
Retrieves the coordinates, in stage space, of the latest motion event during the dragging
|
a ClutterDragAction |
|
return location for the latest motion event's X coordinate. [out] |
|
return location for the latest motion event's Y coordinate. [out] |
Since 1.4
"drag-axis"
property"drag-axis" ClutterDragAxis : Read / Write
Constraints the dragging action to the specified axis
Default value: CLUTTER_DRAG_AXIS_NONE
Since 1.4
"drag-handle"
property"drag-handle" ClutterActor* : Read / Write
The ClutterActor that is effectively being dragged
A ClutterDragAction will, be default, use the ClutterActor that has been attached to the action; it is possible to create a separate ClutterActor and use it instead.
Setting this property has no effect on the ClutterActor argument passed to the ClutterDragAction signals
Since 1.4
"x-drag-threshold"
property "x-drag-threshold" guint : Read / Write
The horizontal threshold, in pixels, that begins a drag action
When set to a non-zero value, ClutterDragAction will only emit "drag-begin" if the pointer has moved horizontally at least of the given amount of pixels since the button press event
Default value: 0
Since 1.4
"y-drag-threshold"
property "y-drag-threshold" guint : Read / Write
The vertical threshold, in pixels, that begins a drag action
When set to a non-zero value, ClutterDragAction will only emit "drag-begin" if the pointer has moved vertically at least of the given amount of pixels since the button press event
Default value: 0
Since 1.4
"drag-begin"
signalvoid user_function (ClutterDragAction *action,
ClutterActor *actor,
gfloat event_x,
gfloat event_y,
ClutterModifierType modifiers,
gpointer user_data) : Run Last
The ::drag-begin signal is emitted when the ClutterDragAction starts the dragging
The emission of this signal can be delayed by using the "x-drag-threshold" and "y-drag-threshold" properties
|
the ClutterDragAction that emitted the signal |
|
the ClutterActor attached to the action |
|
the X coordinate (in stage space) of the press event |
|
the Y coordinate (in stage space) of the press event |
|
the modifiers of the press event |
|
user data set when the signal handler was connected. |
Since 1.4
"drag-end"
signalvoid user_function (ClutterDragAction *action,
ClutterActor *actor,
gfloat event_x,
gfloat event_y,
ClutterModifierType modifiers,
gpointer user_data) : Run Last
The ::drag-end signal is emitted at the end of the dragging, when the pointer button's is released
This signal is emitted if and only if the "drag-begin" signal has been emitted first
|
the ClutterDragAction that emitted the signal |
|
the ClutterActor attached to the action |
|
the X coordinate (in stage space) of the release event |
|
the Y coordinate (in stage space) of the release event |
|
the modifiers of the release event |
|
user data set when the signal handler was connected. |
Since 1.4
"drag-motion"
signalvoid user_function (ClutterDragAction *action,
ClutterActor *actor,
gfloat delta_x,
gfloat delta_y,
gpointer user_data) : Run Last
The ::drag-motion signal is emitted for each motion event after the "drag-begin" signal has been emitted.
The components of the distance between the press event and the
latest motion event are computed in the actor's coordinate space,
to take into account eventual transformations. If you want the
stage coordinates of the latest motion event you can use
clutter_drag_action_get_motion_coords()
.
The default handler of the signal will call clutter_actor_move_by()
either on actor
or, if set, of "drag-handle" using
the delta_x
and delta_y
components of the dragging motion. If you
want to override the default behaviour, you can connect to this
signal and call g_signal_stop_emission_by_name()
from within your
callback.
|
the ClutterDragAction that emitted the signal |
|
the ClutterActor attached to the action |
|
the X component of the distance between the press event that began the dragging and the current position of the pointer, as of the latest motion event |
|
the Y component of the distance between the press event that began the dragging and the current position of the pointer, as of the latest motion event |
|
user data set when the signal handler was connected. |
Since 1.4