FmDndDest

FmDndDest — Libfm support for drag&drop destination.

Functions

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── FmDndDest

Description

include : libfm/fm-gtk.h

The FmDndDest can be used by some widget to provide support for Drop operations onto that widget.

To use FmDndDest the widget should create it - the simplest API for this is fm_dnd_dest_new_with_handlers(). When FmDndDest is created some drop data types ("targets") are set for the widget. The widget can extend the list by adding own targets to the list and connecting own handlers to the “drag-leave”, “drag-drop”, and “drag-data-received” signals.

The “drag-motion” signal should be always handled by the widget. The handler should check if drop can be performed. And if FmDndDest can accept the drop then widget should inform FmDndDest object about FmFileInfo object the mouse pointer targets at that moment by calling fm_dnd_dest_set_dest_file(). The FmDndDest uses a little different sequence for collecting dragged data - it queries data in time of drag motion and uses when data are dropped therefore widget should always call API fm_dnd_dest_get_default_action() from handler of the “drag-motion” signal for any target which FmDndDest supports.

Example 4. Sample Usage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
   widget->dd = fm_dnd_dest_new_with_handlers(widget);
   g_signal_connect(widget, "drag-motion", G_CALLBACK(on_drag_motion), dd);

   ...
}

static void on_object_finalize(MyWidget *widget)
{
   ...

   g_object_unref(G_OBJECT(widget->dd));
}

static gboolean on_drag_motion(MyWidget *widget, GdkDragContext *drag_context,
                               gint x, gint y, guint time, FmDndDest *dd)
{
   GdkAtom target;
   GdkDragAction action = 0;
   FmFileInfo *file_info;

   file_info = my_widget_find_file_at_coords(widget, x, y);
   fm_dnd_dest_set_dest_file(widget->dd, file_info);
   if (file_info == NULL)
      return FALSE; /* not in drop zone */
   target = fm_dnd_dest_find_target(widget->dd, drag_context);
   if (target != GDK_NONE && fm_dnd_dest_is_target_supported(widget->dd, target))
      action = fm_dnd_dest_get_default_action(widget->dd, drag_context, target);
   if (action == 0)
      return FALSE; /* cannot drop on that destination */
   gdk_drag_status(drag_context, action, time);
   return TRUE;
}

Functions

fm_dnd_dest_add_targets()

#define             fm_dnd_dest_add_targets(widget,targets,n)

Adds drop destination targets to existing list for widget . Convenience API.

Parameters

widget

GtkWidget to add targets

 

targets

pointer to array of GtkTargetEntry to add

 

n

number of targets to add

 

Since: 1.0.1


fm_dnd_dest_drag_data_received ()

gboolean
fm_dnd_dest_drag_data_received (FmDndDest *dd,
                                GdkDragContext *drag_context,
                                gint x,
                                gint y,
                                GtkSelectionData *sel_data,
                                guint info,
                                guint time);

A common handler for signals that emitted when information about dragged data is received, such as "drag-data-received".

If the dd was created with fm_dnd_dest_new_with_handlers() then this API should be never used by the widget.

Parameters

dd

a drag destination descriptor

 

drag_context

the drag context

 

x

horisontal position of drop

 

y

vertical position of drop

 

sel_data

selection data that are dragged

 

info

(FmDndDestTargetType) type of data that are dragged

 

time

timestamp of operation

 

Returns

TRUE if dropping data is accepted for processing.

Since: 0.1.17


fm_dnd_dest_drag_drop ()

gboolean
fm_dnd_dest_drag_drop (FmDndDest *dd,
                       GdkDragContext *drag_context,
                       GdkAtom target,
                       int x,
                       int y,
                       guint time);

A common handler for signals that emitted when dragged data are dropped onto destination, "drag-drop". Prepares data and emits the “files-dropped” signal if drop is supported.

If the dd was created with fm_dnd_dest_new_with_handlers() then this API should be never used by the widget.

Parameters

dd

a drag destination descriptor

 

drag_context

the drag context

 

target

target type

 

x

horisontal position of drop

 

y

vertical position of drop

 

time

timestamp of operation

 

Returns

TRUE if drop to target is supported by libfm.

Since: 0.1.17


fm_dnd_dest_drag_leave ()

void
fm_dnd_dest_drag_leave (FmDndDest *dd,
                        GdkDragContext *drag_context,
                        guint time);

A common handler for signals that emitted when drag leaves the destination widget, such as "drag-leave".

If the dd was created with fm_dnd_dest_new_with_handlers() then this API should be never used by the widget.

Parameters

dd

a drag destination descriptor

 

drag_context

the drag context

 

time

timestamp of operation

 

Since: 0.1.17


fm_dnd_dest_find_target ()

GdkAtom
fm_dnd_dest_find_target (FmDndDest *dd,
                         GdkDragContext *drag_context);

Finds target type that is supported for drag_context .

Parameters

dd

a drag destination descriptor

 

drag_context

the drag context

 

Returns

supported target type or GDK_NONE if none found.

Since: 0.1.17


fm_dnd_dest_get_default_action ()

GdkDragAction
fm_dnd_dest_get_default_action (FmDndDest *dd,
                                GdkDragContext *drag_context,
                                GdkAtom target);

