Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions |

# QComboBox Class Reference

The QComboBox widget is a combined button and popup list. More...

    #include <QComboBox>

Inherits QWidget.

- List of all members, including inherited members
- Compatibility members

### Public Types

- enum InsertionPolicy { NoInsertion, AtTop, AtCurrent, AtBottom, AfterCurrent, BeforeCurrent }

### Writable Properties

- autoCompletion : bool
- autoHide : bool
- currentItem : int
- currentText : QString
- duplicatesEnabled : bool

- editable : bool
- insertionPolicy : InsertionPolicy
- maxCount : int
- sizeLimit : int

- 33 writable properties inherited from QWidget
- 1 writable property inherited from QObject

### Read-Only Properties

- count : int

- 20 read-only properties inherited from QWidget

### Public Functions

- QComboBox ( QWidget * parent = 0 )
- ~QComboBox ()
- bool contains ( const QString & text ) const
- QVariant data ( int role, int row ) const
- virtual int findItem ( const QString & text, QAbstractItemModel::MatchFlags flags = QAbstractItemModel::MatchDefault ) const
- void insertItem ( const QString & text, int row = -1 )
- void insertItem ( const QIcon & icon, int row = -1 )
- void insertItem ( const QIcon & icon, const QString & text, int row = -1 )
- void insertStringList ( const QStringList & list, int row = -1 )
- QAbstractItemDelegate * itemDelegate () const
- QAbstractItemView * itemView () const
- QLineEdit * lineEdit () const
- QAbstractItemModel * model () const
- QPixmap pixmap ( int row ) const
- virtual void popup ()
- void setItem ( const QIcon & icon, const QString & text, int row )
- void setItemData ( int role, const QVariant & value, int row )
- void setItemDelegate ( QAbstractItemDelegate * delegate )
- void setItemIcon ( const QIcon & icon, int row )
- void setItemText ( const QString & text, int row )
- void setItemView ( QAbstractItemView * itemView )
- void setLineEdit ( QLineEdit * edit )
- void setModel ( QAbstractItemModel * model )
- void setValidator ( const QValidator * validator )
- QString text ( int row ) const
- const QValidator * validator () const

- 92 public functions inherited from QWidget
- 26 public functions inherited from QObject
- 10 public functions inherited from QPaintDevice

### Public Slots

- void clearEdit ()
- void clearValidator ()
- virtual void setEditText ( const QString & text )

- 16 public slots inherited from QWidget
- 1 public slot inherited from QObject

### Signals

- void activated ( int row )
- void activated ( const QString & text )
- void highlighted ( int row )
- void highlighted ( const QString & text )
- void textChanged ( const QString & text )

- 1 signal inherited from QObject

### Static Public Members

- 4 static public members inherited from QWidget
- 4 static public members inherited from QObject

### Protected Functions

- virtual void wheelEvent ( QWheelEvent * e )

- 42 protected functions inherited from QWidget
- 7 protected functions inherited from QObject

## Detailed Description

The QComboBox widget is a combined button and popup list.

A QComboBox provides a means of presenting a list of options to the user in a way that takes up the minimum amount of screen space.

A combobox is a selection widget that displays the current item, and can pop up a list of selectable items. A combobox may be editable, allowing the user to modify each item in the list.

QComboBox supports three different display styles: Aqua/Motif 1.x, Motif 2.0 and Windows. In Motif 1.x, a combobox was called XmOptionMenu. In Motif 2.0, OSF introduced an improved combobox and named that XmComboBox. QComboBox provides both.

QComboBox provides two different constructors. The simplest constructor creates an "old-style" combobox in Motif (or Aqua) style:

        QComboBox *c = new QComboBox(this, "read-only combobox");

The other constructor creates a new-style combobox in Motif style, and can create both read-only and editable comboboxes:

        QComboBox *c1 = new QComboBox(false, this, "read-only combobox" );
        QComboBox *c2 = new QComboBox(true, this, "editable combobox" );

New-style comboboxes use a list box in both Motif and Windows styles, and both the content size and the on-screen size of the list box can be limited with sizeLimit() and setMaxCount() respectively. Old-style comboboxes use a popup in Aqua and Motif style, and that popup will happily grow larger than the desktop if you put enough data into it.

The two constructors create identical-looking comboboxes in Windows style.

