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