Clutter Reference Manual: ClutterDragAction

## ClutterDragAction ClutterDragAction — Action enabling dragging on actors |

## Functions

ClutterAction * | clutter_drag_action_new ()
void | clutter_drag_action_set_drag_threshold ()
void | clutter_drag_action_get_drag_threshold ()
void | clutter_drag_action_set_drag_handle ()
ClutterActor * | clutter_drag_action_get_drag_handle ()
void | clutter_drag_action_set_drag_axis ()
ClutterDragAxis | clutter_drag_action_get_drag_axis ()
void | clutter_drag_action_set_drag_area ()
gboolean | clutter_drag_action_get_drag_area ()
void | clutter_drag_action_get_press_coords ()
void | clutter_drag_action_get_motion_coords ()

## Properties

ClutterRect * | drag-area | Read / Write
gboolean | drag-area-set | Read
ClutterDragAxis | drag-axis | Read / Write
ClutterActor * | drag-handle | Read / Write
gint | x-drag-threshold | Read / Write
gint | y-drag-threshold | Read / Write

## Signals

void | drag-begin | Run Last
void | drag-end | Run Last
void | drag-motion | Run Last
gboolean | drag-progress | Run Last

## Types and Values

struct | ClutterDragAction
struct | ClutterDragActionClass
enum | ClutterDragAxis

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── ClutterActorMeta
                ╰── ClutterAction
                    ╰── ClutterDragAction

## Description

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

The drag-action example allows dragging the rectangle around the stage using a ClutterDragAction. When pressing the `Shift` key the actor that is being dragged will be a separate rectangle, and when the drag ends, the original rectangle will be animated to the final drop coordinates.

ClutterDragAction is available since Clutter 1.4

## Functions

### clutter_drag_action_new ()

    ClutterAction *
    clutter_drag_action_new (void);

Creates a new ClutterDragAction instance

#### Returns

the newly created ClutterDragAction

Since 1.4

### clutter_drag_action_set_drag_threshold ()

    void
    clutter_drag_action_set_drag_threshold
                                   (ClutterDragAction *action,
                                    gint x_threshold,
                                    gint y_threshold);

Sets the horizontal and vertical drag thresholds that must be cleared by the pointer before `action` can begin the dragging.

If `x_threshold` or `y_threshold` are set to -1 then the default drag threshold stored in the “dnd-drag-threshold” property of ClutterSettings will be used.

#### Parameters

action | a ClutterDragAction |
x_threshold | a distance on the horizontal axis, in pixels, or -1 to use the default drag threshold from ClutterSettings |
y_threshold | a distance on the vertical axis, in pixels, or -1 to use the default drag threshold from ClutterSettings |

Since 1.4

