libs/gtkmm2/gtk/gtkmm/treepath.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GTKMM_TREEPATH_H
   4 #define _GTKMM_TREEPATH_H
   5
   6 #include <glibmm.h>
   7
   8 /* $Id$ */
   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 Library General Public
  14  * License as published by the Free Software Foundation, ) either
  15  * version 2 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  * Library General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Library General Public
  23  * License along with this library, ) if not, write to the Free
  24  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  25  */
  26
  27
  28 #include <gtkmm/treemodel.h>
  29 #include <gtkmm/selectiondata.h>
  30 #include <gtkmmconfig.h>
  31
  32 GLIBMM_USING_STD(random_access_iterator_tag)
  33 GLIBMM_USING_STD(reverse_iterator)
  34
  35
  36 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  37 extern "C" { typedef struct _GtkTreePath GtkTreePath; }
  38 #endif
  39
  40 namespace Gtk
  41 {
  42
  43 /** A path is essentially a potential node. It is a location on a model that may
  44  * or may not actually correspond to a node on a specific model.
  45  *
  46  * A Path can be converted into either an array of unsigned integers or a string. The string
  47  * form is a list of numbers separated by a colon. Each number refers to the
  48  * offset at that level. Thus, the path "0" refers to the root node and the
  49  * path "2:4" refers to the fifth child of the third node.
  50  *
  51  * Typedefed as Gtk::TreeModel::Path.
  52  * @ingroup TreeView
  53  */
  54 class TreePath
  55 {
  56   public:
  57 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  58   typedef TreePath CppObjectType;
  59   typedef GtkTreePath BaseObjectType;
  60
  61   static GType get_type() G_GNUC_CONST;
  62 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  63
  64   TreePath();
  65
  66   explicit TreePath(GtkTreePath* gobject, bool make_a_copy = true);
  67
  68   TreePath(const TreePath& other);
  69   TreePath& operator=(const TreePath& other);
  70
  71   ~TreePath();
  72
  73   void swap(TreePath& other);
  74
  75   ///Provides access to the underlying C instance.
  76   GtkTreePath*       gobj()       { return gobject_; }
  77
  78   ///Provides access to the underlying C instance.
  79   const GtkTreePath* gobj() const { return gobject_; }
  80
  81   ///Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs.
  82   GtkTreePath* gobj_copy() const;
  83
  84 protected:
  85   GtkTreePath* gobject_;
  86
  87 private:
  88
  89
  90 public:
  91   typedef unsigned int  size_type;
  92   typedef int           difference_type;
  93
  94   typedef int           value_type;
  95   typedef int&          reference;
  96   typedef const int&    const_reference;
  97
  98   // Use plain pointers for simplicity.
  99   typedef int*          iterator;
 100   typedef const int*    const_iterator;
 101
 102 #ifndef GLIBMM_HAVE_SUN_REVERSE_ITERATOR
 103
 104   typedef std::reverse_iterator<iterator>       reverse_iterator;
 105   typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
 106
 107 #else
 108
 109   typedef std::reverse_iterator<iterator, std::random_access_iterator_tag,
 110                                 int, int&, int*, ptrdiff_t> reverse_iterator;
 111
 112   typedef std::reverse_iterator<const_iterator, std::random_access_iterator_tag,
 113                                 int, const int&, const int*, ptrdiff_t> const_reverse_iterator;
 114
 115 #endif /* GLIBMM_HAVE_SUN_REVERSE_ITERATOR */
 116
 117   explicit TreePath(size_type n, value_type value = 0);
 118   explicit TreePath(const Glib::ustring& path);
 119   explicit TreePath(const TreeModel::iterator& iter);
 120
 121   template <class In> inline TreePath(In pbegin, In pend);
 122
 123   void clear();
 124
 125   // I think it's OK for this assignment to be implicit.  It's very useful.
 126   TreePath& operator=(const TreeModel::iterator& iter);
 127
 128   template <class In> inline void assign(In pbegin, In pend);
 129   template <class In>        void append(In pbegin, In pend);
 130
 131
 132   /** Appends a new index to a path.  As a result, the depth of the path is
 133    * increased.
 134    * @param index The index.
 135    */
 136   void push_back(int index);
 137
 138   /** Prepends a new index to a path.  As a result, the depth of the path is
 139    * increased.
 140    * @param index The index.
 141    */
 142   void push_front(int index);
 143
 144   size_type size() const;
 145   bool empty() const;
 146
 147   reference       operator[](size_type i);
 148   const_reference operator[](size_type i) const;
 149
 150   iterator begin();
 151   iterator end();
 152   const_iterator begin() const;
 153   const_iterator end()   const;
 154
 155   // Note: there is no advantage in not inlining these methods.
 156   // We can't change them without breaking ABI anyway.
 157   reverse_iterator       rbegin()       { return reverse_iterator(end());         }
 158   reverse_iterator       rend()         { return reverse_iterator(begin());       }
 159   const_reverse_iterator rbegin() const { return const_reverse_iterator(end());   }
 160   const_reverse_iterator rend()   const { return const_reverse_iterator(begin()); }
 161
 162   reference       front()       { return *begin();  }
 163   const_reference front() const { return *begin();  }
 164   reference       back()        { return *rbegin(); }
 165   const_reference back()  const { return *rbegin(); }
 166
 167
 168   /** Moves the @a path  to point to the next node at the current depth.
 169    */
 170   void next();
 171
 172   /** Moves the @a path  to point to the previous node at the current depth, if it exists.
 173    * @return <tt>true</tt> if @a path  has a previous node, and the move was made.
 174    */
 175   bool prev();
 176
 177   /** Moves the @a path  to point to its parent node, if it has a parent.
 178    * @return <tt>true</tt> if @a path  has a parent, and the move was made.
 179    */
 180   bool up();
 181
 182   /** Moves @a path  to point to the first child of the current path.
 183    */
 184   void down();
 185
 186
 187   /** Returns <tt>true</tt> if @a descendant  is a descendant of @a path .
 188    * @param descendant Another Gtk::TreePath.
 189    * @return <tt>true</tt> if @a descendant  is contained inside @a path .
 190    */
 191   bool is_ancestor(const TreePath& descendant) const;
 192
 193   /** Returns <tt>true</tt> if @a path  is a descendant of @a ancestor .
 194    * @param ancestor Another Gtk::TreePath.
 195    * @return <tt>true</tt> if @a ancestor  contains @a path  somewhere below it.
 196    */
 197   bool is_descendant(const TreePath& ancestor) const;
 198
 199
 200   /** Generates a string representation of the path.  This string is a ':'
 201    * separated list of numbers.  For example, "4:10:0:3" would be an acceptable return value for this string.
 202    * @return The string.
 203    */
 204   Glib::ustring to_string() const;
 205
 206
 207 #ifndef GTKMM_DISABLE_DEPRECATED
 208   /// @deprecated replaced by push_back():
 209
 210   /** Appends a new index to a path.  As a result, the depth of the path is
 211    * increased.
 212    * @param index The index.
 213    */
 214   void append_index(int index);
 215   /// @deprecated replaced by push_front():
 216
 217   /** Prepends a new index to a path.  As a result, the depth of the path is
 218    * increased.
 219    * @param index The index.
 220    */
 221   void prepend_index(int index);
 222   /// @deprecated replaced by size():
 223
 224   /** Returns the current depth of @a path .
 225    * @return The depth of @a path .
 226    */
 227   int get_depth() const;
 228
 229   /// @deprecated replaced by begin(), end(), and operator[]
 230   Glib::ArrayHandle<int> get_indices() const;
 231 #endif
 232
 233
 234   /**
 235    * Obtains a Gtk::TreeModel and Gtk::TreeModel::Path from selection data of target type
 236    * "GTK_TREE_MODEL_ROW". Normally called from a drag_data_received handler.
 237    * This function can only be used if @a selection_data originates from the same
 238    * process that's calling this function, because a pointer to the tree model
 239    * is being passed around. If you aren't in the same process, then you'll
 240    * get memory corruption. In the Gtk::TreeDragDest drag_data_received signal handler,
 241    * you can assume that selection data of type "GTK_TREE_MODEL_ROW" is
 242    * from the current process.
 243    *
 244    * @param selection_data a #SelectionData
 245    * @param model a Gtk::TreeModel
 246    * @param path a row in model
 247    *
 248    * @return true if the selection_data had target type "GTK_TREE_MODEL_ROW" and
 249    *  is otherwise valid
 250    **/
 251   static bool get_from_selection_data(const SelectionData& selection_data, Glib::RefPtr<TreeModel>& model, TreePath& path);
 252   //TODO: Add an override that takes a const TreeModel (and deprecate the current version).
 253
 254   /// See description in the other overload.
 255   static bool get_from_selection_data(const SelectionData& selection_data, TreePath& path);
 256
 257   /**
 258    * Sets selection data of target type "GTK_TREE_MODEL_ROW". Normally used
 259    * in a drag_data_get signal handler.
 260    *
 261    * @param selection_data some #SelectionData
 262    * @param model: a Gtk::TreeModel
 263    *
 264    * @return true if the selection_data had the proper target type to allow us to set a tree row
 265    **/
 266   bool set_in_selection_data(SelectionData& selection_data, const Glib::RefPtr<const TreeModel>& model) const;
 267
 268
 269 };
 270
 271 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 272
 273 template <class In>
 274 void TreePath::append(In pbegin, In pend)
 275 {
 276   // push_back() can't throw -- if it could, this code wouldn't be strongly exception-safe.
 277   for(; pbegin != pend; ++pbegin)
 278     this->push_back(*pbegin);
 279 }
 280
 281 template <class In> inline
 282 TreePath::TreePath(In pbegin, In pend)
 283 {
 284   this->append(pbegin, pend);
 285 }
 286
 287 template <class In> inline
 288 void TreePath::assign(In pbegin, In pend)
 289 {
 290   TreePath temp (pbegin, pend);
 291   this->swap(temp);
 292 }
 293
 294
 295 /* Traits for use of TreePath in a Glib::ListHandle<>.
 296  */
 297 struct TreePath_Traits
 298 {
 299   typedef TreePath            CppType;
 300   typedef const GtkTreePath*  CType;
 301   typedef GtkTreePath*        CTypeNonConst;
 302
 303   static CType to_c_type(const CppType& item)
 304     { return item.gobj(); }
 305
 306   static CType to_c_type(CType item)
 307     { return item; }
 308
 309   static CppType to_cpp_type(CType item)
 310     { return CppType(const_cast<CTypeNonConst>(item)); }
 311
 312   static void release_c_type(CType item)
 313     { gtk_tree_path_free(const_cast<CTypeNonConst>(item)); }
 314 };
 315
 316 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 317
 318
 319 } // namespace Gtk
 320
 321
 322 namespace Gtk
 323 {
 324
 325 /** @relates Gtk::TreePath
 326  * @param lhs The left-hand side
 327  * @param rhs The right-hand side
 328  * @result The result
 329  */
 330 bool operator==(const TreePath& lhs, const TreePath& rhs);
 331
 332 /** @relates Gtk::TreePath
 333  * @param lhs The left-hand side
 334  * @param rhs The right-hand side
 335  * @result The result
 336  */
 337 bool operator!=(const TreePath& lhs, const TreePath& rhs);
 338
 339 /** @relates Gtk::TreePath
 340  * @param lhs The left-hand side
 341  * @param rhs The right-hand side
 342  * @result The result
 343  */
 344 bool operator<(const TreePath& lhs, const TreePath& rhs);
 345
 346 /** @relates Gtk::TreePath
 347  * @param lhs The left-hand side
 348  * @param rhs The right-hand side
 349  * @result The result
 350  */
 351 bool operator>(const TreePath& lhs, const TreePath& rhs);
 352
 353 /** @relates Gtk::TreePath
 354  * @param lhs The left-hand side
 355  * @param rhs The right-hand side
 356  * @result The result
 357  */
 358 bool operator<=(const TreePath& lhs, const TreePath& rhs);
 359
 360 /** @relates Gtk::TreePath
 361  * @param lhs The left-hand side
 362  * @param rhs The right-hand side
 363  * @result The result
 364  */
 365 bool operator>=(const TreePath& lhs, const TreePath& rhs);
 366
 367
 368 } // namespace Gtk
 369
 370
 371 namespace Gtk
 372 {
 373
 374 /** @relates Gtk::TreePath
 375  * @param lhs The left-hand side
 376  * @param rhs The right-hand side
 377  */
 378 inline void swap(TreePath& lhs, TreePath& rhs)
 379   { lhs.swap(rhs); }
 380
 381 } // namespace Gtk
 382
 383 namespace Glib
 384 {
 385
 386 /** @relates Gtk::TreePath
 387  * @param object The C instance
 388  * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 389  * @result A C++ instance that wraps this C instance.
 390  */
 391 Gtk::TreePath wrap(GtkTreePath* object, bool take_copy = false);
 392
 393 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 394 template <>
 395 class Value<Gtk::TreePath> : public Glib::Value_Boxed<Gtk::TreePath>
 396 {};
 397 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 398
 399 } // namespace Glib
 400
 401 #endif /* _GTKMM_TREEPATH_H */
 402