Re: Custom TreeModel

[Kevin Ryde <user42 zip com au>]

muppet <scott asofyet org> writes:
> That passage found its way into the docs because of the discussion
> starting here:

Sounds like that was about the callback.  Perhaps something along the
following lines,


  A "Gtk2::TreePath" is numeric coordinates of a possible node.  A path
  object can be converted into either an array of unsigned integers or a
  string.  The string form is a list of numbers separated by a colon.
  Each number refers to the offset at that level.  Thus path '0' refers
  to the first toplevel node and path '2:4' refers to the fifth child of
  the third node.

  By contrast, a Gtk2::TreeIter is like a pointer to a specific node in a
  specific model.  Iters are the primary way to access row data or
  traverse a model.  A path is converted to an iter with
  "$model->get_iter".  An iterator is generally used only for a short
  time and is valid only while the model rows are unchanged.  If any row
  is deleted, inserted or reordered then all existing iters on that model
  become invalid and attempting to use one may result in a crash.  Iters
  on models with "iters-persist" in its "get_flags" last longer though,
  they remain good for as long as its row exists.  (See
  Gtk2::TreeRowReference for a long-lasting row ref which works in both
  cases.)

  Paths and iters are both "boxed" objects (see Glib::Boxed) and like
  many such objects if you're passed one in a signal call or
  "$model->foreach" then it's only good within that call and using it
  later may cause a crash.  Copy with "->copy" if necessary (remembering
  the above iter validity rule too).


diff --git a/xs/GtkTreeModel.xs b/xs/GtkTreeModel.xs
index 75676ca..d41492f 100644
--- a/xs/GtkTreeModel.xs
+++ b/xs/GtkTreeModel.xs
@@ -496,28 +496,30 @@ There are two structures used to reference a particular node in a model:
 the Gtk2::TreePath and the Gtk2::TreeIter (short for "iterator").  Most of
 the interface consists of operations on a Gtk2::TreeIter.
 
-A path is essentially a potential node.  It is a location on a model that
-may or may not actually correspond to a node on a specific model.  The
-Gtk2::TreePath object can be converted into either an array of unsigned
-integers or a string.  The string form is a list of numbers separated by a
-colon.  Each number refers to the offset at that level.  Thus, the path '0'
-refers to the root node and the path '2:4' refers to the fifth child of the
-third node.
-
-By contrast, a Gtk2::TreeIter is a reference to a specific node on a specific
-model.  To the user of a model, the iter is merely an opaque object.
-One can convert a path to an iterator by calling C<Gtk2::TreeModel::get_iter>.
-These iterators are the primary way of accessing a model and are
-similar to the iterators used by Gtk2::TextBuffer. The model interface
-defines a set of operations using them for navigating the model.
-
-The iterators are generally used only for a short time, and their
-behaviour is different to that suggested by the Gtk+ documentation. They
-are not valid when the model is changed, even though get_flags returns
-'iters-persist'. Iterators obtained within a GtkTreeModelForeachFunc are
-also invalid after the foreach terminates. There may be other such
-cases. In the foreach case, and perhaps others, a persistent iterator
-may be obtained by copying it (see Glib::Boxed->copy).
+A C<Gtk2::TreePath> is numeric coordinates of a possible node.  A path
+object can be converted into either an array of unsigned integers or a
+string.  The string form is a list of numbers separated by a colon.
+Each number refers to the offset at that level.  Thus path '0' refers
+to the first toplevel node and path '2:4' refers to the fifth child of
+the third node.
+
+By contrast, a Gtk2::TreeIter is like a pointer to a specific node in
+a specific model.  Iters are the primary way to access row data or
+traverse a model.  A path is converted to an iter with
+C<< $model->get_iter >>.  An iterator is generally used only for a
+short time and is valid only while the model rows are unchanged.  If
+any row is deleted, inserted or reordered then all existing iters on
+that model become invalid and attempting to use one may result in a
+crash.  Iters on models with C<iters-persist> in its C<get_flags> last
+longer though, they remain good for as long as its row exists.  (See
+L<Gtk2::TreeRowReference> for a long-lasting row ref which works in
+both cases.)
+
+Paths and iters are both "boxed" objects (see L<Glib::Boxed>) and like
+many such objects if you're passed one in a signal call or
+C<< $model->foreach >> then it's only good within that call and using
+it later may cause a crash.  Copy with C<< ->copy >> if necessary
+(remembering the above iter validity rule too).
 
 (The preceding description and most of the method descriptions have been
 adapted directly from the Gtk+ C API reference.)