12.2. Adding and Removing nodes

The items in a CTree are termed nodes. Nodes are inserted into a CTree in such a way as to create a hierarchy (although the order of insertion is not critical). The following function is used to insert a node:

GtkCTreeNode *gtk_ctree_insert_node( GtkCTree     *ctree,
                                     GtkCTreeNode *parent, 
                                     GtkCTreeNode *sibling,
                                     gchar        *text[],
                                     guint8        spacing,
                                     GdkPixmap    *pixmap_closed,
                                     GdkBitmap    *mask_closed,
                                     GdkPixmap    *pixmap_opened,
                                     GdkBitmap    *mask_opened,
                                     gboolean      is_leaf,
                                     gboolean      expanded );

This function looks a little daunting, but that is merely due to the power of the CTreee widget. Not all of the parameters above are required.

The CTree widget allows you to specify pixmaps to display in each node. For branch nodes, you can specify different pixmaps for when the branch is collapsed or expanded. This gives a nice visual feedback to the user, but it is optional so you don't have to specify pixmaps.

Lets have a quick look at all of the parameters:

• ctree - the CTree widget we are manipulating

• parent - the parent node of the one we are inserting. May be NULL for a root-level (i.e. initial) node.

• sibling - a sibling of the node we are inserting. May be NULL if there are no siblings.

• text - the textual contents of each column in the tree for this node. This array must have an entry for each column, even if it is an empty string.

• spacing - specifies the padding between the nodes pixmap and text elements, if a pixmap is provided

• pixmap_closed - a pixmap to display for a collapsed branch node and for a leaf node.

• mask_closed - a bitmap mask for the above pixmap.

• pixmap_opened - a pixmap to display for an expanded branch node.

• mask_opened - a bitmap mask for the above pixmap.

• is_leaf - indicates whether this is a leaf or branch node.

• expanded - indicates whether a branch node is initially expanded or collapsed.

An object pointer of type GtkCTreeNode is returned by the gtk_ctree_insert_node() function. This object pointer is used to reference the node when manipulating it. The node pointer is also supplied by many of the CTree signals to identify which node the signal pertains to.

To remove a node for a CTree, the following function is provided:

void gtk_ctree_remove_node( GtkCTree     *ctree, 
                            GtkCTreeNode *node );

As you can see, you merely need to specify a CTree and the node to remove.