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

# GtkTreeView

## Name

GtkTreeView --

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkTreeView;
    struct      GtkTreeSelection;
    struct      GtkTreeSelectionClass;
    GtkWidget*  gtk_tree_view_new               (void);
    GtkWidget*  gtk_tree_view_new_with_model    (GtkTreeModel *model);
    GtkTreeModel* gtk_tree_view_get_model       (GtkTreeView *tree_view);
    void        gtk_tree_view_set_model         (GtkTreeView *tree_view,
                                                 GtkTreeModel *model);
    GtkTreeSelection* gtk_tree_view_get_selection
                                                (GtkTreeView *tree_view);
    GtkAdjustment* gtk_tree_view_get_hadjustment
                                                (GtkTreeView *tree_view);
    void        gtk_tree_view_set_hadjustment   (GtkTreeView *tree_view,
                                                 GtkAdjustment *adjustment);
    GtkAdjustment* gtk_tree_view_get_vadjustment
                                                (GtkTreeView *tree_view);
    void        gtk_tree_view_set_vadjustment   (GtkTreeView *tree_view,
                                                 GtkAdjustment *adjustment);
    gboolean    gtk_tree_view_get_headers_visible
                                                (GtkTreeView *tree_view);
    void        gtk_tree_view_set_headers_visible
                                                (GtkTreeView *tree_view,
                                                 gboolean headers_visible);
    void        gtk_tree_view_columns_autosize  (GtkTreeView *tree_view);
    void        gtk_tree_view_set_headers_clickable
                                                (GtkTreeView *tree_view,
                                                 gboolean setting);
    gint        gtk_tree_view_append_column     (GtkTreeView *tree_view,
                                                 GtkTreeViewColumn *column);
    gint        gtk_tree_view_remove_column     (GtkTreeView *tree_view,
                                                 GtkTreeViewColumn *column);
    gint        gtk_tree_view_insert_column     (GtkTreeView *tree_view,
                                                 GtkTreeViewColumn *column,
                                                 gint position);
    GtkTreeViewColumn* gtk_tree_view_get_column (GtkTreeView *tree_view,
                                                 gint n);
    void        gtk_tree_view_scroll_to_cell    (GtkTreeView *tree_view,
                                                 GtkTreePath *path,
                                                 GtkTreeViewColumn *column,
                                                 gboolean use_align,
                                                 gfloat row_align,
                                                 gfloat col_align);
    gboolean    gtk_tree_view_get_path_at_pos   (GtkTreeView *tree_view,
                                                 GdkWindow *window,
                                                 gint x,
                                                 gint y,
                                                 GtkTreePath **path,
                                                 GtkTreeViewColumn **column,
                                                 gint *cell_x,
                                                 gint *cell_y);
    void        gtk_tree_view_expand_all        (GtkTreeView *tree_view);
    void        gtk_tree_view_collapse_all      (GtkTreeView *tree_view);
    gboolean    gtk_tree_view_expand_row        (GtkTreeView *tree_view,
                                                 GtkTreePath *path,
                                                 gboolean open_all);
    gboolean    gtk_tree_view_collapse_row      (GtkTreeView *tree_view,
                                                 GtkTreePath *path);

## Description

## Details

### struct GtkTreeView

    struct GtkTreeView
    {
      GtkContainer parent;

      GtkTreeViewPrivate *priv;
    };

### struct GtkTreeSelection

    struct GtkTreeSelection
    {
      GObject parent;

      /*< private >*/

      GtkTreeView *tree_view;
      GtkSelectionMode type;
      GtkTreeSelectionFunc user_func;
      gpointer user_data;
      GtkDestroyNotify destroy;
    };

### struct GtkTreeSelectionClass

    struct GtkTreeSelectionClass;

### gtk_tree_view_new ()

    GtkWidget*  gtk_tree_view_new               (void);

Creates a new GtkTreeView widget.

Returns : | A newly created GtkTreeView widget.

### gtk_tree_view_new_with_model ()

    GtkWidget*  gtk_tree_view_new_with_model    (GtkTreeModel *model);

Creates a new GtkTreeView widget with the model initialized to `model`.

`model` : | the model.
Returns : | A newly created GtkTreeView widget.

### gtk_tree_view_get_model ()

    GtkTreeModel* gtk_tree_view_get_model       (GtkTreeView *tree_view);

Returns the model the the GtkTreeView is based on. Returns NULL if the model is unset.

`tree_view` : | a GtkTreeView
Returns : | A GtkTreeModel, or NULL if none is currently being used.

