CtkTreeView drag-and-drop

CtkTreeView drag-and-drop — Interfaces for drag-and-drop support in CtkTreeView

Functions

Types and Values

Object Hierarchy

    GInterface
    ├── CtkTreeDragDest
    ╰── CtkTreeDragSource

Known Implementations

CtkTreeDragSource is implemented by CtkListStore, CtkTreeModelFilter, CtkTreeModelSort and CtkTreeStore.

CtkTreeDragDest is implemented by CtkListStore and CtkTreeStore.

Includes

#include <ctk/ctk.h>

Description

CTK+ supports Drag-and-Drop in tree views with a high-level and a low-level API.

The low-level API consists of the CTK+ DND API, augmented by some treeview utility functions: ctk_tree_view_set_drag_dest_row(), ctk_tree_view_get_drag_dest_row(), ctk_tree_view_get_dest_row_at_pos(), ctk_tree_view_create_row_drag_icon(), ctk_tree_set_row_drag_data() and ctk_tree_get_row_drag_data(). This API leaves a lot of flexibility, but nothing is done automatically, and implementing advanced features like hover-to-open-rows or autoscrolling on top of this API is a lot of work.

On the other hand, if you write to the high-level API, then all the bookkeeping of rows is done for you, as well as things like hover-to-open and auto-scroll, but your models have to implement the CtkTreeDragSource and CtkTreeDragDest interfaces.

Functions

ctk_tree_drag_source_drag_data_delete ()

gboolean
ctk_tree_drag_source_drag_data_delete (CtkTreeDragSource *drag_source,
                                       CtkTreePath *path);

Asks the CtkTreeDragSource 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!

Parameters

drag_source

a CtkTreeDragSource

 

path

row that was being dragged

 

Returns

TRUE if the row was successfully deleted


ctk_tree_drag_source_drag_data_get ()

gboolean
ctk_tree_drag_source_drag_data_get (CtkTreeDragSource *drag_source,
                                    CtkTreePath *path,
                                    CtkSelectionData *selection_data);

Asks the CtkTreeDragSource 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!

Parameters

drag_source

a CtkTreeDragSource

 

path

row that was dragged

 

selection_data

a CtkSelectionData to fill with data from the dragged row

 

Returns

TRUE if data of the required type was provided


ctk_tree_drag_source_row_draggable ()

gboolean
ctk_tree_drag_source_row_draggable (CtkTreeDragSource *drag_source,
                                    CtkTreePath *path);

Asks the CtkTreeDragSource 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.

Parameters

drag_source

a CtkTreeDragSource

 

path

row on which user is initiating a drag

 

Returns

TRUE if the row can be dragged


ctk_tree_drag_dest_drag_data_received ()

gboolean
ctk_tree_drag_dest_drag_data_received (CtkTreeDragDest *drag_dest,
                                       CtkTreePath *dest,
                                       CtkSelectionData *selection_data);

Asks the CtkTreeDragDest to insert a row before the path dest , deriving the contents of the row from selection_data . If dest is outside the tree so that inserting before it is impossible, FALSE will be returned. Also, FALSE may be returned if the new row is not created for some model-specific reason. Should robustly handle a dest no longer found in the model!

Parameters

drag_dest

a CtkTreeDragDest

 

dest

row to drop in front of

 

selection_data

data to drop

 

Returns

whether a new row was created before position dest


ctk_tree_drag_dest_row_drop_possible ()

gboolean
ctk_tree_drag_dest_row_drop_possible (CtkTreeDragDest *drag_dest,
                                      CtkTreePath *dest_path,
                                      CtkSelectionData *selection_data);

Determines whether a drop is possible before the given dest_path , at the same depth as dest_path . i.e., can we drop the data in selection_data at that location. dest_path does not have to exist; the return value will almost certainly be FALSE if the parent of dest_path doesn’t exist, though.

Parameters

drag_dest

a CtkTreeDragDest

 

dest_path

destination row

 

selection_data

the data being dragged

 

Returns

TRUE if a drop is possible before dest_path


ctk_tree_set_row_drag_data ()

gboolean
ctk_tree_set_row_drag_data (CtkSelectionData *selection_data,
                            CtkTreeModel *tree_model,
                            CtkTreePath *path);

Sets selection data of target type CTK_TREE_MODEL_ROW. Normally used in a drag_data_get handler.

Parameters

selection_data

some CtkSelectionData

 

tree_model

a CtkTreeModel

 

path

a row in tree_model

 

Returns

TRUE if the CtkSelectionData had the proper target type to allow us to set a tree row


ctk_tree_get_row_drag_data ()

gboolean
ctk_tree_get_row_drag_data (CtkSelectionData *selection_data,
                            CtkTreeModel **tree_model,
                            CtkTreePath **path);

Obtains a tree_model and path from selection data of target type CTK_TREE_MODEL_ROW. Normally called from a drag_data_received handler. This function can only be used if selection_data originates from the same process that’s calling this function, because a pointer to the tree model is being passed around. If you aren’t in the same process, then you'll get memory corruption. In the CtkTreeDragDest drag_data_received handler, you can assume that selection data of type CTK_TREE_MODEL_ROW is in from the current process. The returned path must be freed with ctk_tree_path_free().

Parameters

selection_data

a CtkSelectionData

 

tree_model

a CtkTreeModel.

[nullable][optional][transfer none][out]

path

row in tree_model .

[nullable][optional][out]

Returns

TRUE if selection_data had target type CTK_TREE_MODEL_ROW and is otherwise valid

Types and Values

CtkTreeDragSource

typedef struct _CtkTreeDragSource CtkTreeDragSource;

struct CtkTreeDragSourceIface

struct CtkTreeDragSourceIface {
  /* VTable - not signals */

  gboolean     (* row_draggable)        (CtkTreeDragSource   *drag_source,
                                         CtkTreePath         *path);

  gboolean     (* drag_data_get)        (CtkTreeDragSource   *drag_source,
                                         CtkTreePath         *path,
                                         CtkSelectionData    *selection_data);

  gboolean     (* drag_data_delete)     (CtkTreeDragSource *drag_source,
                                         CtkTreePath       *path);
};

Members

row_draggable ()

Asks the CtkTreeDragSource whether a particular row can be used as the source of a DND operation.

 

drag_data_get ()

Asks the CtkTreeDragSource to fill in selection_data with a representation of the row at path.

 

drag_data_delete ()

Asks the CtkTreeDragSource to delete the row at path, because it was moved somewhere else via drag-and-drop.

 

CtkTreeDragDest

typedef struct _CtkTreeDragDest CtkTreeDragDest;

struct CtkTreeDragDestIface

struct CtkTreeDragDestIface {
  /* VTable - not signals */

  gboolean     (* drag_data_received) (CtkTreeDragDest   *drag_dest,
                                       CtkTreePath       *dest,
                                       CtkSelectionData  *selection_data);

  gboolean     (* row_drop_possible)  (CtkTreeDragDest   *drag_dest,
                                       CtkTreePath       *dest_path,
				       CtkSelectionData  *selection_data);
};

Members

drag_data_received ()

Asks the CtkTreeDragDest to insert a row before the path dest, deriving the contents of the row from selection_data.

 

row_drop_possible ()

Determines whether a drop is possible before the given dest_path, at the same depth as dest_path.