GTK+ Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GtkTree

## Name

GtkTree -- a tree widget.

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkTree;
    #define     GTK_IS_ROOT_TREE                (obj)
    #define     GTK_TREE_ROOT_TREE              (obj)
    #define     GTK_TREE_SELECTION_OLD          (obj)
    enum        GtkTreeViewMode;
    GtkWidget*  gtk_tree_new                    (void);
    void        gtk_tree_append                 (GtkTree *tree,
                                                 GtkWidget *tree_item);
    void        gtk_tree_prepend                (GtkTree *tree,
                                                 GtkWidget *tree_item);
    void        gtk_tree_insert                 (GtkTree *tree,
                                                 GtkWidget *tree_item,
                                                 gint position);
    void        gtk_tree_remove_items           (GtkTree *tree,
                                                 GList *items);
    void        gtk_tree_clear_items            (GtkTree *tree,
                                                 gint start,
                                                 gint end);
    void        gtk_tree_select_item            (GtkTree *tree,
                                                 gint item);
    void        gtk_tree_unselect_item          (GtkTree *tree,
                                                 gint item);
    void        gtk_tree_select_child           (GtkTree *tree,
                                                 GtkWidget *tree_item);
    void        gtk_tree_unselect_child         (GtkTree *tree,
                                                 GtkWidget *tree_item);
    gint        gtk_tree_child_position         (GtkTree *tree,
                                                 GtkWidget *child);
    void        gtk_tree_set_selection_mode     (GtkTree *tree,
                                                 GtkSelectionMode mode);
    void        gtk_tree_set_view_mode          (GtkTree *tree,
                                                 GtkTreeViewMode mode);
    void        gtk_tree_set_view_lines         (GtkTree *tree,
                                                 gboolean flag);
    void        gtk_tree_remove_item            (GtkTree *tree,
                                                 GtkWidget *child);

## Object Hierarchy

      GObject
       +----GtkObject
             +----GtkWidget
                   +----GtkContainer
                         +----GtkTree

## Signal Prototypes

    "select-child"
                void        user_function      (GtkTree *tree,
                                                GtkWidget *widget,
                                                gpointer user_data);
    "selection-changed"
                void        user_function      (GtkTree *tree,
                                                gpointer user_data);
    "unselect-child"
                void        user_function      (GtkTree *tree,
                                                GtkWidget *widget,
                                                gpointer user_data);

## Description

Warning
GtkTree is deprecated and unsupported. It is known to be buggy. To use it, you must define the symbol `GTK_ENABLE_BROKEN` prior to including the GTK+ header files. Use GtkTreeView instead.

The GtkTree widget is a container that shows users a list of items, in a tree format complete with branches and leafnodes. Branches can be expanded to show their child items, or collapsed to hide them.

## Details

### struct GtkTree

    struct GtkTree;

Warning
`GtkTree` is deprecated and should not be used in newly-written code.

    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;
    };

### GTK_IS_ROOT_TREE()

    #define GTK_IS_ROOT_TREE(obj)   ((GtkObject*) GTK_TREE(obj)->root_tree == (GtkObject*)obj)

Warning
`GTK_IS_ROOT_TREE` is deprecated and should not be used in newly-written code.

A macro that returns a boolean value which indicates if `obj` is a root tree or not.

`obj` : | A pointer to the GtkTree. `obj` will accept any pointer, but if the pointer does not point to a GtkTree, the results are undefined.

### GTK_TREE_ROOT_TREE()

    #define GTK_TREE_ROOT_TREE(obj) (GTK_TREE(obj)->root_tree ? GTK_TREE(obj)->root_tree : GTK_TREE(obj))

Warning
`GTK_TREE_ROOT_TREE` is deprecated and should not be used in newly-written code.

A macro that returns the root tree of `obj`.

If `obj` is already a root tree, `obj` is cast to GtkTree and returned.

`obj` : | A pointer to the GtkTree. `obj` will accept any pointer, but if the pointer does not point to a GtkTree, the results are undefined.

