FmDndDest: Libfm Reference Manual

## FmDndDest FmDndDest — Libfm support for drag&drop destination. |

## Functions

#define | fm_dnd_dest_add_targets()
gboolean | fm_dnd_dest_drag_data_received ()
gboolean | fm_dnd_dest_drag_drop ()
void | fm_dnd_dest_drag_leave ()
GdkAtom | fm_dnd_dest_find_target ()
GdkDragAction | fm_dnd_dest_get_default_action ()
FmFileInfo * | fm_dnd_dest_get_dest_file ()
FmPath * | fm_dnd_dest_get_dest_path ()
gboolean | fm_dnd_dest_is_target_supported ()
FmDndDest * | fm_dnd_dest_new ()
FmDndDest * | fm_dnd_dest_new_with_handlers ()
void | fm_dnd_dest_set_dest_file ()
void | fm_dnd_dest_set_widget ()
#define | fm_drag_context_has_target()
#define | fm_drag_context_has_target_name()

## Signals

gboolean | files-dropped | Run Last

## Types and Values

| FmDndDest
struct | FmDndDestClass
enum | FmDndDestTargetType

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