gtktreemodel.c 76.5 KB
Newer Older
1
/* gtktreemodel.c
2 3 4 5 6 7 8 9 10 11 12 13 14
 * Copyright (C) 2000  Red Hat, Inc.,  Jonathan Blandford <jrb@redhat.com>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
Javier Jardón's avatar
Javier Jardón committed
15
 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
16 17
 */

18
#include "config.h"
19 20
#include <stdlib.h>
#include <string.h>
21
#include <glib.h>
22
#include <glib/gprintf.h>
23
#include <gobject/gvaluecollector.h>
24
#include "gtktreemodel.h"
25 26
#include "gtktreeview.h"
#include "gtktreeprivate.h"
27
#include "gtkmarshalers.h"
28
#include "gtkintl.h"
29

30 31 32 33 34
/**
 * SECTION:gtktreemodel
 * @Title: GtkTreeModel
 * @Short_description: The tree interface used by GtkTreeView
 * @See_also: #GtkTreeView, #GtkTreeStore, #GtkListStore,
35
 *     [GtkTreeView drag-and-drop][gtk3-GtkTreeView-drag-and-drop]
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55
 *     #GtkTreeSortable
 *
 * The #GtkTreeModel interface defines a generic tree interface for
 * use by the #GtkTreeView widget. It is an abstract interface, and
 * is designed to be usable with any appropriate data structure. The
 * programmer just has to implement this interface on their own data
 * type for it to be viewable by a #GtkTreeView widget.
 *
 * The model is represented as a hierarchical tree of strongly-typed,
 * columned data. In other words, the model can be seen as a tree where
 * every node has different values depending on which column is being
 * queried. The type of data found in a column is determined by using
 * the GType system (ie. #G_TYPE_INT, #GTK_TYPE_BUTTON, #G_TYPE_POINTER,
 * etc). The types are homogeneous per column across all nodes. It is
 * important to note that this interface only provides a way of examining
 * a model and observing changes. The implementation of each individual
 * model decides how and if changes are made.
 *
 * In order to make life simpler for programmers who do not need to
 * write their own specialized model, two generic models are provided
56
 * — the #GtkTreeStore and the #GtkListStore. To use these, the
57 58 59 60 61 62 63 64
 * developer simply pushes data into these models as necessary. These
 * models provide the data structure as well as all appropriate tree
 * interfaces. As a result, implementing drag and drop, sorting, and
 * storing data is trivial. For the vast majority of trees and lists,
 * these two models are sufficient.
 *
 * Models are accessed on a node/column level of granularity. One can
 * query for the value of a model at a certain node and a certain
65 66 67 68
 * column on that node. There are two structures used to reference a
 * particular node in a model. They are the #GtkTreePath-struct and
 * the #GtkTreeIter-struct (“iter” is short for iterator). Most of the
 * interface consists of operations on a #GtkTreeIter-struct.
69 70 71
 *
 * A path is essentially a potential node. It is a location on a model
 * that may or may not actually correspond to a node on a specific
72
 * model. The #GtkTreePath-struct can be converted into either an
73 74
 * array of unsigned integers or a string. The string form is a list
 * of numbers separated by a colon. Each number refers to the offset
75 76
 * at that level. Thus, the path `0` refers to the root
 * node and the path `2:4` refers to the fifth child of
77 78
 * the third node.
 *
79
 * By contrast, a #GtkTreeIter-struct is a reference to a specific node on
80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98
 * a specific model. It is a generic struct with an integer and three
 * generic pointers. These are filled in by the model in a model-specific
 * way. One can convert a path to an iterator by calling
 * gtk_tree_model_get_iter(). These iterators are the primary way
 * of accessing a model and are similar to the iterators used by
 * #GtkTextBuffer. They are generally statically allocated on the
 * stack and only used for a short time. The model interface defines
 * a set of operations using them for navigating the model.
 *
 * It is expected that models fill in the iterator with private data.
 * For example, the #GtkListStore model, which is internally a simple
 * linked list, stores a list node in one of the pointers. The
 * #GtkTreeModelSort stores an array and an offset in two of the
 * pointers. Additionally, there is an integer field. This field is
 * generally filled with a unique stamp per model. This stamp is for
 * catching errors resulting from using invalid iterators with a model.
 *
 * The lifecycle of an iterator can be a little confusing at first.
 * Iterators are expected to always be valid for as long as the model
99
 * is unchanged (and doesn’t emit a signal). The model is considered
100
 * to own all outstanding iterators and nothing needs to be done to
101
 * free them from the user’s point of view. Additionally, some models
102 103 104 105 106 107 108 109 110 111
 * guarantee that an iterator is valid for as long as the node it refers
 * to is valid (most notably the #GtkTreeStore and #GtkListStore).
 * Although generally uninteresting, as one always has to allow for
 * the case where iterators do not persist beyond a signal, some very
 * important performance enhancements were made in the sort model.
 * As a result, the #GTK_TREE_MODEL_ITERS_PERSIST flag was added to
 * indicate this behavior.
 *
 * To help show some common operation of a model, some examples are
 * provided. The first example shows three ways of getting the iter at
112
 * the location `3:2:5`. While the first method shown is
113 114 115
 * easier, the second is much more common, as you often get paths from
 * callbacks.
 *
116 117
 * ## Acquiring a #GtkTreeIter-struct
 *
118
 * |[<!-- language="C" -->
119
 * // Three ways of getting the iter pointing to the location
120 121 122 123
 * GtkTreePath *path;
 * GtkTreeIter iter;
 * GtkTreeIter parent_iter;
 *
124
 * // get the iterator from a string
125 126 127
 * gtk_tree_model_get_iter_from_string (model,
 *                                      &iter,
 *                                      "3:2:5");
128
 *
129
 * // get the iterator from a path
130
 * path = gtk_tree_path_new_from_string ("3:2:5");
131
 * gtk_tree_model_get_iter (model, &iter, path);
132 133
 * gtk_tree_path_free (path);
 *
134
 * // walk the tree to find the iterator
135 136
 * gtk_tree_model_iter_nth_child (model, &iter,
 *                                NULL, 3);
137
 * parent_iter = iter;
138 139
 * gtk_tree_model_iter_nth_child (model, &iter,
 *                                &parent_iter, 2);
140
 * parent_iter = iter;
141 142
 * gtk_tree_model_iter_nth_child (model, &iter,
 *                                &parent_iter, 5);
143
 * ]|
144 145 146
 *
 * This second example shows a quick way of iterating through a list
 * and getting a string and an integer from each row. The
147
 * populate_model() function used below is not
148 149 150
 * shown, as it is specific to the #GtkListStore. For information on
 * how to write such a function, see the #GtkListStore documentation.
 *
151 152
 * ## Reading data from a #GtkTreeModel
 *
153
 * |[<!-- language="C" -->
154 155 156 157 158 159 160 161 162 163 164 165 166 167
 * enum
 * {
 *   STRING_COLUMN,
 *   INT_COLUMN,
 *   N_COLUMNS
 * };
 *
 * ...
 *
 * GtkTreeModel *list_store;
 * GtkTreeIter iter;
 * gboolean valid;
 * gint row_count = 0;
 *
168
 * // make a new list_store
169 170 171
 * list_store = gtk_list_store_new (N_COLUMNS,
 *                                  G_TYPE_STRING,
 *                                  G_TYPE_INT);
172
 *
173
 * // Fill the list store with data
174 175
 * populate_model (list_store);
 *
176 177
 * // Get the first iter in the list, check it is valid and walk
 * // through the list, reading each row.
178 179 180 181
 *
 * valid = gtk_tree_model_get_iter_first (list_store,
 *                                        &iter);
 * while (valid)
182 183 184 185
 *  {
 *    gchar *str_data;
 *    gint   int_data;
 *
186
 *    // Make sure you terminate calls to gtk_tree_model_get() with a “-1” value
187 188 189
 *    gtk_tree_model_get (list_store, &iter,
 *                        STRING_COLUMN, &str_data,
 *                        INT_COLUMN, &int_data,
190 191
 *                        -1);
 *
192
 *    // Do something with the data
193 194
 *    g_print ("Row %d: (%s,%d)\n",
 *             row_count, str_data, int_data);
195 196
 *    g_free (str_data);
 *
197 198
 *    valid = gtk_tree_model_iter_next (list_store,
 *                                      &iter);
199 200
 *    row_count++;
 *  }
201
 * ]|
202
 *
203 204 205 206 207 208 209 210 211 212 213 214 215 216 217
 * The #GtkTreeModel interface contains two methods for reference
 * counting: gtk_tree_model_ref_node() and gtk_tree_model_unref_node().
 * These two methods are optional to implement. The reference counting
 * is meant as a way for views to let models know when nodes are being
 * displayed. #GtkTreeView will take a reference on a node when it is
 * visible, which means the node is either in the toplevel or expanded.
 * Being displayed does not mean that the node is currently directly
 * visible to the user in the viewport. Based on this reference counting
 * scheme a caching model, for example, can decide whether or not to cache
 * a node based on the reference count. A file-system based model would
 * not want to keep the entire file hierarchy in memory, but just the
 * folders that are currently expanded in every current view.
 *
 * When working with reference counting, the following rules must be taken
 * into account:
218 219 220 221 222 223 224 225 226 227 228 229 230 231
 *
 * - Never take a reference on a node without owning a reference on its parent.
 *   This means that all parent nodes of a referenced node must be referenced
 *   as well.
 *
 * - Outstanding references on a deleted node are not released. This is not
 *   possible because the node has already been deleted by the time the
 *   row-deleted signal is received.
 *
 * - Models are not obligated to emit a signal on rows of which none of its
 *   siblings are referenced. To phrase this differently, signals are only
 *   required for levels in which nodes are referenced. For the root level
 *   however, signals must be emitted at all times (however the root level
 *   is always referenced when any view is attached).
232
 */
