rb-tree-dnd

## rb-tree-dnd rb-tree-dnd — multi-row drag and drop support for GtkTreeViews |

## Synopsis

                        RbTreeDragSource;
    struct              RbTreeDragSourceIface;
                        RbTreeDragDest;
    struct              RbTreeDragDestIface;
    enum                RbTreeDestFlag;
    gboolean            rb_tree_drag_source_row_draggable   (RbTreeDragSource *drag_source,
                                                             GList *path_list);
    gboolean            rb_tree_drag_source_drag_data_delete
                                                            (RbTreeDragSource *drag_source,
                                                             GList *path_list);
    gboolean            rb_tree_drag_source_drag_data_get   (RbTreeDragSource *drag_source,
                                                             GList *path_list,
                                                             GtkSelectionData *selection_data);
    gboolean            rb_tree_drag_dest_drag_data_received
                                                            (RbTreeDragDest *drag_dest,
                                                             GtkTreePath *dest,
                                                             GtkTreeViewDropPosition pos,
                                                             GtkSelectionData *selection_data);
    gboolean            rb_tree_drag_dest_row_drop_possible (RbTreeDragDest *drag_dest,
                                                             GtkTreePath *dest_path,
                                                             GtkTreeViewDropPosition pos,
                                                             GtkSelectionData *selection_data);
    gboolean            rb_tree_drag_dest_row_drop_position (RbTreeDragDest *drag_dest,
                                                             GtkTreePath *dest_path,
                                                             GList *targets,
                                                             GtkTreeViewDropPosition *pos);
    void                rb_tree_dnd_add_drag_dest_support   (GtkTreeView *tree_view,
                                                             RbTreeDestFlag flags,
                                                             const GtkTargetEntry *targets,
                                                             gint n_targets,
                                                             GdkDragAction actions);
    void                rb_tree_dnd_add_drag_source_support (GtkTreeView *tree_view,
                                                             GdkModifierType start_button_mask,
                                                             const GtkTargetEntry *targets,
                                                             gint n_targets,
                                                             GdkDragAction actions);

## Object Hierarchy

      GInterface
       +----RbTreeDragSource

      GInterface
       +----RbTreeDragDest

## Known Implementations

RbTreeDragSource is implemented by RBDisplayPageModel, RhythmDBPropertyModel and RhythmDBQueryModel.

RbTreeDragDest is implemented by RBDisplayPageModel and RhythmDBQueryModel.

## Description

Provides support for drag and drop operations to and from GtkTreeView widgets that can include multiple rows. The model backing the tree view widgets must implement the RbTreeDragSource and RbTreeDragDest interfaces.

## Details

### RbTreeDragSource

    typedef struct _RbTreeDragSource RbTreeDragSource;

### struct RbTreeDragSourceIface

    struct RbTreeDragSourceIface {
    	GTypeInterface g_iface;

    	/* VTable - not signals */
    	gboolean     (* rb_row_draggable)        (RbTreeDragSource   *drag_source,
    	                              GList              *path_list);

    	gboolean     (* rb_drag_data_get)        (RbTreeDragSource   *drag_source,
                                             GList              *path_list,
                                             GtkSelectionData   *selection_data);

    	gboolean     (* rb_drag_data_delete)     (RbTreeDragSource *drag_source,
                                             GList            *path_list);
    };

### RbTreeDragDest

    typedef struct _RbTreeDragDest RbTreeDragDest;

### struct RbTreeDragDestIface

    struct RbTreeDragDestIface {
    	GTypeInterface g_iface;

    	/* VTable - not signals */

    	gboolean (* rb_drag_data_received) (RbTreeDragDest   *drag_dest,
    					 GtkTreePath       *dest,
    					 GtkTreeViewDropPosition pos,
    					 GtkSelectionData  *selection_data);

    	gboolean (* rb_row_drop_possible)  (RbTreeDragDest   *drag_dest,
    					 GtkTreePath       *dest_path,
    					 GtkTreeViewDropPosition pos,
    					 GtkSelectionData  *selection_data);

    	gboolean (* rb_row_drop_position) (RbTreeDragDest   *drag_dest,
    					GtkTreePath       *dest_path,
    					GList *targets,
    					GtkTreeViewDropPosition *pos);

    	/* optional */
    	GdkAtom  (* rb_get_drag_target)    (RbTreeDragDest   *drag_dest,
    					 GtkWidget        *widget,
    					 GdkDragContext   *context,
    					 GtkTreePath      *dest_path,
    					 GtkTargetList    *target_list);
    };

### enum RbTreeDestFlag

    typedef enum {
    	RB_TREE_DEST_EMPTY_VIEW_DROP = 1 << 0,
    	RB_TREE_DEST_CAN_DROP_INTO = 1 << 1,
    	RB_TREE_DEST_CAN_DROP_BETWEEN = 1 << 2,
    	RB_TREE_DEST_SELECT_ON_DRAG_TIMEOUT = 1 << 3
    } RbTreeDestFlag;

Flags controlling drag destination behaviour.

`RB_TREE_DEST_EMPTY_VIEW_DROP` | If set, drops into empty spaces in the view are accepted
`RB_TREE_DEST_CAN_DROP_INTO` | If set, drops into existing rows are accepted
`RB_TREE_DEST_CAN_DROP_BETWEEN` | If set, drops between existing rows are accepted
`RB_TREE_DEST_SELECT_ON_DRAG_TIMEOUT` | If set, update the drag selection using a timeout

