Write documentation Write documentation

Sat Sep  8 14:19:49 2001  Jonathan Blandford  <jrb@redhat.com>

	* gtk/gtkliststore.c: Write documentation
	* gtk/gtktreestore.c: Write documentation

Quick Documentation cleanup pass.

1 files changed, 213 insertions, 89 deletions

diff --git a/gtk/gtktreestore.c b/gtk/gtktreestore.c
index 6d17ba3215..d6a1c21336 100644
--- a/gtk/gtktreestore.c
+++ b/gtk/gtktreestore.c
@@ -244,7 +244,11 @@ static void
 gtk_tree_store_init (GtkTreeStore *tree_store)
 {
   tree_store->root = g_node_new (NULL);
-  tree_store->stamp = g_random_int ();
+  do
+    {
+      tree_store->stamp = g_random_int ();
+    }
+  while (tree_store->stamp != 0);
   tree_store->sort_list = NULL;
   tree_store->sort_column_id = -2;
 }
@@ -684,10 +688,18 @@ gtk_tree_store_iter_parent (GtkTreeModel *tree_model,
     return FALSE;
 }
 
-/*
- * This is a somewhat inelegant function that does a lot of list
- * manipulations on it's own.
- */
+/**
+ * gtk_tree_store_set_value:
+ * @tree_store: a #GtkTreeStore
+ * @iter: A valid #GtkTreeIter for the row being modified
+ * @column: column number to modify
+ * @value: new value for the cell
+ *
+ * Sets the data in the cell specified by @iter and @column.
+ * The type of @value must be convertible to the type of the
+ * column.
+ *
+ **/
 void
 gtk_tree_store_set_value (GtkTreeStore *tree_store,
 			  GtkTreeIter  *iter,
@@ -786,11 +798,11 @@ gtk_tree_store_set_value (GtkTreeStore *tree_store,
 
 /**
  * gtk_tree_store_set_valist:
- * @tree_store: a #GtkTreeStore
- * @iter: row to set data for
+ * @tree_store: A #GtkTreeStore
+ * @iter: A valid #GtkTreeIter for the row being modified
  * @var_args: va_list of column/value pairs
  *
- * See gtk_tree_store_set(); this version takes a va_list for
+ * See @gtk_tree_store_set; this version takes a va_list for
  * use by language bindings.
  *
  **/
@@ -844,8 +856,8 @@ gtk_tree_store_set_valist (GtkTreeStore *tree_store,
 
 /**
  * gtk_tree_store_set:
- * @tree_store: a #GtkTreeStore
- * @iter: row iterator
+ * @tree_store: A #GtkTreeStore
+ * @iter: A valid #GtkTreeIter for the row being modified
  * @Varargs: pairs of column number and value, terminated with -1
  *
  * Sets the value of one or more cells in the row referenced by @iter.
@@ -870,60 +882,85 @@ gtk_tree_store_set (GtkTreeStore *tree_store,
   va_end (var_args);
 }
 
+/**
+ * gtk_tree_store_remove:
+ * @tree_store: A #GtkTreeStore
+ * @iter: A valid #GtkTreeIter
+ * 
+ * Removes @iter from @tree_store.  After being removed, @iter is set to the
+ * next valid row at that level, or invalidated if it previeously pointed to the last one.
+ **/
 void
-gtk_tree_store_remove (GtkTreeStore *model,
+gtk_tree_store_remove (GtkTreeStore *tree_store,
 		       GtkTreeIter  *iter)
 {
   GtkTreePath *path;
   GtkTreeIter new_iter = {0,};
   GNode *parent;
+  GNode *next_node;
 
-  g_return_if_fail (GTK_IS_TREE_STORE (model));
-  g_return_if_fail (VALID_ITER (iter, model));
+  g_return_if_fail (GTK_IS_TREE_STORE (tree_store));
+  g_return_if_fail (VALID_ITER (iter, tree_store));
 
   parent = G_NODE (iter->user_data)->parent;
 
   g_assert (parent != NULL);
+  next_node = G_NODE (iter->user_data);
 
   if (G_NODE (iter->user_data)->data)
     _gtk_tree_data_list_free ((GtkTreeDataList *) G_NODE (iter->user_data)->data,
-			      model->column_headers);
+			      tree_store->column_headers);
 
-  path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), iter);
+  path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), iter);
   g_node_destroy (G_NODE (iter->user_data));
 