### GTK_TREE_SELECTION_OLD()

    #define GTK_TREE_SELECTION_OLD(obj) (GTK_TREE_ROOT_TREE(obj)->selection)

Warning
`GTK_TREE_SELECTION_OLD` is deprecated and should not be used in newly-written code.

`obj` : |

### enum GtkTreeViewMode

    typedef enum
    {
      GTK_TREE_VIEW_LINE,  /* default view mode */
      GTK_TREE_VIEW_ITEM
    } GtkTreeViewMode;

Warning
`GtkTreeViewMode` is deprecated and should not be used in newly-written code.

### gtk_tree_new ()

    GtkWidget*  gtk_tree_new                    (void);

Warning
`gtk_tree_new` is deprecated and should not be used in newly-written code.

Creates a new GtkTree.

Returns : | A pointer to the newly allocated widget.

### gtk_tree_append ()

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

Warning
`gtk_tree_append` is deprecated and should not be used in newly-written code.

Adds the GtkTreeItem in `tree_item` to the end of the items in `tree`.

`tree` : | A pointer to a GtkTree.
`tree_item` : | A pointer to the GtkWidget that is to be appended to the tree.

### gtk_tree_prepend ()

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

Warning
`gtk_tree_prepend` is deprecated and should not be used in newly-written code.

Adds the GtkTreeItem in `tree_item` to the start of the items in `tree`.

`tree` : | A pointer to a GtkTree.
`tree_item` : | A pointer to the GtkWidget that is to be prepended to the tree.

### gtk_tree_insert ()

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

Warning
`gtk_tree_insert` is deprecated and should not be used in newly-written code.

Adds the GtkTreeItem in `tree_item` to the list of items in `tree` at the position indicated by `position`.

`tree` : | A pointer to a GtkTree.
`tree_item` : | A pointer to the GtkWidget that is to be added to the tree.
`position` : | A gint that indicates the position in the tree, that the `tree_item` is to be added at.

### gtk_tree_remove_items ()

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

Warning
`gtk_tree_remove_items` is deprecated and should not be used in newly-written code.

Removes a list of items from the GtkTree in `tree`.

If only one item is to be removed from the GtkTree, gtk_container_remove() can be used instead.

Removing an item from a GtkTree dereferences the item, and thus usually destroys the item and any subtrees it may contain. If the item is not to be destroyed, use g_object_ref() before removing it.

`tree` : | A pointer to a GtkTree.
`items` : | A pointer to a GList that contains the items to be removed.

### gtk_tree_clear_items ()

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

Warning
`gtk_tree_clear_items` is deprecated and should not be used in newly-written code.

Removes the items at positions between `start` and `end` from the GtkTree `tree`.

Removing an item from a GtkTree dereferences the item, and thus usually destroys the item and any subtrees it may contain. If the item is not to be destroyed, use g_object_ref() before removing it.

`tree` : | A pointer to a GtkTree.
`start` : | A gint.
`end` : | A gint.

### gtk_tree_select_item ()

    void        gtk_tree_select_item            (GtkTree *tree,
                                                 gint item);

Warning
`gtk_tree_select_item` is deprecated and should not be used in newly-written code.

Emits the select_item signal for the child at position `item`, and thus selects it (unless it is unselected in a signal handler).

`tree` : | A pointer to a GtkTree.
`item` : | A gint.

### gtk_tree_unselect_item ()

    void        gtk_tree_unselect_item          (GtkTree *tree,
                                                 gint item);

Warning
`gtk_tree_unselect_item` is deprecated and should not be used in newly-written code.

Emits the unselect_item for the child at position `item`, and thus unselects it.

`tree` : | A pointer to a GtkTree.
`item` : | A gint.

### gtk_tree_select_child ()

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

Warning
`gtk_tree_select_child` is deprecated and should not be used in newly-written code.

Emits the select_item signal for the child `tree_item`, and thus selects it (unless it is unselected in a signal handler).

`tree` : | A pointer to a GtkTree.
`tree_item` : | A pointer to the GtkWidget that is to be selected.

### gtk_tree_unselect_child ()

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

Warning
`gtk_tree_unselect_child` is deprecated and should not be used in newly-written code.

