libs/gtkmm2/gtk/gtkmm/combobox.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GTKMM_COMBOBOX_H
   4 #define _GTKMM_COMBOBOX_H
   5
   6 #include <glibmm.h>
   7
   8 /* $Id$ */
   9
  10 /* combobox.h
  11  *
  12  * Copyright (C) 2003 The gtkmm Development Team
  13  *
  14  * This library is free software; you can redistribute it and/or
  15  * modify it under the terms of the GNU Library General Public
  16  * License as published by the Free Software Foundation; either
  17  * version 2 of the License, or (at your option) any later version.
  18  *
  19  * This library is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  22  * Library General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU Library General Public
  25  * License along with this library; if not, write to the Free
  26  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  27  */
  28
  29 #include <gtkmm/bin.h>
  30 #include <gtkmm/celllayout.h>
  31 #include <gtkmm/treemodel.h>
  32 #include <gtkmm/cellrenderer.h>
  33 #include <gtkmm/treeview.h>
  34
  35
  36 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  37 typedef struct _GtkComboBox GtkComboBox;
  38 typedef struct _GtkComboBoxClass GtkComboBoxClass;
  39 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  40
  41
  42 namespace Gtk
  43 { class ComboBox_Class; } // namespace Gtk
  44 namespace Gtk
  45 {
  46
  47 /** A widget used to choose from a list of items.
  48  *
  49  * A ComboBox is a widget that allows the user to choose from a list of valid choices. The ComboBox displays the
  50  * selected choice. When activated, the ComboBox displays a popup which allows the user to make a new choice. The
  51  * style in which the selected value is displayed, and the style of the popup is determined by the current theme.
  52  * It may be similar to a OptionMenu, or similar to a Windows-style combo box.
  53  *
  54  * The ComboBox uses the model-view pattern; the list of valid choices is specified in the form of a tree model,
  55  * and the display of the choices can be adapted to the data in the model by using cell renderers, as you would in
  56  * a tree view. This is possible since ComboBox implements the CellLayout interface. The tree model holding the
  57  * valid choices is not restricted to a flat list, it can be a real tree, and the popup will reflect the tree
  58  * structure.
  59  *
  60  * See also ComboBoxText, which is specialised for a single text column.
  61  *
  62  * @ingroup Widgets
  63  */
  64
  65 class ComboBox
  66 : public Bin,
  67   public CellLayout
  68 {
  69   public:
  70 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  71   typedef ComboBox CppObjectType;
  72   typedef ComboBox_Class CppClassType;
  73   typedef GtkComboBox BaseObjectType;
  74   typedef GtkComboBoxClass BaseClassType;
  75 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  76
  77   virtual ~ComboBox();
  78
  79 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  80
  81 private:
  82   friend class ComboBox_Class;
  83   static CppClassType combobox_class_;
  84
  85   // noncopyable
  86   ComboBox(const ComboBox&);
  87   ComboBox& operator=(const ComboBox&);
  88
  89 protected:
  90   explicit ComboBox(const Glib::ConstructParams& construct_params);
  91   explicit ComboBox(GtkComboBox* castitem);
  92
  93 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  94
  95 public:
  96 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  97   static GType get_type()      G_GNUC_CONST;
  98   static GType get_base_type() G_GNUC_CONST;
  99 #endif
 100
 101   ///Provides access to the underlying C GtkObject.
 102   GtkComboBox*       gobj()       { return reinterpret_cast<GtkComboBox*>(gobject_); }
 103
 104   ///Provides access to the underlying C GtkObject.
 105   const GtkComboBox* gobj() const { return reinterpret_cast<GtkComboBox*>(gobject_); }
 106
 107
 108 public:
 109   //C++ methods used to invoke GTK+ virtual functions:
 110
 111 protected:
 112   //GTK+ Virtual Functions (override these to change behaviour):
 113
 114   //Default Signal Handlers::
 115   virtual void on_changed();
 116
 117
 118 private:
 119
 120
 121 public:
 122   ComboBox();
 123
 124   /** Creates a new ComboBox with the model initialized to @a model.
 125    */
 126   explicit ComboBox(const Glib::RefPtr<TreeModel>& model);
 127    //See ComboBoxText for an equivalent of gtk_combo_box_new_text().
 128
 129
 130   /** Sets the wrap width of @a combo_box  to be @a width . The wrap width is basically
 131    * the preferred number of columns when you want the popup to be layed out
 132    * in a table.
 133    *
 134    * Since: 2.4
 135    * @param width Preferred number of columns.
 136    */
 137   void set_wrap_width(int width);
 138
 139   /** Returns the wrap width which is used to determine the number
 140    * of columns for the popup menu. If the wrap width is larger than
 141    * 1, the combo box is in table mode.
 142    * @return The wrap width.
 143    *
 144    * Since: 2.6.
 145    */
 146   int get_wrap_width() const;
 147
 148
 149   /** Sets the column with row span information for @a combo_box  to be @a row_span .
 150    * The row span column contains integers which indicate how many rows
 151    * an item should span.
 152    *
 153    * Since: 2.4
 154    * @param row_span A column in the model passed during construction.
 155    */
 156   void set_row_span_column(int row_span);
 157
 158   /** Returns the column with row span information for @a combo_box .
 159    * @return The row span column.
 160    *
 161    * Since: 2.6.
 162    */
 163   int get_row_span_column() const;
 164
 165
 166   /** Sets the column with column span information for @a combo_box  to be
 167    *  @a column_span . The column span column contains integers which indicate
 168    * how many columns an item should span.
 169    *
 170    * Since: 2.4
 171    * @param column_span A column in the model passed during construction.
 172    */
 173   void set_column_span_column(int column_span);
 174
 175   /** Returns the column with column span information for @a combo_box .
 176    * @return The column span column.
 177    *
 178    * Since: 2.6.
 179    */
 180   int get_column_span_column() const;
 181
 182
 183   /** Gets the current value of the :add-tearoffs property.
 184    * @return The current value of the :add-tearoffs property.
 185    */
 186   bool get_add_tearoffs() const;
 187
 188   /** Sets whether the popup menu should have a tearoff
 189    * menu item.
 190    *
 191    * Since: 2.6
 192    * @param add_tearoffs <tt>true</tt> to add tearoff menu items.
 193    */
 194   void set_add_tearoffs(bool add_tearoffs = true);
 195
 196
 197   /** Returns whether the combo box grabs focus when it is clicked
 198    * with the mouse. See set_focus_on_click().
 199    * @return <tt>true</tt> if the combo box grabs focus when it is
 200    * clicked with the mouse.
 201    *
 202    * Since: 2.6.
 203    */
 204   bool get_focus_on_click() const;
 205
 206   /** Sets whether the combo box will grab focus when it is clicked with
 207    * the mouse. Making mouse clicks not grab focus is useful in places
 208    * like toolbars where you don't want the keyboard focus removed from
 209    * the main area of the application.
 210    *
 211    * Since: 2.6
 212    * @param focus_on_click Whether the combo box grabs focus when clicked
 213    * with the mouse.
 214    */
 215   void set_focus_on_click(bool focus_on_click = true);
 216
 217 /* get/set active item */
 218
 219   /** Returns the index of the currently active item, or -1 if there's no
 220    * active item. If the model is a non-flat treemodel, and the active item
 221    * is not an immediate child of the root of the tree, this function returns
 222    * <tt>gtk_tree_path_get_indices (path)[0]</tt>, where
 223    * <tt>path</tt> is the Gtk::TreePath of the active item.
 224    * @return An integer which is the index of the currently active item, or
 225    * -1 if there's no active item.
 226    *
 227    * Since: 2.4.
 228    */
 229   int get_active_row_number() const;
 230
 231   /** Gets an iterator that points to the current active item, if it exists.
 232    * @result The iterator.
 233    */
 234   TreeModel::iterator get_active();
 235
 236   /** Gets an iterator that points to the current active item, if it exists.
 237    * @result The iterator.
 238    */
 239   TreeModel::const_iterator get_active() const;
 240
 241
 242   /** Sets the active item of @a combo_box  to be the item at @a index .
 243    *
 244    * Since: 2.4
 245    * @param index An index in the model passed during construction, or -1 to have
 246    * no active item.
 247    */
 248   void set_active(int index);
 249
 250   /** Sets the current active item to be the one referenced by @a iter .
 251    *  @a iter  must correspond to a path of depth one.
 252    *
 253    * Since: 2.4
 254    * @param iter The Gtk::TreeIter.
 255    */
 256   void set_active(const TreeModel::iterator& iter);
 257
 258   /** Causes no item to be active. See also set_active().
 259    */
 260   void unset_active();
 261
 262
 263   /** Returns the Gtk::TreeModel which is acting as data source for @a combo_box .
 264    * @return A Gtk::TreeModel which was passed during construction.
 265    *
 266    * Since: 2.4.
 267    */
 268   Glib::RefPtr<TreeModel> get_model();
 269
 270   /** Returns the Gtk::TreeModel which is acting as data source for @a combo_box .
 271    * @return A Gtk::TreeModel which was passed during construction.
 272    *
 273    * Since: 2.4.
 274    */
 275   Glib::RefPtr<const TreeModel> get_model() const;
 276
 277   /** Sets the model used by @a combo_box  to be @a model . Will unset a previously set
 278    * model (if applicable). If model is <tt>0</tt>, then it will unset the model.
 279    *
 280    * Note that this function does not clear the cell renderers, you have to
 281    * call gtk_combo_box_cell_layout_clear() yourself if you need to set up
 282    * different cell renderers for the new model.
 283    *
 284    * Since: 2.4
 285    * @param model A Gtk::TreeModel.
 286    */
 287   void set_model(const Glib::RefPtr<TreeModel>& model);
 288
 289   typedef TreeView::SlotRowSeparator SlotRowSeparator;
 290
 291   /** Sets the row separator function, which is used to determine whether a row should be drawn as a separator.
 292    * See also unset_row_separator_func().
 293    *
 294    * @param slot The callback.
 295    */
 296   void set_row_separator_func(const SlotRowSeparator& slot);
 297
 298   /** Causes no separators to be drawn.
 299    */
 300   void unset_row_separator_func();
 301
 302
 303   /** Pops up the menu or dropdown list of @a combo_box .
 304    *
 305    * This function is mostly intended for use by accessibility technologies;
 306    * applications should have little use for it.
 307    *
 308    * Since: 2.4
 309    */
 310   void popup();
 311
 312   /** Hides the menu or dropdown list of @a combo_box .
 313    *
 314    * This function is mostly intended for use by accessibility technologies;
 315    * applications should have little use for it.
 316    *
 317    * Since: 2.4
 318    */
 319   void popdown();
 320
 321
 322   /** Gets the accessible object corresponding to the combo box's popup.
 323    *
 324    * This function is mostly intended for use by accessibility technologies;
 325    * applications should have little use for it.
 326    * @return The accessible object corresponding to the combo box's popup.
 327    *
 328    * Since: 2.6.
 329    */
 330   Glib::RefPtr<Atk::Object> get_popup_accessible();
 331
 332   /** Gets the accessible object corresponding to the combo box's popup.
 333    *
 334    * This function is mostly intended for use by accessibility technologies;
 335    * applications should have little use for it.
 336    * @return The accessible object corresponding to the combo box's popup.
 337    *
 338    * Since: 2.6.
 339    */
 340   Glib::RefPtr<const Atk::Object> get_popup_accessible() const;
 341
 342    //These are in ComboBoxText.
 343
 344   /** The model for the combo box.
 345    *
 346    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 347    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 348    * the value of the property changes.
 349    */
 350   Glib::PropertyProxy< Glib::RefPtr<TreeModel> > property_model() ;
 351
 352 /** The model for the combo box.
 353    *
 354    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 355    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 356    * the value of the property changes.
 357    */
 358   Glib::PropertyProxy_ReadOnly< Glib::RefPtr<TreeModel> > property_model() const;
 359
 360   /** Wrap width for layouting the items in a grid.
 361    *
 362    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 363    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 364    * the value of the property changes.
 365    */
 366   Glib::PropertyProxy<int> property_wrap_width() ;
 367
 368 /** Wrap width for layouting the items in a grid.
 369    *
 370    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 371    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 372    * the value of the property changes.
 373    */
 374   Glib::PropertyProxy_ReadOnly<int> property_wrap_width() const;
 375
 376   /** TreeModel column containing the row span values.
 377    *
 378    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 379    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 380    * the value of the property changes.
 381    */
 382   Glib::PropertyProxy<int> property_row_span_column() ;
 383
 384 /** TreeModel column containing the row span values.
 385    *
 386    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 387    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 388    * the value of the property changes.
 389    */
 390   Glib::PropertyProxy_ReadOnly<int> property_row_span_column() const;
 391
 392   /** TreeModel column containing the column span values.
 393    *
 394    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 395    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 396    * the value of the property changes.
 397    */
 398   Glib::PropertyProxy<int> property_column_span_column() ;
 399
 400 /** TreeModel column containing the column span values.
 401    *
 402    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 403    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 404    * the value of the property changes.
 405    */
 406   Glib::PropertyProxy_ReadOnly<int> property_column_span_column() const;
 407
 408   /** The item which is currently active.
 409    *
 410    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 411    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 412    * the value of the property changes.
 413    */
 414   Glib::PropertyProxy<int> property_active() ;
 415
 416 /** The item which is currently active.
 417    *
 418    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 419    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 420    * the value of the property changes.
 421    */
 422   Glib::PropertyProxy_ReadOnly<int> property_active() const;
 423
 424   /** Whether dropdowns should have a tearoff menu item.
 425    *
 426    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 427    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 428    * the value of the property changes.
 429    */
 430   Glib::PropertyProxy<bool> property_add_tearoffs() ;
 431
 432 /** Whether dropdowns should have a tearoff menu item.
 433    *
 434    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 435    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 436    * the value of the property changes.
 437    */
 438   Glib::PropertyProxy_ReadOnly<bool> property_add_tearoffs() const;
 439
 440   /** Whether the combo box draws a frame around the child.
 441    *
 442    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 443    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 444    * the value of the property changes.
 445    */
 446   Glib::PropertyProxy<bool> property_has_frame() ;
 447
 448 /** Whether the combo box draws a frame around the child.
 449    *
 450    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 451    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 452    * the value of the property changes.
 453    */
 454   Glib::PropertyProxy_ReadOnly<bool> property_has_frame() const;
 455
 456   /** Whether the combo box grabs focus when it is clicked with the mouse.
 457    *
 458    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 459    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 460    * the value of the property changes.
 461    */
 462   Glib::PropertyProxy<bool> property_focus_on_click() ;
 463
 464 /** Whether the combo box grabs focus when it is clicked with the mouse.
 465    *
 466    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 467    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 468    * the value of the property changes.
 469    */
 470   Glib::PropertyProxy_ReadOnly<bool> property_focus_on_click() const;
 471
 472
 473   Glib::SignalProxy0< void > signal_changed();
 474
 475
 476 };
 477
 478
 479 } // namespace Gtk
 480
 481
 482 namespace Glib
 483 {
 484   /** @relates Gtk::ComboBox
 485    * @param object The C instance
 486    * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 487    * @result A C++ instance that wraps this C instance.
 488    */
 489   Gtk::ComboBox* wrap(GtkComboBox* object, bool take_copy = false);
 490 }
 491 #endif /* _GTKMM_COMBOBOX_H */
 492