/* $Id: comboboxentry.hg,v 1.10 2005/05/26 21:07: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 Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 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
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser 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/combobox.h>
#include <gtkmm/entry.h>

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


namespace Gtk
{

/** A text entry field with a dropdown list.
 * A ComboBoxEntry is a widget that allows the user to choose from a list of valid choices or enter a different 
 * value. It is very similar to a ComboBox, but it displays the selected value in an entry to allow modifying it.
 *
 * In contrast to a ComboBox, the underlying model of a ComboBoxEntry must always have a text column (see 
 * set_text_column()), and the entry will show the content of the text column in the selected row. To get the text from the entry, use get_active_text().
 *
 * The changed signal will be emitted while typing into a ComboBoxEntry, as well as when selecting an item from the 
 * ComboBoxEntry's list. Use get_active() to discover whether an item was actually selected from 
 * the list. 
 *
 * See also ComboBoxEntryText, which is specialised for a single text column.
 *
 * To add and remove strings from the list, just modify the model using its data manipulation API. You can get the 
 * Entry by using get_child().
 *
 * If you have special needs that go beyond a simple entry (e.g. input validation), it is possible to replace the 
 * child entry by a different widget using Gtk::Container::remove() and Gtk::Container::add(). 
 *
 * The ComboBoxEntry widget looks like this:
 * @image html comboboxentry1.png
 *
 * @ingroup Widgets
 */
class ComboBoxEntry : public ComboBox
{
  _CLASS_GTKOBJECT(ComboBoxEntry, GtkComboBoxEntry, GTK_COMBO_BOX_ENTRY, Gtk::ComboBox, GtkComboBox)
public:
  _CTOR_DEFAULT()
  _IGNORE(gtk_combo_box_entry_new, gtk_combo_box_entyry_new_text) //See ComboBoxEntryText for an equivalent of gtk_combo_box_entry_new_text().

  /** Creates a new ComboBoxEntry which has an Entry as child and a list of strings as popup. You can get the 
   * Entry from a ComboBoxEntry using get_entry(). To add and remove strings from the list, just modify @a model 
   * using its data manipulation API.
   *
   * @param model A TreeModel.
   * @param text_column A column in @a model to get the strings from.
   */
  _WRAP_CTOR(ComboBoxEntry(const Glib::RefPtr<TreeModel>& model, const TreeModelColumnBase& text_column), gtk_combo_box_entry_new_with_model)
  
  /** Creates a new ComboBoxEntry which has an Entry as child and a list of strings as popup. You can get the 
   * Entry from a ComboBoxEntry using get_entry(). To add and remove strings from the list, just modify @a model 
   * using its data manipulation API.
   *
   * @param model A TreeModel.
   * @param text_column A column in @a model to get the strings from.
   */
  _WRAP_CTOR(ComboBoxEntry(const Glib::RefPtr<TreeModel>& model, int text_column = 0), gtk_combo_box_entry_new_with_model)

  _WRAP_METHOD(void set_text_column(const TreeModelColumnBase& text_column) const, gtk_combo_box_entry_set_text_column)   
  _WRAP_METHOD(void set_text_column(int text_column) const, gtk_combo_box_entry_set_text_column) 
  _WRAP_METHOD(int get_text_column() const, gtk_combo_box_entry_get_text_column) 

  /** Returns the currently active string.
   * @result The currently active text.
   *
   * @newin{2,14}
   */
  Glib::ustring get_active_text() const;

  //The child is always an entry:

  /** @see Bin::get_child().
   */
  Entry* get_entry();

  /** @see Bin::get_child().
   */
  const Entry* get_entry() const;   
  
  _WRAP_PROPERTY("text-column", int)                                   
};


} // namespace Gtk

