From 3f99e8efb2cb9d3138b095d8a7abf5a9968d8741 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 10 Feb 2006 19:33:17 +0000 Subject: [PATCH] improve liststore docs --- docs/reference/ChangeLog | 5 +++++ docs/reference/gtk/tmpl/gtkliststore.sgml | 13 +++++++++++++ 2 files changed, 18 insertions(+) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 3189d5ee93..e2635b8a34 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,8 @@ +2006-02-10 Matthias Clasen + + * gtk/tmpl/gtkliststore.sgml: Add a section about + atomicity of insertions. (#329831, Milosz Derezynski) + 2006-02-03 Matthias Clasen * gtk/tmpl/gtkmenushell.sgml: diff --git a/docs/reference/gtk/tmpl/gtkliststore.sgml b/docs/reference/gtk/tmpl/gtkliststore.sgml index ebebf7421e..29db5a45f9 100644 --- a/docs/reference/gtk/tmpl/gtkliststore.sgml +++ b/docs/reference/gtk/tmpl/gtkliststore.sgml @@ -91,6 +91,19 @@ that #GtkTreeIters 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. +Atomic Operations + +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. +