gtktreemodel.c 71.5 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
/* gtktreemodel.c
 * 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
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

20
#include "config.h"
21 22
#include <stdlib.h>
#include <string.h>
23
#include <glib.h>
24
#include <glib/gprintf.h>
25
#include <gobject/gvaluecollector.h>
26
#include "gtktreemodel.h"
Jonathan Blandford's avatar
Jonathan Blandford committed
27 28
#include "gtktreeview.h"
#include "gtktreeprivate.h"
29
#include "gtkmarshalers.h"
Matthias Clasen's avatar
Matthias Clasen committed
30
#include "gtkintl.h"
Jonathan Blandford's avatar
Jonathan Blandford committed
31

32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200
/**
 * SECTION:gtktreemodel
 * @Title: GtkTreeModel
 * @Short_description: The tree interface used by GtkTreeView
 * @See_also: #GtkTreeView, #GtkTreeStore, #GtkListStore,
 *     <link linkend="gtk-GtkTreeView-drag-and-drop">GtkTreeDnd</link>,
 *     #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
 * &mdash; the #GtkTreeStore and the #GtkListStore. To use these, the
 * 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
 * column on that node. There are two structures used to reference
 * a particular node in a model. They are the #GtkTreePath and the
 * #GtkTreeIter<footnote><para>Here, <abbrev>iter</abbrev> is short
 * for <quote>iterator</quote></para></footnote>. Most of the interface
 * consists of operations on a #GtkTreeIter.
 *
 * 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
 * model. The #GtkTreePath struct can be converted into either an
 * 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
 * at that level. Thus, the path <quote>0</quote> refers to the root
 * node and the path <quote>2:4</quote> refers to the fifth child of
 * the third node.
 *
 * By contrast, a #GtkTreeIter is a reference to a specific node on
 * 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
 * is unchanged (and doesn't emit a signal). The model is considered
 * to own all outstanding iterators and nothing needs to be done to
 * free them from the user's point of view. Additionally, some models
 * 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
 * the location <quote>3:2:5</quote>. While the first method shown is
 * easier, the second is much more common, as you often get paths from
 * callbacks.
 *
 * <example>
 * <title>Acquiring a <structname>GtkTreeIter</structname></title>
 * <programlisting>
 *  /&ast; Three ways of getting the iter pointing to the location &ast;/
 * GtkTreePath *path;
 * GtkTreeIter iter;
 * GtkTreeIter parent_iter;
 *
 * /&ast; get the iterator from a string &ast;/
 * gtk_tree_model_get_iter_from_string (model, &amp;iter, "3:2:5");
 *
 * /&ast; get the iterator from a path &ast;/
 * path = gtk_tree_path_new_from_string ("3:2:5");
 * gtk_tree_model_get_iter (model, &amp;iter, path);
 * gtk_tree_path_free (path);
 *
 * /&ast; walk the tree to find the iterator &ast;/
 * gtk_tree_model_iter_nth_child (model, &amp;iter, NULL, 3);
 * parent_iter = iter;
 * gtk_tree_model_iter_nth_child (model, &amp;iter, &amp;parent_iter, 2);
 * parent_iter = iter;
 * gtk_tree_model_iter_nth_child (model, &amp;iter, &amp;parent_iter, 5);
 * </programlisting>
 * </example>
 *
 * This second example shows a quick way of iterating through a list
 * and getting a string and an integer from each row. The
 * <function>populate_model</function> function used below is not
 * shown, as it is specific to the #GtkListStore. For information on
 * how to write such a function, see the #GtkListStore documentation.
 *
 * <example>
 * <title>Reading data from a <structname>GtkTreeModel</structname></title>
 * <programlisting>
 * enum
 * {
 *   STRING_COLUMN,
 *   INT_COLUMN,
 *   N_COLUMNS
 * };
 *
 * ...
 *
 * GtkTreeModel *list_store;
 * GtkTreeIter iter;
 * gboolean valid;
 * gint row_count = 0;
 *
 * /&ast; make a new list_store &ast;/
 * list_store = gtk_list_store_new (N_COLUMNS, G_TYPE_STRING, G_TYPE_INT);
 *
 * /&ast; Fill the list store with data &ast;/
 * populate_model (list_store);
 *
 * /&ast; Get the first iter in the list &ast;/
 * valid = gtk_tree_model_get_iter_first (list_store, &amp;iter);
 *
 * while (valid)
 *  {
 *    /&ast; Walk through the list, reading each row &ast;/
 *    gchar *str_data;
 *    gint   int_data;
 *
 *    /&ast; Make sure you terminate calls to gtk_tree_model_get()
 *     &ast; with a '-1' value
 *     &ast;/
 *    gtk_tree_model_get (list_store, &amp;iter,
 *                        STRING_COLUMN, &amp;str_data,
 *                        INT_COLUMN, &amp;int_data,
 *                        -1);
 *
 *    /&ast; Do something with the data &ast;/
 *    g_print ("Row &percnt;d: (&percnt;s,&percnt;d)\n", row_count, str_data, int_data);
 *    g_free (str_data);
 *
 *    row_count++;
 *    valid = gtk_tree_model_iter_next (list_store, &amp;iter);
 *  }
 * </programlisting>
 * </example>
 *
 */