### rb_tree_drag_source_row_draggable ()

    gboolean            rb_tree_drag_source_row_draggable   (RbTreeDragSource *drag_source,
                                                             GList *path_list);

Asks the RbTreeDragSource whether a particular row can be used as the source of a DND operation. If the source doesn't implement this interface, the row is assumed draggable.

`drag_source` : | a RbTreeDragSource
`path_list` : | row on which user is initiating a drag
Returns : | `TRUE` if the row can be dragged

### rb_tree_drag_source_drag_data_delete ()

    gboolean            rb_tree_drag_source_drag_data_delete
                                                            (RbTreeDragSource *drag_source,
                                                             GList *path_list);

Asks the RbTreeDragSource to delete the row at `path`, because it was moved somewhere else via drag-and-drop. Returns `FALSE` if the deletion fails because `path` no longer exists, or for some model-specific reason. Should robustly handle a `path` no longer found in the model!

`drag_source` : | a RbTreeDragSource
`path_list` : | row that was being dragged
Returns : | `TRUE` if the row was successfully deleted

### rb_tree_drag_source_drag_data_get ()

    gboolean            rb_tree_drag_source_drag_data_get   (RbTreeDragSource *drag_source,
                                                             GList *path_list,
                                                             GtkSelectionData *selection_data);

Asks the RbTreeDragSource to fill in `selection_data` with a representation of the row at `path`. `selection_data->target` gives the required type of the data. Should robustly handle a `path` no longer found in the model!

`drag_source` : | a RbTreeDragSource
`path_list` : | row that was dragged
`selection_data` : | a GtkSelectionData to fill with data from the dragged row
Returns : | `TRUE` if data of the required type was provided

### rb_tree_drag_dest_drag_data_received ()

    gboolean            rb_tree_drag_dest_drag_data_received
                                                            (RbTreeDragDest *drag_dest,
                                                             GtkTreePath *dest,
                                                             GtkTreeViewDropPosition pos,
                                                             GtkSelectionData *selection_data);

Asks a RbTreeDragDest to accept some drag and drop data.

`drag_dest` : | a RbTreeDragDest
`dest` : | the GtkTreePath on which the data was dropped
`pos` : | the drop position relative to the row identified by `dest`
`selection_data` : | a GtkSelectionData containing the drag data
Returns : | `TRUE` if the data was accepted, `FALSE` otherwise

### rb_tree_drag_dest_row_drop_possible ()

    gboolean            rb_tree_drag_dest_row_drop_possible (RbTreeDragDest *drag_dest,
                                                             GtkTreePath *dest_path,
                                                             GtkTreeViewDropPosition pos,
                                                             GtkSelectionData *selection_data);

Asks the RbTreeDragDest whether data can be dropped on a particular row. This should probably check based on the format and the row.

`drag_dest` : | a RbTreeDragDest
`dest_path` : | the GtkTreePath on which the data may be dropped
`pos` : | the drop position relative to the row identified by `dest`
`selection_data` : | a GtkSelectionData containing the drag data
Returns : | `TRUE` if the data can be dropped there

### rb_tree_drag_dest_row_drop_position ()

    gboolean            rb_tree_drag_dest_row_drop_position (RbTreeDragDest *drag_dest,
                                                             GtkTreePath *dest_path,
                                                             GList *targets,
                                                             GtkTreeViewDropPosition *pos);

Asks the RbTreeDragDest which drop position to use relative to the specified row. The drag destination should decide which drop position to use based on the target row and the list of drag targets.

`drag_dest` : | a RbTreeDragDest
`dest_path` : | a GtkTreePath describing a possible drop row
`targets` : | a GList containing possible drop target types
`pos` : | returns the GtkTreeViewDropPosition to use relative to the row
Returns : | `TRUE` if a drop position has been set, `FALSE` if a drop should not be allowed in the specified row

### rb_tree_dnd_add_drag_dest_support ()

    void                rb_tree_dnd_add_drag_dest_support   (GtkTreeView *tree_view,
                                                             RbTreeDestFlag flags,
                                                             const GtkTargetEntry *targets,
                                                             gint n_targets,
                                                             GdkDragAction actions);

Adds event handlers to perform multi-row drag and drop operations to the specified GtkTreeView. The model backing the tree view should implement the RbTreeDragDest interface. This should be called immediately after the tree view is created.

`tree_view` : | a GtkTreeView that wants to be a drag destination
`flags` : | RbTreeDestFlags for this drag destination
`targets` : | an array of GtkTargetEntry structures describing the allowed drag targets
`n_targets` : | the number of elements in `targets`
`actions` : | the allowable drag actions for this destination

### rb_tree_dnd_add_drag_source_support ()

    void                rb_tree_dnd_add_drag_source_support (GtkTreeView *tree_view,
                                                             GdkModifierType start_button_mask,
                                                             const GtkTargetEntry *targets,
                                                             gint n_targets,
                                                             GdkDragAction actions);

Adds event handlers to perform multi-row drag and drop operations from the specified GtkTreeView widget. The model backing the GtkTreeView must implement the RbTreeDragSource interface. This should be called immediately after the tree view is created.

`tree_view` : | a GtkTreeView that wants to be a drag source
`start_button_mask` : | a mask describing modifier keys to handle when dragging
`targets` : | an array of GtkTargetEntry structures describing drag data types
`n_targets` : | the number of elements in `targets`
`actions` : | a mask describing drag actions that are allowed from this source