Re: Custom TreeModel

[Dave Howorth <dhoworth mrc-lmb cam ac uk>]

Kevin Ryde wrote:
> 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,

Thanks for taking the time to write a new version. I'd like to suggest a
couple of changes but I'm still confused about the actual semantics
though, so I can only provide draft text for one of them.

> 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.

I prefer the original version of the paragraph above. It emphasises the
distinction between a path and an iter better to my eyes.

> 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".

I prefer the original separation into paragraphs and don't have any
problem with the original wording of the "By contrast ..." paragraph.

>  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.

I like the new mention of the consequences of using an invalid iter.

> 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.)

This is what I'm not clear about. Does iters-persist cause this change
or not? If it does then the text under Creating a Custom Tree Model/Tree
Iters also needs some text explaining what is required. If not then the
original warning about differences from gtk+ needs reinstating.

> 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).

This is very important. Specifically, it should be stated in the
documentation for Glib::Boxed! Perhaps something like:

"Glib::Boxed is a generic wrapper mechanism for arbitrary C structures.
For the most part you don't care about this as a Perl developer, but it
is important to know that all Glib::Boxed descendents can be copied with
the copy method. You must make a copy when you wish to save a boxed
object that was given to you inside a callback from a signal or iterator."

In the Tree Model docs. It is probably also worth stating "The easiest
way to save a TreePath is to convert it to a string and save that:
$string = $treePath_object->to_string"

HTH, Dave