improve liststore docs

docs/reference/ChangeLog

@@ -1,3 +1,8 @@
+2006-02-10  Matthias Clasen  <mclasen@redhat.com>
+
+	* gtk/tmpl/gtkliststore.sgml: Add a section about
+	atomicity of insertions. (#329831, Milosz Derezynski)
+
 2006-02-03  Matthias Clasen  <mclasen@redhat.com>
 
 	* gtk/tmpl/gtkmenushell.sgml: 

docs/reference/gtk/tmpl/gtkliststore.sgml

@@ -91,6 +91,19 @@ that #GtkTreeIter<!-- -->s can be cached while the row exists.  Thus, if
 access to a particular row is needed often and your code is expected to
 run on older versions of GTK+, it is worth keeping the iter around.
 </para>
+<title>Atomic Operations</title>
+<para>
+It is important to note that only the methods @gtk_list_store_insert_with_values and
+@gtk_list_store_insert_with_valuesv are atomic, in the sense that the row is being appended
+to the store and the values filled in in a single operation with regard to #GtkTreeModel signaling.
+In contrast, using e.g. @gtk_list_store_append and then @gtk_list_store_set will first create a row,
+which triggers the "row_inserted" #GtkTreeModel signal on #GtkListStore. The row, however, is still
+empty, and any signal handler connecting to "row_inserted" on this particular store should be prepared
+for the situation that the row might be empty.
+This is especially important if you are wrapping the #GtkListStore inside a #GtkTreeModelFilter and are
+using a #GtkTreeModelFilterVisibleFunc. Using any of the non-atomic operations to append rows to the #GtkListStore
+will cause the #GtkTreeModelFilterVisibleFunc to be visited with an empty row first; the function must be prepared for that.
+</para>
 </refsect2>
 
 <!-- ##### SECTION See_Also ##### -->