1Gtk2::TreeModel(3)    User Contributed Perl Documentation   Gtk2::TreeModel(3)
2
3
4

NAME

6       Gtk2::TreeModel - wrapper for GtkTreeModel
7

SYNOPSIS

9        # Three ways of getting the iter pointing to the location 3:2:5
10
11        # get the iterator from a string
12        $iter = $model->get_iter_from_string ("3:2:5");
13
14        # get the iterator from a path
15        $path = Gtk2::TreePath->new_from_string ("3:2:5");
16        $iter = $model->get_iter ($path);
17
18        # 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
23
24        # getting and setting values
25
26        # assuming a model with these columns
27        use constant STRING_COLUMN => 0;
28        use constant INT_COLUMN => 1;
29
30        # set values
31        $model->set ($iter,
32                     STRING_COLUMN, $new_string_value,
33                     INT_COLUMN, $new_int_value);
34
35        # and get values
36        ($int, $str) = $model->get ($iter, INT_COLUMN, STRING_COLUMN);
37
38        # if you don't specify a list of column numbers,
39        # you get all of them.
40        @values = $model->get ($iter);
41

DESCRIPTION

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
47       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
57       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
67       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
74       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
82       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
90       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
99       (The preceding description and most of the method descriptions have
100       been adapted directly from the Gtk+ C API reference.)
101

HIERARCHY

103         Glib::Interface
104         +----Gtk2::TreeModel
105

METHODS

