Add an example to the docs

svn path=/trunk/; revision=20935

ChangeLog

@@ -1,3 +1,12 @@
+2008-08-02  Matthias Clasen  <mclasen@redhat.com>
+
+	Bug 523950 – GtkTreeModelFilter's visible function may get an empty
+	row
+
+	* gtk/gtktreemodelfilter.c (gtk_tree_model_filter_set_visible_func):
+	Explain and show how iterators pointing to empty rows should be
+	handled in the visible function. Patch by Björn Lindqvist
+
 2008-08-02  Matthias Clasen  <mclasen@redhat.com>
 
 	Bug 539733 – No way to control treeview separator height

gtk/gtktreemodelfilter.c

@@ -2884,6 +2884,29 @@ gtk_tree_model_filter_get_model (GtkTreeModelFilter *filter)
  * gtk_tree_model_filter_refilter() to keep the visibility information of 
  * the model uptodate.
  *
+ * Note that @func is called whenever a row is inserted, when it may still be
+ * empty. The visible function should therefore take special care of empty
+ * rows, like in the example below.
+ *
+ * <informalexample><programlisting>
+ * static gboolean
+ * visible_func (GtkTreeModel *model,
+ *               GtkTreeIter  *iter,
+ *               gpointer      data)
+ * {
+ *   /&ast; Visible if row is non-empty and first column is "HI" &ast;/
+ *   gchar *str;
+ *   gboolean visible = FALSE;
+ *
+ *   gtk_tree_model_get (model, iter, 0, &str, -1);
+ *   if (str && strcmp (str, "HI") == 0)
+ *     visible = TRUE;
+ *   g_free (str);
+ *
+ *   return visible;
+ * }
+ * </programlisting></informalexample>
+ *
  * Since: 2.4
  */
 void