233

Daniel Elstner's avatar
Daniel Elstner committed
234 235 236 237 238 239 240 241
#define INITIALIZE_TREE_ITER(Iter) \
    G_STMT_START{ \
      (Iter)->stamp = 0; \
      (Iter)->user_data  = NULL; \
      (Iter)->user_data2 = NULL; \
      (Iter)->user_data3 = NULL; \
    }G_STMT_END

242
#define ROW_REF_DATA_STRING "gtk-tree-row-refs"
Daniel Elstner's avatar
Daniel Elstner committed
243

244 245 246 247 248 249 250 251 252 253 254
enum {
  ROW_CHANGED,
  ROW_INSERTED,
  ROW_HAS_CHILD_TOGGLED,
  ROW_DELETED,
  ROWS_REORDERED,
  LAST_SIGNAL
};

static guint tree_model_signals[LAST_SIGNAL] = { 0 };

255 256
struct _GtkTreePath
{
257 258
  gint depth;    /* Number of elements */
  gint alloc;    /* Number of allocated elements */
259 260 261
  gint *indices;
};

262 263 264 265
typedef struct
{
  GSList *list;
} RowRefList;
266

267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297
static void      gtk_tree_model_base_init   (gpointer           g_class);

/* custom closures */
static void      row_inserted_marshal       (GClosure          *closure,
                                             GValue /* out */  *return_value,
                                             guint              n_param_value,
                                             const GValue      *param_values,
                                             gpointer           invocation_hint,
                                             gpointer           marshal_data);
static void      row_deleted_marshal        (GClosure          *closure,
                                             GValue /* out */  *return_value,
                                             guint              n_param_value,
                                             const GValue      *param_values,
                                             gpointer           invocation_hint,
                                             gpointer           marshal_data);
static void      rows_reordered_marshal     (GClosure          *closure,
                                             GValue /* out */  *return_value,
                                             guint              n_param_value,
                                             const GValue      *param_values,
                                             gpointer           invocation_hint,
                                             gpointer           marshal_data);

static void      gtk_tree_row_ref_inserted  (RowRefList        *refs,
                                             GtkTreePath       *path,
                                             GtkTreeIter       *iter);
static void      gtk_tree_row_ref_deleted   (RowRefList        *refs,
                                             GtkTreePath       *path);
