libs/gtkmm2/gtk/gtkmm/iconview.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GTKMM_ICONVIEW_H
   4 #define _GTKMM_ICONVIEW_H
   5
   6
   7 #include <glibmm.h>
   8
   9 /* $Id$ */
  10
  11 /* iconview.h
  12  *
  13  * Copyright (C) 1998-2004 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
  31 #include <gtkmm/container.h>
  32 #include <gtkmm/treemodel.h>
  33 #include <gtkmm/treepath.h>
  34 #include <gtkmm/cellrenderer.h>
  35 #include <gtkmm/tooltip.h>
  36
  37
  38 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  39 typedef struct _GtkIconView GtkIconView;
  40 typedef struct _GtkIconViewClass GtkIconViewClass;
  41 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  42
  43
  44 namespace Gtk
  45 { class IconView_Class; } // namespace Gtk
  46 namespace Gtk
  47 {
  48
  49 /** @addtogroup gtkmmEnums Enums and Flags */
  50
  51 /**
  52  * @ingroup gtkmmEnums
  53  */
  54 enum IconViewDropPosition
  55 {
  56   ICON_VIEW_NO_DROP,
  57   ICON_VIEW_DROP_INTO,
  58   ICON_VIEW_DROP_LEFT,
  59   ICON_VIEW_DROP_RIGHT,
  60   ICON_VIEW_DROP_ABOVE,
  61   ICON_VIEW_DROP_BELOW
  62 };
  63
  64 } // namespace Gtk
  65
  66
  67 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  68 namespace Glib
  69 {
  70
  71 template <>
  72 class Value<Gtk::IconViewDropPosition> : public Glib::Value_Enum<Gtk::IconViewDropPosition>
  73 {
  74 public:
  75   static GType value_type() G_GNUC_CONST;
  76 };
  77
  78 } // namespace Glib
  79 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  80
  81
  82 namespace Gtk
  83 {
  84
  85
  86 //TODO: This should derive+implement from CellLayout when we can break ABI.
  87
  88 /** The IconView provides an alternative view of a list model.
  89  * It displays the model as a grid of icons with labels.
  90  * Like the TreeView, it allows the user to select one or multiple items
  91  * (depending on the selection mode - see set_selection_mode()).
  92  * In addition to selection with the arrow keys, the IconView supports
  93  * rubberband selection, by dragging the pointer.
  94  *
  95  * @ingroup Widgets
  96  * @ingroup Containers
  97  */
  98
  99 class IconView : public Container
 100 {
 101   public:
 102 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 103   typedef IconView CppObjectType;
 104   typedef IconView_Class CppClassType;
 105   typedef GtkIconView BaseObjectType;
 106   typedef GtkIconViewClass BaseClassType;
 107 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 108
 109   virtual ~IconView();
 110
 111 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 112
 113 private:
 114   friend class IconView_Class;
 115   static CppClassType iconview_class_;
 116
 117   // noncopyable
 118   IconView(const IconView&);
 119   IconView& operator=(const IconView&);
 120
 121 protected:
 122   explicit IconView(const Glib::ConstructParams& construct_params);
 123   explicit IconView(GtkIconView* castitem);
 124
 125 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 126
 127 public:
 128 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 129   static GType get_type()      G_GNUC_CONST;
 130   static GType get_base_type() G_GNUC_CONST;
 131 #endif
 132
 133   ///Provides access to the underlying C GtkObject.
 134   GtkIconView*       gobj()       { return reinterpret_cast<GtkIconView*>(gobject_); }
 135
 136   ///Provides access to the underlying C GtkObject.
 137   const GtkIconView* gobj() const { return reinterpret_cast<GtkIconView*>(gobject_); }
 138
 139
 140 public:
 141   //C++ methods used to invoke GTK+ virtual functions:
 142 #ifdef GLIBMM_VFUNCS_ENABLED
 143 #endif //GLIBMM_VFUNCS_ENABLED
 144
 145 protected:
 146   //GTK+ Virtual Functions (override these to change behaviour):
 147 #ifdef GLIBMM_VFUNCS_ENABLED
 148 #endif //GLIBMM_VFUNCS_ENABLED
 149
 150   //Default Signal Handlers::
 151 #ifdef GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED
 152   virtual void on_set_scroll_adjustments(Adjustment* hadjustment, Adjustment* vadjustment);
 153   virtual void on_item_activated(const TreeModel::Path& path);
 154   virtual void on_selection_changed();
 155 #endif //GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED
 156
 157
 158 private:
 159
 160 public:
 161
 162   IconView();
 163   explicit IconView(const Glib::RefPtr<TreeModel>& model);
 164
 165
 166   /** Sets the model for a Gtk::IconView.
 167    * If the @a icon_view  already has a model set, it will remove
 168    * it before setting the new model.  If @a model  is <tt>0</tt>, then
 169    * it will unset the old model.
 170    *
 171    * @newin2p6
 172    * @param model The model.
 173    */
 174   void set_model(const Glib::RefPtr<TreeModel>& model);
 175
 176   /** Return value: A Gtk::TreeModel, or <tt>0</tt> if none is currently being used.
 177    * @return A Gtk::TreeModel, or <tt>0</tt> if none is currently being used.
 178    *
 179    * @newin2p6.
 180    */
 181   Glib::RefPtr<TreeModel> get_model();
 182
 183   /** Return value: A Gtk::TreeModel, or <tt>0</tt> if none is currently being used.
 184    * @return A Gtk::TreeModel, or <tt>0</tt> if none is currently being used.
 185    *
 186    * @newin2p6.
 187    */
 188   Glib::RefPtr<const TreeModel> get_model() const;
 189
 190
 191   /** Sets the column with text for @a icon_view  to be @a column . The text
 192    * column must be of type G::TYPE_STRING.
 193    *
 194    * @newin2p6
 195    * @param column A column in the currently used model, or -1 to display no text.
 196    */
 197   void set_text_column(int column);
 198
 199   /** Sets the column with text for @a icon_view  to be @a column . The text
 200    * column must be of type G::TYPE_STRING.
 201    *
 202    * @newin2p6
 203    * @param column A column in the currently used model, or -1 to display no text.
 204    */
 205   void set_text_column(const TreeModelColumnBase& model_column);
 206
 207   /** Returns: the text column, or -1 if it's unset.
 208    * @return The text column, or -1 if it's unset.
 209    *
 210    * @newin2p6.
 211    */
 212   int get_text_column() const;
 213
 214   /** Sets the column with markup information for @a icon_view  to be
 215    *  @a column . The markup column must be of type G::TYPE_STRING.
 216    * If the markup column is set to something, it overrides
 217    * the text column set by set_text_column().
 218    *
 219    * @newin2p6
 220    * @param column A column in the currently used model, or -1 to display no text.
 221    */
 222   void set_markup_column(int column);
 223
 224   /** Sets the column with markup information for @a icon_view  to be
 225    *  @a column . The markup column must be of type G::TYPE_STRING.
 226    * If the markup column is set to something, it overrides
 227    * the text column set by set_text_column().
 228    *
 229    * @newin2p6
 230    * @param column A column in the currently used model, or -1 to display no text.
 231    */
 232   void set_markup_column(const TreeModelColumnBase& column);
 233
 234   /** Returns: the markup column, or -1 if it's unset.
 235    * @return The markup column, or -1 if it's unset.
 236    *
 237    * @newin2p6.
 238    */
 239   int get_markup_column() const;
 240
 241   /** Sets the column with pixbufs for @a icon_view  to be @a column . The pixbuf
 242    * column must be of type Gdk::TYPE_PIXBUF
 243    *
 244    * @newin2p6
 245    * @param column A column in the currently used model, or -1 to disable.
 246    */
 247   void set_pixbuf_column(int column);
 248
 249   /** Sets the column with pixbufs for @a icon_view  to be @a column . The pixbuf
 250    * column must be of type Gdk::TYPE_PIXBUF
 251    *
 252    * @newin2p6
 253    * @param column A column in the currently used model, or -1 to disable.
 254    */
 255   void set_pixbuf_column(const TreeModelColumnBase& column);
 256
 257   /** Returns: the pixbuf column, or -1 if it's unset.
 258    * @return The pixbuf column, or -1 if it's unset.
 259    *
 260    * @newin2p6.
 261    */
 262   int get_pixbuf_column() const;
 263
 264
 265   /** Sets the ::orientation property which determines whether the labels
 266    * are drawn beside the icons instead of below.
 267    *
 268    * @newin2p6
 269    * @param orientation The relative position of texts and icons.
 270    */
 271   void set_orientation(Orientation orientation);
 272
 273   /** Return value: the relative position of texts and icons
 274    * @return The relative position of texts and icons
 275    *
 276    * @newin2p6.
 277    */
 278   Orientation get_orientation() const;
 279
 280
 281   /** Sets the ::columns property which determines in how
 282    * many columns the icons are arranged. If @a columns  is
 283    * -1, the number of columns will be chosen automatically
 284    * to fill the available area.
 285    *
 286    * @newin2p6
 287    * @param columns The number of columns.
 288    */
 289   void set_columns(int columns);
 290
 291   /** Return value: the number of columns, or -1
 292    * @return The number of columns, or -1
 293    *
 294    * @newin2p6.
 295    */
 296   int get_columns() const;
 297
 298   /** Sets the ::item-width property which specifies the width
 299    * to use for each item. If it is set to -1, the icon view will
 300    * automatically determine a suitable item size.
 301    *
 302    * @newin2p6
 303    * @param item_width The width for each item.
 304    */
 305   void set_item_width(int item_width);
 306
 307   /** Return value: the width of a single item, or -1
 308    * @return The width of a single item, or -1
 309    *
 310    * @newin2p6.
 311    */
 312   int get_icon_width() const;
 313
 314   /** Sets the ::spacing property which specifies the space
 315    * which is inserted between the cells (i.e.\ the icon and
 316    * the text) of an item.
 317    *
 318    * @newin2p6
 319    * @param spacing The spacing.
 320    */
 321   void set_spacing(int spacing);
 322
 323   /** Return value: the space between cells
 324    * @return The space between cells
 325    *
 326    * @newin2p6.
 327    */
 328   int get_spacing() const;
 329
 330   /** Sets the ::row-spacing property which specifies the space
 331    * which is inserted between the rows of the icon view.
 332    *
 333    * @newin2p6
 334    * @param row_spacing The row spacing.
 335    */
 336   void set_row_spacing(int row_spacing);
 337
 338   /** Return value: the space between rows
 339    * @return The space between rows
 340    *
 341    * @newin2p6.
 342    */
 343   gint get_row_spacing() const;
 344
 345   /** Sets the ::column-spacing property which specifies the space
 346    * which is inserted between the columns of the icon view.
 347    *
 348    * @newin2p6
 349    * @param column_spacing The column spacing.
 350    */
 351   void set_column_spacing(int column_spacing);
 352
 353   /** Return value: the space between columns
 354    * @return The space between columns
 355    *
 356    * @newin2p6.
 357    */
 358   int get_column_spacing() const;
 359
 360
 361   /** Sets the ::margin property which specifies the space
 362    * which is inserted at the top, bottom, left and right
 363    * of the icon view.
 364    *
 365    * @newin2p6
 366    * @param margin The margin.
 367    */
 368   void set_margin(int margin);
 369
 370   /** Return value: the space at the borders
 371    * @return The space at the borders
 372    *
 373    * @newin2p6.
 374    */
 375   int get_margin() const;
 376
 377
 378   /** Finds the path at the point ( @a x , @a y ), relative to bin_window coordinates.
 379    * See get_item_at_pos(), if you are also interested in
 380    * the cell at the specified position.
 381    * See convert_widget_to_bin_window_coords() for converting
 382    * widget coordinates to bin_window coordinates.
 383    * @param x The x position to be identified.
 384    * @param y The y position to be identified.
 385    * @return The Gtk::TreePath corresponding to the icon or <tt>0</tt>
 386    * if no icon exists at that position.
 387    *
 388    * @newin2p6.
 389    */
 390   TreeModel::Path get_path_at_pos(int x, int y) const;
 391
 392
 393   /** Finds the path at the point (@a x, @a y), relative to widget coordinates.
 394    *
 395    * @param x The x position to be identified.
 396    * @param y The y position to be identified.
 397    * @param path The path.
 398    * @param cell The renderer responsible for the cell at (@a x, @a y).
 399    *
 400    * @result true if an item exists at the specified position.
 401    *
 402    * @newin2p6
 403    */
 404   bool get_item_at_pos(int x, int y, TreeModel::Path& path, CellRenderer*& cell) const;
 405
 406   /** Finds the path at the point (@a x, @a y), relative to widget coordinates.
 407    *
 408    * @param x The x position to be identified.
 409    * @param y The y position to be identified.
 410    * @param path The path.
 411    *
 412    * @result true if an item exists at the specified position.
 413    *
 414    * @newin2p6
 415    */
 416   bool get_item_at_pos(int x, int y, TreeModel::Path& path) const;
 417
 418   /** Finds the path at the point (@a x, @a y), relative to widget coordinates.
 419    *
 420    * @param x The x position to be identified.
 421    * @param y The y position to be identified.
 422    * @param path The path.
 423    *
 424    * @result true if an item exists at the specified position.
 425    *
 426    * @newin2p6
 427    */
 428   bool get_item_at_pos(int x, int y, CellRenderer*& cell) const;
 429
 430
 431   bool get_visible_range(TreeModel::Path& start_path, TreeModel::Path& end_path) const;
 432
 433
 434   /** For instance,
 435    * void on_foreach(const Gtk::TreeModel::Path& path);
 436    */
 437   typedef sigc::slot<void, const TreeModel::Path&> SlotForeach;
 438
 439   /** Calls a function for each selected icon. Note that the model or
 440   * selection cannot be modified from within this function.
 441   *
 442   * @param slot The callback to call for each selected icon.
 443   */
 444   void selected_foreach(const SlotForeach& slot);
 445
 446
 447 //Default value?:
 448
 449   /** Sets the selection mode of the @a icon_view .
 450    *
 451    * @newin2p6
 452    * @param mode The selection mode.
 453    */
 454   void set_selection_mode(SelectionMode mode);
 455
 456   /** Gets the selection mode of the @a icon_view .
 457    * @return The current selection mode
 458    *
 459    * @newin2p6.
 460    */
 461   SelectionMode get_selection_mode() const;
 462
 463   /** Selects the row at @a path .
 464    *
 465    * @newin2p6
 466    * @param path The Gtk::TreePath to be selected.
 467    */
 468   void select_path(const TreeModel::Path& path);
 469
 470   /** Unselects the row at @a path .
 471    *
 472    * @newin2p6
 473    * @param path The Gtk::TreePath to be unselected.
 474    */
 475   void unselect_path(const TreeModel::Path& path);
 476
 477   /** Return value: <tt>true</tt> if @a path  is selected.
 478    * @param path A Gtk::TreePath to check selection on.
 479    * @return <tt>true</tt> if @a path  is selected.
 480    *
 481    * @newin2p6.
 482    */
 483   bool path_is_selected(const TreeModel::Path& path) const;
 484
 485
 486   #ifndef DOXYGEN_SHOULD_SKIP_THIS
 487   //TODO: I'm not sure about these to_*() functions. murrayc.
 488   struct TreePathTraits
 489   {
 490     typedef TreePath  CppType;
 491     typedef const GtkTreePath* CType;
 492     typedef GtkTreePath*    CTypeNonConst;
 493
 494     static CType   to_c_type      (const CppType& obj) { return obj.gobj(); }
 495     static CType   to_c_type      (const CType&   obj) { return obj; }
 496     static CppType to_cpp_type    (const CType&   obj) { return CppType(const_cast<CTypeNonConst>(obj), true); }
 497     static void    release_c_type (const CType&)       {}
 498   };
 499   #endif //DOXYGEN_SHOULD_SKIP_THIS
 500
 501   typedef Glib::ListHandle<TreePath, TreePathTraits> ArrayHandle_TreePaths;
 502
 503
 504   /** Creates a list of paths of all selected items. Additionally, if you are
 505    * planning on modifying the model after calling this function, you may
 506    * want to convert the returned list into a list of Gtk::TreeRowReference&lt;!-- --&gt;s.
 507    * To do this, you can use Gtk::Tree::row_reference_new().
 508    *
 509    * To free the return value, use:
 510    * @code
 511    * g_list_foreach (list, gtk_tree_path_free, <tt>0</tt>);
 512    * g_list_free (list);
 513    * @endcode
 514    * @return A G::List containing a Gtk::TreePath for each selected row.
 515    *
 516    * @newin2p6.
 517    */
 518   ArrayHandle_TreePaths get_selected_items() const;
 519
 520
 521   /** Selects all the icons. @a icon_view  must has its selection mode set
 522    * to Gtk::SELECTION_MULTIPLE.
 523    *
 524    * @newin2p6
 525    */
 526   void select_all();
 527
 528   /** Unselects all the icons.
 529    *
 530    * @newin2p6
 531    */
 532   void unselect_all();
 533
 534   /** Activates the item determined by @a path .
 535    *
 536    * @newin2p6
 537    * @param path The Gtk::TreePath to be activated.
 538    */
 539   void item_activated(const TreeModel::Path& path);
 540
 541   //TODO: Add a version with no cell parameter.
 542
 543   /** Sets the current keyboard focus to be at @a path , and selects it.  This is
 544    * useful when you want to focus the user's attention on a particular item.
 545    * If @a cell  is not <tt>0</tt>, then focus is given to the cell specified by
 546    * it. Additionally, if @a start_editing  is <tt>true</tt>, then editing should be
 547    * started in the specified cell.
 548    *
 549    * This function is often followed by <tt>gtk_widget_grab_focus
 550    * (icon_view)</tt> in order to give keyboard focus to the widget.
 551    * Please note that editing can only happen when the widget is realized.
 552    *
 553    * @newin2p8
 554    * @param path A Gtk::TreePath.
 555    * @param cell One of the cell renderers of @a icon_view , or <tt>0</tt>.
 556    * @param start_editing <tt>true</tt> if the specified cell should start being edited.
 557    */
 558   void set_cursor(const TreeModel::Path& path, CellRenderer& cell, bool start_editing);
 559
 560   /** Fills in @a path and @a cell with the current cursor path and cell.
 561    * If the cursor isn't currently set, then @a path will be empty.
 562    * If no cell currently has focus, then @a cell will be NULL.
 563    *
 564    * @param path The current cursor path.
 565    * @param cell The current focus cell.
 566    * @result true if the cursor is set.
 567    *
 568    * @newin2p8
 569    */
 570   bool get_cursor(TreeModel::Path& path, CellRenderer*& cell) const;
 571
 572   /** Fills in @a path and @a cell with the current cursor path and cell.
 573    * If the cursor isn't currently set, then @a path will be empty.
 574    * If no cell currently has focus, then @a cell will be NULL.
 575    *
 576    * @param path The current cursor path.
 577    * @result true if the cursor is set.
 578    *
 579    * @newin2p8
 580    */
 581   bool get_cursor(TreeModel::Path& path) const;
 582
 583   /** Fills in @a path and @a cell with the current cursor path and cell.
 584    * If the cursor isn't currently set, then @a path will be empty.
 585    * If no cell currently has focus, then @a cell will be NULL.
 586    *
 587    * @param cell The current focus cell.
 588    * @result true if the cursor is set.
 589    *
 590    * @newin2p8
 591    */
 592   bool get_cursor(CellRenderer*& cell) const;
 593
 594
 595   /** Moves the alignments of @a icon_view  to the position specified by @a path .
 596    *  @a row_align  determines where the row is placed, and @a col_align  determines
 597    * where @a column  is placed.  Both are expected to be between 0.0 and 1.0.
 598    * 0.0 means left/top alignment, 1.0 means right/bottom alignment, 0.5 means
 599    * center.
 600    *
 601    * If @a use_align  is <tt>false</tt>, then the alignment arguments are ignored, and the
 602    * tree does the minimum amount of work to scroll the item onto the screen.
 603    * This means that the item will be scrolled to the edge closest to its current
 604    * position.  If the item is currently visible on the screen, nothing is done.
 605    *
 606    * This function only works if the model is set, and @a path  is a valid row on
 607    * the model. If the model changes before the @a icon_view  is realized, the
 608    * centered path will be modified to reflect this change.
 609    *
 610    * @newin2p8
 611    * @param path The path of the item to move to.
 612    * @param use_align Whether to use alignment arguments, or <tt>false</tt>.
 613    * @param row_align The vertical alignment of the item specified by @a path .
 614    * @param col_align The horizontal alignment of the item specified by @a path .
 615    */
 616   void scroll_to_path(const TreeModel::Path& path, bool use_align, gfloat row_align, gfloat col_align);
 617
 618 /* Drag-and-Drop support */
 619   /**
 620    * Turns the IconView into a drag source for automatic DND.
 621    *
 622    * @param targets Standard container of targets that the drag will support.
 623    * @param start_button_mask Mask of allowed buttons to start drag.
 624    * @param actions The bitmask of possible actions for a drag from this widget.
 625    */
 626   void enable_model_drag_source(const ArrayHandle_TargetEntry& targets,
 627                                 Gdk::ModifierType start_button_mask = Gdk::MODIFIER_MASK,
 628                                 Gdk::DragAction actions = Gdk::ACTION_COPY | Gdk::ACTION_MOVE);
 629
 630
 631   /** Turns the IconView into a drop destination for automatic DND.
 632    *
 633    * @param targets The table of targets that the drag will support.
 634    * @param actions The bitmask of possible actions for a drag from this widget.
 635    */
 636   void enable_model_drag_dest(const ArrayHandle_TargetEntry& targets, Gdk::DragAction actions = Gdk::ACTION_COPY | Gdk::ACTION_MOVE);
 637
 638
 639   /** Undoes the effect of enable_model_drag_source().
 640    *
 641    * @newin2p8
 642    */
 643   void unset_model_drag_source();
 644
 645   /** Undoes the effect of enable_model_drag_dest().
 646    *
 647    * @newin2p8
 648    */
 649   void unset_model_drag_dest();
 650
 651
 652   /** This function is a convenience function to allow you to reorder models that
 653    * support the Gtk::TreeDragSourceIface and the Gtk::TreeDragDestIface.  Both
 654    * Gtk::TreeStore and Gtk::ListStore support these.  If @a reorderable  is <tt>true</tt>, then
 655    * the user can reorder the model by dragging and dropping rows.  The
 656    * developer can listen to these changes by connecting to the model's
 657    * row_inserted and row_deleted signals.
 658    *
 659    * This function does not give you any degree of control over the order -- any
 660    * reordering is allowed.  If more control is needed, you should probably
 661    * handle drag and drop manually.
 662    *
 663    * @newin2p8
 664    * @param reorderable <tt>true</tt>, if the list of items can be reordered.
 665    */
 666   void set_reorderable(bool reorderable = true);
 667
 668   /** Retrieves whether the user can reorder the list via drag-and-drop.
 669    * See set_reorderable().
 670    * @return <tt>true</tt> if the list can be reordered.
 671    *
 672    * @newin2p8.
 673    */
 674   bool get_reorderable() const;
 675
 676
 677 /* These are useful to implement your own custom stuff. */
 678   //TODO: Discover what arguments are output arguments:
 679
 680   /** Sets the item that is highlighted for feedback.
 681    *
 682    * @newin2p8
 683    * @param path The path of the item to highlight, or <tt>0</tt>.
 684    * @param pos Specifies where to drop, relative to the item.
 685    */
 686   void set_drag_dest_item(const TreeModel::Path& path, IconViewDropPosition pos);
 687
 688   /** Gets information about the item that is highlighted for feedback.
 689    *
 690    * @param path The highlighted item.
 691    * @pos The drop position.
 692    *
 693    * @newin2p10
 694    */
 695   void get_drag_dest_item(TreeModel::Path& path, IconViewDropPosition& pos) const;
 696
 697   /** Gets information about the item that is highlighted for feedback.
 698    *
 699    * @param path The highlighted item.
 700    *
 701    * @newin2p10
 702    */
 703   void get_drag_dest_item(TreeModel::Path& path) const;
 704
 705   /** Gets information about the item that is highlighted for feedback.
 706    *
 707    * @pos The drop position.
 708    *
 709    * @newin2p10
 710    */
 711   void get_drag_dest_item(IconViewDropPosition& pos) const;
 712
 713
 714   /** Determines the destination item for a given position.
 715    *
 716    * @param drag_x The position to determine the destination item for.
 717    * @param drag_y the position to determine the destination item for.
 718    * @param path The path of the item.
 719    * @param pos: The drop position.
 720    * @result whether there is an item at the given position.
 721    *
 722    * @newin2p10
 723    */
 724   bool get_dest_item_at_pos(int drag_x, int drag_y, TreeModel::Path& path, IconViewDropPosition& pos) const;
 725
 726   /** Determines the destination item for a given position.
 727    *
 728    * @param drag_x The position to determine the destination item for.
 729    * @param drag_y the position to determine the destination item for.
 730    * @param path The path of the item.
 731    * @result whether there is an item at the given position.
 732    *
 733    * @newin2p10
 734    */
 735   bool get_dest_item_at_pos(int drag_x, int drag_y, TreeModel::Path& path) const;
 736
 737   /** Determines the destination item for a given position.
 738    *
 739    * @param drag_x The position to determine the destination item for.
 740    * @param drag_y the position to determine the destination item for.
 741    * @param pos: The drop position.
 742    * @result whether there is an item at the given position.
 743    *
 744    * @newin2p10
 745    */
 746   bool get_dest_item_at_pos(int drag_x, int drag_y, IconViewDropPosition& pos) const;
 747
 748
 749   /** Creates a Gdk::Pixmap representation of the item at @a path .
 750    * This image is used for a drag icon.
 751    * @param path A Gtk::TreePath in @a icon_view .
 752    * @return A newly-allocated pixmap of the drag icon.
 753    *
 754    * @newin2p8.
 755    */
 756   Glib::RefPtr<Gdk::Pixmap> create_drag_icon( const TreeModel::Path& path);
 757
 758
 759   /** Converts widget coordinates to coordinates for the bin_window,
 760    * as expected by e.g.\ get_path_at_pos().
 761    *
 762    * @newin2p12
 763    * @param wy Y coordinate relative to the widget.
 764    * @param bx Return location for bin_window X coordinate.
 765    * @param by Return location for bin_window Y coordinate.
 766    */
 767   void convert_widget_to_bin_window_coords(int wx, int wy, int& bx, int& by) const;
 768
 769
 770   /** Sets the tip area of @a tooltip  to be the area covered by the item at @a path .
 771    * See also Tooltip::set_tip_area().
 772    *
 773    * @newin2p12
 774    * @param tooltip A Gtk::Tooltip.
 775    * @param path A Gtk::TreePath.
 776    */
 777   void set_tooltip_item(const Glib::RefPtr<Tooltip>& tooltip, const TreeModel::Path& path);
 778
 779   /** Sets the tip area of @a tooltip  to the area which @a cell  occupies in
 780    * the item pointed to by @a path . See also Tooltip::set_tip_area().
 781    *
 782    * @newin2p12
 783    * @param tooltip A Gtk::Tooltip.
 784    * @param path A Gtk::TreePath.
 785    * @param cell A Gtk::CellRenderer.
 786    */
 787   void set_tooltip_cell(const Glib::RefPtr<Tooltip>& tooltip, const TreeModel::Path& path, CellRenderer& cell);
 788
 789   /** Sets the tip area of @a tooltip to the area occupied by
 790    * the item pointed to by @a path. See also Tooltip::set_tip_area().
 791    *
 792    * @newin2p12
 793    * @param tooltip A Gtk::Tooltip.
 794    * @param path A Gtk::TreePath.
 795    */
 796   void set_tooltip_cell(const Glib::RefPtr<Tooltip>& tooltip, const TreeModel::Path& path);
 797
 798
 799   /**
 800    * @param x: the x coordinate (relative to widget coordinates)
 801    * @param y: the y coordinate (relative to widget coordinates)
 802    * @param keyboard_tip: whether this is a keyboard tooltip or not
 803    * @param path: a reference to receive a Gtk::TreePath
 804    *
 805    * This function is supposed to be used in a Gtk::Widget::query-tooltip
 806    * signal handler for Gtk::IconView. The x, y and keyboard_tip values
 807    * which are received in the signal handler, should be passed to this
 808    * function without modification.
 809    *
 810    * The return value indicates whether there is an icon view item at the given
 811    * coordinates (true) or not (false) for mouse tooltips. For keyboard
 812    * tooltips the item returned will be the cursor item. When true, then the
 813    * path which has been provided will be set to point to
 814    * that row and the corresponding model. x and y will always be converted
 815    * to be relative to IconView's bin_window if keyboard_tooltip is false.
 816    *
 817    * Return value: whether or not the given tooltip context points to a item.
 818    *
 819    * @newin2p12
 820    */
 821   bool get_tooltip_context_path(int& x, int& y,
 822                                 bool keyboard_tip,
 823                                 TreeModel::Path& path);
 824
 825   /**
 826    * @param x: the x coordinate (relative to widget coordinates)
 827    * @param y: the y coordinate (relative to widget coordinates)
 828    * @param keyboard_tip: whether this is a keyboard tooltip or not
 829    * @param iter: a pointer to receive a Gtk::TreeIter
 830    *
 831    * This function is supposed to be used in a Gtk::Widget::query-tooltip
 832    * signal handler for Gtk::IconView. The x, y and keyboard_tip values
 833    * which are received in the signal handler, should be passed to this
 834    * function without modification.
 835    *
 836    * The return value indicates whether there is an icon view item at the given
 837    * coordinates (true) or not (false) for mouse tooltips. For keyboard
 838    * tooltips the item returned will be the cursor item. When true, then the
 839    * iter which has been provided will be set to point to
 840    * that row and the corresponding model. x and y will always be converted
 841    * to be relative to IconView's bin_window if keyboard_tooltip is false.
 842    *
 843    * Return value: whether or not the given tooltip context points to a item.
 844    *
 845    * @newin2p12
 846    */
 847   bool get_tooltip_context_iter(int& x, int& y,
 848                                 bool keyboard_tip,
 849                                 Gtk::TreeModel::iterator& iter);
 850
 851
 852   void set_tooltip_column(int column);
 853
 854   int get_tooltip_column() const;
 855
 856
 857   /**
 858    * @par Prototype:
 859    * <tt>void on_my_%set_scroll_adjustments(Adjustment* hadjustment, Adjustment* vadjustment)</tt>
 860    */
 861
 862   Glib::SignalProxy2< void,Adjustment*,Adjustment* > signal_set_scroll_adjustments();
 863
 864
 865   /**
 866    * @par Prototype:
 867    * <tt>void on_my_%item_activated(const TreeModel::Path& path)</tt>
 868    */
 869
 870   Glib::SignalProxy1< void,const TreeModel::Path& > signal_item_activated();
 871
 872
 873   /**
 874    * @par Prototype:
 875    * <tt>void on_my_%selection_changed()</tt>
 876    */
 877
 878   Glib::SignalProxy0< void > signal_selection_changed();
 879
 880
 881   /* Key binding signals */
 882
 883
 884   #ifdef GLIBMM_PROPERTIES_ENABLED
 885 /** Model column used to retrieve the icon pixbuf from.
 886    *
 887    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 888    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 889    * the value of the property changes.
 890    */
 891   Glib::PropertyProxy<int> property_pixbuf_column() ;
 892 #endif //#GLIBMM_PROPERTIES_ENABLED
 893
 894 #ifdef GLIBMM_PROPERTIES_ENABLED
 895 /** Model column used to retrieve the icon pixbuf from.
 896    *
 897    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 898    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 899    * the value of the property changes.
 900    */
 901   Glib::PropertyProxy_ReadOnly<int> property_pixbuf_column() const;
 902 #endif //#GLIBMM_PROPERTIES_ENABLED
 903
 904   #ifdef GLIBMM_PROPERTIES_ENABLED
 905 /** Model column used to retrieve the text from.
 906    *
 907    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 908    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 909    * the value of the property changes.
 910    */
 911   Glib::PropertyProxy<int> property_text_column() ;
 912 #endif //#GLIBMM_PROPERTIES_ENABLED
 913
 914 #ifdef GLIBMM_PROPERTIES_ENABLED
 915 /** Model column used to retrieve the text from.
 916    *
 917    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 918    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 919    * the value of the property changes.
 920    */
 921   Glib::PropertyProxy_ReadOnly<int> property_text_column() const;
 922 #endif //#GLIBMM_PROPERTIES_ENABLED
 923
 924   #ifdef GLIBMM_PROPERTIES_ENABLED
 925 /** Model column used to retrieve the text if using Pango markup.
 926    *
 927    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 928    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 929    * the value of the property changes.
 930    */
 931   Glib::PropertyProxy<int> property_markup_column() ;
 932 #endif //#GLIBMM_PROPERTIES_ENABLED
 933
 934 #ifdef GLIBMM_PROPERTIES_ENABLED
 935 /** Model column used to retrieve the text if using Pango markup.
 936    *
 937    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 938    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 939    * the value of the property changes.
 940    */
 941   Glib::PropertyProxy_ReadOnly<int> property_markup_column() const;
 942 #endif //#GLIBMM_PROPERTIES_ENABLED
 943
 944   #ifdef GLIBMM_PROPERTIES_ENABLED
 945 /** The selection mode.
 946    *
 947    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 948    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 949    * the value of the property changes.
 950    */
 951   Glib::PropertyProxy<SelectionMode> property_selection_mode() ;
 952 #endif //#GLIBMM_PROPERTIES_ENABLED
 953
 954 #ifdef GLIBMM_PROPERTIES_ENABLED
 955 /** The selection mode.
 956    *
 957    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 958    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 959    * the value of the property changes.
 960    */
 961   Glib::PropertyProxy_ReadOnly<SelectionMode> property_selection_mode() const;
 962 #endif //#GLIBMM_PROPERTIES_ENABLED
 963
 964   #ifdef GLIBMM_PROPERTIES_ENABLED
 965 /** How the text and icon of each item are positioned relative to each other.
 966    *
 967    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 968    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 969    * the value of the property changes.
 970    */
 971   Glib::PropertyProxy<Orientation> property_orientation() ;
 972 #endif //#GLIBMM_PROPERTIES_ENABLED
 973
 974 #ifdef GLIBMM_PROPERTIES_ENABLED
 975 /** How the text and icon of each item are positioned relative to each other.
 976    *
 977    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 978    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 979    * the value of the property changes.
 980    */
 981   Glib::PropertyProxy_ReadOnly<Orientation> property_orientation() const;
 982 #endif //#GLIBMM_PROPERTIES_ENABLED
 983
 984   #ifdef GLIBMM_PROPERTIES_ENABLED
 985 /** The model for the icon view.
 986    *
 987    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 988    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 989    * the value of the property changes.
 990    */
 991   Glib::PropertyProxy< Glib::RefPtr<TreeModel> > property_model() ;
 992 #endif //#GLIBMM_PROPERTIES_ENABLED
 993
 994 #ifdef GLIBMM_PROPERTIES_ENABLED
 995 /** The model for the icon view.
 996    *
 997    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 998    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 999    * the value of the property changes.
1000    */
1001   Glib::PropertyProxy_ReadOnly< Glib::RefPtr<TreeModel> > property_model() const;
1002 #endif //#GLIBMM_PROPERTIES_ENABLED
1003
1004   #ifdef GLIBMM_PROPERTIES_ENABLED
1005 /** Number of columns to display.
1006    *
1007    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1008    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1009    * the value of the property changes.
1010    */
1011   Glib::PropertyProxy<int> property_columns() ;
1012 #endif //#GLIBMM_PROPERTIES_ENABLED
1013
1014 #ifdef GLIBMM_PROPERTIES_ENABLED
1015 /** Number of columns to display.
1016    *
1017    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1018    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1019    * the value of the property changes.
1020    */
1021   Glib::PropertyProxy_ReadOnly<int> property_columns() const;
1022 #endif //#GLIBMM_PROPERTIES_ENABLED
1023
1024   #ifdef GLIBMM_PROPERTIES_ENABLED
1025 /** The width used for each item.
1026    *
1027    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1028    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1029    * the value of the property changes.
1030    */
1031   Glib::PropertyProxy<int> property_item_width() ;
1032 #endif //#GLIBMM_PROPERTIES_ENABLED
1033
1034 #ifdef GLIBMM_PROPERTIES_ENABLED
1035 /** The width used for each item.
1036    *
1037    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1038    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1039    * the value of the property changes.
1040    */
1041   Glib::PropertyProxy_ReadOnly<int> property_item_width() const;
1042 #endif //#GLIBMM_PROPERTIES_ENABLED
1043
1044   #ifdef GLIBMM_PROPERTIES_ENABLED
1045 /** Space which is inserted between cells of an item.
1046    *
1047    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1048    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1049    * the value of the property changes.
1050    */
1051   Glib::PropertyProxy<int> property_spacing() ;
1052 #endif //#GLIBMM_PROPERTIES_ENABLED
1053
1054 #ifdef GLIBMM_PROPERTIES_ENABLED
1055 /** Space which is inserted between cells of an item.
1056    *
1057    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1058    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1059    * the value of the property changes.
1060    */
1061   Glib::PropertyProxy_ReadOnly<int> property_spacing() const;
1062 #endif //#GLIBMM_PROPERTIES_ENABLED
1063
1064   #ifdef GLIBMM_PROPERTIES_ENABLED
1065 /** Space which is inserted between grid rows.
1066    *
1067    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1068    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1069    * the value of the property changes.
1070    */
1071   Glib::PropertyProxy<int> property_row_spacing() ;
1072 #endif //#GLIBMM_PROPERTIES_ENABLED
1073
1074 #ifdef GLIBMM_PROPERTIES_ENABLED
1075 /** Space which is inserted between grid rows.
1076    *
1077    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1078    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1079    * the value of the property changes.
1080    */
1081   Glib::PropertyProxy_ReadOnly<int> property_row_spacing() const;
1082 #endif //#GLIBMM_PROPERTIES_ENABLED
1083
1084   #ifdef GLIBMM_PROPERTIES_ENABLED
1085 /** Space which is inserted between grid columns.
1086    *
1087    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1088    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1089    * the value of the property changes.
1090    */
1091   Glib::PropertyProxy<int> property_column_spacing() ;
1092 #endif //#GLIBMM_PROPERTIES_ENABLED
1093
1094 #ifdef GLIBMM_PROPERTIES_ENABLED
1095 /** Space which is inserted between grid columns.
1096    *
1097    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1098    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1099    * the value of the property changes.
1100    */
1101   Glib::PropertyProxy_ReadOnly<int> property_column_spacing() const;
1102 #endif //#GLIBMM_PROPERTIES_ENABLED
1103
1104   #ifdef GLIBMM_PROPERTIES_ENABLED
1105 /** Space which is inserted at the edges of the icon view.
1106    *
1107    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1108    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1109    * the value of the property changes.
1110    */
1111   Glib::PropertyProxy<int> property_margin() ;
1112 #endif //#GLIBMM_PROPERTIES_ENABLED
1113
1114 #ifdef GLIBMM_PROPERTIES_ENABLED
1115 /** Space which is inserted at the edges of the icon view.
1116    *
1117    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
1118    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
1119    * the value of the property changes.
1120    */
1121   Glib::PropertyProxy_ReadOnly<int> property_margin() const;
1122 #endif //#GLIBMM_PROPERTIES_ENABLED
1123
1124
1125 };
1126
1127 } // namespace Gtk
1128
1129
1130 namespace Glib
1131 {
1132   /** A Glib::wrap() method for this object.
1133    *
1134    * @param object The C instance.
1135    * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
1136    * @result A C++ instance that wraps this C instance.
1137    *
1138    * @relates Gtk::IconView
1139    */
1140   Gtk::IconView* wrap(GtkIconView* object, bool take_copy = false);
1141 } //namespace Glib
1142
1143
1144 #endif /* _GTKMM_ICONVIEW_H */
1145