### gtk_tree_view_set_model ()

    void        gtk_tree_view_set_model         (GtkTreeView *tree_view,
                                                 GtkTreeModel *model);

Sets the model for a GtkTreeView. If the `tree_view` already has a model set, it will remove it before setting the new model. If `model` is NULL, then it will unset the old model.

`tree_view` : | A GtkTreeNode.
`model` : | The model.

### gtk_tree_view_get_selection ()

    GtkTreeSelection* gtk_tree_view_get_selection
                                                (GtkTreeView *tree_view);

Gets the GtkTreeSelection associated with `tree_view`.

`tree_view` : | A GtkTreeView.
Returns : | A GtkTreeSelection object.

### gtk_tree_view_get_hadjustment ()

    GtkAdjustment* gtk_tree_view_get_hadjustment
                                                (GtkTreeView *tree_view);

Gets the GtkAdjustment currently being used for the horizontal aspect.

`tree_view` : | A GtkTreeView
Returns : | A GtkAdjustment object, or NULL if none is currently being used.

### gtk_tree_view_set_hadjustment ()

    void        gtk_tree_view_set_hadjustment   (GtkTreeView *tree_view,
                                                 GtkAdjustment *adjustment);

Sets the GtkAdjustment for the current horizontal aspect.

`tree_view` : | A GtkTreeView
`adjustment` : | The GtkAdjustment to set, or NULL

### gtk_tree_view_get_vadjustment ()

    GtkAdjustment* gtk_tree_view_get_vadjustment
                                                (GtkTreeView *tree_view);

Gets the GtkAdjustment currently being used for the vertical aspect.

`tree_view` : | A GtkTreeView
Returns : | A GtkAdjustment object, or NULL if none is currently being used.

### gtk_tree_view_set_vadjustment ()

    void        gtk_tree_view_set_vadjustment   (GtkTreeView *tree_view,
                                                 GtkAdjustment *adjustment);

Sets the GtkAdjustment for the current vertical aspect.

`tree_view` : | A GtkTreeView
`adjustment` : | The GtkAdjustment to set, or NULL

### gtk_tree_view_get_headers_visible ()

    gboolean    gtk_tree_view_get_headers_visible
                                                (GtkTreeView *tree_view);

Returns TRUE if the headers on the `tree_view` are visible.

`tree_view` : | A GtkTreeView.
Returns : | Whether the headers are visible or not.

### gtk_tree_view_set_headers_visible ()

    void        gtk_tree_view_set_headers_visible
                                                (GtkTreeView *tree_view,
                                                 gboolean headers_visible);

Sets the the visibility state of the headers.

`tree_view` : | A GtkTreeView.
`headers_visible` : | TRUE if the headers are visible

### gtk_tree_view_columns_autosize ()

    void        gtk_tree_view_columns_autosize  (GtkTreeView *tree_view);

Resizes all columns to their optimal width.

`tree_view` : | A GtkTreeView.

### gtk_tree_view_set_headers_clickable ()

    void        gtk_tree_view_set_headers_clickable
                                                (GtkTreeView *tree_view,
                                                 gboolean setting);

Allow the column title buttons to be clicked.

`tree_view` : | A GtkTreeView.
`setting` : | TRUE if the columns are clickable.

### gtk_tree_view_append_column ()

    gint        gtk_tree_view_append_column     (GtkTreeView *tree_view,
                                                 GtkTreeViewColumn *column);

Appends `column` to the list of columns.

`tree_view` : | A GtkTreeView.
`column` : | The GtkTreeViewColumn to add.
Returns : | The number of columns in `tree_view` after appending.

### gtk_tree_view_remove_column ()

    gint        gtk_tree_view_remove_column     (GtkTreeView *tree_view,
                                                 GtkTreeViewColumn *column);

Removes `column` from `tree_view`.

`tree_view` : | A GtkTreeView.
`column` : | The GtkTreeViewColumn to remove.
Returns : | The number of columns in `tree_view` after removing.

### gtk_tree_view_insert_column ()

    gint        gtk_tree_view_insert_column     (GtkTreeView *tree_view,
                                                 GtkTreeViewColumn *column,
                                                 gint position);

This inserts the `column` into the `tree_view` at `position`. If `position` is -1, then the column is inserted at the end.

`tree_view` : | A GtkTreeView.
`column` : | The GtkTreeViewColumn to be inserted.
`position` : | The position to insert `column` in.
Returns : | The number of columns in `tree_view` after insertion.