201

Daniel Elstner's avatar
Daniel Elstner committed
202 203 204 205 206 207 208 209
#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

210
#define ROW_REF_DATA_STRING "gtk-tree-row-refs"
Daniel Elstner's avatar
Daniel Elstner committed
211

212 213 214 215 216 217 218 219 220 221 222
enum {
  ROW_CHANGED,
  ROW_INSERTED,
  ROW_HAS_CHILD_TOGGLED,
  ROW_DELETED,
  ROWS_REORDERED,
  LAST_SIGNAL
};

static guint tree_model_signals[LAST_SIGNAL] = { 0 };

223 224 225 226 227 228
struct _GtkTreePath
{
  gint depth;
  gint *indices;
};

229 230 231 232
typedef struct
{
  GSList *list;
} RowRefList;
233

234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264
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);
265

Manish Singh's avatar
Manish Singh committed
266
GType
267 268
gtk_tree_model_get_type (void)
{
Manish Singh's avatar
Manish Singh committed
269
  static GType tree_model_type = 0;
270

271
  if (! tree_model_type)
272
    {
273
      const GTypeInfo tree_model_info =
274
      {
275
        sizeof (GtkTreeModelIface), /* class_size */
276 277 278 279 280 281 282 283
        gtk_tree_model_base_init,   /* base_init */
        NULL,           /* base_finalize */
        NULL,
        NULL,           /* class_finalize */
        NULL,           /* class_data */
        0,
        0,              /* n_preallocs */
        NULL
284 285
      };

Manish Singh's avatar
Manish Singh committed
286
      tree_model_type =
287 288
        g_type_register_static (G_TYPE_INTERFACE, I_("GtkTreeModel"),
                                &tree_model_info, 0);
Manish Singh's avatar
Manish Singh committed
289

290
      g_type_interface_add_prerequisite (tree_model_type, G_TYPE_OBJECT);
291 292 293 294 295
    }

  return tree_model_type;
}

