libs/gtkmm2/gtk/src/treepath.hg

   1 /* $Id: treepath.hg,v 1.15 2006/02/25 12:38:11 murrayc Exp $ */
   2
   3 /* Copyright(C) 1998-2002 The gtkmm Development Team
   4  *
   5  * This library is free software, ) you can redistribute it and/or
   6  * modify it under the terms of the GNU Library General Public
   7  * License as published by the Free Software Foundation, ) either
   8  * version 2 of the License, or(at your option) any later version.
   9  *
  10  * This library 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 GNU
  13  * Library General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Library General Public
  16  * License along with this library, ) if not, write to the Free
  17  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18  */
  19
  20 // This is for including the config header before any code (such as
  21 // the #ifndef GTKMM_DISABLE_DEPRECATED in deprecated classes) is generated:
  22 _CONFIGINCLUDE(gtkmmconfig.h)
  23
  24 _DEFS(gtkmm,gtk)
  25
  26 #include <gtkmm/treemodel.h>
  27 #include <gtkmm/selectiondata.h>
  28 #include <gtkmmconfig.h>
  29
  30 GLIBMM_USING_STD(random_access_iterator_tag)
  31 GLIBMM_USING_STD(reverse_iterator)
  32
  33
  34 namespace Gtk
  35 {
  36
  37 /** A path is essentially a potential node. It is a location on a model that may
  38  * or may not actually correspond to a node on a specific model.
  39  *
  40  * A Path can be converted into either an array of unsigned integers or a string. The string
  41  * form is a list of numbers separated by a colon. Each number refers to the
  42  * offset at that level. Thus, the path "0" refers to the root node and the
  43  * path "2:4" refers to the fifth child of the third node.
  44  *
  45  * Typedefed as Gtk::TreeModel::Path.
  46  * @ingroup TreeView
  47  */
  48 class TreePath
  49 {
  50   _CLASS_BOXEDTYPE(TreePath, GtkTreePath, gtk_tree_path_new, gtk_tree_path_copy, gtk_tree_path_free)
  51   _IGNORE(gtk_tree_path_copy, gtk_tree_path_free, gtk_tree_path_compare, gtk_tree_path_get_indices)
  52
  53 public:
  54   typedef unsigned int  size_type;
  55   typedef int           difference_type;
  56
  57   typedef int           value_type;
  58   typedef int&          reference;
  59   typedef const int&    const_reference;
  60
  61   // Use plain pointers for simplicity.
  62   typedef int*          iterator;
  63   typedef const int*    const_iterator;
  64
  65 #ifndef GLIBMM_HAVE_SUN_REVERSE_ITERATOR
  66
  67   typedef std::reverse_iterator<iterator>       reverse_iterator;
  68   typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
  69
  70 #else
  71
  72   typedef std::reverse_iterator<iterator, std::random_access_iterator_tag,
  73                                 int, int&, int*, ptrdiff_t> reverse_iterator;
  74
  75   typedef std::reverse_iterator<const_iterator, std::random_access_iterator_tag,
  76                                 int, const int&, const int*, ptrdiff_t> const_reverse_iterator;
  77
  78 #endif /* GLIBMM_HAVE_SUN_REVERSE_ITERATOR */
  79
  80   explicit TreePath(size_type n, value_type value = 0);
  81   explicit TreePath(const Glib::ustring& path);
  82   explicit TreePath(const TreeModel::iterator& iter);
  83
  84   template <class In> inline TreePath(In pbegin, In pend);
  85
  86   void clear();
  87
  88   // I think it's OK for this assignment to be implicit.  It's very useful.
  89   TreePath& operator=(const TreeModel::iterator& iter);
  90
  91   template <class In> inline void assign(In pbegin, In pend);
  92   template <class In>        void append(In pbegin, In pend);
  93
  94   _WRAP_METHOD(void push_back(int index), gtk_tree_path_append_index)
  95   _WRAP_METHOD(void push_front(int index), gtk_tree_path_prepend_index)
  96
  97   size_type size() const;
  98   bool empty() const;
  99
 100   reference       operator[](size_type i);
 101   const_reference operator[](size_type i) const;
 102
 103   iterator begin();
 104   iterator end();
 105   const_iterator begin() const;
 106   const_iterator end()   const;
 107
 108   // Note: there is no advantage in not inlining these methods.
 109   // We can't change them without breaking ABI anyway.
 110   reverse_iterator       rbegin()       { return reverse_iterator(end());         }
 111   reverse_iterator       rend()         { return reverse_iterator(begin());       }
 112   const_reverse_iterator rbegin() const { return const_reverse_iterator(end());   }
 113   const_reverse_iterator rend()   const { return const_reverse_iterator(begin()); }
 114
 115   reference       front()       { return *begin();  }
 116   const_reference front() const { return *begin();  }
 117   reference       back()        { return *rbegin(); }
 118   const_reference back()  const { return *rbegin(); }
 119
 120   _WRAP_METHOD(void next(), gtk_tree_path_next)
 121   _WRAP_METHOD(bool prev(), gtk_tree_path_prev)
 122   _WRAP_METHOD(bool up(), gtk_tree_path_up)
 123   _WRAP_METHOD(void down(), gtk_tree_path_down)
 124
 125   _WRAP_METHOD(bool is_ancestor(const TreePath& descendant) const, gtk_tree_path_is_ancestor)
 126   _WRAP_METHOD(bool is_descendant(const TreePath& ancestor) const, gtk_tree_path_is_descendant)
 127
 128   _WRAP_METHOD(Glib::ustring to_string() const, gtk_tree_path_to_string)
 129
 130 #m4begin
 131   _WRAP_COMPARE(gtk_tree_path_compare)
 132 #m4end
 133
 134
 135   _WRAP_METHOD(void append_index(int index), gtk_tree_path_append_index, deprecated "replaced by push_back()")
 136   _WRAP_METHOD(void prepend_index(int index), gtk_tree_path_prepend_index, deprecated "replaced by push_front().")
 137   _WRAP_METHOD(int get_depth() const, gtk_tree_path_get_depth, deprecated "replaced by size().")
 138
 139 _DEPRECATE_IFDEF_START
 140   /// @deprecated replaced by begin(), end(), and operator[]
 141   Glib::ArrayHandle<int> get_indices() const;
 142 _DEPRECATE_IFDEF_END
 143   _IGNORE(gtk_tree_path_get_depth)
 144
 145   /**
 146    * Obtains a Gtk::TreeModel and Gtk::TreeModel::Path from selection data of target type
 147    * "GTK_TREE_MODEL_ROW". Normally called from a drag_data_received handler.
 148    * This function can only be used if @a selection_data originates from the same
 149    * process that's calling this function, because a pointer to the tree model
 150    * is being passed around. If you aren't in the same process, then you'll
 151    * get memory corruption. In the Gtk::TreeDragDest drag_data_received signal handler,
 152    * you can assume that selection data of type "GTK_TREE_MODEL_ROW" is
 153    * from the current process.
 154    *
 155    * @param selection_data a #SelectionData
 156    * @param model a Gtk::TreeModel
 157    * @param path a row in model
 158    *
 159    * @return true if the selection_data had target type "GTK_TREE_MODEL_ROW" and
 160    *  is otherwise valid
 161    **/
 162   static bool get_from_selection_data(const SelectionData& selection_data, Glib::RefPtr<TreeModel>& model, TreePath& path);
 163   //TODO: Add an override that takes a const TreeModel (and deprecate the current version).
 164
 165   /// See description in the other overload.
 166   static bool get_from_selection_data(const SelectionData& selection_data, TreePath& path);
 167
 168   /**
 169    * Sets selection data of target type "GTK_TREE_MODEL_ROW". Normally used
 170    * in a drag_data_get signal handler.
 171    *
 172    * @param selection_data some #SelectionData
 173    * @param model: a Gtk::TreeModel
 174    *
 175    * @return true if the selection_data had the proper target type to allow us to set a tree row
 176    **/
 177   bool set_in_selection_data(SelectionData& selection_data, const Glib::RefPtr<const TreeModel>& model) const;
 178 };
 179
 180 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 181
 182 template <class In>
 183 void TreePath::append(In pbegin, In pend)
 184 {
 185   // push_back() can't throw -- if it could, this code wouldn't be strongly exception-safe.
 186   for(; pbegin != pend; ++pbegin)
 187     this->push_back(*pbegin);
 188 }
 189
 190 template <class In> inline
 191 TreePath::TreePath(In pbegin, In pend)
 192 {
 193   this->append(pbegin, pend);
 194 }
 195
 196 template <class In> inline
 197 void TreePath::assign(In pbegin, In pend)
 198 {
 199   TreePath temp (pbegin, pend);
 200   this->swap(temp);
 201 }
 202
 203
 204 /* Traits for use of TreePath in a Glib::ListHandle<>.
 205  */
 206 struct TreePath_Traits
 207 {
 208   typedef TreePath            CppType;
 209   typedef const GtkTreePath*  CType;
 210   typedef GtkTreePath*        CTypeNonConst;
 211
 212   static CType to_c_type(const CppType& item)
 213     { return item.gobj(); }
 214
 215   static CType to_c_type(CType item)
 216     { return item; }
 217
 218   static CppType to_cpp_type(CType item)
 219     { return CppType(const_cast<CTypeNonConst>(item)); }
 220
 221   static void release_c_type(CType item)
 222     { gtk_tree_path_free(const_cast<CTypeNonConst>(item)); }
 223 };
 224
 225 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 226
 227
 228 } // namespace Gtk
 229