## ClutterDropAction

ClutterDropAction — An action for drop targets

## Synopsis

    struct              ClutterDropAction;
    struct              ClutterDropActionClass;
    ClutterAction *     clutter_drop_action_new             (void);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterActorMeta
                   +----ClutterAction
                         +----ClutterDropAction

## Signals

      "can-drop"                                       : Run Last
      "drop"                                           : Run Last
      "over-in"                                        : Run Last
      "over-out"                                       : Run Last

## Description

ClutterDropAction is a ClutterAction that allows a ClutterActor implementation to control what happens when a dragged actor crosses the target area or when a dragged actor is released (or "dropped") on the target area.

A trivial use of ClutterDropAction consists in connecting to the "drop" signal and handling the drop from there, for instance:

    1
    2
    3
    4

    ClutterAction *action = clutter_drop_action ();

    g_signal_connect (action, "drop", G_CALLBACK (on_drop), NULL);
    clutter_actor_add_action (an_actor, action);

The "can-drop" can be used to control whether the "drop" signal is going to be emitted; returning `FALSE` from a handler connected to the "can-drop" signal will cause the "drop" signal to be skipped when the input device button is released.

ClutterDropAction is available since Clutter 1.8

## Details

### struct ClutterDropAction

    struct ClutterDropAction;

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

Since 1.8

### struct ClutterDropActionClass

    struct ClutterDropActionClass {
      gboolean (* can_drop) (ClutterDropAction *action,
                             ClutterActor      *actor,
                             gfloat             event_x,
                             gfloat             event_y);

      void     (* over_in)  (ClutterDropAction *action,
                             ClutterActor      *actor);
      void     (* over_out) (ClutterDropAction *action,
                             ClutterActor      *actor);

      void     (* drop)     (ClutterDropAction *action,
                             ClutterActor      *actor,
                             gfloat             event_x,
                             gfloat             event_y);
    };

The ClutterDropActionClass structure contains only private data.

`can_drop` () | class handler for the "can-drop" signal
`over_in` () | class handler for the "over-in" signal
`over_out` () | class handler for the "over-out" signal
`drop` () | class handler for the "drop" signal

Since 1.8

### clutter_drop_action_new ()

    ClutterAction *     clutter_drop_action_new             (void);

Creates a new ClutterDropAction.

Use `clutter_actor_add_action()` to add the action to a ClutterActor.

Returns : | the newly created ClutterDropAction

Since 1.8

## Signal Details

### The `"can-drop"` signal

    gboolean            user_function                      (ClutterDropAction *action,
                                                            ClutterActor      *actor,
                                                            gfloat             Returns,
                                                            gfloat             arg3,
                                                            gpointer           user_data)      : Run Last

The ::can-drop signal is emitted when the dragged actor is dropped on `actor`. The return value of the ::can-drop signal will determine whether or not the "drop" signal is going to be emitted on `action`.

The default implementation of ClutterDropAction returns `TRUE` for this signal.

`action` : | the ClutterDropAction 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 drop is accepted, and `FALSE` otherwise

Since 1.8

### The `"drop"` signal

    void                user_function                      (ClutterDropAction *action,
                                                            ClutterActor      *actor,
                                                            gfloat             arg2,
                                                            gfloat             arg3,
                                                            gpointer           user_data)      : Run Last

The ::drop signal is emitted when the dragged actor is dropped on `actor`. This signal is only emitted if at least an handler of "can-drop" returns `TRUE`.

`action` : | the ClutterDropAction 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 `"over-in"` signal

    void                user_function                      (ClutterDropAction *action,
                                                            ClutterActor      *actor,
                                                            gpointer           user_data)      : Run Last

The ::over-in signal is emitted when the dragged actor crosses into `actor`.

`action` : | the ClutterDropAction 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 `"over-out"` signal

    void                user_function                      (ClutterDropAction *action,
                                                            ClutterActor      *actor,
                                                            gpointer           user_data)      : Run Last

The ::over-out signal is emitted when the dragged actor crosses outside `actor`.

`action` : | the ClutterDropAction 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