From ba60ad9a94f7f109944c1bbcbc573c0911f34b79 Mon Sep 17 00:00:00 2001
From: Jonathan Blandford <jrb@redhat.com>
Date: Wed, 6 Mar 2002 19:22:36 +0000
Subject: [PATCH] docs

Wed Mar  6 14:12:34 2002  Jonathan Blandford  <jrb@redhat.com>

	* gtk/tmpl/gtktreeselection.sgml: docs

	* gtk/tree_widget.sgml: clean up docs
---
 docs/reference/ChangeLog                      |  6 ++
 docs/reference/gtk/tmpl/gtktreeselection.sgml | 61 ++++++++++++++-----
 docs/reference/gtk/tree_widget.sgml           | 19 ++++--
 3 files changed, 67 insertions(+), 19 deletions(-)

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index d2124b15b..c491983f0 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,9 @@
+Wed Mar  6 14:12:34 2002  Jonathan Blandford  <jrb@redhat.com>
+
+	* gtk/tmpl/gtktreeselection.sgml: docs
+
+	* gtk/tree_widget.sgml: clean up docs
+
 2002-03-05  Matthias Clasen  <maclas@gmx.de>
 
 	* gtk/gtk-sections.txt: Remove gtk_win32_get_installation_directory.
diff --git a/docs/reference/gtk/tmpl/gtktreeselection.sgml b/docs/reference/gtk/tmpl/gtktreeselection.sgml
index 35a293cc8..a9a050e2c 100644
--- a/docs/reference/gtk/tmpl/gtktreeselection.sgml
+++ b/docs/reference/gtk/tmpl/gtktreeselection.sgml
@@ -2,16 +2,42 @@
 GtkTreeSelection
 
 <!-- ##### SECTION Short_Description ##### -->
-
+The selection object for #GtkTreeView
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+The #GtkTreeSelection object is a helper object to manage the selection
+for a #GtkTreeView widget.  The #GtkTreeSelection object is
+automatically created when a new #GtkTreeView widget is created, and
+cannot exist independentally of this widget.  The primary reason the
+#GtkTreeSelection objects exists is for cleanliness of code and API.
+That is, there is no conceptual reason all these functions could not be
+methods on the #GtkTreeView widget instead of a separate function.
+</para>
 
+<para>
+The #GtkTreeSelection object is gotten from a #GtkTreeView by calling
+gtk_tree_view_get_selection().  It can be manipulated to check the
+selection status of the tree, as well as select and deselect individual
+rows.  Selection is done completely view side.  As a result, multiple
+views of the same model can have completely different selections.
+Additionally, you cannot change the selection of a row on the model that
+is not currently displayed by the view without expanding its parents
+first.
+</para>
+
+<para>
+One of the important things to remember when monitoring the selection of
+a view is that the "changed" signal is mostly a hint.  That is, it may
+only emit one signal when a range of rows is selected.  Additionally, it
+may on occasion emit a "changed" signal when nothing has happened
+(mostly as a result of programmers calling select_row on an already
+selected row).
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#GtkTreeView, #GtkTreeViewColumn, #GtkTreeDnd, #GtkTreeMode, #GtkTreeSortable, #GtkTreeModelSort, #GtkListStore, #GtkTreeStore, #GtkCellRenderer, #GtkCellEditable, #GtkCellRendererPixbuf, #GtkCellRendererText, #GtkCellRendererToggle
 </para>
 
 <!-- ##### STRUCT GtkTreeSelection ##### -->
@@ -22,26 +48,30 @@ GtkTreeSelection
 
 <!-- ##### USER_FUNCTION GtkTreeSelectionFunc ##### -->
 <para>
-
+A function used by gtk_tree_selection_set_select_function() to filter
+whether or not a row may be selected.  It is called whenever a row's
+state might change.  A return value of %TRUE indicates to @selection
+that it is okay to change the selection.
 </para>
 
-@selection: 
-@model: 
-@path: 
-@path_currently_selected: 
-@data: 
-@Returns: 
+@selection: A #GtkTreeSelection
+@model: A #GtkTreeModel being viewed
+@path: The #GtkTreePath of the row in question
+@path_currently_selected: %TRUE, if the path is currently selected
+@data: user data
+@Returns: %TRUE, if the selection state of the row can be toggled
 
 
 <!-- ##### USER_FUNCTION GtkTreeSelectionForeachFunc ##### -->
 <para>
-
+A function used by gtk_tree_selection_selected_foreach() to map all
+selected rows.  It will be called on every selected row in the view.
 </para>
 
-@model: 
-@path: 
-@iter: 
-@data: 
+@model: The #GtkTreeModel being viewed
+@path: The #GtkTreePath of a selected row
+@iter: A #GtkTreeIter pointing to a selected row
+@data: user data
 
 
 <!-- ##### FUNCTION gtk_tree_selection_set_mode ##### -->
@@ -196,7 +226,8 @@ GtkTreeSelection
 
 <!-- ##### SIGNAL GtkTreeSelection::changed ##### -->
 <para>
-
+Emitted whenever the selection has (possibly) changed.  Please note that
+this signal is 
 </para>
 
 @treeselection: the object which received the signal.
diff --git a/docs/reference/gtk/tree_widget.sgml b/docs/reference/gtk/tree_widget.sgml
index e0fd5359f..94dde8e6b 100644
--- a/docs/reference/gtk/tree_widget.sgml
+++ b/docs/reference/gtk/tree_widget.sgml
@@ -50,6 +50,12 @@
       information can be found on this in the <link
       linkend="GtkTreeStore">GtkTreeModel</link> section.
       <informalexample><programlisting><![CDATA[
+enum
+{
+  COLUMN_ONE,
+  N_COLUMNS
+};
+
 {
   GtkTreeStore *model;
   GtkWidget *view;
@@ -58,7 +64,9 @@
 
   /* Create a model.  We are using the store model for now, though we
    * could use any other GtkTreeModel */
-  model = gtk_tree_store_new_with_values (1, G_TYPE_STRING);
+  model = gtk_tree_store_new_with_values (N_COLUMNS, G_TYPE_STRING);
+
+  /* custom function to fill the model with data */
   populate_tree_model (model);
 
   /* Create a view */
@@ -68,8 +76,8 @@
    * reference */
   g_object_unref (G_OBJECT (model));
 
-  /* Create a cell render and arbitrarily make it red for demonstartion
-   *purposes */
+  /* Create a cell render and arbitrarily make it red for demonstration
+   * purposes */
   cell_renderer = gtk_cell_renderer_text_new ();
   g_object_set (G_OBJECT (cell_renderer), "foreground", "red", NULL);
 
@@ -77,11 +85,14 @@
    * cell_renderer to the first column of the model */
   column = gtk_tree_view_column_new_with_attributes ("title",
 						     cell_renderer,
-						     "text", 0,
+						     "text", COLUMN_ONE,
 						     NULL);
 
   /* Add the column to the view. */
   gtk_tree_view_append_column (GTK_TREE_VIEW (view), column);
+
+  /* Now we can manipulate the view just like any other GTK widget */
+  ...
 }
 ]]>
       </programlisting></informalexample>