libs/gtkmm2/gtk/gtkmm/treeselection.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GTKMM_TREESELECTION_H
   4 #define _GTKMM_TREESELECTION_H
   5
   6 #include <glibmm.h>
   7
   8 /* $Id$ */
   9
  10 /* Copyright(C) 1998-1999 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/enums.h>
  29 #include <gtkmm/treemodel.h>
  30 #include <gtkmm/treeiter.h>
  31 #include <gtkmm/treepath.h>
  32
  33
  34 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  35 typedef struct _GtkTreeSelection GtkTreeSelection;
  36 typedef struct _GtkTreeSelectionClass GtkTreeSelectionClass;
  37 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  38
  39
  40 namespace Gtk
  41 { class TreeSelection_Class; } // namespace Gtk
  42 namespace Gtk
  43 {
  44
  45 class TreeView;
  46 class TreeModel;
  47 class TreePath;
  48
  49 /** Typedefed as Gtk::TreeView::Selection.
  50  * This is a helper object to manage the selection for a Gtk::TreeView widget.
  51  *
  52  * It is automatically created when a new Gtk::TreeView widget is created, and
  53  * cannot exist independently of this widget.  The primary reason this class
  54  * exists is for cleanliness of code and API. That is, there is no conceptual
  55  * reason all these methods could not be methods on the Gtk::TreeView widget
  56  * instead of a separate class.
  57  *
  58  * The Gtk::TreeSelection object can be obtained from a Gtk::TreeView by
  59  * calling Gtk::TreeView::get_selection().  It can be manipulated to check the
  60  * selection status of the tree, as well as to select and deselect individual
  61  * rows.  Selection is done completely view-side. As a result, multiple views
  62  * of the same model can have completely different selections.  Additionally,
  63  * you cannot change the selection of a row on the model that is not currently
  64  * displayed by the view without expanding its parents first.
  65  *
  66  * When monitoring the selection of a view, it's important to remember that the
  67  * "changed" signal is mostly a hint. That is, it may only emit one signal when
  68  * a range of rows is selected. Additionally, it may on occasion emit a
  69  * "changed" signal when nothing has happened.
  70  *
  71  * @ingroup TreeView
  72  */
  73
  74 class TreeSelection : public Glib::Object
  75 {
  76
  77 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  78
  79 public:
  80   typedef TreeSelection CppObjectType;
  81   typedef TreeSelection_Class CppClassType;
  82   typedef GtkTreeSelection BaseObjectType;
  83   typedef GtkTreeSelectionClass BaseClassType;
  84
  85 private:  friend class TreeSelection_Class;
  86   static CppClassType treeselection_class_;
  87
  88 private:
  89   // noncopyable
  90   TreeSelection(const TreeSelection&);
  91   TreeSelection& operator=(const TreeSelection&);
  92
  93 protected:
  94   explicit TreeSelection(const Glib::ConstructParams& construct_params);
  95   explicit TreeSelection(GtkTreeSelection* castitem);
  96
  97 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  98
  99 public:
 100   virtual ~TreeSelection();
 101
 102 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 103   static GType get_type()      G_GNUC_CONST;
 104   static GType get_base_type() G_GNUC_CONST;
 105 #endif
 106
 107   ///Provides access to the underlying C GObject.
 108   GtkTreeSelection*       gobj()       { return reinterpret_cast<GtkTreeSelection*>(gobject_); }
 109
 110   ///Provides access to the underlying C GObject.
 111   const GtkTreeSelection* gobj() const { return reinterpret_cast<GtkTreeSelection*>(gobject_); }
 112
 113   ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
 114   GtkTreeSelection* gobj_copy();
 115
 116 private:
 117
 118
 119 protected:
 120
 121
 122 public:
 123
 124   /** Sets the selection mode of the @a selection .  If the previous type was
 125    * Gtk::SELECTION_MULTIPLE, then the anchor is kept selected, if it was
 126    * previously selected.
 127    * @param type The selection mode.
 128    */
 129   void set_mode(SelectionMode type);
 130
 131   /** Gets the selection mode for @a selection . See
 132    * set_mode().
 133    * @return The current selection mode.
 134    */
 135   SelectionMode get_mode() const;
 136
 137   /** For instance, bool on_select_function(const Glib::RefPtr<TreeModel>& model, const TreeModel::Path& path, bool path_currently_selected)
 138    * The select function should return true if the state of the node may be toggled,
 139    * and false if the state of the node should be left unchanged.
 140    */
 141   typedef sigc::slot<bool, const Glib::RefPtr<TreeModel>&, const TreeModel::Path&, bool> SlotSelect;
 142
 143   /** Sets the selection callback slot. If set, this function is called before any node is selected or unselected,
 144    * giving some control over which nodes are selected.
 145    *
 146    * The select function should return true if the state of the node may be toggled, and FALSE if the state of the node
 147    * should be left unchanged.
 148    *
 149    * @param slot The selection function.
 150    */
 151   void set_select_function(const SlotSelect& slot);
 152
 153    // This would be our SignalProxy_Select* data.
 154
 155
 156   /** Returns the tree view associated with @a selection .
 157    * @return A Gtk::TreeView.
 158    */
 159   TreeView* get_tree_view();
 160
 161   /** Returns the tree view associated with @a selection .
 162    * @return A Gtk::TreeView.
 163    */
 164   const TreeView* get_tree_view() const;
 165
 166   /** Shortcut for get_tree_view()->get_model().
 167    * @return The TreeModel associated with this TreeSelection.
 168    */
 169   Glib::RefPtr<TreeModel> get_model(); // convenience function, not in GTK+
 170   Glib::RefPtr<const TreeModel> get_model() const; // convenience function, not in GTK+
 171
 172   //TODO: Add TreeModel::const_iterator get_selected() const, when we have a real const_iterator.
 173
 174   /** Get the currently selected row.
 175    * @return The currently selected row.
 176    * @note
 177    * This method won't work if the selection mode is <tt>Gtk::SELECTION_MULTIPLE</tt>.
 178    * Use get_selected_rows() for multiple selections.
 179    */
 180   TreeModel::iterator get_selected();
 181
 182   /** Get the currently selected row.
 183    * @return The currently selected row. Or end() if no rows were selected.
 184    * @retval model The current TreeModel.
 185    * @note
 186    * This method won't work if the selection mode is <tt>Gtk::SELECTION_MULTIPLE</tt>.
 187    * Use get_selected_rows() for multiple selections.
 188    */
 189   TreeModel::iterator get_selected(Glib::RefPtr<TreeModel>& model);
 190
 191   typedef Glib::ListHandle<TreeModel::Path, TreePath_Traits> ListHandle_Path;
 192
 193   /** Creates a list of paths of all selected rows.
 194    * Additionally, if you are planning on modifying the model after calling this function,
 195    * you may want to convert the returned list into a list of GtkTreeRowReferences.
 196    *
 197    * @returns a standard container containing a Gtk::Model::Path for each selected row.
 198    */
 199   ListHandle_Path get_selected_rows() const;
 200
 201   /** Creates a list of paths of all selected rows.
 202    * Additionally, if you are planning on modifying the model after calling this function,
 203    * you may want to convert the returned list into a list of GtkTreeRowReferences.
 204    *
 205    * @retval model The current TreeModel.
 206    * @returns a standard container containing a Gtk::Model::Path for each selected row.
 207    */
 208   ListHandle_Path get_selected_rows(Glib::RefPtr<TreeModel>& model);
 209
 210
 211   /** Returns the number of rows that have been selected in @a tree .
 212    * @return The number of rows selected.
 213    *
 214    * Since: 2.2.
 215    */
 216   int count_selected_rows() const;
 217
 218   //TODO: Consider deprecating these selected_foreach() methods, because get_selected_rows() should be enough.
 219
 220   //TODO: SlotForEachIter should take a const_iterator, when we have a real const iterator.
 221   /** For example,
 222    * void on_foreach(const Gtk::TreeModel::iterator& iter);
 223    *
 224    * Note that you cannot modify the tree or selection from within the callback function.
 225    * As a result, get_selected_rows() might be more useful.
 226    */
 227   typedef sigc::slot<void, const TreeModel::iterator&> SlotForeachIter;
 228
 229   /** Calls a callback slot for each selected node.
 230    * Note that you cannot modify the tree or selection from within the callback function.
 231    * As a result, get_selected_rows() might be more useful.
 232    *
 233    * @param slot The function to call for each selected node.
 234    */
 235   void selected_foreach_iter(const SlotForeachIter& slot) const;
 236
 237   /** For example,
 238    * void on_foreach(const Gtk::TreeModel::Path& path);
 239    *
 240    * Note that you cannot modify the tree or selection from within the callback function.
 241    * As a result, get_selected_rows() might be more useful.
 242    */
 243   typedef sigc::slot<void, const TreeModel::Path&> SlotForeachPath;
 244
 245   /** Calls a callback slot for each selected node.
 246    * Note that you cannot modify the tree or selection from within the callback function.
 247    * As a result, get_selected_rows() might be more useful.
 248    *
 249    * @param slot The function to call for each selected node.
 250    */
 251   void selected_foreach_path(const SlotForeachPath& slot) const;
 252
 253
 254   /** For example,
 255    * void on_foreach(const Gtk::TreeModel::Path& path, const Gtk::TreeModel::iterator& iter);
 256    *
 257    * Note that you cannot modify the tree or selection from within the callback function.
 258    * As a result, get_selected_rows() might be more useful.
 259    */
 260   typedef sigc::slot<void, const TreeModel::Path&, const TreeModel::iterator&> SlotForeachPathAndIter;
 261
 262   /** Calls a callback slot for each selected node.
 263    * Note that you cannot modify the tree or selection from within the callback function.
 264    * As a result, get_selected_rows() might be more useful.
 265    *
 266    * @param slot The function to call for each selected node.
 267    */
 268   void selected_foreach(const SlotForeachPathAndIter& slot) const;
 269
 270
 271   /** Select the row at @a path .
 272    * @param path The Gtk::TreePath to be selected.
 273    */
 274   void select(const TreeModel::Path& path);
 275
 276   /** Selects the specified iterator.
 277    * @param iter The Gtk::TreeIter to be selected.
 278    */
 279   void select(const TreeModel::iterator& iter);
 280
 281   /** Selects the specified iterator.
 282    * @param iter The Gtk::TreeIter to be selected.
 283    */
 284   void select(const TreeModel::Row& row);
 285
 286   /** Selects a range of nodes, determined by @a start_path  and @a end_path  inclusive.
 287    *  @a selection  must be set to Gtk::SELECTION_MULTIPLE mode.
 288    * @param start_path The initial node of the range.
 289    * @param end_path The final node of the range.
 290    */
 291   void select(const TreeModel::Path& start_path, const TreeModel::Path& end_path);
 292
 293
 294   /** Unselects the row at @a path .
 295    * @param path The Gtk::TreePath to be unselected.
 296    */
 297   void unselect(const TreeModel::Path& path);
 298
 299   /** Unselects a range of nodes, determined by @a start_path  and @a end_path
 300    * inclusive.
 301    *
 302    * Since: 2.2
 303    * @param start_path The initial node of the range.
 304    * @param end_path The initial node of the range.
 305    */
 306   void unselect(const TreeModel::Path& start_path, const TreeModel::Path& end_path);
 307
 308   /** Unselects the specified iterator.
 309    * @param iter The Gtk::TreeIter to be unselected.
 310    */
 311   void unselect(const TreeModel::iterator& iter);
 312
 313
 314   /** Returns <tt>true</tt> if the row pointed to by @a path  is currently selected.  If @a path
 315    * does not point to a valid location, <tt>false</tt> is returned
 316    * @param path A Gtk::TreePath to check selection on.
 317    * @return <tt>true</tt> if @a path  is selected.
 318    */
 319   bool is_selected(const TreeModel::Path& path) const;
 320
 321   /** Returns <tt>true</tt> if the row at @a iter  is currently selected.
 322    * @param iter A valid Gtk::TreeIter.
 323    * @return <tt>true</tt>, if @a iter  is selected.
 324    */
 325   bool is_selected(const TreeModel::iterator& iter) const;
 326
 327
 328   /** Selects all the nodes. @a selection  must be set to Gtk::SELECTION_MULTIPLE
 329    * mode.
 330    */
 331   void select_all();
 332
 333   /** Unselects all the nodes.
 334    */
 335   void unselect_all();
 336
 337
 338   Glib::SignalProxy0< void > signal_changed();
 339
 340
 341 public:
 342
 343 public:
 344   //C++ methods used to invoke GTK+ virtual functions:
 345
 346 protected:
 347   //GTK+ Virtual Functions (override these to change behaviour):
 348
 349   //Default Signal Handlers::
 350   virtual void on_changed();
 351
 352
 353 };
 354
 355 } // namespace Gtk
 356
 357
 358 namespace Glib
 359 {
 360   /** @relates Gtk::TreeSelection
 361    * @param object The C instance
 362    * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 363    * @result A C++ instance that wraps this C instance.
 364    */
 365   Glib::RefPtr<Gtk::TreeSelection> wrap(GtkTreeSelection* object, bool take_copy = false);
 366 }
 367
 368
 369 #endif /* _GTKMM_TREESELECTION_H */
 370