296 297 298
static void
gtk_tree_model_base_init (gpointer g_class)
{
299
  static gboolean initialized = FALSE;
300
  GClosure *closure;
301

302
  if (! initialized)
303
    {
304 305 306 307
      GType row_inserted_params[2];
      GType row_deleted_params[1];
      GType rows_reordered_params[3];

308
      row_inserted_params[0] = GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE;
309 310
      row_inserted_params[1] = GTK_TYPE_TREE_ITER;

311
      row_deleted_params[0] = GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE;
312

313
      rows_reordered_params[0] = GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE;
314 315
      rows_reordered_params[1] = GTK_TYPE_TREE_ITER;
      rows_reordered_params[2] = G_TYPE_POINTER;
316

317 318 319 320 321 322
      /**
       * GtkTreeModel::row-changed:
       * @tree_model: the #GtkTreeModel on which the signal is emitted
       * @path: a #GtkTreePath identifying the changed row
       * @iter: a valid #GtkTreeIter pointing to the changed row
       *
323
       * This signal is emitted when a row in the model has changed.
324
       */
325
      tree_model_signals[ROW_CHANGED] =
326
        g_signal_new (I_("row-changed"),
327
                      GTK_TYPE_TREE_MODEL,
328
                      G_SIGNAL_RUN_LAST, 
329 330 331 332
                      G_STRUCT_OFFSET (GtkTreeModelIface, row_changed),
                      NULL, NULL,
                      _gtk_marshal_VOID__BOXED_BOXED,
                      G_TYPE_NONE, 2,
333
                      GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE,
334
                      GTK_TYPE_TREE_ITER);
335

336 337 338 339 340 341 342 343 344 345 346 347
      /* 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.
       */
348 349 350 351 352 353 354

      /**
       * GtkTreeModel::row-inserted:
       * @tree_model: the #GtkTreeModel on which the signal is emitted
       * @path: a #GtkTreePath identifying the new row
       * @iter: a valid #GtkTreeIter pointing to the new row
       *
355 356
       * This signal is emitted when a new row has been inserted in
       * the model.
357 358
       *
       * Note that the row may still be empty at this point, since
359
       * it is a common pattern to first insert an empty row, and
360 361
       * then fill it with the desired values.
       */
362 363
      closure = g_closure_new_simple (sizeof (GClosure), NULL);
      g_closure_set_marshal (closure, row_inserted_marshal);
364
      tree_model_signals[ROW_INSERTED] =
365
        g_signal_newv (I_("row-inserted"),
366 367 368 369 370 371 372 373
                       GTK_TYPE_TREE_MODEL,
                       G_SIGNAL_RUN_FIRST,
                       closure,
                       NULL, NULL,
                       _gtk_marshal_VOID__BOXED_BOXED,
                       G_TYPE_NONE, 2,
                       row_inserted_params);

374 375 376 377 378 379
      /**
       * GtkTreeModel::row-has-child-toggled:
       * @tree_model: the #GtkTreeModel on which the signal is emitted
       * @path: a #GtkTreePath identifying the row
       * @iter: a valid #GtkTreeIter pointing to the row
       *
380 381
       * This signal is emitted when a row has gotten the first child
       * row or lost its last child row.
382
       */
383
      tree_model_signals[ROW_HAS_CHILD_TOGGLED] =
384
        g_signal_new (I_("row-has-child-toggled"),
385 386 387 388 389 390
                      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,
391
                      GTK_TYPE_TREE_PATH | G_SIGNAL_TYPE_STATIC_SCOPE,
392
                      GTK_TYPE_TREE_ITER);
393

394 395 396 397 398
      /**
       * GtkTreeModel::row-deleted:
       * @tree_model: the #GtkTreeModel on which the signal is emitted
       * @path: a #GtkTreePath identifying the row
       *
399
       * This signal is emitted when a row has been deleted.
400 401 402
       *
       * Note that no iterator is passed to the signal handler,
       * since the row is already deleted.
403
       *
404 405 406
       * 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.
407
       */
408 409
      closure = g_closure_new_simple (sizeof (GClosure), NULL);
      g_closure_set_marshal (closure, row_deleted_marshal);
410
      tree_model_signals[ROW_DELETED] =
411
        g_signal_newv (I_("row-deleted"),
412 413 414 415 416 417 418 419
                       GTK_TYPE_TREE_MODEL,
                       G_SIGNAL_RUN_FIRST,
                       closure,
                       NULL, NULL,
                       _gtk_marshal_VOID__BOXED,
                       G_TYPE_NONE, 1,
                       row_deleted_params);

420
      /**
421
       * GtkTreeModel::rows-reordered: (skip)
422 423
       * @tree_model: the #GtkTreeModel on which the signal is emitted
       * @path: a #GtkTreePath identifying the tree node whose children
424 425 426 427 428
       *     have been reordered
       * @iter: a valid #GtkTreeIter pointing to the node whose
       * @new_order: an array of integers mapping the current position
       *     of each child to its old position before the re-ordering,
       *     i.e. @new_order<literal>[newpos] = oldpos</literal>
429
       *
430 431
       * This signal is emitted when the children of a node in the
       * #GtkTreeModel have been reordered.
432 433 434 435 436
       *
       * Note that this signal is <emphasis>not</emphasis> emitted
       * when rows are reordered by DND, since this is implemented
       * by removing and then reinserting the row.
       */
437 438
      closure = g_closure_new_simple (sizeof (GClosure), NULL);
      g_closure_set_marshal (closure, rows_reordered_marshal);
439
      tree_model_signals[ROWS_REORDERED] =
440
        g_signal_newv (I_("rows-reordered"),
441 442 443 444 445 446 447
                       GTK_TYPE_TREE_MODEL,
                       G_SIGNAL_RUN_FIRST,
                       closure,
                       NULL, NULL,
                       _gtk_marshal_VOID__BOXED_BOXED_POINTER,
                       G_TYPE_NONE, 3,
                       rows_reordered_params);
448
      initialized = TRUE;
449 450 451
    }
}

452 453 454 455 456 457 458 459 460
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;
461 462 463

  void (* row_inserted_callback) (GtkTreeModel *tree_model,
                                  GtkTreePath *path,
Matthias Clasen's avatar
Matthias Clasen committed
464
                                  GtkTreeIter *iter) = NULL;
465

466
  GObject *model = g_value_get_object (param_values + 0);
467 468
  GtkTreePath *path = (GtkTreePath *)g_value_get_boxed (param_values + 1);
  GtkTreeIter *iter = (GtkTreeIter *)g_value_get_boxed (param_values + 2);
