/* $Id: combo.hg,v 1.7 2005/11/29 16:38:10 murrayc Exp $ */

/* combo.h
 * 
 * Copyright (C) 1998-2002 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 <glibmm/listhandle.h>
#include <glibmm/helperlist.h>
#include <gtkmm/box.h>
#include <gtkmm/button.h>
#include <gtkmm/entry.h>
#include <gtkmm/item.h>
_DEFS(gtkmm,gtk)
_PINCLUDE(gtkmm/private/box_p.h)
_PINCLUDE(gtkmm/private/item_p.h)

namespace Gtk
{


/** An item in a ComboDropDownList.
 * 
 * Items in a ComboDropDownList inherit Item. Two signals are added.
 *
 * @deprecated Use the ComboBox widget instead. 
 */
class ComboDropDownItem : public Gtk::Item
{
  _CLASS_GTKOBJECT(ComboDropDownItem,GtkListItem,GTK_LIST_ITEM,Gtk::Item,GtkItem)
  _IS_DEPRECATED
  _IGNORE(gtk_list_item_select,gtk_list_item_deselect)

public:
  _CTOR_DEFAULT

  _WRAP_SIGNAL(void scroll_horizontal(ScrollType scroll_type, float position), "scroll-horizontal")
  _WRAP_SIGNAL(void scroll_vertical(ScrollType scroll_type, float position), "scroll-vertical")
};


namespace ComboDropDown_Helpers
{

typedef Gtk::ComboDropDownItem Element;

#m4 include(list.m4)
  GP_LIST(ComboDropDownList,ComboDropDown,GtkList,ComboDropDownItem,children)
  GP_LIST_ITER(Glib::List_Cpp_Iterator<GtkListItem, ComboDropDownItem>)
  GP_LIST_FIND()
  GP_LIST_END()

} /* namespace ComboDropDown_Helpers */


class Combo;

/** The dropdown list of a Combo.
 * 
 * A combo is a compound widget which crosses a text entry area and a pull
 * down list. The dropdown list is implemented with the deprecated GtkList
 * widget on the gtk+ side. ComboDropDown is a thin wrapper around GtkList
 * containing just the functionality necessary for a Combo's list. To add
 * and remove items use the STL-style interface that is accessible through
 * ComboDropDown::children().
 *
 * @deprecated Use the ComboBox widget instead.
 */
class ComboDropDown : public Gtk::Container
{
  _CLASS_GTKOBJECT(ComboDropDown,GtkList,GTK_LIST,Gtk::Container,GtkContainer)
  _IS_DEPRECATED
  _IGNORE(gtk_list_remove_items_no_unref,gtk_list_select_item,gtk_list_unselect_item,gtk_list_set_selection_mode,gtk_list_extend_selection,gtk_list_start_selection,gtk_list_end_selection,gtk_list_select_all,gtk_list_unselect_all,gtk_list_toggle_add_mode,gtk_list_toggle_focus_row,gtk_list_toggle_row,gtk_list_undo_selection,gtk_list_end_drag_selection)
public:
  typedef ComboDropDown_Helpers::ComboDropDownList ComboDropDownList;

protected:
  _CTOR_DEFAULT
  friend class Combo;
public:

  _WRAP_METHOD(void scroll_horizontal(ScrollType scroll_type, float position), gtk_list_scroll_horizontal)
  _WRAP_METHOD(void scroll_vertical(ScrollType scroll_type, float position), gtk_list_scroll_vertical)

  ComboDropDownList& children();
  const ComboDropDownList& children() const;

  _IGNORE(gtk_list_insert_items)
  _IGNORE(gtk_list_append_items,gtk_list_prepend_items)
  _IGNORE(gtk_list_child_position)
  _IGNORE(gtk_list_remove_items)

  _WRAP_SIGNAL(void select_child(Widget& item), "select_child")
  _WRAP_SIGNAL(void selection_changed(), "selection_changed")
  _WRAP_SIGNAL(void unselect_child(Widget& item), "unselect_child")

protected:
#ifndef DOXYGEN_SHOULD_SKIP_THIS
  mutable ComboDropDownList children_proxy_;
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
};


class ScrolledWindow;
class Window;

/** A text entry field with a dropdown list.
 * 
 * A combo is a compound widget which crosses a text entry area and a pull
 * down list.  It may allow text entry or it may just allow list
 * values depending on the settings.
 *
 * Access members allow altering of the widget components.
 *
 * @deprecated Use the ComboBox widget instead.
 */
class Combo : public HBox
{
  _CLASS_GTKOBJECT(Combo,GtkCombo,GTK_COMBO,Gtk::HBox,GtkHBox)
  _IS_DEPRECATED
public:

  _CTOR_DEFAULT
  
  /** Allow direct text entry
   * Whether the text in the entry must be or not be in the list.
   *
   * @param value Set to true if the value must be in list.
   * @param empty Set to true if the text area is allowed to be empty.
   */
  _WRAP_METHOD(void set_value_in_list(bool value = true, bool empty = false), gtk_combo_set_value_in_list)

  /** Set arrows keys to change value
   * Up and down will scroll through the list items.
   * Useful when there is a small list of value that the
   * list must have.
   *
   * @param arrows_on true indicates the arrow keys scroll.
   */
  _WRAP_METHOD(void set_use_arrows(bool arrows_on = true), gtk_combo_set_use_arrows)

  /** Set arrows keys to change if value not in list
   * Up and down will scroll through the list items but only
   * change the current value if the text does not match a list item..
   * Useful when there is a small list of value that the
   * list must have.
   *
   * @param arrows_always true indicates the value will change.
   */
  _WRAP_METHOD(void set_use_arrows_always(bool arrows_always = true), gtk_combo_set_use_arrows_always)

  /** Sets list case sensitive
   * Determines if the list items and text comparisons for
   * set_use_arrows_always() should be case sensitive.
   */
  _WRAP_METHOD(void set_case_sensitive(bool val = true), gtk_combo_set_case_sensitive)

  /** Set the current entry Glib::ustring
   * Call this function on an item if it isn't a label or you
   * want it to have a different value to be displayed in the entry
   */
  _WRAP_METHOD(void set_item_string(Gtk::Item& item, const Glib::ustring& item_value), gtk_combo_set_item_string)
   void remove_item_string(Gtk::Item& item);

  /// Insert a list of items.
  _WRAP_METHOD(void set_popdown_strings(const Glib::ListHandle<Glib::ustring>& strings), gtk_combo_set_popdown_strings)

  Glib::ListHandle<Glib::ustring> get_popdown_strings() const;

  _WRAP_METHOD(void disable_activate(), gtk_combo_disable_activate)

  _MEMBER_GET_PTR(entry,entry,Entry*,GtkWidget*)
  _MEMBER_GET_PTR(list,list,ComboDropDown*,GtkWidget*)

  _WRAP_PROPERTY("enable-arrow-keys", bool)
  _WRAP_PROPERTY("enable-arrows-always", bool)
  _WRAP_PROPERTY("case-sensitive", bool)
  _WRAP_PROPERTY("allow-empty", bool)
  _WRAP_PROPERTY("value-in-list", bool)
};


} /* namespace Gtk */


