2
// Generated by gtkmmproc -- DO NOT MODIFY!
3
#ifndef _GTKMM_TREEMODEL_H
4
#define _GTKMM_TREEMODEL_H
9
/* $Id: treemodel.hg,v 1.25 2006/05/10 20:59:28 murrayc Exp $ */
11
/* Copyright (C) 1998-2002 The gtkmm Development Team
13
* This library is free software; you can redistribute it and/or
14
* modify it under the terms of the GNU Lesser General Public
15
* License as published by the Free Software Foundation; either
16
* version 2.1 of the License, or (at your option) any later version.
18
* This library is distributed in the hope that it will be useful,
19
* but WITHOUT ANY WARRANTY; without even the implied warranty of
20
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21
* Lesser General Public License for more details.
23
* You should have received a copy of the GNU Lesser General Public
24
* License along with this library; if not, write to the Free
25
* Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
28
#include <glibmm/interface.h>
29
#include <gtkmm/treeiter.h>
32
#ifndef DOXYGEN_SHOULD_SKIP_THIS
33
typedef struct _GtkTreeModel GtkTreeModel;
34
typedef struct _GtkTreeModelClass GtkTreeModelClass;
35
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
39
{ class TreeModel_Class; } // namespace Gtk
45
class TreeRowReference;
48
/** @addtogroup gtkmmEnums gtkmm Enums and Flags */
52
* @par Bitwise operators:
53
* <tt>%TreeModelFlags operator|(TreeModelFlags, TreeModelFlags)</tt><br>
54
* <tt>%TreeModelFlags operator&(TreeModelFlags, TreeModelFlags)</tt><br>
55
* <tt>%TreeModelFlags operator^(TreeModelFlags, TreeModelFlags)</tt><br>
56
* <tt>%TreeModelFlags operator~(TreeModelFlags)</tt><br>
57
* <tt>%TreeModelFlags& operator|=(TreeModelFlags&, TreeModelFlags)</tt><br>
58
* <tt>%TreeModelFlags& operator&=(TreeModelFlags&, TreeModelFlags)</tt><br>
59
* <tt>%TreeModelFlags& operator^=(TreeModelFlags&, TreeModelFlags)</tt><br>
63
TREE_MODEL_ITERS_PERSIST = 1 << 0,
64
TREE_MODEL_LIST_ONLY = 1 << 1
67
/** @ingroup gtkmmEnums */
68
inline TreeModelFlags operator|(TreeModelFlags lhs, TreeModelFlags rhs)
69
{ return static_cast<TreeModelFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); }
71
/** @ingroup gtkmmEnums */
72
inline TreeModelFlags operator&(TreeModelFlags lhs, TreeModelFlags rhs)
73
{ return static_cast<TreeModelFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); }
75
/** @ingroup gtkmmEnums */
76
inline TreeModelFlags operator^(TreeModelFlags lhs, TreeModelFlags rhs)
77
{ return static_cast<TreeModelFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); }
79
/** @ingroup gtkmmEnums */
80
inline TreeModelFlags operator~(TreeModelFlags flags)
81
{ return static_cast<TreeModelFlags>(~static_cast<unsigned>(flags)); }
83
/** @ingroup gtkmmEnums */
84
inline TreeModelFlags& operator|=(TreeModelFlags& lhs, TreeModelFlags rhs)
85
{ return (lhs = static_cast<TreeModelFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); }
87
/** @ingroup gtkmmEnums */
88
inline TreeModelFlags& operator&=(TreeModelFlags& lhs, TreeModelFlags rhs)
89
{ return (lhs = static_cast<TreeModelFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); }
91
/** @ingroup gtkmmEnums */
92
inline TreeModelFlags& operator^=(TreeModelFlags& lhs, TreeModelFlags rhs)
93
{ return (lhs = static_cast<TreeModelFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); }
98
#ifndef DOXYGEN_SHOULD_SKIP_THIS
103
class Value<Gtk::TreeModelFlags> : public Glib::Value_Flags<Gtk::TreeModelFlags>
106
static GType value_type() G_GNUC_CONST;
110
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
117
//TODO: Remove any mention of null arguments from the method documentation, by adding overrides in gtk_docs_override.xml.
118
/** This class defines a generic tree interface for use by the Gtk::TreeView widget.
121
* It is is designed to be usable with any appropriate data structure. The
122
* programmer just has to implement this interface on their own data type for
123
* it to be viewable by a Gtk::TreeView widget.
125
* The model is represented as a hierarchical tree of strongly-typed, columned
126
* data. In other words, the model can be seen as a tree where every node has
127
* different values depending on which column is being queried. The type of
128
* data found in a column is determined by TreeModel::Column<> templates.
129
* The types are homogeneous per column across all nodes. It is important to note that this
130
* interface only provides a way of examining a model and observing changes.
131
* The implementation of each individual model decides how and if changes are
134
* In order to make life simpler for programmers who do not need to write their
135
* own specialized model, two generic models are provided - the Gtk::TreeStore
136
* and the Gtk::ListStore. To use these, the developer simply pushes data into
137
* these models as necessary. These models provide the data structure as well
138
* as all appropriate tree interfaces. As a result, implementing drag and drop,
139
* sorting, and storing data is trivial. For the vast majority of trees and
140
* lists, these two models are sufficient.
142
* Models are accessed on a node/column level of granularity. One can query for
143
* the value of a model at a certain node and a certain column on that node.
144
* There are two structures used to reference a particular node in a model.
145
* They are the @link Gtk::TreePath Path@endlink and the iterator. Most of the interface consists of
146
* operations on an @link Gtk::TreeIter iterator@endlink.
148
* A @link Gtk::TreePath Gtk::TreeModel::Path@endlink is essentially a potential node. It is a location on a model that may
149
* or may not actually correspond to a node on a specific model.
151
* By contrast, an @link Gtk::TreeIter Gtk::TreeModel::iterator@endlink is a reference to a specific node on a specific
152
* model. One can convert a path to an @link Gtk::TreeIter iterator@endlink by calling Gtk::TreeModel::get_iter().
153
* These iterators are the primary way of accessing a model and are similar to the iterators
154
* used by Gtk::TextBuffer. The model interface defines a set of operations
155
* using them for navigating the model.
157
* The @link Gtk::TreeRowReference RowReference@endlink is also useful, because it remains
158
* 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.
161
class TreeModel : public Glib::Interface
164
#ifndef DOXYGEN_SHOULD_SKIP_THIS
167
typedef TreeModel CppObjectType;
168
typedef TreeModel_Class CppClassType;
169
typedef GtkTreeModel BaseObjectType;
170
typedef GtkTreeModelIface BaseClassType;
173
friend class TreeModel_Class;
174
static CppClassType treemodel_class_;
177
TreeModel(const TreeModel&);
178
TreeModel& operator=(const TreeModel&);
181
TreeModel(); // you must derive from this class
183
/** Called by constructors of derived classes. Provide the result of
184
* the Class init() function to ensure that it is properly
187
* @param interface_class The Class object for the derived type.
189
explicit TreeModel(const Glib::Interface_Class& interface_class);
192
// This is public so that C++ wrapper instances can be
193
// created for C instances of unwrapped types.
194
// For instance, if an unexpected C type implements the C interface.
195
explicit TreeModel(GtkTreeModel* castitem);
198
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
201
virtual ~TreeModel();
203
static void add_interface(GType gtype_implementer);
205
#ifndef DOXYGEN_SHOULD_SKIP_THIS
206
static GType get_type() G_GNUC_CONST;
207
static GType get_base_type() G_GNUC_CONST;
210
///Provides access to the underlying C GObject.
211
GtkTreeModel* gobj() { return reinterpret_cast<GtkTreeModel*>(gobject_); }
213
///Provides access to the underlying C GObject.
214
const GtkTreeModel* gobj() const { return reinterpret_cast<GtkTreeModel*>(gobject_); }
220
typedef TreeModelColumnRecord ColumnRecord;
222
typedef TreeNodeChildren Children;
223
typedef Children::iterator iterator;
224
typedef Children::reverse_iterator reverse_iterator;
225
typedef Children::const_iterator const_iterator;
226
typedef Children::const_reverse_iterator const_reverse_iterator;
229
typedef TreePath Path;
230
typedef TreeRowReference RowReference;
233
//These are part of GtkTreeModelFilter or GtkTreeModelSort, not GtkTreeModel:
236
/** Returns a valid iterator pointing to @a path.
238
* @param path The @link Gtk::TreePath Gtk::TreeModel::Path@endlink.
239
* @result A valid iterator pointing to the path, or an invalid iterator if that is not possible.
241
iterator get_iter(const Path& path);
242
//TODO: Add const_iterator get_iter(const Path& path) const;
243
//Implement a const_iterator?
245
/** Returns a valid iterator pointing to @a path_string.
247
* @param path_string The path, as a string representation.
248
* @result A valid iterator pointing to the path, or an invalid iterator if that is not possible.
250
iterator get_iter(const Glib::ustring& path_string);
251
//TODO: Implement a const_iterator? const_iterator get_iter(const Glib::ustring& path_string) const;
253
///This returns an STL-like container API, for iterating over the rows.
256
//TODO: Return a real TreeNodeChildren (a container of const_iterators), when we have a real const_iterator.
257
///This returns an STL-like container API, for iterating over the rows.
258
Children children() const;
262
* void on_foreach(const Gtk::TreeModel::iterator& iter);
264
* If the callback function returns true, then the tree ceases to be walked, and foreach() returns.
266
typedef sigc::slot<bool, const TreeModel::iterator&> SlotForeachIter;
268
/** Calls a callback slot on each node in the model in a depth-first fashion.
269
* If the callback function returns true, then the tree ceases to be walked, and foreach() returns.
271
* @param slot The function to call for each selected node.
273
void foreach_iter(const SlotForeachIter& slot);
276
* void on_foreach(const Gtk::TreeModel::Path& path);
278
* If the callback function returns true, then the tree ceases to be walked, and foreach() returns.
280
typedef sigc::slot<bool, const TreeModel::Path&> SlotForeachPath;
282
/** Calls a callback slot on each node in the model in a depth-first fashion.
283
* If the callback function returns true, then the tree ceases to be walked, and foreach() returns.
285
* @param slot The function to call for each selected node.
287
void foreach_path(const SlotForeachPath& slot);
290
* void on_foreach(const Gtk::TreeModel::Path& path, const Gtk::TreeModel::iterator& iter);
292
* If the callback function returns true, then the tree ceases to be walked, and foreach() returns.
294
typedef sigc::slot<bool, const TreeModel::Path&, const TreeModel::iterator&> SlotForeachPathAndIter;
296
/** Calls a callback slot on each node in the model in a depth-first fashion.
297
* If the callback function returns true, then the tree ceases to be walked, and foreach() returns.
299
* @param slot The function to call for each selected node.
301
void foreach(const SlotForeachPathAndIter& slot);
304
/** Returns a set of flags supported by this interface. The flags are a bitwise
305
* combination of Gtk::TreeModelFlags. The flags supported should not change
306
* during the lifecycle of the @a tree_model.
307
* @return The flags supported by this interface.
309
TreeModelFlags get_flags() const;
311
/** Returns the number of columns supported by @a tree_model.
312
* @return The number of columns.
314
int get_n_columns() const;
316
/** Returns the type of the column.
317
* @param index The column index.
318
* @return The type of the column.
320
GType get_column_type(int index) const;
321
//TODO: A C++-type version of get_column_type()?
324
/** Returns a Gtk::TreePath referenced by @a iter.
325
* @param iter The Gtk::TreeIter.
326
* @return A Gtk::TreePath.
328
TreeModel::Path get_path(const iterator& iter) const;
331
/** Emits the "row-changed" signal on @a tree_model.
332
* @param path A Gtk::TreePath pointing to the changed row.
333
* @param iter A valid Gtk::TreeIter pointing to the changed row.
335
void row_changed(const Path& path, const iterator& iter);
337
/** Emits the "row-inserted" signal on @a tree_model
338
* @param path A Gtk::TreePath pointing to the inserted row.
339
* @param iter A valid Gtk::TreeIter pointing to the inserted row.
341
void row_inserted(const Path& path, const iterator& iter);
343
/** Emits the "row-has-child-toggled" signal on @a tree_model. This should be
344
* called by models after the child state of a node changes.
345
* @param path A Gtk::TreePath pointing to the changed row.
346
* @param iter A valid Gtk::TreeIter pointing to the changed row.
348
void row_has_child_toggled(const Path& path, const iterator& iter);
350
/** Emits the "row-deleted" signal on @a tree_model. This should be called by
351
* models after a row has been removed. The location pointed to by @a path
352
* should be the location that the row previously was at. It may not be a
353
* valid location anymore.
354
* @param path A Gtk::TreePath pointing to the previous location of the deleted row.
356
void row_deleted(const Path& path);
358
/** Emits the "rows_reordered" signal on the tree model. This should be called by
359
* custom models when their rows have been reordered.
361
* @param path A tree path pointing to the tree node whose children have been reordered.
362
* @param iter A valid iterator pointing to the node whose children have been reordered. See also, rows_reordered(const Path& path, const Glib::ArrayHandle<int>& new_order), if the path has a depth of 0.
363
* @param new_order An array of integers mapping the current position of each child
364
* to its old position before the re-ordering, i.e. @a new_order<literal>[newpos] = oldpos.
366
void rows_reordered(const Path& path, const iterator& iter, const Glib::ArrayHandle<int>& new_order);
368
/** Emits the "rows_reordered" signal on the tree model. This should be called by
369
* custom models when their rows have been reordered. This method overload is for nodes whose
370
* path has a depth of 0.
373
* @param path A tree path pointing to the tree node whose children have been reordered.
374
* @param new_order An array of integers mapping the current position of each child
375
* to its old position before the re-ordering, i.e. @a new_order<literal>[newpos] = oldpos.
377
void rows_reordered(const Path& path, const Glib::ArrayHandle<int>& new_order);
380
/** Emits the "rows-reordered" signal on @a tree_model. This should be called by
381
* models when their rows have been reordered.
382
* @param path A Gtk::TreePath pointing to the tree node whose children have been
384
* @param iter A valid Gtk::TreeIter pointing to the node whose children have been
385
* reordered, or <tt>0</tt> if the depth of @a path is 0.
386
* @param new_order An array of integers mapping the current position of each child
387
* to its old position before the re-ordering,
388
* i.e. @a new_order<tt>[newpos] = oldpos</tt>.
390
void rows_reordered(const Path& path, const iterator& iter, int* new_order);
393
/** Generates a string representation of the iter. This string is a ':'
394
* separated list of numbers. For example, "4:10:0:3" would be an
395
* acceptable return value for this string.
398
* @param iter An Gtk::TreeIter.
399
* @return The string.
401
Glib::ustring get_string(const iterator& iter) const;
406
* <tt>void on_my_%row_changed(const TreeModel::Path& path, const TreeModel::iterator& iter)</tt>
409
Glib::SignalProxy2< void,const TreeModel::Path&,const TreeModel::iterator& > signal_row_changed();
414
* <tt>void on_my_%row_inserted(const TreeModel::Path& path, const TreeModel::iterator& iter)</tt>
417
Glib::SignalProxy2< void,const TreeModel::Path&,const TreeModel::iterator& > signal_row_inserted();
422
* <tt>void on_my_%row_has_child_toggled(const TreeModel::Path& path, const TreeModel::iterator& iter)</tt>
425
Glib::SignalProxy2< void,const TreeModel::Path&,const TreeModel::iterator& > signal_row_has_child_toggled();
430
* <tt>void on_my_%row_deleted(const TreeModel::Path& path)</tt>
433
Glib::SignalProxy1< void,const TreeModel::Path& > signal_row_deleted();
438
* <tt>void on_my_%rows_reordered(const TreeModel::Path& path, const TreeModel::iterator& iter, int* new_order)</tt>
441
Glib::SignalProxy3< void,const TreeModel::Path&,const TreeModel::iterator&,int* > signal_rows_reordered();
445
virtual TreeModelFlags get_flags_vfunc() const;
447
virtual int get_n_columns_vfunc() const;
449
virtual GType get_column_type_vfunc(int index) const;
452
//These are only for deriving new TreeModels, which isn't very common or easy:
454
/** Override and implement this in a derived TreeModel class.
455
* Sets @a iter_next to refer to the node following @a iter it at the current level.
456
* If there is no next iter, false is returned and iter_next is set to be invalid.
458
* @param iter An iterator.
459
* @param iter_next An iterator that will be set to refer to the next node, or will be set as invalid.
460
* @result true if the operation was possible.
462
virtual bool iter_next_vfunc(const iterator& iter, iterator& iter_next) const;
464
/** Override and implement this in a derived TreeModel class.
465
* Sets @a iter to a valid iterator pointing to @a path
467
* @param path An path to a node.
468
* @param iter An iterator that will be set to refer to a node to the path, or will be set as invalid.
469
* @result true if the operation was possible.
471
virtual bool get_iter_vfunc(const Path& path, iterator& iter) const;
473
/** Override and implement this in a derived TreeModel class.
474
* Sets @a iter to refer to the first child of @a parent. If @a parent has no children,
475
* false is returned and @a iter is set to be invalid.
477
* @param parent An iterator.
478
* @param iter An iterator that will be set to refer to the firt child node, or will be set as invalid.
479
* @result true if the operation was possible.
481
virtual bool iter_children_vfunc(const iterator& parent, iterator& iter) const;
483
/** Override and implement this in a derived TreeModel class.
484
* Sets @a iter to be the parent of @a child. If @a child is at the toplevel, and
485
* doesn't have a parent, then @a iter is set to an invalid iterator and false
488
* @param child An iterator.
489
* @param iter An iterator that will be set to refer to the parent node, or will be set as invalid.
490
* @result true if the operation was possible.
492
virtual bool iter_parent_vfunc(const iterator& child, iterator& iter) const;
494
/** Override and implement this in a derived TreeModel class.
495
* Sets @a iter to be the child of @a parent using the given index. The first
496
* index is 0. If @a n is too big, or @a parent has no children, @a iter is set
497
* to an invalid iterator and false is returned.
498
* See also iter_nth_root_child_vfunc()
500
* @param parent An iterator.
501
* @param n The index of the child node to which @a iter should be set.
502
* @param iter An iterator that will be set to refer to the nth node, or will be set as invalid.
503
* @result true if the operation was possible.
505
virtual bool iter_nth_child_vfunc(const iterator& parent, int n, iterator& iter) const;
507
/** Override and implement this in a derived TreeModel class.
508
* Sets @a iter to be the child of at the root level using the given index. The first
509
* index is 0. If @a n is too big, or if there are no children, @a iter is set
510
* to an invalid iterator and false is returned.
511
* See also iter_nth_child_vfunc().
513
* @param n The index of the child node to which @a iter should be set.
514
* @param iter An iterator that will be set to refer to the nth node, or will be set as invalid.
515
* @result true if the operation was possible.
517
virtual bool iter_nth_root_child_vfunc(int n, iterator& iter) const;
520
/** Override and implement this in a derived TreeModel class.
521
* Returns true if @a iter has children, false otherwise.
523
* @param iter The iterator to test for children.
524
* @result true if @a iter has children.
526
virtual bool iter_has_child_vfunc(const iterator& iter) const;
529
/** Override and implement this in a derived TreeModel class.
530
* Returns the number of children that @a iter has.
531
* See also iter_n_root_children_vfunc().
533
* @param iter The iterator to test for children.
534
* @result The number of children of @a iter.
536
virtual int iter_n_children_vfunc(const iterator& iter) const;
538
/** Override and implement this in a derived TreeModel class.
539
* Returns the number of toplevel nodes.
540
* See also iter_n_children().
542
* @result The number of children at the root level.
544
virtual int iter_n_root_children_vfunc() const;
546
/** Override and implement this in a derived TreeModel class.
547
* Lets the tree ref the node. This is an optional method for models to
548
* implement. To be more specific, models may ignore this call as it exists
549
* primarily for performance reasons.
551
* This function is primarily meant as a way for views to let caching model know
552
* when nodes are being displayed (and hence, whether or not to cache that
553
* node.) For example, a file-system based model would not want to keep the
554
* entire file-hierarchy in memory, just the sections that are currently being
555
* displayed by every current view.
557
* A model should be expected to be able to get an iter independent of its
560
* @param iter the iterator.
562
virtual void ref_node_vfunc(const iterator& iter) const;
565
/** Override and implement this in a derived TreeModel class.
566
* Lets the tree unref the node. This is an optional method for models to
567
* implement. To be more specific, models may ignore this call as it exists
568
* primarily for performance reasons.
570
* For more information on what this means, see unref_node_vfunc().
571
* Please note that nodes that are deleted are not unreffed.
573
* @param iter the iterator.
575
virtual void unref_node_vfunc(const iterator& iter) const;
578
/** Override and implement this in a derived TreeModel class.
579
* Returns a Path referenced by @a iter.
581
* @param iter The iterator.
586
virtual TreeModel::Path get_path_vfunc(const iterator& iter) const;
589
/** Override and implement this in a derived TreeModel class.
590
* Initializes and sets @a value to that at @a column.
592
* @param iter The iterator.
593
* @param column The column to lookup the value at.
594
* @param value An empty Glib:Value to set.
596
virtual void get_value_vfunc(const iterator& iter, int column, Glib::ValueBase& value) const;
599
//We don't put an deprecation ifdef around this because it would break ABI.
600
/** Override and implement this in a derived TreeModel class.
601
* @note This virtual method is not recommended. To check
602
* whether an iterator is valid, call TreeStore::iter_is_valid(),
603
* ListStore::iter_is_valid() or TreeModelSort::iter_is_valid() directly
604
* instead. Because these methods are intended to be used only for debugging
605
* and/or testing purposes, it doesn't make sense to provide an abstract
608
* @result true if the iterator is valid.
610
* @deprecated Use iter_is_valid() in the derived class.
612
virtual bool iter_is_valid(const iterator& iter) const;
614
//Called by TreeRow, which is a friend class:
615
//The comment about set_row_changed() in the documentation is based on my reading of the source of
616
//gtk_list_store_set_value() and gtk_tree_store_set_value().
617
/** Override and implement this in a derived TreeModel class, so that Row::operator() and
618
* Row::set_value() work.
619
* You can probably just implement this by calling set_value_vfunc().
620
* Your implementation of set_value_impl() should also call row_changed() after changing the value.
622
virtual void set_value_impl(const iterator& row, int column, const Glib::ValueBase& value);
624
//This might not need to be virtual, but it's not a big deal. murrayc.
625
virtual void get_value_impl(const iterator& row, int column, Glib::ValueBase& value) const;
627
friend class Gtk::TreeModelSort;
628
friend class Gtk::TreeRow;
629
friend class Gtk::TreeIter;
635
//C++ methods used to invoke GTK+ virtual functions:
638
//GTK+ Virtual Functions (override these to change behaviour):
640
//Default Signal Handlers::
641
virtual void on_row_changed(const TreeModel::Path& path, const TreeModel::iterator& iter);
642
virtual void on_row_inserted(const TreeModel::Path& path, const TreeModel::iterator& iter);
643
virtual void on_row_has_child_toggled(const TreeModel::Path& path, const TreeModel::iterator& iter);
644
virtual void on_row_deleted(const TreeModel::Path& path);
645
virtual void on_rows_reordered(const TreeModel::Path& path, const TreeModel::iterator& iter, int* new_order);
655
/** A Glib::wrap() method for this object.
657
* @param object The C instance.
658
* @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
659
* @result A C++ instance that wraps this C instance.
661
* @relates Gtk::TreeModel
663
Glib::RefPtr<Gtk::TreeModel> wrap(GtkTreeModel* object, bool take_copy = false);
668
#endif /* _GTKMM_TREEMODEL_H */
added
removed
include/gtkmm-2.4/gtkmm/treemodel.h