469 470 471

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

474 475
  /* fetch the interface ->row_inserted implementation */
  iface = GTK_TREE_MODEL_GET_IFACE (model);
476
  row_inserted_callback = G_STRUCT_MEMBER (gpointer, iface,
477 478
                              G_STRUCT_OFFSET (GtkTreeModelIface,
                                               row_inserted));
479

480
  /* Call that default signal handler, it if has been set */
481 482
  if (row_inserted_callback)
    row_inserted_callback (GTK_TREE_MODEL (model), path, iter);
483 484 485 486 487 488 489 490 491 492 493
}

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;
494
  void (* row_deleted_callback) (GtkTreeModel *tree_model,
495
                                 GtkTreePath  *path) = NULL;
496
  GObject *model = g_value_get_object (param_values + 0);
497
  GtkTreePath *path = (GtkTreePath *)g_value_get_boxed (param_values + 1);
498 499 500

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

503
  /* fetch the interface ->row_deleted implementation */
504
  iface = GTK_TREE_MODEL_GET_IFACE (model);
505
  row_deleted_callback = G_STRUCT_MEMBER (gpointer, iface,
506 507
                              G_STRUCT_OFFSET (GtkTreeModelIface,
                                               row_deleted));
508

509 510 511
  /* Call that default signal handler, it if has been set */
  if (row_deleted_callback)
    row_deleted_callback (GTK_TREE_MODEL (model), path);
512 513 514 515 516 517 518 519 520 521 522
}

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;
523 524 525 526
  void (* rows_reordered_callback) (GtkTreeModel *tree_model,
                                    GtkTreePath  *path,
                                    GtkTreeIter  *iter,
                                    gint         *new_order);
527

528
  GObject *model = g_value_get_object (param_values + 0);
529 530 531
  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);
532

533 534
  /* first, we need to update internal row references */
  gtk_tree_row_ref_reordered ((RowRefList *)g_object_get_data (model, ROW_REF_DATA_STRING),
535
                              path, iter, new_order);
536

537
  /* fetch the interface ->rows_reordered implementation */
538
  iface = GTK_TREE_MODEL_GET_IFACE (model);
539
  rows_reordered_callback = G_STRUCT_MEMBER (gpointer, iface,
540 541
                              G_STRUCT_OFFSET (GtkTreeModelIface,
                                               rows_reordered));
542 543 544 545

  /* 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);
546 547
}

7's avatar
7 committed
548 549
/**
 * gtk_tree_path_new:
Jonathan Blandford's avatar
Jonathan Blandford committed
550
 *
551 552
 * Creates a new #GtkTreePath.
 * This structure refers to a row.
Jonathan Blandford's avatar
Jonathan Blandford committed
553
 *
7's avatar
7 committed
554
 * Return value: A newly created #GtkTreePath.
555
 */
556 557 558 559
GtkTreePath *
gtk_tree_path_new (void)
{
  GtkTreePath *retval;
Philip Van Hoof's avatar
Philip Van Hoof committed
560
  retval = g_slice_new (GtkTreePath);
561 562 563 564 565 566
  retval->depth = 0;
  retval->indices = NULL;

  return retval;
}

7's avatar
7 committed
567 568
/**
 * gtk_tree_path_new_from_string:
569 570 571
 * @path: The string representation of a path
 *
 * Creates a new #GtkTreePath initialized to @path.
Jonathan Blandford's avatar
Jonathan Blandford committed
572
 *
573 574 575 576 577
 * @path is expected to be a colon separated list of numbers.
 * For example, the string "10:4:0" would create a path of depth
 * 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.
Jonathan Blandford's avatar
Jonathan Blandford committed
578
 *
Matthias Clasen's avatar
Matthias Clasen committed
579
 * Return value: A newly-created #GtkTreePath, or %NULL
580
 */
581
GtkTreePath *
Tim Janik's avatar
Tim Janik committed
582
gtk_tree_path_new_from_string (const gchar *path)
583 584
{
  GtkTreePath *retval;
Tim Janik's avatar
Tim Janik committed
585
  const gchar *orig_path = path;
586 587 588
  gchar *ptr;
  gint i;

589 590
  g_return_val_if_fail (path != NULL, NULL);
  g_return_val_if_fail (*path != '\000', NULL);
591 592 593 594 595 596

  retval = gtk_tree_path_new ();

  while (1)
    {
      i = strtol (path, &ptr, 10);
597
      if (i < 0)
598 599 600 601 602
        {
          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;
        }
603 604 605

      gtk_tree_path_append_index (retval, i);

606
      if (*ptr == '\000')
607
        break;
608
      if (ptr == path || *ptr != ':')
609 610 611 612 613
        {
          g_warning (G_STRLOC ": Invalid path %s passed to gtk_tree_path_new_from_string", orig_path);
          gtk_tree_path_free (retval);
          return NULL;
        }
614 615 616 617 618 619
      path = ptr + 1;
    }

  return retval;
}

