Class WComboBox

Direct Known Subclasses:

public class WComboBox extends WFormWidget
A widget that provides a drop-down combo-box control.

A combo box provides the user with a set of options, from which one option may be selected.

WComboBox is an MVC view class, using a simple string list model by default. The model may be populated using addItem() or insertItem() and the contents can be cleared through clear(). These methods manipulate the underlying getModel().

To use the combo box with a custom model instead of the default WStringListModel, use setModel().

To react to selection events, connect to the WFormWidget.changed(), activated() or sactivated() signals.

At all times, the current selection index is available through getCurrentIndex() and the current selection text using getCurrentText().

WComboBox does not have support for auto-completion, this behaviour can be found in the WSuggestionPopup.

WComboBox is an inline widget.


The widget corresponds to the HTML <select> tag and does not provide styling. It can be styled using inline or external CSS as appropriate.

  • Constructor Details

  • Method Details

    • addItem

      public void addItem(CharSequence text)
      Adds an option item.

      This adds an item to the underlying model. This requires that the getModel() is editable.

      Equivalent to insertItem() (getCount(), text).

    • getCount

      public int getCount()
      Returns the number of items.
    • getCurrentIndex

      public int getCurrentIndex()
      Returns the currently selected item.

      If no item is currently selected, the method returns -1.

      See Also:
    • insertItem

      public void insertItem(int index, CharSequence text)
      Inserts an item at the specified position.

      The item is inserted in the underlying model at position index. This requires that the getModel() is editable.

      See Also:
    • removeItem

      public void removeItem(int index)
      Removes the item at the specified position.

      The item is removed from the underlying model. This requires that the getModel() is editable.

      See Also:
    • setCurrentIndex

      public void setCurrentIndex(int index)
      Changes the current selection.

      Specify a value of -1 for index to clear the selection.

      Note: Setting a value of -1 works only if JavaScript is available.

    • setItemText

      public void setItemText(int index, CharSequence text)
      Changes the text for a specified option.

      The text for the item at position index is changed. This requires that the getModel() is editable.

    • getCurrentText

      public WString getCurrentText()
      Returns the text of the currently selected item.

      See Also:
    • getItemText

      public WString getItemText(int index)
      Returns the text of a particular item.

      See Also:
    • setModel

      public void setModel(WAbstractItemModel model)
      Sets the model to be used for the items.

      The default model is a WStringListModel.

      Items in the model can be grouped by setting the ItemDataRole.Level. The contents is interpreted by Wt::asString, and subsequent items of the same group are rendered as children of a HTML <optgroup> element.

      See Also:
    • setModelColumn

      public void setModelColumn(int index)
      Sets the column in the model to be used for the items.

      The column index in the model will be used to retrieve data.

      The default value is 0.

      See Also:
    • getModel

      public WAbstractItemModel getModel()
      Returns the data model.

      See Also:
    • findText

      public int findText(CharSequence text, MatchOptions flags)
      Returns the index of the first item that matches a text.
    • getSelectionMode

      public SelectionMode getSelectionMode()
      Returns the selection mode.

      Always returns SelectionMode.Single for a combo box, but may return SelectionMode.Extended for a selection box

      See Also:
    • getValueText

      public String getValueText()
      Returns the current value.

      Returns getCurrentText() as a String.

      Specified by:
      getValueText in class WFormWidget
    • setValueText

      public void setValueText(String value)
      Sets the current value.

      Sets the current index to the item corresponding to value.

      Specified by:
      setValueText in class WFormWidget
    • refresh

      public void refresh()
      Description copied from class: WWidget
      Refresh the widget.

      The refresh method is invoked when the locale is changed using WApplication#setLocale() or when the user hit the refresh button.

      The widget must actualize its contents in response.

      Note: This does not rerender the widget! Calling refresh() usually does not have any effect (unless you've reimplemented refresh() to attach to it an effect).

      refresh in class WFormWidget
    • clear

      public void clear()
      Clears all items.

      Removes all items from the underlying model. This requires that the getModel() is editable.

    • activated

      public Signal1<Integer> activated()
      Signal emitted when the selection changed.

      The newly selected item is passed as an argument.

      See Also:
    • sactivated

      public Signal1<WString> sactivated()
      Signal emitted when the selection changed.

      The newly selected text is passed as an argument.

      See Also:
    • setNoSelectionEnabled

      public void setNoSelectionEnabled(boolean enabled)
      Enables the ability to have 'no currently selected' item.

      The setting may only be changed for a combo box (and not for a selection box). When enabled, the getCurrentIndex() may be '-1' also when the combo box contains values. The user can however not select this option, it is thus only useful as a default value.

      By default, no selection is false for a combo-box and true for a selection box.

    • isNoSelectionEnabled

      public boolean isNoSelectionEnabled()
      Returns whether 'no selection' is a valid state.

      See Also:
    • setFormData

      protected void setFormData(WObject.FormData formData)
      setFormData in class WObject