From 3a4bb5f8fb9f0eaa182e33fae9a20884a653180c Mon Sep 17 00:00:00 2001
From: Jonathan Blandford <jrb@redhat.com>
Date: Sat, 9 Mar 2002 18:06:05 +0000
Subject: [PATCH] Lots of docs.

Sat Mar  9 13:00:38 2002  Jonathan Blandford  <jrb@redhat.com>

	* gtk/tmpl/gtktreemodel.sgml: Lots of docs.
---
 docs/reference/ChangeLog                  |   4 +
 docs/reference/gtk/tmpl/gtk-unused.sgml   |   7 +
 docs/reference/gtk/tmpl/gtkliststore.sgml |   3 +
 docs/reference/gtk/tmpl/gtktreemodel.sgml | 213 +++++++++++++++++++++-
 docs/reference/gtk/tmpl/gtktreeview.sgml  |   7 -
 5 files changed, 218 insertions(+), 16 deletions(-)

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index b84d55e888..fa5a4fe019 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,7 @@
+Sat Mar  9 13:00:38 2002  Jonathan Blandford  <jrb@redhat.com>
+
+	* gtk/tmpl/gtktreemodel.sgml: Lots of docs.
+
 Fri Mar  8 15:14:32 2002  Owen Taylor  <otaylor@redhat.com>
 
 	* gtk/building.sgml: List -I/opt/gtk/include not
diff --git a/docs/reference/gtk/tmpl/gtk-unused.sgml b/docs/reference/gtk/tmpl/gtk-unused.sgml
index 2494ad670b..cae2b8cb69 100644
--- a/docs/reference/gtk/tmpl/gtk-unused.sgml
+++ b/docs/reference/gtk/tmpl/gtk-unused.sgml
@@ -1272,6 +1272,13 @@ produce superscript and subscript.
 @GTK_TREE_SELECTION_SINGLE: 
 @GTK_TREE_SELECTION_MULTI: 
 
+<!-- ##### SIGNAL GtkTreeView::focus-column-header ##### -->
+<para>
+
+</para>
+
+@treeview: the object which received the signal.
+
 <!-- ##### USER_FUNCTION GtkTreeViewDraggableFunc ##### -->
 <para>
 
diff --git a/docs/reference/gtk/tmpl/gtkliststore.sgml b/docs/reference/gtk/tmpl/gtkliststore.sgml
index b0d2f70401..74178a5479 100644
--- a/docs/reference/gtk/tmpl/gtkliststore.sgml
+++ b/docs/reference/gtk/tmpl/gtkliststore.sgml
@@ -14,6 +14,9 @@ Finally, it also implements the tree <link linkend="gtktreednd">drag and
 drop</link> interfaces.
 </para>
 
+<para>
+</para>
+
 <!-- ##### SECTION See_Also ##### -->
 <para>
 
diff --git a/docs/reference/gtk/tmpl/gtktreemodel.sgml b/docs/reference/gtk/tmpl/gtktreemodel.sgml
index 422a6faa97..83f6caf378 100644
--- a/docs/reference/gtk/tmpl/gtktreemodel.sgml
+++ b/docs/reference/gtk/tmpl/gtktreemodel.sgml
@@ -6,12 +6,200 @@ The tree interface used by #GtkTreeView
 
 <!-- ##### 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 &mdash; 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 ##### -->
@@ -22,13 +210,16 @@ The tree interface used by #GtkTreeView
 
 <!-- ##### 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>
@@ -82,11 +273,15 @@ The tree interface used by #GtkTreeView
 
 <!-- ##### 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>
diff --git a/docs/reference/gtk/tmpl/gtktreeview.sgml b/docs/reference/gtk/tmpl/gtktreeview.sgml
index dc9ee9264c..bc5a93852d 100644
--- a/docs/reference/gtk/tmpl/gtktreeview.sgml
+++ b/docs/reference/gtk/tmpl/gtktreeview.sgml
@@ -742,13 +742,6 @@ Function used for #gtk_tree_view_map_expanded_rows.
 @arg2: 
 @arg3: 
 
-<!-- ##### SIGNAL GtkTreeView::focus-column-header ##### -->
-<para>
-
-</para>
-
-@treeview: the object which received the signal.
-
 <!-- ##### SIGNAL GtkTreeView::move-cursor ##### -->
 <para>