Pileus Git - ~andy/gtk/blob - gtk/gtktreemodel.c

   1 /* gtktreemodel.c
   2  * Copyright (C) 2000  Red Hat, Inc.,  Jonathan Blandford <jrb@redhat.com>
   3  *
   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.
   8  *
   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.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 #include <stdlib.h>
  21 #include <stdio.h>
  22 #include <string.h>
  23 #include "gtktreemodel.h"
  24
  25 struct _GtkTreePath
  26 {
  27   gint depth;
  28   gint *indices;
  29 };
  30
  31 GtkType
  32 gtk_tree_model_get_type (void)
  33 {
  34   static GtkType tree_model_type = 0;
  35
  36   if (!tree_model_type)
  37     {
  38       static const GTypeInfo tree_model_info =
  39       {
  40         sizeof (GtkTreeModelIface), /* class_size */
  41         NULL,           /* base_init */
  42         NULL,           /* base_finalize */
  43         NULL,
  44         NULL,           /* class_finalize */
  45         NULL,           /* class_data */
  46         0,
  47         0,              /* n_preallocs */
  48         NULL
  49       };
  50
  51       tree_model_type = g_type_register_static (G_TYPE_INTERFACE, "GtkTreeModel", &tree_model_info, 0);
  52     }
  53
  54   return tree_model_type;
  55 }
  56
  57 /**
  58  * gtk_tree_path_new:
  59  *
  60  * Creates a new #GtkTreePath.
  61  *
  62  * Return value: A newly created #GtkTreePath.
  63  **/
  64 /* GtkTreePath Operations */
  65 GtkTreePath *
  66 gtk_tree_path_new (void)
  67 {
  68   GtkTreePath *retval;
  69   retval = (GtkTreePath *) g_new (GtkTreePath, 1);
  70   retval->depth = 0;
  71   retval->indices = NULL;
  72
  73   return retval;
  74 }
  75
  76 /**
  77  * gtk_tree_path_new_from_string:
  78  * @path: The string representation of a path.
  79  *
  80  * Creates a new #GtkTreePath initialized to @path.  @path is expected
  81  * to be a colon separated list of numbers.  For example, the string
  82  * "10:4:0" would create a path of depth 3 pointing to the 11th child
  83  * of the root node, the 5th child of that 11th child, and the 1st
  84  * child of that 5th child.
  85  *
  86  * Return value: A newly created #GtkTreePath.
  87  **/
  88 GtkTreePath *
  89 gtk_tree_path_new_from_string (gchar *path)
  90 {
  91   GtkTreePath *retval;
  92   gchar *ptr;
  93   gint i;
  94
  95   g_return_val_if_fail (path != NULL, gtk_tree_path_new ());
  96
  97   retval = gtk_tree_path_new ();
  98
  99   while (1)
 100     {
 101       i = strtol (path, &ptr, 10);
 102       gtk_tree_path_append_index (retval, i);
 103
 104       if (*ptr == '\000')
 105         break;
 106       /* FIXME: should we error out if this is not a ':', or should we be tolerant? */
 107       path = ptr + 1;
 108     }
 109
 110   return retval;
 111 }
 112
 113 /**
 114  * gtk_tree_path_to_string:
 115  * @path: A #GtkTreePath
 116  *
 117  * Generates a string representation of the path.  This string is a ':'
 118  * separated list of numbers.  For example, "4:10:0:3" would be an acceptable return value for this string.
 119  *
 120  * Return value: A newly allocated string.  Must be freed with #g_free.
 121  **/
 122 gchar *
 123 gtk_tree_path_to_string (GtkTreePath *path)
 124 {
 125   gchar *retval, *ptr;
 126   gint i;
 127
 128   if (path->depth == 0)
 129     return NULL;
 130
 131   ptr = retval = (gchar *) g_new0 (char *, path->depth*8);
 132   sprintf (retval, "%d", path->indices[0]);
 133   while (*ptr != '\000')
 134     ptr++;
 135
 136   for (i = 1; i < path->depth; i++)
 137     {
 138       sprintf (ptr, ":%d", path->indices[i]);
 139       while (*ptr != '\000')
 140         ptr++;
 141     }
 142
 143   return retval;
 144 }
 145
 146 /**
 147  * gtk_tree_path_new_root:
 148  *
 149  * Creates a new root #GtkTreePath.  The string representation of this path is
 150  * "0"
 151  *
 152  * Return value: A new #GtkTreePath.
 153  **/
 154 GtkTreePath *
 155 gtk_tree_path_new_root (void)
 156 {
 157   GtkTreePath *retval;
 158
 159   retval = gtk_tree_path_new ();
 160   gtk_tree_path_append_index (retval, 0);
 161
 162   return retval;
 163 }
 164
 165 /**
 166  * gtk_tree_path_append_index:
 167  * @path: A #GtkTreePath.
 168  * @index: The index.
 169  *
 170  * Appends a new index to a path.  As a result, the depth of the path is
 171  * increased.
 172  **/
 173 void
 174 gtk_tree_path_append_index (GtkTreePath *path,
 175                             gint         index)
 176 {
 177   gint *new_indices;
 178
 179   g_return_if_fail (path != NULL);
 180   g_return_if_fail (index >= 0);
 181
 182   new_indices = g_new (gint, ++path->depth);
 183   if (path->indices == NULL)
 184     {
 185       path->indices = new_indices;
 186       path->indices[0] = index;
 187       return;
 188     }
 189
 190   memcpy (new_indices, path->indices, (path->depth - 1)*sizeof (gint));
 191   g_free (path->indices);
 192   path->indices = new_indices;
 193   path->indices[path->depth - 1] = index;
 194 }
 195
 196 /**
 197  * gtk_tree_path_prepend_index:
 198  * @path: A #GtkTreePath.
 199  * @index: The index.
 200  *
 201  * Prepends a new index to a path.  As a result, the depth of the path is
 202  * increased.
 203  **/
 204 void
 205 gtk_tree_path_prepend_index (GtkTreePath *path,
 206                              gint       index)
 207 {
 208   gint *new_indices = g_new (gint, ++path->depth);
 209   if (path->indices == NULL)
 210     {
 211       path->indices = new_indices;
 212       path->indices[0] = index;
 213       return;
 214     }
 215   memcpy (new_indices + 1, path->indices, (path->depth - 1)*sizeof (gint));
 216   g_free (path->indices);
 217   path->indices = new_indices;
 218   path->indices[0] = index;
 219 }
 220
 221 /**
 222  * gtk_tree_path_get_depth:
 223  * @path: A #GtkTreePath.
 224  *
 225  * Returns the current depth of @path.
 226  *
 227  * Return value: The depth of @path
 228  **/
 229 gint
 230 gtk_tree_path_get_depth (GtkTreePath *path)
 231 {
 232   g_return_val_if_fail (path != NULL, 0);
 233
 234   return path->depth;
 235 }
 236
 237 /**
 238  * gtk_tree_path_get_indices:
 239  * @path: A #GtkTreePath.
 240  *
 241  * Returns the current indices of @path.  This is an array of integers, each
 242  * representing a node in a tree.
 243  *
 244  * Return value: The current indices, or NULL.
 245  **/
 246 gint *
 247 gtk_tree_path_get_indices (GtkTreePath *path)
 248 {
 249   g_return_val_if_fail (path != NULL, NULL);
 250
 251   return path->indices;
 252 }
 253
 254 /**
 255  * gtk_tree_path_free:
 256  * @path: A #GtkTreePath.
 257  *
 258  * Frees @path.
 259  **/
 260 void
 261 gtk_tree_path_free (GtkTreePath *path)
 262 {
 263   g_return_if_fail (path != NULL);
 264
 265   g_free (path->indices);
 266   g_free (path);
 267 }
 268
 269 /**
 270  * gtk_tree_path_copy:
 271  * @path: A #GtkTreePath.
 272  *
 273  * Creates a new #GtkTreePath as a copy of @path.
 274  *
 275  * Return value: A new #GtkTreePath.
 276  **/
 277 GtkTreePath *
 278 gtk_tree_path_copy (GtkTreePath *path)
 279 {
 280   GtkTreePath *retval;
 281
 282   g_return_val_if_fail (path != NULL, NULL);
 283
 284   retval = g_new (GtkTreePath, 1);
 285   retval->depth = path->depth;
 286   retval->indices = g_new (gint, path->depth);
 287   memcpy (retval->indices, path->indices, path->depth * sizeof (gint));
 288   return retval;
 289 }
 290
 291 /**
 292  * gtk_tree_path_compare:
 293  * @a: A #GtkTreePath.
 294  * @b: A #GtkTreePath to compare with.
 295  *
 296  * Compares two paths.  If @a appears before @b in a tree, then 1, is returned.
 297  * If @b appears before @a, then -1 is returned.  If the two nodes are equal,
 298  * then 0 is returned.
 299  *
 300  * Return value: The relative positions of @a and @b
 301  **/
 302 gint
 303 gtk_tree_path_compare (const GtkTreePath *a,
 304                        const GtkTreePath *b)
 305 {
 306   gint p = 0, q = 0;
 307
 308   g_return_val_if_fail (a != NULL, 0);
 309   g_return_val_if_fail (b != NULL, 0);
 310   g_return_val_if_fail (a->depth > 0, 0);
 311   g_return_val_if_fail (b->depth > 0, 0);
 312
 313   do
 314     {
 315       if (a->indices[p] == b->indices[q])
 316         continue;
 317       return (a->indices[p] < b->indices[q]?1:-1);
 318     }
 319   while (++p < a->depth && ++q < b->depth);
 320   if (a->depth == b->depth)
 321     return 0;
 322   return (a->depth < b->depth?1:-1);
 323 }
 324
 325 /**
 326  * gtk_tree_path_next:
 327  * @path: A #GtkTreePath.
 328  *
 329  * Moves the @path to point to the next node at the current depth.
 330  **/
 331 void
 332 gtk_tree_path_next (GtkTreePath *path)
 333 {
 334   g_return_if_fail (path != NULL);
 335   g_return_if_fail (path->depth > 0);
 336
 337   path->indices[path->depth - 1] ++;
 338 }
 339
 340 /**
 341  * gtk_tree_path_prev:
 342  * @path: A #GtkTreePath.
 343  *
 344  * Moves the @path to point to the previous node at the current depth, if it exists.
 345  *
 346  * Return value: TRUE if @path has a previous node, and the move was made.
 347  **/
 348 gboolean
 349 gtk_tree_path_prev (GtkTreePath *path)
 350 {
 351   g_return_val_if_fail (path != NULL, FALSE);
 352
 353   if (path->indices[path->depth] == 0)
 354     return FALSE;
 355
 356   path->indices[path->depth - 1] --;
 357
 358   return TRUE;
 359 }
 360
 361 /**
 362  * gtk_tree_path_up:
 363  * @path: A #GtkTreePath.
 364  *
 365  * Moves the @path to point to it's parent node, if it has a parent.
 366  *
 367  * Return value: TRUE if @path has a parent, and the move was made.
 368  **/
 369 gboolean
 370 gtk_tree_path_up (GtkTreePath *path)
 371 {
 372   g_return_val_if_fail (path != NULL, FALSE);
 373
 374   if (path->depth == 1)
 375     return FALSE;
 376
 377   path->depth--;
 378
 379   return TRUE;
 380 }
 381
 382 /**
 383  * gtk_tree_path_down:
 384  * @path: A #GtkTreePath.
 385  *
 386  * Moves @path to point to the first child of the current path.
 387  **/
 388 void
 389 gtk_tree_path_down (GtkTreePath *path)
 390 {
 391   g_return_if_fail (path != NULL);
 392
 393   gtk_tree_path_append_index (path, 0);
 394 }
 395
 396
 397 /**
 398  * gtk_tree_iter_copy:
 399  * @iter: A #GtkTreeIter.
 400  *
 401  * Creates a dynamically allocated tree iterator as a copy of @iter.  This
 402  * function is not intended for use in applications, because you can just copy
 403  * the structs by value (GtkTreeIter new_iter = iter;).  You
 404  * must free this iter with gtk_tree_iter_free ().
 405  *
 406  * Return value: a newly allocated copy of @iter.
 407  **/
 408 GtkTreeIter *
 409 gtk_tree_iter_copy (GtkTreeIter *iter)
 410 {
 411   GtkTreeIter *retval;
 412
 413   g_return_val_if_fail (iter != NULL, NULL);
 414
 415   retval = g_new (GtkTreeIter, 1);
 416   *retval = *iter;
 417
 418   return retval;
 419 }
 420
 421 /**
 422  * gtk_tree_iter_free:
 423  * @iter: A dynamically allocated tree iterator.
 424  *
 425  * Free an iterator that has been allocated on the heap.  This function is
 426  * mainly used for language bindings.
 427  **/
 428 void
 429 gtk_tree_iter_free (GtkTreeIter *iter)
 430 {
 431   g_return_if_fail (iter != NULL);
 432
 433   g_free (iter);
 434
 435 }
 436
 437 /**
 438  * gtk_tree_model_get_flags:
 439  * @tree_model: A #GtkTreeModel.
 440  *
 441  * Returns a set of flags supported by this interface.  The flags are a bitwise
 442  * combination of #GtkTreeModelFlags.  It is expected that the flags supported
 443  * do not change for an interface.
 444  *
 445  * Return value: The flags supported by this interface.
 446  **/
 447 GtkTreeModelFlags
 448 gtk_tree_model_get_flags (GtkTreeModel *tree_model)
 449 {
 450   g_return_val_if_fail (tree_model != NULL, 0);
 451   g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), 0);
 452
 453   if (GTK_TREE_MODEL_GET_IFACE (tree_model)->get_flags)
 454     return (GTK_TREE_MODEL_GET_IFACE (tree_model)->get_flags) (tree_model);
 455
 456   return 0;
 457 }
 458
 459 /**
 460  * gtk_tree_model_get_n_columns:
 461  * @tree_model: A #GtkTreeModel.
 462  *
 463  * Returns the number of columns supported by the #tree_model
 464  *
 465  * Return value: The number of columns.
 466  **/
 467 gint
 468 gtk_tree_model_get_n_columns (GtkTreeModel *tree_model)
 469 {
 470   g_return_val_if_fail (tree_model != NULL, 0);
 471   g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), 0);
 472   g_return_val_if_fail (GTK_TREE_MODEL_GET_IFACE (tree_model)->get_n_columns != NULL, 0);
 473
 474   return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->get_n_columns) (tree_model);
 475 }
 476
 477 /**
 478  * gtk_tree_model_get_column_type:
 479  * @tree_model: A #GtkTreeModel.
 480  * @index: The column index.
 481  *
 482  * Returns the type of the column.
 483  *
 484  * Return value: The type of the column.
 485  **/
 486 GType
 487 gtk_tree_model_get_column_type (GtkTreeModel *tree_model,
 488                                 gint          index)
 489 {
 490   g_return_val_if_fail (tree_model != NULL, G_TYPE_INVALID);
 491   g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), G_TYPE_INVALID);
 492   g_return_val_if_fail (GTK_TREE_MODEL_GET_IFACE (tree_model)->get_column_type != NULL, G_TYPE_INVALID);
 493   g_return_val_if_fail (index >= 0, G_TYPE_INVALID);
 494
 495   return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->get_column_type) (tree_model, index);
 496 }
 497
 498 /**
 499  * gtk_tree_model_get_iter:
 500  * @tree_model: A #GtkTreeModel.
 501  * @iter: The uninitialized #GtkTreeIter.
 502  * @path: The #GtkTreePath.
 503  *
 504  * Sets @iter to a valid iterator pointing to @path.  If the model does not
 505  * provide an implementation of this function, it is implemented in terms of
 506  * @gtk_tree_model_iter_nth_child.
 507  *
 508  * Return value: TRUE, if @iter was set.
 509  **/
 510 gboolean
 511 gtk_tree_model_get_iter (GtkTreeModel *tree_model,
 512                          GtkTreeIter  *iter,
 513                          GtkTreePath  *path)
 514 {
 515   GtkTreeIter parent;
 516   gint *indices;
 517   gint depth, i;
 518
 519   g_return_val_if_fail (tree_model != NULL, FALSE);
 520   g_return_val_if_fail (iter != NULL, FALSE);
 521   g_return_val_if_fail (path != NULL, FALSE);
 522   g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
 523
 524   if (GTK_TREE_MODEL_GET_IFACE (tree_model)->get_iter != NULL)
 525     return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->get_iter) (tree_model, iter, path);
 526
 527   indices = gtk_tree_path_get_indices (path);
 528   depth = gtk_tree_path_get_depth (path);
 529
 530   g_return_val_if_fail (depth > 0, FALSE);
 531
 532   if (! gtk_tree_model_iter_nth_child (tree_model, iter, NULL, indices[0]))
 533     return FALSE;
 534
 535   for (i = 1; i < depth; i++)
 536     {
 537       parent = *iter;
 538       if (! gtk_tree_model_iter_nth_child (tree_model, iter, &parent, indices[i]))
 539         return FALSE;
 540     }
 541
 542   return TRUE;
 543 }
 544
 545 /**
 546  * gtk_tree_model_get_first:
 547  * @tree_model: a #GtkTreeModel
 548  * @iter: iterator to initialize
 549  *
 550  * Initialized @iter with the first iterator in the tree (the one at the
 551  * root path) and returns %TRUE, or returns %FALSE if there are no
 552  * iterable locations in the model (i.e. the tree is empty).
 553  *
 554  * Return value: %TRUE if @iter was initialized
 555  **/
 556 gboolean
 557 gtk_tree_model_get_first (GtkTreeModel *tree_model,
 558                           GtkTreeIter  *iter)
 559 {
 560   gboolean retval;
 561   GtkTreePath *path;
 562
 563   g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
 564   g_return_val_if_fail (iter != NULL, FALSE);
 565
 566   path = gtk_tree_path_new_root ();
 567
 568   retval = gtk_tree_model_get_iter (tree_model, iter, path);
 569
 570   gtk_tree_path_free (path);
 571
 572   return retval;
 573 }
 574
 575 /**
 576  * gtk_tree_model_get_path:
 577  * @tree_model: A #GtkTreeModel.
 578  * @iter: The #GtkTreeIter.
 579  *
 580  * Returns a newly created #GtkTreePath referenced by @iter.  This path should
 581  * be freed with #gtk_tree_path_free.
 582  *
 583  * Return value: a newly created #GtkTreePath.
 584  **/
 585 GtkTreePath *
 586 gtk_tree_model_get_path (GtkTreeModel *tree_model,
 587                          GtkTreeIter  *iter)
 588 {
 589   g_return_val_if_fail (tree_model != NULL, NULL);
 590   g_return_val_if_fail (iter != NULL, NULL);
 591   g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), NULL);
 592   g_return_val_if_fail (GTK_TREE_MODEL_GET_IFACE (tree_model)->get_path != NULL, NULL);
 593
 594   return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->get_path) (tree_model, iter);
 595 }
 596
 597 /**
 598  * gtk_tree_model_get_value:
 599  * @tree_model: A #GtkTreeModel.
 600  * @iter: The #GtkTreeIter.
 601  * @column: The column to lookup the value at.
 602  * @value: An empty #GValue to set.
 603  *
 604  * Sets initializes and sets @value to that at @column.  When done with value,
 605  * #g_value_unset needs to be called on it.
 606  **/
 607 void
 608 gtk_tree_model_get_value (GtkTreeModel *tree_model,
 609                           GtkTreeIter  *iter,
 610                           gint          column,
 611                           GValue       *value)
 612 {
 613   g_return_if_fail (tree_model != NULL);
 614   g_return_if_fail (iter != NULL);
 615   g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
 616   g_return_if_fail (value != NULL);
 617   g_return_if_fail (GTK_TREE_MODEL_GET_IFACE (tree_model)->get_value != NULL);
 618
 619   (* GTK_TREE_MODEL_GET_IFACE (tree_model)->get_value) (tree_model, iter, column, value);
 620 }
 621
 622 /**
 623  * gtk_tree_model_iter_next:
 624  * @tree_model: A #GtkTreeModel.
 625  * @iter: The #GtkTreeIter.
 626  *
 627  * Sets @iter to point to the node following it at the current level.  If there
 628  * is no next @iter, FALSE is returned and @iter is set to be invalid.
 629  *
 630  * Return value: TRUE if @iter has been changed to the next node.
 631  **/
 632 gboolean
 633 gtk_tree_model_iter_next (GtkTreeModel  *tree_model,
 634                           GtkTreeIter   *iter)
 635 {
 636   g_return_val_if_fail (tree_model != NULL, FALSE);
 637   g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
 638   g_return_val_if_fail (iter != NULL, FALSE);
 639   g_return_val_if_fail (GTK_TREE_MODEL_GET_IFACE (tree_model)->iter_next != NULL, FALSE);
 640
 641   return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->iter_next) (tree_model, iter);
 642 }
 643
 644 /**
 645  * gtk_tree_model_iter_children:
 646  * @tree_model: A #GtkTreeModel.
 647  * @iter: The new #GtkTreeIter to be set to the child.
 648  * @parent: The #GtkTreeIter.
 649  *
 650  * Sets @iter to point to the first child of @parent.  If @parent has no children,
 651  * FALSE is returned and @iter is set to be invalid.  @parent will remain a valid
 652  * node after this function has been called.
 653  *
 654  * Return value: TRUE, if @child has been set to the first child.
 655  **/
 656 gboolean
 657 gtk_tree_model_iter_children (GtkTreeModel *tree_model,
 658                               GtkTreeIter  *iter,
 659                               GtkTreeIter  *parent)
 660 {
 661   g_return_val_if_fail (tree_model != NULL, FALSE);
 662   g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
 663   g_return_val_if_fail (iter != NULL, FALSE);
 664   g_return_val_if_fail (GTK_TREE_MODEL_GET_IFACE (tree_model)->iter_children != NULL, FALSE);
 665
 666   return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->iter_children) (tree_model, iter, parent);
 667 }
 668
 669 /**
 670  * gtk_tree_model_iter_has_child:
 671  * @tree_model: A #GtkTreeModel.
 672  * @iter: The #GtkTreeIter to test for children.
 673  *
 674  * Returns TRUE if @iter has children, FALSE otherwise.
 675  *
 676  * Return value: TRUE if @iter has children.
 677  **/
 678 gboolean
 679 gtk_tree_model_iter_has_child (GtkTreeModel *tree_model,
 680                                GtkTreeIter  *iter)
 681 {
 682   g_return_val_if_fail (tree_model != NULL, FALSE);
 683   g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
 684   g_return_val_if_fail (iter != NULL, FALSE);
 685   g_return_val_if_fail (GTK_TREE_MODEL_GET_IFACE (tree_model)->iter_has_child != NULL, FALSE);
 686
 687   return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->iter_has_child) (tree_model, iter);
 688 }
 689
 690 /**
 691  * gtk_tree_model_iter_n_children:
 692  * @tree_model: A #GtkTreeModel.
 693  * @iter: The #GtkTreeIter, or NULL.
 694  *
 695  * Returns the number of children that @iter has.  If @iter is NULL, then the
 696  * number of toplevel nodes is returned.
 697  *
 698  * Return value: The number of children of @iter.
 699  **/
 700 gint
 701 gtk_tree_model_iter_n_children (GtkTreeModel *tree_model,
 702                                 GtkTreeIter  *iter)
 703 {
 704   g_return_val_if_fail (tree_model != NULL, 0);
 705   g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), 0);
 706   g_return_val_if_fail (GTK_TREE_MODEL_GET_IFACE (tree_model)->iter_n_children != NULL, 0);
 707
 708   return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->iter_n_children) (tree_model, iter);
 709 }
 710
 711 /**
 712  * gtk_tree_model_iter_nth_child:
 713  * @tree_model: A #GtkTreeModel.
 714  * @iter: The #GtkTreeIter to set to the nth child.
 715  * @parent: The #GtkTreeIter to get the child from, or NULL.
 716  * @n: Then index of the desired child.
 717  *
 718  * Sets @iter to be the child of @parent, using the given index.  The first
 719  * index is 0.  If the index is too big, or @parent has no children, @iter is
 720  * set to an invalid iterator and FALSE is returned.  @parent will remain a
 721  * valid node after this function has been called.  If @parent is NULL, then the
 722  * root node is assumed.
 723  *
 724  * Return value: TRUE, if @parent has an nth child.
 725  **/
 726 gboolean
 727 gtk_tree_model_iter_nth_child (GtkTreeModel *tree_model,
 728                                GtkTreeIter  *iter,
 729                                GtkTreeIter  *parent,
 730                                gint          n)
 731 {
 732   g_return_val_if_fail (tree_model != NULL, FALSE);
 733   g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
 734   g_return_val_if_fail (iter != NULL, FALSE);
 735   g_return_val_if_fail (n >= 0, FALSE);
 736   g_return_val_if_fail (GTK_TREE_MODEL_GET_IFACE (tree_model)->iter_nth_child != NULL, FALSE);
 737
 738   return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->iter_nth_child) (tree_model, iter, parent, n);
 739 }
 740
 741 /**
 742  * gtk_tree_model_iter_parent:
 743  * @tree_model: A #GtkTreeModel
 744  * @iter: The new #GtkTreeIter to set to the parent.
 745  * @child: The #GtkTreeIter.
 746  *
 747  * Sets @iter to be the parent of @child.  If @child is at the toplevel, and
 748  * doesn't have a parent, then @iter is set to an invalid iterator and FALSE
 749  * is returned.  @child will remain a valid node after this function has been
 750  * called.
 751  *
 752  * Return value: TRUE, if @iter is set to the parent of @child.
 753  **/
 754 gboolean
 755 gtk_tree_model_iter_parent (GtkTreeModel *tree_model,
 756                             GtkTreeIter  *iter,
 757                             GtkTreeIter  *child)
 758 {
 759   g_return_val_if_fail (tree_model != NULL, FALSE);
 760   g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
 761   g_return_val_if_fail (iter != NULL, FALSE);
 762   g_return_val_if_fail (child != NULL, FALSE);
 763   g_return_val_if_fail (GTK_TREE_MODEL_GET_IFACE (tree_model)->iter_parent != NULL, FALSE);
 764
 765   return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->iter_parent) (tree_model, iter, child);
 766 }
 767
 768 /* FIXME explain what the method is supposed to do! */
 769 /**
 770  * gtk_tree_model_ref_iter:
 771  * @tree_model: A #GtkTreeModel.
 772  * @iter: The #GtkTreeIter.
 773  *
 774  * Ref's the iter.  This is an optional method for models to implement.  To be
 775  * more specific, models may ignore this call as it exists primarily for
 776  * performance reasons.
 777  **/
 778 void
 779 gtk_tree_model_ref_iter (GtkTreeModel *tree_model,
 780                          GtkTreeIter  *iter)
 781 {
 782   g_return_if_fail (tree_model != NULL);
 783   g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
 784
 785   if (GTK_TREE_MODEL_GET_IFACE (tree_model)->ref_iter)
 786     (* GTK_TREE_MODEL_GET_IFACE (tree_model)->ref_iter) (tree_model, iter);
 787 }
 788
 789 /* FIXME explain what the method is supposed to do! */
 790 /**
 791  * gtk_tree_model_unref_iter:
 792  * @tree_model: A #GtkTreeModel.
 793  * @iter: The #GtkTreeIter.
 794  *
 795  * Unref's the iter.  This is an optional method for models to implement.  To be
 796  * more specific, models may ignore this call as it exists primarily for
 797  * performance reasons.
 798  **/
 799 void
 800 gtk_tree_model_unref_iter (GtkTreeModel *tree_model,
 801                            GtkTreeIter  *iter)
 802 {
 803   g_return_if_fail (tree_model != NULL);
 804   g_return_if_fail (GTK_IS_TREE_MODEL (tree_model));
 805
 806   if (GTK_TREE_MODEL_GET_IFACE (tree_model)->unref_iter)
 807     (* GTK_TREE_MODEL_GET_IFACE (tree_model)->unref_iter) (tree_model, iter);
 808 }