GtkListStore
<!-- ##### SECTION Short_Description ##### -->
-
+A list-like data structure that can be used with the GtkTreeView
<!-- ##### SECTION Long_Description ##### -->
<para>
+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 it can be sorted by the view.
+Finally, it also implements the tree <link linkend="gtktreednd">drag and
+drop</link> interfaces.
+</para>
+<para>
+The #GtkListStore 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
+#GtkListStore 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
+#GdkPixbuf<!-- -->s stored.
</para>
-<!-- ##### SECTION See_Also ##### -->
+<example>
+<title>Creating a simple list store.</title>
+<programlisting>
+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);
+}
+</programlisting>
+</example>
+
+<refsect2>
+<title>Performance Considerations</title>
+<para>
+Internally, the #GtkListStore 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
+#GtkListStore sets the #GTK_TREE_MODEL_ITERS_PERSIST flag, which means
+that #GtkTreeIter<!-- -->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.
+</para>
+<title>Atomic Operations</title>
+<para>
+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 #GtkTreeModel signaling.
+In contrast, using e.g. gtk_list_store_append() and then gtk_list_store_set()
+will first create a row, which triggers the #GtkTreeModel::row-inserted signal
+on #GtkListStore. 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 #GtkListStore inside a #GtkTreeModelFilter and are
+using a #GtkTreeModelFilterVisibleFunc. Using any of the non-atomic operations
+to append rows to the #GtkListStore will cause the
+#GtkTreeModelFilterVisibleFunc to be visited with an empty row first; the
+function must be prepared for that.
+</para>
+</refsect2>
+<refsect2 id="GtkListStore-BUILDER-UI">
+<title>GtkListStore as GtkBuildable</title>
+<para>
+The GtkListStore implementation of the GtkBuildable interface allows
+to specify the model columns with a <columns> element that may
+contain multiple <column> elements, each specifying one model
+column. The "type" attribute specifies the data type for the column.
+</para>
+<para>
+Additionally, it is possible to specify content for the list store
+in the UI definition, with the <data> element. It can contain
+multiple <row> elements, each specifying to content for one
+row of the list model. Inside a <row>, the <col> elements
+specify the content for individual cells.
+</para>
<para>
+Note that it is probably more common to define your models
+in the code, and one might consider it a layering violation
+to specify the content of a list store in a UI definition,
+<emphasis>data</emphasis>, not <emphasis>presentation</emphasis>,
+and common wisdom is to separate the two, as far as possible.
+<!-- FIXME a bit inconclusive -->
+</para>
+<example>
+<title>A UI Definition fragment for a list store</title>
+<programlisting><![CDATA[
+<object class="GtkListStore">
+ <columns>
+ <column type="gchararray"/>
+ <column type="gchararray"/>
+ <column type="gint"/>
+ </columns>
+ <data>
+ <row>
+ <col id="0">John</col>
+ <col id="1">Doe</col>
+ <col id="2">25</col>
+ </row>
+ <row>
+ <col id="0">Johan</col>
+ <col id="1">Dahlin</col>
+ <col id="2">50</col>
+ </row>
+ </data>
+</object>
+]]></programlisting>
+</example>
+</refsect2>
+<!-- ##### SECTION See_Also ##### -->
+<para>
+#GtkTreeModel, #GtkTreeStore
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
<!-- ##### STRUCT GtkListStore ##### -->
<para>
@Returns:
+<!-- ##### FUNCTION gtk_list_store_newv ##### -->
+<para>
+
+</para>
+
+@n_columns:
+@types:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_list_store_set_column_types ##### -->
+<para>
+
+</para>
+
+@list_store:
+@n_columns:
+@types:
+
+
+<!-- ##### FUNCTION gtk_list_store_set ##### -->
+<para>
+
+</para>
+
+@list_store:
+@iter:
+@Varargs:
+
+
+<!-- ##### FUNCTION gtk_list_store_set_valist ##### -->
+<para>
+
+</para>
+
+@list_store:
+@iter:
+@var_args:
+
+
+<!-- ##### FUNCTION gtk_list_store_set_value ##### -->
+<para>
+
+</para>
+
+@list_store:
+@iter:
+@column:
+@value:
+
+
+<!-- ##### FUNCTION gtk_list_store_set_valuesv ##### -->
+<para>
+
+</para>
+
+@list_store:
+@iter:
+@columns:
+@values:
+@n_values:
+
+
<!-- ##### FUNCTION gtk_list_store_remove ##### -->
<para>
@list_store:
@iter:
-<!-- # Unused Parameters # -->
-@store:
+@Returns:
<!-- ##### FUNCTION gtk_list_store_insert ##### -->
@list_store:
@iter:
@position:
-<!-- # Unused Parameters # -->
-@store:
<!-- ##### FUNCTION gtk_list_store_insert_before ##### -->
@list_store:
@iter:
@sibling:
-<!-- # Unused Parameters # -->
-@store:
<!-- ##### FUNCTION gtk_list_store_insert_after ##### -->
@list_store:
@iter:
@sibling:
-<!-- # Unused Parameters # -->
-@store:
+
+
+<!-- ##### FUNCTION gtk_list_store_insert_with_values ##### -->
+<para>
+
+</para>
+
+@list_store:
+@iter:
+@position:
+@Varargs:
+
+
+<!-- ##### FUNCTION gtk_list_store_insert_with_valuesv ##### -->
+<para>
+
+</para>
+
+@list_store:
+@iter:
+@position:
+@columns:
+@values:
+@n_values:
<!-- ##### FUNCTION gtk_list_store_prepend ##### -->
@list_store:
@iter:
-<!-- # Unused Parameters # -->
-@store:
<!-- ##### FUNCTION gtk_list_store_append ##### -->
@list_store:
@iter:
-<!-- # Unused Parameters # -->
+
+
+<!-- ##### FUNCTION gtk_list_store_clear ##### -->
+<para>
+
+</para>
+
+@list_store:
+
+
+<!-- ##### FUNCTION gtk_list_store_iter_is_valid ##### -->
+<para>
+
+</para>
+
+@list_store:
+@iter:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_list_store_reorder ##### -->
+<para>
+
+</para>
+
@store:
+@new_order:
+
+
+<!-- ##### FUNCTION gtk_list_store_swap ##### -->
+<para>
+
+</para>
+
+@store:
+@a:
+@b:
+
+
+<!-- ##### FUNCTION gtk_list_store_move_before ##### -->
+<para>
+
+</para>
+
+@store:
+@iter:
+@position:
+
+
+<!-- ##### FUNCTION gtk_list_store_move_after ##### -->
+<para>
+
+</para>
+
+@store:
+@iter:
+@position:
projects / ~andy / gtk / blobdiff