620 621
/**
 * gtk_tree_path_new_from_indices:
Matthias Clasen's avatar
Matthias Clasen committed
622 623
 * @first_index: first integer
 * @varargs: list of integers terminated by -1
624 625 626
 *
 * Creates a new path with @first_index and @varargs as indices.
 *
627
 * Return value: A newly created #GtkTreePath
Matthias Clasen's avatar
Matthias Clasen committed
628 629
 *
 * Since: 2.2
630
 */
631 632
GtkTreePath *
gtk_tree_path_new_from_indices (gint first_index,
633
                                ...)
634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654
{
  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;
}

7's avatar
7 committed
655 656 657
/**
 * gtk_tree_path_to_string:
 * @path: A #GtkTreePath
Jonathan Blandford's avatar
Jonathan Blandford committed
658
 *
659
 * Generates a string representation of the path.
Jonathan Blandford's avatar
Jonathan Blandford committed
660
 *
661 662 663 664 665 666 667
 * This string is a ':' separated list of numbers.
 * For example, "4:10:0:3" would be an acceptable
 * return value for this string.
 *
 * Return value: A newly-allocated string.
 *     Must be freed with g_free().
 */
668 669 670
gchar *
gtk_tree_path_to_string (GtkTreePath *path)
{
671 672
  gchar *retval, *ptr, *end;
  gint i, n;
673

674 675
  g_return_val_if_fail (path != NULL, NULL);

676 677 678
  if (path->depth == 0)
    return NULL;

679 680 681 682
  n = path->depth * 12;
  ptr = retval = g_new0 (gchar, n);
  end = ptr + n;
  g_snprintf (retval, end - ptr, "%d", path->indices[0]);
683
  while (*ptr != '\000')
684 685 686 687
    ptr++;

  for (i = 1; i < path->depth; i++)
    {
688
      g_snprintf (ptr, end - ptr, ":%d", path->indices[i]);
689
      while (*ptr != '\000')
690
        ptr++;
691 692 693 694 695
    }

  return retval;
}

7's avatar
7 committed
696
/**
697
 * gtk_tree_path_new_first:
Jonathan Blandford's avatar
Jonathan Blandford committed
698
 *
699
 * Creates a new #GtkTreePath.
Jonathan Blandford's avatar
Jonathan Blandford committed
700
 *
701 702 703 704
 * The string representation of this path is "0".
 *
 * Return value: A new #GtkTreePath
 */
705
GtkTreePath *
706
gtk_tree_path_new_first (void)
707 708 709 710 711 712 713 714 715
{
  GtkTreePath *retval;

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

  return retval;
}

7's avatar
7 committed
716 717
/**
 * gtk_tree_path_append_index:
718 719
 * @path: a #GtkTreePath
 * @index_: the index
Jonathan Blandford's avatar
Jonathan Blandford committed
720
 *
721 722 723 724
 * Appends a new index to a path.
 *
 * As a result, the depth of the path is increased.
 */
725 726
void
gtk_tree_path_append_index (GtkTreePath *path,
727
                            gint         index)
728
{
7's avatar
7 committed
729 730 731
  g_return_if_fail (path != NULL);
  g_return_if_fail (index >= 0);

732 733
  path->depth += 1;
  path->indices = g_realloc (path->indices, path->depth * sizeof(gint));
734 735 736
  path->indices[path->depth - 1] = index;
}

7's avatar
7 committed
737 738
/**
 * gtk_tree_path_prepend_index:
739 740 741 742
 * @path: a #GtkTreePath
 * @index_: the index
 *
 * Prepends a new index to a path.
Jonathan Blandford's avatar
Jonathan Blandford committed
743
 *
744 745
 * As a result, the depth of the path is increased.
 */
746 747
void
gtk_tree_path_prepend_index (GtkTreePath *path,
748
                             gint       index)
749
{
750 751 752 753 754
  gint *new_indices;

  (path->depth)++;
  new_indices = g_new (gint, path->depth);

755 756 757 758 759 760 761 762 763 764 765 766
  if (path->indices == NULL)
    {
      path->indices = new_indices;
      path->indices[0] = index;
      return;
    }
  memcpy (new_indices + 1, path->indices, (path->depth - 1)*sizeof (gint));
  g_free (path->indices);
  path->indices = new_indices;
  path->indices[0] = index;
}