107   string = $tree_model->get_column_type ($index_)
108       •   $index_ (integer)
109
110       Returns the type of column $index_ as a package name.
111
112   treemodelflags = $tree_model->get_flags
113   $model->foreach ($func, $user_data=undef)
114       •   $func (subroutine)
115
116       •   $user_data (scalar)
117
118       Call $func on each row in $model as
119
120           bool = &$func ($model, $path, $iter, $user_data)
121
122       If $func returns true, the tree ceases to be walked, and
123       "$treemodel->foreach" returns.
124
125   $tree_model->get ($iter, ...)
126       •   $iter (Gtk2::TreeIter)
127
128       •   ... (list) of column indices
129
130       Fetch and return the model's values in the row pointed to by $iter.  If
131       you specify no column indices, it returns the values for all of the
132       columns, otherwise, returns just those columns' values (in order).
133
134       This overrides overrides Glib::Object's "get", so you'll want to use
135       "$object->get_property" to get object properties.
136
137   treeiter = $tree_model->iter_children ($parent)
138       •   $parent (Gtk2::TreeIter or undef)
139
140       Returns undef if $parent has no children, otherwise, returns a new iter
141       to the first child of $parent.  $parent is unaltered.  If $parent is
142       undef, this is equivalent to "Gtk2::TreeModel::get_iter_first".
143
144   treeiter = $tree_model->get_iter_first
145       Return a new iter pointing to the first node in the tree (the one at
146       path "0"), or undef if the tree is empty.
147
148   treeiter = $tree_model->get_iter_from_string ($path_string)
149       •   $path_string (string)
150
151       Returns a new iter pointing to the node described by $path_string, or
152       undef if the path does not exist.
153
154   treeiter = $tree_model->get_iter ($path)
155       •   $path (Gtk2::TreePath)
156
157       Returns a new Gtk2::TreeIter corresponding to $path.
158
159   boolean = $tree_model->iter_has_child ($iter)
160       •   $iter (Gtk2::TreeIter)
161
162       Returns true if $iter has child nodes.
163
164   integer = $tree_model->iter_n_children ($iter=undef)
165       •   $iter (Gtk2::TreeIter or undef)
166
167       Returns the number of children $iter has.  If $iter is undef (or
168       omitted) then returns the number of toplevel nodes.
169
170   treeiter = $tree_model->iter_next ($iter)
171       •   $iter (Gtk2::TreeIter)
172
173       Return a new iter pointing to node following $iter at the current
174       level, or undef if there is no next node.  $iter is unaltered.  (Note:
175       this is different from the C version, which modifies the iter.)
176
177   treeiter = $tree_model->iter_nth_child ($parent, $n)
178       •   $parent (Gtk2::TreeIter or undef)
179
180       •   $n (integer)
181
182       Returns an iter to the child of $parent at index $n, or undef if there
183       is no such child.  $parent is unaltered.
184
185   treeiter = $tree_model->iter_parent ($child)
186       •   $child (Gtk2::TreeIter)
187
188       Returns a new iter pointing to $child's parent node, or undef if $child
189       doesn't have a parent.  $child is unaltered.
190
191   integer = $tree_model->get_n_columns
192   treepath = $tree_model->get_path ($iter)
193       •   $iter (Gtk2::TreeIter)
194
195       Return a new Gtk2::TreePath corresponding to $iter.
196
197   $tree_model->ref_node ($iter)
198       •   $iter (Gtk2::TreeIter)
199
200       Lets the tree ref the node. This is an optional method for models to
201       implement.  To be more specific, models may ignore this call as it
202       exists primarily for performance reasons.
203
204       This function is primarily meant as a way for views to let caching
205       model know when nodes are being displayed (and hence, whether or not to
206       cache that node.)  For example, a file-system based model would not
207       want to keep the entire file-hierarchy in memory, just the sections
208       that are currently being displayed by every current view.
209
210       A model should be expected to be able to get an iter independent of its
211       reffed state.
212
213   $tree_model->row_changed ($path, $iter)
214       •   $path (Gtk2::TreePath)
215
216       •   $iter (Gtk2::TreeIter)
217
218       Emits the "row_changed" signal on $tree_model.
219
220   $tree_model->row_deleted ($path)
221       •   $path (Gtk2::TreePath)
222
223       Emits the "row_deleted" signal on $tree_model.  This should be called
224       by models after a row has been removed.  The location pointed to by
225       $path should be the removed row's old location.  It may not be a valid
226       location anymore.
227
228   $tree_model->row_has_child_toggled ($path, $iter)
229       •   $path (Gtk2::TreePath)
230
231       •   $iter (Gtk2::TreeIter)
232
233       Emits the "row_has_child_toggled" signal on $tree_model.  This should
234       be called by models after the child state of a node changes.
235
236   $tree_model->row_inserted ($path, $iter)
237       •   $path (Gtk2::TreePath)
238
239       •   $iter (Gtk2::TreeIter)
240
241       Emits the "row_inserted" signal on $tree_model.
242
243   $tree_model->rows_reordered ($path, $iter, ...)
244       •   $path (Gtk2::TreePath) the tree node whose children have been
245           reordered
246
247       •   $iter (Gtk2::TreeIter or undef) the tree node whose children have
248           been reordered
249
250       •   ... (list) list of integers mapping the current position of each
251           child to its old position before the re-ordering, i.e.
252           $new_order[$newpos] = $oldpos.  There should be as many elements in
253           this list as there are rows in $tree_model.
254
255       Emits the "rows-reordered" signal on $tree_model/  This should be
256       called by models with their rows have been reordered.
257
258   string = $tree_model->get_string_from_iter ($iter)
259       •   $iter (Gtk2::TreeIter)
260
261       Generates a string representation of the iter.  This string is a ':'
262       separated list of numbers.  For example, "4:10:0:3" would be an
263       acceptable return value for this string.
264
265       Since: gtk+ 2.2
266
267   $tree_model->unref_node ($iter)
268       •   $iter (Gtk2::TreeIter)
269
270       Lets the tree unref the node. This is an optional method for models to
271       implement. To be more specific, models may ignore this call as it
272       exists primarily for performance reasons.
273
274       For more information on what this means, see
275       "Gtk2::TreeModel::ref_node".  Please note that nodes that are deleted
276       are not unreffed.
277
278   $tree_model->get_value ($iter, ...)
279       •   $iter (Gtk2::TreeIter)
280
281       •   ... (list) of column indices
282
283       Alias for get.
284

CREATING A CUSTOM TREE MODEL