static void      gtk_tree_row_ref_reordered (RowRefList        *refs,
                                             GtkTreePath       *path,
                                             GtkTreeIter       *iter,
                                             gint              *new_order);
298

Manish Singh's avatar
Manish Singh committed
299
GType
300 301
gtk_tree_model_get_type (void)
{
Manish Singh's avatar
Manish Singh committed
302
  static GType tree_model_type = 0;
303

304
  if (! tree_model_type)
305
    {
306
      const GTypeInfo tree_model_info =
307
      {
308
        sizeof (GtkTreeModelIface), /* class_size */
309 310 311 312 313 314 315 316
        gtk_tree_model_base_init,   /* base_init */
        NULL,           /* base_finalize */
        NULL,
        NULL,           /* class_finalize */
        NULL,           /* class_data */
        0,
        0,              /* n_preallocs */
        NULL
317 318
      };

Manish Singh's avatar
Manish Singh committed
319
      tree_model_type =
320 321
        g_type_register_static (G_TYPE_INTERFACE, I_("GtkTreeModel"),
                                &tree_model_info, 0);
Manish Singh's avatar
Manish Singh committed
322

323
      g_type_interface_add_prerequisite (tree_model_type, G_TYPE_OBJECT);
324 325 326 327 328
    }

  return tree_model_type;
}

329 330 331
static void
gtk_tree_model_base_init (gpointer g_class)
{
332
  static gboolean initialized = FALSE;
333
  GClosure *closure;
334

335
  if (! initialized)
336
    {
337 338 339 340
      GType row_inserted_params[2];
      GType row_deleted_params[1];
      GType rows_reordered_params[3];

341
      row_inserted_params[0] = GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE;
342 343
      row_inserted_params[1] = GTK_TYPE_TREE_ITER;

344
      row_deleted_params[0] = GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE;
345

346
      rows_reordered_params[0] = GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE;
347 348
      rows_reordered_params[1] = GTK_TYPE_TREE_ITER;
      rows_reordered_params[2] = G_TYPE_POINTER;
349

350 351 352
      /**
       * GtkTreeModel::row-changed:
       * @tree_model: the #GtkTreeModel on which the signal is emitted
353 354
       * @path: a #GtkTreePath-struct identifying the changed row
       * @iter: a valid #GtkTreeIter-struct pointing to the changed row
355
       *
356
       * This signal is emitted when a row in the model has changed.
357
       */
358
      tree_model_signals[ROW_CHANGED] =
359
        g_signal_new (I_("row-changed"),
360
                      GTK_TYPE_TREE_MODEL,
361
                      G_SIGNAL_RUN_LAST, 
362 363 364 365
                      G_STRUCT_OFFSET (GtkTreeModelIface, row_changed),
                      NULL, NULL,
                      _gtk_marshal_VOID__BOXED_BOXED,
                      G_TYPE_NONE, 2,
366
                      GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE,
367
                      GTK_TYPE_TREE_ITER);
368

369 370 371 372 373 374 375 376 377 378 379 380
      /* We need to get notification about structure changes
       * to update row references., so instead of using the
       * standard g_signal_new() with an offset into our interface
       * structure, we use a customs closures for the class
       * closures (default handlers) that first update row references
       * and then calls the function from the interface structure.
       *
       * The reason we don't simply update the row references from
       * the wrapper functions (gtk_tree_model_row_inserted(), etc.)
       * is to keep proper ordering with respect to signal handlers
       * connected normally and after.
       */
381 382 383 384

      /**
       * GtkTreeModel::row-inserted:
       * @tree_model: the #GtkTreeModel on which the signal is emitted
385 386
       * @path: a #GtkTreePath-struct identifying the new row
       * @iter: a valid #GtkTreeIter-struct pointing to the new row
387
       *
388 389
       * This signal is emitted when a new row has been inserted in
       * the model.
390 391
       *
       * Note that the row may still be empty at this point, since
392
       * it is a common pattern to first insert an empty row, and
393 394
       * then fill it with the desired values.
       */
395 396
      closure = g_closure_new_simple (sizeof (GClosure), NULL);
      g_closure_set_marshal (closure, row_inserted_marshal);
397
      tree_model_signals[ROW_INSERTED] =
398
        g_signal_newv (I_("row-inserted"),
399 400 401 402 403 404 405 406
                       GTK_TYPE_TREE_MODEL,
                       G_SIGNAL_RUN_FIRST,
                       closure,
                       NULL, NULL,
                       _gtk_marshal_VOID__BOXED_BOXED,
                       G_TYPE_NONE, 2,
                       row_inserted_params);

407 408 409
      /**
       * GtkTreeModel::row-has-child-toggled:
       * @tree_model: the #GtkTreeModel on which the signal is emitted
410 411
       * @path: a #GtkTreePath-struct identifying the row
       * @iter: a valid #GtkTreeIter-struct pointing to the row
412
       *
413 414
       * This signal is emitted when a row has gotten the first child
       * row or lost its last child row.
415
       */
416
      tree_model_signals[ROW_HAS_CHILD_TOGGLED] =
417
        g_signal_new (I_("row-has-child-toggled"),
418 419 420 421 422 423
                      GTK_TYPE_TREE_MODEL,
                      G_SIGNAL_RUN_LAST,
                      G_STRUCT_OFFSET (GtkTreeModelIface, row_has_child_toggled),
                      NULL, NULL,
                      _gtk_marshal_VOID__BOXED_BOXED,
                      G_TYPE_NONE, 2,
424
                      GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE,
425
                      GTK_TYPE_TREE_ITER);
426

427 428 429
      /**
       * GtkTreeModel::row-deleted:
       * @tree_model: the #GtkTreeModel on which the signal is emitted
430
       * @path: a #GtkTreePath-struct identifying the row
431
       *
432
       * This signal is emitted when a row has been deleted.
433 434 435
       *
       * Note that no iterator is passed to the signal handler,
       * since the row is already deleted.
436
       *
437 438 439
       * This should be called by models after a row has been removed.
       * The location pointed to by @path should be the location that
       * the row previously was at. It may not be a valid location anymore.
440
       */
441 442
      closure = g_closure_new_simple (sizeof (GClosure), NULL);
      g_closure_set_marshal (closure, row_deleted_marshal);
443
      tree_model_signals[ROW_DELETED] =
444
        g_signal_newv (I_("row-deleted"),
445 446 447 448
                       GTK_TYPE_TREE_MODEL,
                       G_SIGNAL_RUN_FIRST,
                       closure,
                       NULL, NULL,
449
                       NULL,
450 451 452
                       G_TYPE_NONE, 1,
                       row_deleted_params);

453
      /**
454
       * GtkTreeModel::rows-reordered: (skip)
455
       * @tree_model: the #GtkTreeModel on which the signal is emitted
456
       * @path: a #GtkTreePath-struct identifying the tree node whose children
457
       *     have been reordered
458
       * @iter: a valid #GtkTreeIter-struct pointing to the node whose children
459
       *     have been reordered, or %NULL if the depth of @path is 0
460 461
       * @new_order: an array of integers mapping the current position
       *     of each child to its old position before the re-ordering,
462
       *     i.e. @new_order`[newpos] = oldpos`
463
       *
464 465
       * This signal is emitted when the children of a node in the
       * #GtkTreeModel have been reordered.
466
       *
467
       * Note that this signal is not emitted
468 469 470
       * when rows are reordered by DND, since this is implemented
       * by removing and then reinserting the row.
       */
471 472
      closure = g_closure_new_simple (sizeof (GClosure), NULL);
      g_closure_set_marshal (closure, rows_reordered_marshal);
473
      tree_model_signals[ROWS_REORDERED] =
474
        g_signal_newv (I_("rows-reordered"),
475 476 477 478 479 480 481
                       GTK_TYPE_TREE_MODEL,
                       G_SIGNAL_RUN_FIRST,
                       closure,
                       NULL, NULL,
                       _gtk_marshal_VOID__BOXED_BOXED_POINTER,
                       G_TYPE_NONE, 3,
                       rows_reordered_params);
482
      initialized = TRUE;
483 484 485
    }
}

