<!-- ##### SECTION Long_Description ##### -->
<para>
+The #GtkTreeModel interface defines a generic tree interface for use by
+the #GtkTreeView widget. It is an abstract interface, and is designed
+to be usable with any appropriate data structure. The programmer just
+has to implement this interface on their own data type for it to be
+viewable by a #GtkTreeView widget.
+</para>
+
+<para>
+The model is represented as a hierarchical tree of strongly-typed,
+columned data. In other words, the model can be seen as a tree where
+every node has different values depending on which column is being
+queried. The type of data found in a column is determined by using the
+GType system (ie. #G_TYPE_INT, #GTK_TYPE_BUTTON, #G_TYPE_POINTER, etc.).
+The types are homogeneous per column across all nodes. It is important
+to note that this interface only provides a way of examining a model and
+observing changes. The implementation of each individual model decides
+how and if changes are made.
+</para>
+
+<para>
+In order to make life simpler for programmers who do not need to write
+their own specialized model, two generic models are provided — the
+#GtkTreeStore and the #GtkListStore. To use these, the developer simply
+pushes data into these models as necessary. These models provide the
+data structure as well as all appropriate tree interfaces. As a result,
+implementing drag and drop, sorting, and storing data is trivial. For
+the vast majority of trees and lists, these two models are sufficient.
+</para>
+
+<para>
+Models are accessed on a node/column level of granularity. One can
+query for the value of a model at a certain node and a certain column
+on that node. There are two structures used to reference a particular
+node in a model. They are the #GtkTreePath and the #GtkTreeIter
+<footnote>
+<para>
+Here, <abbrev>iter</abbrev> is short for <quote>iterator</quote>
+</para>
+</footnote>
+Most of the interface consists of operations on a #GtkTreeIter.
+</para>
+<para>
+A path is essentially a potential node. It is a location on a model
+that may or may not actually correspond to a node on a specific model.
+The #GtkTreePath struct can be converted into either an array of
+unsigned integers or a string. The string form is a list of numbers
+separated by a colon. Each number refers to the offset at that level.
+Thus, the path <quote>0</quote> refers to the root node and the path
+<quote>2:4</quote> refers to the fifth child of the third node.
+</para>
+
+<para>
+By contrast, a #GtkTreeIter is a reference to a specific node on a
+specific model. It is a generic struct with an integer and three
+generic pointers. These are filled in by the model in a model-specific
+way. One can convert a path to an iterator by calling
+gtk_tree_model_get_iter(). These iterators are the primary way of
+accessing a model and are similar to the iterators used by
+#GtkTextBuffer. They are generally statically allocated on the heap and
+only used for a short time. The model interface defines a set of
+operations using them for navigating the model.
+</para>
+
+<para>
+It is expected that models fill in the iterator with private data. For
+example, the #GtkListStore model, which is internally a simple linked
+list, stores a list node in one of the pointers. The #GtkTreeModelSort
+stores an array and an offset in two of the pointers. Additionally,
+there is an integer field. This field is generally filled with a unique
+stamp per model. This stamp is for catching errors resulting from using
+invalid iterators with a model.
+</para>
+
+<para>
+The lifecycle of an iterator can be a little confusing at first.
+Iterators are expected to always be valid for as long as the model is
+unchanged (and doesn't emit a signal). The model is considered to own
+all outstanding iterators and nothing needs to be done to free them from
+the user's point of view. Additionally, some models guarantee that an
+iterator is valid for as long as the node it refers to is valid (most
+notably the #GtkTreeStore and #GtkListStore). Although generally
+uninteresting, as one always has to allow for the case where iterators
+do not persist beyond a signal, some very important performance
+enhancements were made in the sort model. As a result, the
+#GTK_TREE_MODEL_ITERS_PERSIST flag was added to indicate this behavior.
+</para>
+
+<para>
+To help show some common operation of a model, some examples are
+provided. The first example shows three ways of getting the iter at the
+location <quote>3:2:5</quote>. While the first method shown is easier,
+the second is much more common, as you often get paths from callbacks.
+</para>
+<para>
+<example>
+<title>Acquiring a <structname>GtkTreeIter</structname></title>
+<programlisting><![CDATA[
+/* Three ways of getting the iter pointing to the location
+ */
+{
+ GtkTreePath *path;
+ GtkTreeIter iter;
+ GtkTreeIter parent_iter;
+
+ /* get the iterator from a string */
+ gtk_tree_model_get_iter_from_string (model, &iter, "3:2:5");
+
+ /* get the iterator from a path */
+ path = gtk_tree_path_new_from_string ("3:2:5");
+ gtk_tree_model_get_iter (model, &iter, path);
+ gtk_tree_path_free (path);
+
+
+ /* walk the tree to find the iterator */
+ gtk_tree_model_get_nth_child (model, &iter, NULL, 3);
+ parent_iter = iter;
+ gtk_tree_model_get_nth_child (model, &iter, &parent_iter, 2);
+ parent_iter = iter;
+ gtk_tree_model_get_nth_child (model, &iter, NULL, 5);
+}
+]]>
+</programlisting>
+</example>
+</para>
+
+<para>
+This second example shows a quick way of iterating through a list and
+getting a string and an integer from each row. The
+<function>populate_model</function> function used below is not shown, as
+it is specific to the #GtkListStore. For information on how to write
+such a function, see the #GtkListStore documentation.
+<example>
+<title>Reading data from a <structname>GtkTreeModel</structname></title>
+<programlisting><![CDATA[
+enum
+{
+ STRING_COLUMN,
+ INT_COLUMN,
+ N_COLUMNS
+};
+
+{
+ GtkTreeModel *list_store;
+ GtkTreeIter iter;
+
+ /* make a new list_store */
+ list_store = gtk_list_store_new (N_COLUMNS, G_TYPE_STRING, G_TYPE_INT);
+
+ /* Fill the list store with data */
+ populate_model (list_store);
+
+ /* Get the first iter in the list */
+ if (gtk_tree_model_get_iter_first (model, &iter))
+ {
+ gint row_count = 0;
+
+ /* Walk through the list, reading each row */
+ do
+ {
+ gchar *str_data;
+ gint int_data;
+
+ /* Make sure you terminate calls to gtk_tree_model_get
+ * with a '-1' value
+ */
+ gtk_tree_model_get (list_store,
+ STRING_COLUMN, &str_data,
+ INT_COLUMN, &int_data,
+ -1);
+
+ /* Do something with the data */
+ g_print ("Row %d: (%s,%d)\n", row_count, str_data, int_data);
+ g_free (str_data);
+
+ row_count ++;
+ }
+ while (gtk_tree_model_iter_next (model, &iter));
+ }
+ else
+ {
+ /* As gtk_tree_model_get_iter_first returned FALSE, the list is empty */
+ g_print ("Model is empty.\n");
+ }
+}
+]]>
+
+</programlisting>
+</example>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-#GtkTreeView, #GtkTreeStore, #GtkListStore
+#GtkTreeView, #GtkTreeStore, #GtkListStore, #GtkTreeDnd, #GtkTreeSortable
</para>
<!-- ##### STRUCT GtkTreeModel ##### -->
<!-- ##### STRUCT GtkTreeIter ##### -->
<para>
-
+The <structname>GtkTreeIter</structname> is the primary structure for
+accessing a structure. Models are expected to put a unique integer in
+the <structfield>stamp</structfield> member, and put model-specific
+data in the three <structfield>user_data</structfield> members.
</para>
-@stamp:
-@user_data:
-@user_data2:
-@user_data3:
+@stamp: A unique stamp to catch invalid iterators
+@user_data: Model specific data
+@user_data2: Model specific data
+@user_data3: Model specific data
<!-- ##### STRUCT GtkTreePath ##### -->
<para>
<!-- ##### ENUM GtkTreeModelFlags ##### -->
<para>
-
+These flags indicate various properties of a #GtkTreeModel. They are
+returned by gtk_tree_model_get_flags(), and must be static for the
+lifetime of the object. A more complete description of
+#GTK_TREE_MODEL_ITERS_PERSIST can be found in the overview of this
+section.
</para>
-@GTK_TREE_MODEL_ITERS_PERSIST:
-@GTK_TREE_MODEL_LIST_ONLY:
+@GTK_TREE_MODEL_ITERS_PERSIST: Iterators survive all signals emitted by the tree.
+@GTK_TREE_MODEL_LIST_ONLY: The model is a list only, and never has children
<!-- ##### FUNCTION gtk_tree_path_new ##### -->
<para>
projects / ~andy / gtk / commitdiff