// This may look like C code, but it's really -*- C++ -*-
/*
 * Copyright (C) 2008 Emweb bvba, Kessel-Lo, Belgium.
 *
 * See the LICENSE file for terms of use.
 */
#ifndef WCOMBOBOX_H_
#define WCOMBOBOX_H_

#include <Wt/WAbstractItemModel>
#include <Wt/WFormWidget>
#include <string>

namespace Wt {

/*! \class WComboBox Wt/WComboBox Wt/WComboBox
 *  \brief A widget that provides a drop-down combo-box control.
 *
 * A combo box provides the user with a choice of options, from which
 * one option may be selected.
 *
 * WComboBox is a MVC component, and uses a simple string list model
 * for convenience. Use addItem(const WString&) or insertItem(int,
 * const WString&) to populate the combo-box. All the content can be
 * cleared through clear(). The methods manipulate the underlying
 * model.
 *
 * To use the combo box with a custom model instead of the default
 * WStringListModel, use setModel().
 *
 * To act on a new selection, either connect a slot to the \link
 * WComboBox::changed changed\endlink, \link WComboBox::activated
 * activated<int>\endlink or \link WComboBox::sactivated
 * sactivated<WString>\endlink signals.
 *
 * At all times, the current selection index is available through
 * currentIndex() or the text using currentText().
 *
 * %WComboBox is an \link WWidget::setInline(bool) inline \endlink widget.
 *
 * \ingroup modelview
 */
class WT_API WComboBox : public WFormWidget
{
public:
  /*! \brief Create an empty combo-box with optional <i>parent</i>.
   */
  WComboBox(WContainerWidget *parent = 0);

  /*! \brief Add an option item.
   *
   * Equivalent to
   * \link insertItem(int, const WString&) insertItem \endlink (count(),
   * <i>text</i>).
   */
  void addItem(const WString& text);

  /*! \brief Get the number of items
   */
  int count() const;

  /*! \brief Get the currently selected item.
   *
   * If no item is currently selected, the method returns -1.
   *
   * The default value is 0, unless the combo box is empty.
   */
  int currentIndex() const;

  /*! \brief Insert an item at the specified position.
   *
   * The item is inserted in the underlying model at position
   * <i>index</i>. This requires that the model() is editable.
   *
   * \sa addItem(const WString&), removeItem(int)
   */
  void insertItem(int index, const WString& text);

  /*! \brief Remove the item at the specified position.
   *
   * The item is removed from the underlying model. This requires that
   * the model() is editable.
   *
   * \sa insertItem(index, const WString&), clear()
   */
  void removeItem(int index);

  /*! \brief Change the current selection.
   *
   * Specify a value of -1 for <i>index</i> to clear the selection.
   */
  void setCurrentIndex(int index);

  /*! \brief Change the text for a specified option.
   *
   * The text for the item at position <i>index</i> is changed. This requires
   * that the model() is editable.
   */
  void setItemText(int index, const WString& text);

  /*! \brief Get the text of the currently selected item.
   *
   * \sa currentIndex(), itemText(int)
   */
  const WString currentText() const;

  /*! \brief Get the text of a particular item.
   *
   * \sa setItemText(int, const WString&), currentText()
   */
  const WString itemText(int index) const;

  /*! \brief Set the model to be used for the items.
   *
   * The <i>model</i> may not be 0, and ownership of the model is not
   * transferred.
   *
   * The default value is a WStringListModel that is owned by the the
   * combo box and which will be deleted together with the combo box.
   *
   * \sa setModelColumn(int)
   */
  void setModel(WAbstractItemModel *model);

  /*! \brief Set the column in the model to be used for the items.
   *
   * The column <i>index</i> in the model will be used to retrieve data.
   *
   * The default value is 0.
   *
   * \sa setModel()
   */
  void setModelColumn(int index);

  /*! \brief Return the data model.
   *
   * \sa setModel()
   */
  WAbstractItemModel *model() const { return model_; }

  /*! \brief Returns the index of the first item that matches a text.
   */
  int findText(const WString& text, MatchFlags flags
	       = MatchFlags(MatchExactly | MatchCaseSensitive));

  WValidator::State validate();

  virtual void refresh();

public slots:
  /*! \brief Clear all items.
   *
   * Removes all items from the underlying model. This requires that the
   * model() is editable.
   */
  void clear();

public:
  /*! \brief %Signal emitted when the selection changed.
   *
   * The newly selected item is passed as an argument.
   *
   * \sa sactivated, currentIndex()
   */
  Signal<int> activated;

  /*! \brief %Signal emitted when the selection changed.
   *
   * The newly selected text is passed as an argument.
   *
   * \sa activated, currentText()
   */
  Signal<WString> sactivated;

private slots:
  void propagateChange();

private:
  WAbstractItemModel *model_;
  int modelColumn_;
  int currentIndex_;

  bool itemsChanged_;
  bool maxVisibleItemsChanged_;
  bool selectionChanged_;
  bool currentlyConnected_;

  std::vector<boost::signals::connection> modelConnections_;

  void itemsChanged();

protected:
  virtual void           updateDom(DomElement& element, bool all);
  virtual DomElementType domElementType() const;

  virtual void setFormData(CgiEntry *entry);

  virtual bool isSelected(int index) const;
  virtual void dummy();

  friend class WSelectionBox;
};

}

#endif // WCOMBOBOX_H_
