FmDndDest

FmDndDest — Libfm support for drag&drop destination.

Synopsis

                    FmDndDest;
struct              FmDndDestClass;
enum                FmDndDestTargetType;
#define             fm_dnd_dest_add_targets             (widget,
                                                         targets,
                                                         n)
gboolean            fm_dnd_dest_drag_data_received      (FmDndDest *dd,
                                                         GdkDragContext *drag_context,
                                                         gint x,
                                                         gint y,
                                                         GtkSelectionData *sel_data,
                                                         guint info,
                                                         guint time);
gboolean            fm_dnd_dest_drag_drop               (FmDndDest *dd,
                                                         GdkDragContext *drag_context,
                                                         GdkAtom target,
                                                         int x,
                                                         int y,
                                                         guint time);
void                fm_dnd_dest_drag_leave              (FmDndDest *dd,
                                                         GdkDragContext *drag_context,
                                                         guint time);
GdkAtom             fm_dnd_dest_find_target             (FmDndDest *dd,
                                                         GdkDragContext *drag_context);
GdkDragAction       fm_dnd_dest_get_default_action      (FmDndDest *dd,
                                                         GdkDragContext *drag_context,
                                                         GdkAtom target);
FmFileInfo *        fm_dnd_dest_get_dest_file           (FmDndDest *dd);
FmPath *            fm_dnd_dest_get_dest_path           (FmDndDest *dd);
gboolean            fm_dnd_dest_is_target_supported     (FmDndDest *dd,
                                                         GdkAtom target);
FmDndDest *         fm_dnd_dest_new                     (GtkWidget *w);
FmDndDest *         fm_dnd_dest_new_with_handlers       (GtkWidget *w);
void                fm_dnd_dest_set_dest_file           (FmDndDest *dd,
                                                         FmFileInfo *dest_file);
void                fm_dnd_dest_set_widget              (FmDndDest *dd,
                                                         GtkWidget *w);
#define             fm_drag_context_has_target          (ctx,
                                                         target)
#define             fm_drag_context_has_target_name     (ctx,
                                                         name)

Object Hierarchy

  GObject
   +----FmDndDest

Signals

  "files-dropped"                                  : Run Last

Description

include: libfm/fm-dnd-dest.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().

Example 1. 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 = gtk_drag_dest_find_target(widget, drag_context, NULL);
   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;
}


Details

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);
};

GObjectClass parent_class;

 the parent class

files_dropped ()

 the class closure for the "files-dropped" signal

enum FmDndDestTargetType

typedef enum {
    FM_DND_DEST_TARGET_FM_LIST,
    FM_DND_DEST_TARGET_URI_LIST,
    FM_DND_DEST_TARGET_XDS,
} FmDndDestTargetType;

default droppable targets supported by FmDndDest

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

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.

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.

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.

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.

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.

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);

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.

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.

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.

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

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

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.

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

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)

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)      : Run Last

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.

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.

Since 0.1.0

Generated by GTK-Doc V1.18