1 // Generated by gmmproc 2.60.0 -- DO NOT MODIFY! 2 #ifndef _GTKMM_TREEMODEL_H 3 #define _GTKMM_TREEMODEL_H 4 5 6 #include <glibmm/ustring.h> 7 #include <sigc++/sigc++.h> 8 9 /* 10 * Copyright (C) 1998-2002 The gtkmm Development Team 11 * 12 * This library is free software; you can redistribute it and/or 13 * modify it under the terms of the GNU Lesser General Public 14 * License as published by the Free Software Foundation; either 15 * version 2.1 of the License, or (at your option) any later version. 16 * 17 * This library is distributed in the hope that it will be useful, 18 * but WITHOUT ANY WARRANTY; without even the implied warranty of 19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 20 * Lesser General Public License for more details. 21 * 22 * You should have received a copy of the GNU Lesser General Public 23 * License along with this library; if not, write to the Free Software 24 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 25 */ 26 27 #include <vector> 28 29 #include <gtk/gtk.h> 30 #include <glibmm/interface.h> 31 #include <gtkmm/treeiter.h> 32 #include <gtkmm/treemodelcolumn.h> 33 34 35 #ifndef DOXYGEN_SHOULD_SKIP_THIS 36 using GtkTreeModel = struct _GtkTreeModel; 37 using GtkTreeModelClass = struct _GtkTreeModelClass; 38 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ 39 40 41 #ifndef DOXYGEN_SHOULD_SKIP_THIS 42 namespace Gtk 43 { class TreeModel_Class; } // namespace Gtk 44 #endif // DOXYGEN_SHOULD_SKIP_THIS 45 46 namespace Gtk 47 { 48 49 class TreeModelFilter; 50 class TreeModelSort; 51 class TreePath; 52 class TreeRowReference; 53 54 55 /** @addtogroup gtkmmEnums gtkmm Enums and Flags */ 56 57 /** 58 * @var TreeModelFlags TREE_MODEL_ITERS_PERSIST 59 * Iterators survive all signals 60 * emitted by the tree. 61 * 62 * @var TreeModelFlags TREE_MODEL_LIST_ONLY 63 * The model is a list only, and never 64 * has children. 65 * 66 * @enum TreeModelFlags 67 * 68 * These flags indicate various properties of a Gtk::TreeModel. 69 * 70 * They are returned by Gtk::TreeModel::get_flags(), and must be 71 * static for the lifetime of the object. A more complete description 72 * of Gtk::TREE_MODEL_ITERS_PERSIST can be found in the overview of 73 * this section. 74 * 75 * @ingroup gtkmmEnums 76 * @par Bitwise operators: 77 * <tt>%TreeModelFlags operator|(TreeModelFlags, TreeModelFlags)</tt><br> 78 * <tt>%TreeModelFlags operator&(TreeModelFlags, TreeModelFlags)</tt><br> 79 * <tt>%TreeModelFlags operator^(TreeModelFlags, TreeModelFlags)</tt><br> 80 * <tt>%TreeModelFlags operator~(TreeModelFlags)</tt><br> 81 * <tt>%TreeModelFlags& operator|=(TreeModelFlags&, TreeModelFlags)</tt><br> 82 * <tt>%TreeModelFlags& operator&=(TreeModelFlags&, TreeModelFlags)</tt><br> 83 * <tt>%TreeModelFlags& operator^=(TreeModelFlags&, TreeModelFlags)</tt><br> 84 */ 85 enum TreeModelFlags 86 { 87 TREE_MODEL_ITERS_PERSIST = 1 << 0, 88 TREE_MODEL_LIST_ONLY = 1 << 1 89 }; 90 91 /** @ingroup gtkmmEnums */ 92 inline TreeModelFlags operator|(TreeModelFlags lhs, TreeModelFlags rhs) 93 { return static_cast<TreeModelFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); } 94 95 /** @ingroup gtkmmEnums */ 96 inline TreeModelFlags operator&(TreeModelFlags lhs, TreeModelFlags rhs) 97 { return static_cast<TreeModelFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); } 98 99 /** @ingroup gtkmmEnums */ 100 inline TreeModelFlags operator^(TreeModelFlags lhs, TreeModelFlags rhs) 101 { return static_cast<TreeModelFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); } 102 103 /** @ingroup gtkmmEnums */ 104 inline TreeModelFlags operator~(TreeModelFlags flags) 105 { return static_cast<TreeModelFlags>(~static_cast<unsigned>(flags)); } 106 107 /** @ingroup gtkmmEnums */ 108 inline TreeModelFlags& operator|=(TreeModelFlags& lhs, TreeModelFlags rhs) 109 { return (lhs = static_cast<TreeModelFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); } 110 111 /** @ingroup gtkmmEnums */ 112 inline TreeModelFlags& operator&=(TreeModelFlags& lhs, TreeModelFlags rhs) 113 { return (lhs = static_cast<TreeModelFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); } 114 115 /** @ingroup gtkmmEnums */ 116 inline TreeModelFlags& operator^=(TreeModelFlags& lhs, TreeModelFlags rhs) 117 { return (lhs = static_cast<TreeModelFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); } 118 119 } // namespace Gtk 120 121 #ifndef DOXYGEN_SHOULD_SKIP_THIS 122 namespace Glib 123 { 124 125 template <> 126 class Value<Gtk::TreeModelFlags> : public Glib::Value_Flags<Gtk::TreeModelFlags> 127 { 128 public: 129 static GType value_type() G_GNUC_CONST; 130 }; 131 132 } // namespace Glib 133 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ 134 135 namespace Gtk 136 { 137 138 139 //TODO: Remove any mention of null arguments from the method documentation, by adding overrides in gtk_docs_override.xml. 140 /** This class defines a generic tree interface for use by the Gtk::TreeView widget. 141 * @ingroup TreeView 142 * 143 * It is is designed to be usable with any appropriate data structure. The 144 * programmer just has to implement this interface on their own data type for 145 * it to be viewable by a Gtk::TreeView widget. 146 * 147 * The model is represented as a hierarchical tree of strongly-typed, columned 148 * data. In other words, the model can be seen as a tree where every node has 149 * different values depending on which column is being queried. The type of 150 * data found in a column is determined by TreeModel::Column<> templates. 151 * The types are homogeneous per column across all nodes. It is important to note that this 152 * interface only provides a way of examining a model and observing changes. 153 * The implementation of each individual model decides how and if changes are 154 * made. 155 * 156 * In order to make life simpler for programmers who do not need to write their 157 * own specialized model, two generic models are provided - the Gtk::TreeStore 158 * and the Gtk::ListStore. To use these, the developer simply pushes data into 159 * these models as necessary. These models provide the data structure as well 160 * as all appropriate tree interfaces. As a result, implementing drag and drop, 161 * sorting, and storing data is trivial. For the vast majority of trees and 162 * lists, these two models are sufficient. 163 * 164 * Models are accessed on a node/column level of granularity. One can query for 165 * the value of a model at a certain node and a certain column on that node. 166 * There are two structures used to reference a particular node in a model. 167 * They are the @link Gtk::TreePath Path@endlink and the iterator. Most of the interface consists of 168 * operations on an @link Gtk::TreeIter iterator@endlink. 169 * 170 * A @link Gtk::TreePath Gtk::TreeModel::Path@endlink is essentially a potential node. It is a location on a model that may 171 * or may not actually correspond to a node on a specific model. 172 * 173 * By contrast, an @link Gtk::TreeIter Gtk::TreeModel::iterator@endlink is a reference to a specific node on a specific 174 * model. One can convert a path to an @link Gtk::TreeIter iterator@endlink by calling Gtk::TreeModel::get_iter(). 175 * These iterators are the primary way of accessing a model and are similar to the iterators 176 * used by Gtk::TextBuffer. The model interface defines a set of operations 177 * using them for navigating the model. 178 * 179 * The @link Gtk::TreeRowReference RowReference@endlink is also useful, because it remains 180 * valid as long as there is an existing row pointed to by it's path. You can convert between RowReferences and iterators and @link Gtk::TreePath Path@endlink s. 181 */ 182 183 class TreeModel : public Glib::Interface 184 { 185 186 #ifndef DOXYGEN_SHOULD_SKIP_THIS 187 188 public: 189 using CppObjectType = TreeModel; 190 using CppClassType = TreeModel_Class; 191 using BaseObjectType = GtkTreeModel; 192 using BaseClassType = GtkTreeModelIface; 193 194 // noncopyable 195 TreeModel(const TreeModel&) = delete; 196 TreeModel& operator=(const TreeModel&) = delete; 197 198 private: 199 friend class TreeModel_Class; 200 static CppClassType treemodel_class_; 201 202 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ 203 protected: 204 /** 205 * You should derive from this class to use it. 206 */ 207 TreeModel(); 208 209 #ifndef DOXYGEN_SHOULD_SKIP_THIS 210 /** Called by constructors of derived classes. Provide the result of 211 * the Class init() function to ensure that it is properly 212 * initialized. 213 * 214 * @param interface_class The Class object for the derived type. 215 */ 216 explicit TreeModel(const Glib::Interface_Class& interface_class); 217 218 public: 219 // This is public so that C++ wrapper instances can be 220 // created for C instances of unwrapped types. 221 // For instance, if an unexpected C type implements the C interface. 222 explicit TreeModel(GtkTreeModel* castitem); 223 224 protected: 225 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ 226 227 public: 228 229 TreeModel(TreeModel&& src) noexcept; 230 TreeModel& operator=(TreeModel&& src) noexcept; 231 232 ~TreeModel() noexcept override; 233 234 static void add_interface(GType gtype_implementer); 235 236 /** Get the GType for this class, for use with the underlying GObject type system. 237 */ 238 static GType get_type() G_GNUC_CONST; 239 240 #ifndef DOXYGEN_SHOULD_SKIP_THIS 241 static GType get_base_type() G_GNUC_CONST; 242 #endif 243 244 ///Provides access to the underlying C GObject. gobj()245 GtkTreeModel* gobj() { return reinterpret_cast<GtkTreeModel*>(gobject_); } 246 247 ///Provides access to the underlying C GObject. gobj()248 const GtkTreeModel* gobj() const { return reinterpret_cast<GtkTreeModel*>(gobject_); } 249 250 private: 251 252 253 public: 254 typedef TreeModelColumnRecord ColumnRecord; 255 256 typedef TreeNodeChildren Children; 257 typedef Children::iterator iterator; 258 typedef Children::const_iterator const_iterator; 259 260 // Reverse iterator: https://bugzilla.gnome.org/show_bug.cgi?id=554889 261 #ifndef GTKMM_DISABLE_DEPRECATED 262 263 /** @deprecated This reverse_iterator has never worked, 264 * use the normal (forward) iterator instead. 265 */ 266 typedef Children::reverse_iterator reverse_iterator; 267 268 /** @deprecated This reverse_iterator has never worked, 269 * use the normal (forward) iterator instead. 270 */ 271 typedef Children::const_reverse_iterator const_reverse_iterator; 272 #endif // GTKMM_DISABLE_DEPRECATED 273 274 275 typedef TreeRow Row; 276 typedef TreePath Path; 277 typedef TreeRowReference RowReference; 278 279 280 //These are part of GtkTreeModelFilter or GtkTreeModelSort, not GtkTreeModel: 281 282 283 /** Returns a valid iterator pointing to @a path. 284 * 285 * @param path The @link Gtk::TreePath Gtk::TreeModel::Path@endlink. 286 * @result A valid iterator pointing to the path, or an invalid iterator if that is not possible. 287 */ 288 iterator get_iter(const Path& path); 289 //TODO: Add const_iterator get_iter(const Path& path) const; 290 //Implement a const_iterator? 291 292 /** Returns a valid iterator pointing to @a path_string. 293 * 294 * @param path_string The path, as a string representation. 295 * @result A valid iterator pointing to the path, or an invalid iterator if that is not possible. 296 */ 297 iterator get_iter(const Glib::ustring& path_string); 298 //TODO: Implement a const_iterator? const_iterator get_iter(const Glib::ustring& path_string) const; 299 300 ///This returns an STL-like container API, for iterating over the rows. 301 Children children(); 302 303 //TODO: Return a real TreeNodeChildren (a container of const_iterators), when we have a real const_iterator. 304 ///This returns an STL-like container API, for iterating over the rows. 305 Children children() const; 306 307 308 /** The type of callback slot used by foreach_iter(). 309 * 310 * If the callback function returns true, then the tree ceases to be walked, 311 * and foreach_iter() returns. 312 * 313 * For example: bool on_foreach_iter(const Gtk::TreeModel::iterator& iter); 314 */ 315 typedef sigc::slot<bool, const TreeModel::iterator&> SlotForeachIter; 316 317 /** Calls a callback of type @link Gtk::TreeModel::SlotForeachIter 318 * SlotForeachIter @endlink on each node in the model in a depth-first 319 * fashion. 320 * 321 * If the callback function returns true, then the tree ceases to be walked, 322 * and foreach_iter() returns. 323 * 324 * @param slot The function to call for each selected node. 325 */ 326 void foreach_iter(const SlotForeachIter& slot); 327 328 /** The type of callback slot used by foreach_path(). 329 * 330 * For example: bool on_foreach_path(const Gtk::TreeModel::Path& path); 331 * 332 * If the callback function returns true, then the tree ceases to be walked, 333 * and foreach_path() returns. 334 */ 335 typedef sigc::slot<bool, const TreeModel::Path&> SlotForeachPath; 336 337 /** Calls a callback of type @link Gtk::TreeModel::SlotForeachPath 338 * SlotForeachPath @endlink on each node in the model in a depth-first 339 * fashion. 340 * 341 * If the callback function returns true, then the tree ceases to be walked, 342 * and foreach_path() returns. 343 * 344 * @param slot The function to call for each selected node. 345 */ 346 void foreach_path(const SlotForeachPath& slot); 347 348 /** The type of callback slot used by foreach(). 349 * 350 * For example: bool on_foreach(const Gtk::TreeModel::Path& path, const Gtk::TreeModel::iterator& iter); 351 * 352 * If the callback function returns true, then the tree ceases to be walked, 353 * and foreach() returns. 354 */ 355 typedef sigc::slot<bool, const TreeModel::Path&, const TreeModel::iterator&> SlotForeachPathAndIter; 356 357 /** Calls a callback of type @link Gtk::TreeModel::SlotForeachPathAndIter 358 * SlotForeachPathAndIter @endlink on each node in the model in a depth-first 359 * fashion. 360 * 361 * If the callback function returns true, then the tree ceases to be walked, 362 * and foreach() returns. 363 * 364 * @param slot The function to call for each selected node. 365 */ 366 void foreach(const SlotForeachPathAndIter& slot); 367 368 369 /** Returns a set of flags supported by this interface. 370 * 371 * The flags are a bitwise combination of Gtk::TreeModelFlags. 372 * The flags supported should not change during the lifetime 373 * of the @a tree_model. 374 * 375 * @return The flags supported by this interface. 376 */ 377 TreeModelFlags get_flags() const; 378 379 /** Returns the number of columns supported by @a tree_model. 380 * 381 * @return The number of columns. 382 */ 383 int get_n_columns() const; 384 385 /** Returns the type of the column. 386 * 387 * @param index The column index. 388 * @return The type of the column. 389 */ 390 GType get_column_type(int index) const; 391 //TODO: A C++-type version of get_column_type()? 392 393 394 /** Returns a Gtk::TreePath referenced by @a iter. 395 * 396 * @param iter The Gtk::TreeIter. 397 * @return A Gtk::TreePath. 398 */ 399 TreeModel::Path get_path(const iterator& iter) const; 400 401 402 /** Emits the Gtk::TreeModel::signal_row_changed() signal on @a tree_model. 403 * 404 * @param path A Gtk::TreePath-struct pointing to the changed row. 405 * @param iter A valid Gtk::TreeIter-struct pointing to the changed row. 406 */ 407 void row_changed(const Path& path, const iterator& iter); 408 409 /** Emits the Gtk::TreeModel::signal_row_inserted() signal on @a tree_model. 410 * 411 * @param path A Gtk::TreePath-struct pointing to the inserted row. 412 * @param iter A valid Gtk::TreeIter-struct pointing to the inserted row. 413 */ 414 void row_inserted(const Path& path, const iterator& iter); 415 416 /** Emits the Gtk::TreeModel::signal_row_has_child_toggled() signal on 417 * @a tree_model. This should be called by models after the child 418 * state of a node changes. 419 * 420 * @param path A Gtk::TreePath-struct pointing to the changed row. 421 * @param iter A valid Gtk::TreeIter-struct pointing to the changed row. 422 */ 423 void row_has_child_toggled(const Path& path, const iterator& iter); 424 425 /** Emits the Gtk::TreeModel::signal_row_deleted() signal on @a tree_model. 426 * 427 * This should be called by models after a row has been removed. 428 * The location pointed to by @a path should be the location that 429 * the row previously was at. It may not be a valid location anymore. 430 * 431 * Nodes that are deleted are not unreffed, this means that any 432 * outstanding references on the deleted node should not be released. 433 * 434 * @param path A Gtk::TreePath-struct pointing to the previous location of 435 * the deleted row. 436 */ 437 void row_deleted(const Path& path); 438 439 /** Emits the "rows_reordered" signal on the tree model. This should be called by 440 * custom models when their rows have been reordered. 441 * 442 * @param path A tree path pointing to the tree node whose children have been reordered. 443 * @param iter A valid iterator pointing to the node whose children have been reordered. See also, rows_reordered(const Path& path, const std::vector<int>& new_order), if the path has a depth of 0. 444 * @param new_order An array of integers mapping the current position of each child 445 * to its old position before the re-ordering, i.e. @a new_order<literal>[newpos] = oldpos. 446 */ 447 void rows_reordered(const Path& path, const iterator& iter, const std::vector<int>& new_order); 448 449 450 /** Emits the "rows_reordered" signal on the tree model. This should be called by 451 * custom models when their rows have been reordered. This method overload is for nodes whose 452 * path has a depth of 0. 453 * @newin{2,10} 454 * 455 * @param path A tree path pointing to the tree node whose children have been reordered. 456 * @param new_order An array of integers mapping the current position of each child 457 * to its old position before the re-ordering, i.e. @a new_order<literal>[newpos] = oldpos. 458 */ 459 void rows_reordered(const Path& path, const std::vector<int>& new_order); 460 461 462 /** Emits the Gtk::TreeModel::signal_rows_reordered() signal on @a tree_model. 463 * 464 * This should be called by models when their rows have been 465 * reordered. 466 * 467 * @param path A Gtk::TreePath pointing to the tree node whose children 468 * have been reordered. 469 * @param iter A valid Gtk::TreeIter pointing to the node whose children 470 * have been reordered, or <tt>nullptr</tt> if the depth of @a path is 0. 471 * @param new_order An array of integers mapping the current position of 472 * each child to its old position before the re-ordering, 473 * i.e. new_order<tt>[newpos] = oldpos</tt>. 474 */ 475 void rows_reordered(const Path& path, const iterator& iter, int* new_order); 476 477 478 /** Generates a string representation of the iter. 479 * 480 * This string is a “:” separated list of numbers. 481 * For example, “4:10:0:3” would be an acceptable 482 * return value for this string. 483 * 484 * @newin{2,2} 485 * 486 * @param iter An Gtk::TreeIter. 487 * @return The string. 488 */ 489 Glib::ustring get_string(const iterator& iter) const; 490 491 492 /** 493 * @par Slot Prototype: 494 * <tt>void on_my_%row_changed(const TreeModel::Path& path, const TreeModel::iterator& iter)</tt> 495 * 496 * Flags: Run Last 497 * 498 * This signal is emitted when a row in the model has changed. 499 * 500 * @param path A Gtk::TreePath-struct identifying the changed row. 501 * @param iter A valid Gtk::TreeIter-struct pointing to the changed row. 502 */ 503 504 Glib::SignalProxy< void,const TreeModel::Path&,const TreeModel::iterator& > signal_row_changed(); 505 506 507 /** 508 * @par Slot Prototype: 509 * <tt>void on_my_%row_inserted(const TreeModel::Path& path, const TreeModel::iterator& iter)</tt> 510 * 511 * Flags: Run First 512 * 513 * This signal is emitted when a new row has been inserted in 514 * the model. 515 * 516 * Note that the row may still be empty at this point, since 517 * it is a common pattern to first insert an empty row, and 518 * then fill it with the desired values. 519 * 520 * @param path A Gtk::TreePath-struct identifying the new row. 521 * @param iter A valid Gtk::TreeIter-struct pointing to the new row. 522 */ 523 524 Glib::SignalProxy< void,const TreeModel::Path&,const TreeModel::iterator& > signal_row_inserted(); 525 526 527 /** 528 * @par Slot Prototype: 529 * <tt>void on_my_%row_has_child_toggled(const TreeModel::Path& path, const TreeModel::iterator& iter)</tt> 530 * 531 * Flags: Run Last 532 * 533 * This signal is emitted when a row has gotten the first child 534 * row or lost its last child row. 535 * 536 * @param path A Gtk::TreePath-struct identifying the row. 537 * @param iter A valid Gtk::TreeIter-struct pointing to the row. 538 */ 539 540 Glib::SignalProxy< void,const TreeModel::Path&,const TreeModel::iterator& > signal_row_has_child_toggled(); 541 542 543 /** 544 * @par Slot Prototype: 545 * <tt>void on_my_%row_deleted(const TreeModel::Path& path)</tt> 546 * 547 * Flags: Run First 548 * 549 * This signal is emitted when a row has been deleted. 550 * 551 * Note that no iterator is passed to the signal handler, 552 * since the row is already deleted. 553 * 554 * This should be called by models after a row has been removed. 555 * The location pointed to by @a path should be the location that 556 * the row previously was at. It may not be a valid location anymore. 557 * 558 * @param path A Gtk::TreePath-struct identifying the row. 559 */ 560 561 Glib::SignalProxy< void,const TreeModel::Path& > signal_row_deleted(); 562 563 564 /** 565 * @par Slot Prototype: 566 * <tt>void on_my_%rows_reordered(const TreeModel::Path& path, const TreeModel::iterator& iter, int* new_order)</tt> 567 * 568 * Flags: Run First 569 * 570 * This signal is emitted when the children of a node in the 571 * Gtk::TreeModel have been reordered. 572 * 573 * Note that this signal is not emitted 574 * when rows are reordered by DND, since this is implemented 575 * by removing and then reinserting the row. 576 * 577 * @param path A Gtk::TreePath-struct identifying the tree node whose children 578 * have been reordered. 579 * @param iter A valid Gtk::TreeIter-struct pointing to the node whose children 580 * have been reordered, or <tt>nullptr</tt> if the depth of @a path is 0. 581 * @param new_order An array of integers mapping the current position 582 * of each child to its old position before the re-ordering, 583 * i.e. @a new_order`[newpos] = oldpos`. 584 */ 585 586 Glib::SignalProxy< void,const TreeModel::Path&,const TreeModel::iterator&,int* > signal_rows_reordered(); 587 588 589 protected: 590 virtual TreeModelFlags get_flags_vfunc() const; 591 592 virtual int get_n_columns_vfunc() const; 593 594 virtual GType get_column_type_vfunc(int index) const; 595 596 597 //These are only for deriving new TreeModels, which isn't very common or easy: 598 599 /** Override and implement this in a derived TreeModel class. 600 * Sets @a iter_next to refer to the node following @a iter it at the current level. 601 * If there is no next iter, false is returned and iter_next is set to be invalid. 602 * 603 * @param iter An iterator. 604 * @param iter_next An iterator that will be set to refer to the next node, or will be set as invalid. 605 * @result true if the operation was possible. 606 */ 607 virtual bool iter_next_vfunc(const iterator& iter, iterator& iter_next) const; 608 609 /** Override and implement this in a derived TreeModel class. 610 * Sets @a iter to a valid iterator pointing to @a path 611 * 612 * @param path An path to a node. 613 * @param iter An iterator that will be set to refer to a node to the path, or will be set as invalid. 614 * @result true if the operation was possible. 615 */ 616 virtual bool get_iter_vfunc(const Path& path, iterator& iter) const; 617 618 /** Override and implement this in a derived TreeModel class. 619 * Sets @a iter to refer to the first child of @a parent. If @a parent has no children, 620 * false is returned and @a iter is set to be invalid. 621 * 622 * @param parent An iterator. 623 * @param iter An iterator that will be set to refer to the firt child node, or will be set as invalid. 624 * @result true if the operation was possible. 625 */ 626 virtual bool iter_children_vfunc(const iterator& parent, iterator& iter) const; 627 628 /** Override and implement this in a derived TreeModel class. 629 * Sets @a iter to be the parent of @a child. If @a child is at the toplevel, and 630 * doesn't have a parent, then @a iter is set to an invalid iterator and false 631 * is returned. 632 * 633 * @param child An iterator. 634 * @param iter An iterator that will be set to refer to the parent node, or will be set as invalid. 635 * @result true if the operation was possible. 636 */ 637 virtual bool iter_parent_vfunc(const iterator& child, iterator& iter) const; 638 639 /** Override and implement this in a derived TreeModel class. 640 * Sets @a iter to be the child of @a parent using the given index. The first 641 * index is 0. If @a n is too big, or @a parent has no children, @a iter is set 642 * to an invalid iterator and false is returned. 643 * See also iter_nth_root_child_vfunc() 644 * 645 * @param parent An iterator. 646 * @param n The index of the child node to which @a iter should be set. 647 * @param iter An iterator that will be set to refer to the nth node, or will be set as invalid. 648 * @result true if the operation was possible. 649 */ 650 virtual bool iter_nth_child_vfunc(const iterator& parent, int n, iterator& iter) const; 651 652 /** Override and implement this in a derived TreeModel class. 653 * Sets @a iter to be the child of at the root level using the given index. The first 654 * index is 0. If @a n is too big, or if there are no children, @a iter is set 655 * to an invalid iterator and false is returned. 656 * See also iter_nth_child_vfunc(). 657 * 658 * @param n The index of the child node to which @a iter should be set. 659 * @param iter An iterator that will be set to refer to the nth node, or will be set as invalid. 660 * @result true if the operation was possible. 661 */ 662 virtual bool iter_nth_root_child_vfunc(int n, iterator& iter) const; 663 664 665 /** Override and implement this in a derived TreeModel class. 666 * Returns true if @a iter has children, false otherwise. 667 * 668 * @param iter The iterator to test for children. 669 * @result true if @a iter has children. 670 */ 671 virtual bool iter_has_child_vfunc(const iterator& iter) const; 672 673 674 /** Override and implement this in a derived TreeModel class. 675 * Returns the number of children that @a iter has. 676 * See also iter_n_root_children_vfunc(). 677 * 678 * @param iter The iterator to test for children. 679 * @result The number of children of @a iter. 680 */ 681 virtual int iter_n_children_vfunc(const iterator& iter) const; 682 683 /** Override and implement this in a derived TreeModel class. 684 * Returns the number of toplevel nodes. 685 * See also iter_n_children(). 686 * 687 * @result The number of children at the root level. 688 */ 689 virtual int iter_n_root_children_vfunc() const; 690 691 /** Override and implement this in a derived TreeModel class. 692 * Lets the tree ref the node. This is an optional method for models to 693 * implement. To be more specific, models may ignore this call as it exists 694 * primarily for performance reasons. 695 * 696 * This function is primarily meant as a way for views to let caching model know 697 * when nodes are being displayed (and hence, whether or not to cache that 698 * node.) For example, a file-system based model would not want to keep the 699 * entire file-hierarchy in memory, just the sections that are currently being 700 * displayed by every current view. 701 * 702 * A model should be expected to be able to get an iter independent of its 703 * reffed state. 704 * 705 * @param iter the iterator. 706 */ 707 virtual void ref_node_vfunc(const iterator& iter) const; 708 709 710 /** Override and implement this in a derived TreeModel class. 711 * Lets the tree unref the node. This is an optional method for models to 712 * implement. To be more specific, models may ignore this call as it exists 713 * primarily for performance reasons. 714 * 715 * For more information on what this means, see unref_node_vfunc(). 716 * Please note that nodes that are deleted are not unreffed. 717 * 718 * @param iter the iterator. 719 */ 720 virtual void unref_node_vfunc(const iterator& iter) const; 721 722 723 /** Override and implement this in a derived TreeModel class. 724 * Returns a Path referenced by @a iter. 725 * 726 * @param iter The iterator. 727 * @result The path. 728 */ 729 730 731 virtual TreeModel::Path get_path_vfunc(const iterator& iter) const; 732 733 734 /** Override and implement this in a derived TreeModel class. 735 * Initializes and sets @a value to that at @a column. 736 * 737 * @param iter The iterator. 738 * @param column The column to lookup the value at. 739 * @param value An empty Glib:Value to set. 740 */ 741 virtual void get_value_vfunc(const iterator& iter, int column, Glib::ValueBase& value) const; 742 743 744 //Called by TreeRow, which is a friend class: 745 //The comment about row_changed() in the documentation is based on my reading of the source of 746 //gtk_list_store_set_value() and gtk_tree_store_set_value(). murrayc 747 /** Override and implement this in a derived TreeModel class, so that Row::operator() and 748 * Row::set_value() work. 749 * Your implementation of set_value_impl() should call row_changed() after changing the value. 750 */ 751 virtual void set_value_impl(const iterator& row, int column, const Glib::ValueBase& value); 752 753 //This might not need to be virtual, but it's not a big deal. murrayc. 754 virtual void get_value_impl(const iterator& row, int column, Glib::ValueBase& value) const; 755 756 friend class Gtk::TreeModelFilter; 757 friend class Gtk::TreeModelSort; 758 friend class Gtk::TreeRow; 759 friend class Gtk::TreeIter; 760 761 762 public: 763 764 public: 765 //C++ methods used to invoke GTK+ virtual functions: 766 767 protected: 768 //GTK+ Virtual Functions (override these to change behaviour): 769 770 //Default Signal Handlers:: 771 /// This is a default handler for the signal signal_row_changed(). 772 virtual void on_row_changed(const TreeModel::Path& path, const TreeModel::iterator& iter); 773 /// This is a default handler for the signal signal_row_inserted(). 774 virtual void on_row_inserted(const TreeModel::Path& path, const TreeModel::iterator& iter); 775 /// This is a default handler for the signal signal_row_has_child_toggled(). 776 virtual void on_row_has_child_toggled(const TreeModel::Path& path, const TreeModel::iterator& iter); 777 /// This is a default handler for the signal signal_row_deleted(). 778 virtual void on_row_deleted(const TreeModel::Path& path); 779 /// This is a default handler for the signal signal_rows_reordered(). 780 virtual void on_rows_reordered(const TreeModel::Path& path, const TreeModel::iterator& iter, int* new_order); 781 782 783 }; 784 785 } // namespace Gtk 786 787 788 namespace Glib 789 { 790 /** A Glib::wrap() method for this object. 791 * 792 * @param object The C instance. 793 * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref. 794 * @result A C++ instance that wraps this C instance. 795 * 796 * @relates Gtk::TreeModel 797 */ 798 Glib::RefPtr<Gtk::TreeModel> wrap(GtkTreeModel* object, bool take_copy = false); 799 800 } // namespace Glib 801 802 803 #endif /* _GTKMM_TREEMODEL_H */ 804 805