7's avatar
7 committed
767 768
/**
 * gtk_tree_path_get_depth:
769
 * @path: a #GtkTreePath
Jonathan Blandford's avatar
Jonathan Blandford committed
770
 *
7's avatar
7 committed
771
 * Returns the current depth of @path.
Jonathan Blandford's avatar
Jonathan Blandford committed
772
 *
7's avatar
7 committed
773
 * Return value: The depth of @path
774
 */
775 776 777
gint
gtk_tree_path_get_depth (GtkTreePath *path)
{
7's avatar
7 committed
778 779
  g_return_val_if_fail (path != NULL, 0);

780 781 782
  return path->depth;
}

7's avatar
7 committed
783
/**
784
 * gtk_tree_path_get_indices: (skip)
785
 * @path: a #GtkTreePath
786
 *
787
 * Returns the current indices of @path.
788
 *
789 790 791 792 793
 * This is an array of integers, each representing a node in a tree.
 * This value should not be freed.
 *
 * Return value: The current indices, or %NULL
 */
794 795 796 797 798 799 800 801 802 803
gint *
gtk_tree_path_get_indices (GtkTreePath *path)
{
  g_return_val_if_fail (path != NULL, NULL);

  return path->indices;
}

/**
 * gtk_tree_path_get_indices_with_depth:
804 805 806
 * @path: a #GtkTreePath
 * @depth: (allow-none): return location for number of elements
 *     returned in the integer array, or %NULL
807 808
 *
 * Returns the current indices of @path.
809
 *
810 811 812 813
 * 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.
 *
814 815
 * Return value: (array length=depth) (transfer none): The current
 *     indices, or %NULL
816 817
 *
 * Since: 3.0
818 819
 *
 * Rename to: gtk_tree_path_get_indices
820
 */
821
gint *
822 823
gtk_tree_path_get_indices_with_depth (GtkTreePath *path,
                                      gint        *depth)
824 825 826 827 828 829 830 831 832
{
  g_return_val_if_fail (path != NULL, NULL);

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

  return path->indices;
}

7's avatar
7 committed
833 834
/**
 * gtk_tree_path_free:
835
 * @path: a #GtkTreePath
Jonathan Blandford's avatar
Jonathan Blandford committed
836
 *
7's avatar
7 committed
837
 * Frees @path.
838
 */
839 840 841
void
gtk_tree_path_free (GtkTreePath *path)
{
842 843
  if (!path)
    return;
844

845
  g_free (path->indices);
Philip Van Hoof's avatar
Philip Van Hoof committed
846
  g_slice_free (GtkTreePath, path);
847 848
}

7's avatar
7 committed
849 850
/**
 * gtk_tree_path_copy:
851
 * @path: a #GtkTreePath
Jonathan Blandford's avatar
Jonathan Blandford committed
852
 *
853
 * Creates a new #GtkTreePath as a copy of @path.
Jonathan Blandford's avatar
Jonathan Blandford committed
854
 *
855 856
 * Return value: a new #GtkTreePath
 */
857
GtkTreePath *
858
gtk_tree_path_copy (const GtkTreePath *path)
859 860 861
{
  GtkTreePath *retval;

862 863
  g_return_val_if_fail (path != NULL, NULL);

Philip Van Hoof's avatar
Philip Van Hoof committed
864
  retval = g_slice_new (GtkTreePath);
865 866 867 868 869 870
  retval->depth = path->depth;
  retval->indices = g_new (gint, path->depth);
  memcpy (retval->indices, path->indices, path->depth * sizeof (gint));
  return retval;
}

Christian Persch's avatar
Christian Persch committed
871 872 873
G_DEFINE_BOXED_TYPE (GtkTreePath, gtk_tree_path,
                     gtk_tree_path_copy,
                     gtk_tree_path_free)
874

7's avatar
7 committed
875 876
/**
 * gtk_tree_path_compare:
877 878 879 880
 * @a: a #GtkTreePath
 * @b: a #GtkTreePath to compare with
 *
 * Compares two paths.
Jonathan Blandford's avatar
Jonathan Blandford committed
881
 *
882 883 884
 * 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.
Jonathan Blandford's avatar
Jonathan Blandford committed
885
 *
886 887
 * Return value: the relative positions of @a and @b
 */
888
gint
7's avatar
7 committed
889
gtk_tree_path_compare (const GtkTreePath *a,
890
                       const GtkTreePath *b)