-  model->stamp++;
-  gtk_tree_model_deleted (GTK_TREE_MODEL (model), path);
+  tree_store->stamp++;
+  gtk_tree_model_deleted (GTK_TREE_MODEL (tree_store), path);
 
-  if (parent != G_NODE (model->root))
+  if (parent != G_NODE (tree_store->root))
     {
       /* child_toggled */
       if (parent->children == NULL)
 	{
 	  gtk_tree_path_up (path);
 
-	  new_iter.stamp = model->stamp;
+	  new_iter.stamp = tree_store->stamp;
 	  new_iter.user_data = parent;
-	  gtk_tree_model_has_child_toggled (GTK_TREE_MODEL (model), path, &new_iter);
-	}
-
-      /* revalidate iter */
-      while (parent != G_NODE (model->root))
-	{
-	  if (parent->next != NULL)
-	    {
-	      iter->stamp = model->stamp;
-	      iter->user_data = parent->next;
-	      break;
-	    }
-	  parent = parent->parent;
+	  gtk_tree_model_has_child_toggled (GTK_TREE_MODEL (tree_store), path, &new_iter);
 	}
     }
   gtk_tree_path_free (path);
+
+  /* revalidate iter */
+  if (next_node != NULL)
+    {
+      iter->stamp = tree_store->stamp;
+      iter->user_data = next_node;
+    }
+  else
+    {
+      iter->stamp = 0;
+    }
 }
 
+/**
+ * gtk_tree_store_insert:
+ * @list_store: A #GtkListStore
+ * @iter: An unset #GtkTreeIter to set to the new row
+ * @parent: A valid #GtkTreeIter, or %NULL
+ * @position: position to insert the new row
+ *
+ * Creates a new row at @position.  If parent is non-NULL, then the row will be
+ * made a child of @parent.  Otherwise, the row will be created at the toplevel.
+ * If @position is larger than the number of rows at that level, then the new
+ * row will be inserted to the end of the list.  @iter will be changed to point
+ * to this new row.  The row will be empty before this function is called.  To
+ * fill in values, you need to call @gtk_list_store_set or
+ * @gtk_list_store_set_value.
+ *
+ **/
 void
-gtk_tree_store_insert (GtkTreeStore *model,
+gtk_tree_store_insert (GtkTreeStore *tree_store,
 		       GtkTreeIter  *iter,
 		       GtkTreeIter  *parent,
 		       gint          position)
@@ -931,29 +968,47 @@ gtk_tree_store_insert (GtkTreeStore *model,
   GtkTreePath *path;
   GNode *parent_node;
 
-  g_return_if_fail (GTK_IS_TREE_STORE (model));
+  g_return_if_fail (GTK_IS_TREE_STORE (tree_store));
   if (parent)
-    g_return_if_fail (VALID_ITER (parent, model));
+    g_return_if_fail (VALID_ITER (parent, tree_store));
 
   if (parent)
     parent_node = parent->user_data;
   else
-    parent_node = model->root;
+    parent_node = tree_store->root;
 
-  iter->stamp = model->stamp;
+  iter->stamp = tree_store->stamp;
   iter->user_data = g_node_new (NULL);
   g_node_insert (parent_node, position, G_NODE (iter->user_data));
 
-  path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), iter);
-  gtk_tree_model_inserted (GTK_TREE_MODEL (model), path, iter);
+  path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), iter);
+  gtk_tree_model_inserted (GTK_TREE_MODEL (tree_store), path, iter);
 
   gtk_tree_path_free (path);
 
-  validate_tree ((GtkTreeStore*)model);
+  validate_tree ((GtkTreeStore*)tree_store);
 }
 
+/**
+ * gtk_tree_store_insert_before:
+ * @tree_store: A #GtkTreeStore
+ * @iter: An unset #GtkTreeIter to set to the new row
+ * parent: A valid #GtkTreeIter, or %NULL
+ * @sibling: A valid #GtkTreeIter, or %NULL
+ *
+ * Inserts a new row before @sibling.  If @sibling is %NULL, then the row will
+ * be appended to the beginning of the @parent 's children.  If @parent and
+ * @sibling are %NULL, then the row will be appended to the toplevel.  If both
+ * @sibling and @parent are set, then @parent must be the parent of @sibling.
+ * When @sibling is set, @parent is optional.
+ *
+ * @iter will be changed to point to this new row.  The row will be empty after
+ * this function is called.  To fill in values, you need to call
+ * @gtk_tree_store_set or @gtk_tree_store_set_value.
+ *
+ **/
 void