486 487 488 489 490 491 492 493 494
static void
row_inserted_marshal (GClosure          *closure,
                      GValue /* out */  *return_value,
                      guint              n_param_values,
                      const GValue      *param_values,
                      gpointer           invocation_hint,
                      gpointer           marshal_data)
{
  GtkTreeModelIface *iface;
495 496 497

  void (* row_inserted_callback) (GtkTreeModel *tree_model,
                                  GtkTreePath *path,
498
                                  GtkTreeIter *iter) = NULL;
499

500
  GObject *model = g_value_get_object (param_values + 0);
501 502
  GtkTreePath *path = (GtkTreePath *)g_value_get_boxed (param_values + 1);
  GtkTreeIter *iter = (GtkTreeIter *)g_value_get_boxed (param_values + 2);
503 504 505

  /* first, we need to update internal row references */
  gtk_tree_row_ref_inserted ((RowRefList *)g_object_get_data (model, ROW_REF_DATA_STRING),
506
                             path, iter);
507

508 509
  /* fetch the interface ->row_inserted implementation */
  iface = GTK_TREE_MODEL_GET_IFACE (model);
510
  row_inserted_callback = G_STRUCT_MEMBER (gpointer, iface,
511 512
                              G_STRUCT_OFFSET (GtkTreeModelIface,
                                               row_inserted));
513

514
  /* Call that default signal handler, it if has been set */
515 516
  if (row_inserted_callback)
    row_inserted_callback (GTK_TREE_MODEL (model), path, iter);
517 518 519 520 521 522 523 524 525 526 527
}

static void
row_deleted_marshal (GClosure          *closure,
                     GValue /* out */  *return_value,
                     guint              n_param_values,
                     const GValue      *param_values,
                     gpointer           invocation_hint,
                     gpointer           marshal_data)
{
  GtkTreeModelIface *iface;
528
  void (* row_deleted_callback) (GtkTreeModel *tree_model,
529
                                 GtkTreePath  *path) = NULL;
530
  GObject *model = g_value_get_object (param_values + 0);
531
  GtkTreePath *path = (GtkTreePath *)g_value_get_boxed (param_values + 1);
532 533 534

  /* first, we need to update internal row references */
  gtk_tree_row_ref_deleted ((RowRefList *)g_object_get_data (model, ROW_REF_DATA_STRING),
535
                            path);
536

537
  /* fetch the interface ->row_deleted implementation */
538
  iface = GTK_TREE_MODEL_GET_IFACE (model);
539
  row_deleted_callback = G_STRUCT_MEMBER (gpointer, iface,
540 541
                              G_STRUCT_OFFSET (GtkTreeModelIface,
                                               row_deleted));
542

543 544 545
  /* Call that default signal handler, it if has been set */
  if (row_deleted_callback)
    row_deleted_callback (GTK_TREE_MODEL (model), path);
546 547 548 549 550 551 552 553 554 555 556
}

static void
rows_reordered_marshal (GClosure          *closure,
                        GValue /* out */  *return_value,
                        guint              n_param_values,
                        const GValue      *param_values,
                        gpointer           invocation_hint,
                        gpointer           marshal_data)
{
  GtkTreeModelIface *iface;
557 558 559 560
  void (* rows_reordered_callback) (GtkTreeModel *tree_model,
                                    GtkTreePath  *path,
                                    GtkTreeIter  *iter,
                                    gint         *new_order);
561

562
  GObject *model = g_value_get_object (param_values + 0);
563 564 565
  GtkTreePath *path = (GtkTreePath *)g_value_get_boxed (param_values + 1);
  GtkTreeIter *iter = (GtkTreeIter *)g_value_get_boxed (param_values + 2);
  gint *new_order = (gint *)g_value_get_pointer (param_values + 3);
566

567 568
  /* first, we need to update internal row references */
  gtk_tree_row_ref_reordered ((RowRefList *)g_object_get_data (model, ROW_REF_DATA_STRING),
569
                              path, iter, new_order);
570

571
  /* fetch the interface ->rows_reordered implementation */
572
  iface = GTK_TREE_MODEL_GET_IFACE (model);
573
  rows_reordered_callback = G_STRUCT_MEMBER (gpointer, iface,
574 575
                              G_STRUCT_OFFSET (GtkTreeModelIface,
                                               rows_reordered));
576 577 578 579

  /* Call that default signal handler, it if has been set */
  if (rows_reordered_callback)
    rows_reordered_callback (GTK_TREE_MODEL (model), path, iter, new_order);
580 581
}

