Chapter 13. Tree Widget

Table of Contents
Creating a Tree
Adding a Subtree
Handling the Selection List
Tree Widget Internals
Tree Item Widget
Tree Example

The purpose of tree widgets is to display hierarchically-organized data. The Tree widget itself is a vertical container for widgets of type TreeItem. Tree itself is not terribly different from CList - both are derived directly from Container, and the Container methods work in the same way on Tree widgets as on CList widgets. The difference is that Tree widgets can be nested within other Tree widgets. We'll see how to do this shortly.

The Tree widget has its own window, and defaults to a white background, as does CList. Also, most of the Tree methods work in the same way as the corresponding CList ones. However, Tree is not derived from CList, so you cannot use them interchangeably.

Creating a Tree

A Tree is created in the usual way, using:

GtkWidget *gtk_tree_new( void );

Like the CList widget, a Tree will simply keep growing as more items are added to it, as well as when subtrees are expanded. For this reason, they are almost always packed into a ScrolledWindow. You might want to use gtk_widget_set_usize() on the scrolled window to ensure that it is big enough to see the tree's items, as the default size for ScrolledWindow is quite small.

Now that you have a tree, you'll probably want to add some items to it. The Tree Item Widget below explains the gory details of TreeItem. For now, it'll suffice to create one, using:

GtkWidget *gtk_tree_item_new_with_label( gchar *label );

You can then add it to the tree using one of the following (see Functions and Macros below for more options):

void gtk_tree_append( GtkTree    *tree,
                       GtkWidget *tree_item );

void gtk_tree_prepend( GtkTree   *tree,
                       GtkWidget *tree_item );

Note that you must add items to a Tree one at a time - there is no equivalent to gtk_list_*_items().