rb-tree-dnd

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

Synopsis

                    RbTreeDragSource;
                    RbTreeDragSourceIface;
                    RbTreeDragDest;
                    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 RhythmDBPropertyModel, RhythmDBQueryModel and RBSourceListModel.

RbTreeDragDest is implemented by RhythmDBQueryModel and RBSourceListModel.

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;


RbTreeDragSourceIface

typedef struct {
	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);
} RbTreeDragSourceIface;


RbTreeDragDest

typedef struct _RbTreeDragDest RbTreeDragDest;


RbTreeDragDestIface

typedef struct {
	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);
} RbTreeDragDestIface;


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