7's avatar
7 committed
582 583
/**
 * gtk_tree_path_new:
584
 *
585 586
 * Creates a new #GtkTreePath-struct.
 * This refers to a row.
587
 *
588
 * Returns: A newly created #GtkTreePath-struct.
589
 */
590 591 592 593
GtkTreePath *
gtk_tree_path_new (void)
{
  GtkTreePath *retval;
594
  retval = g_slice_new (GtkTreePath);
595
  retval->depth = 0;
596
  retval->alloc = 0;
597 598 599 600 601
  retval->indices = NULL;

  return retval;
}

7's avatar
7 committed
602 603
/**
 * gtk_tree_path_new_from_string:
604 605
 * @path: The string representation of a path
 *
606
 * Creates a new #GtkTreePath-struct initialized to @path.
607
 *
608
 * @path is expected to be a colon separated list of numbers.
609
 * For example, the string “10:4:0” would create a path of depth
610 611 612
 * 3 pointing to the 11th child of the root node, the 5th
 * child of that 11th child, and the 1st child of that 5th child.
 * If an invalid path string is passed in, %NULL is returned.
613
 *
614
 * Returns: A newly-created #GtkTreePath-struct, or %NULL
615
 */
616
GtkTreePath *
617
gtk_tree_path_new_from_string (const gchar *path)
618 619
{
  GtkTreePath *retval;
620
  const gchar *orig_path = path;
621 622 623
  gchar *ptr;
  gint i;

624 625
  g_return_val_if_fail (path != NULL, NULL);
  g_return_val_if_fail (*path != '\000', NULL);
626 627 628 629 630 631

  retval = gtk_tree_path_new ();

  while (1)
    {
      i = strtol (path, &ptr, 10);
632
      if (i < 0)
633 634 635 636 637
        {
          g_warning (G_STRLOC ": Negative numbers in path %s passed to gtk_tree_path_new_from_string", orig_path);
          gtk_tree_path_free (retval);
          return NULL;
        }
638 639 640

      gtk_tree_path_append_index (retval, i);

641
      if (*ptr == '\000')
642
        break;
643
      if (ptr == path || *ptr != ':')
644 645 646 647 648
        {
          g_warning (G_STRLOC ": Invalid path %s passed to gtk_tree_path_new_from_string", orig_path);
          gtk_tree_path_free (retval);
          return NULL;
        }
649 650 651 652 653 654
      path = ptr + 1;
    }

  return retval;
}

655 656
/**
 * gtk_tree_path_new_from_indices:
Matthias Clasen's avatar
Matthias Clasen committed
657
 * @first_index: first integer
Matthias Clasen's avatar
Matthias Clasen committed
658
 * @...: list of integers terminated by -1
659 660 661
 *
 * Creates a new path with @first_index and @varargs as indices.
 *
662
 * Returns: A newly created #GtkTreePath-struct
663 664
 *
 * Since: 2.2
665
 */
666 667
GtkTreePath *
gtk_tree_path_new_from_indices (gint first_index,
668
                                ...)
669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689
{
  int arg;
  va_list args;
  GtkTreePath *path;

  path = gtk_tree_path_new ();

  va_start (args, first_index);
  arg = first_index;

  while (arg != -1)
    {
      gtk_tree_path_append_index (path, arg);
      arg = va_arg (args, gint);
    }

  va_end (args);

  return path;
}

690 691 692 693 694 695 696
/**
 * gtk_tree_path_new_from_indicesv: (rename-to gtk_tree_path_new_from_indices)
 * @indices: (array length=length): array of indices
 * @length: length of @indices array
 *
 * Creates a new path with the given @indices array of @length.
 *
697
 * Returns: A newly created #GtkTreePath-struct
698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717
 *
 * Since: 3.12
 */
GtkTreePath *
gtk_tree_path_new_from_indicesv (gint *indices,
                                 gsize length)
{
  GtkTreePath *path;

  g_return_val_if_fail (indices != NULL && length != 0, NULL);

  path = gtk_tree_path_new ();
  path->alloc = length;
  path->depth = length;
  path->indices = g_new (gint, length);
  memcpy (path->indices, indices, length * sizeof (gint));

  return path;
}

7's avatar
7 committed
718 719
/**
 * gtk_tree_path_to_string:
720
 * @path: A #GtkTreePath-struct
721
 *
722
 * Generates a string representation of the path.
723
 *
724
 * This string is a “:” separated list of numbers.
725
 * For example, “4:10:0:3” would be an acceptable
726 727
 * return value for this string.
 *
728
 * Returns: A newly-allocated string.
729 730
 *     Must be freed with g_free().
 */
731 732 733
gchar *
gtk_tree_path_to_string (GtkTreePath *path)
{
734 735
  gchar *retval, *ptr, *end;
  gint i, n;
736

737 738
  g_return_val_if_fail (path != NULL, NULL);

739 740 741
  if (path->depth == 0)
    return NULL;

742 743 744 745
  n = path->depth * 12;
  ptr = retval = g_new0 (gchar, n);
  end = ptr + n;
  g_snprintf (retval, end - ptr, "%d", path->indices[0]);
746
  while (*ptr != '\000')
747 748 749 750
    ptr++;

  for (i = 1; i < path->depth; i++)
    {
751
      g_snprintf (ptr, end - ptr, ":%d", path->indices[i]);
752
      while (*ptr != '\000')
753
        ptr++;
754 755 756 757 758
    }

  return retval;
}

7's avatar
7 committed
759
/**
760
 * gtk_tree_path_new_first:
761
 *
762
 * Creates a new #GtkTreePath-struct.
763
 *
764
 * The string representation of this path is “0”.
765
 *
766
 * Returns: A new #GtkTreePath-struct
767
 */
