ardour/libs/gtkmm2/gtk/src/combobox.hg

/* $Id: combobox.hg,v 1.17 2006/09/19 20:08:42 murrayc Exp $ */

/* combobox.h
 * 
 * Copyright (C) 2003 The gtkmm Development Team
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the Free
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

#include <gtkmm/bin.h>
#include <gtkmm/celllayout.h>
#include <gtkmm/treemodel.h>
#include <gtkmm/cellrenderer.h>
#include <gtkmm/treeview.h>

_DEFS(gtkmm,gtk)
_PINCLUDE(gtkmm/private/bin_p.h)


namespace Gtk
{

/** A widget used to choose from a list of items.
 *
 * A ComboBox is a widget that allows the user to choose from a list of valid choices. The ComboBox displays the 
 * selected choice. When activated, the ComboBox displays a popup which allows the user to make a new choice. The 
 * style in which the selected value is displayed, and the style of the popup is determined by the current theme. 
 * It may be similar to a OptionMenu, or similar to a Windows-style combo box.
 *
 * The ComboBox uses the model-view pattern; the list of valid choices is specified in the form of a tree model, 
 * and the display of the choices can be adapted to the data in the model by using cell renderers, as you would in 
 * a tree view. This is possible since ComboBox implements the CellLayout interface. The tree model holding the 
 * valid choices is not restricted to a flat list, it can be a real tree, and the popup will reflect the tree 
 * structure.
 *
 * See also ComboBoxText, which is specialised for a single text column.
 *
 * @ingroup Widgets
 */
class ComboBox
: public Bin,
  public CellLayout
//TODO: Since GTK+ 2.6, this should now inherit also from CellEditable, but we can't add this base without breaking ABI.
{
  _CLASS_GTKOBJECT(ComboBox, GtkComboBox, GTK_COMBO_BOX, Gtk::Bin, GtkBin)
  _IMPLEMENTS_INTERFACE(CellLayout)
public:
  _CTOR_DEFAULT()
  
  /** Creates a new ComboBox with the model initialized to @a model.
   */
  _WRAP_CTOR(ComboBox(const Glib::RefPtr<TreeModel>& model), gtk_combo_box_new_with_model)
  _IGNORE(gtk_combo_box_new, gtk_combo_box_new_text) //See ComboBoxText for an equivalent of gtk_combo_box_new_text().


  _WRAP_METHOD(void set_wrap_width(int width), gtk_combo_box_set_wrap_width)
  _WRAP_METHOD(int get_wrap_width() const, gtk_combo_box_get_wrap_width)

  _WRAP_METHOD(void set_row_span_column(int row_span), gtk_combo_box_set_row_span_column)
  _WRAP_METHOD(int get_row_span_column() const, gtk_combo_box_get_row_span_column)

  _WRAP_METHOD(void set_column_span_column(int column_span), gtk_combo_box_set_column_span_column)
  _WRAP_METHOD(int get_column_span_column() const, gtk_combo_box_get_column_span_column)

  _WRAP_METHOD(bool get_add_tearoffs() const, gtk_combo_box_get_add_tearoffs)
  _WRAP_METHOD(void set_add_tearoffs(bool add_tearoffs = true), gtk_combo_box_set_add_tearoffs)

  _WRAP_METHOD(Glib::ustring get_title() const, gtk_combo_box_get_title)
  _WRAP_METHOD(void set_title(const Glib::ustring& title), gtk_combo_box_set_title)

  _WRAP_METHOD(bool get_focus_on_click() const, gtk_combo_box_get_focus_on_click)
  _WRAP_METHOD(void set_focus_on_click(bool focus_on_click = true), gtk_combo_box_set_focus_on_click)

/* get/set active item */
  _WRAP_METHOD(int get_active_row_number() const, gtk_combo_box_get_active)

  /** Gets an iterator that points to the current active item, if it exists.
   * @result The iterator.
   */
  TreeModel::iterator get_active();
  
  /** Gets an iterator that points to the current active item, if it exists.
   * @result The iterator.
   */
  TreeModel::const_iterator get_active() const;
  _IGNORE(gtk_combo_box_get_active_iter)
    
  _WRAP_METHOD(void set_active(int index), gtk_combo_box_set_active)
  _WRAP_METHOD(void set_active(const TreeModel::iterator& iter), gtk_combo_box_set_active_iter)
  
  /** Causes no item to be active. See also set_active().
   */
  void unset_active();

  _WRAP_METHOD(Glib::RefPtr<TreeModel> get_model(), gtk_combo_box_get_model, refreturn)
  _WRAP_METHOD(Glib::RefPtr<const TreeModel> get_model() const, gtk_combo_box_get_model, refreturn, constversion)
  _WRAP_METHOD(void set_model(const Glib::RefPtr<TreeModel>& model), gtk_combo_box_set_model)

  typedef TreeView::SlotRowSeparator SlotRowSeparator;  
  
  /** Sets the row separator function, which is used to determine whether a row should be drawn as a separator. 
   * See also unset_row_separator_func().
   * 
   * @param slot The callback.
   */
  void set_row_separator_func(const SlotRowSeparator& slot);
  
  /** Causes no separators to be drawn.
   */
  void unset_row_separator_func();
  _IGNORE(gtk_combo_box_set_row_separator_func, gtk_combo_box_get_row_separator_func)

  _WRAP_METHOD(void popup(), gtk_combo_box_popup)
  _WRAP_METHOD(void popdown(), gtk_combo_box_popdown)

  _WRAP_METHOD(Glib::RefPtr<Atk::Object> get_popup_accessible(), gtk_combo_box_get_popup_accessible, ifdef GTKMM_ATKMM_ENABLED)
  _WRAP_METHOD(Glib::RefPtr<const Atk::Object> get_popup_accessible() const, gtk_combo_box_get_popup_accessible, constversion, ifdef GTKMM_ATKMM_ENABLED)

  _IGNORE(gtk_combo_box_append_text, gtk_combo_box_insert_text, gtk_combo_box_prepend_text, gtk_combo_box_remove_text, gtk_combo_box_get_active_text) //These are in ComboBoxText.

  _WRAP_PROPERTY("model", Glib::RefPtr<TreeModel>)
  _WRAP_PROPERTY("wrap_width", int)
  _WRAP_PROPERTY("row_span_column", int)
  _WRAP_PROPERTY("column_span_column", int)
  _WRAP_PROPERTY("active", int)
  _WRAP_PROPERTY("add-tearoffs", bool)
  _WRAP_PROPERTY("has-frame", bool)
  _WRAP_PROPERTY("focus-on-click", bool)
  _WRAP_PROPERTY("tearoff-title", Glib::ustring)

  /** The changed signal gets emitted when the active
   * item is changed. This can be due to the user selecting
   * a different item from the list, or due to a 
   * call to set_active_iter().
   */
  _WRAP_SIGNAL(void changed(), "changed")

  //Key-binding signals:
  _IGNORE_SIGNAL("move-active")
  _IGNORE_SIGNAL("popup")  
  _IGNORE_SIGNAL("popdown")                                           
};


} // namespace Gtk