13
0
livetrax/libs/gtkmm2/gtk/gtkmm/treeiter.h

518 lines
16 KiB
C
Raw Normal View History

// -*- c++ -*-
// Generated by gtkmmproc -- DO NOT MODIFY!
#ifndef _GTKMM_TREEITER_H
#define _GTKMM_TREEITER_H
#include <glibmm.h>
/* $Id$ */
/* Copyright(C) 1998-2002 The gtkmm Development Team
*
* This library is free software, ) you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation, ) either
* version 2 of the License, or(at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY, ) without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public
* License along with this library, ) if not, write to the Free
* Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
#include <gtkmm/treemodelcolumn.h>
#include <gtkmmconfig.h>
#include <iterator>
#include <gtk/gtktreemodel.h> /* for GtkTreeIter */
GLIBMM_USING_STD(forward_iterator_tag)
namespace Gtk
{
class TreeModel;
class TreeRow;
class TreeNodeChildren;
/**
* @ingroup TreeView
*/
class TreeIterBase
{
public:
#ifndef DOXYGEN_SHOULD_SKIP_THIS
typedef TreeIterBase CppObjectType;
typedef GtkTreeIter BaseObjectType;
static GType get_type() G_GNUC_CONST;
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
TreeIterBase();
explicit TreeIterBase(const GtkTreeIter* gobject); // always takes a copy
///Provides access to the underlying C instance.
GtkTreeIter* gobj() { return &gobject_; }
///Provides access to the underlying C instance.
const GtkTreeIter* gobj() const { return &gobject_; }
protected:
GtkTreeIter gobject_;
private:
//A wrap() for TreeIterBase* wouldn't be very helpful.
};
// In order to offer STL-like iterator functionality, we cannot wrap
// GtkTreeIter directly. Most GTK+ functions that operate on GtkTreeIter
// are virtual functions in GtkTreeModel. Therefore, the C++ TreeIter
// must store a pointer to the Gtk::TreeModel to which it belongs.
//
// Another problem, which is much worse, is that the GTK+ tree iterator
// doesn't support the STL-style half-open interval [begin,end). Instead,
// it uses a [first,last] interval, and functions return FALSE to indicate
// the end was reached. Also, some functions accept a NULL GtkTreeIter*,
// which will be interpreted as the end() iterator.
//
// Most of the immense complexity in the Gtk::TreeIter implementation is
// needed for proper emulation of [begin,end) intervals. Unfortunately,
// it's not even possible to encapsulate everything in the TreeIter
// class. Almost all wrapper methods dealing with GtkTreeIter must be
// carefully implemented by hand. TODO: document implementation details
//TODO: Implement a const_iterator too:
//danielk says that this ConstTreeIter class should return a ConstTreeRow, which would not allow operator=.
/** A Gtk::TreeModel::iterator is a reference to a specific node on a specific
* model.
*
* It is a generic structure with an integer and three generic pointers.
* These are filled in by the model in a model-specific way.
*
* One can convert a path to an iterator by calling Gtk::TreeModel::get_iter().
*
* These iterators are the primary way of accessing a model and are similar to the iterators
* used by Gtk::TextBuffer. The model interface defines a set of operations
* using them for navigating the model.
*
* The lifecycle of an iterator can be a little confusing at first. Iterators
* are expected to always be valid for as long as the model is unchanged (and
* doesn't emit a signal).
* Additionally, some models guarantee that an iterator is valid for as
* long as the node it refers to is valid (most notably the Gtk::TreeStore and
* Gtk::ListStore).
*
* Although generally uninteresting, as one always has to
* allow for the case where iterators do not persist beyond a signal, some very
* important performance enhancements were made in the sort model. As a result,
* the Gtk::TREE_MODEL_ITERS_PERSIST flag was added to indicate this behaviour -
* see Gtk::TreeModel::get_flags().
*
* Typedefed as Gtk::TreeModel::iterator.
* The Gtk::TreeModel iterator.
* @ingroup TreeView
*/
class TreeIter : public TreeIterBase
{
public:
typedef std::bidirectional_iterator_tag iterator_category;
typedef Gtk::TreeRow value_type;
typedef int difference_type;
typedef const Gtk::TreeRow& reference;
typedef const Gtk::TreeRow* pointer;
TreeIter();
TreeIter& operator++();
const TreeIter operator++(int);
/** Please note that this is very slow compared to operator++().
*/
TreeIter& operator--();
/** Please note that this is very slow compared to operator++().
*/
const TreeIter operator--(int);
inline reference operator*() const;
inline pointer operator->() const;
bool equal(const TreeIter& other) const;
/** Discover whether the iterator is valid, and not equal to end().
*/
operator bool() const;
/** This is only useful when implementing a custom Gtk::TreeModel class.
* Compare the iterator's stamp with your model's stamp to discover whether it is valid.
* @see set_stamp().
* @result The iterator's stamp.
*/
int get_stamp() const;
/** This is only useful when implementing a custom Gtk::TreeModel class.
* Set the stamp to be equal to your model's stamp, to mark the iterator as valid.
* When your model's structure changes, you should increment your model's stamp
* to mark all older iterators as invalid. They will be recognised as invalid because
* they will then have an incorrect stamp.
*/
void set_stamp(int stamp);
#ifndef DOXYGEN_SHOULD_SKIP_THIS
explicit TreeIter(TreeModel* model); // used in TreeModel methods
TreeIter(GtkTreeModel* model, const GtkTreeIter* iter); // used by signal proxies
void set_model_refptr(const Glib::RefPtr<TreeModel>& model);
void set_model_gobject(GtkTreeModel* model);
GtkTreeModel* get_model_gobject() const;
void setup_end_iterator(const TreeIter& last_valid);
const GtkTreeIter* get_gobject_if_not_end() const
{ return (!is_end_) ? &gobject_ : 0; }
const GtkTreeIter* get_parent_gobject_if_end() const
{ return (is_end_ && gobject_.stamp) ? &gobject_ : 0; }
protected:
// Yes, using a simple TreeModel* rather than Glib::RefPtr<TreeModel>
// violates the general policy. But Gtk::TreeIter should have a trivial
// copy constructor and assignment operator, i.e. it must contain only
// POD (plain old data).
//
// Gtk::TreeIter is copied a lot, particularly often as return value from
// methods. Postfix ++ must return by value, and STL algorithms usually
// pass iterators by value, too. With a RefPtr<> as member data, copying
// would no longer be trivial, and even cause frequent calls to reference()
// and unreference(). That usually doesn't matter much for GUI stuff, but
// Gtk::TreeModel is used as a generic container. Imagine a for-loop that
// checks whether iter != children.end() on each iteration.
TreeModel* model_;
bool is_end_;
friend class Gtk::TreeRow;
friend class Gtk::TreeNodeChildren;
friend class Gtk::TreeModel;
#endif // DOXYGEN_SHOULD_SKIP_THIS
};
/** @relates Gtk::TreeIter */
inline bool operator==(const TreeIter& lhs, const TreeIter& rhs)
{ return lhs.equal(rhs); }
/** @relates Gtk::TreeIter */
inline bool operator!=(const TreeIter& lhs, const TreeIter& rhs)
{ return !lhs.equal(rhs); }
template <class ColumnType>
class TreeValueProxy
{
public:
#ifndef DOXYGEN_SHOULD_SKIP_THIS
inline TreeValueProxy(const TreeRow& row, const TreeModelColumn<ColumnType>& column);
#endif
inline TreeValueProxy<ColumnType>& operator=(const ColumnType& data);
inline operator ColumnType() const;
private:
const TreeRow& row_;
const TreeModelColumn<ColumnType>& column_;
// no copy assignment
TreeValueProxy<ColumnType>& operator=(const TreeValueProxy<ColumnType>&);
};
/** Typedefed as TreeModel::Row.
*
* Dereference a TreeModel::iterator to get the Row. Use operator[] or set_value() and get_value() to access the
* values in the columns of this row.
*
* If the model contains a hierarchy of rows (such as Gtk::TreeStore), then you can access the child rows with
* children().
*
* You can use a const TreeModel::Row& for any parameter that takes a const TreeModel::iterator&.
* @ingroup TreeView
*/
class TreeRow : public TreeIter //We use public inheritance so that we can cast from a TreeRow to a TreeIter.
{
public:
/** Use this to set and get the value of this @a column of this row.
* This is a templated method, so the compiler will not allow you to provide an inappropriate type
* of data for the model column.
*
* This is just a more convient syntax that does the same thing as set_value() and get_value().
*
* @param column The model column..
*/
template <class ColumnType> inline
TreeValueProxy<ColumnType> operator[](const TreeModelColumn<ColumnType>& column) const;
/** Sets the value of this @a column of this row.
* This is a templated method, so the compiler will not allow you to provide an inappropriate type
* of @a data for the model column.
*
* See also operator[].
*
* @param column The model column.
* @param data The new value to use for this column of this row.
*/
template <class ColumnType>
void set_value(const TreeModelColumn<ColumnType>& column, const ColumnType& data) const;
/** Use set_value(const TreeModelColumn<>& column, const ColumnType& data) unless
* you do not know the column type at compile-time.
* If the @a data is of an inappropriate C++ type then this might fail at runtime.
* @param column The number of the column whose value you want to change.
* @param data The new value to use for this column of this row.
*/
template <class ColumnType>
void set_value(int column, const ColumnType& data) const;
/** Gets the value of this @a column of this row.
* This is a templated method, so the compiler will not allow you to provide an inappropriate type
* of data for the model column.
*
* See also operator[].
*
* @param column The model column.
* @result The new value to use for this column of this row.
*/
template <class ColumnType>
ColumnType get_value(const TreeModelColumn<ColumnType>& column) const;
/** Use get_value(const TreeModelColumn<>& column) unless
* you do not know the column type at compile-time.
* If the @a data output argument is of an inappropriate C++ type then this might fail at runtime.
* @param column The number of the column whose value you want to change.
* @retval data An output argument which will contain the value of this column of this row.
*/
template <class ColumnType>
void get_value(int column, ColumnType& data) const;
/** This returns an STL-like container API, for iterating over the rows.
* See also Gtk::TreeModel::children() for the top-level children.
*/
const TreeNodeChildren& children() const;
/** Gets an iterator to the parent row of this row.
* @result An iterator to the parent row.
*/
TreeIter parent() const;
/** Discover whether this is a valid row.
*/
operator bool() const;
/// Provides access to the underlying C GObject.
GtkTreeIter* gobj() { return TreeIter::gobj(); }
/// Provides access to the underlying C GObject.
const GtkTreeIter* gobj() const { return TreeIter::gobj(); }
private:
// Forwarders to Gtk::TreeModel virtual methods.
void set_value_impl(int column, const Glib::ValueBase& value) const;
void get_value_impl(int column, Glib::ValueBase& value) const;
};
//TODO: Document begin(), end(), size(), etc, in an STL-style way. murrayc.
/** typedefed as TreeModel::Children.
* Virtual container of TreeModel::Row items.
* @ingroup TreeView
*/
class TreeNodeChildren : public TreeIter
{
public:
typedef Gtk::TreeRow value_type;
typedef unsigned int size_type;
typedef int difference_type;
typedef Gtk::TreeIter iterator;
#ifndef GLIBMM_HAVE_SUN_REVERSE_ITERATOR
typedef std::reverse_iterator<iterator> reverse_iterator;
#else
typedef std::reverse_iterator<iterator, std::random_access_iterator_tag,
int, int&, int*, ptrdiff_t> reverse_iterator;
#endif
typedef Gtk::TreeIter const_iterator; //TODO: Make it a real const_iterator.
#ifndef GLIBMM_HAVE_SUN_REVERSE_ITERATOR
typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
#else
typedef std::reverse_iterator<const_iterator, std::random_access_iterator_tag,
int, const int&, const int*, ptrdiff_t> const_reverse_iterator;
#endif
iterator begin();
const_iterator begin() const;
iterator end();
const_iterator end() const;
// Note: there is no advantage in not inlining these methods.
// We can't change them without breaking ABI anyway.
reverse_iterator rbegin() { return reverse_iterator(end()); }
reverse_iterator rend() { return reverse_iterator(begin()); }
const_reverse_iterator rbegin() const { return const_reverse_iterator(end()); }
const_reverse_iterator rend() const { return const_reverse_iterator(begin()); }
value_type operator[](size_type index) const;
size_type size() const;
bool empty() const;
operator bool() const { return !empty(); }
#ifndef DOXYGEN_SHOULD_SKIP_THIS
explicit TreeNodeChildren(TreeModel* model)
: TreeIter(model) {}
const GtkTreeIter* get_parent_gobject() const
{ return (gobject_.stamp != 0) ? &gobject_ : 0; }
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
};
#ifndef DOXYGEN_SHOULD_SKIP_THIS
/**** Gtk::TreeIter ********************************************************/
inline
TreeIter::reference TreeIter::operator*() const
{
return static_cast<const TreeRow&>(*this);
}
inline
TreeIter::pointer TreeIter::operator->() const
{
return static_cast<const TreeRow*>(this);
}
/**** Gtk::TreeValueProxy<> ************************************************/
template <class ColumnType> inline
TreeValueProxy<ColumnType>::TreeValueProxy(const TreeRow& row, const TreeModelColumn<ColumnType>& column)
:
row_ (row),
column_ (column)
{}
template <class ColumnType> inline
TreeValueProxy<ColumnType>& TreeValueProxy<ColumnType>::operator=(const ColumnType& data)
{
row_.set_value(column_, data);
return *this;
}
template <class ColumnType> inline
TreeValueProxy<ColumnType>::operator ColumnType() const
{
return row_.get_value(column_);
}
/**** Gtk::TreeRow *********************************************************/
template <class ColumnType> inline
TreeValueProxy<ColumnType> TreeRow::operator[](const TreeModelColumn<ColumnType>& column) const
{
return TreeValueProxy<ColumnType>(*this, column);
}
template <class ColumnType>
void TreeRow::set_value(const TreeModelColumn<ColumnType>& column, const ColumnType& data) const
{
typedef typename Gtk::TreeModelColumn<ColumnType>::ValueType ValueType;
ValueType value;
value.init(column.type());
value.set(data);
this->set_value_impl(column.index(), value);
}
template <class ColumnType>
void TreeRow::set_value(int column, const ColumnType& data) const
{
//This could fail at run-time, because the wrong ColumnType might be used.
//It's only for dynamically generated model columns.
typedef typename Gtk::TreeModelColumn<ColumnType> type_cppcolumn;
typedef typename type_cppcolumn::ValueType ValueType;
ValueType value;
value.init(ValueType::value_type());
value.set(data);
this->set_value_impl(column, value);
}
template <class ColumnType>
ColumnType TreeRow::get_value(const TreeModelColumn<ColumnType>& column) const
{
typedef typename Gtk::TreeModelColumn<ColumnType>::ValueType ValueType;
ValueType value;
this->get_value_impl(column.index(), value);
return value.get();
}
template <class ColumnType>
void TreeRow::get_value(int column, ColumnType& data) const
{
//This could fail at run-time, because the wrong ColumnType might be used.
//It's only for dynamically generated model columns.
typedef typename Gtk::TreeModelColumn<ColumnType>::ValueType ValueType;
ValueType value;
this->get_value_impl(column, value);
data = value.get();
}
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
} // namespace Gtk
namespace Glib
{
#ifndef DOXYGEN_SHOULD_SKIP_THIS
template <>
class Value<Gtk::TreeIterBase> : public Glib::Value_Boxed<Gtk::TreeIterBase>
{};
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
} // namespace Glib
#endif /* _GTKMM_TREEITER_H */