768
GtkTreePath *
769
gtk_tree_path_new_first (void)
770 771 772 773 774 775 776 777 778
{
  GtkTreePath *retval;

  retval = gtk_tree_path_new ();
  gtk_tree_path_append_index (retval, 0);

  return retval;
}

7's avatar
7 committed
779 780
/**
 * gtk_tree_path_append_index:
781
 * @path: a #GtkTreePath-struct
782
 * @index_: the index
783
 *
784 785 786 787
 * Appends a new index to a path.
 *
 * As a result, the depth of the path is increased.
 */
788 789
void
gtk_tree_path_append_index (GtkTreePath *path,
790
                            gint         index_)
791
{
7's avatar
7 committed
792
  g_return_if_fail (path != NULL);
793 794 795 796 797 798 799 800 801 802 803
  g_return_if_fail (index_ >= 0);

  if (path->depth == path->alloc)
    {
      gint *indices;
      path->alloc = MAX (path->alloc * 2, 1);
      indices = g_new (gint, path->alloc);
      memcpy (indices, path->indices, path->depth * sizeof (gint));
      g_free (path->indices);
      path->indices = indices;
    }
7's avatar
7 committed
804

805
  path->depth += 1;
806
  path->indices[path->depth - 1] = index_;
807 808
}

7's avatar
7 committed
809 810
/**
 * gtk_tree_path_prepend_index:
811
 * @path: a #GtkTreePath-struct
812 813 814
 * @index_: the index
 *
 * Prepends a new index to a path.
815
 *
816 817
 * As a result, the depth of the path is increased.
 */
818 819
void
gtk_tree_path_prepend_index (GtkTreePath *path,
820
                             gint       index)
821
{
822
  if (path->depth == path->alloc)
823
    {
824 825 826 827 828 829
      gint *indices;
      path->alloc = MAX (path->alloc * 2, 1);
      indices = g_new (gint, path->alloc);
      memcpy (indices + 1, path->indices, path->depth * sizeof (gint));
      g_free (path->indices);
      path->indices = indices;
830
    }
831 832 833 834
  else if (path->depth > 0)
    memmove (path->indices + 1, path->indices, path->depth * sizeof (gint));

  path->depth += 1;
835 836 837
  path->indices[0] = index;
}

7's avatar
7 committed
838 839
/**
 * gtk_tree_path_get_depth:
840
 * @path: a #GtkTreePath-struct
841
 *
7's avatar
7 committed
842
 * Returns the current depth of @path.
843
 *
844
 * Returns: The depth of @path
845
 */
846 847 848
gint
gtk_tree_path_get_depth (GtkTreePath *path)
{
7's avatar
7 committed
849 850
  g_return_val_if_fail (path != NULL, 0);

851 852 853
  return path->depth;
}

7's avatar
7 committed
854
/**
855
 * gtk_tree_path_get_indices: (skip)
856
 * @path: a #GtkTreePath-struct
857
 *
858
 * Returns the current indices of @path.
859
 *
860 861 862
 * This is an array of integers, each representing a node in a tree.
 * This value should not be freed.
 *
863 864
 * The length of the array can be obtained with gtk_tree_path_get_depth().
 *
865
 * Returns: The current indices, or %NULL
866
 */
867 868 869 870 871 872 873 874 875
gint *
gtk_tree_path_get_indices (GtkTreePath *path)
{
  g_return_val_if_fail (path != NULL, NULL);

  return path->indices;
}

/**
Jasper St. Pierre's avatar
Jasper St. Pierre committed
876
 * gtk_tree_path_get_indices_with_depth: (rename-to gtk_tree_path_get_indices)
877
 * @path: a #GtkTreePath-struct
878
 * @depth: (out) (allow-none): return location for number of elements
879
 *     returned in the integer array, or %NULL
880 881
 *
 * Returns the current indices of @path.
882
 *
883 884 885 886
 * This is an array of integers, each representing a node in a tree.
 * It also returns the number of elements in the array.
 * The array should not be freed.
 *
887
 * Returns: (array length=depth) (transfer none): The current
888
 *     indices, or %NULL
889 890
 *
 * Since: 3.0
891
 */
892
gint *
893 894
gtk_tree_path_get_indices_with_depth (GtkTreePath *path,
                                      gint        *depth)
895 896 897 898 899 900 901 902 903
{
  g_return_val_if_fail (path != NULL, NULL);

  if (depth)
    *depth = path->depth;

  return path->indices;
}

7's avatar
7 committed
904 905
/**
 * gtk_tree_path_free:
906
 * @path: (allow-none): a #GtkTreePath-struct
907
 *
908
 * Frees @path. If @path is %NULL, it simply returns.
909
 */
910 911 912
void
gtk_tree_path_free (GtkTreePath *path)
{
913 914
  if (!path)
    return;
915

916
  g_free (path->indices);
917
  g_slice_free (GtkTreePath, path);
918 919
}

7's avatar
7 committed
920 921
/**
 * gtk_tree_path_copy:
922
 * @path: a #GtkTreePath-struct
923
 *
924
 * Creates a new #GtkTreePath-struct as a copy of @path.
925
 *
926
 * Returns: a new #GtkTreePath-struct
927
 */
928
GtkTreePath *
929
gtk_tree_path_copy (const GtkTreePath *path)
930 931 932
{
  GtkTreePath *retval;

933 934
  g_return_val_if_fail (path != NULL, NULL);

935
  retval = g_slice_new (GtkTreePath);
936
  retval->depth = path->depth;
937 938
  retval->alloc = retval->depth;
  retval->indices = g_new (gint, path->alloc);
939 940 941 942
  memcpy (retval->indices, path->indices, path->depth * sizeof (gint));
  return retval;
}

943 944 945
G_DEFINE_BOXED_TYPE (GtkTreePath, gtk_tree_path,
                     gtk_tree_path_copy,
                     gtk_tree_path_free)
946

