GtkTree

GtkTree — A tree widget

Synopsis

#include <gtk/gtk.h>

                    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
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkTree

Implemented Interfaces

GtkTree implements AtkImplementorIface and GtkBuildable.

Signals

  "select-child"                                   : Run First
  "selection-changed"                              : Run First
  "unselect-child"                                 : Run First

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

GtkTree

typedef struct _GtkTree 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

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.

Signal Details

The "select-child" signal

void                user_function                      (GtkTree   *tree,
                                                        GtkWidget *widget,
                                                        gpointer   user_data)      : Run First

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)      : Run First

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)      : Run First

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.