Handling the Selection List

As with CList, the Tree type has a selection field, and it is possible to control the behaviour of the tree (somewhat) by setting the selection type using:

void gtk_tree_set_selection_mode( GtkTree          *tree,
                                  GtkSelectionMode  mode );

The semantics associated with the various selection modes are described in the section on the CList widget. As with the CList widget, the "select_child", "unselect_child" (not really - see Signals below for an explanation), and "selection_changed" signals are emitted when list items are selected or unselected. However, in order to take advantage of these signals, you need to know which Tree widget they will be emitted by, and where to find the list of selected items.

This is a source of potential confusion. The best way to explain this is that though all Tree widgets are created equal, some are more equal than others. All Tree widgets have their own X window, and can therefore receive events such as mouse clicks (if their TreeItems or their children don't catch them first!). However, to make GTK_SELECTION_SINGLE and GTK_SELECTION_BROWSE selection types behave in a sane manner, the list of selected items is specific to the topmost Tree widget in a hierarchy, known as the "root tree".

Thus, accessing the selection field directly in an arbitrary Tree widget is not a good idea unless you know it's the root tree. Instead, use the GTK_TREE_SELECTION (Tree) macro, which gives the root tree's selection list as a GList pointer. Of course, this list can include items that are not in the subtree in question if the selection type is GTK_SELECTION_MULTIPLE.

Finally, the "select_child" (and "unselect_child", in theory) signals are emitted by all trees, but the "selection_changed" signal is only emitted by the root tree. Consequently, if you want to handle the "select_child" signal for a tree and all its subtrees, you will have to call gtk_signal_connect() for every subtree.