gtkD/src/gtk/TreeIter.d

   1 /*
   2  * This file is part of gtkD.
   3  *
   4  * gtkD is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU Lesser General Public License as published by
   6  * the Free Software Foundation; either version 2.1 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * gtkD 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
  12  * GNU Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public License
  15  * along with gtkD; if not, write to the Free Software
  16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  17  */
  18
  19 // generated automatically - do not change
  20 // find conversion definition on APILookup.txt
  21 // implement new conversion functionalities on the wrap.utils pakage
  22
  23 /*
  24  * Conversion parameters:
  25  * inFile  =
  26  * outPack = gtk
  27  * outFile = TreeIter
  28  * strct   = GtkTreeIter
  29  * realStrct=
  30  * ctorStrct=
  31  * clss    = TreeIter
  32  * interf  =
  33  * class Code: Yes
  34  * interface Code: No
  35  * template for:
  36  * extend  =
  37  * implements:
  38  * prefixes:
  39  *      - gtk_tree_iter_
  40  * omit structs:
  41  * omit prefixes:
  42  * omit code:
  43  * imports:
  44  *      - glib.Str
  45  *      - gtk.TreeIter
  46  *      - gtk.TreeModel
  47  *      - gtk.TreePath
  48  *      - gtk.TreeIterError
  49  *      - gobject.Value;
  50  * structWrap:
  51  *      - GtkTreeIter* -> TreeIter
  52  * module aliases:
  53  * local aliases:
  54  */
  55
  56 module gtk.TreeIter;
  57
  58 version(noAssert)
  59 {
  60         version(Tango)
  61         {
  62                 import tango.io.Stdout; // use the tango loging?
  63         }
  64 }
  65
  66 private import gtkc.gtktypes;
  67
  68 private import gtkc.gtk;
  69
  70
  71 private import glib.Str;
  72 private import gtk.TreeIter;
  73 private import gtk.TreeModel;
  74 private import gtk.TreePath;
  75 private import gtk.TreeIterError;
  76 private import gobject.Value;;
  77
  78
  79
  80
  81 /**
  82  * Description
  83  * The GtkTreeModel interface defines a generic tree interface for use by
  84  * the GtkTreeView widget. It is an abstract interface, and is designed
  85  * to be usable with any appropriate data structure. The programmer just
  86  * has to implement this interface on their own data type for it to be
  87  * viewable by a GtkTreeView widget.
  88  * The model is represented as a hierarchical tree of strongly-typed,
  89  * columned data. In other words, the model can be seen as a tree where
  90  * every node has different values depending on which column is being
  91  * queried. The type of data found in a column is determined by using the
  92  * GType system (ie. G_TYPE_INT, GTK_TYPE_BUTTON, G_TYPE_POINTER, etc.).
  93  * The types are homogeneous per column across all nodes. It is important
  94  * to note that this interface only provides a way of examining a model and
  95  * observing changes. The implementation of each individual model decides
  96  * how and if changes are made.
  97  * In order to make life simpler for programmers who do not need to write
  98  * their own specialized model, two generic models are provided  the
  99  * GtkTreeStore and the GtkListStore. To use these, the developer simply
 100  * pushes data into these models as necessary. These models provide the
 101  * data structure as well as all appropriate tree interfaces. As a result,
 102  * implementing drag and drop, sorting, and storing data is trivial. For
 103  * the vast majority of trees and lists, these two models are sufficient.
 104  * Models are accessed on a node/column level of granularity. One can
 105  * query for the value of a model at a certain node and a certain column
 106  * on that node. There are two structures used to reference a particular
 107  * node in a model. They are the GtkTreePath and the GtkTreeIter
 108  * [4]
 109  * Most of the interface consists of operations on a GtkTreeIter.
 110  * A path is essentially a potential node. It is a location on a model
 111  * that may or may not actually correspond to a node on a specific model.
 112  * The GtkTreePath struct can be converted into either an array of
 113  * unsigned integers or a string. The string form is a list of numbers
 114  * separated by a colon. Each number refers to the offset at that level.
 115  * Thus, the path 0 refers to the root node and the path
 116  * 2:4 refers to the fifth child of the third node.
 117  * By contrast, a GtkTreeIter is a reference to a specific node on a
 118  * specific model. It is a generic struct with an integer and three
 119  * generic pointers. These are filled in by the model in a model-specific
 120  * way. One can convert a path to an iterator by calling
 121  * gtk_tree_model_get_iter(). These iterators are the primary way of
 122  * accessing a model and are similar to the iterators used by
 123  * GtkTextBuffer. They are generally statically allocated on the stack and
 124  * only used for a short time. The model interface defines a set of
 125  * operations using them for navigating the model.
 126  * It is expected that models fill in the iterator with private data. For
 127  * example, the GtkListStore model, which is internally a simple linked
 128  * list, stores a list node in one of the pointers. The GtkTreeModelSort
 129  * stores an array and an offset in two of the pointers. Additionally,
 130  * there is an integer field. This field is generally filled with a unique
 131  * stamp per model. This stamp is for catching errors resulting from using
 132  * invalid iterators with a model.
 133  * The lifecycle of an iterator can be a little confusing at first.
 134  * Iterators are expected to always be valid for as long as the model is
 135  * unchanged (and doesn't emit a signal). The model is considered to own
 136  * all outstanding iterators and nothing needs to be done to free them from
 137  * the user's point of view. Additionally, some models guarantee that an
 138  * iterator is valid for as long as the node it refers to is valid (most
 139  * notably the GtkTreeStore and GtkListStore). Although generally
 140  * uninteresting, as one always has to allow for the case where iterators
 141  * do not persist beyond a signal, some very important performance
 142  * enhancements were made in the sort model. As a result, the
 143  * GTK_TREE_MODEL_ITERS_PERSIST flag was added to indicate this behavior.
 144  * To help show some common operation of a model, some examples are
 145  * provided. The first example shows three ways of getting the iter at the
 146  * location 3:2:5. While the first method shown is easier,
 147  * the second is much more common, as you often get paths from callbacks.
 148  * Example1.Acquiring a GtkTreeIter
 149  * /+* Three ways of getting the iter pointing to the location
 150  *  +/
 151  * {
 152          *  GtkTreePath *path;
 153          *  GtkTreeIter iter;
 154          *  GtkTreeIter parent_iter;
 155          *  /+* get the iterator from a string +/
 156          *  gtk_tree_model_get_iter_from_string (model, iter, "3:2:5");
 157          *  /+* get the iterator from a path +/
 158          *  path = gtk_tree_path_new_from_string ("3:2:5");
 159          *  gtk_tree_model_get_iter (model, iter, path);
 160          *  gtk_tree_path_free (path);
 161          *  /+* walk the tree to find the iterator +/
 162          *  gtk_tree_model_iter_nth_child (model, iter, NULL, 3);
 163          *  parent_iter = iter;
 164          *  gtk_tree_model_iter_nth_child (model, iter, parent_iter, 2);
 165          *  parent_iter = iter;
 166          *  gtk_tree_model_iter_nth_child (model, iter, parent_iter, 5);
 167  * }
 168  * This second example shows a quick way of iterating through a list and
 169  * getting a string and an integer from each row. The
 170  * populate_model function used below is not shown, as
 171  * it is specific to the GtkListStore. For information on how to write
 172  * such a function, see the GtkListStore documentation.
 173  * Example2.Reading data from a GtkTreeModel
 174  * enum
 175  * {
 176          *  STRING_COLUMN,
 177          *  INT_COLUMN,
 178          *  N_COLUMNS
 179  * };
 180  * {
 181          *  GtkTreeModel *list_store;
 182          *  GtkTreeIter iter;
 183          *  gboolean valid;
 184          *  gint row_count = 0;
 185          *  /+* make a new list_store +/
 186          *  list_store = gtk_list_store_new (N_COLUMNS, G_TYPE_STRING, G_TYPE_INT);
 187          *  /+* Fill the list store with data +/
 188          *  populate_model (list_store);
 189          *  /+* Get the first iter in the list +/
 190          *  valid = gtk_tree_model_get_iter_first (list_store, iter);
 191          *  while (valid)
 192          *  {
 193                  *  /+* Walk through the list, reading each row +/
 194                  *  gchar *str_data;
 195                  *  gint int_data;
 196                  *  /+* Make sure you terminate calls to gtk_tree_model_get()
 197                  *  * with a '-1' value
 198                  *  +/
 199                  *  gtk_tree_model_get (list_store, iter,
 200                  *  STRING_COLUMN, str_data,
 201                  *  INT_COLUMN, int_data,
 202                  *  -1);
 203                  *  /+* Do something with the data +/
 204                  *  g_print ("Row %d: (%s,%d)\n", row_count, str_data, int_data);
 205                  *  g_free (str_data);
 206                  *  row_count ++;
 207                  *  valid = gtk_tree_model_iter_next (list_store, iter);
 208          *  }
 209  * }
 210  */
 211 public class TreeIter
 212 {
 213
 214         /** the main Gtk struct */
 215         protected GtkTreeIter* gtkTreeIter;
 216
 217
 218         public GtkTreeIter* getTreeIterStruct()
 219         {
 220                 return gtkTreeIter;
 221         }
 222
 223
 224         /** the main Gtk struct as a void* */
 225         protected void* getStruct()
 226         {
 227                 return cast(void*)gtkTreeIter;
 228         }
 229
 230         /**
 231          * Sets our main struct and passes it to the parent class
 232          */
 233         public this (GtkTreeIter* gtkTreeIter)
 234         {
 235                 version(noAssert)
 236                 {
 237                         if ( gtkTreeIter is null )
 238                         {
 239                                 int zero = 0;
 240                                 version(Tango)
 241                                 {
 242                                         Stdout("struct gtkTreeIter is null on constructor").newline;
 243                                 }
 244                                 else
 245                                 {
 246                                         printf("struct gtkTreeIter is null on constructor");
 247                                 }
 248                                 zero = zero / zero;
 249                         }
 250                 }
 251                 else
 252                 {
 253                         assert(gtkTreeIter !is null, "struct gtkTreeIter is null on constructor");
 254                 }
 255                 this.gtkTreeIter = gtkTreeIter;
 256         }
 257
 258         /**
 259          * this will be set only when the iter
 260          * is created from the model.
 261          */
 262         GtkTreeModel *gtkTreeModel;
 263
 264         public void setModel(GtkTreeModel *gtkTreeModel)
 265         {
 266                 this.gtkTreeModel = gtkTreeModel;
 267         }
 268
 269         public void setModel(TreeModel treeModel)
 270         {
 271                 this.gtkTreeModel = treeModel.getTreeModelStruct();
 272         }
 273
 274         public this(TreeModel treeModel, TreePath treePath)
 275         {
 276                 this();
 277                 setModel(treeModel);
 278                 if ( gtk_tree_model_get_iter_from_string(
 279                 treeModel.getTreeModelStruct(),
 280                 getTreeIterStruct(), Str.toStringz(treePath.toString())) )
 281                 {
 282                         // ???
 283                 }
 284         }
 285
 286         /**
 287          * creates a new tree iteractor.
 288          * used TreeView.createIter and TreeView.append() to create iteractor for a tree or list
 289          */
 290         this()
 291         {
 292                 this(new GtkTreeIter);
 293         }
 294
 295
 296         /**
 297          * Get Value
 298          * @param iter
 299          * @param column
 300          * @param value
 301          */
 302         void getValue(int column, Value value)
 303         {
 304                 if ( gtkTreeModel  is  null )
 305                 {
 306                         throw new TreeIterError("getValue","Tree model not set");
 307                 }
 308                 gtk_tree_model_get_value(gtkTreeModel, gtkTreeIter, column, value.getValueStruct());
 309         }
 310
 311         /**
 312          * Get the value of a column as a string
 313          * @para column the column number
 314          * @return a string representing the value of the column
 315          */
 316         char[] getValueString(int column)
 317         {
 318                 if ( gtkTreeModel  is  null )
 319                 {
 320                         throw new TreeIterError("getValueString","Tree model not set");
 321                 }
 322                 Value value = new Value();
 323                 gtk_tree_model_get_value(gtkTreeModel, gtkTreeIter, column, value.getValueStruct());
 324                 //printf("TreeIter.getValuaString = %.*s\n", value.getString().toString());
 325                 return value.getString();
 326         }
 327
 328         /**
 329          * Get the value of a column as an int
 330          * @para column the column number
 331          * @return a string representing the value of the column
 332          */
 333         int getValueInt(int column)
 334         {
 335                 if ( gtkTreeModel  is  null )
 336                 {
 337                         throw new TreeIterError("getValueInt", "Tree model not set");
 338                 }
 339                 Value value = new Value();
 340                 gtk_tree_model_get_value(gtkTreeModel, gtkTreeIter, column, value.getValueStruct());
 341                 return value.getInt();
 342         }
 343
 344         TreePath getTreePath()
 345         {
 346                 if ( gtkTreeModel  is  null )
 347                 {
 348                         throw new TreeIterError("getTreePath","Tree model not set");
 349                 }
 350                 return new TreePath(gtk_tree_model_get_path(gtkTreeModel, gtkTreeIter));
 351         }
 352
 353         /**
 354          * This return the path visible to the user.
 355          */
 356         char[] getVisiblePath(char[] separator)
 357         {
 358                 char[] vPath;
 359                 if ( gtkTreeModel  is  null )
 360                 {
 361                         throw new TreeIterError("getVisiblePath", "Tree model not set");
 362                 }
 363
 364                 vPath = getValueString(0);
 365                 TreeIter parent = getParent();
 366                 while ( parent !is  null )
 367                 {
 368                         //printf("TreeIter.getVisiblePath parent = %.*s\n",parent.getValueString(0).toString());
 369                         vPath = parent.getValueString(0) ~ separator ~ vPath;
 370                         parent = parent.getParent();
 371                 }
 372
 373                 //printf("TreeIter.getVisiblePath = %.*s\n", vPath.toString());
 374
 375                 return vPath;
 376         }
 377
 378         /**
 379          * Gets the parent of this iter
 380          * @param child
 381          * @return the parent iter or null if can't get parent or an error occured
 382          */
 383         TreeIter getParent()
 384         {
 385                 if ( gtkTreeModel  is  null )
 386                 {
 387                         throw new TreeIterError("getParent", "Tree model not set");
 388                 }
 389                 TreeIter parent = new TreeIter();
 390                 bool gotParent = gtk_tree_model_iter_parent(gtkTreeModel, parent.getTreeIterStruct(), gtkTreeIter) == 0 ? false : true;
 391                 if ( !gotParent )
 392                 {
 393                         return null;
 394                 }
 395                 parent.setModel(gtkTreeModel);
 396                 return parent;
 397         }
 398
 399
 400         TreeIter getGrandParent()
 401         {
 402                 if ( gtkTreeModel  is  null )
 403                 {
 404                         throw new TreeIterError("getGrandParent", "Tree model not set");
 405                 }
 406                 TreeIter grandParent = this;
 407                 TreeIter parent = grandParent.getParent();
 408                 while ( parent !is null )
 409                 {
 410                         grandParent = parent;
 411                         parent = grandParent.getParent();
 412                 }
 413
 414                 return grandParent;
 415         }
 416
 417
 418
 419
 420
 421         /**
 422          */
 423
 424         // imports for the signal processing
 425         private import gobject.Signals;
 426         private import gtkc.gdktypes;
 427         int[char[]] connectedSignals;
 428
 429         void delegate(GtkTreePath*, TreeIter, TreeIter)[] onRowChangedListeners;
 430         void addOnRowChanged(void delegate(GtkTreePath*, TreeIter, TreeIter) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
 431         {
 432                 if ( !("row-changed" in connectedSignals) )
 433                 {
 434                         Signals.connectData(
 435                         getStruct(),
 436                         "row-changed",
 437                         cast(GCallback)&callBackRowChanged,
 438                         cast(void*)this,
 439                         null,
 440                         connectFlags);
 441                         connectedSignals["row-changed"] = 1;
 442                 }
 443                 onRowChangedListeners ~= dlg;
 444         }
 445         extern(C) static void callBackRowChanged(GtkTreeModel* treeModelStruct, GtkTreePath* path, GtkTreeIter* iter, TreeIter treeIter)
 446         {
 447                 bool consumed = false;
 448
 449                 foreach ( void delegate(GtkTreePath*, TreeIter, TreeIter) dlg ; treeIter.onRowChangedListeners )
 450                 {
 451                         dlg(path, new TreeIter(iter), treeIter);
 452                 }
 453
 454                 return consumed;
 455         }
 456
 457         void delegate(GtkTreePath*, TreeIter)[] onRowDeletedListeners;
 458         void addOnRowDeleted(void delegate(GtkTreePath*, TreeIter) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
 459         {
 460                 if ( !("row-deleted" in connectedSignals) )
 461                 {
 462                         Signals.connectData(
 463                         getStruct(),
 464                         "row-deleted",
 465                         cast(GCallback)&callBackRowDeleted,
 466                         cast(void*)this,
 467                         null,
 468                         connectFlags);
 469                         connectedSignals["row-deleted"] = 1;
 470                 }
 471                 onRowDeletedListeners ~= dlg;
 472         }
 473         extern(C) static void callBackRowDeleted(GtkTreeModel* treeModelStruct, GtkTreePath* path, TreeIter treeIter)
 474         {
 475                 bool consumed = false;
 476
 477                 foreach ( void delegate(GtkTreePath*, TreeIter) dlg ; treeIter.onRowDeletedListeners )
 478                 {
 479                         dlg(path, treeIter);
 480                 }
 481
 482                 return consumed;
 483         }
 484
 485         void delegate(GtkTreePath*, TreeIter, TreeIter)[] onRowHasChildToggledListeners;
 486         void addOnRowHasChildToggled(void delegate(GtkTreePath*, TreeIter, TreeIter) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
 487         {
 488                 if ( !("row-has-child-toggled" in connectedSignals) )
 489                 {
 490                         Signals.connectData(
 491                         getStruct(),
 492                         "row-has-child-toggled",
 493                         cast(GCallback)&callBackRowHasChildToggled,
 494                         cast(void*)this,
 495                         null,
 496                         connectFlags);
 497                         connectedSignals["row-has-child-toggled"] = 1;
 498                 }
 499                 onRowHasChildToggledListeners ~= dlg;
 500         }
 501         extern(C) static void callBackRowHasChildToggled(GtkTreeModel* treeModelStruct, GtkTreePath* path, GtkTreeIter* iter, TreeIter treeIter)
 502         {
 503                 bool consumed = false;
 504
 505                 foreach ( void delegate(GtkTreePath*, TreeIter, TreeIter) dlg ; treeIter.onRowHasChildToggledListeners )
 506                 {
 507                         dlg(path, new TreeIter(iter), treeIter);
 508                 }
 509
 510                 return consumed;
 511         }
 512
 513         void delegate(GtkTreePath*, TreeIter, TreeIter)[] onRowInsertedListeners;
 514         void addOnRowInserted(void delegate(GtkTreePath*, TreeIter, TreeIter) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
 515         {
 516                 if ( !("row-inserted" in connectedSignals) )
 517                 {
 518                         Signals.connectData(
 519                         getStruct(),
 520                         "row-inserted",
 521                         cast(GCallback)&callBackRowInserted,
 522                         cast(void*)this,
 523                         null,
 524                         connectFlags);
 525                         connectedSignals["row-inserted"] = 1;
 526                 }
 527                 onRowInsertedListeners ~= dlg;
 528         }
 529         extern(C) static void callBackRowInserted(GtkTreeModel* treeModelStruct, GtkTreePath* path, GtkTreeIter* iter, TreeIter treeIter)
 530         {
 531                 bool consumed = false;
 532
 533                 foreach ( void delegate(GtkTreePath*, TreeIter, TreeIter) dlg ; treeIter.onRowInsertedListeners )
 534                 {
 535                         dlg(path, new TreeIter(iter), treeIter);
 536                 }
 537
 538                 return consumed;
 539         }
 540
 541         void delegate(GtkTreePath*, TreeIter, gpointer, TreeIter)[] onRowsReorderedListeners;
 542         void addOnRowsReordered(void delegate(GtkTreePath*, TreeIter, gpointer, TreeIter) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
 543         {
 544                 if ( !("rows-reordered" in connectedSignals) )
 545                 {
 546                         Signals.connectData(
 547                         getStruct(),
 548                         "rows-reordered",
 549                         cast(GCallback)&callBackRowsReordered,
 550                         cast(void*)this,
 551                         null,
 552                         connectFlags);
 553                         connectedSignals["rows-reordered"] = 1;
 554                 }
 555                 onRowsReorderedListeners ~= dlg;
 556         }
 557         extern(C) static void callBackRowsReordered(GtkTreeModel* treeModelStruct, GtkTreePath* path, GtkTreeIter* iter, gpointer arg3, TreeIter treeIter)
 558         {
 559                 bool consumed = false;
 560
 561                 foreach ( void delegate(GtkTreePath*, TreeIter, gpointer, TreeIter) dlg ; treeIter.onRowsReorderedListeners )
 562                 {
 563                         dlg(path, new TreeIter(iter), arg3, treeIter);
 564                 }
 565
 566                 return consumed;
 567         }
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606         /**
 607          * Creates a dynamically allocated tree iterator as a copy of iter. This
 608          * function is not intended for use in applications, because you can just copy
 609          * the structs by value (GtkTreeIter new_iter = iter;). You
 610          * must free this iter with gtk_tree_iter_free().
 611          * iter:
 612          *  A GtkTreeIter.
 613          * Returns:
 614          *  a newly-allocated copy of iter.
 615          */
 616         public TreeIter copy()
 617         {
 618                 // GtkTreeIter* gtk_tree_iter_copy (GtkTreeIter *iter);
 619                 return new TreeIter( gtk_tree_iter_copy(gtkTreeIter) );
 620         }
 621
 622         /**
 623          * Frees an iterator that has been allocated on the heap. This function is
 624          * mainly used for language bindings.
 625          * iter:
 626          *  A dynamically allocated tree iterator.
 627          */
 628         public void free()
 629         {
 630                 // void gtk_tree_iter_free (GtkTreeIter *iter);
 631                 gtk_tree_iter_free(gtkTreeIter);
 632         }
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663 }