1Gtk2::TreeModel(3) User Contributed Perl Documentation Gtk2::TreeModel(3)
2
6 Gtk2::TreeModel
7
9 # Three ways of getting the iter pointing to the location 3:2:5
10 # get the iterator from a string
12 $iter = $model->get_iter_from_string ("3:2:5");
13 # get the iterator from a path
15 $path = Gtk2::TreePath->new_from_string ("3:2:5");
16 $iter = $model->get_iter ($path);
17 # walk the tree to find the iterator
19 $iter = $model->iter_nth_child (undef, 3);
20 $iter = $model->iter_nth_child ($iter, 2);
21 $iter = $model->iter_nth_child ($iter, 5);
22 # getting and setting values
25 # assuming a model with these columns
27 use constant STRING_COLUMN => 0;
28 use constant INT_COLUMN => 1;
29 # set values
31 $model->set ($iter,
32 STRING_COLUMN, $new_string_value,
33 INT_COLUMN, $new_int_value);
34 # and get values
36 ($int, $str) = $model->get ($iter, INT_COLUMN, STRING_COLUMN);
37 # if you don't specify a list of column numbers,
39 # you get all of them.
40 @values = $model->get ($iter);
41
43 The Gtk2::TreeModel provides a generic tree interface for use by the
44 Gtk2::TreeView widget. It is an abstract interface, designed to be
45 usable with any appropriate data structure.
46 The model is represented as a hierarchical tree of strongly-typed,
48 columned data. In other words, the model can be seen as a tree where
49 every node has different values depending on which column is being
50 queried. The type of data found in a column is determined by using the
51 GType system (i.e. package names like Glib::Int, Gtk2::Button,
52 Glib::Scalar, etc). The types are homogeneous per column across all
53 nodes. It is important to note that this interface only provides a way
54 of examining a model and observing changes. The implementation of each
55 individual model decides how and if changes are made.
56 In order to make life simpler for programmers who do not need to write
58 their own specialized model, two generic models are provided - the
59 Gtk2::TreeStore and the Gtk2::ListStore. To use these, the developer
60 simply pushes data into these models as necessary. These models
61 provide the data structure as well as all appropriate tree interfaces.
62 As a result, implementing drag and drop, sorting, and storing data is
63 trivial. For the vast majority of trees and lists, these two models
64 are sufficient. For information on how to implement your own model in
65 Perl, see "CREATING A CUSTOM TREE MODEL".
66 Models are accessed on a node/column level of granularity. One can
68 query for the value of a model at a certain node and a certain column
69 on that node. There are two structures used to reference a particular
70 node in a model: the Gtk2::TreePath and the Gtk2::TreeIter (short for
71 "iterator"). Most of the interface consists of operations on a
72 Gtk2::TreeIter.
73 A path is essentially a potential node. It is a location on a model
75 that may or may not actually correspond to a node on a specific model.
76 The Gtk2::TreePath object can be converted into either an array of
77 unsigned integers or a string. The string form is a list of numbers
78 separated by a colon. Each number refers to the offset at that level.
79 Thus, the path '0' refers to the root node and the path '2:4' refers to
80 the fifth child of the third node.
81 By contrast, a Gtk2::TreeIter is a reference to a specific node on a
83 specific model. To the user of a model, the iter is merely an opaque
84 object. One can convert a path to an iterator by calling
85 "Gtk2::TreeModel::get_iter". These iterators are the primary way of
86 accessing a model and are similar to the iterators used by
87 Gtk2::TextBuffer. The model interface defines a set of operations using
88 them for navigating the model.
89 The iterators are generally used only for a short time, and their
91 behaviour is different to that suggested by the Gtk+ documentation.
92 They are not valid when the model is changed, even though get_flags
93 returns 'iters-persist'. Iterators obtained within a
94 GtkTreeModelForeachFunc are also invalid after the foreach terminates.
95 There may be other such cases. In the foreach case, and perhaps others,
96 a persistent iterator may be obtained by copying it (see
97 Glib::Boxed->copy).
98 (The preceding description and most of the method descriptions have
100 been adapted directly from the Gtk+ C API reference.)
101
103 Glib::Interface
104 +----Gtk2::TreeModel
105
107 string = $tree_model->get_column_type ($index_)
108 · $index_ (integer)
109 Returns the type of column $index_ as a package name.
111 treemodelflags = $tree_model->get_flags
113 $model->foreach ($func, $user_data=undef)
114 · $func (subroutine)
115 · $user_data (scalar)
117 Call $func on each row in $model as
119 bool = &$func ($model, $path, $iter, $user_data)
121 If $func returns true, the tree ceases to be walked, and
123 "$treemodel->foreach" returns.
124 $tree_model->get ($iter, ...)
126 · $iter (Gtk2::TreeIter)
127 · ... (list) of column indices
129 Fetch and return the model's values in the row pointed to by $iter.
131 If you specify no column indices, it returns the values for all of
132 the columns, otherwise, returns just those columns' values (in
133 order).
134 This overrides overrides Glib::Object's "get", so you'll want to
136 use "$object->get_property" to get object properties.
137 treeiter = $tree_model->iter_children ($parent)
139 · $parent (Gtk2::TreeIter or undef)
140 Returns undef if $parent has no children, otherwise, returns a new
142 iter to the first child of $parent. $parent is unaltered. If
143 $parent is undef, this is equivalent to
144 "Gtk2::TreeModel::get_iter_first".
145 treeiter = $tree_model->get_iter_first
147 Return a new iter pointing to the first node in the tree (the one
148 at path "0"), or undef if the tree is empty.
149 treeiter = $tree_model->get_iter_from_string ($path_string)
151 · $path_string (string)
152 Returns a new iter pointing to the node described by $path_string,
154 or undef if the path does not exist.
155 treeiter = $tree_model->get_iter ($path)
157 · $path (Gtk2::TreePath)
158 Returns a new Gtk2::TreeIter corresponding to $path.
160 boolean = $tree_model->iter_has_child ($iter)
162 · $iter (Gtk2::TreeIter)
163 Returns true if $iter has child nodes.
165 integer = $tree_model->iter_n_children ($iter=undef)
167 · $iter (Gtk2::TreeIter or undef)
168 Returns the number of children $iter has. If $iter is undef (or
170 omitted) then returns the number of toplevel nodes.
171 treeiter = $tree_model->iter_next ($iter)
173 · $iter (Gtk2::TreeIter)
174 Return a new iter pointing to node following $iter at the current
176 level, or undef if there is no next node. $iter is unaltered.
177 (Note: this is different from the C version, which modifies the
178 iter.)
179 treeiter = $tree_model->iter_nth_child ($parent, $n)
181 · $parent (Gtk2::TreeIter or undef)
182 · $n (integer)
184 Returns an iter to the child of $parent at index $n, or undef if
186 there is no such child. $parent is unaltered.
187 treeiter = $tree_model->iter_parent ($child)
189 · $child (Gtk2::TreeIter)
190 Returns a new iter pointing to $child's parent node, or undef if
192 $child doesn't have a parent. $child is unaltered.
193 integer = $tree_model->get_n_columns
195 treepath = $tree_model->get_path ($iter)
196 · $iter (Gtk2::TreeIter)
197 Return a new Gtk2::TreePath corresponding to $iter.
199 $tree_model->ref_node ($iter)
201 · $iter (Gtk2::TreeIter)
202 Lets the tree ref the node. This is an optional method for models
204 to implement. To be more specific, models may ignore this call as
205 it exists primarily for performance reasons.
206 This function is primarily meant as a way for views to let caching
208 model know when nodes are being displayed (and hence, whether or
209 not to cache that node.) For example, a file-system based model
210 would not want to keep the entire file-hierarchy in memory, just
211 the sections that are currently being displayed by every current
212 view.
213 A model should be expected to be able to get an iter independent of
215 its reffed state.
216 $tree_model->row_changed ($path, $iter)
218 · $path (Gtk2::TreePath)
219 · $iter (Gtk2::TreeIter)
221 Emits the "row_changed" signal on $tree_model.
223 $tree_model->row_deleted ($path)
225 · $path (Gtk2::TreePath)
226 Emits the "row_deleted" signal on $tree_model. This should be
228 called by models after a row has been removed. The location
229 pointed to by $path should be the removed row's old location. It
230 may not be a valid location anymore.
231 $tree_model->row_has_child_toggled ($path, $iter)
233 · $path (Gtk2::TreePath)
234 · $iter (Gtk2::TreeIter)
236 Emits the "row_has_child_toggled" signal on $tree_model. This
238 should be called by models after the child state of a node changes.
239 $tree_model->row_inserted ($path, $iter)
241 · $path (Gtk2::TreePath)
242 · $iter (Gtk2::TreeIter)
244 Emits the "row_inserted" signal on $tree_model.
246 $tree_model->rows_reordered ($path, $iter, ...)
248 · $path (Gtk2::TreePath) the tree node whose children have been
249 reordered
250 · $iter (Gtk2::TreeIter or undef) the tree node whose children
252 have been reordered
253 · ... (list) list of integers mapping the current position of
255 each child to its old position before the re-ordering, i.e.
256 $new_order[$newpos] = $oldpos. There should be as many
257 elements in this list as there are rows in $tree_model.
258 Emits the "rows-reordered" signal on $tree_model/ This should be
260 called by models with their rows have been reordered.
261 string = $tree_model->get_string_from_iter ($iter)
263 · $iter (Gtk2::TreeIter)
264 Generates a string representation of the iter. This string is a
266 ':' separated list of numbers. For example, "4:10:0:3" would be an
267 acceptable return value for this string.
268 Since: gtk+ 2.2
270 $tree_model->unref_node ($iter)
272 · $iter (Gtk2::TreeIter)
273 Lets the tree unref the node. This is an optional method for models
275 to implement. To be more specific, models may ignore this call as
276 it exists primarily for performance reasons.
277 For more information on what this means, see
279 "Gtk2::TreeModel::ref_node". Please note that nodes that are
280 deleted are not unreffed.
281 $tree_model->get_value ($iter, ...)
283 · $iter (Gtk2::TreeIter)
284 · ... (list) of column indices
286 Alias for get.
288
290 GTK+ provides two model implementations, Gtk2::TreeStore and
291 Gtk2::ListStore, which should be sufficient in most cases. For some
292 cases, however, it is advantageous to provide a custom tree model
293 implementation. It is possible to create custom tree models in Perl,
294 because we're cool like that.
295 To do this, you create a Glib::Object derivative which implements the
297 Gtk2::TreeModel interface; this is gtk2-perl-speak for "you have to add
298 a special key when you register your object type." For example:
299 package MyModel;
301 use Gtk2;
302 use Glib::Object::Subclass
303 Glib::Object::,
304 interfaces => [ Gtk2::TreeModel:: ],
305 ;
306 This will cause perl to call several virtual methods with
308 ALL_CAPS_NAMES when Gtk+ attempts to perform certain actions on the
309 model. You simply provide (or override) those methods.
310 TREE ITERS
312 Gtk2::TreeIter is normally an opaque object, but on the implementation
313 side of a Gtk2::TreeModel, you have to define what's inside. The
314 virtual methods described below deal with iters as a reference to an
315 array containing four values:
316 o stamp (integer)
318 A number unique to this model.
319 o user_data (integer)
321 An arbitrary integer value.
322 o user_data2 (scalar)
324 An arbitrary reference. Will not persist. May be undef.
325 o user_data3 (scalar)
327 An arbitrary reference. Will not persist. May be undef.
328 The two references, if used, will generally be to data within the
330 model, like a row array, or a node object in a tree or linked list.
331 Keeping the things referred to alive is the model's responsibility. An
332 iter doesn't make them persist, and if the things are destroyed then
333 any iters still containing them will become invalid (and result in
334 memory corruption if used). An iter only has to remain valid until the
335 model contents change, so generally anything internal to the model is
336 fine.
337 VIRTUAL METHODS
339 An implementation of
340 treemodelflags = GET_FLAGS ($model)
342 integer = GET_N_COLUMNS ($model)
343 string = GET_COLUMN_TYPE ($model, $index)
344 ARRAYREF = GET_ITER ($model, $path)
345 See above for a description of what goes in the returned array
346 reference.
347 treepath = GET_PATH ($model, ARRAYREF)
349 scalar = GET_VALUE ($model, ARRAYREF, $column)
350 Implements $treemodel->get().
351 ARRAYREF = ITER_NEXT ($model, ARRAYREF)
353 ARRAYREF = ITER_CHILDREN ($model, ARRAYREF)
354 boolean = ITER_HAS_CHILD ($model, ARRAYREF)
355 integer = ITER_N_CHILDREN ($model, ARRAYREF)
356 ARRAYREF = ITER_NTH_CHILD ($model, ARRAYREF, $n)
357 ARRAYREF = ITER_PARENT ($model, ARRAYREF)
358 REF_NODE ($model, ARRAYREF)
359 Optional.
360 UNREF_NODE ($model, ARRAYREF)
362 Optional.
363
365 row-changed (Gtk2::TreeModel, Gtk2::TreePath, Gtk2::TreeIter)
366 row-inserted (Gtk2::TreeModel, Gtk2::TreePath, Gtk2::TreeIter)
367 row-has-child-toggled (Gtk2::TreeModel, Gtk2::TreePath, Gtk2::TreeIter)
368 row-deleted (Gtk2::TreeModel, Gtk2::TreePath)
369 rows-reordered (Gtk2::TreeModel, Gtk2::TreePath, Gtk2::TreeIter,
370 gpointer)
371 Note that currently in a Perl subclass of an object implementing
373 "Gtk2::TreeModel", the class closure, ie. class default signal handler,
374 for the "rows-reordered" signal is called only with an integer address
375 for the reorder array parameter, not a Perl arrayref like a handler
376 installed with "signal_connect" receives. It works to
377 "signal_chain_from_overridden" with the address, but it's otherwise
378 fairly useless and will likely change in the future.
379
381 flags Gtk2::TreeModelFlags
382 · 'iters-persist' / 'GTK_TREE_MODEL_ITERS_PERSIST'
383 · 'list-only' / 'GTK_TREE_MODEL_LIST_ONLY'
385
387 Gtk2, Glib::Interface
388
390 Copyright (C) 2003-2008 by the gtk2-perl team.
391 This software is licensed under the LGPL. See Gtk2 for a full notice.
393perl v5.12.0 2010-05-02 Gtk2::TreeModel(3)