2 * Copyright (C) 2000 Red Hat, Inc., Jonathan Blandford <jrb@redhat.com>
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
22 #include <glib/gprintf.h>
23 #include <gobject/gvaluecollector.h>
24 #include "gtktreemodel.h"
25 #include "gtktreeview.h"
26 #include "gtktreeprivate.h"
27 #include "gtkmarshalers.h"
31 * SECTION:gtktreemodel
32 * @Title: GtkTreeModel
33 * @Short_description: The tree interface used by GtkTreeView
34 * @See_also: #GtkTreeView, #GtkTreeStore, #GtkListStore,
35 * <link linkend="gtk-GtkTreeView-drag-and-drop">GtkTreeDnd</link>,
38 * The #GtkTreeModel interface defines a generic tree interface for
39 * use by the #GtkTreeView widget. It is an abstract interface, and
40 * is designed to be usable with any appropriate data structure. The
41 * programmer just has to implement this interface on their own data
42 * type for it to be viewable by a #GtkTreeView widget.
44 * The model is represented as a hierarchical tree of strongly-typed,
45 * columned data. In other words, the model can be seen as a tree where
46 * every node has different values depending on which column is being
47 * queried. The type of data found in a column is determined by using
48 * the GType system (ie. #G_TYPE_INT, #GTK_TYPE_BUTTON, #G_TYPE_POINTER,
49 * etc). The types are homogeneous per column across all nodes. It is
50 * important to note that this interface only provides a way of examining
51 * a model and observing changes. The implementation of each individual
52 * model decides how and if changes are made.
54 * In order to make life simpler for programmers who do not need to
55 * write their own specialized model, two generic models are provided
56 * — the #GtkTreeStore and the #GtkListStore. To use these, the
57 * developer simply pushes data into these models as necessary. These
58 * models provide the data structure as well as all appropriate tree
59 * interfaces. As a result, implementing drag and drop, sorting, and
60 * storing data is trivial. For the vast majority of trees and lists,
61 * these two models are sufficient.
63 * Models are accessed on a node/column level of granularity. One can
64 * query for the value of a model at a certain node and a certain
65 * column on that node. There are two structures used to reference
66 * a particular node in a model. They are the #GtkTreePath and the
67 * #GtkTreeIter<footnote><para>Here, <abbrev>iter</abbrev> is short
68 * for <quote>iterator</quote></para></footnote>. Most of the interface
69 * consists of operations on a #GtkTreeIter.
71 * A path is essentially a potential node. It is a location on a model
72 * that may or may not actually correspond to a node on a specific
73 * model. The #GtkTreePath struct can be converted into either an
74 * array of unsigned integers or a string. The string form is a list
75 * of numbers separated by a colon. Each number refers to the offset
76 * at that level. Thus, the path <quote>0</quote> refers to the root
77 * node and the path <quote>2:4</quote> refers to the fifth child of
80 * By contrast, a #GtkTreeIter is a reference to a specific node on
81 * a specific model. It is a generic struct with an integer and three
82 * generic pointers. These are filled in by the model in a model-specific
83 * way. One can convert a path to an iterator by calling
84 * gtk_tree_model_get_iter(). These iterators are the primary way
85 * of accessing a model and are similar to the iterators used by
86 * #GtkTextBuffer. They are generally statically allocated on the
87 * stack and only used for a short time. The model interface defines
88 * a set of operations using them for navigating the model.
90 * It is expected that models fill in the iterator with private data.
91 * For example, the #GtkListStore model, which is internally a simple
92 * linked list, stores a list node in one of the pointers. The
93 * #GtkTreeModelSort stores an array and an offset in two of the
94 * pointers. Additionally, there is an integer field. This field is
95 * generally filled with a unique stamp per model. This stamp is for
96 * catching errors resulting from using invalid iterators with a model.
98 * The lifecycle of an iterator can be a little confusing at first.
99 * Iterators are expected to always be valid for as long as the model
100 * is unchanged (and doesn't emit a signal). The model is considered
101 * to own all outstanding iterators and nothing needs to be done to
102 * free them from the user's point of view. Additionally, some models
103 * guarantee that an iterator is valid for as long as the node it refers
104 * to is valid (most notably the #GtkTreeStore and #GtkListStore).
105 * Although generally uninteresting, as one always has to allow for
106 * the case where iterators do not persist beyond a signal, some very
107 * important performance enhancements were made in the sort model.
108 * As a result, the #GTK_TREE_MODEL_ITERS_PERSIST flag was added to
109 * indicate this behavior.
111 * To help show some common operation of a model, some examples are
112 * provided. The first example shows three ways of getting the iter at
113 * the location <quote>3:2:5</quote>. While the first method shown is
114 * easier, the second is much more common, as you often get paths from
118 * <title>Acquiring a <structname>GtkTreeIter</structname></title>
120 * /* Three ways of getting the iter pointing to the location */
123 * GtkTreeIter parent_iter;
125 * /* get the iterator from a string */
126 * gtk_tree_model_get_iter_from_string (model, &iter, "3:2:5");
128 * /* get the iterator from a path */
129 * path = gtk_tree_path_new_from_string ("3:2:5");
130 * gtk_tree_model_get_iter (model, &iter, path);
131 * gtk_tree_path_free (path);
133 * /* walk the tree to find the iterator */
134 * gtk_tree_model_iter_nth_child (model, &iter, NULL, 3);
135 * parent_iter = iter;
136 * gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, 2);
137 * parent_iter = iter;
138 * gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, 5);
142 * This second example shows a quick way of iterating through a list
143 * and getting a string and an integer from each row. The
144 * <function>populate_model</function> function used below is not
145 * shown, as it is specific to the #GtkListStore. For information on
146 * how to write such a function, see the #GtkListStore documentation.
149 * <title>Reading data from a <structname>GtkTreeModel</structname></title>
160 * GtkTreeModel *list_store;
163 * gint row_count = 0;
165 * /* make a new list_store */
166 * list_store = gtk_list_store_new (N_COLUMNS, G_TYPE_STRING, G_TYPE_INT);
168 * /* Fill the list store with data */
169 * populate_model (list_store);
171 * /* Get the first iter in the list */
172 * valid = gtk_tree_model_get_iter_first (list_store, &iter);
176 * /* Walk through the list, reading each row */
180 * /* Make sure you terminate calls to gtk_tree_model_get()
181 * * with a '-1' value
183 * gtk_tree_model_get (list_store, &iter,
184 * STRING_COLUMN, &str_data,
185 * INT_COLUMN, &int_data,
188 * /* Do something with the data */
189 * g_print ("Row %d: (%s,%d)\n", row_count, str_data, int_data);
193 * valid = gtk_tree_model_iter_next (list_store, &iter);
198 * The #GtkTreeModel interface contains two methods for reference
199 * counting: gtk_tree_model_ref_node() and gtk_tree_model_unref_node().
200 * These two methods are optional to implement. The reference counting
201 * is meant as a way for views to let models know when nodes are being
202 * displayed. #GtkTreeView will take a reference on a node when it is
203 * visible, which means the node is either in the toplevel or expanded.
204 * Being displayed does not mean that the node is currently directly
205 * visible to the user in the viewport. Based on this reference counting
206 * scheme a caching model, for example, can decide whether or not to cache
207 * a node based on the reference count. A file-system based model would
208 * not want to keep the entire file hierarchy in memory, but just the
209 * folders that are currently expanded in every current view.
211 * When working with reference counting, the following rules must be taken
214 * <listitem><para>Never take a reference on a node without owning a
215 * reference on its parent. This means that all parent nodes of a referenced
216 * node must be referenced as well.</para></listitem>
217 * <listitem><para>Outstanding references on a deleted node are not released.
218 * This is not possible because the node has already been deleted by the
219 * time the row-deleted signal is received.
221 * <listitem><para>Models are not obligated to emit a signal on rows of
222 * which none of its siblings are referenced. To phrase this differently,
223 * signals are only required for levels in which nodes are referenced. For
224 * the root level however, signals must be emitted at all times (however the
225 * root level is always referenced when any view is attached).
230 #define INITIALIZE_TREE_ITER(Iter) \
233 (Iter)->user_data = NULL; \
234 (Iter)->user_data2 = NULL; \
235 (Iter)->user_data3 = NULL; \
238 #define ROW_REF_DATA_STRING "gtk-tree-row-refs"
243 ROW_HAS_CHILD_TOGGLED,
249 static guint tree_model_signals[LAST_SIGNAL] = { 0 };
253 gint depth; /* Number of elements */
254 gint alloc; /* Number of allocated elements */
263 static void gtk_tree_model_base_init (gpointer g_class);
265 /* custom closures */
266 static void row_inserted_marshal (GClosure *closure,
267 GValue /* out */ *return_value,
269 const GValue *param_values,
270 gpointer invocation_hint,
271 gpointer marshal_data);
272 static void row_deleted_marshal (GClosure *closure,
273 GValue /* out */ *return_value,
275 const GValue *param_values,
276 gpointer invocation_hint,
277 gpointer marshal_data);
278 static void rows_reordered_marshal (GClosure *closure,
279 GValue /* out */ *return_value,
281 const GValue *param_values,
282 gpointer invocation_hint,
283 gpointer marshal_data);
285 static void gtk_tree_row_ref_inserted (RowRefList *refs,
288 static void gtk_tree_row_ref_deleted (RowRefList *refs,
290 static void gtk_tree_row_ref_reordered (RowRefList *refs,
296 gtk_tree_model_get_type (void)
298 static GType tree_model_type = 0;
300 if (! tree_model_type)
302 const GTypeInfo tree_model_info =
304 sizeof (GtkTreeModelIface), /* class_size */
305 gtk_tree_model_base_init, /* base_init */
306 NULL, /* base_finalize */
308 NULL, /* class_finalize */
309 NULL, /* class_data */
316 g_type_register_static (G_TYPE_INTERFACE, I_("GtkTreeModel"),
317 &tree_model_info, 0);
319 g_type_interface_add_prerequisite (tree_model_type, G_TYPE_OBJECT);
322 return tree_model_type;
326 gtk_tree_model_base_init (gpointer g_class)
328 static gboolean initialized = FALSE;
333 GType row_inserted_params[2];
334 GType row_deleted_params[1];
335 GType rows_reordered_params[3];
337 row_inserted_params[0] = GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE;
338 row_inserted_params[1] = GTK_TYPE_TREE_ITER;
340 row_deleted_params[0] = GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE;
342 rows_reordered_params[0] = GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE;
343 rows_reordered_params[1] = GTK_TYPE_TREE_ITER;
344 rows_reordered_params[2] = G_TYPE_POINTER;
347 * GtkTreeModel::row-changed:
348 * @tree_model: the #GtkTreeModel on which the signal is emitted
349 * @path: a #GtkTreePath identifying the changed row
350 * @iter: a valid #GtkTreeIter pointing to the changed row
352 * This signal is emitted when a row in the model has changed.
354 tree_model_signals[ROW_CHANGED] =
355 g_signal_new (I_("row-changed"),
358 G_STRUCT_OFFSET (GtkTreeModelIface, row_changed),
360 _gtk_marshal_VOID__BOXED_BOXED,
362 GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE,
365 /* We need to get notification about structure changes
366 * to update row references., so instead of using the
367 * standard g_signal_new() with an offset into our interface
368 * structure, we use a customs closures for the class
369 * closures (default handlers) that first update row references
370 * and then calls the function from the interface structure.
372 * The reason we don't simply update the row references from
373 * the wrapper functions (gtk_tree_model_row_inserted(), etc.)
374 * is to keep proper ordering with respect to signal handlers
375 * connected normally and after.
379 * GtkTreeModel::row-inserted:
380 * @tree_model: the #GtkTreeModel on which the signal is emitted
381 * @path: a #GtkTreePath identifying the new row
382 * @iter: a valid #GtkTreeIter pointing to the new row
384 * This signal is emitted when a new row has been inserted in
387 * Note that the row may still be empty at this point, since
388 * it is a common pattern to first insert an empty row, and
389 * then fill it with the desired values.
391 closure = g_closure_new_simple (sizeof (GClosure), NULL);
392 g_closure_set_marshal (closure, row_inserted_marshal);
393 tree_model_signals[ROW_INSERTED] =
394 g_signal_newv (I_("row-inserted"),
399 _gtk_marshal_VOID__BOXED_BOXED,
401 row_inserted_params);
404 * GtkTreeModel::row-has-child-toggled:
405 * @tree_model: the #GtkTreeModel on which the signal is emitted
406 * @path: a #GtkTreePath identifying the row
407 * @iter: a valid #GtkTreeIter pointing to the row
409 * This signal is emitted when a row has gotten the first child
410 * row or lost its last child row.
412 tree_model_signals[ROW_HAS_CHILD_TOGGLED] =
413 g_signal_new (I_("row-has-child-toggled"),
416 G_STRUCT_OFFSET (GtkTreeModelIface, row_has_child_toggled),
418 _gtk_marshal_VOID__BOXED_BOXED,
420 GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE,
424 * GtkTreeModel::row-deleted:
425 * @tree_model: the #GtkTreeModel on which the signal is emitted
426 * @path: a #GtkTreePath identifying the row
428 * This signal is emitted when a row has been deleted.
430 * Note that no iterator is passed to the signal handler,
431 * since the row is already deleted.
433 * This should be called by models after a row has been removed.
434 * The location pointed to by @path should be the location that
435 * the row previously was at. It may not be a valid location anymore.
437 closure = g_closure_new_simple (sizeof (GClosure), NULL);
438 g_closure_set_marshal (closure, row_deleted_marshal);
439 tree_model_signals[ROW_DELETED] =
440 g_signal_newv (I_("row-deleted"),
445 _gtk_marshal_VOID__BOXED,
450 * GtkTreeModel::rows-reordered: (skip)
451 * @tree_model: the #GtkTreeModel on which the signal is emitted
452 * @path: a #GtkTreePath identifying the tree node whose children
453 * have been reordered
454 * @iter: a valid #GtkTreeIter pointing to the node whose
455 * @new_order: an array of integers mapping the current position
456 * of each child to its old position before the re-ordering,
457 * i.e. @new_order<literal>[newpos] = oldpos</literal>
459 * This signal is emitted when the children of a node in the
460 * #GtkTreeModel have been reordered.
462 * Note that this signal is <emphasis>not</emphasis> emitted
463 * when rows are reordered by DND, since this is implemented
464 * by removing and then reinserting the row.
466 closure = g_closure_new_simple (sizeof (GClosure), NULL);
467 g_closure_set_marshal (closure, rows_reordered_marshal);
468 tree_model_signals[ROWS_REORDERED] =
469 g_signal_newv (I_("rows-reordered"),
474 _gtk_marshal_VOID__BOXED_BOXED_POINTER,
476 rows_reordered_params);
482 row_inserted_marshal (GClosure *closure,
483 GValue /* out */ *return_value,
484 guint n_param_values,
485 const GValue *param_values,
486 gpointer invocation_hint,
487 gpointer marshal_data)
489 GtkTreeModelIface *iface;
491 void (* row_inserted_callback) (GtkTreeModel *tree_model,
493 GtkTreeIter *iter) = NULL;
495 GObject *model = g_value_get_object (param_values + 0);
496 GtkTreePath *path = (GtkTreePath *)g_value_get_boxed (param_values + 1);
497 GtkTreeIter *iter = (GtkTreeIter *)g_value_get_boxed (param_values + 2);
499 /* first, we need to update internal row references */
500 gtk_tree_row_ref_inserted ((RowRefList *)g_object_get_data (model, ROW_REF_DATA_STRING),
503 /* fetch the interface ->row_inserted implementation */
504 iface = GTK_TREE_MODEL_GET_IFACE (model);
505 row_inserted_callback = G_STRUCT_MEMBER (gpointer, iface,
506 G_STRUCT_OFFSET (GtkTreeModelIface,
509 /* Call that default signal handler, it if has been set */
510 if (row_inserted_callback)
511 row_inserted_callback (GTK_TREE_MODEL (model), path, iter);
515 row_deleted_marshal (GClosure *closure,
516 GValue /* out */ *return_value,
517 guint n_param_values,
518 const GValue *param_values,
519 gpointer invocation_hint,
520 gpointer marshal_data)
522 GtkTreeModelIface *iface;
523 void (* row_deleted_callback) (GtkTreeModel *tree_model,
524 GtkTreePath *path) = NULL;
525 GObject *model = g_value_get_object (param_values + 0);
526 GtkTreePath *path = (GtkTreePath *)g_value_get_boxed (param_values + 1);
528 /* first, we need to update internal row references */
529 gtk_tree_row_ref_deleted ((RowRefList *)g_object_get_data (model, ROW_REF_DATA_STRING),
532 /* fetch the interface ->row_deleted implementation */
533 iface = GTK_TREE_MODEL_GET_IFACE (model);
534 row_deleted_callback = G_STRUCT_MEMBER (gpointer, iface,
535 G_STRUCT_OFFSET (GtkTreeModelIface,
538 /* Call that default signal handler, it if has been set */
539 if (row_deleted_callback)
540 row_deleted_callback (GTK_TREE_MODEL (model), path);
544 rows_reordered_marshal (GClosure *closure,
545 GValue /* out */ *return_value,
546 guint n_param_values,
547 const GValue *param_values,
548 gpointer invocation_hint,
549 gpointer marshal_data)
551 GtkTreeModelIface *iface;
552 void (* rows_reordered_callback) (GtkTreeModel *tree_model,
557 GObject *model = g_value_get_object (param_values + 0);
558 GtkTreePath *path = (GtkTreePath *)g_value_get_boxed (param_values + 1);
559 GtkTreeIter *iter = (GtkTreeIter *)g_value_get_boxed (param_values + 2);
560 gint *new_order = (gint *)g_value_get_pointer (param_values + 3);
562 /* first, we need to update internal row references */
563 gtk_tree_row_ref_reordered ((RowRefList *)g_object_get_data (model, ROW_REF_DATA_STRING),
564 path, iter, new_order);
566 /* fetch the interface ->rows_reordered implementation */
567 iface = GTK_TREE_MODEL_GET_IFACE (model);
568 rows_reordered_callback = G_STRUCT_MEMBER (gpointer, iface,
569 G_STRUCT_OFFSET (GtkTreeModelIface,
572 /* Call that default signal handler, it if has been set */
573 if (rows_reordered_callback)
574 rows_reordered_callback (GTK_TREE_MODEL (model), path, iter, new_order);
580 * Creates a new #GtkTreePath.
581 * This structure refers to a row.
583 * Return value: A newly created #GtkTreePath.
586 gtk_tree_path_new (void)
589 retval = g_slice_new (GtkTreePath);
592 retval->indices = NULL;
598 * gtk_tree_path_new_from_string:
599 * @path: The string representation of a path
601 * Creates a new #GtkTreePath initialized to @path.
603 * @path is expected to be a colon separated list of numbers.
604 * For example, the string "10:4:0" would create a path of depth
605 * 3 pointing to the 11th child of the root node, the 5th
606 * child of that 11th child, and the 1st child of that 5th child.
607 * If an invalid path string is passed in, %NULL is returned.
609 * Return value: A newly-created #GtkTreePath, or %NULL
612 gtk_tree_path_new_from_string (const gchar *path)
615 const gchar *orig_path = path;
619 g_return_val_if_fail (path != NULL, NULL);
620 g_return_val_if_fail (*path != '\000', NULL);
622 retval = gtk_tree_path_new ();
626 i = strtol (path, &ptr, 10);
629 g_warning (G_STRLOC ": Negative numbers in path %s passed to gtk_tree_path_new_from_string", orig_path);
630 gtk_tree_path_free (retval);
634 gtk_tree_path_append_index (retval, i);
638 if (ptr == path || *ptr != ':')
640 g_warning (G_STRLOC ": Invalid path %s passed to gtk_tree_path_new_from_string", orig_path);
641 gtk_tree_path_free (retval);
651 * gtk_tree_path_new_from_indices:
652 * @first_index: first integer
653 * @...: list of integers terminated by -1
655 * Creates a new path with @first_index and @varargs as indices.
657 * Return value: A newly created #GtkTreePath
662 gtk_tree_path_new_from_indices (gint first_index,
669 path = gtk_tree_path_new ();
671 va_start (args, first_index);
676 gtk_tree_path_append_index (path, arg);
677 arg = va_arg (args, gint);
686 * gtk_tree_path_to_string:
687 * @path: A #GtkTreePath
689 * Generates a string representation of the path.
691 * This string is a ':' separated list of numbers.
692 * For example, "4:10:0:3" would be an acceptable
693 * return value for this string.
695 * Return value: A newly-allocated string.
696 * Must be freed with g_free().
699 gtk_tree_path_to_string (GtkTreePath *path)
701 gchar *retval, *ptr, *end;
704 g_return_val_if_fail (path != NULL, NULL);
706 if (path->depth == 0)
709 n = path->depth * 12;
710 ptr = retval = g_new0 (gchar, n);
712 g_snprintf (retval, end - ptr, "%d", path->indices[0]);
713 while (*ptr != '\000')
716 for (i = 1; i < path->depth; i++)
718 g_snprintf (ptr, end - ptr, ":%d", path->indices[i]);
719 while (*ptr != '\000')
727 * gtk_tree_path_new_first:
729 * Creates a new #GtkTreePath.
731 * The string representation of this path is "0".
733 * Return value: A new #GtkTreePath
736 gtk_tree_path_new_first (void)
740 retval = gtk_tree_path_new ();
741 gtk_tree_path_append_index (retval, 0);
747 * gtk_tree_path_append_index:
748 * @path: a #GtkTreePath
751 * Appends a new index to a path.
753 * As a result, the depth of the path is increased.
756 gtk_tree_path_append_index (GtkTreePath *path,
759 g_return_if_fail (path != NULL);
760 g_return_if_fail (index_ >= 0);
762 if (path->depth == path->alloc)
765 path->alloc = MAX (path->alloc * 2, 1);
766 indices = g_new (gint, path->alloc);
767 memcpy (indices, path->indices, path->depth * sizeof (gint));
768 g_free (path->indices);
769 path->indices = indices;
773 path->indices[path->depth - 1] = index_;
777 * gtk_tree_path_prepend_index:
778 * @path: a #GtkTreePath
781 * Prepends a new index to a path.
783 * As a result, the depth of the path is increased.
786 gtk_tree_path_prepend_index (GtkTreePath *path,
789 if (path->depth == path->alloc)
792 path->alloc = MAX (path->alloc * 2, 1);
793 indices = g_new (gint, path->alloc);
794 memcpy (indices + 1, path->indices, path->depth * sizeof (gint));
795 g_free (path->indices);
796 path->indices = indices;
798 else if (path->depth > 0)
799 memmove (path->indices + 1, path->indices, path->depth * sizeof (gint));
802 path->indices[0] = index;
806 * gtk_tree_path_get_depth:
807 * @path: a #GtkTreePath
809 * Returns the current depth of @path.
811 * Return value: The depth of @path
814 gtk_tree_path_get_depth (GtkTreePath *path)
816 g_return_val_if_fail (path != NULL, 0);
822 * gtk_tree_path_get_indices: (skip)
823 * @path: a #GtkTreePath
825 * Returns the current indices of @path.
827 * This is an array of integers, each representing a node in a tree.
828 * This value should not be freed.
830 * The length of the array can be obtained with gtk_tree_path_get_depth().
832 * Return value: The current indices, or %NULL
835 gtk_tree_path_get_indices (GtkTreePath *path)
837 g_return_val_if_fail (path != NULL, NULL);
839 return path->indices;
843 * gtk_tree_path_get_indices_with_depth:
844 * @path: a #GtkTreePath
845 * @depth: (allow-none): return location for number of elements
846 * returned in the integer array, or %NULL
848 * Returns the current indices of @path.
850 * This is an array of integers, each representing a node in a tree.
851 * It also returns the number of elements in the array.
852 * The array should not be freed.
854 * Return value: (array length=depth) (transfer none): The current
859 * Rename to: gtk_tree_path_get_indices
862 gtk_tree_path_get_indices_with_depth (GtkTreePath *path,
865 g_return_val_if_fail (path != NULL, NULL);
868 *depth = path->depth;
870 return path->indices;
874 * gtk_tree_path_free:
875 * @path: (allow-none): a #GtkTreePath
877 * Frees @path. If @path is %NULL, it simply returns.
880 gtk_tree_path_free (GtkTreePath *path)
885 g_free (path->indices);
886 g_slice_free (GtkTreePath, path);
890 * gtk_tree_path_copy:
891 * @path: a #GtkTreePath
893 * Creates a new #GtkTreePath as a copy of @path.
895 * Return value: a new #GtkTreePath
898 gtk_tree_path_copy (const GtkTreePath *path)
902 g_return_val_if_fail (path != NULL, NULL);
904 retval = g_slice_new (GtkTreePath);
905 retval->depth = path->depth;
906 retval->alloc = retval->depth;
907 retval->indices = g_new (gint, path->alloc);
908 memcpy (retval->indices, path->indices, path->depth * sizeof (gint));
912 G_DEFINE_BOXED_TYPE (GtkTreePath, gtk_tree_path,
917 * gtk_tree_path_compare:
919 * @b: a #GtkTreePath to compare with
921 * Compares two paths.
923 * If @a appears before @b in a tree, then -1 is returned.
924 * If @b appears before @a, then 1 is returned.
925 * If the two nodes are equal, then 0 is returned.
927 * Return value: the relative positions of @a and @b
930 gtk_tree_path_compare (const GtkTreePath *a,
931 const GtkTreePath *b)
935 g_return_val_if_fail (a != NULL, 0);
936 g_return_val_if_fail (b != NULL, 0);
937 g_return_val_if_fail (a->depth > 0, 0);
938 g_return_val_if_fail (b->depth > 0, 0);
942 if (a->indices[p] == b->indices[q])
944 return (a->indices[p] < b->indices[q]?-1:1);
946 while (++p < a->depth && ++q < b->depth);
947 if (a->depth == b->depth)
949 return (a->depth < b->depth?-1:1);
953 * gtk_tree_path_is_ancestor:
954 * @path: a #GtkTreePath
955 * @descendant: another #GtkTreePath
957 * Returns %TRUE if @descendant is a descendant of @path.
959 * Return value: %TRUE if @descendant is contained inside @path
962 gtk_tree_path_is_ancestor (GtkTreePath *path,
963 GtkTreePath *descendant)
967 g_return_val_if_fail (path != NULL, FALSE);
968 g_return_val_if_fail (descendant != NULL, FALSE);
970 /* can't be an ancestor if we're deeper */
971 if (path->depth >= descendant->depth)
975 while (i < path->depth)
977 if (path->indices[i] != descendant->indices[i])
986 * gtk_tree_path_is_descendant:
987 * @path: a #GtkTreePath
988 * @ancestor: another #GtkTreePath
990 * Returns %TRUE if @path is a descendant of @ancestor.
992 * Return value: %TRUE if @ancestor contains @path somewhere below it
995 gtk_tree_path_is_descendant (GtkTreePath *path,
996 GtkTreePath *ancestor)
1000 g_return_val_if_fail (path != NULL, FALSE);
1001 g_return_val_if_fail (ancestor != NULL, FALSE);
1003 /* can't be a descendant if we're shallower in the tree */
1004 if (path->depth <= ancestor->depth)
1008 while (i < ancestor->depth)
1010 if (path->indices[i] != ancestor->indices[i])
1020 * gtk_tree_path_next:
1021 * @path: a #GtkTreePath
1023 * Moves the @path to point to the next node at the current depth.
1026 gtk_tree_path_next (GtkTreePath *path)
1028 g_return_if_fail (path != NULL);
1029 g_return_if_fail (path->depth > 0);
1031 path->indices[path->depth - 1] ++;
1035 * gtk_tree_path_prev:
1036 * @path: a #GtkTreePath
1038 * Moves the @path to point to the previous node at the
1039 * current depth, if it exists.
1041 * Return value: %TRUE if @path has a previous node, and
1045 gtk_tree_path_prev (GtkTreePath *path)
1047 g_return_val_if_fail (path != NULL, FALSE);
1049 if (path->depth == 0)
1052 if (path->indices[path->depth - 1] == 0)
1055 path->indices[path->depth - 1] -= 1;
1062 * @path: a #GtkTreePath
1064 * Moves the @path to point to its parent node, if it has a parent.
1066 * Return value: %TRUE if @path has a parent, and the move was made
1069 gtk_tree_path_up (GtkTreePath *path)
1071 g_return_val_if_fail (path != NULL, FALSE);
1073 if (path->depth == 0)
1082 * gtk_tree_path_down:
1083 * @path: a #GtkTreePath
1085 * Moves @path to point to the first child of the current path.
1088 gtk_tree_path_down (GtkTreePath *path)
1090 g_return_if_fail (path != NULL);
1092 gtk_tree_path_append_index (path, 0);
1096 * gtk_tree_iter_copy:
1097 * @iter: a #GtkTreeIter
1099 * Creates a dynamically allocated tree iterator as a copy of @iter.
1101 * This function is not intended for use in applications,
1102 * because you can just copy the structs by value
1103 * (<literal>GtkTreeIter new_iter = iter;</literal>).
1104 * You must free this iter with gtk_tree_iter_free().
1106 * Return value: a newly-allocated copy of @iter
1109 gtk_tree_iter_copy (GtkTreeIter *iter)
1111 GtkTreeIter *retval;
1113 g_return_val_if_fail (iter != NULL, NULL);
1115 retval = g_slice_new (GtkTreeIter);
1122 * gtk_tree_iter_free:
1123 * @iter: a dynamically allocated tree iterator
1125 * Frees an iterator that has been allocated by gtk_tree_iter_copy().
1127 * This function is mainly used for language bindings.
1130 gtk_tree_iter_free (GtkTreeIter *iter)
1132 g_return_if_fail (iter != NULL);
1134 g_slice_free (GtkTreeIter, iter);
1137 G_DEFINE_BOXED_TYPE (GtkTreeIter, gtk_tree_iter,
1142 * gtk_tree_model_get_flags:
1143 * @tree_model: a #GtkTreeModel
1145 * Returns a set of flags supported by this interface.
1147 * The flags are a bitwise combination of #GtkTreeModelFlags.
1148 * The flags supported should not change during the lifetime
1149 * of the @tree_model.
1151 * Return value: the flags supported by this interface
1154 gtk_tree_model_get_flags (GtkTreeModel *tree_model)
1156 GtkTreeModelIface *iface;
1158 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), 0);
1160 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1161 if (iface->get_flags)
1162 return (* iface->get_flags) (tree_model);
1168 * gtk_tree_model_get_n_columns:
1169 * @tree_model: a #GtkTreeModel
1171 * Returns the number of columns supported by @tree_model.
1173 * Return value: the number of columns
1176 gtk_tree_model_get_n_columns (GtkTreeModel *tree_model)
1178 GtkTreeModelIface *iface;
1179 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), 0);
1181 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1182 g_return_val_if_fail (iface->get_n_columns != NULL, 0);
1184 return (* iface->get_n_columns) (tree_model);
1188 * gtk_tree_model_get_column_type:
1189 * @tree_model: a #GtkTreeModel
1190 * @index_: the column index
1192 * Returns the type of the column.
1194 * Return value: (transfer none): the type of the column
1197 gtk_tree_model_get_column_type (GtkTreeModel *tree_model,
1200 GtkTreeModelIface *iface;
1202 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), G_TYPE_INVALID);
1204 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1205 g_return_val_if_fail (iface->get_column_type != NULL, G_TYPE_INVALID);
1206 g_return_val_if_fail (index >= 0, G_TYPE_INVALID);
1208 return (* iface->get_column_type) (tree_model, index);
1212 * gtk_tree_model_get_iter:
1213 * @tree_model: a #GtkTreeModel
1214 * @iter: (out): the uninitialized #GtkTreeIter
1215 * @path: the #GtkTreePath
1217 * Sets @iter to a valid iterator pointing to @path. If @path does
1218 * not exist, @iter is set to an invalid iterator and %FALSE is returned.
1220 * Return value: %TRUE, if @iter was set
1223 gtk_tree_model_get_iter (GtkTreeModel *tree_model,
1227 GtkTreeModelIface *iface;
1229 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1230 g_return_val_if_fail (iter != NULL, FALSE);
1231 g_return_val_if_fail (path != NULL, FALSE);
1233 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1234 g_return_val_if_fail (iface->get_iter != NULL, FALSE);
1235 g_return_val_if_fail (path->depth > 0, FALSE);
1237 INITIALIZE_TREE_ITER (iter);
1239 return (* iface->get_iter) (tree_model, iter, path);
1243 * gtk_tree_model_get_iter_from_string:
1244 * @tree_model: a #GtkTreeModel
1245 * @iter: (out): an uninitialized #GtkTreeIter
1246 * @path_string: a string representation of a #GtkTreePath
1248 * Sets @iter to a valid iterator pointing to @path_string, if it
1249 * exists. Otherwise, @iter is left invalid and %FALSE is returned.
1251 * Return value: %TRUE, if @iter was set
1254 gtk_tree_model_get_iter_from_string (GtkTreeModel *tree_model,
1256 const gchar *path_string)
1261 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1262 g_return_val_if_fail (iter != NULL, FALSE);
1263 g_return_val_if_fail (path_string != NULL, FALSE);
1265 path = gtk_tree_path_new_from_string (path_string);
1267 g_return_val_if_fail (path != NULL, FALSE);
1269 retval = gtk_tree_model_get_iter (tree_model, iter, path);
1270 gtk_tree_path_free (path);
1276 * gtk_tree_model_get_string_from_iter:
1277 * @tree_model: a #GtkTreeModel
1278 * @iter: a #GtkTreeIter
1280 * Generates a string representation of the iter.
1282 * This string is a ':' separated list of numbers.
1283 * For example, "4:10:0:3" would be an acceptable
1284 * return value for this string.
1286 * Return value: a newly-allocated string.
1287 * Must be freed with g_free().
1292 gtk_tree_model_get_string_from_iter (GtkTreeModel *tree_model,
1298 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), NULL);
1299 g_return_val_if_fail (iter != NULL, NULL);
1301 path = gtk_tree_model_get_path (tree_model, iter);
1303 g_return_val_if_fail (path != NULL, NULL);
1305 ret = gtk_tree_path_to_string (path);
1306 gtk_tree_path_free (path);
1312 * gtk_tree_model_get_iter_first:
1313 * @tree_model: a #GtkTreeModel
1314 * @iter: (out): the uninitialized #GtkTreeIter
1316 * Initializes @iter with the first iterator in the tree
1317 * (the one at the path "0") and returns %TRUE. Returns
1318 * %FALSE if the tree is empty.
1320 * Return value: %TRUE, if @iter was set
1323 gtk_tree_model_get_iter_first (GtkTreeModel *tree_model,
1329 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1330 g_return_val_if_fail (iter != NULL, FALSE);
1332 path = gtk_tree_path_new_first ();
1333 retval = gtk_tree_model_get_iter (tree_model, iter, path);
1334 gtk_tree_path_free (path);
1340 * gtk_tree_model_get_path:
1341 * @tree_model: a #GtkTreeModel
1342 * @iter: the #GtkTreeIter
1344 * Returns a newly-created #GtkTreePath referenced by @iter.
1346 * This path should be freed with gtk_tree_path_free().
1348 * Return value: a newly-created #GtkTreePath
1351 gtk_tree_model_get_path (GtkTreeModel *tree_model,
1354 GtkTreeModelIface *iface;
1356 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), NULL);
1357 g_return_val_if_fail (iter != NULL, NULL);
1359 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1360 g_return_val_if_fail (iface->get_path != NULL, NULL);
1362 return (* iface->get_path) (tree_model, iter);
1366 * gtk_tree_model_get_value:
1367 * @tree_model: a #GtkTreeModel
1368 * @iter: the #GtkTreeIter
1369 * @column: the column to lookup the value at
1370 * @value: (out) (transfer none): an empty #GValue to set
1372 * Initializes and sets @value to that at @column.
1374 * When done with @value, g_value_unset() needs to be called
1375 * to free any allocated memory.
1378 gtk_tree_model_get_value (GtkTreeModel *tree_model,
1383 GtkTreeModelIface *iface;
1385 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1386 g_return_if_fail (iter != NULL);
1387 g_return_if_fail (value != NULL);
1389 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1390 g_return_if_fail (iface->get_value != NULL);
1392 (* iface->get_value) (tree_model, iter, column, value);
1396 * gtk_tree_model_iter_next:
1397 * @tree_model: a #GtkTreeModel
1398 * @iter: (in): the #GtkTreeIter
1400 * Sets @iter to point to the node following it at the current level.
1402 * If there is no next @iter, %FALSE is returned and @iter is set
1405 * Return value: %TRUE if @iter has been changed to the next node
1408 gtk_tree_model_iter_next (GtkTreeModel *tree_model,
1411 GtkTreeModelIface *iface;
1413 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1414 g_return_val_if_fail (iter != NULL, FALSE);
1416 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1417 g_return_val_if_fail (iface->iter_next != NULL, FALSE);
1419 return (* iface->iter_next) (tree_model, iter);
1423 gtk_tree_model_iter_previous_default (GtkTreeModel *tree_model,
1429 path = gtk_tree_model_get_path (tree_model, iter);
1433 retval = gtk_tree_path_prev (path) &&
1434 gtk_tree_model_get_iter (tree_model, iter, path);
1435 if (retval == FALSE)
1438 gtk_tree_path_free (path);
1444 * gtk_tree_model_iter_previous:
1445 * @tree_model: a #GtkTreeModel
1446 * @iter: (in): the #GtkTreeIter
1448 * Sets @iter to point to the previous node at the current level.
1450 * If there is no previous @iter, %FALSE is returned and @iter is
1451 * set to be invalid.
1453 * Return value: %TRUE if @iter has been changed to the previous node
1458 gtk_tree_model_iter_previous (GtkTreeModel *tree_model,
1462 GtkTreeModelIface *iface;
1464 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1465 g_return_val_if_fail (iter != NULL, FALSE);
1467 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1469 if (iface->iter_previous)
1470 retval = (* iface->iter_previous) (tree_model, iter);
1472 retval = gtk_tree_model_iter_previous_default (tree_model, iter);
1478 * gtk_tree_model_iter_children:
1479 * @tree_model: a #GtkTreeModel
1480 * @iter: (out): the new #GtkTreeIter to be set to the child
1481 * @parent: (allow-none): the #GtkTreeIter, or %NULL
1483 * Sets @iter to point to the first child of @parent.
1485 * If @parent has no children, %FALSE is returned and @iter is
1486 * set to be invalid. @parent will remain a valid node after this
1487 * function has been called.
1489 * If @parent is %NULL returns the first node, equivalent to
1490 * <literal>gtk_tree_model_get_iter_first (tree_model, iter);</literal>
1492 * Return value: %TRUE, if @child has been set to the first child
1495 gtk_tree_model_iter_children (GtkTreeModel *tree_model,
1497 GtkTreeIter *parent)
1499 GtkTreeModelIface *iface;
1501 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1502 g_return_val_if_fail (iter != NULL, FALSE);
1504 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1505 g_return_val_if_fail (iface->iter_children != NULL, FALSE);
1507 INITIALIZE_TREE_ITER (iter);
1509 return (* iface->iter_children) (tree_model, iter, parent);
1513 * gtk_tree_model_iter_has_child:
1514 * @tree_model: a #GtkTreeModel
1515 * @iter: the #GtkTreeIter to test for children
1517 * Returns %TRUE if @iter has children, %FALSE otherwise.
1519 * Return value: %TRUE if @iter has children
1522 gtk_tree_model_iter_has_child (GtkTreeModel *tree_model,
1525 GtkTreeModelIface *iface;
1527 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1528 g_return_val_if_fail (iter != NULL, FALSE);
1530 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1531 g_return_val_if_fail (iface->iter_has_child != NULL, FALSE);
1533 return (* iface->iter_has_child) (tree_model, iter);
1537 * gtk_tree_model_iter_n_children:
1538 * @tree_model: a #GtkTreeModel
1539 * @iter: (allow-none): the #GtkTreeIter, or %NULL
1541 * Returns the number of children that @iter has.
1543 * As a special case, if @iter is %NULL, then the number
1544 * of toplevel nodes is returned.
1546 * Return value: the number of children of @iter
1549 gtk_tree_model_iter_n_children (GtkTreeModel *tree_model,
1552 GtkTreeModelIface *iface;
1554 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), 0);
1556 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1557 g_return_val_if_fail (iface->iter_n_children != NULL, 0);
1559 return (* iface->iter_n_children) (tree_model, iter);
1563 * gtk_tree_model_iter_nth_child:
1564 * @tree_model: a #GtkTreeModel
1565 * @iter: (out): the #GtkTreeIter to set to the nth child
1566 * @parent: (allow-none): the #GtkTreeIter to get the child from, or %NULL.
1567 * @n: the index of the desired child
1569 * Sets @iter to be the child of @parent, using the given index.
1571 * The first index is 0. If @n is too big, or @parent has no children,
1572 * @iter is set to an invalid iterator and %FALSE is returned. @parent
1573 * will remain a valid node after this function has been called. As a
1574 * special case, if @parent is %NULL, then the @n<!-- -->th root node
1577 * Return value: %TRUE, if @parent has an @n<!-- -->th child
1580 gtk_tree_model_iter_nth_child (GtkTreeModel *tree_model,
1582 GtkTreeIter *parent,
1585 GtkTreeModelIface *iface;
1587 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1588 g_return_val_if_fail (iter != NULL, FALSE);
1589 g_return_val_if_fail (n >= 0, FALSE);
1591 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1592 g_return_val_if_fail (iface->iter_nth_child != NULL, FALSE);
1594 INITIALIZE_TREE_ITER (iter);
1596 return (* iface->iter_nth_child) (tree_model, iter, parent, n);
1600 * gtk_tree_model_iter_parent:
1601 * @tree_model: a #GtkTreeModel
1602 * @iter: (out): the new #GtkTreeIter to set to the parent
1603 * @child: the #GtkTreeIter
1605 * Sets @iter to be the parent of @child.
1607 * If @child is at the toplevel, and doesn't have a parent, then
1608 * @iter is set to an invalid iterator and %FALSE is returned.
1609 * @child will remain a valid node after this function has been
1612 * Return value: %TRUE, if @iter is set to the parent of @child
1615 gtk_tree_model_iter_parent (GtkTreeModel *tree_model,
1619 GtkTreeModelIface *iface;
1621 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1622 g_return_val_if_fail (iter != NULL, FALSE);
1623 g_return_val_if_fail (child != NULL, FALSE);
1625 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1626 g_return_val_if_fail (iface->iter_parent != NULL, FALSE);
1628 INITIALIZE_TREE_ITER (iter);
1630 return (* iface->iter_parent) (tree_model, iter, child);
1634 * gtk_tree_model_ref_node:
1635 * @tree_model: a #GtkTreeModel
1636 * @iter: the #GtkTreeIter
1638 * Lets the tree ref the node.
1640 * This is an optional method for models to implement.
1641 * To be more specific, models may ignore this call as it exists
1642 * primarily for performance reasons.
1644 * This function is primarily meant as a way for views to let
1645 * caching models know when nodes are being displayed (and hence,
1646 * whether or not to cache that node). Being displayed means a node
1647 * is in an expanded branch, regardless of whether the node is currently
1648 * visible in the viewport. For example, a file-system based model
1649 * would not want to keep the entire file-hierarchy in memory,
1650 * just the sections that are currently being displayed by
1651 * every current view.
1653 * A model should be expected to be able to get an iter independent
1654 * of its reffed state.
1657 gtk_tree_model_ref_node (GtkTreeModel *tree_model,
1660 GtkTreeModelIface *iface;
1662 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1664 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1665 if (iface->ref_node)
1666 (* iface->ref_node) (tree_model, iter);
1670 * gtk_tree_model_unref_node:
1671 * @tree_model: a #GtkTreeModel
1672 * @iter: the #GtkTreeIter
1674 * Lets the tree unref the node.
1676 * This is an optional method for models to implement.
1677 * To be more specific, models may ignore this call as it exists
1678 * primarily for performance reasons. For more information on what
1679 * this means, see gtk_tree_model_ref_node().
1681 * Please note that nodes that are deleted are not unreffed.
1684 gtk_tree_model_unref_node (GtkTreeModel *tree_model,
1687 GtkTreeModelIface *iface;
1689 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1690 g_return_if_fail (iter != NULL);
1692 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1693 if (iface->unref_node)
1694 (* iface->unref_node) (tree_model, iter);
1698 * gtk_tree_model_get:
1699 * @tree_model: a #GtkTreeModel
1700 * @iter: a row in @tree_model
1701 * @...: pairs of column number and value return locations,
1704 * Gets the value of one or more cells in the row referenced by @iter.
1705 * The variable argument list should contain integer column numbers,
1706 * each column number followed by a place to store the value being
1707 * retrieved. The list is terminated by a -1. For example, to get a
1708 * value from column 0 with type %G_TYPE_STRING, you would
1709 * write: <literal>gtk_tree_model_get (model, iter, 0, &place_string_here, -1)</literal>,
1710 * where <literal>place_string_here</literal> is a <type>gchar*</type>
1711 * to be filled with the string.
1713 * Returned values with type %G_TYPE_OBJECT have to be unreferenced,
1714 * values with type %G_TYPE_STRING or %G_TYPE_BOXED have to be freed.
1715 * Other values are passed by value.
1718 gtk_tree_model_get (GtkTreeModel *tree_model,
1724 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1725 g_return_if_fail (iter != NULL);
1727 va_start (var_args, iter);
1728 gtk_tree_model_get_valist (tree_model, iter, var_args);
1733 * gtk_tree_model_get_valist:
1734 * @tree_model: a #GtkTreeModel
1735 * @iter: a row in @tree_model
1736 * @var_args: <type>va_list</type> of column/return location pairs
1738 * See gtk_tree_model_get(), this version takes a <type>va_list</type>
1739 * for language bindings to use.
1742 gtk_tree_model_get_valist (GtkTreeModel *tree_model,
1748 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1749 g_return_if_fail (iter != NULL);
1751 column = va_arg (var_args, gint);
1753 while (column != -1)
1755 GValue value = G_VALUE_INIT;
1756 gchar *error = NULL;
1758 if (column >= gtk_tree_model_get_n_columns (tree_model))
1760 g_warning ("%s: Invalid column number %d accessed (remember to end your list of columns with a -1)", G_STRLOC, column);
1764 gtk_tree_model_get_value (GTK_TREE_MODEL (tree_model), iter, column, &value);
1766 G_VALUE_LCOPY (&value, var_args, 0, &error);
1769 g_warning ("%s: %s", G_STRLOC, error);
1772 /* we purposely leak the value here, it might not be
1773 * in a sane state if an error condition occurred
1778 g_value_unset (&value);
1780 column = va_arg (var_args, gint);
1785 * gtk_tree_model_row_changed:
1786 * @tree_model: a #GtkTreeModel
1787 * @path: a #GtkTreePath pointing to the changed row
1788 * @iter: a valid #GtkTreeIter pointing to the changed row
1790 * Emits the #GtkTreeModel::row-changed signal on @tree_model.
1793 gtk_tree_model_row_changed (GtkTreeModel *tree_model,
1797 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1798 g_return_if_fail (path != NULL);
1799 g_return_if_fail (iter != NULL);
1801 g_signal_emit (tree_model, tree_model_signals[ROW_CHANGED], 0, path, iter);
1805 * gtk_tree_model_row_inserted:
1806 * @tree_model: a #GtkTreeModel
1807 * @path: a #GtkTreePath pointing to the inserted row
1808 * @iter: a valid #GtkTreeIter pointing to the inserted row
1810 * Emits the #GtkTreeModel::row-inserted signal on @tree_model.
1813 gtk_tree_model_row_inserted (GtkTreeModel *tree_model,
1817 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1818 g_return_if_fail (path != NULL);
1819 g_return_if_fail (iter != NULL);
1821 g_signal_emit (tree_model, tree_model_signals[ROW_INSERTED], 0, path, iter);
1825 * gtk_tree_model_row_has_child_toggled:
1826 * @tree_model: a #GtkTreeModel
1827 * @path: a #GtkTreePath pointing to the changed row
1828 * @iter: a valid #GtkTreeIter pointing to the changed row
1830 * Emits the #GtkTreeModel::row-has-child-toggled signal on
1831 * @tree_model. This should be called by models after the child
1832 * state of a node changes.
1835 gtk_tree_model_row_has_child_toggled (GtkTreeModel *tree_model,
1839 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1840 g_return_if_fail (path != NULL);
1841 g_return_if_fail (iter != NULL);
1843 g_signal_emit (tree_model, tree_model_signals[ROW_HAS_CHILD_TOGGLED], 0, path, iter);
1847 * gtk_tree_model_row_deleted:
1848 * @tree_model: a #GtkTreeModel
1849 * @path: a #GtkTreePath pointing to the previous location of
1852 * Emits the #GtkTreeModel::row-deleted signal on @tree_model.
1854 * This should be called by models after a row has been removed.
1855 * The location pointed to by @path should be the location that
1856 * the row previously was at. It may not be a valid location anymore.
1858 * Nodes that are deleted are not unreffed, this means that any
1859 * outstanding references on the deleted node should not be released.
1862 gtk_tree_model_row_deleted (GtkTreeModel *tree_model,
1865 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1866 g_return_if_fail (path != NULL);
1868 g_signal_emit (tree_model, tree_model_signals[ROW_DELETED], 0, path);
1872 * gtk_tree_model_rows_reordered: (skip)
1873 * @tree_model: a #GtkTreeModel
1874 * @path: a #GtkTreePath pointing to the tree node whose children
1875 * have been reordered
1876 * @iter: a valid #GtkTreeIter pointing to the node whose children
1877 * have been reordered, or %NULL if the depth of @path is 0
1878 * @new_order: an array of integers mapping the current position of
1879 * each child to its old position before the re-ordering,
1880 * i.e. @new_order<literal>[newpos] = oldpos</literal>
1882 * Emits the #GtkTreeModel::rows-reordered signal on @tree_model.
1884 * This should be called by models when their rows have been
1888 gtk_tree_model_rows_reordered (GtkTreeModel *tree_model,
1893 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1894 g_return_if_fail (new_order != NULL);
1896 g_signal_emit (tree_model, tree_model_signals[ROWS_REORDERED], 0, path, iter, new_order);
1901 gtk_tree_model_foreach_helper (GtkTreeModel *model,
1904 GtkTreeModelForeachFunc func,
1911 if ((* func) (model, path, iter, user_data))
1914 if (gtk_tree_model_iter_children (model, &child, iter))
1916 gtk_tree_path_down (path);
1917 if (gtk_tree_model_foreach_helper (model, &child, path, func, user_data))
1919 gtk_tree_path_up (path);
1922 gtk_tree_path_next (path);
1924 while (gtk_tree_model_iter_next (model, iter));
1930 * gtk_tree_model_foreach:
1931 * @model: a #GtkTreeModel
1932 * @func: (scope call): a function to be called on each row
1933 * @user_data: user data to passed to @func
1935 * Calls func on each node in model in a depth-first fashion.
1937 * If @func returns %TRUE, then the tree ceases to be walked,
1938 * and gtk_tree_model_foreach() returns.
1941 gtk_tree_model_foreach (GtkTreeModel *model,
1942 GtkTreeModelForeachFunc func,
1948 g_return_if_fail (GTK_IS_TREE_MODEL (model));
1949 g_return_if_fail (func != NULL);
1951 path = gtk_tree_path_new_first ();
1952 if (gtk_tree_model_get_iter (model, &iter, path) == FALSE)
1954 gtk_tree_path_free (path);
1958 gtk_tree_model_foreach_helper (model, &iter, path, func, user_data);
1959 gtk_tree_path_free (path);
1964 * GtkTreeRowReference
1967 static void gtk_tree_row_reference_unref_path (GtkTreePath *path,
1968 GtkTreeModel *model,
1972 G_DEFINE_BOXED_TYPE (GtkTreeRowReference, gtk_tree_row_reference,
1973 gtk_tree_row_reference_copy,
1974 gtk_tree_row_reference_free)
1976 struct _GtkTreeRowReference
1979 GtkTreeModel *model;
1985 release_row_references (gpointer data)
1987 RowRefList *refs = data;
1988 GSList *tmp_list = NULL;
1990 tmp_list = refs->list;
1991 while (tmp_list != NULL)
1993 GtkTreeRowReference *reference = tmp_list->data;
1995 if (reference->proxy == (GObject *)reference->model)
1996 reference->model = NULL;
1997 reference->proxy = NULL;
1999 /* we don't free the reference, users are responsible for that. */
2001 tmp_list = g_slist_next (tmp_list);
2004 g_slist_free (refs->list);
2009 gtk_tree_row_ref_inserted (RowRefList *refs,
2018 /* This function corrects the path stored in the reference to
2019 * account for an insertion. Note that it's called _after_ the
2020 * insertion with the path to the newly-inserted row. Which means
2021 * that the inserted path is in a different "coordinate system" than
2022 * the old path (e.g. if the inserted path was just before the old
2023 * path, then inserted path and old path will be the same, and old
2024 * path must be moved down one).
2027 tmp_list = refs->list;
2029 while (tmp_list != NULL)
2031 GtkTreeRowReference *reference = tmp_list->data;
2033 if (reference->path == NULL)
2036 if (reference->path->depth >= path->depth)
2039 gboolean ancestor = TRUE;
2041 for (i = 0; i < path->depth - 1; i ++)
2043 if (path->indices[i] != reference->path->indices[i])
2049 if (ancestor == FALSE)
2052 if (path->indices[path->depth-1] <= reference->path->indices[path->depth-1])
2053 reference->path->indices[path->depth-1] += 1;
2056 tmp_list = g_slist_next (tmp_list);
2061 gtk_tree_row_ref_deleted (RowRefList *refs,
2069 /* This function corrects the path stored in the reference to
2070 * account for an deletion. Note that it's called _after_ the
2071 * deletion with the old path of the just-deleted row. Which means
2072 * that the deleted path is the same now-defunct "coordinate system"
2073 * as the path saved in the reference, which is what we want to fix.
2076 tmp_list = refs->list;
2078 while (tmp_list != NULL)
2080 GtkTreeRowReference *reference = tmp_list->data;
2082 if (reference->path)
2086 if (path->depth > reference->path->depth)
2088 for (i = 0; i < path->depth - 1; i++)
2090 if (path->indices[i] != reference->path->indices[i])
2094 /* We know it affects us. */
2095 if (path->indices[i] == reference->path->indices[i])
2097 if (reference->path->depth > path->depth)
2098 /* some parent was deleted, trying to unref any node
2099 * between the deleted parent and the node the reference
2100 * is pointing to is bad, as those nodes are already gone.
2102 gtk_tree_row_reference_unref_path (reference->path, reference->model, path->depth - 1);
2104 gtk_tree_row_reference_unref_path (reference->path, reference->model, reference->path->depth - 1);
2105 gtk_tree_path_free (reference->path);
2106 reference->path = NULL;
2108 else if (path->indices[i] < reference->path->indices[i])
2110 reference->path->indices[path->depth-1]-=1;
2115 tmp_list = g_slist_next (tmp_list);
2120 gtk_tree_row_ref_reordered (RowRefList *refs,
2131 tmp_list = refs->list;
2133 while (tmp_list != NULL)
2135 GtkTreeRowReference *reference = tmp_list->data;
2137 length = gtk_tree_model_iter_n_children (GTK_TREE_MODEL (reference->model), iter);
2142 if ((reference->path) &&
2143 (gtk_tree_path_is_ancestor (path, reference->path)))
2145 gint ref_depth = gtk_tree_path_get_depth (reference->path);
2146 gint depth = gtk_tree_path_get_depth (path);
2148 if (ref_depth > depth)
2151 gint *indices = gtk_tree_path_get_indices (reference->path);
2153 for (i = 0; i < length; i++)
2155 if (new_order[i] == indices[depth])
2164 tmp_list = g_slist_next (tmp_list);
2168 /* We do this recursively so that we can unref children nodes
2169 * before their parent
2172 gtk_tree_row_reference_unref_path_helper (GtkTreePath *path,
2173 GtkTreeModel *model,
2174 GtkTreeIter *parent_iter,
2180 if (depth == current_depth)
2183 gtk_tree_model_iter_nth_child (model, &iter, parent_iter, path->indices[current_depth]);
2184 gtk_tree_row_reference_unref_path_helper (path, model, &iter, depth, current_depth + 1);
2185 gtk_tree_model_unref_node (model, &iter);
2189 gtk_tree_row_reference_unref_path (GtkTreePath *path,
2190 GtkTreeModel *model,
2198 gtk_tree_model_iter_nth_child (model, &iter, NULL, path->indices[0]);
2199 gtk_tree_row_reference_unref_path_helper (path, model, &iter, depth, 1);
2200 gtk_tree_model_unref_node (model, &iter);
2204 * gtk_tree_row_reference_new:
2205 * @model: a #GtkTreeModel
2206 * @path: a valid #GtkTreePath to monitor
2208 * Creates a row reference based on @path.
2210 * This reference will keep pointing to the node pointed to
2211 * by @path, so long as it exists. It listens to all signals
2212 * emitted by @model, and updates its path appropriately. If
2213 * @path isn't a valid path in @model, then %NULL is returned.
2215 * Return value: a newly allocated #GtkTreeRowReference, or %NULL
2217 GtkTreeRowReference *
2218 gtk_tree_row_reference_new (GtkTreeModel *model,
2221 g_return_val_if_fail (GTK_IS_TREE_MODEL (model), NULL);
2222 g_return_val_if_fail (path != NULL, NULL);
2224 /* We use the model itself as the proxy object; and call
2225 * gtk_tree_row_reference_inserted(), etc, in the
2226 * class closure (default handler) marshalers for the signal.
2228 return gtk_tree_row_reference_new_proxy (G_OBJECT (model), model, path);
2232 * gtk_tree_row_reference_new_proxy:
2233 * @proxy: a proxy #GObject
2234 * @model: a #GtkTreeModel
2235 * @path: a valid #GtkTreePath to monitor
2237 * You do not need to use this function.
2239 * Creates a row reference based on @path.
2241 * This reference will keep pointing to the node pointed to
2242 * by @path, so long as it exists. If @path isn't a valid
2243 * path in @model, then %NULL is returned. However, unlike
2244 * references created with gtk_tree_row_reference_new(), it
2245 * does not listen to the model for changes. The creator of
2246 * the row reference must do this explicitly using
2247 * gtk_tree_row_reference_inserted(), gtk_tree_row_reference_deleted(),
2248 * gtk_tree_row_reference_reordered().
2250 * These functions must be called exactly once per proxy when the
2251 * corresponding signal on the model is emitted. This single call
2252 * updates all row references for that proxy. Since built-in GTK+
2253 * objects like #GtkTreeView already use this mechanism internally,
2254 * using them as the proxy object will produce unpredictable results.
2255 * Further more, passing the same object as @model and @proxy
2256 * doesn't work for reasons of internal implementation.
2258 * This type of row reference is primarily meant by structures that
2259 * need to carefully monitor exactly when a row reference updates
2260 * itself, and is not generally needed by most applications.
2262 * Return value: a newly allocated #GtkTreeRowReference, or %NULL
2264 GtkTreeRowReference *
2265 gtk_tree_row_reference_new_proxy (GObject *proxy,
2266 GtkTreeModel *model,
2269 GtkTreeRowReference *reference;
2271 GtkTreeIter parent_iter;
2274 g_return_val_if_fail (G_IS_OBJECT (proxy), NULL);
2275 g_return_val_if_fail (GTK_IS_TREE_MODEL (model), NULL);
2276 g_return_val_if_fail (path != NULL, NULL);
2277 g_return_val_if_fail (path->depth > 0, NULL);
2279 /* check that the path is valid */
2280 if (gtk_tree_model_get_iter (model, &parent_iter, path) == FALSE)
2283 /* Now we want to ref every node */
2284 gtk_tree_model_iter_nth_child (model, &parent_iter, NULL, path->indices[0]);
2285 gtk_tree_model_ref_node (model, &parent_iter);
2287 for (i = 1; i < path->depth; i++)
2290 gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, path->indices[i]);
2291 gtk_tree_model_ref_node (model, &iter);
2295 /* Make the row reference */
2296 reference = g_new (GtkTreeRowReference, 1);
2298 g_object_ref (proxy);
2299 g_object_ref (model);
2300 reference->proxy = proxy;
2301 reference->model = model;
2302 reference->path = gtk_tree_path_copy (path);
2304 refs = g_object_get_data (G_OBJECT (proxy), ROW_REF_DATA_STRING);
2308 refs = g_new (RowRefList, 1);
2311 g_object_set_data_full (G_OBJECT (proxy),
2312 I_(ROW_REF_DATA_STRING),
2313 refs, release_row_references);
2316 refs->list = g_slist_prepend (refs->list, reference);
2322 * gtk_tree_row_reference_get_path:
2323 * @reference: a #GtkTreeRowReference
2325 * Returns a path that the row reference currently points to,
2326 * or %NULL if the path pointed to is no longer valid.
2328 * Return value: a current path, or %NULL
2331 gtk_tree_row_reference_get_path (GtkTreeRowReference *reference)
2333 g_return_val_if_fail (reference != NULL, NULL);
2335 if (reference->proxy == NULL)
2338 if (reference->path == NULL)
2341 return gtk_tree_path_copy (reference->path);
2345 * gtk_tree_row_reference_get_model:
2346 * @reference: a #GtkTreeRowReference
2348 * Returns the model that the row reference is monitoring.
2350 * Return value: (transfer none): the model
2355 gtk_tree_row_reference_get_model (GtkTreeRowReference *reference)
2357 g_return_val_if_fail (reference != NULL, NULL);
2359 return reference->model;
2363 * gtk_tree_row_reference_valid:
2364 * @reference: (allow-none): a #GtkTreeRowReference, or %NULL
2366 * Returns %TRUE if the @reference is non-%NULL and refers to
2367 * a current valid path.
2369 * Return value: %TRUE if @reference points to a valid path
2372 gtk_tree_row_reference_valid (GtkTreeRowReference *reference)
2374 if (reference == NULL || reference->path == NULL)
2382 * gtk_tree_row_reference_copy:
2383 * @reference: a #GtkTreeRowReference
2385 * Copies a #GtkTreeRowReference.
2387 * Return value: a copy of @reference
2391 GtkTreeRowReference *
2392 gtk_tree_row_reference_copy (GtkTreeRowReference *reference)
2394 return gtk_tree_row_reference_new_proxy (reference->proxy,
2400 * gtk_tree_row_reference_free:
2401 * @reference: (allow-none): a #GtkTreeRowReference, or %NULL
2403 * Free's @reference. @reference may be %NULL
2406 gtk_tree_row_reference_free (GtkTreeRowReference *reference)
2410 if (reference == NULL)
2413 refs = g_object_get_data (G_OBJECT (reference->proxy), ROW_REF_DATA_STRING);
2417 g_warning (G_STRLOC": bad row reference, proxy has no outstanding row references");
2421 refs->list = g_slist_remove (refs->list, reference);
2423 if (refs->list == NULL)
2425 g_object_set_data (G_OBJECT (reference->proxy),
2426 I_(ROW_REF_DATA_STRING),
2430 if (reference->path)
2432 gtk_tree_row_reference_unref_path (reference->path, reference->model, reference->path->depth);
2433 gtk_tree_path_free (reference->path);
2436 g_object_unref (reference->proxy);
2437 g_object_unref (reference->model);
2442 * gtk_tree_row_reference_inserted:
2443 * @proxy: a #GObject
2444 * @path: the row position that was inserted
2446 * Lets a set of row reference created by
2447 * gtk_tree_row_reference_new_proxy() know that the
2448 * model emitted the #GtkTreeModel::row-inserted signal.
2451 gtk_tree_row_reference_inserted (GObject *proxy,
2454 g_return_if_fail (G_IS_OBJECT (proxy));
2456 gtk_tree_row_ref_inserted ((RowRefList *)g_object_get_data (proxy, ROW_REF_DATA_STRING), path, NULL);
2460 * gtk_tree_row_reference_deleted:
2461 * @proxy: a #GObject
2462 * @path: the path position that was deleted
2464 * Lets a set of row reference created by
2465 * gtk_tree_row_reference_new_proxy() know that the
2466 * model emitted the #GtkTreeModel::row-deleted signal.
2469 gtk_tree_row_reference_deleted (GObject *proxy,
2472 g_return_if_fail (G_IS_OBJECT (proxy));
2474 gtk_tree_row_ref_deleted ((RowRefList *)g_object_get_data (proxy, ROW_REF_DATA_STRING), path);
2478 * gtk_tree_row_reference_reordered: (skip)
2479 * @proxy: a #GObject
2480 * @path: the parent path of the reordered signal
2481 * @iter: the iter pointing to the parent of the reordered
2482 * @new_order: the new order of rows
2484 * Lets a set of row reference created by
2485 * gtk_tree_row_reference_new_proxy() know that the
2486 * model emitted the #GtkTreeModel::rows-reordered signal.
2489 gtk_tree_row_reference_reordered (GObject *proxy,
2494 g_return_if_fail (G_IS_OBJECT (proxy));
2496 gtk_tree_row_ref_reordered ((RowRefList *)g_object_get_data (proxy, ROW_REF_DATA_STRING), path, iter, new_order);