Clutter Reference Manual: ClutterDropAction

## ClutterDropAction ClutterDropAction — An action for drop targets |

## Functions

ClutterAction * | clutter_drop_action_new ()

## Signals

gboolean | can-drop | Run Last
void | drop | Run Last
void | drop-cancel | Run Last
void | over-in | Run Last
void | over-out | Run Last

## Types and Values

struct | ClutterDropAction
struct | ClutterDropActionClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── ClutterActorMeta
                ╰── ClutterAction
                    ╰── ClutterDropAction

## Description

ClutterDropAction is a ClutterAction that allows a ClutterActor implementation to control what happens when an actor dragged using a ClutterDragAction 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.

It's important to note that ClutterDropAction will only work with actors dragged using ClutterDragAction.

See drop-action.c for an example of how to use ClutterDropAction.

ClutterDropAction is available since Clutter 1.8

## Functions

### 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

## Types and Values

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

#### Members

`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

## Signal Details

### The `“can-drop”` signal

    gboolean
    user_function (ClutterDropAction *action,
                   ClutterActor      *actor,
                   gfloat             event_x,
                   gfloat             event_y,
                   gpointer           user_data)

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.

#### Parameters

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

#### Returns

`TRUE` if the drop is accepted, and `FALSE` otherwise

Flags: Run Last

Since 1.8

### The `“drop”` signal

    void
    user_function (ClutterDropAction *action,
                   ClutterActor      *actor,
                   gfloat             event_x,
                   gfloat             event_y,
                   gpointer           user_data)

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

#### Parameters

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

Flags: Run Last

Since 1.8

### The `“drop-cancel”` signal

    void
    user_function (ClutterDropAction *action,
                   ClutterActor      *actor,
                   gfloat             event_x,
                   gfloat             event_y,
                   gpointer           user_data)

The ::drop-cancel signal is emitted when the drop is refused by an emission of the “can-drop” signal.

After the ::drop-cancel signal is fired the active drag is terminated.

#### Parameters

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

Flags: Run Last

Since 1.12

### The `“over-in”` signal

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

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

#### Parameters

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

Flags: Run Last

Since 1.8

### The `“over-out”` signal

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

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

#### Parameters

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

Flags: Run Last

Since 1.8