PyGTK Tutorial
<<< Previous Chapter 13. Tree Widget Next >>>

13.5. Tree Item Widget

The TreeItem widget, like CListItem, is derived from Item, which in turn is derived from Bin. Therefore, the item itself is a generic container holding exactly one child widget, which can be of any type. The TreeItem widget has a number of extra fields, but the only one we need be concerned with is the subtree field.

Since it is directly derived from an Item it can be treated as such. A TreeItem usually holds a label, you can pass a string when creating a TreeItem to create a label. The same effect can be achieved using code like the following:
  
tree_item = GtkTreeItem()
label_widget = GtkLabel(label)
label_widget.set_alignment(0.0, 0.5)

tree_item.add(label_widget)
label_widget.show()

As one is not forced to add a Label to a TreeItem, you could also add an HBox or an Arrow, or even a Notebook (though your app will likely be quite unpopular in this case) to the TreeItem.

If you remove all the items from a subtree, it will be destroyed and unparented, unless you reference it beforehand, and the TreeItem which owns it will be collapsed:

Finally, drag-n-drop does work with TreeItems. You just have to make sure that the TreeItem you want to make into a drag item or a drop site has not only been added to a Tree, but that each successive parent widget has a parent itself, all the way back to a toplevel or dialog window, when you call the dnd_drag_set() method or the dnd_drop_set() method. Otherwise, strange things will happen.

13.5.1. Signals

TreeItem inherits the "select", "deselect", and "toggle" signals from Item. In addition, it adds two signals of its own, "expand" and "collapse".
  
def select(tree_item):

This signal is emitted when an item is about to be selected, either after it has been clicked on by the user, or when the program calls the select() method, or the select_child() method.
  
def deselect(tree_item):

This signal is emitted when an item is about to be unselected, either after it has been clicked on by the user, or when the program calls the deselect() method. In the case of TreeItems, it is also emitted by the unselect_child() method, and sometimes the select_child() method.
  
def toggle(tree_item):

This signal is emitted when the program calls the toggle() method. The effect it has when emitted on a TreeItem is to call the select_child() method (and never the unselect_child() method) on the item's parent tree, if the item has a parent tree. If it doesn't, then the highlight is reversed on the item.
  
def expand(tree_item):

This signal is emitted when the tree item's subtree is about to be expanded, that is, when the user clicks on the plus sign next to the item, or when the program calls the item_expand() method.
  
def collapse(tree_item):

This signal is emitted when the tree item's subtree is about to be collapsed, that is, when the user clicks on the minus sign next to the item, or when the program calls the collapse() method.

13.5.2. Methods

tree_type = GtkTreeItem.get_type()

Returns the "GtkTreeItem" type identifier.
  
tree_item = GtkTreeItem()

Create a new TreeItem object. The new widget is returned as a reference to a GtkWidget object. None is returned on failure.
  
tree_item = GtkTreeItem(label)

Create a new TreeItem object, having a single GtkLabel as the sole child. The new widget is returned as a reference to a GtkWidget object. None is returned on failure.
  
tree_item.select()

This method emits the select signal.
  
tree_item.deselect()

This method emits the deselect signal.
  
tree_item.set_subtree(subtree)

This method adds a subtree to tree_item, showing it if tree_item is expanded, or hiding it if tree_item is collapsed. Again, remember that the tree_item must have already been added to a tree for this to work.
  
tree_item.remove_subtree()

This removes all of tree_item's subtree's children (thus unreferencing and destroying it, any of its children's subtrees, and so on...), then removes the subtree itself, and hides the plus/minus sign.
  
tree_item.expand()

This emits the "expand" signal on tree_item, which expands it.
  
tree_item.collapse()

This emits the "collapse" signal on tree_item, which collapses it.
  
subtree = tree_item.subtree

Returns a tree_item's subtree.

<<< Previous Home Next >>>
Tree Widget Internals Up Tree Example