From 35cecde0c82ce6b018bb742a23ac6f4260782549 Mon Sep 17 00:00:00 2001
From: "Neil J. Patel" <njp@openedhand.com>
Date: Thu, 15 Nov 2007 17:10:12 +0000
Subject: [PATCH] 2007-11-15  Neil J. Patel  <njp@o-hand.com>

	* clutter/clutter-model.c:
	Added some more examples to the documentation, plus explained how the
	iters work internally.
---
 ChangeLog               |  6 ++++++
 clutter/clutter-model.c | 40 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index be5d8d0ba..6365a5daa 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2007-11-15  Neil J. Patel  <njp@o-hand.com>
+
+	* clutter/clutter-model.c:
+	Added some more examples to the documentation, plus explained how the
+	iters work internally.
+
 2007-11-15  Øyvind Kolås  <pippin@o-hand.com>
 
 	* clutter/clutter-main.[ch]: added clutter_grab_pointer,
diff --git a/clutter/clutter-model.c b/clutter/clutter-model.c
index abf46c82f..e26996a66 100644
--- a/clutter/clutter-model.c
+++ b/clutter/clutter-model.c
@@ -64,6 +64,46 @@
  * }
  * </programlisting>
  *
+ * Iterating through the model consists of retrieving a new #ClutterModelIter
+ * pointing to the starting row, and calling #clutter_model_iter_next or
+ * #clutter_model_iter_prev to move forward or backwards, repectively.
+ *
+ * A valid #ClutterModelIter represents the position between two rows in the
+ * model. For example, the @begin iterator represents the gap immediately 
+ * before the first row, and the @end iterator represents the gap immediately
+ * after the last row. In an empty sequence, the begin and end iterators are
+ * the same.
+ *
+ * Iterating a #ClutterModel:
+  * <programlisting>
+ * enum {
+ *   COLUMN_INT,
+ *   COLUMN_STRING.
+ *   N_COLUMNS
+ * };
+ * 
+ * {
+ *   ClutterModel *model;
+ *   ClutterModelIter *iter = NULL;
+ *
+ *   model = clutter_model_new (2, G_TYPE_INT, G_TYPE_STRING);
+ *  
+ *   /<!-- -->*  Fill the model *<!-- -->/
+ *   populate_model (model);
+ *
+ *   /<!-- -->* Get the first iter *<!-- -->/
+ *   iter = clutter_model_get_first_iter (model);
+ *   while (!clutter_model_iter_is_last (iter))
+ *     {
+ *       print_row (iter);
+ *       
+ *       iter = clutter_model_iter_next (iter);
+ *     }
+ *
+ *   /<!-- -->* Make sure to unref the iter *<!-- -->/
+ *   g_object_unref (iter);
+ * }
+ * </programlisting>
  *
  * #ClutterModel is available since Clutter 0.6
  */