add more to the docs.

Sun Nov 17 15:42:08 2002  Jonathan Blandford  <jrb@gnome.org>

        * gtk/tmpl/gtkliststore.sgml: add more to the docs.

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index f44391edb73e74f69cdfa3c67a7977c000f17fa0..8fdb835aea472652cf07ee7fcc6bcade59815303 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,7 @@
+Sun Nov 17 15:42:08 2002  Jonathan Blandford  <jrb@gnome.org>
+
+       * gtk/tmpl/gtkliststore.sgml: add more to the docs.
+
 2002-11-10  Matthias Clasen  <maclas@gmx.de>
 
        * gdk/gdk-sections.txt: gdk_display_open_default_libgtk_only

diff --git a/docs/reference/gtk/tmpl/gtkliststore.sgml b/docs/reference/gtk/tmpl/gtkliststore.sgml
index 6bfac2fcebb89ce6b821ddb70d706bab1732c305..a2954cae73af3ce98c2f47cbf7bd512dc6aa4c35 100644 (file)
--- a/docs/reference/gtk/tmpl/gtkliststore.sgml
+++ b/docs/reference/gtk/tmpl/gtkliststore.sgml
@@ -14,6 +14,18 @@ Finally, it also implements the tree <link linkend="gtktreednd">drag and
 drop</link> interfaces.
 </para>
 
+<para>
+The #GtkListStore can accept most GObject types as a column type, though
+it can't accept all custom types.  Internally, it will keep a copy of
+data passed in (such as a string or a boxed pointer).  Columns that
+accept #GObject<!-- -->s are handled a little differently.  The
+#GtkListStore will keep a reference to the object instead of copying the
+value.  As a result, if the object is modified, it is up to the
+application writer to call @gtk_tree_model_row_changed to emit the
+"row_changed" signal.  This most commonly effects lists with
+#GdkPixbuf<!-- -->s stored.
+</para>
+
 <example>
 <title>Creating a simple list store.</title>
 <programlisting>
@@ -22,7 +34,7 @@ enum {
   COLUMN_INT,
   COLUMN_BOOLEAN,
   N_COLUMNS
-}
+};
 
 {
   GtkListStore *list_store;
@@ -49,6 +61,9 @@ enum {
                           COLUMN_BOOLEAN,  FALSE,
                           -1);
 
+      /* As the store will keep a copy of the string internally, we
+       * free some_data.
+       */
       g_free (some_data);
     }
 
@@ -65,9 +80,21 @@ enum {
 </programlisting>
 </example>
 
-<!-- ##### SECTION See_Also ##### -->
+<refsect2>
+<title>Performance Considerations</title>
 <para>
+Internally, the #GtkListStore is implemented with a linked list with a
+tail pointer.  As a result, it is fast at data insertion and deletion,
+and not as fast at random data access.  The #GtkListStore sets the
+#GTK_TREE_MODEL_ITERS_PERSIST flag, which means that #GtkTreeIter<!--
+-->s can be cached while the row exists.  Thus, if access to a
+particular row is needed often, it is worth keeping the iter around.
+</para>
+</refsect>
 
+<!-- ##### SECTION See_Also ##### -->
+<para>
+#GtkTreeModel, #GtkTreeStore
 </para>
 
 <!-- ##### STRUCT GtkListStore ##### -->

diff --git a/docs/reference/gtk/tmpl/gtktreestore.sgml b/docs/reference/gtk/tmpl/gtktreestore.sgml
index 2c1bf106082eb8dcc3b65e66974205f57614d67f..b24b3ad4c808f8eaab14228ec76f50f8fbe07768 100644 (file)
--- a/docs/reference/gtk/tmpl/gtktreestore.sgml
+++ b/docs/reference/gtk/tmpl/gtktreestore.sgml
@@ -17,7 +17,7 @@ drop</link> interfaces.
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#GtkTreeModel, #GtkTreeStore
 </para>
 
 <!-- ##### STRUCT GtkTreeStore ##### -->