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

# GtkListStore

## Name

GtkListStore --

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkListStore;
    GtkListStore* gtk_list_store_new            (gint n_columns,
                                                 ...);
    GtkListStore* gtk_list_store_newv           (gint n_columns,
                                                 GType *types);
    void        gtk_list_store_set_column_types (GtkListStore *list_store,
                                                 gint n_columns,
                                                 GType *types);
    void        gtk_list_store_set              (GtkListStore *list_store,
                                                 GtkTreeIter *iter,
                                                 ...);
    void        gtk_list_store_set_valist       (GtkListStore *list_store,
                                                 GtkTreeIter *iter,
                                                 va_list var_args);
    void        gtk_list_store_set_value        (GtkListStore *list_store,
                                                 GtkTreeIter *iter,
                                                 gint column,
                                                 GValue *value);
    gboolean    gtk_list_store_remove           (GtkListStore *list_store,
                                                 GtkTreeIter *iter);
    void        gtk_list_store_insert           (GtkListStore *list_store,
                                                 GtkTreeIter *iter,
                                                 gint position);
    void        gtk_list_store_insert_before    (GtkListStore *list_store,
                                                 GtkTreeIter *iter,
                                                 GtkTreeIter *sibling);
    void        gtk_list_store_insert_after     (GtkListStore *list_store,
                                                 GtkTreeIter *iter,
                                                 GtkTreeIter *sibling);
    void        gtk_list_store_prepend          (GtkListStore *list_store,
                                                 GtkTreeIter *iter);
    void        gtk_list_store_append           (GtkListStore *list_store,
                                                 GtkTreeIter *iter);
    void        gtk_list_store_clear            (GtkListStore *list_store);

## Object Hierarchy

      GObject
       +----GtkListStore

## Description

The GtkListStore object is a list model for use with a GtkTreeView widget. It implements the GtkTreeModel interface, and consequentialy, can use all of the methods available there. It also implements the GtkTreeSortable interface so you can sort the list using the view. Finally, it also implements the tree drag and drop interfaces.

## Details

### struct GtkListStore

    struct GtkListStore;

### gtk_list_store_new ()

    GtkListStore* gtk_list_store_new            (gint n_columns,
                                                 ...);

Creates a new list store as with `n_columns` columns each of the types passed in. As an example, `gtk_tree_store_new (3, G_TYPE_INT, G_TYPE_STRING, GDK_TYPE_PIXBUF);` will create a new GtkListStore with three columns, of type int, string and GdkPixbuf respectively.

`n_columns` : | number of columns in the list store
`...` : | all GType types for the columns, from first to last
Returns : | a new GtkListStore

### gtk_list_store_newv ()

    GtkListStore* gtk_list_store_newv           (gint n_columns,
                                                 GType *types);

Non-vararg creation function. Used primarily by language bindings.

`n_columns` : | number of columns in the list store
`types` : | an array of GType types for the columns, from first to last
Returns : | a new GtkListStore

### gtk_list_store_set_column_types ()

    void        gtk_list_store_set_column_types (GtkListStore *list_store,
                                                 gint n_columns,
                                                 GType *types);

This function is meant primarily for GObjects that inherit from GtkListStore, and should only be used when constructing a new GtkListStore. It will not function after a row has been added, or a method on the GtkTreeModel interface is called.

`list_store` : | A GtkListStore
`n_columns` : | Number of columns for the list store
`types` : | An array length n of GTypes

### gtk_list_store_set ()

    void        gtk_list_store_set              (GtkListStore *list_store,
                                                 GtkTreeIter *iter,
                                                 ...);

Sets the value of one or more cells in the row referenced by `iter`. The variable argument list should contain integer column numbers, each column number followed by the value to be set. The list is terminated by a -1. For example, to set column 0 with type `G_TYPE_STRING` to "Foo", you would write `gtk_list_store_set (store, iter, 0, "Foo", -1)`.

`list_store` : | a GtkListStore
`iter` : | row iterator
`...` : | pairs of column number and value, terminated with -1

### gtk_list_store_set_valist ()

    void        gtk_list_store_set_valist       (GtkListStore *list_store,
                                                 GtkTreeIter *iter,
                                                 va_list var_args);

See gtk_list_store_set(); this version takes a va_list for use by language bindings.

`list_store` : | A GtkListStore
`iter` : | A valid GtkTreeIter for the row being modified
`var_args` : | va_list of column/value pairs

### gtk_list_store_set_value ()

    void        gtk_list_store_set_value        (GtkListStore *list_store,
                                                 GtkTreeIter *iter,
                                                 gint column,
                                                 GValue *value);

Sets the data in the cell specified by `iter` and `column`. The type of `value` must be convertible to the type of the column.

`list_store` : | A GtkListStore
`iter` : | A valid GtkTreeIter for the row being modified
`column` : | column number to modify
`value` : | new value for the cell

### gtk_list_store_remove ()

    gboolean    gtk_list_store_remove           (GtkListStore *list_store,
                                                 GtkTreeIter *iter);

Removes the given row from the list store. After being removed, `iter` is set to be the next valid row, or invalidated if it pointed to the last row in `list_store`.

`list_store` : | A GtkListStore
`iter` : | A valid GtkTreeIter
Returns : | `TRUE` if `iter` is valid, `FALSE` if not.

### gtk_list_store_insert ()

    void        gtk_list_store_insert           (GtkListStore *list_store,
                                                 GtkTreeIter *iter,
                                                 gint position);

Creates a new row at `position`. `iter` will be changed to point to this new row. If `position` is larger than the number of rows on the list, then the new row will be appended to the list. The row will be empty before this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value().

`list_store` : | A GtkListStore
`iter` : | An unset GtkTreeIter to set to the new row
`position` : | position to insert the new row

### gtk_list_store_insert_before ()

    void        gtk_list_store_insert_before    (GtkListStore *list_store,
                                                 GtkTreeIter *iter,
                                                 GtkTreeIter *sibling);

Inserts a new row before `sibling`. If `sibling` is `NULL`, then the row will be appended to the end of the list. `iter` will be changed to point to this new row. The row will be empty before this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value().

`list_store` : | A GtkListStore
`iter` : | An unset GtkTreeIter to set to the new row
`sibling` : | A valid GtkTreeIter, or `NULL`

### gtk_list_store_insert_after ()

    void        gtk_list_store_insert_after     (GtkListStore *list_store,
                                                 GtkTreeIter *iter,
                                                 GtkTreeIter *sibling);

Inserts a new row after `sibling`. If `sibling` is `NULL`, then the row will be prepended to the beginning of the list. `iter` will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value().

`list_store` : | A GtkListStore
`iter` : | An unset GtkTreeIter to set to the new row
`sibling` : | A valid GtkTreeIter, or `NULL`

### gtk_list_store_prepend ()

    void        gtk_list_store_prepend          (GtkListStore *list_store,
                                                 GtkTreeIter *iter);

Prepends a new row to `list_store`. `iter` will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value().

`list_store` : | A GtkListStore
`iter` : | An unset GtkTreeIter to set to the prepend row

### gtk_list_store_append ()

    void        gtk_list_store_append           (GtkListStore *list_store,
                                                 GtkTreeIter *iter);

Appends a new row to `list_store`. `iter` will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value().

`list_store` : | A GtkListStore
`iter` : | An unset GtkTreeIter to set to the appended row

### gtk_list_store_clear ()

    void        gtk_list_store_clear            (GtkListStore *list_store);

Removes all rows from the list store.

`list_store` : | a GtkListStore.

<<< Previous Page | Home | Up | Next Page >>>
GtkCellRendererToggle | GtkTreeStore