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.

The definition for the TreeItem struct looks like this:

struct _GtkTreeItem
{
  GtkItem item;

  GtkWidget *subtree;
  GtkWidget *pixmaps_box;
  GtkWidget *plus_pix_widget, *minus_pix_widget;

  GList *pixmaps;		/* pixmap node for this items color depth */

  guint expanded : 1;
};

The pixmaps_box field is an EventBox which catches clicks on the plus/minus symbol which controls expansion and collapsing. The pixmaps field points to an internal data structure. Since you can always obtain the subtree of a TreeItem in a (relatively) type-safe manner with the GTK_TREE_ITEM_SUBTREE (Item) macro, it's probably advisable never to touch the insides of a TreeItem unless you really know what you're doing.

Since it is directly derived from an Item it can be treated as such by using the GTK_ITEM (TreeItem) macro. A TreeItem usually holds a label, so the convenience function gtk_list_item_new_with_label() is provided. The same effect can be achieved using code like the following, which is actually copied verbatim from gtk_tree_item_new_with_label():

tree_item = gtk_tree_item_new ();
label_widget = gtk_label_new (label);
gtk_misc_set_alignment (GTK_MISC (label_widget), 0.0, 0.5);

gtk_container_add (GTK_CONTAINER (tree_item), label_widget);
gtk_widget_show (label_widget);

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. So, if you want it to stick around, do something like the following:

gtk_widget_ref (tree);
owner = GTK_TREE(tree)->tree_owner;
gtk_container_remove (GTK_CONTAINER(tree), item);
if (tree->parent == NULL){
  gtk_tree_item_expand (GTK_TREE_ITEM(owner));
  gtk_tree_item_set_subtree (GTK_TREE_ITEM(owner), tree);
}
else
  gtk_widget_unref (tree);

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 gtk_widget_dnd_drag_set() or gtk_widget_dnd_drop_set(). 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".

void select( GtkItem *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 gtk_tree_item_select(), gtk_item_select(), or gtk_tree_select_child().

void deselect( GtkItem *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 gtk_tree_item_deselect() or gtk_item_deselect(). In the case of TreeItems, it is also emitted by gtk_tree_unselect_child(), and sometimes gtk_tree_select_child().

void toggle( GtkItem *tree_item );

This signal is emitted when the program calls gtk_item_toggle(). The effect it has when emitted on a TreeItem is to call gtk_tree_select_child() (and never gtk_tree_unselect_child()) 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.

void expand( GtkTreeItem *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 gtk_tree_item_expand().

void collapse( GtkTreeItem *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 gtk_tree_item_collapse().

13.5.2. Functions and Macros

guint gtk_tree_item_get_type( void );

Returns the "GtkTreeItem" type identifier.

GtkWidget* gtk_tree_item_new( void );

Create a new TreeItem object. The new widget is returned as a pointer to a GtkWidget object. NULL is returned on failure.

GtkWidget* gtk_tree_item_new_with_label (gchar       *label);

Create a new TreeItem object, having a single GtkLabel as the sole child. The new widget is returned as a pointer to a GtkWidget object. NULL is returned on failure.

void gtk_tree_item_select( GtkTreeItem *tree_item );

This function is basically a wrapper around a call to gtk_item_select (GTK_ITEM (tree_item)) which will emit the select signal.

void gtk_tree_item_deselect( GtkTreeItem *tree_item );

This function is basically a wrapper around a call to gtk_item_deselect (GTK_ITEM (tree_item)) which will emit the deselect signal.

void gtk_tree_item_set_subtree( GtkTreeItem *tree_item,
                                GtkWidget   *subtree );

This function 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.

void gtk_tree_item_remove_subtree( GtkTreeItem *tree_item );

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.

void gtk_tree_item_expand( GtkTreeItem *tree_item );

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

void gtk_tree_item_collapse( GtkTreeItem *tree_item );

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

GtkTreeItem *GTK_TREE_ITEM (gpointer obj)

Cast a generic pointer to "GtkTreeItem *".

GtkTreeItemClass *GTK_TREE_ITEM_CLASS (gpointer obj)

Cast a generic pointer to "GtkTreeItemClass".

gint GTK_IS_TREE_ITEM (gpointer obj)

Determine if a generic pointer refers to a "GtkTreeItem" object.

GtkWidget GTK_TREE_ITEM_SUBTREE (gpointer obj)

Returns a tree item's subtree (obj should point to a "GtkTreeItem" object).