-gtk_tree_store_insert_before (GtkTreeStore *model,
+gtk_tree_store_insert_before (GtkTreeStore *tree_store,
 			      GtkTreeIter  *iter,
 			      GtkTreeIter  *parent,
 			      GtkTreeIter  *sibling)
@@ -962,17 +1017,17 @@ gtk_tree_store_insert_before (GtkTreeStore *model,
   GNode *parent_node = NULL;
   GNode *new_node;
 
-  g_return_if_fail (GTK_IS_TREE_STORE (model));
+  g_return_if_fail (GTK_IS_TREE_STORE (tree_store));
   g_return_if_fail (iter != NULL);
   if (parent != NULL)
-    g_return_if_fail (VALID_ITER (parent, model));
+    g_return_if_fail (VALID_ITER (parent, tree_store));
   if (sibling != NULL)
-    g_return_if_fail (VALID_ITER (sibling, model));
+    g_return_if_fail (VALID_ITER (sibling, tree_store));
 
   new_node = g_node_new (NULL);
 
   if (parent == NULL && sibling == NULL)
-    parent_node = model->root;
+    parent_node = tree_store->root;
   else if (parent == NULL)
     parent_node = G_NODE (sibling->user_data)->parent;
   else if (sibling == NULL)
@@ -987,19 +1042,37 @@ gtk_tree_store_insert_before (GtkTreeStore *model,
 			sibling ? G_NODE (sibling->user_data) : NULL,
                         new_node);
 
-  iter->stamp = model->stamp;
+  iter->stamp = tree_store->stamp;
   iter->user_data = new_node;
 
-  path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), iter);
-  gtk_tree_model_inserted (GTK_TREE_MODEL (model), path, iter);
+  path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), iter);
+  gtk_tree_model_inserted (GTK_TREE_MODEL (tree_store), path, iter);
 
   gtk_tree_path_free (path);
 
-  validate_tree ((GtkTreeStore*)model);
+  validate_tree ((GtkTreeStore*)tree_store);
 }
 
+/**
+ * gtk_tree_store_insert_after:
+ * @tree_store: A #GtkTreeStore
+ * @iter: An unset #GtkTreeIter to set to the new row
+ * parent: A valid #GtkTreeIter, or %NULL
+ * @sibling: A valid #GtkTreeIter, or %NULL
+ *
+ * Inserts a new row after @sibling.  If @sibling is %NULL, then the row will be
+ * prepended to the beginning of the @parent 's children.  If @parent and
+ * @sibling are %NULL, then the row will be prepended to the toplevel.  If both
+ * @sibling and @parent are set, then @parent must be the parent of @sibling.
+ * When @sibling is set, @parent is optional.
+ *
+ * @iter will be changed to point to this new row.  The row will be empty after
+ * this function is called.  To fill in values, you need to call
+ * @gtk_tree_store_set or @gtk_tree_store_set_value.
+ *
+ **/
 void
-gtk_tree_store_insert_after (GtkTreeStore *model,
+gtk_tree_store_insert_after (GtkTreeStore *tree_store,
 			     GtkTreeIter  *iter,
 			     GtkTreeIter  *parent,
 			     GtkTreeIter  *sibling)
@@ -1008,17 +1081,17 @@ gtk_tree_store_insert_after (GtkTreeStore *model,
   GNode *parent_node;
   GNode *new_node;
 
-  g_return_if_fail (GTK_IS_TREE_STORE (model));
+  g_return_if_fail (GTK_IS_TREE_STORE (tree_store));
   g_return_if_fail (iter != NULL);
   if (parent != NULL)
-    g_return_if_fail (VALID_ITER (parent, model));
+    g_return_if_fail (VALID_ITER (parent, tree_store));
   if (sibling != NULL)
-    g_return_if_fail (VALID_ITER (sibling, model));
+    g_return_if_fail (VALID_ITER (sibling, tree_store));
 
   new_node = g_node_new (NULL);
 
   if (parent == NULL && sibling == NULL)
-    parent_node = model->root;
+    parent_node = tree_store->root;
   else if (parent == NULL)
     parent_node = G_NODE (sibling->user_data)->parent;
   else if (sibling == NULL)
@@ -1035,31 +1108,43 @@ gtk_tree_store_insert_after (GtkTreeStore *model,
 		       sibling ? G_NODE (sibling->user_data) : NULL,
                        new_node);
 
-  iter->stamp = model->stamp;
+  iter->stamp = tree_store->stamp;
   iter->user_data = new_node;
 
-  path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), iter);
-  gtk_tree_model_inserted (GTK_TREE_MODEL (model), path, iter);
+  path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), iter);
+  gtk_tree_model_inserted (GTK_TREE_MODEL (tree_store), path, iter);
 
   gtk_tree_path_free (path);
 
