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, check it is valid and walk
172 * * through the list, reading each row. */
173 * for (valid = gtk_tree_model_get_iter_first (list_store, &iter);
175 * valid = gtk_tree_model_iter_next (list_store, &iter))
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);
197 * The #GtkTreeModel interface contains two methods for reference
198 * counting: gtk_tree_model_ref_node() and gtk_tree_model_unref_node().
199 * These two methods are optional to implement. The reference counting
200 * is meant as a way for views to let models know when nodes are being
201 * displayed. #GtkTreeView will take a reference on a node when it is
202 * visible, which means the node is either in the toplevel or expanded.
203 * Being displayed does not mean that the node is currently directly
204 * visible to the user in the viewport. Based on this reference counting
205 * scheme a caching model, for example, can decide whether or not to cache
206 * a node based on the reference count. A file-system based model would
207 * not want to keep the entire file hierarchy in memory, but just the
208 * folders that are currently expanded in every current view.
210 * When working with reference counting, the following rules must be taken
213 * <listitem><para>Never take a reference on a node without owning a
214 * reference on its parent. This means that all parent nodes of a referenced
215 * node must be referenced as well.</para></listitem>
216 * <listitem><para>Outstanding references on a deleted node are not released.
217 * This is not possible because the node has already been deleted by the
218 * time the row-deleted signal is received.
220 * <listitem><para>Models are not obligated to emit a signal on rows of
221 * which none of its siblings are referenced. To phrase this differently,
222 * signals are only required for levels in which nodes are referenced. For
223 * the root level however, signals must be emitted at all times (however the
224 * root level is always referenced when any view is attached).
229 #define INITIALIZE_TREE_ITER(Iter) \
232 (Iter)->user_data = NULL; \
233 (Iter)->user_data2 = NULL; \
234 (Iter)->user_data3 = NULL; \
237 #define ROW_REF_DATA_STRING "gtk-tree-row-refs"
242 ROW_HAS_CHILD_TOGGLED,
248 static guint tree_model_signals[LAST_SIGNAL] = { 0 };
252 gint depth; /* Number of elements */
253 gint alloc; /* Number of allocated elements */
262 static void gtk_tree_model_base_init (gpointer g_class);
264 /* custom closures */
265 static void row_inserted_marshal (GClosure *closure,
266 GValue /* out */ *return_value,
268 const GValue *param_values,
269 gpointer invocation_hint,
270 gpointer marshal_data);
271 static void row_deleted_marshal (GClosure *closure,
272 GValue /* out */ *return_value,
274 const GValue *param_values,
275 gpointer invocation_hint,
276 gpointer marshal_data);
277 static void rows_reordered_marshal (GClosure *closure,
278 GValue /* out */ *return_value,
280 const GValue *param_values,
281 gpointer invocation_hint,
282 gpointer marshal_data);
284 static void gtk_tree_row_ref_inserted (RowRefList *refs,
287 static void gtk_tree_row_ref_deleted (RowRefList *refs,
289 static void gtk_tree_row_ref_reordered (RowRefList *refs,
295 gtk_tree_model_get_type (void)
297 static GType tree_model_type = 0;
299 if (! tree_model_type)
301 const GTypeInfo tree_model_info =
303 sizeof (GtkTreeModelIface), /* class_size */
304 gtk_tree_model_base_init, /* base_init */
305 NULL, /* base_finalize */
307 NULL, /* class_finalize */
308 NULL, /* class_data */
315 g_type_register_static (G_TYPE_INTERFACE, I_("GtkTreeModel"),
316 &tree_model_info, 0);
318 g_type_interface_add_prerequisite (tree_model_type, G_TYPE_OBJECT);
321 return tree_model_type;
325 gtk_tree_model_base_init (gpointer g_class)
327 static gboolean initialized = FALSE;
332 GType row_inserted_params[2];
333 GType row_deleted_params[1];
334 GType rows_reordered_params[3];
336 row_inserted_params[0] = GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE;
337 row_inserted_params[1] = GTK_TYPE_TREE_ITER;
339 row_deleted_params[0] = GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE;
341 rows_reordered_params[0] = GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE;
342 rows_reordered_params[1] = GTK_TYPE_TREE_ITER;
343 rows_reordered_params[2] = G_TYPE_POINTER;
346 * GtkTreeModel::row-changed:
347 * @tree_model: the #GtkTreeModel on which the signal is emitted
348 * @path: a #GtkTreePath identifying the changed row
349 * @iter: a valid #GtkTreeIter pointing to the changed row
351 * This signal is emitted when a row in the model has changed.
353 tree_model_signals[ROW_CHANGED] =
354 g_signal_new (I_("row-changed"),
357 G_STRUCT_OFFSET (GtkTreeModelIface, row_changed),
359 _gtk_marshal_VOID__BOXED_BOXED,
361 GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE,
364 /* We need to get notification about structure changes
365 * to update row references., so instead of using the
366 * standard g_signal_new() with an offset into our interface
367 * structure, we use a customs closures for the class
368 * closures (default handlers) that first update row references
369 * and then calls the function from the interface structure.
371 * The reason we don't simply update the row references from
372 * the wrapper functions (gtk_tree_model_row_inserted(), etc.)
373 * is to keep proper ordering with respect to signal handlers
374 * connected normally and after.
378 * GtkTreeModel::row-inserted:
379 * @tree_model: the #GtkTreeModel on which the signal is emitted
380 * @path: a #GtkTreePath identifying the new row
381 * @iter: a valid #GtkTreeIter pointing to the new row
383 * This signal is emitted when a new row has been inserted in
386 * Note that the row may still be empty at this point, since
387 * it is a common pattern to first insert an empty row, and
388 * then fill it with the desired values.
390 closure = g_closure_new_simple (sizeof (GClosure), NULL);
391 g_closure_set_marshal (closure, row_inserted_marshal);
392 tree_model_signals[ROW_INSERTED] =
393 g_signal_newv (I_("row-inserted"),
398 _gtk_marshal_VOID__BOXED_BOXED,
400 row_inserted_params);
403 * GtkTreeModel::row-has-child-toggled:
404 * @tree_model: the #GtkTreeModel on which the signal is emitted
405 * @path: a #GtkTreePath identifying the row
406 * @iter: a valid #GtkTreeIter pointing to the row
408 * This signal is emitted when a row has gotten the first child
409 * row or lost its last child row.
411 tree_model_signals[ROW_HAS_CHILD_TOGGLED] =
412 g_signal_new (I_("row-has-child-toggled"),
415 G_STRUCT_OFFSET (GtkTreeModelIface, row_has_child_toggled),
417 _gtk_marshal_VOID__BOXED_BOXED,
419 GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE,
423 * GtkTreeModel::row-deleted:
424 * @tree_model: the #GtkTreeModel on which the signal is emitted
425 * @path: a #GtkTreePath identifying the row
427 * This signal is emitted when a row has been deleted.
429 * Note that no iterator is passed to the signal handler,
430 * since the row is already deleted.
432 * This should be called by models after a row has been removed.
433 * The location pointed to by @path should be the location that
434 * the row previously was at. It may not be a valid location anymore.
436 closure = g_closure_new_simple (sizeof (GClosure), NULL);
437 g_closure_set_marshal (closure, row_deleted_marshal);
438 tree_model_signals[ROW_DELETED] =
439 g_signal_newv (I_("row-deleted"),
444 _gtk_marshal_VOID__BOXED,
449 * GtkTreeModel::rows-reordered: (skip)
450 * @tree_model: the #GtkTreeModel on which the signal is emitted
451 * @path: a #GtkTreePath identifying the tree node whose children
452 * have been reordered
453 * @iter: a valid #GtkTreeIter pointing to the node whose
454 * @new_order: an array of integers mapping the current position
455 * of each child to its old position before the re-ordering,
456 * i.e. @new_order<literal>[newpos] = oldpos</literal>
458 * This signal is emitted when the children of a node in the
459 * #GtkTreeModel have been reordered.
461 * Note that this signal is <emphasis>not</emphasis> emitted
462 * when rows are reordered by DND, since this is implemented
463 * by removing and then reinserting the row.
465 closure = g_closure_new_simple (sizeof (GClosure), NULL);
466 g_closure_set_marshal (closure, rows_reordered_marshal);
467 tree_model_signals[ROWS_REORDERED] =
468 g_signal_newv (I_("rows-reordered"),
473 _gtk_marshal_VOID__BOXED_BOXED_POINTER,
475 rows_reordered_params);
481 row_inserted_marshal (GClosure *closure,
482 GValue /* out */ *return_value,
483 guint n_param_values,
484 const GValue *param_values,
485 gpointer invocation_hint,
486 gpointer marshal_data)
488 GtkTreeModelIface *iface;
490 void (* row_inserted_callback) (GtkTreeModel *tree_model,
492 GtkTreeIter *iter) = NULL;
494 GObject *model = g_value_get_object (param_values + 0);
495 GtkTreePath *path = (GtkTreePath *)g_value_get_boxed (param_values + 1);
496 GtkTreeIter *iter = (GtkTreeIter *)g_value_get_boxed (param_values + 2);
498 /* first, we need to update internal row references */
499 gtk_tree_row_ref_inserted ((RowRefList *)g_object_get_data (model, ROW_REF_DATA_STRING),
502 /* fetch the interface ->row_inserted implementation */
503 iface = GTK_TREE_MODEL_GET_IFACE (model);
504 row_inserted_callback = G_STRUCT_MEMBER (gpointer, iface,
505 G_STRUCT_OFFSET (GtkTreeModelIface,
508 /* Call that default signal handler, it if has been set */
509 if (row_inserted_callback)
510 row_inserted_callback (GTK_TREE_MODEL (model), path, iter);
514 row_deleted_marshal (GClosure *closure,
515 GValue /* out */ *return_value,
516 guint n_param_values,
517 const GValue *param_values,
518 gpointer invocation_hint,
519 gpointer marshal_data)
521 GtkTreeModelIface *iface;
522 void (* row_deleted_callback) (GtkTreeModel *tree_model,
523 GtkTreePath *path) = NULL;
524 GObject *model = g_value_get_object (param_values + 0);
525 GtkTreePath *path = (GtkTreePath *)g_value_get_boxed (param_values + 1);
527 /* first, we need to update internal row references */
528 gtk_tree_row_ref_deleted ((RowRefList *)g_object_get_data (model, ROW_REF_DATA_STRING),
531 /* fetch the interface ->row_deleted implementation */
532 iface = GTK_TREE_MODEL_GET_IFACE (model);
533 row_deleted_callback = G_STRUCT_MEMBER (gpointer, iface,
534 G_STRUCT_OFFSET (GtkTreeModelIface,
537 /* Call that default signal handler, it if has been set */
538 if (row_deleted_callback)
539 row_deleted_callback (GTK_TREE_MODEL (model), path);
543 rows_reordered_marshal (GClosure *closure,
544 GValue /* out */ *return_value,
545 guint n_param_values,
546 const GValue *param_values,
547 gpointer invocation_hint,
548 gpointer marshal_data)
550 GtkTreeModelIface *iface;
551 void (* rows_reordered_callback) (GtkTreeModel *tree_model,
556 GObject *model = g_value_get_object (param_values + 0);
557 GtkTreePath *path = (GtkTreePath *)g_value_get_boxed (param_values + 1);
558 GtkTreeIter *iter = (GtkTreeIter *)g_value_get_boxed (param_values + 2);
559 gint *new_order = (gint *)g_value_get_pointer (param_values + 3);
561 /* first, we need to update internal row references */
562 gtk_tree_row_ref_reordered ((RowRefList *)g_object_get_data (model, ROW_REF_DATA_STRING),
563 path, iter, new_order);
565 /* fetch the interface ->rows_reordered implementation */
566 iface = GTK_TREE_MODEL_GET_IFACE (model);
567 rows_reordered_callback = G_STRUCT_MEMBER (gpointer, iface,
568 G_STRUCT_OFFSET (GtkTreeModelIface,
571 /* Call that default signal handler, it if has been set */
572 if (rows_reordered_callback)
573 rows_reordered_callback (GTK_TREE_MODEL (model), path, iter, new_order);
579 * Creates a new #GtkTreePath.
580 * This structure refers to a row.
582 * Return value: A newly created #GtkTreePath.
585 gtk_tree_path_new (void)
588 retval = g_slice_new (GtkTreePath);
591 retval->indices = NULL;
597 * gtk_tree_path_new_from_string:
598 * @path: The string representation of a path
600 * Creates a new #GtkTreePath initialized to @path.
602 * @path is expected to be a colon separated list of numbers.
603 * For example, the string "10:4:0" would create a path of depth
604 * 3 pointing to the 11th child of the root node, the 5th
605 * child of that 11th child, and the 1st child of that 5th child.
606 * If an invalid path string is passed in, %NULL is returned.
608 * Return value: A newly-created #GtkTreePath, or %NULL
611 gtk_tree_path_new_from_string (const gchar *path)
614 const gchar *orig_path = path;
618 g_return_val_if_fail (path != NULL, NULL);
619 g_return_val_if_fail (*path != '\000', NULL);
621 retval = gtk_tree_path_new ();
625 i = strtol (path, &ptr, 10);
628 g_warning (G_STRLOC ": Negative numbers in path %s passed to gtk_tree_path_new_from_string", orig_path);
629 gtk_tree_path_free (retval);
633 gtk_tree_path_append_index (retval, i);
637 if (ptr == path || *ptr != ':')
639 g_warning (G_STRLOC ": Invalid path %s passed to gtk_tree_path_new_from_string", orig_path);
640 gtk_tree_path_free (retval);
650 * gtk_tree_path_new_from_indices:
651 * @first_index: first integer
652 * @...: list of integers terminated by -1
654 * Creates a new path with @first_index and @varargs as indices.
656 * Return value: A newly created #GtkTreePath
661 gtk_tree_path_new_from_indices (gint first_index,
668 path = gtk_tree_path_new ();
670 va_start (args, first_index);
675 gtk_tree_path_append_index (path, arg);
676 arg = va_arg (args, gint);
685 * gtk_tree_path_to_string:
686 * @path: A #GtkTreePath
688 * Generates a string representation of the path.
690 * This string is a ':' separated list of numbers.
691 * For example, "4:10:0:3" would be an acceptable
692 * return value for this string.
694 * Return value: A newly-allocated string.
695 * Must be freed with g_free().
698 gtk_tree_path_to_string (GtkTreePath *path)
700 gchar *retval, *ptr, *end;
703 g_return_val_if_fail (path != NULL, NULL);
705 if (path->depth == 0)
708 n = path->depth * 12;
709 ptr = retval = g_new0 (gchar, n);
711 g_snprintf (retval, end - ptr, "%d", path->indices[0]);
712 while (*ptr != '\000')
715 for (i = 1; i < path->depth; i++)
717 g_snprintf (ptr, end - ptr, ":%d", path->indices[i]);
718 while (*ptr != '\000')
726 * gtk_tree_path_new_first:
728 * Creates a new #GtkTreePath.
730 * The string representation of this path is "0".
732 * Return value: A new #GtkTreePath
735 gtk_tree_path_new_first (void)
739 retval = gtk_tree_path_new ();
740 gtk_tree_path_append_index (retval, 0);
746 * gtk_tree_path_append_index:
747 * @path: a #GtkTreePath
750 * Appends a new index to a path.
752 * As a result, the depth of the path is increased.
755 gtk_tree_path_append_index (GtkTreePath *path,
758 g_return_if_fail (path != NULL);
759 g_return_if_fail (index_ >= 0);
761 if (path->depth == path->alloc)
764 path->alloc = MAX (path->alloc * 2, 1);
765 indices = g_new (gint, path->alloc);
766 memcpy (indices, path->indices, path->depth * sizeof (gint));
767 g_free (path->indices);
768 path->indices = indices;
772 path->indices[path->depth - 1] = index_;
776 * gtk_tree_path_prepend_index:
777 * @path: a #GtkTreePath
780 * Prepends a new index to a path.
782 * As a result, the depth of the path is increased.
785 gtk_tree_path_prepend_index (GtkTreePath *path,
788 if (path->depth == path->alloc)
791 path->alloc = MAX (path->alloc * 2, 1);
792 indices = g_new (gint, path->alloc);
793 memcpy (indices + 1, path->indices, path->depth * sizeof (gint));
794 g_free (path->indices);
795 path->indices = indices;
797 else if (path->depth > 0)
798 memmove (path->indices + 1, path->indices, path->depth * sizeof (gint));
801 path->indices[0] = index;
805 * gtk_tree_path_get_depth:
806 * @path: a #GtkTreePath
808 * Returns the current depth of @path.
810 * Return value: The depth of @path
813 gtk_tree_path_get_depth (GtkTreePath *path)
815 g_return_val_if_fail (path != NULL, 0);
821 * gtk_tree_path_get_indices: (skip)
822 * @path: a #GtkTreePath
824 * Returns the current indices of @path.
826 * This is an array of integers, each representing a node in a tree.
827 * This value should not be freed.
829 * The length of the array can be obtained with gtk_tree_path_get_depth().
831 * Return value: The current indices, or %NULL
834 gtk_tree_path_get_indices (GtkTreePath *path)
836 g_return_val_if_fail (path != NULL, NULL);
838 return path->indices;
842 * gtk_tree_path_get_indices_with_depth:
843 * @path: a #GtkTreePath
844 * @depth: (allow-none): return location for number of elements
845 * returned in the integer array, or %NULL
847 * Returns the current indices of @path.
849 * This is an array of integers, each representing a node in a tree.
850 * It also returns the number of elements in the array.
851 * The array should not be freed.
853 * Return value: (array length=depth) (transfer none): The current
858 * Rename to: gtk_tree_path_get_indices
861 gtk_tree_path_get_indices_with_depth (GtkTreePath *path,
864 g_return_val_if_fail (path != NULL, NULL);
867 *depth = path->depth;
869 return path->indices;
873 * gtk_tree_path_free:
874 * @path: (allow-none): a #GtkTreePath
876 * Frees @path. If @path is %NULL, it simply returns.
879 gtk_tree_path_free (GtkTreePath *path)
884 g_free (path->indices);
885 g_slice_free (GtkTreePath, path);
889 * gtk_tree_path_copy:
890 * @path: a #GtkTreePath
892 * Creates a new #GtkTreePath as a copy of @path.
894 * Return value: a new #GtkTreePath
897 gtk_tree_path_copy (const GtkTreePath *path)
901 g_return_val_if_fail (path != NULL, NULL);
903 retval = g_slice_new (GtkTreePath);
904 retval->depth = path->depth;
905 retval->alloc = retval->depth;
906 retval->indices = g_new (gint, path->alloc);
907 memcpy (retval->indices, path->indices, path->depth * sizeof (gint));
911 G_DEFINE_BOXED_TYPE (GtkTreePath, gtk_tree_path,
916 * gtk_tree_path_compare:
918 * @b: a #GtkTreePath to compare with
920 * Compares two paths.
922 * If @a appears before @b in a tree, then -1 is returned.
923 * If @b appears before @a, then 1 is returned.
924 * If the two nodes are equal, then 0 is returned.
926 * Return value: the relative positions of @a and @b
929 gtk_tree_path_compare (const GtkTreePath *a,
930 const GtkTreePath *b)
934 g_return_val_if_fail (a != NULL, 0);
935 g_return_val_if_fail (b != NULL, 0);
936 g_return_val_if_fail (a->depth > 0, 0);
937 g_return_val_if_fail (b->depth > 0, 0);
941 if (a->indices[p] == b->indices[q])
943 return (a->indices[p] < b->indices[q]?-1:1);
945 while (++p < a->depth && ++q < b->depth);
946 if (a->depth == b->depth)
948 return (a->depth < b->depth?-1:1);
952 * gtk_tree_path_is_ancestor:
953 * @path: a #GtkTreePath
954 * @descendant: another #GtkTreePath
956 * Returns %TRUE if @descendant is a descendant of @path.
958 * Return value: %TRUE if @descendant is contained inside @path
961 gtk_tree_path_is_ancestor (GtkTreePath *path,
962 GtkTreePath *descendant)
966 g_return_val_if_fail (path != NULL, FALSE);
967 g_return_val_if_fail (descendant != NULL, FALSE);
969 /* can't be an ancestor if we're deeper */
970 if (path->depth >= descendant->depth)
974 while (i < path->depth)
976 if (path->indices[i] != descendant->indices[i])
985 * gtk_tree_path_is_descendant:
986 * @path: a #GtkTreePath
987 * @ancestor: another #GtkTreePath
989 * Returns %TRUE if @path is a descendant of @ancestor.
991 * Return value: %TRUE if @ancestor contains @path somewhere below it
994 gtk_tree_path_is_descendant (GtkTreePath *path,
995 GtkTreePath *ancestor)
999 g_return_val_if_fail (path != NULL, FALSE);
1000 g_return_val_if_fail (ancestor != NULL, FALSE);
1002 /* can't be a descendant if we're shallower in the tree */
1003 if (path->depth <= ancestor->depth)
1007 while (i < ancestor->depth)
1009 if (path->indices[i] != ancestor->indices[i])
1019 * gtk_tree_path_next:
1020 * @path: a #GtkTreePath
1022 * Moves the @path to point to the next node at the current depth.
1025 gtk_tree_path_next (GtkTreePath *path)
1027 g_return_if_fail (path != NULL);
1028 g_return_if_fail (path->depth > 0);
1030 path->indices[path->depth - 1] ++;
1034 * gtk_tree_path_prev:
1035 * @path: a #GtkTreePath
1037 * Moves the @path to point to the previous node at the
1038 * current depth, if it exists.
1040 * Return value: %TRUE if @path has a previous node, and
1044 gtk_tree_path_prev (GtkTreePath *path)
1046 g_return_val_if_fail (path != NULL, FALSE);
1048 if (path->depth == 0)
1051 if (path->indices[path->depth - 1] == 0)
1054 path->indices[path->depth - 1] -= 1;
1061 * @path: a #GtkTreePath
1063 * Moves the @path to point to its parent node, if it has a parent.
1065 * Return value: %TRUE if @path has a parent, and the move was made
1068 gtk_tree_path_up (GtkTreePath *path)
1070 g_return_val_if_fail (path != NULL, FALSE);
1072 if (path->depth == 0)
1081 * gtk_tree_path_down:
1082 * @path: a #GtkTreePath
1084 * Moves @path to point to the first child of the current path.
1087 gtk_tree_path_down (GtkTreePath *path)
1089 g_return_if_fail (path != NULL);
1091 gtk_tree_path_append_index (path, 0);
1095 * gtk_tree_iter_copy:
1096 * @iter: a #GtkTreeIter
1098 * Creates a dynamically allocated tree iterator as a copy of @iter.
1100 * This function is not intended for use in applications,
1101 * because you can just copy the structs by value
1102 * (<literal>GtkTreeIter new_iter = iter;</literal>).
1103 * You must free this iter with gtk_tree_iter_free().
1105 * Return value: a newly-allocated copy of @iter
1108 gtk_tree_iter_copy (GtkTreeIter *iter)
1110 GtkTreeIter *retval;
1112 g_return_val_if_fail (iter != NULL, NULL);
1114 retval = g_slice_new (GtkTreeIter);
1121 * gtk_tree_iter_free:
1122 * @iter: a dynamically allocated tree iterator
1124 * Frees an iterator that has been allocated by gtk_tree_iter_copy().
1126 * This function is mainly used for language bindings.
1129 gtk_tree_iter_free (GtkTreeIter *iter)
1131 g_return_if_fail (iter != NULL);
1133 g_slice_free (GtkTreeIter, iter);
1136 G_DEFINE_BOXED_TYPE (GtkTreeIter, gtk_tree_iter,
1141 * gtk_tree_model_get_flags:
1142 * @tree_model: a #GtkTreeModel
1144 * Returns a set of flags supported by this interface.
1146 * The flags are a bitwise combination of #GtkTreeModelFlags.
1147 * The flags supported should not change during the lifetime
1148 * of the @tree_model.
1150 * Return value: the flags supported by this interface
1153 gtk_tree_model_get_flags (GtkTreeModel *tree_model)
1155 GtkTreeModelIface *iface;
1157 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), 0);
1159 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1160 if (iface->get_flags)
1161 return (* iface->get_flags) (tree_model);
1167 * gtk_tree_model_get_n_columns:
1168 * @tree_model: a #GtkTreeModel
1170 * Returns the number of columns supported by @tree_model.
1172 * Return value: the number of columns
1175 gtk_tree_model_get_n_columns (GtkTreeModel *tree_model)
1177 GtkTreeModelIface *iface;
1178 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), 0);
1180 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1181 g_return_val_if_fail (iface->get_n_columns != NULL, 0);
1183 return (* iface->get_n_columns) (tree_model);
1187 * gtk_tree_model_get_column_type:
1188 * @tree_model: a #GtkTreeModel
1189 * @index_: the column index
1191 * Returns the type of the column.
1193 * Return value: (transfer none): the type of the column
1196 gtk_tree_model_get_column_type (GtkTreeModel *tree_model,
1199 GtkTreeModelIface *iface;
1201 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), G_TYPE_INVALID);
1203 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1204 g_return_val_if_fail (iface->get_column_type != NULL, G_TYPE_INVALID);
1205 g_return_val_if_fail (index >= 0, G_TYPE_INVALID);
1207 return (* iface->get_column_type) (tree_model, index);
1211 * gtk_tree_model_get_iter:
1212 * @tree_model: a #GtkTreeModel
1213 * @iter: (out): the uninitialized #GtkTreeIter
1214 * @path: the #GtkTreePath
1216 * Sets @iter to a valid iterator pointing to @path. If @path does
1217 * not exist, @iter is set to an invalid iterator and %FALSE is returned.
1219 * Return value: %TRUE, if @iter was set
1222 gtk_tree_model_get_iter (GtkTreeModel *tree_model,
1226 GtkTreeModelIface *iface;
1228 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1229 g_return_val_if_fail (iter != NULL, FALSE);
1230 g_return_val_if_fail (path != NULL, FALSE);
1232 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1233 g_return_val_if_fail (iface->get_iter != NULL, FALSE);
1234 g_return_val_if_fail (path->depth > 0, FALSE);
1236 INITIALIZE_TREE_ITER (iter);
1238 return (* iface->get_iter) (tree_model, iter, path);
1242 * gtk_tree_model_get_iter_from_string:
1243 * @tree_model: a #GtkTreeModel
1244 * @iter: (out): an uninitialized #GtkTreeIter
1245 * @path_string: a string representation of a #GtkTreePath
1247 * Sets @iter to a valid iterator pointing to @path_string, if it
1248 * exists. Otherwise, @iter is left invalid and %FALSE is returned.
1250 * Return value: %TRUE, if @iter was set
1253 gtk_tree_model_get_iter_from_string (GtkTreeModel *tree_model,
1255 const gchar *path_string)
1260 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1261 g_return_val_if_fail (iter != NULL, FALSE);
1262 g_return_val_if_fail (path_string != NULL, FALSE);
1264 path = gtk_tree_path_new_from_string (path_string);
1266 g_return_val_if_fail (path != NULL, FALSE);
1268 retval = gtk_tree_model_get_iter (tree_model, iter, path);
1269 gtk_tree_path_free (path);
1275 * gtk_tree_model_get_string_from_iter:
1276 * @tree_model: a #GtkTreeModel
1277 * @iter: a #GtkTreeIter
1279 * Generates a string representation of the iter.
1281 * This string is a ':' separated list of numbers.
1282 * For example, "4:10:0:3" would be an acceptable
1283 * return value for this string.
1285 * Return value: a newly-allocated string.
1286 * Must be freed with g_free().
1291 gtk_tree_model_get_string_from_iter (GtkTreeModel *tree_model,
1297 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), NULL);
1298 g_return_val_if_fail (iter != NULL, NULL);
1300 path = gtk_tree_model_get_path (tree_model, iter);
1302 g_return_val_if_fail (path != NULL, NULL);
1304 ret = gtk_tree_path_to_string (path);
1305 gtk_tree_path_free (path);
1311 * gtk_tree_model_get_iter_first:
1312 * @tree_model: a #GtkTreeModel
1313 * @iter: (out): the uninitialized #GtkTreeIter
1315 * Initializes @iter with the first iterator in the tree
1316 * (the one at the path "0") and returns %TRUE. Returns
1317 * %FALSE if the tree is empty.
1319 * Return value: %TRUE, if @iter was set
1322 gtk_tree_model_get_iter_first (GtkTreeModel *tree_model,
1328 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1329 g_return_val_if_fail (iter != NULL, FALSE);
1331 path = gtk_tree_path_new_first ();
1332 retval = gtk_tree_model_get_iter (tree_model, iter, path);
1333 gtk_tree_path_free (path);
1339 * gtk_tree_model_get_path:
1340 * @tree_model: a #GtkTreeModel
1341 * @iter: the #GtkTreeIter
1343 * Returns a newly-created #GtkTreePath referenced by @iter.
1345 * This path should be freed with gtk_tree_path_free().
1347 * Return value: a newly-created #GtkTreePath
1350 gtk_tree_model_get_path (GtkTreeModel *tree_model,
1353 GtkTreeModelIface *iface;
1355 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), NULL);
1356 g_return_val_if_fail (iter != NULL, NULL);
1358 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1359 g_return_val_if_fail (iface->get_path != NULL, NULL);
1361 return (* iface->get_path) (tree_model, iter);
1365 * gtk_tree_model_get_value:
1366 * @tree_model: a #GtkTreeModel
1367 * @iter: the #GtkTreeIter
1368 * @column: the column to lookup the value at
1369 * @value: (out) (transfer none): an empty #GValue to set
1371 * Initializes and sets @value to that at @column.
1373 * When done with @value, g_value_unset() needs to be called
1374 * to free any allocated memory.
1377 gtk_tree_model_get_value (GtkTreeModel *tree_model,
1382 GtkTreeModelIface *iface;
1384 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1385 g_return_if_fail (iter != NULL);
1386 g_return_if_fail (value != NULL);
1388 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1389 g_return_if_fail (iface->get_value != NULL);
1391 (* iface->get_value) (tree_model, iter, column, value);
1395 * gtk_tree_model_iter_next:
1396 * @tree_model: a #GtkTreeModel
1397 * @iter: (in): the #GtkTreeIter
1399 * Sets @iter to point to the node following it at the current level.
1401 * If there is no next @iter, %FALSE is returned and @iter is set
1404 * Return value: %TRUE if @iter has been changed to the next node
1407 gtk_tree_model_iter_next (GtkTreeModel *tree_model,
1410 GtkTreeModelIface *iface;
1412 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1413 g_return_val_if_fail (iter != NULL, FALSE);
1415 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1416 g_return_val_if_fail (iface->iter_next != NULL, FALSE);
1418 return (* iface->iter_next) (tree_model, iter);
1422 gtk_tree_model_iter_previous_default (GtkTreeModel *tree_model,
1428 path = gtk_tree_model_get_path (tree_model, iter);
1432 retval = gtk_tree_path_prev (path) &&
1433 gtk_tree_model_get_iter (tree_model, iter, path);
1434 if (retval == FALSE)
1437 gtk_tree_path_free (path);
1443 * gtk_tree_model_iter_previous:
1444 * @tree_model: a #GtkTreeModel
1445 * @iter: (in): the #GtkTreeIter
1447 * Sets @iter to point to the previous node at the current level.
1449 * If there is no previous @iter, %FALSE is returned and @iter is
1450 * set to be invalid.
1452 * Return value: %TRUE if @iter has been changed to the previous node
1457 gtk_tree_model_iter_previous (GtkTreeModel *tree_model,
1461 GtkTreeModelIface *iface;
1463 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1464 g_return_val_if_fail (iter != NULL, FALSE);
1466 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1468 if (iface->iter_previous)
1469 retval = (* iface->iter_previous) (tree_model, iter);
1471 retval = gtk_tree_model_iter_previous_default (tree_model, iter);
1477 * gtk_tree_model_iter_children:
1478 * @tree_model: a #GtkTreeModel
1479 * @iter: (out): the new #GtkTreeIter to be set to the child
1480 * @parent: (allow-none): the #GtkTreeIter, or %NULL
1482 * Sets @iter to point to the first child of @parent.
1484 * If @parent has no children, %FALSE is returned and @iter is
1485 * set to be invalid. @parent will remain a valid node after this
1486 * function has been called.
1488 * If @parent is %NULL returns the first node, equivalent to
1489 * <literal>gtk_tree_model_get_iter_first (tree_model, iter);</literal>
1491 * Return value: %TRUE, if @child has been set to the first child
1494 gtk_tree_model_iter_children (GtkTreeModel *tree_model,
1496 GtkTreeIter *parent)
1498 GtkTreeModelIface *iface;
1500 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1501 g_return_val_if_fail (iter != NULL, FALSE);
1503 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1504 g_return_val_if_fail (iface->iter_children != NULL, FALSE);
1506 INITIALIZE_TREE_ITER (iter);
1508 return (* iface->iter_children) (tree_model, iter, parent);
1512 * gtk_tree_model_iter_has_child:
1513 * @tree_model: a #GtkTreeModel
1514 * @iter: the #GtkTreeIter to test for children
1516 * Returns %TRUE if @iter has children, %FALSE otherwise.
1518 * Return value: %TRUE if @iter has children
1521 gtk_tree_model_iter_has_child (GtkTreeModel *tree_model,
1524 GtkTreeModelIface *iface;
1526 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1527 g_return_val_if_fail (iter != NULL, FALSE);
1529 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1530 g_return_val_if_fail (iface->iter_has_child != NULL, FALSE);
1532 return (* iface->iter_has_child) (tree_model, iter);
1536 * gtk_tree_model_iter_n_children:
1537 * @tree_model: a #GtkTreeModel
1538 * @iter: (allow-none): the #GtkTreeIter, or %NULL
1540 * Returns the number of children that @iter has.
1542 * As a special case, if @iter is %NULL, then the number
1543 * of toplevel nodes is returned.
1545 * Return value: the number of children of @iter
1548 gtk_tree_model_iter_n_children (GtkTreeModel *tree_model,
1551 GtkTreeModelIface *iface;
1553 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), 0);
1555 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1556 g_return_val_if_fail (iface->iter_n_children != NULL, 0);
1558 return (* iface->iter_n_children) (tree_model, iter);
1562 * gtk_tree_model_iter_nth_child:
1563 * @tree_model: a #GtkTreeModel
1564 * @iter: (out): the #GtkTreeIter to set to the nth child
1565 * @parent: (allow-none): the #GtkTreeIter to get the child from, or %NULL.
1566 * @n: the index of the desired child
1568 * Sets @iter to be the child of @parent, using the given index.
1570 * The first index is 0. If @n is too big, or @parent has no children,
1571 * @iter is set to an invalid iterator and %FALSE is returned. @parent
1572 * will remain a valid node after this function has been called. As a
1573 * special case, if @parent is %NULL, then the @n<!-- -->th root node
1576 * Return value: %TRUE, if @parent has an @n<!-- -->th child
1579 gtk_tree_model_iter_nth_child (GtkTreeModel *tree_model,
1581 GtkTreeIter *parent,
1584 GtkTreeModelIface *iface;
1586 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1587 g_return_val_if_fail (iter != NULL, FALSE);
1588 g_return_val_if_fail (n >= 0, FALSE);
1590 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1591 g_return_val_if_fail (iface->iter_nth_child != NULL, FALSE);
1593 INITIALIZE_TREE_ITER (iter);
1595 return (* iface->iter_nth_child) (tree_model, iter, parent, n);
1599 * gtk_tree_model_iter_parent:
1600 * @tree_model: a #GtkTreeModel
1601 * @iter: (out): the new #GtkTreeIter to set to the parent
1602 * @child: the #GtkTreeIter
1604 * Sets @iter to be the parent of @child.
1606 * If @child is at the toplevel, and doesn't have a parent, then
1607 * @iter is set to an invalid iterator and %FALSE is returned.
1608 * @child will remain a valid node after this function has been
1611 * Return value: %TRUE, if @iter is set to the parent of @child
1614 gtk_tree_model_iter_parent (GtkTreeModel *tree_model,
1618 GtkTreeModelIface *iface;
1620 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1621 g_return_val_if_fail (iter != NULL, FALSE);
1622 g_return_val_if_fail (child != NULL, FALSE);
1624 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1625 g_return_val_if_fail (iface->iter_parent != NULL, FALSE);
1627 INITIALIZE_TREE_ITER (iter);
1629 return (* iface->iter_parent) (tree_model, iter, child);
1633 * gtk_tree_model_ref_node:
1634 * @tree_model: a #GtkTreeModel
1635 * @iter: the #GtkTreeIter
1637 * Lets the tree ref the node.
1639 * This is an optional method for models to implement.
1640 * To be more specific, models may ignore this call as it exists
1641 * primarily for performance reasons.
1643 * This function is primarily meant as a way for views to let
1644 * caching models know when nodes are being displayed (and hence,
1645 * whether or not to cache that node). Being displayed means a node
1646 * is in an expanded branch, regardless of whether the node is currently
1647 * visible in the viewport. For example, a file-system based model
1648 * would not want to keep the entire file-hierarchy in memory,
1649 * just the sections that are currently being displayed by
1650 * every current view.
1652 * A model should be expected to be able to get an iter independent
1653 * of its reffed state.
1656 gtk_tree_model_ref_node (GtkTreeModel *tree_model,
1659 GtkTreeModelIface *iface;
1661 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1663 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1664 if (iface->ref_node)
1665 (* iface->ref_node) (tree_model, iter);
1669 * gtk_tree_model_unref_node:
1670 * @tree_model: a #GtkTreeModel
1671 * @iter: the #GtkTreeIter
1673 * Lets the tree unref the node.
1675 * This is an optional method for models to implement.
1676 * To be more specific, models may ignore this call as it exists
1677 * primarily for performance reasons. For more information on what
1678 * this means, see gtk_tree_model_ref_node().
1680 * Please note that nodes that are deleted are not unreffed.
1683 gtk_tree_model_unref_node (GtkTreeModel *tree_model,
1686 GtkTreeModelIface *iface;
1688 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1689 g_return_if_fail (iter != NULL);
1691 iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
1692 if (iface->unref_node)
1693 (* iface->unref_node) (tree_model, iter);
1697 * gtk_tree_model_get:
1698 * @tree_model: a #GtkTreeModel
1699 * @iter: a row in @tree_model
1700 * @...: pairs of column number and value return locations,
1703 * Gets the value of one or more cells in the row referenced by @iter.
1704 * The variable argument list should contain integer column numbers,
1705 * each column number followed by a place to store the value being
1706 * retrieved. The list is terminated by a -1. For example, to get a
1707 * value from column 0 with type %G_TYPE_STRING, you would
1708 * write: <literal>gtk_tree_model_get (model, iter, 0, &place_string_here, -1)</literal>,
1709 * where <literal>place_string_here</literal> is a <type>gchar*</type>
1710 * to be filled with the string.
1712 * Returned values with type %G_TYPE_OBJECT have to be unreferenced,
1713 * values with type %G_TYPE_STRING or %G_TYPE_BOXED have to be freed.
1714 * Other values are passed by value.
1717 gtk_tree_model_get (GtkTreeModel *tree_model,
1723 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1724 g_return_if_fail (iter != NULL);
1726 va_start (var_args, iter);
1727 gtk_tree_model_get_valist (tree_model, iter, var_args);
1732 * gtk_tree_model_get_valist:
1733 * @tree_model: a #GtkTreeModel
1734 * @iter: a row in @tree_model
1735 * @var_args: <type>va_list</type> of column/return location pairs
1737 * See gtk_tree_model_get(), this version takes a <type>va_list</type>
1738 * for language bindings to use.
1741 gtk_tree_model_get_valist (GtkTreeModel *tree_model,
1747 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1748 g_return_if_fail (iter != NULL);
1750 column = va_arg (var_args, gint);
1752 while (column != -1)
1754 GValue value = G_VALUE_INIT;
1755 gchar *error = NULL;
1757 if (column >= gtk_tree_model_get_n_columns (tree_model))
1759 g_warning ("%s: Invalid column number %d accessed (remember to end your list of columns with a -1)", G_STRLOC, column);
1763 gtk_tree_model_get_value (GTK_TREE_MODEL (tree_model), iter, column, &value);
1765 G_VALUE_LCOPY (&value, var_args, 0, &error);
1768 g_warning ("%s: %s", G_STRLOC, error);
1771 /* we purposely leak the value here, it might not be
1772 * in a sane state if an error condition occurred
1777 g_value_unset (&value);
1779 column = va_arg (var_args, gint);
1784 * gtk_tree_model_row_changed:
1785 * @tree_model: a #GtkTreeModel
1786 * @path: a #GtkTreePath pointing to the changed row
1787 * @iter: a valid #GtkTreeIter pointing to the changed row
1789 * Emits the #GtkTreeModel::row-changed signal on @tree_model.
1792 gtk_tree_model_row_changed (GtkTreeModel *tree_model,
1796 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1797 g_return_if_fail (path != NULL);
1798 g_return_if_fail (iter != NULL);
1800 g_signal_emit (tree_model, tree_model_signals[ROW_CHANGED], 0, path, iter);
1804 * gtk_tree_model_row_inserted:
1805 * @tree_model: a #GtkTreeModel
1806 * @path: a #GtkTreePath pointing to the inserted row
1807 * @iter: a valid #GtkTreeIter pointing to the inserted row
1809 * Emits the #GtkTreeModel::row-inserted signal on @tree_model.
1812 gtk_tree_model_row_inserted (GtkTreeModel *tree_model,
1816 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1817 g_return_if_fail (path != NULL);
1818 g_return_if_fail (iter != NULL);
1820 g_signal_emit (tree_model, tree_model_signals[ROW_INSERTED], 0, path, iter);
1824 * gtk_tree_model_row_has_child_toggled:
1825 * @tree_model: a #GtkTreeModel
1826 * @path: a #GtkTreePath pointing to the changed row
1827 * @iter: a valid #GtkTreeIter pointing to the changed row
1829 * Emits the #GtkTreeModel::row-has-child-toggled signal on
1830 * @tree_model. This should be called by models after the child
1831 * state of a node changes.
1834 gtk_tree_model_row_has_child_toggled (GtkTreeModel *tree_model,
1838 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1839 g_return_if_fail (path != NULL);
1840 g_return_if_fail (iter != NULL);
1842 g_signal_emit (tree_model, tree_model_signals[ROW_HAS_CHILD_TOGGLED], 0, path, iter);
1846 * gtk_tree_model_row_deleted:
1847 * @tree_model: a #GtkTreeModel
1848 * @path: a #GtkTreePath pointing to the previous location of
1851 * Emits the #GtkTreeModel::row-deleted signal on @tree_model.
1853 * This should be called by models after a row has been removed.
1854 * The location pointed to by @path should be the location that
1855 * the row previously was at. It may not be a valid location anymore.
1857 * Nodes that are deleted are not unreffed, this means that any
1858 * outstanding references on the deleted node should not be released.
1861 gtk_tree_model_row_deleted (GtkTreeModel *tree_model,
1864 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1865 g_return_if_fail (path != NULL);
1867 g_signal_emit (tree_model, tree_model_signals[ROW_DELETED], 0, path);
1871 * gtk_tree_model_rows_reordered: (skip)
1872 * @tree_model: a #GtkTreeModel
1873 * @path: a #GtkTreePath pointing to the tree node whose children
1874 * have been reordered
1875 * @iter: a valid #GtkTreeIter pointing to the node whose children
1876 * have been reordered, or %NULL if the depth of @path is 0
1877 * @new_order: an array of integers mapping the current position of
1878 * each child to its old position before the re-ordering,
1879 * i.e. @new_order<literal>[newpos] = oldpos</literal>
1881 * Emits the #GtkTreeModel::rows-reordered signal on @tree_model.
1883 * This should be called by models when their rows have been
1887 gtk_tree_model_rows_reordered (GtkTreeModel *tree_model,
1892 g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
1893 g_return_if_fail (new_order != NULL);
1895 g_signal_emit (tree_model, tree_model_signals[ROWS_REORDERED], 0, path, iter, new_order);
1900 gtk_tree_model_foreach_helper (GtkTreeModel *model,
1903 GtkTreeModelForeachFunc func,
1910 if ((* func) (model, path, iter, user_data))
1913 if (gtk_tree_model_iter_children (model, &child, iter))
1915 gtk_tree_path_down (path);
1916 if (gtk_tree_model_foreach_helper (model, &child, path, func, user_data))
1918 gtk_tree_path_up (path);
1921 gtk_tree_path_next (path);
1923 while (gtk_tree_model_iter_next (model, iter));
1929 * gtk_tree_model_foreach:
1930 * @model: a #GtkTreeModel
1931 * @func: (scope call): a function to be called on each row
1932 * @user_data: user data to passed to @func
1934 * Calls func on each node in model in a depth-first fashion.
1936 * If @func returns %TRUE, then the tree ceases to be walked,
1937 * and gtk_tree_model_foreach() returns.
1940 gtk_tree_model_foreach (GtkTreeModel *model,
1941 GtkTreeModelForeachFunc func,
1947 g_return_if_fail (GTK_IS_TREE_MODEL (model));
1948 g_return_if_fail (func != NULL);
1950 path = gtk_tree_path_new_first ();
1951 if (gtk_tree_model_get_iter (model, &iter, path) == FALSE)
1953 gtk_tree_path_free (path);
1957 gtk_tree_model_foreach_helper (model, &iter, path, func, user_data);
1958 gtk_tree_path_free (path);
1963 * GtkTreeRowReference
1966 static void gtk_tree_row_reference_unref_path (GtkTreePath *path,
1967 GtkTreeModel *model,
1971 G_DEFINE_BOXED_TYPE (GtkTreeRowReference, gtk_tree_row_reference,
1972 gtk_tree_row_reference_copy,
1973 gtk_tree_row_reference_free)
1975 struct _GtkTreeRowReference
1978 GtkTreeModel *model;
1984 release_row_references (gpointer data)
1986 RowRefList *refs = data;
1987 GSList *tmp_list = NULL;
1989 tmp_list = refs->list;
1990 while (tmp_list != NULL)
1992 GtkTreeRowReference *reference = tmp_list->data;
1994 if (reference->proxy == (GObject *)reference->model)
1995 reference->model = NULL;
1996 reference->proxy = NULL;
1998 /* we don't free the reference, users are responsible for that. */
2000 tmp_list = g_slist_next (tmp_list);
2003 g_slist_free (refs->list);
2008 gtk_tree_row_ref_inserted (RowRefList *refs,
2017 /* This function corrects the path stored in the reference to
2018 * account for an insertion. Note that it's called _after_ the
2019 * insertion with the path to the newly-inserted row. Which means
2020 * that the inserted path is in a different "coordinate system" than
2021 * the old path (e.g. if the inserted path was just before the old
2022 * path, then inserted path and old path will be the same, and old
2023 * path must be moved down one).
2026 tmp_list = refs->list;
2028 while (tmp_list != NULL)
2030 GtkTreeRowReference *reference = tmp_list->data;
2032 if (reference->path == NULL)
2035 if (reference->path->depth >= path->depth)
2038 gboolean ancestor = TRUE;
2040 for (i = 0; i < path->depth - 1; i ++)
2042 if (path->indices[i] != reference->path->indices[i])
2048 if (ancestor == FALSE)
2051 if (path->indices[path->depth-1] <= reference->path->indices[path->depth-1])
2052 reference->path->indices[path->depth-1] += 1;
2055 tmp_list = g_slist_next (tmp_list);
2060 gtk_tree_row_ref_deleted (RowRefList *refs,
2068 /* This function corrects the path stored in the reference to
2069 * account for an deletion. Note that it's called _after_ the
2070 * deletion with the old path of the just-deleted row. Which means
2071 * that the deleted path is the same now-defunct "coordinate system"
2072 * as the path saved in the reference, which is what we want to fix.
2075 tmp_list = refs->list;
2077 while (tmp_list != NULL)
2079 GtkTreeRowReference *reference = tmp_list->data;
2081 if (reference->path)
2085 if (path->depth > reference->path->depth)
2087 for (i = 0; i < path->depth - 1; i++)
2089 if (path->indices[i] != reference->path->indices[i])
2093 /* We know it affects us. */
2094 if (path->indices[i] == reference->path->indices[i])
2096 if (reference->path->depth > path->depth)
2097 /* some parent was deleted, trying to unref any node
2098 * between the deleted parent and the node the reference
2099 * is pointing to is bad, as those nodes are already gone.
2101 gtk_tree_row_reference_unref_path (reference->path, reference->model, path->depth - 1);
2103 gtk_tree_row_reference_unref_path (reference->path, reference->model, reference->path->depth - 1);
2104 gtk_tree_path_free (reference->path);
2105 reference->path = NULL;
2107 else if (path->indices[i] < reference->path->indices[i])
2109 reference->path->indices[path->depth-1]-=1;
2114 tmp_list = g_slist_next (tmp_list);
2119 gtk_tree_row_ref_reordered (RowRefList *refs,
2130 tmp_list = refs->list;
2132 while (tmp_list != NULL)
2134 GtkTreeRowReference *reference = tmp_list->data;
2136 length = gtk_tree_model_iter_n_children (GTK_TREE_MODEL (reference->model), iter);
2141 if ((reference->path) &&
2142 (gtk_tree_path_is_ancestor (path, reference->path)))
2144 gint ref_depth = gtk_tree_path_get_depth (reference->path);
2145 gint depth = gtk_tree_path_get_depth (path);
2147 if (ref_depth > depth)
2150 gint *indices = gtk_tree_path_get_indices (reference->path);
2152 for (i = 0; i < length; i++)
2154 if (new_order[i] == indices[depth])
2163 tmp_list = g_slist_next (tmp_list);
2167 /* We do this recursively so that we can unref children nodes
2168 * before their parent
2171 gtk_tree_row_reference_unref_path_helper (GtkTreePath *path,
2172 GtkTreeModel *model,
2173 GtkTreeIter *parent_iter,
2179 if (depth == current_depth)
2182 gtk_tree_model_iter_nth_child (model, &iter, parent_iter, path->indices[current_depth]);
2183 gtk_tree_row_reference_unref_path_helper (path, model, &iter, depth, current_depth + 1);
2184 gtk_tree_model_unref_node (model, &iter);
2188 gtk_tree_row_reference_unref_path (GtkTreePath *path,
2189 GtkTreeModel *model,
2197 gtk_tree_model_iter_nth_child (model, &iter, NULL, path->indices[0]);
2198 gtk_tree_row_reference_unref_path_helper (path, model, &iter, depth, 1);
2199 gtk_tree_model_unref_node (model, &iter);
2203 * gtk_tree_row_reference_new:
2204 * @model: a #GtkTreeModel
2205 * @path: a valid #GtkTreePath to monitor
2207 * Creates a row reference based on @path.
2209 * This reference will keep pointing to the node pointed to
2210 * by @path, so long as it exists. Any changes that occur on @model are
2211 * propagated, and the path is updated appropriately. If
2212 * @path isn't a valid path in @model, then %NULL is returned.
2214 * Return value: a newly allocated #GtkTreeRowReference, or %NULL
2216 GtkTreeRowReference *
2217 gtk_tree_row_reference_new (GtkTreeModel *model,
2220 g_return_val_if_fail (GTK_IS_TREE_MODEL (model), NULL);
2221 g_return_val_if_fail (path != NULL, NULL);
2223 /* We use the model itself as the proxy object; and call
2224 * gtk_tree_row_reference_inserted(), etc, in the
2225 * class closure (default handler) marshalers for the signal.
2227 return gtk_tree_row_reference_new_proxy (G_OBJECT (model), model, path);
2231 * gtk_tree_row_reference_new_proxy:
2232 * @proxy: a proxy #GObject
2233 * @model: a #GtkTreeModel
2234 * @path: a valid #GtkTreePath to monitor
2236 * You do not need to use this function.
2238 * Creates a row reference based on @path.
2240 * This reference will keep pointing to the node pointed to
2241 * by @path, so long as it exists. If @path isn't a valid
2242 * path in @model, then %NULL is returned. However, unlike
2243 * references created with gtk_tree_row_reference_new(), it
2244 * does not listen to the model for changes. The creator of
2245 * the row reference must do this explicitly using
2246 * gtk_tree_row_reference_inserted(), gtk_tree_row_reference_deleted(),
2247 * gtk_tree_row_reference_reordered().
2249 * These functions must be called exactly once per proxy when the
2250 * corresponding signal on the model is emitted. This single call
2251 * updates all row references for that proxy. Since built-in GTK+
2252 * objects like #GtkTreeView already use this mechanism internally,
2253 * using them as the proxy object will produce unpredictable results.
2254 * Further more, passing the same object as @model and @proxy
2255 * doesn't work for reasons of internal implementation.
2257 * This type of row reference is primarily meant by structures that
2258 * need to carefully monitor exactly when a row reference updates
2259 * itself, and is not generally needed by most applications.
2261 * Return value: a newly allocated #GtkTreeRowReference, or %NULL
2263 GtkTreeRowReference *
2264 gtk_tree_row_reference_new_proxy (GObject *proxy,
2265 GtkTreeModel *model,
2268 GtkTreeRowReference *reference;
2270 GtkTreeIter parent_iter;
2273 g_return_val_if_fail (G_IS_OBJECT (proxy), NULL);
2274 g_return_val_if_fail (GTK_IS_TREE_MODEL (model), NULL);
2275 g_return_val_if_fail (path != NULL, NULL);
2276 g_return_val_if_fail (path->depth > 0, NULL);
2278 /* check that the path is valid */
2279 if (gtk_tree_model_get_iter (model, &parent_iter, path) == FALSE)
2282 /* Now we want to ref every node */
2283 gtk_tree_model_iter_nth_child (model, &parent_iter, NULL, path->indices[0]);
2284 gtk_tree_model_ref_node (model, &parent_iter);
2286 for (i = 1; i < path->depth; i++)
2289 gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, path->indices[i]);
2290 gtk_tree_model_ref_node (model, &iter);
2294 /* Make the row reference */
2295 reference = g_new (GtkTreeRowReference, 1);
2297 g_object_ref (proxy);
2298 g_object_ref (model);
2299 reference->proxy = proxy;
2300 reference->model = model;
2301 reference->path = gtk_tree_path_copy (path);
2303 refs = g_object_get_data (G_OBJECT (proxy), ROW_REF_DATA_STRING);
2307 refs = g_new (RowRefList, 1);
2310 g_object_set_data_full (G_OBJECT (proxy),
2311 I_(ROW_REF_DATA_STRING),
2312 refs, release_row_references);
2315 refs->list = g_slist_prepend (refs->list, reference);
2321 * gtk_tree_row_reference_get_path:
2322 * @reference: a #GtkTreeRowReference
2324 * Returns a path that the row reference currently points to,
2325 * or %NULL if the path pointed to is no longer valid.
2327 * Return value: a current path, or %NULL
2330 gtk_tree_row_reference_get_path (GtkTreeRowReference *reference)
2332 g_return_val_if_fail (reference != NULL, NULL);
2334 if (reference->proxy == NULL)
2337 if (reference->path == NULL)
2340 return gtk_tree_path_copy (reference->path);
2344 * gtk_tree_row_reference_get_model:
2345 * @reference: a #GtkTreeRowReference
2347 * Returns the model that the row reference is monitoring.
2349 * Return value: (transfer none): the model
2354 gtk_tree_row_reference_get_model (GtkTreeRowReference *reference)
2356 g_return_val_if_fail (reference != NULL, NULL);
2358 return reference->model;
2362 * gtk_tree_row_reference_valid:
2363 * @reference: (allow-none): a #GtkTreeRowReference, or %NULL
2365 * Returns %TRUE if the @reference is non-%NULL and refers to
2366 * a current valid path.
2368 * Return value: %TRUE if @reference points to a valid path
2371 gtk_tree_row_reference_valid (GtkTreeRowReference *reference)
2373 if (reference == NULL || reference->path == NULL)
2381 * gtk_tree_row_reference_copy:
2382 * @reference: a #GtkTreeRowReference
2384 * Copies a #GtkTreeRowReference.
2386 * Return value: a copy of @reference
2390 GtkTreeRowReference *
2391 gtk_tree_row_reference_copy (GtkTreeRowReference *reference)
2393 return gtk_tree_row_reference_new_proxy (reference->proxy,
2399 * gtk_tree_row_reference_free:
2400 * @reference: (allow-none): a #GtkTreeRowReference, or %NULL
2402 * Free's @reference. @reference may be %NULL
2405 gtk_tree_row_reference_free (GtkTreeRowReference *reference)
2409 if (reference == NULL)
2412 refs = g_object_get_data (G_OBJECT (reference->proxy), ROW_REF_DATA_STRING);
2416 g_warning (G_STRLOC": bad row reference, proxy has no outstanding row references");
2420 refs->list = g_slist_remove (refs->list, reference);
2422 if (refs->list == NULL)
2424 g_object_set_data (G_OBJECT (reference->proxy),
2425 I_(ROW_REF_DATA_STRING),
2429 if (reference->path)
2431 gtk_tree_row_reference_unref_path (reference->path, reference->model, reference->path->depth);
2432 gtk_tree_path_free (reference->path);
2435 g_object_unref (reference->proxy);
2436 g_object_unref (reference->model);
2441 * gtk_tree_row_reference_inserted:
2442 * @proxy: a #GObject
2443 * @path: the row position that was inserted
2445 * Lets a set of row reference created by
2446 * gtk_tree_row_reference_new_proxy() know that the
2447 * model emitted the #GtkTreeModel::row-inserted signal.
2450 gtk_tree_row_reference_inserted (GObject *proxy,
2453 g_return_if_fail (G_IS_OBJECT (proxy));
2455 gtk_tree_row_ref_inserted ((RowRefList *)g_object_get_data (proxy, ROW_REF_DATA_STRING), path, NULL);
2459 * gtk_tree_row_reference_deleted:
2460 * @proxy: a #GObject
2461 * @path: the path position that was deleted
2463 * Lets a set of row reference created by
2464 * gtk_tree_row_reference_new_proxy() know that the
2465 * model emitted the #GtkTreeModel::row-deleted signal.
2468 gtk_tree_row_reference_deleted (GObject *proxy,
2471 g_return_if_fail (G_IS_OBJECT (proxy));
2473 gtk_tree_row_ref_deleted ((RowRefList *)g_object_get_data (proxy, ROW_REF_DATA_STRING), path);
2477 * gtk_tree_row_reference_reordered: (skip)
2478 * @proxy: a #GObject
2479 * @path: the parent path of the reordered signal
2480 * @iter: the iter pointing to the parent of the reordered
2481 * @new_order: the new order of rows
2483 * Lets a set of row reference created by
2484 * gtk_tree_row_reference_new_proxy() know that the
2485 * model emitted the #GtkTreeModel::rows-reordered signal.
2488 gtk_tree_row_reference_reordered (GObject *proxy,
2493 g_return_if_fail (G_IS_OBJECT (proxy));
2495 gtk_tree_row_ref_reordered ((RowRefList *)g_object_get_data (proxy, ROW_REF_DATA_STRING), path, iter, new_order);