Emits the unselect_item signal for the child `tree_item`, and thus unselects it.

`tree` : | A pointer to a GtkTree.
`tree_item` : | A pointer to the GtkWidget that is to be selected.

### gtk_tree_child_position ()

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

Warning
`gtk_tree_child_position` is deprecated and should not be used in newly-written code.

Returns the position of `child` in the GtkTree `tree`.

If `child` is not a child of `tree`, then -1 is returned.

`tree` : | A pointer to a GtkTree.
`child` : | A pointer to a GtkWidget.
Returns : | A gint.

### gtk_tree_set_selection_mode ()

    void        gtk_tree_set_selection_mode     (GtkTree *tree,
                                                 GtkSelectionMode mode);

Warning
`gtk_tree_set_selection_mode` is deprecated and should not be used in newly-written code.

Sets the selection mode for the GtkTree `tree`.

`mode` can be one of

- `GTK_SELECTION_SINGLE` for when only one item can be selected at a time.

- `GTK_SELECTION_BROWSE` for when one item must be selected.

- `GTK_SELECTION_MULTIPLE` for when many items can be selected at once.

- `GTK_SELECTION_EXTENDED` Reserved for later use.

The selection mode is only defined for a root tree, as the root tree "owns" the selection.

The default mode is `GTK_SELECTION_SINGLE`.

`tree` : | A pointer to a GtkTree.
`mode` : | A GtkSelectionMode.

### gtk_tree_set_view_mode ()

    void        gtk_tree_set_view_mode          (GtkTree *tree,
                                                 GtkTreeViewMode mode);

Warning
`gtk_tree_set_view_mode` is deprecated and should not be used in newly-written code.

Sets the 'viewmode' for the GtkTree in `tree`. The 'viewmode' defines how the tree looks when an item is selected.

`mode` can be one of:

- `GTK_TREE_VIEW_LINE` : When an item is selected the entire GtkTreeItem is highlighted.

- `GTK_TREE_VIEW_ITEM` : When an item is selected only the selected item's child widget is highlighted.

The default mode is `GTK_TREE_VIEW_LINE`.

`tree` : | A pointer to a GtkTree.
`mode` : | A GtkTreeViewMode.

### gtk_tree_set_view_lines ()

    void        gtk_tree_set_view_lines         (GtkTree *tree,
                                                 gboolean flag);

Warning
`gtk_tree_set_view_lines` is deprecated and should not be used in newly-written code.

Sets whether or not the connecting lines between branches and children are drawn.

`tree` : | A pointer to a GtkTree.
`flag` : | A guint, indicating `TRUE`, or `FALSE`.

### gtk_tree_remove_item ()

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

Warning
`gtk_tree_remove_item` is deprecated and should not be used in newly-written code.

Removes the item `child` from the GtkTree `tree`.

`tree` : | A pointer to a GtkTree.
`child` : | A pointer to the GtkWidget that is to be removed from the tree.

## Signals

### The "select-child" signal

    void        user_function                  (GtkTree *tree,
                                                GtkWidget *widget,
                                                gpointer user_data);

This signal is emitted by `tree` whenever `widget` is about to be selected.

`tree` : | the object which received the signal.
`widget` : | The child that is about to be selected.
`user_data` : | user data set when the signal handler was connected.

### The "selection-changed" signal

    void        user_function                  (GtkTree *tree,
                                                gpointer user_data);

This signal is emitted by the root tree whenever the selection changes.

`tree` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The "unselect-child" signal

    void        user_function                  (GtkTree *tree,
                                                GtkWidget *widget,
                                                gpointer user_data);

This signal is emitted by `tree` whenever `widget` is about to be unselected.

`tree` : | the object which received the signal.
`widget` : | The child that is about to be unselected.
`user_data` : | user data set when the signal handler was connected.

## See Also

GtkTreeList for the items to put into a GtkTree.

GtkScrolledWindow for details on how to scroll around a GtkTree.

<<< Previous Page | Home | Up | Next Page >>>
GtkTipsQuery | GtkTreeItem