Re: Custom TreeModel

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 

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

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

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]