Wt: Wt::Ext::ComboBox Class Reference

Wt 3.3.0

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

- Class List
- Class Hierarchy
- Class Members

Public Member Functions
Wt::Ext::ComboBox Class Reference
Ext widgets (Wt::Ext, deprecated) | Model/view system

A widget that provides a drop-down combo-box control. More...

`#include <Wt/Ext/ComboBox>`

Inheritance diagram for Wt::Ext::ComboBox:
[legend]

List of all members.

## Public Member Functions
| ComboBox (WContainerWidget *parent=0)
| Create an empty combo-box with optional parent.
void | addItem (const WString &text)
| Add an option item.
int | count () const
| Get the number of items.
int | currentIndex () const
| Get the currently selected item.
void | insertItem (int index, const WString &text)
| Insert an option item at the specified position.
void | removeItem (int index)
| Remove the option item at the specified position.
void | setCurrentIndex (int index)
| Change the current selection.
void | setItemText (int index, const WString &text)
| Change the text for a specified option.
const WString | currentText () const
| Get the text of the currently selected item.
const WString | itemText (int index) const
| Get the text of a particular item.
void | setModel (WAbstractItemModel *model)
| Set the model to be used for the items.
void | setModelColumn (int index)
| Set the column in the model to be used for the items.
void | setEditable (bool how)
| Set if the combo-box is editable.
void | setQueryDelay (int milliSeconds)
| Configure the delay to filter the list matching the current input.
void | setMinQueryLength (int numChars)
| Configure the minimum number of characters to be entered before filtering the drop-down list.
void | setPageSize (int pageSize)
| Configure a page size to show matching values one page at a time.
void | setDataLocation (DataLocation dataLocation)
| Configure the location of the data for the combo-box.
virtual void | refresh ()
| Refresh the widget.
void | clear ()
| Clear all items.
JSignal< int > & | activated ()
| Signal emitted when the selection changed.

## Detailed Description

A widget that provides a drop-down combo-box control.

A combo-box provides the user with a choice of options to chose from. Use addItem(const WString&) or insertItem(int, const WString&) to populate the combo-box. All the content can be cleared through clear().

To act on a new selection, either connect a slot to the activated() signal.

At all times, the current selection index is available through currentIndex() or the text using currentText().

By default the ComboBox uses a WStringListModel to store the items. This may be changed by specifying a custom model with setModel().

When the combobox is configured to be editable, the user may enter a value which is not available in the list of values. In that case, currentText() will hold this value, while currentIndex() == -1 indicates that the value was not in the list.

By default, all the data is downloaded to the client. This may be changed using setDataLocation(DataLocation) to keep the data at hte server, and download data on-demand. This is useful if you have a very large list of options.

The API is a superset of the WComboBox API.

ComboBox with expanded drop-down list.

## Member Function Documentation

void Wt::Ext::ComboBox::addItem | ( | const WString & | text | ) |

Add an option item.

Equivalent to insertItem (count(), text).

int Wt::Ext::ComboBox::currentIndex | ( |  | ) | const

Get the currently selected item.

If no item is currently selected, the method returns -1.
If the combo-box is editable and the entered text does not match an existing item, then this method also returns -1. Otherwise the index is returned of the first item that matches the value of currentText().

const WString Wt::Ext::ComboBox::currentText | ( |  | ) | const

Get the text of the currently selected item.

This retrieves the current text entered by the user. When the combo-box is editable, this may be text that does not correspond to any of the items.

void Wt::Ext::ComboBox::insertItem | ( | int | index,
|  | const WString & | text
| ) |  |

Insert an option item at the specified position.

The option item is inserted at position index.

const WString Wt::Ext::ComboBox::itemText | ( | int | index | ) | const

Get the text of a particular item.

Use this method to get the text for the item at position index.

void Wt::Ext::ComboBox::refresh | ( |  | ) | `[virtual]`

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.

Reimplemented from Wt::Ext::FormField.

void Wt::Ext::ComboBox::removeItem | ( | int | index | ) |

Remove the option item at the specified position.

The option item at position index will be removed.

void Wt::Ext::ComboBox::setCurrentIndex | ( | int | index | ) |

Change the current selection.

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

void Wt::Ext::ComboBox::setDataLocation | ( | DataLocation | dataLocation | ) |

Configure the location of the data for the combo-box.

When a ClientSide data location is specified, all data for the combo-box is downloaded when the combo-box is created. Using a ServerSide data location, data is downloaded to the client only when needed.

The defualt value is ClientSide.

void Wt::Ext::ComboBox::setEditable | ( | bool | how | ) |

Set if the combo-box is editable.

An editable combo-box allows the user to specify a value that is not part of the list of values.

The default is false.

See also:
  currentText()

void Wt::Ext::ComboBox::setItemText | ( | int | index,
|  | const WString & | text
| ) |  |

Change the text for a specified option.

Use this method to change the text for the item at position index.

void Wt::Ext::ComboBox::setMinQueryLength | ( | int | numChars | ) |

Configure the minimum number of characters to be entered before filtering the drop-down list.

Values in the drop-down list will only be filtered when the entered text contains more that numChars characters.

The default value is 4.

See also:
  setQueryDelay(int)

void Wt::Ext::ComboBox::setModel | ( | WAbstractItemModel * | model | ) |

Set the model to be used for the items.

The model may not be 0, and ownership of the model is not transferred.

See also:
  setModelColumn(int)

void Wt::Ext::ComboBox::setModelColumn | ( | int | index | ) |

Set the column in the model to be used for the items.

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

See also:
  setModel()

void Wt::Ext::ComboBox::setPageSize | ( | int | pageSize | ) |

Configure a page size to show matching values one page at a time.

At most pageSize matches will be shown at the same time in the combo-box.

The default value is 0 (no paging).

void Wt::Ext::ComboBox::setQueryDelay | ( | int | milliSeconds | ) |

Configure the delay to filter the list matching the current input.

After the a delay of milliSeconds milli seconds, the list items are filtered to match the currently entered text and the drop-down list is updated. It is recommended to specify a non-zero delay when using a Remote data location.

The default is 0.

See also:
  setMinQueryLength(int)

All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator