ClutterDropAction: Clutter Reference Manual

ClutterDropAction

ClutterDropAction — An action for drop targets

Functions

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:

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