891 892 893 894 895 896 897 898 899 900 901
{
  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])
902
        continue;
903
      return (a->indices[p] < b->indices[q]?-1:1);
904 905 906 907
    }
  while (++p < a->depth && ++q < b->depth);
  if (a->depth == b->depth)
    return 0;
908
  return (a->depth < b->depth?-1:1);
909 910
}

911 912 913 914
/**
 * gtk_tree_path_is_ancestor:
 * @path: a #GtkTreePath
 * @descendant: another #GtkTreePath
Jonathan Blandford's avatar
Jonathan Blandford committed
915
 *
916
 * Returns %TRUE if @descendant is a descendant of @path.
Jonathan Blandford's avatar
Jonathan Blandford committed
917
 *
918
 * Return value: %TRUE if @descendant is contained inside @path
919
 */
920 921 922 923 924
gboolean
gtk_tree_path_is_ancestor (GtkTreePath *path,
                           GtkTreePath *descendant)
{
  gint i;
Jonathan Blandford's avatar
Jonathan Blandford committed
925

926 927 928 929 930 931
  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;
Jonathan Blandford's avatar
Jonathan Blandford committed
932

933 934 935 936 937 938 939 940 941 942 943 944 945 946 947
  i = 0;
  while (i < path->depth)
    {
      if (path->indices[i] != descendant->indices[i])
        return FALSE;
      ++i;
    }

  return TRUE;
}

/**
 * gtk_tree_path_is_descendant:
 * @path: a #GtkTreePath
 * @ancestor: another #GtkTreePath
Jonathan Blandford's avatar
Jonathan Blandford committed
948
 *
Matthias Clasen's avatar
Matthias Clasen committed
949
 * Returns %TRUE if @path is a descendant of @ancestor.
Jonathan Blandford's avatar
Jonathan Blandford committed
950
 *
951
 * Return value: %TRUE if @ancestor contains @path somewhere below it
952
 */
953 954 955 956 957
gboolean
gtk_tree_path_is_descendant (GtkTreePath *path,
                             GtkTreePath *ancestor)
{
  gint i;
Jonathan Blandford's avatar
Jonathan Blandford committed
958

959 960
  g_return_val_if_fail (path != NULL, FALSE);
  g_return_val_if_fail (ancestor != NULL, FALSE);
Jonathan Blandford's avatar
Jonathan Blandford committed
961

962 963 964
  /* can't be a descendant if we're shallower in the tree */
  if (path->depth <= ancestor->depth)
    return FALSE;
Jonathan Blandford's avatar
Jonathan Blandford committed
965

966 967 968 969 970 971 972 973 974 975 976 977
  i = 0;
  while (i < ancestor->depth)
    {
      if (path->indices[i] != ancestor->indices[i])
        return FALSE;
      ++i;
    }

  return TRUE;
}


7's avatar
7 committed
978 979
/**
 * gtk_tree_path_next:
980
 * @path: a #GtkTreePath
Jonathan Blandford's avatar
Jonathan Blandford committed
981
 *
7's avatar
7 committed
982
 * Moves the @path to point to the next node at the current depth.
983
 */
