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 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module gtk.TreeModelIF; 26 27 private import glib.Str; 28 private import gobject.ObjectG; 29 private import gobject.Signals; 30 private import gobject.Value; 31 private import gtk.TreeIter; 32 private import gtk.TreePath; 33 private import gtk.c.functions; 34 public import gtk.c.types; 35 public import gtkc.gtktypes; 36 private import std.algorithm; 37 38 39 /** 40 * The #GtkTreeModel interface defines a generic tree interface for 41 * use by the #GtkTreeView widget. It is an abstract interface, and 42 * is designed to be usable with any appropriate data structure. The 43 * programmer just has to implement this interface on their own data 44 * type for it to be viewable by a #GtkTreeView widget. 45 * 46 * The model is represented as a hierarchical tree of strongly-typed, 47 * columned data. In other words, the model can be seen as a tree where 48 * every node has different values depending on which column is being 49 * queried. The type of data found in a column is determined by using 50 * the GType system (ie. #G_TYPE_INT, #GTK_TYPE_BUTTON, #G_TYPE_POINTER, 51 * etc). The types are homogeneous per column across all nodes. It is 52 * important to note that this interface only provides a way of examining 53 * a model and observing changes. The implementation of each individual 54 * model decides how and if changes are made. 55 * 56 * In order to make life simpler for programmers who do not need to 57 * write their own specialized model, two generic models are provided 58 * — the #GtkTreeStore and the #GtkListStore. To use these, the 59 * developer simply pushes data into these models as necessary. These 60 * models provide the data structure as well as all appropriate tree 61 * interfaces. As a result, implementing drag and drop, sorting, and 62 * storing data is trivial. For the vast majority of trees and lists, 63 * these two models are sufficient. 64 * 65 * Models are accessed on a node/column level of granularity. One can 66 * query for the value of a model at a certain node and a certain 67 * column on that node. There are two structures used to reference a 68 * particular node in a model. They are the #GtkTreePath-struct and 69 * the #GtkTreeIter-struct (“iter” is short for iterator). Most of the 70 * interface consists of operations on a #GtkTreeIter-struct. 71 * 72 * A path is essentially a potential node. It is a location on a model 73 * that may or may not actually correspond to a node on a specific 74 * model. The #GtkTreePath-struct can be converted into either an 75 * array of unsigned integers or a string. The string form is a list 76 * of numbers separated by a colon. Each number refers to the offset 77 * at that level. Thus, the path `0` refers to the root 78 * node and the path `2:4` refers to the fifth child of 79 * the third node. 80 * 81 * By contrast, a #GtkTreeIter-struct is a reference to a specific node on 82 * a specific model. It is a generic struct with an integer and three 83 * generic pointers. These are filled in by the model in a model-specific 84 * way. One can convert a path to an iterator by calling 85 * gtk_tree_model_get_iter(). These iterators are the primary way 86 * of accessing a model and are similar to the iterators used by 87 * #GtkTextBuffer. They are generally statically allocated on the 88 * stack and only used for a short time. The model interface defines 89 * a set of operations using them for navigating the model. 90 * 91 * It is expected that models fill in the iterator with private data. 92 * For example, the #GtkListStore model, which is internally a simple 93 * linked list, stores a list node in one of the pointers. The 94 * #GtkTreeModelSort stores an array and an offset in two of the 95 * pointers. Additionally, there is an integer field. This field is 96 * generally filled with a unique stamp per model. This stamp is for 97 * catching errors resulting from using invalid iterators with a model. 98 * 99 * The lifecycle of an iterator can be a little confusing at first. 100 * Iterators are expected to always be valid for as long as the model 101 * is unchanged (and doesn’t emit a signal). The model is considered 102 * to own all outstanding iterators and nothing needs to be done to 103 * free them from the user’s point of view. Additionally, some models 104 * guarantee that an iterator is valid for as long as the node it refers 105 * to is valid (most notably the #GtkTreeStore and #GtkListStore). 106 * Although generally uninteresting, as one always has to allow for 107 * the case where iterators do not persist beyond a signal, some very 108 * important performance enhancements were made in the sort model. 109 * As a result, the #GTK_TREE_MODEL_ITERS_PERSIST flag was added to 110 * indicate this behavior. 111 * 112 * To help show some common operation of a model, some examples are 113 * provided. The first example shows three ways of getting the iter at 114 * the location `3:2:5`. While the first method shown is 115 * easier, the second is much more common, as you often get paths from 116 * callbacks. 117 * 118 * ## Acquiring a #GtkTreeIter-struct 119 * 120 * |[<!-- language="C" --> 121 * // Three ways of getting the iter pointing to the location 122 * GtkTreePath *path; 123 * GtkTreeIter iter; 124 * GtkTreeIter parent_iter; 125 * 126 * // get the iterator from a string 127 * gtk_tree_model_get_iter_from_string (model, 128 * &iter, 129 * "3:2:5"); 130 * 131 * // get the iterator from a path 132 * path = gtk_tree_path_new_from_string ("3:2:5"); 133 * gtk_tree_model_get_iter (model, &iter, path); 134 * gtk_tree_path_free (path); 135 * 136 * // walk the tree to find the iterator 137 * gtk_tree_model_iter_nth_child (model, &iter, 138 * NULL, 3); 139 * parent_iter = iter; 140 * gtk_tree_model_iter_nth_child (model, &iter, 141 * &parent_iter, 2); 142 * parent_iter = iter; 143 * gtk_tree_model_iter_nth_child (model, &iter, 144 * &parent_iter, 5); 145 * ]| 146 * 147 * This second example shows a quick way of iterating through a list 148 * and getting a string and an integer from each row. The 149 * populate_model() function used below is not 150 * shown, as it is specific to the #GtkListStore. For information on 151 * how to write such a function, see the #GtkListStore documentation. 152 * 153 * ## Reading data from a #GtkTreeModel 154 * 155 * |[<!-- language="C" --> 156 * enum 157 * { 158 * STRING_COLUMN, 159 * INT_COLUMN, 160 * N_COLUMNS 161 * }; 162 * 163 * ... 164 * 165 * GtkTreeModel *list_store; 166 * GtkTreeIter iter; 167 * gboolean valid; 168 * gint row_count = 0; 169 * 170 * // make a new list_store 171 * list_store = gtk_list_store_new (N_COLUMNS, 172 * G_TYPE_STRING, 173 * G_TYPE_INT); 174 * 175 * // Fill the list store with data 176 * populate_model (list_store); 177 * 178 * // Get the first iter in the list, check it is valid and walk 179 * // through the list, reading each row. 180 * 181 * valid = gtk_tree_model_get_iter_first (list_store, 182 * &iter); 183 * while (valid) 184 * { 185 * gchar *str_data; 186 * gint int_data; 187 * 188 * // Make sure you terminate calls to gtk_tree_model_get() with a “-1” value 189 * gtk_tree_model_get (list_store, &iter, 190 * STRING_COLUMN, &str_data, 191 * INT_COLUMN, &int_data, 192 * -1); 193 * 194 * // Do something with the data 195 * g_print ("Row %d: (%s,%d)\n", 196 * row_count, str_data, int_data); 197 * g_free (str_data); 198 * 199 * valid = gtk_tree_model_iter_next (list_store, 200 * &iter); 201 * row_count++; 202 * } 203 * ]| 204 * 205 * The #GtkTreeModel interface contains two methods for reference 206 * counting: gtk_tree_model_ref_node() and gtk_tree_model_unref_node(). 207 * These two methods are optional to implement. The reference counting 208 * is meant as a way for views to let models know when nodes are being 209 * displayed. #GtkTreeView will take a reference on a node when it is 210 * visible, which means the node is either in the toplevel or expanded. 211 * Being displayed does not mean that the node is currently directly 212 * visible to the user in the viewport. Based on this reference counting 213 * scheme a caching model, for example, can decide whether or not to cache 214 * a node based on the reference count. A file-system based model would 215 * not want to keep the entire file hierarchy in memory, but just the 216 * folders that are currently expanded in every current view. 217 * 218 * When working with reference counting, the following rules must be taken 219 * into account: 220 * 221 * - Never take a reference on a node without owning a reference on its parent. 222 * This means that all parent nodes of a referenced node must be referenced 223 * as well. 224 * 225 * - Outstanding references on a deleted node are not released. This is not 226 * possible because the node has already been deleted by the time the 227 * row-deleted signal is received. 228 * 229 * - Models are not obligated to emit a signal on rows of which none of its 230 * siblings are referenced. To phrase this differently, signals are only 231 * required for levels in which nodes are referenced. For the root level 232 * however, signals must be emitted at all times (however the root level 233 * is always referenced when any view is attached). 234 */ 235 public interface TreeModelIF{ 236 /** Get the main Gtk struct */ 237 public GtkTreeModel* getTreeModelStruct(bool transferOwnership = false); 238 239 /** the main Gtk struct as a void* */ 240 protected void* getStruct(); 241 242 /** 243 * Get the value of a column as a char array. 244 * this is the same calling getValue and get the string from the value object 245 */ 246 string getValueString(TreeIter iter, int column); 247 248 /** 249 * Get the value of a column as a char array. 250 * this is the same calling getValue and get the int from the value object 251 */ 252 int getValueInt(TreeIter iter, int column); 253 254 /** 255 * Sets iter to a valid iterator pointing to path. 256 * Params: 257 * iter = The uninitialized GtkTreeIter. 258 * path = The GtkTreePath. 259 * Returns: 260 * TRUE, if iter was set. 261 */ 262 public int getIter(TreeIter iter, TreePath path); 263 264 /** 265 * Initializes and sets value to that at column. 266 * When done with value, g_value_unset() needs to be called 267 * to free any allocated memory. 268 * Params: 269 * iter = The GtkTreeIter. 270 * column = The column to lookup the value at. 271 * value = (inout) (transfer none) An empty GValue to set. 272 */ 273 public Value getValue(TreeIter iter, int column, Value value = null); 274 275 /** 276 */ 277 278 /** */ 279 public static GType getType() 280 { 281 return gtk_tree_model_get_type(); 282 } 283 284 /** 285 * Calls func on each node in model in a depth-first fashion. 286 * 287 * If @func returns %TRUE, then the tree ceases to be walked, 288 * and gtk_tree_model_foreach() returns. 289 * 290 * Params: 291 * func = a function to be called on each row 292 * userData = user data to passed to @func 293 */ 294 public void foreac(GtkTreeModelForeachFunc func, void* userData); 295 296 /** 297 * Returns the type of the column. 298 * 299 * Params: 300 * index = the column index 301 * 302 * Returns: the type of the column 303 */ 304 public GType getColumnType(int index); 305 306 /** 307 * Returns a set of flags supported by this interface. 308 * 309 * The flags are a bitwise combination of #GtkTreeModelFlags. 310 * The flags supported should not change during the lifetime 311 * of the @tree_model. 312 * 313 * Returns: the flags supported by this interface 314 */ 315 public GtkTreeModelFlags getFlags(); 316 317 /** 318 * Initializes @iter with the first iterator in the tree 319 * (the one at the path "0") and returns %TRUE. Returns 320 * %FALSE if the tree is empty. 321 * 322 * Params: 323 * iter = the uninitialized #GtkTreeIter-struct 324 * 325 * Returns: %TRUE, if @iter was set 326 */ 327 public bool getIterFirst(out TreeIter iter); 328 329 /** 330 * Sets @iter to a valid iterator pointing to @path_string, if it 331 * exists. Otherwise, @iter is left invalid and %FALSE is returned. 332 * 333 * Params: 334 * iter = an uninitialized #GtkTreeIter-struct 335 * pathString = a string representation of a #GtkTreePath-struct 336 * 337 * Returns: %TRUE, if @iter was set 338 */ 339 public bool getIterFromString(out TreeIter iter, string pathString); 340 341 /** 342 * Returns the number of columns supported by @tree_model. 343 * 344 * Returns: the number of columns 345 */ 346 public int getNColumns(); 347 348 /** 349 * Returns a newly-created #GtkTreePath-struct referenced by @iter. 350 * 351 * This path should be freed with gtk_tree_path_free(). 352 * 353 * Params: 354 * iter = the #GtkTreeIter-struct 355 * 356 * Returns: a newly-created #GtkTreePath-struct 357 */ 358 public TreePath getPath(TreeIter iter); 359 360 /** 361 * Generates a string representation of the iter. 362 * 363 * This string is a “:” separated list of numbers. 364 * For example, “4:10:0:3” would be an acceptable 365 * return value for this string. 366 * 367 * Params: 368 * iter = a #GtkTreeIter-struct 369 * 370 * Returns: a newly-allocated string. 371 * Must be freed with g_free(). 372 * 373 * Since: 2.2 374 */ 375 public string getStringFromIter(TreeIter iter); 376 377 /** 378 * See gtk_tree_model_get(), this version takes a va_list 379 * for language bindings to use. 380 * 381 * Params: 382 * iter = a row in @tree_model 383 * varArgs = va_list of column/return location pairs 384 */ 385 public void getValist(TreeIter iter, void* varArgs); 386 387 /** 388 * Sets @iter to point to the first child of @parent. 389 * 390 * If @parent has no children, %FALSE is returned and @iter is 391 * set to be invalid. @parent will remain a valid node after this 392 * function has been called. 393 * 394 * If @parent is %NULL returns the first node, equivalent to 395 * `gtk_tree_model_get_iter_first (tree_model, iter);` 396 * 397 * Params: 398 * iter = the new #GtkTreeIter-struct to be set to the child 399 * parent = the #GtkTreeIter-struct, or %NULL 400 * 401 * Returns: %TRUE, if @iter has been set to the first child 402 */ 403 public bool iterChildren(out TreeIter iter, TreeIter parent); 404 405 /** 406 * Returns %TRUE if @iter has children, %FALSE otherwise. 407 * 408 * Params: 409 * iter = the #GtkTreeIter-struct to test for children 410 * 411 * Returns: %TRUE if @iter has children 412 */ 413 public bool iterHasChild(TreeIter iter); 414 415 /** 416 * Returns the number of children that @iter has. 417 * 418 * As a special case, if @iter is %NULL, then the number 419 * of toplevel nodes is returned. 420 * 421 * Params: 422 * iter = the #GtkTreeIter-struct, or %NULL 423 * 424 * Returns: the number of children of @iter 425 */ 426 public int iterNChildren(TreeIter iter); 427 428 /** 429 * Sets @iter to point to the node following it at the current level. 430 * 431 * If there is no next @iter, %FALSE is returned and @iter is set 432 * to be invalid. 433 * 434 * Params: 435 * iter = the #GtkTreeIter-struct 436 * 437 * Returns: %TRUE if @iter has been changed to the next node 438 */ 439 public bool iterNext(TreeIter iter); 440 441 /** 442 * Sets @iter to be the child of @parent, using the given index. 443 * 444 * The first index is 0. If @n is too big, or @parent has no children, 445 * @iter is set to an invalid iterator and %FALSE is returned. @parent 446 * will remain a valid node after this function has been called. As a 447 * special case, if @parent is %NULL, then the @n-th root node 448 * is set. 449 * 450 * Params: 451 * iter = the #GtkTreeIter-struct to set to the nth child 452 * parent = the #GtkTreeIter-struct to get the child from, or %NULL. 453 * n = the index of the desired child 454 * 455 * Returns: %TRUE, if @parent has an @n-th child 456 */ 457 public bool iterNthChild(out TreeIter iter, TreeIter parent, int n); 458 459 /** 460 * Sets @iter to be the parent of @child. 461 * 462 * If @child is at the toplevel, and doesn’t have a parent, then 463 * @iter is set to an invalid iterator and %FALSE is returned. 464 * @child will remain a valid node after this function has been 465 * called. 466 * 467 * @iter will be initialized before the lookup is performed, so @child 468 * and @iter cannot point to the same memory location. 469 * 470 * Params: 471 * iter = the new #GtkTreeIter-struct to set to the parent 472 * child = the #GtkTreeIter-struct 473 * 474 * Returns: %TRUE, if @iter is set to the parent of @child 475 */ 476 public bool iterParent(out TreeIter iter, TreeIter child); 477 478 /** 479 * Sets @iter to point to the previous node at the current level. 480 * 481 * If there is no previous @iter, %FALSE is returned and @iter is 482 * set to be invalid. 483 * 484 * Params: 485 * iter = the #GtkTreeIter-struct 486 * 487 * Returns: %TRUE if @iter has been changed to the previous node 488 * 489 * Since: 3.0 490 */ 491 public bool iterPrevious(TreeIter iter); 492 493 /** 494 * Lets the tree ref the node. 495 * 496 * This is an optional method for models to implement. 497 * To be more specific, models may ignore this call as it exists 498 * primarily for performance reasons. 499 * 500 * This function is primarily meant as a way for views to let 501 * caching models know when nodes are being displayed (and hence, 502 * whether or not to cache that node). Being displayed means a node 503 * is in an expanded branch, regardless of whether the node is currently 504 * visible in the viewport. For example, a file-system based model 505 * would not want to keep the entire file-hierarchy in memory, 506 * just the sections that are currently being displayed by 507 * every current view. 508 * 509 * A model should be expected to be able to get an iter independent 510 * of its reffed state. 511 * 512 * Params: 513 * iter = the #GtkTreeIter-struct 514 */ 515 public void refNode(TreeIter iter); 516 517 /** 518 * Emits the #GtkTreeModel::row-changed signal on @tree_model. 519 * 520 * Params: 521 * path = a #GtkTreePath-struct pointing to the changed row 522 * iter = a valid #GtkTreeIter-struct pointing to the changed row 523 */ 524 public void rowChanged(TreePath path, TreeIter iter); 525 526 /** 527 * Emits the #GtkTreeModel::row-deleted signal on @tree_model. 528 * 529 * This should be called by models after a row has been removed. 530 * The location pointed to by @path should be the location that 531 * the row previously was at. It may not be a valid location anymore. 532 * 533 * Nodes that are deleted are not unreffed, this means that any 534 * outstanding references on the deleted node should not be released. 535 * 536 * Params: 537 * path = a #GtkTreePath-struct pointing to the previous location of 538 * the deleted row 539 */ 540 public void rowDeleted(TreePath path); 541 542 /** 543 * Emits the #GtkTreeModel::row-has-child-toggled signal on 544 * @tree_model. This should be called by models after the child 545 * state of a node changes. 546 * 547 * Params: 548 * path = a #GtkTreePath-struct pointing to the changed row 549 * iter = a valid #GtkTreeIter-struct pointing to the changed row 550 */ 551 public void rowHasChildToggled(TreePath path, TreeIter iter); 552 553 /** 554 * Emits the #GtkTreeModel::row-inserted signal on @tree_model. 555 * 556 * Params: 557 * path = a #GtkTreePath-struct pointing to the inserted row 558 * iter = a valid #GtkTreeIter-struct pointing to the inserted row 559 */ 560 public void rowInserted(TreePath path, TreeIter iter); 561 562 /** 563 * Emits the #GtkTreeModel::rows-reordered signal on @tree_model. 564 * 565 * This should be called by models when their rows have been 566 * reordered. 567 * 568 * Params: 569 * path = a #GtkTreePath-struct pointing to the tree node whose children 570 * have been reordered 571 * iter = a valid #GtkTreeIter-struct pointing to the node whose children 572 * have been reordered, or %NULL if the depth of @path is 0 573 * newOrder = an array of integers mapping the current position of 574 * each child to its old position before the re-ordering, 575 * i.e. @new_order`[newpos] = oldpos` 576 */ 577 public void rowsReordered(TreePath path, TreeIter iter, int* newOrder); 578 579 /** 580 * Emits the #GtkTreeModel::rows-reordered signal on @tree_model. 581 * 582 * This should be called by models when their rows have been 583 * reordered. 584 * 585 * Params: 586 * path = a #GtkTreePath-struct pointing to the tree node whose children 587 * have been reordered 588 * iter = a valid #GtkTreeIter-struct pointing to the node 589 * whose children have been reordered, or %NULL if the depth 590 * of @path is 0 591 * newOrder = an array of integers 592 * mapping the current position of each child to its old 593 * position before the re-ordering, 594 * i.e. @new_order`[newpos] = oldpos` 595 * 596 * Since: 3.10 597 */ 598 public void rowsReorderedWithLength(TreePath path, TreeIter iter, int[] newOrder); 599 600 /** 601 * Lets the tree unref the node. 602 * 603 * This is an optional method for models to implement. 604 * To be more specific, models may ignore this call as it exists 605 * primarily for performance reasons. For more information on what 606 * this means, see gtk_tree_model_ref_node(). 607 * 608 * Please note that nodes that are deleted are not unreffed. 609 * 610 * Params: 611 * iter = the #GtkTreeIter-struct 612 */ 613 public void unrefNode(TreeIter iter); 614 615 /** 616 * This signal is emitted when a row in the model has changed. 617 * 618 * Params: 619 * path = a #GtkTreePath-struct identifying the changed row 620 * iter = a valid #GtkTreeIter-struct pointing to the changed row 621 */ 622 gulong addOnRowChanged(void delegate(TreePath, TreeIter, TreeModelIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0); 623 624 /** 625 * This signal is emitted when a row has been deleted. 626 * 627 * Note that no iterator is passed to the signal handler, 628 * since the row is already deleted. 629 * 630 * This should be called by models after a row has been removed. 631 * The location pointed to by @path should be the location that 632 * the row previously was at. It may not be a valid location anymore. 633 * 634 * Params: 635 * path = a #GtkTreePath-struct identifying the row 636 */ 637 gulong addOnRowDeleted(void delegate(TreePath, TreeModelIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0); 638 639 /** 640 * This signal is emitted when a row has gotten the first child 641 * row or lost its last child row. 642 * 643 * Params: 644 * path = a #GtkTreePath-struct identifying the row 645 * iter = a valid #GtkTreeIter-struct pointing to the row 646 */ 647 gulong addOnRowHasChildToggled(void delegate(TreePath, TreeIter, TreeModelIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0); 648 649 /** 650 * This signal is emitted when a new row has been inserted in 651 * the model. 652 * 653 * Note that the row may still be empty at this point, since 654 * it is a common pattern to first insert an empty row, and 655 * then fill it with the desired values. 656 * 657 * Params: 658 * path = a #GtkTreePath-struct identifying the new row 659 * iter = a valid #GtkTreeIter-struct pointing to the new row 660 */ 661 gulong addOnRowInserted(void delegate(TreePath, TreeIter, TreeModelIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0); 662 663 /** 664 * This signal is emitted when the children of a node in the 665 * #GtkTreeModel have been reordered. 666 * 667 * Note that this signal is not emitted 668 * when rows are reordered by DND, since this is implemented 669 * by removing and then reinserting the row. 670 * 671 * Params: 672 * path = a #GtkTreePath-struct identifying the tree node whose children 673 * have been reordered 674 * iter = a valid #GtkTreeIter-struct pointing to the node whose children 675 * have been reordered, or %NULL if the depth of @path is 0 676 * newOrder = an array of integers mapping the current position 677 * of each child to its old position before the re-ordering, 678 * i.e. @new_order`[newpos] = oldpos` 679 */ 680 gulong addOnRowsReordered(void delegate(TreePath, TreeIter, void*, TreeModelIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0); 681 }