13.4. Tree Widget Internals

13.4.1. Signals

def selection_changed_cb(tree):

This signal will be emitted whenever the selection field of a Tree has changed. This happens when a child of the Tree is selected or deselected.
 

def select_child_cb(tree, child):

This signal is emitted when a child of the Tree is about to get selected. This happens on calls to the select_item() method, the select_child() method, on all button presses and calls to the item_toggle() method and the toggle() method. It may sometimes be indirectly triggered on other occasions where children get added to or removed from the Tree.
 

def unselect_child_cb(tree, child):

This signal is emitted when a child of the Tree is about to get deselected. This seems to only occur on calls to the unselect_item() method or the unselect_child() method, and perhaps on other occasions, but not when a button press deselects a child, nor on emission of the "toggle" signal by the toggle() method.

13.4.2. Methods

type = GtkTree.get_type()

Returns the "GtkTree" type identifier.
 

tree = GtkTree()

Creates a new Tree object. A reference to the new widget is returned. None is returned on failure.
 

tree.append(tree_item)

Append a tree item to a Tree.
 

tree.prepend(tree_item)

Prepend a tree item to a Tree.
 

tree.insert(tree_item, position)

Insert a tree item into a Tree at the position in the list specified by position.
 

tree.remove_items(items)

Remove a list of items from a Tree. Note that removing an item from a tree dereferences (and thus usually) destroys it and its subtree, if it has one, and all subtrees in that subtree. If you want to remove only one item, you can use the GtkContainer remove() method.
 

tree.clear_items(start, end)

Remove the items from position start to position end from a Tree. The same warning about dereferencing applies here, as clear_items() simply constructs a list and passes it to the remove_items() method.
 

tree.select_item(item)

Emits the "select_item" signal for the child at position item, thus selecting the child (unless you unselect it in a signal handler).
 

tree.unselect_item(item)

Emits the "unselect_item" signal for the child at position item, thus unselecting the child.
 

tree.select_child(tree_item)

Emits the "select_item" signal for the child tree_item, thus selecting it.
 

tree.unselect_child(tree_item)

Emits the "unselect_item" signal for the child tree_item, thus unselecting it.
 

position = tree.child_position(child)

Returns the position in the tree of child, unless child is not in the tree, in which case it returns -1.
 

tree.set_selection_mode(mode)

Sets the selection mode, which can be one of SELECTION_SINGLE (the default), SELECTION_BROWSE, SELECTION_MULTIPLE, or SELECTION_EXTENDED. This is only defined for root trees, which makes sense, since the root tree "owns" the selection. Setting it for subtrees has no effect at all; the value is simply ignored.
 

tree.set_view_mode(mode)

Sets the "view mode", which can be either TREE_VIEW_LINE (the default) or TREE_VIEW_ITEM. The view mode propagates from a tree to its subtrees, and can't be set exclusively to a subtree (this is not exactly true - see the example code comments).

The term "view mode" is rather ambiguous - basically, it controls the way the highlight is drawn when one of a tree's children is selected. If it's TREE_VIEW_LINE, the entire TreeItem widget is highlighted, while for TREE_VIEW_ITEM, only the child widget (i.e., usually the label) is highlighted.
 

tree.set_view_lines(flag)

Controls whether connecting lines between tree items are drawn. flag is either TRUE, in which case they are, or FALSE, in which case they aren't.