984 985 986 987
void
gtk_tree_path_next (GtkTreePath *path)
{
  g_return_if_fail (path != NULL);
7's avatar
7 committed
988
  g_return_if_fail (path->depth > 0);
989 990 991 992

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

7's avatar
7 committed
993 994
/**
 * gtk_tree_path_prev:
995
 * @path: a #GtkTreePath
Jonathan Blandford's avatar
Jonathan Blandford committed
996
 *
997 998
 * Moves the @path to point to the previous node at the
 * current depth, if it exists.
Jonathan Blandford's avatar
Jonathan Blandford committed
999
 *
1000 1001 1002
 * Return value: %TRUE if @path has a previous node, and
 *     the move was made
 */
1003
gboolean
1004 1005 1006 1007
gtk_tree_path_prev (GtkTreePath *path)
{
  g_return_val_if_fail (path != NULL, FALSE);

Matthias Clasen's avatar
Matthias Clasen committed
1008 1009 1010
  if (path->depth == 0)
    return FALSE;

1011
  if (path->indices[path->depth - 1] == 0)
1012 1013
    return FALSE;

1014
  path->indices[path->depth - 1] -= 1;
1015 1016 1017 1018

  return TRUE;
}

7's avatar
7 committed
1019 1020
/**
 * gtk_tree_path_up:
1021
 * @path: a #GtkTreePath
Jonathan Blandford's avatar
Jonathan Blandford committed
1022
 *
1023
 * Moves the @path to point to its parent node, if it has a parent.
Jonathan Blandford's avatar
Jonathan Blandford committed
1024
 *
1025 1026
 * Return value: %TRUE if @path has a parent, and the move was made
 */
1027
gboolean
1028 1029 1030 1031
gtk_tree_path_up (GtkTreePath *path)
{
  g_return_val_if_fail (path != NULL, FALSE);

1032
  if (path->depth == 0)
1033 1034 1035 1036 1037 1038 1039
    return FALSE;

  path->depth--;

  return TRUE;
}

7's avatar
7 committed
1040 1041
/**
 * gtk_tree_path_down:
1042
 * @path: a #GtkTreePath
Jonathan Blandford's avatar
Jonathan Blandford committed
1043
 *
7's avatar
7 committed
1044
 * Moves @path to point to the first child of the current path.
1045
 */
1046 1047 1048 1049 1050 1051 1052 1053
void
gtk_tree_path_down (GtkTreePath *path)
{
  g_return_if_fail (path != NULL);

  gtk_tree_path_append_index (path, 0);
}

1054 1055
/**
 * gtk_tree_iter_copy:
1056 1057 1058
 * @iter: a #GtkTreeIter
 *
 * Creates a dynamically allocated tree iterator as a copy of @iter.
Jonathan Blandford's avatar
Jonathan Blandford committed
1059
 *
1060 1061
 * This function is not intended for use in applications,
 * because you can just copy the structs by value
Matthias Clasen's avatar
Matthias Clasen committed
1062 1063
 * (<literal>GtkTreeIter new_iter = iter;</literal>).
 * You must free this iter with gtk_tree_iter_free().
Jonathan Blandford's avatar
Jonathan Blandford committed
1064
 *
1065 1066
 * Return value: a newly-allocated copy of @iter
 */
1067 1068 1069 1070 1071 1072 1073
GtkTreeIter *
gtk_tree_iter_copy (GtkTreeIter *iter)
{
  GtkTreeIter *retval;

  g_return_val_if_fail (iter != NULL, NULL);

1074
  retval = g_slice_new (GtkTreeIter);
1075 1076 1077 1078 1079 1080 1081
  *retval = *iter;

  return retval;
}

/**
 * gtk_tree_iter_free:
1082
 * @iter: a dynamically allocated tree iterator
Jonathan Blandford's avatar
Jonathan Blandford committed
1083
 *
Matthias Clasen's avatar
Matthias Clasen committed
1084
 * Frees an iterator that has been allocated by gtk_tree_iter_copy().
1085
 *
Matthias Clasen's avatar
Matthias Clasen committed
1086
 * This function is mainly used for language bindings.
1087
 */
1088 1089 1090 1091 1092
void
gtk_tree_iter_free (GtkTreeIter *iter)
{
  g_return_if_fail (iter != NULL);

1093
  g_slice_free (GtkTreeIter, iter);
1094 1095
}

Christian Persch's avatar
Christian Persch committed
1096 1097 1098
G_DEFINE_BOXED_TYPE (GtkTreeIter,  gtk_tree_iter,
                     gtk_tree_iter_copy,
                     gtk_tree_iter_free)
1099

1100 1101
/**
 * gtk_tree_model_get_flags:
1102 1103 1104
 * @tree_model: a #GtkTreeModel
 *
 * Returns a set of flags supported by this interface.
Jonathan Blandford's avatar
Jonathan Blandford committed
1105
 *
1106 1107 1108
 * The flags are a bitwise combination of #GtkTreeModelFlags.
 * The flags supported should not change during the lifetime
 * of the @tree_model.
Jonathan Blandford's avatar
Jonathan Blandford committed
1109
 *
1110 1111
 * Return value: the flags supported by this interface
 */
1112
GtkTreeModelFlags
1113 1114
gtk_tree_model_get_flags (GtkTreeModel *tree_model)
{
Matthias Clasen's avatar
Matthias Clasen committed
1115 1116
  GtkTreeModelIface *iface;

1117 1118
  g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), 0);

Matthias Clasen's avatar
Matthias Clasen committed
1119 1120 1121
  iface = GTK_TREE_MODEL_GET_IFACE (tree_model);
  if (iface->get_flags)
    return (* iface->get_flags) (tree_model);
1122 1123 1124 1125

  return 0;
}

7's avatar
7 committed
1126 1127
/**
 * gtk_tree_model_get_n_columns:
1128
 * @tree_model: a #GtkTreeModel
Jonathan Blandford's avatar
Jonathan Blandford committed
1129
 *
Matthias Clasen's avatar
Matthias Clasen committed
1130