Parameters

dd

object which will receive data

 

drag_context

the drag context

 

target

GdkAtom of the target data type

 

Returns

the default action to take for the dragged files.

Since: 0.1.17


fm_dnd_dest_get_dest_file ()

FmFileInfo *
fm_dnd_dest_get_dest_file (FmDndDest *dd);

Retrieves file info of drag destination. Returned data are owned by dd and should not be freed by caller.

Parameters

dd

a drag destination descriptor

 

Returns

file info of drag destination.

[transfer none]

Since: 0.1.0


fm_dnd_dest_get_dest_path ()

FmPath *
fm_dnd_dest_get_dest_path (FmDndDest *dd);

Retrieves file path of drag destination. Returned data are owned by dd and should not be freed by caller.

Parameters

dd

a drag destination descriptor

 

Returns

file path of drag destination.

[transfer none]

Since: 0.1.0


fm_dnd_dest_is_target_supported ()

gboolean
fm_dnd_dest_is_target_supported (FmDndDest *dd,
                                 GdkAtom target);

Checks if target is supported by libfm.

Parameters

dd

a drag destination descriptor

 

target

target type

 

Returns

TRUE if drop to target is supported by libfm.

Since: 0.1.17


fm_dnd_dest_new ()

FmDndDest *
fm_dnd_dest_new (GtkWidget *w);

Creates new drag destination descriptor and sets a widget as a potential drop destination. Caller should connect handlers for the Gtk+ Drag and Drop signals to the widget: “drag-leave”, “drag-motion”, “drag-drop”, and “drag-data-received”.

Before 1.0.1 this API didn't set drop destination on widget so caller should set it itself. Access to fm_default_dnd_dest_targets outside of this API considered unsecure so that behavior was changed.

See also: fm_dnd_dest_new_with_handlers().

Parameters

w

a widget that probably is drop destination

 

Returns

a new FmDndDest object.

[transfer full]

Since: 0.1.0


fm_dnd_dest_new_with_handlers ()

FmDndDest *
fm_dnd_dest_new_with_handlers (GtkWidget *w);

Creates new drag destination descriptor, sets a widget as a potential drop destination, and connects handlers for the Gtk+ Drag and Drop signals: “drag-leave”, “drag-drop”, and “drag-data-received”. Caller should connect own handler for the “drag-motion” signal to the widget to complete the support.

See also: fm_dnd_dest_new().

Parameters

w

a widget that probably is drop destination

 

Returns

a new FmDndDest object.

[transfer full]

Since: 1.0.1


fm_dnd_dest_set_dest_file ()

void
fm_dnd_dest_set_dest_file (FmDndDest *dd,
                           FmFileInfo *dest_file);

Sets drag destination for dd .

Parameters

dd

a drag destination descriptor

 

dest_file

file info of drag destination

 

Since: 0.1.0


fm_dnd_dest_set_widget ()

void
fm_dnd_dest_set_widget (FmDndDest *dd,
                        GtkWidget *w);

Updates link to widget that probably is drop destination and setups widget with drop targets supported by FmDndDest.

Before 1.0.1 this API didn't update drop destination on widget so caller should set and unset it itself. Access to fm_default_dnd_dest_targets outside of this API considered unsecure so that behavior was changed.

See also: fm_dnd_dest_new(), fm_dnd_dest_new_with_handlers().

Parameters

dd

a drag destination descriptor

 

w

a widget that probably is drop destination

 

Since: 0.1.0


fm_drag_context_has_target()

#define             fm_drag_context_has_target(ctx, target)

fm_drag_context_has_target_name()

#define             fm_drag_context_has_target_name(ctx, name)

Types and Values

FmDndDest

typedef struct _FmDndDest FmDndDest;

struct FmDndDestClass

struct FmDndDestClass {
    GObjectClass parent_class;
    gboolean (*files_dropped)(FmDndDest* dd, int x, int y, guint action, guint info_type, FmPathList* files);
};

Members

files_dropped ()

the class closure for the “files-dropped” signal

 

enum FmDndDestTargetType

default droppable targets supported by FmDndDest

Members

FM_DND_DEST_TARGET_FM_LIST

direct pointer of FmList

 

FM_DND_DEST_TARGET_URI_LIST

"text/uri-list"

 

FM_DND_DEST_TARGET_XDS

X direct save

 

N_FM_DND_DEST_DEFAULT_TARGETS

widget's target indices should start from this

 

Signal Details

The “files-dropped” signal

gboolean
user_function (FmDndDest *dd,
               gint       x,
               gint       y,
               guint      action,
               guint      info_type,
               gpointer   files,
               gpointer   user_data)

The “files-dropped” signal is emitted when files are dropped on the destination widget. If handler connected to this signal returns TRUE then further emission of the signal will be stopped.

Parameters

dd

the object which emitted the signal

 

x

horisontal position of drop

 

y

vertical position of drop

 

action

(GdkDragAction) action requested on drop

 

info_type

(FmDndDestTargetType) type of data that are dropped

 

files

(FmPathList *) list of files that are dropped

 

user_data

user data set when the signal handler was connected.

 

Returns

TRUE if action can be performed.

Flags: Run Last

Since: 0.1.0