### gtk_tree_view_get_column ()

    GtkTreeViewColumn* gtk_tree_view_get_column (GtkTreeView *tree_view,
                                                 gint n);

Gets the GtkTreeViewColumn at the given position in the tree_view.

`tree_view` : | A GtkTreeView.
`n` : | The position of the column, counting from 0.
Returns : | The GtkTreeViewColumn, or NULL if the position is outside the range of columns.

### gtk_tree_view_scroll_to_cell ()

    void        gtk_tree_view_scroll_to_cell    (GtkTreeView *tree_view,
                                                 GtkTreePath *path,
                                                 GtkTreeViewColumn *column,
                                                 gboolean use_align,
                                                 gfloat row_align,
                                                 gfloat col_align);

Moves the alignments of `tree_view` to the position specified by `column` and `path`. If `column` is NULL, then no horizontal scrolling occurs. Likewise, if `path` is NULL no vertical scrolling occurs. `row_align` determines where the row is placed, and `col_align` determines where `column` is placed. Both are expected to be between 0.0 and 1.0. 0.0 means left/top alignment, 1.0 means right/bottom alignment, 0.5 means center. If `use_align` is `TRUE`, then the alignment arguments are ignored, and the tree does the minimum amount of work to scroll the cell onto the screen.

`tree_view` : | A GtkTreeView.
`path` : | The path of the row to move to.
`column` : | The GtkTreeViewColumn to move horizontally to.
`use_align` : | whether to use alignment arguments, or `FALSE`.
`row_align` : | The vertical alignment of the row specified by `path`.
`col_align` : | The horizontal alignment of the column specified by `column`.

### gtk_tree_view_get_path_at_pos ()

    gboolean    gtk_tree_view_get_path_at_pos   (GtkTreeView *tree_view,
                                                 GdkWindow *window,
                                                 gint x,
                                                 gint y,
                                                 GtkTreePath **path,
                                                 GtkTreeViewColumn **column,
                                                 gint *cell_x,
                                                 gint *cell_y);

Finds the path at the point (`x`, `y`) relative to `window`. If `window` is NULL, then the point is found relative to the widget coordinates. This function is expected to be called after an event, with event->window being passed in as `window`. It is primarily for things like popup menus. If `path` is non-NULL, then it will be filled with the GtkTreePath at that point. This path should be freed with gtk_tree_path_free. If `column` is non-NULL, then it will be filled with the column at that point. `cell_x` and `cell_y` return the coordinates relative to the cell background (i.e. the background_area passed to gtk_cell_renderer_render()). This function only works if `tree_view` is realized.

`tree_view` : | A GtkTreeView.
`window` : | The GdkWindow to check against.
`x` : | The x position to be identified.
`y` : | The y position to be identified.
`path` : | A pointer to a GtkTreePath pointer to be filled in, or `NULL`
`column` : | A pointer to a GtkTreeViewColumn pointer to be filled in, or `NULL`
`cell_x` : | A pointer where the X coordinate relative to the cell can be placed, or `NULL`
`cell_y` : | A pointer where the Y coordinate relative to the cell can be placed, or `NULL`
Returns : | TRUE if a row exists at that coordinate.

### gtk_tree_view_expand_all ()

    void        gtk_tree_view_expand_all        (GtkTreeView *tree_view);

Recursively expands all nodes in the `tree_view`.

`tree_view` : | A GtkTreeView.

### gtk_tree_view_collapse_all ()

    void        gtk_tree_view_collapse_all      (GtkTreeView *tree_view);

Recursively collapses all visible, expanded nodes in `tree_view`.

`tree_view` : | A GtkTreeView.

### gtk_tree_view_expand_row ()

    gboolean    gtk_tree_view_expand_row        (GtkTreeView *tree_view,
                                                 GtkTreePath *path,
                                                 gboolean open_all);

Opens the row so its children are visible

`tree_view` : | a GtkTreeView
`path` : | path to a row
`open_all` : | whether to recursively expand, or just expand immediate children
Returns : | `TRUE` if the row existed and had children

### gtk_tree_view_collapse_row ()

    gboolean    gtk_tree_view_collapse_row      (GtkTreeView *tree_view,
                                                 GtkTreePath *path);

Collapses a row (hides its child rows, if they exist.)

`tree_view` : | a GtkTreeView
`path` : | path to a row in the `tree_view`
Returns : | `TRUE` if the row was collapsed.

<<< Previous Page | Home | Up | Next Page >>>
GtkTreeViewColumn | GtkTreeView drag-and-drop