### clutter_drag_action_get_drag_threshold ()

    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()`.

If the “x-drag-threshold” property or the “y-drag-threshold” property have been set to -1 then this function will return the default drag threshold value as stored by the “dnd-drag-threshold” property of ClutterSettings.

#### Parameters

action | a ClutterDragAction |
x_threshold | return location for the horizontal drag threshold value, in pixels. | [out]
y_threshold | return location for the vertical drag threshold value, in pixels. | [out]

Since 1.4

### clutter_drag_action_set_drag_handle ()

    void
    clutter_drag_action_set_drag_handle (ClutterDragAction *action,
                                         ClutterActor *handle);

Sets the actor to be used as the drag handle.

#### Parameters

action | a ClutterDragAction |
handle | a ClutterActor, or `NULL` to unset. | [allow-none]

Since 1.4

### clutter_drag_action_get_drag_handle ()

    ClutterActor *
    clutter_drag_action_get_drag_handle (ClutterDragAction *action);

Retrieves the drag handle set by `clutter_drag_action_set_drag_handle()`

#### Parameters

action | a ClutterDragAction |

#### Returns

a ClutterActor, used as the drag handle, or `NULL` if none was set.

[transfer none]

Since 1.4

### clutter_drag_action_set_drag_axis ()

    void
    clutter_drag_action_set_drag_axis (ClutterDragAction *action,
                                       ClutterDragAxis axis);

Restricts the dragging action to a specific axis

#### Parameters

action | a ClutterDragAction |
axis | the axis to constraint the dragging to |

Since 1.4

### clutter_drag_action_get_drag_axis ()

    ClutterDragAxis
    clutter_drag_action_get_drag_axis (ClutterDragAction *action);

Retrieves the axis constraint set by `clutter_drag_action_set_drag_axis()`

#### Parameters

action | a ClutterDragAction |

#### Returns

the axis constraint

Since 1.4

### clutter_drag_action_set_drag_area ()

    void
    clutter_drag_action_set_drag_area (ClutterDragAction *action,
                                       const ClutterRect *drag_area);

Sets `drag_area` to constrain the dragging of the actor associated with `action` , so that it position is always within `drag_area` , expressed in parent's coordinates. If `drag_area` is `NULL`, the actor is not constrained.

#### Parameters

action | a ClutterDragAction |
drag_area | a ClutterRect. | [allow-none]

### clutter_drag_action_get_drag_area ()

    gboolean
    clutter_drag_action_get_drag_area (ClutterDragAction *action,
                                       ClutterRect *drag_area);

Retrieves the "drag area" associated with `action` , that is a ClutterRect that constrains the actor movements, in parents coordinates.

#### Parameters

action | a ClutterDragAction |
drag_area | a ClutterRect to be filled. | [out caller-allocates]

#### Returns

`TRUE` if the actor is actually constrained (and thus `drag_area` is valid), `FALSE` otherwise

### clutter_drag_action_get_press_coords ()

    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

#### Parameters

action | a ClutterDragAction |
press_x | return location for the press event's X coordinate. | [out]
press_y | return location for the press event's Y coordinate. | [out]

Since 1.4

### clutter_drag_action_get_motion_coords ()

    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

#### Parameters

action | a ClutterDragAction |
motion_x | return location for the latest motion event's X coordinate. | [out]
motion_y | return location for the latest motion event's Y coordinate. | [out]

Since 1.4

## Types and Values

### struct ClutterDragAction

    struct ClutterDragAction;

The ClutterDragAction structure contains only private data and should be accessed using the provided API

Since 1.4

### struct ClutterDragActionClass

    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);
      gboolean      (* drag_progress)       (ClutterDragAction   *action,
                                             ClutterActor        *actor,
                                             gfloat               delta_x,
                                             gfloat               delta_y);
    };

The ClutterDragActionClass structure contains only private data

#### Members

`drag_begin` () | class handler of the “drag-begin” signal |
`drag_motion` () | class handler of the “drag-motion” signal |
`drag_end` () | class handler of the “drag-end” signal |
`drag_progress` () | class handler of the “drag-progress” signal |

Since 1.4

### enum ClutterDragAxis

The axis of the constraint that should be applied on the dragging action

#### Members

CLUTTER_DRAG_AXIS_NONE | No constraint |
CLUTTER_DRAG_X_AXIS | Set a constraint on the X axis |
CLUTTER_DRAG_Y_AXIS | Set a constraint on the Y axis |

Since 1.4

## Property Details

### The `“drag-area”` property

      “drag-area”                ClutterRect *

Constains the dragging action (or in particular, the resulting actor position) to the specified ClutterRect, in parent's coordinates.

Flags: Read / Write

Since 1.12

### The `“drag-area-set”` property

      “drag-area-set”            gboolean

Whether the “drag-area” property has been set.

Flags: Read

Default value: FALSE

Since 1.12

### The `“drag-axis”` property

      “drag-axis”                ClutterDragAxis

Constraints the dragging action to the specified axis

Flags: Read / Write

Default value: CLUTTER_DRAG_AXIS_NONE

Since 1.4

### The `“drag-handle”` property

      “drag-handle”              ClutterActor *

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

Flags: Read / Write

Since 1.4

### The `“x-drag-threshold”` property

      “x-drag-threshold”         gint

The horizontal threshold, in pixels, that the cursor must travel in order to begin a drag action.

When set to a positive 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.

When set to -1, ClutterDragAction will use the default threshold stored in the “dnd-drag-threshold” property of ClutterSettings.

When read, this property will always return a valid drag threshold, either as set or the default one.

Flags: Read / Write

Allowed values: >= -1

Default value: 0

Since 1.4

### The `“y-drag-threshold”` property

      “y-drag-threshold”         gint

The vertical threshold, in pixels, that the cursor must travel in order to begin a drag action.

When set to a positive 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.

When set to -1, ClutterDragAction will use the value stored in the “dnd-drag-threshold” property of ClutterSettings.

When read, this property will always return a valid drag threshold, either as set or the default one.

Flags: Read / Write

Allowed values: >= -1

Default value: 0

Since 1.4

## Signal Details

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

    void
    user_function (ClutterDragAction  *action,
                   ClutterActor       *actor,
                   gfloat              event_x,
                   gfloat              event_y,
                   ClutterModifierType modifiers,
                   gpointer            user_data)

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

#### Parameters

action | the ClutterDragAction that emitted the signal |
actor | the ClutterActor attached to the action |
event_x | the X coordinate (in stage space) of the press event |
event_y | the Y coordinate (in stage space) of the press event |
modifiers | the modifiers of the press event |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since 1.4

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

    void
    user_function (ClutterDragAction  *action,
                   ClutterActor       *actor,
                   gfloat              event_x,
                   gfloat              event_y,
                   ClutterModifierType modifiers,
                   gpointer            user_data)

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

#### Parameters

action | the ClutterDragAction that emitted the signal |
actor | the ClutterActor attached to the action |
event_x | the X coordinate (in stage space) of the release event |
event_y | the Y coordinate (in stage space) of the release event |
modifiers | the modifiers of the release event |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since 1.4

### The `“drag-motion”` signal

    void
    user_function (ClutterDragAction *action,
                   ClutterActor      *actor,
                   gfloat             delta_x,
                   gfloat             delta_y,
                   gpointer           user_data)

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 the “drag-progress” signal and return `FALSE` from the handler.

#### Parameters

action | the ClutterDragAction that emitted the signal |
actor | the ClutterActor attached to the action |
delta_x | 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 |
delta_y | 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 | user data set when the signal handler was connected. |

Flags: Run Last

Since 1.4

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

    gboolean
    user_function (ClutterDragAction *action,
                   ClutterActor      *actor,
                   gfloat             delta_x,
                   gfloat             delta_y,
                   gpointer           user_data)

The ::drag-progress 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 will emit “drag-motion”, if “drag-progress” emission returns `TRUE`.

#### Parameters

action | the ClutterDragAction that emitted the signal |
actor | the ClutterActor attached to the action |
delta_x | 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 |
delta_y | 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 | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the drag should continue, and `FALSE` if it should be stopped.

Flags: Run Last

Since 1.12