-  validate_tree ((GtkTreeStore*)model);
+  validate_tree ((GtkTreeStore*)tree_store);
 }
 
+/**
+ * gtk_tree_store_prepend:
+ * @tree_store: A #GtkTreeStore
+ * @iter: An unset #GtkTreeIter to set to the prepended row
+ * @parent: A valid #GtkTreeIter, or %NULL
+ * 
+ * Prepends a new row to @tree_store.  If @parent is non-NULL, then it will prepend
+ * the new row before the last child of @parent, otherwise it will prepend a row
+ * to the top level.  @iter will be changed to point to this new row.  The row
+ * will be empty after this function is called.  To fill in values, you need to
+ * call @gtk_tree_store_set or @gtk_tree_store_set_value.
+ **/
 void
-gtk_tree_store_prepend (GtkTreeStore *model,
+gtk_tree_store_prepend (GtkTreeStore *tree_store,
 			GtkTreeIter  *iter,
 			GtkTreeIter  *parent)
 {
   GNode *parent_node;
 
-  g_return_if_fail (GTK_IS_TREE_STORE (model));
+  g_return_if_fail (GTK_IS_TREE_STORE (tree_store));
   g_return_if_fail (iter != NULL);
   if (parent != NULL)
-    g_return_if_fail (VALID_ITER (parent, model));
+    g_return_if_fail (VALID_ITER (parent, tree_store));
 
   if (parent == NULL)
-    parent_node = model->root;
+    parent_node = tree_store->root;
   else
     parent_node = parent->user_data;
 
@@ -1067,47 +1152,59 @@ gtk_tree_store_prepend (GtkTreeStore *model,
     {
       GtkTreePath *path;
 
-      iter->stamp = model->stamp;
+      iter->stamp = tree_store->stamp;
       iter->user_data = g_node_new (NULL);
 
       g_node_prepend (parent_node, iter->user_data);
 
-      if (parent_node != model->root)
+      if (parent_node != tree_store->root)
 	{
-	  path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), parent);
-	  gtk_tree_model_has_child_toggled (GTK_TREE_MODEL (model), path, parent);
+	  path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), parent);
+	  gtk_tree_model_has_child_toggled (GTK_TREE_MODEL (tree_store), path, parent);
 	  gtk_tree_path_append_index (path, 0);
 	}
       else
 	{
-	  path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), iter);
+	  path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), iter);
 	}
-      gtk_tree_model_inserted (GTK_TREE_MODEL (model), path, iter);
+      gtk_tree_model_inserted (GTK_TREE_MODEL (tree_store), path, iter);
       gtk_tree_path_free (path);
     }
   else
     {
-      gtk_tree_store_insert_after (model, iter, parent, NULL);
+      gtk_tree_store_insert_after (tree_store, iter, parent, NULL);
     }
 
-  validate_tree ((GtkTreeStore*)model);
+  validate_tree ((GtkTreeStore*)tree_store);
 }
 
+/**
+ * gtk_tree_store_append:
+ * @tree_store: A #GtkTreeStore
+ * @iter: An unset #GtkTreeIter to set to the appended row
+ * @parent: A valid #GtkTreeIter, or %NULL
+ * 
+ * Appends a new row to @tree_store.  If @parent is non-NULL, then it will append the
+ * new row after the last child of @parent, otherwise it will append a row to
+ * the top level.  @iter will be changed to point to this new row.  The row will
+ * be empty after this function is called.  To fill in values, you need to call
+ * @gtk_tree_store_set or @gtk_tree_store_set_value.
+ **/
 void