7's avatar
7 committed
947 948
/**
 * gtk_tree_path_compare:
949 950
 * @a: a #GtkTreePath-struct
 * @b: a #GtkTreePath-struct to compare with
951 952
 *
 * Compares two paths.
953
 *
954 955 956
 * If @a appears before @b in a tree, then -1 is returned.
 * If @b appears before @a, then 1 is returned.
 * If the two nodes are equal, then 0 is returned.
957
 *
958
 * Returns: the relative positions of @a and @b
959
 */
960
gint
7's avatar
7 committed
961
gtk_tree_path_compare (const GtkTreePath *a,
962
                       const GtkTreePath *b)
963 964 965 966 967 968 969 970 971 972 973
{
  gint p = 0, q = 0;

  g_return_val_if_fail (a != NULL, 0);
  g_return_val_if_fail (b != NULL, 0);
  g_return_val_if_fail (a->depth > 0, 0);
  g_return_val_if_fail (b->depth > 0, 0);

  do
    {
      if (a->indices[p] == b->indices[q])
974
        continue;
975
      return (a->indices[p] < b->indices[q]?-1:1);
976 977 978 979
    }
  while (++p < a->depth && ++q < b->depth);
  if (a->depth == b->depth)
    return 0;
980
  return (a->depth < b->depth?-1:1);
981 982
}

983 984
/**
 * gtk_tree_path_is_ancestor:
985 986
 * @path: a #GtkTreePath-struct
 * @descendant: another #GtkTreePath-struct
987
 *
988
 * Returns %TRUE if @descendant is a descendant of @path.
989
 *
990
 * Returns: %TRUE if @descendant is contained inside @path
991
 */
992 993 994 995 996
gboolean
gtk_tree_path_is_ancestor (GtkTreePath *path,
                           GtkTreePath *descendant)
{
  gint i;
997

998 999 1000 1001 1002 1003
  g_return_val_if_fail (path != NULL, FALSE);
  g_return_val_if_fail (descendant != NULL, FALSE);

  /* can't be an ancestor if we're deeper */
  if (path->depth >= descendant->depth)
    return FALSE;
1004

1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017
  i = 0;
  while (i < path->depth)
    {
      if (path->indices[i] != descendant->indices[i])
        return FALSE;
      ++i;
    }

  return TRUE;
}

/**
 * gtk_tree_path_is_descendant:
1018 1019
 * @path: a #GtkTreePath-struct
 * @ancestor: another #GtkTreePath-struct
1020
 *
Matthias Clasen's avatar
Matthias Clasen committed
1021
 * Returns %TRUE if @path is a descendant of @ancestor.
1022
 *
1023
 * Returns: %TRUE if @ancestor contains @path somewhere below it
1024
 */
1025 1026 1027 1028 1029
gboolean
gtk_tree_path_is_descendant (GtkTreePath *path,
                             GtkTreePath *ancestor)
{
  gint i;
1030

1031 1032
  g_return_val_if_fail (path != NULL, FALSE);
  g_return_val_if_fail (ancestor != NULL, FALSE);
1033

1034 1035 1036
  /* can't be a descendant if we're shallower in the tree */
  if (path->depth <= ancestor->depth)
    return FALSE;
1037

1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049
  i = 0;
  while (i < ancestor->depth)
    {
      if (path->indices[i] != ancestor->indices[i])
        return FALSE;
      ++i;
    }

  return TRUE;
}


7's avatar
7 committed
1050 1051
/**
 * gtk_tree_path_next:
1052
 * @path: a #GtkTreePath-struct
1053
 *
7's avatar
7 committed
1054
 * Moves the @path to point to the next node at the current depth.
1055
 */
1056 1057 1058 1059
void
gtk_tree_path_next (GtkTreePath *path)
{
  g_return_if_fail (path != NULL);
7's avatar
7 committed
1060
  g_return_if_fail (path->depth > 0);
1061 1062 1063 1064

  path->indices[path->depth - 1] ++;
}

7's avatar
7 committed
1065 1066
/**
 * gtk_tree_path_prev:
1067
 * @path: a #GtkTreePath-struct
1068
 *
1069 1070
 * Moves the @path to point to the previous node at the
 * current depth, if it exists.
1071
 *
1072
 * Returns: %TRUE if @path has a previous node, and
1073 1074
 *     the move was made
 */
1075
gboolean
1076 1077 1078 1079
gtk_tree_path_prev (GtkTreePath *path)
{
  g_return_val_if_fail (path != NULL, FALSE);

1080 1081 1082
  if (path->depth == 0)
    return FALSE;

1083
  if (path->indices[path->depth - 1] == 0)
1084 1085
    return FALSE;

1086
  path->indices[path->depth - 1] -= 1;
1087 1088 1089 1090

  return TRUE;
}

7's avatar
7 committed
1091 1092
/**
 * gtk_tree_path_up:
1093
 * @path: a #GtkTreePath-struct
1094
 *
1095
 * Moves the @path to point to its parent node, if it has a parent.
1096
 *
1097
 * Returns: %TRUE if @path has a parent, and the move was made
1098
 */
1099
gboolean
1100 1101 1102 1103
gtk_tree_path_up (GtkTreePath *path)
{
  g_return_val_if_fail (path != NULL, FALSE);

1104
  if (path->depth == 0)
1105 1106 1107 1108 1109 1110 1111
    return FALSE;

  path->depth--;

  return TRUE;
}

7's avatar
7 committed
1112 1113
/**
 * gtk_tree_path_down:
1114
 * @path: a #GtkTreePath-struct
1115
 *
7's avatar
7 committed
1116
 * Moves @path to point to the first child of the current path.
1117
 */
1118 1119 1120 1121 1122 1123 1124 1125
void
gtk_tree_path_down (GtkTreePath *path)
{
  g_return_if_fail (path != NULL);

  gtk_tree_path_append_index (path, 0);
}

1126 1127
/**
 * gtk_tree_iter_copy:
1128
 * @iter: a #GtkTreeIter-struct
1129 1130
 *
 * Creates a dynamically allocated tree iterator as a copy of @iter.
1131
 *
1132 1133
 * This function is not intended for use in applications,
 * because you can just copy the structs by value
1134
 * (`GtkTreeIter new_iter = iter;`).
Matthias Clasen's avatar
Matthias Clasen committed
1135
 * You must free this iter with gtk_tree_iter_free().
1136
 *
1137
 * Returns: a newly-allocated copy of @iter
1138
 */
