GtkListStore
************

A list-like data structure that can be used with the

Overview
========

The <gtk-list-store> object is a list model for use with a <gtk-tree-view> widget. It implements the <gtk-tree-model> interface, and consequentialy, can use all of the methods available there. It also implements the <gtk-tree-sortable> interface so it can be sorted by the view. Finally, it also implements the tree drag and drop interfaces.

The <gtk-list-store> can accept most GObject types as a column type, though it can't accept all custom types. Internally, it will keep a copy of data passed in (such as a string or a boxed pointer). Columns that accept <gobject>s are handled a little differently. The <gtk-list-store> will keep a reference to the object instead of copying the value. As a result, if the object is modified, it is up to the application writer to call GTK-TREE-MODEL-ROW-CHANGED to emit the "row_changed" signal. This most commonly affects lists with <gdk-pixbuf>s stored.

     enum {
       COLUMN_STRING,
       COLUMN_INT,
       COLUMN_BOOLEAN,
       N_COLUMNS
     };

     {
       GtkListStore *list_store;
       GtkTreePath *path;
       GtkTreeIter iter;
       gint i;

       list_store = gtk_list_store_new (N_COLUMNS,
                                        G_TYPE_STRING,
                                        G_TYPE_INT,
                                        G_TYPE_BOOLEAN);

       for (i = 0; i < 10; i++)
         {
           gchar *some_data;

           some_data = get_some_data (i);

           /* Add a new row to the model */
           gtk_list_store_append (list_store, &iter);
           gtk_list_store_set (list_store, &iter,
                               COLUMN_STRING, some_data,
                               COLUMN_INT, i,
                               COLUMN_BOOLEAN,  FALSE,
                               -1);

           /* As the store will keep a copy of the string internally, we
            * free some_data.
            */
           g_free (some_data);
         }

       /* Modify a particular row */
       path = gtk_tree_path_new_from_string ("4");
       gtk_tree_model_get_iter (GTK_TREE_MODEL (list_store),
                                &iter,
                                path);
       gtk_tree_path_free (path);
       gtk_list_store_set (list_store, &iter,
                           COLUMN_BOOLEAN, TRUE,
                           -1);
     }

Performance Considerations
==========================

Internally, the <gtk-list-store> was implemented with a linked list with a tail pointer prior to GTK+ 2.6. As a result, it was fast at data insertion and deletion, and not fast at random data access. The <gtk-list-store> sets the <gtk-tree-model-iters-persist> flag, which means that <gtk-tree-iter>s can be cached while the row exists. Thus, if access to a particular row is needed often and your code is expected to run on older versions of GTK+, it is worth keeping the iter around.

It is important to note that only the methods GTK-LIST-STORE-INSERT-WITH-VALUES and GTK-LIST-STORE-INSERT-WITH-VALUESV are atomic, in the sense that the row is being appended to the store and the values filled in in a single operation with regard to <gtk-tree-model> signaling. In contrast, using e.g. GTK-LIST-STORE-APPEND and then GTK-LIST-STORE-SET will first create a row, which triggers the "row_inserted" <gtk-tree-model> signal on <gtk-list-store>. The row, however, is still empty, and any signal handler connecting to "row_inserted" on this particular store should be prepared for the situation that the row might be empty. This is especially important if you are wrapping the <gtk-list-store> inside a <gtk-tree-model-filter> and are using a <gtk-tree-model-filter-visible-func>. Using any of the non-atomic operations to append rows to the <gtk-list-store> will cause the <gtk-tree-model-filter-visible-func> to be visited with an empty row first; the function must be prepared for that.

Usage
=====

     [file defuns-gtkliststore.xml.texi not included]