-gtk_tree_store_append (GtkTreeStore *model,
+gtk_tree_store_append (GtkTreeStore *tree_store,
 		       GtkTreeIter  *iter,
 		       GtkTreeIter  *parent)
 {
   GNode *parent_node;
 
-  g_return_if_fail (GTK_IS_TREE_STORE (model));
+  g_return_if_fail (GTK_IS_TREE_STORE (tree_store));
   g_return_if_fail (iter != NULL);
 
   if (parent != NULL)
-    g_return_if_fail (VALID_ITER (parent, model));
+    g_return_if_fail (VALID_ITER (parent, tree_store));
 
   if (parent == NULL)
-    parent_node = model->root;
+    parent_node = tree_store->root;
   else
     parent_node = parent->user_data;
 
@@ -1115,58 +1212,85 @@ gtk_tree_store_append (GtkTreeStore *model,
     {
       GtkTreePath *path;
 
-      iter->stamp = model->stamp;
+      iter->stamp = tree_store->stamp;
       iter->user_data = g_node_new (NULL);
 
       g_node_append (parent_node, G_NODE (iter->user_data));
 
-      if (parent_node != model->root)
+      if (parent_node != tree_store->root)
 	{
-	  path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), parent);
-	  gtk_tree_model_has_child_toggled (GTK_TREE_MODEL (model), path, parent);
+	  path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), parent);
+	  gtk_tree_model_has_child_toggled (GTK_TREE_MODEL (tree_store), path, parent);
 	  gtk_tree_path_append_index (path, 0);
 	}
       else
 	{
-	  path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), iter);
+	  path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), iter);
 	}
 
-      gtk_tree_model_inserted (GTK_TREE_MODEL (model), path, iter);
+      gtk_tree_model_inserted (GTK_TREE_MODEL (tree_store), path, iter);
       gtk_tree_path_free (path);
     }
   else
     {
-      gtk_tree_store_insert_before (model, iter, parent, NULL);
+      gtk_tree_store_insert_before (tree_store, iter, parent, NULL);
     }
 
-  validate_tree ((GtkTreeStore*)model);
+  validate_tree ((GtkTreeStore*)tree_store);
 }
 
+/**
+ * gtk_tree_store_is_ancestor:
+ * @tree_store: A #GtkTreeStore
+ * @iter: A valid #GtkTreeIter
+ * @descendant: A valid #GtkTreeIter
+ * 
+ * Returns %TRUE if @iter is an ancestor of @descendant.  That is, @iter is the
+ * parent (or grandparent or great-grandparent) of @descendant.
+ * 
+ * Return value: %TRUE, if @iter is an ancestor of @descendant
+ **/
 gboolean
-gtk_tree_store_is_ancestor (GtkTreeStore *model,
+gtk_tree_store_is_ancestor (GtkTreeStore *tree_store,
 			    GtkTreeIter  *iter,
 			    GtkTreeIter  *descendant)
 {
-  g_return_val_if_fail (GTK_IS_TREE_STORE (model), FALSE);
-  g_return_val_if_fail (VALID_ITER (iter, model), FALSE);
-  g_return_val_if_fail (VALID_ITER (descendant, model), FALSE);
+  g_return_val_if_fail (GTK_IS_TREE_STORE (tree_store), FALSE);
+  g_return_val_if_fail (VALID_ITER (iter, tree_store), FALSE);
+  g_return_val_if_fail (VALID_ITER (descendant, tree_store), FALSE);
 
   return g_node_is_ancestor (G_NODE (iter->user_data),
 			     G_NODE (descendant->user_data));
 }
 
 
+/**
+ * gtk_tree_store_iter_depth:
+ * @tree_store: A #GtkTreeStore
+ * @iter: A valid #GtkTreeIter
+ * 
+ * Returns the depth of @iter.  This will be 0 for anything on the root level, 1
+ * for anything down a level, etc.
+ * 
+ * Return value: The depth of @iter
+ **/
 gint
-gtk_tree_store_iter_depth (GtkTreeStore *model,
+gtk_tree_store_iter_depth (GtkTreeStore *tree_store,
 			   GtkTreeIter  *iter)
 {
-  g_return_val_if_fail (GTK_IS_TREE_STORE (model), 0);
-  g_return_val_if_fail (VALID_ITER (iter, model), 0);
+  g_return_val_if_fail (GTK_IS_TREE_STORE (tree_store), 0);
+  g_return_val_if_fail (VALID_ITER (iter, tree_store), 0);
 
   return g_node_depth (G_NODE (iter->user_data)) - 1;
 }
 
 
+/**
+ * gtk_tree_store_clear:
+ * @tree_store: @ #GtkTreeStore
+ * 
+ * Removes all rows from @tree_store
+ **/
 void
 gtk_tree_store_clear (GtkTreeStore *tree_store)
 {