1139 1140 1141 1142 1143 1144 1145
GtkTreeIter *
gtk_tree_iter_copy (GtkTreeIter *iter)
{
  GtkTreeIter *retval;

  g_return_val_if_fail (iter != NULL, NULL);

1146
  retval = g_slice_new (GtkTreeIter);
1147 1148 1149 1150 1151 1152 1153
  *retval = *iter;

  return retval;
}

/**
 * gtk_tree_iter_free:
1154
 * @iter: a dynamically allocated tree iterator
1155
 *
Matthias Clasen's avatar
Matthias Clasen committed
1156
 * Frees an iterator that has been allocated by gtk_tree_iter_copy().
1157
 *
Matthias Clasen's avatar
Matthias Clasen committed
1158
 * This function is mainly used for language bindings.
1159
 */
1160 1161 1162 1163 1164
void
gtk_tree_iter_free (GtkTreeIter *iter)
{
  g_return_if_fail (iter != NULL);

1165
  g_slice_free (GtkTreeIter, iter);
1166 1167
}

1168 1169 1170
G_DEFINE_BOXED_TYPE (GtkTreeIter,  gtk_tree_iter,
                     gtk_tree_iter_copy,
                     gtk_tree_iter_free)
1171

1172 1173
/**
 * gtk_tree_model_get_flags:
1174 1175 1176
 * @tree_model: a #GtkTreeModel
 *
 * Returns a set of flags supported by this interface.
1177
 *
1178 1179 1180
 * The flags are a bitwise combination of #GtkTreeModelFlags.
 * The flags supported should not change during the lifetime
 * of the @tree_model.
1181
 *
1182
 * Returns: the flags supported by this interface
1183
 */
1184
GtkTreeModelFlags
1185 1186
gtk_tree_model_get_flags (GtkTreeModel *tree_model)
{
Matthias Clasen's avatar
Matthias Clasen committed
1187 1188
  GtkTreeModelIface *iface;

1189 1190
  g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), 0);

Matthias Clasen's avatar
Matthias Clasen committed
1191 1192 1193
  iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
  if (iface->get_flags)
    return (* iface->get_flags) (tree_model);
1194 1195 1196 1197

  return 0;
}

7's avatar
7 committed
1198 1199
/**
 * gtk_tree_model_get_n_columns:
1200
 * @tree_model: a #GtkTreeModel
1201
 *
Matthias Clasen's avatar
Matthias Clasen committed
1202
 * Returns the number of columns supported by @tree_model.
1203
 *
1204
 * Returns: the number of columns
1205
 */
1206 1207 1208
gint
gtk_tree_model_get_n_columns (GtkTreeModel *tree_model)
{
Matthias Clasen's avatar
Matthias Clasen committed
1209
  GtkTreeModelIface *iface;
1210
  g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), 0);
1211

Matthias Clasen's avatar
Matthias Clasen committed
1212 1213 1214 1215
  iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
  g_return_val_if_fail (iface->get_n_columns != NULL, 0);

  return (* iface->get_n_columns) (tree_model);
1216 1217
}

1218 1219
/**
 * gtk_tree_model_get_column_type:
1220 1221
 * @tree_model: a #GtkTreeModel
 * @index_: the column index
1222
 *
1223
 * Returns the type of the column.
1224
 *
1225
 * Returns: the type of the column
1226
 */
1227 1228
GType
gtk_tree_model_get_column_type (GtkTreeModel *tree_model,
1229
                                gint          index)
1230
{
Matthias Clasen's avatar
Matthias Clasen committed
1231 1232
  GtkTreeModelIface *iface;

1233
  g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), G_TYPE_INVALID);
Matthias Clasen's avatar
Matthias Clasen committed
1234 1235 1236

  iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
  g_return_val_if_fail (iface->get_column_type != NULL, G_TYPE_INVALID);
1237 1238
  g_return_val_if_fail (index >= 0, G_TYPE_INVALID);

Matthias Clasen's avatar
Matthias Clasen committed
1239
  return (* iface->get_column_type) (tree_model, index);
1240 1241
}

7's avatar
7 committed
1242
/**
1243
 * gtk_tree_model_get_iter:
1244
 * @tree_model: a #GtkTreeModel
1245 1246
 * @iter: (out): the uninitialized #GtkTreeIter-struct
 * @path: the #GtkTreePath-struct
1247
 *
1248
 * Sets @iter to a valid iterator pointing to @path.  If @path does
1249
 * not exist, @iter is set to an invalid iterator and %FALSE is returned.
1250
 *
1251
 * Returns: %TRUE, if @iter was set
1252
 */
1253 1254
gboolean
gtk_tree_model_get_iter (GtkTreeModel *tree_model,
1255 1256
                         GtkTreeIter  *iter,
                         GtkTreePath  *path)
1257
{
Matthias Clasen's avatar
Matthias Clasen committed
1258 1259
  GtkTreeModelIface *iface;

1260
  g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
1261 1262
  g_return_val_if_fail (iter != NULL, FALSE);
  g_return_val_if_fail (path != NULL, FALSE);
Matthias Clasen's avatar
Matthias Clasen committed
1263 1264 1265

  iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
  g_return_val_if_fail (iface->get_iter != NULL, FALSE);
1266
  g_return_val_if_fail (path->depth > 0, FALSE);
1267

Daniel Elstner's avatar
Daniel Elstner committed
1268 1269
  INITIALIZE_TREE_ITER (iter);

Matthias Clasen's avatar
Matthias Clasen committed
1270
  return (* iface->get_iter) (tree_model, iter, path);
1271 1272
}

1273 1274
/**
 * gtk_tree_model_get_iter_from_string:
1275
 * @tree_model: a #GtkTreeModel
1276 1277
 * @iter: (out): an uninitialized #GtkTreeIter-struct
 * @path_string: a string representation of a #GtkTreePath-struct