Comboboxes can contain pixmaps as well as strings; the insertItem() and changeItem() functions are suitably overloaded. For editable comboboxes, the function clearEdit() is provided, to clear the displayed string without changing the combobox's contents.

A combobox emits two signals, activated() and highlighted(), when a new item has been activated (selected) or highlighted (made current). Both signals exist in two versions, one with a `QString` argument and one with an `int` argument. If the user highlights or activates a pixmap, only the `int` signals are emitted. Whenever the text of an editable combobox is changed the textChanged() signal is emitted.

When the user enters a new string in an editable combobox, the widget may or may not insert it, and it can insert it in several locations. The default policy is is `AtBottom` but you can change this using setInsertionPolicy().

It is possible to constrain the input to an editable combobox using QValidator; see setValidator(). By default, any input is accepted.

A combobox can be populated using the insert functions, insertStringList() and insertItem() for example. Items can be changed with changeItem(). An item can be removed with removeItem() and all items can be removed with clear(). The text of the current item is returned by currentText(), and the text of a numbered item is returned with text(). The current item can be set with setCurrentItem() or setCurrentText(). The number of items in the combobox is returned by count(); the maximum number of items can be set with setMaxCount(). You can allow editing using setEditable(). For editable comboboxes you can set auto-completion using setAutoCompletion() and whether or not the user can add duplicates is set with setDuplicatesEnabled().

<img src="qcombo1-m.png">(Motif 1, read-only)<br clear=all> <img src="qcombo2-m.png">(Motif 2, editable)<br clear=all> <img src="qcombo3-m.png">(Motif 2, read-only)<br clear=all> <img src="qcombo1-w.png">(Windows style)

GUI Design Handbook: Combo Box, GUI Design Handbook: Drop-Down List Box.

See also QLineEdit, QSpinBox, QRadioButton, and QButtonGroup.

## Member Type Documentation

### enum QComboBox::InsertionPolicy

This enum specifies what the QComboBox should do when a new string is entered by the user.

`QComboBox::NoInsertion` | The string will not be inserted into the combobox.
`QComboBox::AtTop` | The string will be inserted as the first item in the combobox.
`QComboBox::AtCurrent` | The current item will be replaced by the string.
`QComboBox::AtBottom` | The string will be inserted after the last item in the combobox.
`QComboBox::AfterCurrent` | The string is inserted after the current item in the combobox.
`QComboBox::BeforeCurrent` | The string is inserted before the current item in the combobox.

## Property Documentation

### autoCompletion : bool

This property holds whether the combobox provides auto-completion for editable items.

Access functions:

- bool autoCompletion () const
- void setAutoCompletion ( bool enable )

See also editable.

### autoHide : bool

This property holds whether the combobox hides the popup listbox when an item is activated.

Access functions:

- bool autoHide () const
- void setAutoHide ( bool enable )

### count : int

This property holds the number of items in the combobox.

Access functions:

- int count () const

### currentItem : int

Access functions:

- int currentItem () const
- void setCurrentItem ( int row )

### currentText : QString

Access functions:

- QString currentText () const
- void setCurrentText ( const QString & )

### duplicatesEnabled : bool

This property holds whether the combobox can contain duplicate items.

Access functions:

- bool duplicatesEnabled () const
- void setDuplicatesEnabled ( bool enable )

### editable : bool

This property holds whether the combobox can be edited by the user.

Access functions:

- bool isEditable () const
- void setEditable ( bool editable )

### insertionPolicy : InsertionPolicy

This property holds the policy used to determine where user-inserted items should appear in the combobox.

The default value is `AtBottom`, indicating that new items will appear at the bottom of the list of items.

Access functions:

- InsertionPolicy insertionPolicy () const
- void setInsertionPolicy ( InsertionPolicy policy )

See also InsertionPolicy.

### maxCount : int

This property holds the maximum number of items allowed in the combobox.

Access functions:

- int maxCount () const
- void setMaxCount ( int max )

### sizeLimit : int

This property holds the maximum allowed size on screen of the combobox.

Access functions:

- int sizeLimit () const
- void setSizeLimit ( int limit )

## Member Function Documentation

### QComboBox::QComboBox ( QWidget * parent = 0 )

Constructs a combobox with the given parent, using the default model QStandardItemModel.

