13.3. 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:
 
tree.set_selection_mode(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 SELECTION_SINGLE and 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".

Use the get_selection() method, to access the root tree's selection list as a list. Another way of accessing the selection list is using the selection attribute. Of course, this list can include items that are not in the subtree in question if the selection type is SELECTION_MULTIPLE.
 
selection_list = tree.get_selection()

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 connect() for every subtree.