286       GTK+ provides two model implementations, Gtk2::TreeStore and
287       Gtk2::ListStore, which should be sufficient in most cases.  For some
288       cases, however, it is advantageous to provide a custom tree model
289       implementation.  It is possible to create custom tree models in Perl,
290       because we're cool like that.
291
292       To do this, you create a Glib::Object derivative which implements the
293       Gtk2::TreeModel interface; this is gtk2-perl-speak for "you have to add
294       a special key when you register your object type."  For example:
295
296         package MyModel;
297         use Gtk2;
298         use Glib::Object::Subclass
299             Glib::Object::,
300             interfaces => [ Gtk2::TreeModel:: ],
301             ;
302
303       This will cause perl to call several virtual methods with
304       ALL_CAPS_NAMES when Gtk+ attempts to perform certain actions on the
305       model.  You simply provide (or override) those methods.
306
307   TREE ITERS
308       Gtk2::TreeIter is normally an opaque object, but on the implementation
309       side of a Gtk2::TreeModel, you have to define what's inside.  The
310       virtual methods described below deal with iters as a reference to an
311       array containing four values:
312
313       o stamp (integer)
314           A number unique to this model.
315
316       o user_data (integer)
317           An arbitrary integer value.
318
319       o user_data2 (scalar)
320           An arbitrary reference.  Will not persist.  May be undef.
321
322       o user_data3 (scalar)
323           An arbitrary reference.  Will not persist.  May be undef.
324
325       The two references, if used, will generally be to data within the
326       model, like a row array, or a node object in a tree or linked list.
327       Keeping the things referred to alive is the model's responsibility.  An
328       iter doesn't make them persist, and if the things are destroyed then
329       any iters still containing them will become invalid (and result in
330       memory corruption if used).  An iter only has to remain valid until the
331       model contents change, so generally anything internal to the model is
332       fine.
333
334   VIRTUAL METHODS
335       An implementation of
336
337       treemodelflags = GET_FLAGS ($model)
338       integer = GET_N_COLUMNS ($model)
339       string = GET_COLUMN_TYPE ($model, $index)
340       ARRAYREF = GET_ITER ($model, $path)
341           See above for a description of what goes in the returned array
342           reference.
343
344       treepath = GET_PATH ($model, ARRAYREF)
345       scalar = GET_VALUE ($model, ARRAYREF, $column)
346           Implements $treemodel->get().
347
348       ARRAYREF = ITER_NEXT ($model, ARRAYREF)
349       ARRAYREF = ITER_CHILDREN ($model, ARRAYREF)
350       boolean = ITER_HAS_CHILD ($model, ARRAYREF)
351       integer = ITER_N_CHILDREN ($model, ARRAYREF)
352       ARRAYREF = ITER_NTH_CHILD ($model, ARRAYREF, $n)
353       ARRAYREF = ITER_PARENT ($model, ARRAYREF)
354       REF_NODE ($model, ARRAYREF)
355           Optional.
356
357       UNREF_NODE ($model, ARRAYREF)
358           Optional.
359

SIGNALS

361       row-changed (Gtk2::TreeModel, Gtk2::TreePath, Gtk2::TreeIter)
362       row-deleted (Gtk2::TreeModel, Gtk2::TreePath)
363       row-has-child-toggled (Gtk2::TreeModel, Gtk2::TreePath, Gtk2::TreeIter)
364       row-inserted (Gtk2::TreeModel, Gtk2::TreePath, Gtk2::TreeIter)
365       rows-reordered (Gtk2::TreeModel, Gtk2::TreePath, Gtk2::TreeIter,
366       gpointer)
367
368       Note that currently in a Perl subclass of an object implementing
369       "Gtk2::TreeModel", the class closure, ie. class default signal handler,
370       for the "rows-reordered" signal is called only with an integer address
371       for the reorder array parameter, not a Perl arrayref like a handler
372       installed with "signal_connect" receives.  It works to
373       "signal_chain_from_overridden" with the address, but it's otherwise
374       fairly useless and will likely change in the future.
375

ENUMS AND FLAGS

377   flags Gtk2::TreeModelFlags
378       •   'iters-persist' / 'GTK_TREE_MODEL_ITERS_PERSIST'
379
380       •   'list-only' / 'GTK_TREE_MODEL_LIST_ONLY'
381

SEE ALSO

383       Gtk2, Glib::Interface
384
386       Copyright (C) 2003-2011 by the gtk2-perl team.
387
388       This software is licensed under the LGPL.  See Gtk2 for a full notice.
389
390
391
392perl v5.34.0                      2022-01-21                Gtk2::TreeModel(3)
Impressum