### QComboBox::~QComboBox ()

Destroys the combobox.

### void QComboBox::activated ( int row ) `[signal]`

This signal is sent when an item in the combobox is activated. The item's row is given.

### void QComboBox::activated ( const QString & text ) `[signal]`

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

This signal is sent when an item in the combobox is activated. The item's text is given.

### void QComboBox::clearEdit () `[slot]`

Clears the contents of the line edit used for editing in the combobox.

### void QComboBox::clearValidator () `[slot]`

Clears (removes) the validator used to check user input for the combobox.

### bool QComboBox::contains ( const QString & text ) const

Returns true if any item in the combobox matches the given text.

### QVariant QComboBox::data ( int role, int row ) const

Returns the data for the given role in the given row in the combobox, or QVariant::Invalid if there is no data for this role.

### int QComboBox::findItem ( const QString & text, QAbstractItemModel::MatchFlags flags = QAbstractItemModel::MatchDefault ) const `[virtual]`

Returns the index of the item containing the given text; otherwise returns -1.

The flags specify how the items in the combobox are searched.

### void QComboBox::highlighted ( int row ) `[signal]`

This signal is sent when an item in the combobox is highlighted. The item's row is given.

### void QComboBox::highlighted ( const QString & text ) `[signal]`

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

This signal is sent when an item in the combobox is highlighted. The item's text is given.

### void QComboBox::insertItem ( const QString & text, int row = -1 )

Inserts the text into the combobox at the given row.

### void QComboBox::insertItem ( const QIcon & icon, int row = -1 )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Inserts the icon into the combobox at the given row.

### void QComboBox::insertItem ( const QIcon & icon, const QString & text, int row = -1 )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Inserts the icon and text into the combobox at the given row.

### void QComboBox::insertStringList ( const QStringList & list, int row = -1 )

Inserts the strings from the list into the combobox as separate items, starting at the row specified.

### QAbstractItemDelegate * QComboBox::itemDelegate () const

Returns the item delegate used by the popup list view.

See also setItemDelegate().

### QAbstractItemView * QComboBox::itemView () const

Returns the list view used for the combobox popup.

### QLineEdit * QComboBox::lineEdit () const

Returns the line edit used to edit items in the combobox, or 0 if there is no line edit.

Only editable combo boxes have a line edit.

### QAbstractItemModel * QComboBox::model () const

Returns the model used by the combobox.

### QPixmap QComboBox::pixmap ( int row ) const

Returns the pixmap for the given row in the combobox.

### void QComboBox::popup () `[virtual]`

Displays the list of items in the combobox. If the list is empty then no items will be shown.

### void QComboBox::setEditText ( const QString & text ) `[virtual slot]`

Sets the text in the combobox's text edit.

### void QComboBox::setItem ( const QIcon & icon, const QString & text, int row )

Sets the icon and text for the given row in the combobox.

### void QComboBox::setItemData ( int role, const QVariant & value, int row )

Sets the data role for the item on the given row in the combobox to the value variant.

### void QComboBox::setItemDelegate ( QAbstractItemDelegate * delegate )

Sets the item delegate for the popup list view. The combobox takes ownership of the delegate.

See also itemDelegate().

### void QComboBox::setItemIcon ( const QIcon & icon, int row )

Sets the icon for the item on the given row in the combobox.

### void QComboBox::setItemText ( const QString & text, int row )

Sets the text for the item on the given row in the combobox.

### void QComboBox::setItemView ( QAbstractItemView * itemView )

Sets the view to be used in the combobox popup.

### void QComboBox::setLineEdit ( QLineEdit * edit )

Sets the line edit to use instead of the current line edit widget.

### void QComboBox::setModel ( QAbstractItemModel * model )

Sets the model to be model,

### void QComboBox::setValidator ( const QValidator * validator )

Sets the validator to use instead of the current validator.

### QString QComboBox::text ( int row ) const

Returns the text for the given row in the combobox.

### void QComboBox::textChanged ( const QString & text ) `[signal]`

This signal is sent when the text changes in the current item. The item's new text is given.

### const QValidator * QComboBox::validator () const

Returns the validator that is used to constrain text input for the combobox.

See also editable.

### void QComboBox::wheelEvent ( QWheelEvent * e ) `[virtual protected]`