13.4. Tree Widget Internals

The Tree's struct definition looks like this:

struct _GtkTree
{
  GtkContainer container;

  GList *children;
  
  GtkTree* root_tree; /* owner of selection list */
  GtkWidget* tree_owner;
  GList *selection;
  guint level;
  guint indent_value;
  guint current_indent;
  guint selection_mode : 2;
  guint view_mode : 1;
  guint view_line : 1;
};

The perils associated with accessing the selection field directly have already been mentioned. The other important fields of the struct can also be accessed with handy macros or class functions. GTK_IS_ROOT_TREE (Tree) returns a boolean value which indicates whether a tree is the root tree in a Tree hierarchy, while GTK_TREE_ROOT_TREE (Tree) returns the root tree, an object of type GtkTree (so, remember to cast it using GTK_WIDGET (Tree) if you want to use one of the gtk_widget_*() functions on it).

Instead of directly accessing the children field of a Tree widget, it's probably best to cast it using >tt/GTK_CONTAINER (Tree)/, and pass it to the gtk_container_children() function. This creates a duplicate of the original list, so it's advisable to free it up using g_list_free() after you're done with it, or to iterate on it destructively, like this:

    children = gtk_container_children (GTK_CONTAINER (tree));
    while (children) {
      do_something_nice (GTK_TREE_ITEM (children->data));
      children = g_list_remove_link (children, children);
}

The tree_owner field is defined only in subtrees, where it points to the TreeItem widget which holds the tree in question. The level field indicates how deeply nested a particular tree is; root trees have level 0, and each successive level of subtrees has a level one greater than the parent level. This field is set only after a Tree widget is actually mapped (i.e. drawn on the screen).

13.4.1. Signals

void selection_changed( GtkTree *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.

void select_child( GtkTree   *tree,
                   GtkWidget *child );

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

void unselect_child (GtkTree   *tree,
                     GtkWidget *child);

This signal is emitted when a child of the Tree is about to get deselected. As of GTK 1.0.4, this seems to only occur on calls to gtk_tree_unselect_item() or gtk_tree_unselect_child(), and perhaps on other occasions, but not when a button press deselects a child, nor on emission of the "toggle" signal by gtk_item_toggle().

13.4.2. Functions and Macros

guint gtk_tree_get_type( void );

Returns the "GtkTree" type identifier.

GtkWidget* gtk_tree_new( void );

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

void gtk_tree_append( GtkTree   *tree,
                      GtkWidget *tree_item );

Append a tree item to a Tree.

void gtk_tree_prepend( GtkTree   *tree,
                       GtkWidget *tree_item );

Prepend a tree item to a Tree.

void gtk_tree_insert( GtkTree   *tree,
                      GtkWidget *tree_item,
                      gint       position );

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

void gtk_tree_remove_items( GtkTree *tree,
                            GList   *items );

Remove a list of items (in the form of a GList *) 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 gtk_container_remove().

void gtk_tree_clear_items( GtkTree *tree,
                           gint     start,
                           gint     end );

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

void gtk_tree_select_item( GtkTree *tree,
                           gint     item );

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

void gtk_tree_unselect_item( GtkTree *tree,
                             gint     item );

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

void gtk_tree_select_child( GtkTree   *tree,
                            GtkWidget *tree_item );

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

void gtk_tree_unselect_child( GtkTree   *tree,
                              GtkWidget *tree_item );

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

gint gtk_tree_child_position( GtkTree   *tree,
                              GtkWidget *child );

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

void gtk_tree_set_selection_mode( GtkTree          *tree,
                                  GtkSelectionMode  mode );

Sets the selection mode, which can be one of GTK_SELECTION_SINGLE (the default), GTK_SELECTION_BROWSE, GTK_SELECTION_MULTIPLE, or GTK_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.

void gtk_tree_set_view_mode( GtkTree         *tree,
                             GtkTreeViewMode  mode );

Sets the "view mode", which can be either GTK_TREE_VIEW_LINE (the default) or GTK_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 GTK_TREE_VIEW_LINE, the entire TreeItem widget is highlighted, while for GTK_TREE_VIEW_ITEM, only the child widget (i.e., usually the label) is highlighted.

void gtk_tree_set_view_lines( GtkTree *tree,
                              guint    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.

GtkTree *GTK_TREE (gpointer obj);

Cast a generic pointer to "GtkTree *".

GtkTreeClass *GTK_TREE_CLASS (gpointer class);

Cast a generic pointer to "GtkTreeClass *".

gint GTK_IS_TREE (gpointer obj);

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

gint GTK_IS_ROOT_TREE (gpointer obj)

Determine if a generic pointer refers to a "GtkTree" object and is a root tree. Though this will accept any pointer, the results of passing it a pointer that does not refer to a Tree are undefined and possibly harmful.

GtkTree *GTK_TREE_ROOT_TREE (gpointer obj)

Return the root tree of a pointer to a "GtkTree" object. The above warning applies.

GList *GTK_TREE_SELECTION( gpointer obj)

Return the selection list of the root tree of a "GtkTree" object. The above warning applies here, too.