Contents

• Public Types
• Properties
• Public Functions
• Reimplemented Public Functions
• Public Slots
• Signals
• Protected Functions
• Reimplemented Protected Functions
• Detailed Description

Detailed Description

TheQComboBox widget is a combined button and popup list.

AQComboBox 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.

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

There are two signals emitted if the current item of a combobox changes,currentIndexChanged() andactivated().currentIndexChanged() is always emitted regardless if the change was done programmatically or by user interaction, whileactivated() is only emitted when the change is caused by user interaction. Thehighlighted() signal is emitted when the user highlights an item in the combobox popup list. All three signals exist in two versions, one with aQString argument and one with anint argument. If the user selects or highlights a pixmap, only theint signals are emitted. Whenever the text of an editable combobox is changed theeditTextChanged() 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 isAtBottom but you can change this usingsetInsertPolicy().

It is possible to constrain the input to an editable combobox usingQValidator; seesetValidator(). By default, any input is accepted.

A combobox can be populated using the insert functions,insertItem() andinsertItems() for example. Items can be changed withsetItemText(). An item can be removed withremoveItem() and all items can be removed withclear(). The text of the current item is returned bycurrentText(), and the text of a numbered item is returned withtext(). The current item can be set withsetCurrentIndex(). The number of items in the combobox is returned bycount(); the maximum number of items can be set withsetMaxCount(). You can allow editing usingsetEditable(). For editable comboboxes you can set auto-completion usingsetCompleter() and whether or not the user can add duplicates is set withsetDuplicatesEnabled().

QComboBox uses themodel/view framework for its popup list and to store its items. By default aQStandardItemModel stores the items and aQListView subclass displays the popuplist. You can access the model and view directly (withmodel() andview()), butQComboBox also provides functions to set and get item data (e.g.,setItemData() anditemText()). You can also set a new model and view (withsetModel() andsetView()). For the text and icon in the combobox label, the data in the model that has theQt::DisplayRole andQt::DecorationRole is used. Note that you cannot alter theSelectionMode of theview(), e.g., by usingsetSelectionMode().

Member Type Documentation

enum QComboBox::InsertPolicy

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

enum QComboBox::SizeAdjustPolicy

This enum specifies how the size hint of theQComboBox should adjust when new content is added or content changes.

Property Documentation

count : constint

This property holds the number of items in the combobox.

By default, for an empty combo box, this property has a value of 0.

Access functions:

currentIndex :int

This property holds the index of the current item in the combobox.

The current index can change when inserting or removing items.

By default, for an empty combo box or a combo box in which no current item is set, this property has a value of -1.

Access functions:

Notifier signal:

currentText : constQString

This property holds the current text.

If the combo box is editable, the current text is the value displayed by the line edit. Otherwise, it is the value of the current item or an empty string if the combo box is empty or no current item is set.

Access functions:

See alsoeditable.

duplicatesEnabled :bool

This property holds whether the user can enter duplicate items into the combobox.

Note that it is always possible to programmatically insert duplicate items into the combobox.

By default, this property is false (duplicates are not allowed).

Access functions:

editable :bool

This property holds whether the combo box can be edited by the user.

By default, this property is false. The effect of editing depends on the insert policy.

Access functions:

See alsoInsertPolicy.

frame :bool

This property holds whether the combo box draws itself with a frame.

If enabled (the default) the combo box draws itself inside a frame, otherwise the combo box draws itself without any frame.

Access functions:

iconSize :QSize

This property holds the size of the icons shown in the combobox.

Unless explicitly set this returns the default value of the current style. This size is the maximum size that icons can have; icons of smaller size are not scaled up.

Access functions:

insertPolicy :InsertPolicy

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

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

Access functions:

See alsoInsertPolicy.

maxCount :int

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

Note:If you set the maximum number to be less then the current amount of items in the combobox, the extra items will be truncated. This also applies if you have set an external model on the combobox.

By default, this property's value is derived from the highest signed integer available (typically 2147483647).

Access functions:

maxVisibleItems :int

This property holds the maximum allowed size on screen of the combo box, measured in items.

By default, this property has a value of 10.

Note:This property is ignored for non-editable comboboxes in styles that returns true forQStyle::SH_ComboBox_Popup such as the Mac style or the Gtk+ Style.

Access functions:

minimumContentsLength :int

This property holds the minimum number of characters that should fit into the combobox.

The default value is 0.

If this property is set to a positive value, theminimumSizeHint() andsizeHint() take it into account.

Access functions:

See alsosizeAdjustPolicy.

modelColumn :int

This property holds the column in the model that is visible.

If set prior to populating the combo box, the pop-up view will not be affected and will show the first column (using this property's default value).

By default, this property has a value of 0.

Access functions:

sizeAdjustPolicy :SizeAdjustPolicy

This property holds the policy describing how the size of the combobox changes when the content changes.

The default value isAdjustToContentsOnFirstShow.

Access functions:

See alsoSizeAdjustPolicy.

Member Function Documentation

QComboBox::QComboBox(QWidget * parent = 0)

Constructs a combobox with the givenparent, using the default modelQStandardItemModel.

QComboBox::~QComboBox()

Destroys the combobox.

[signal]void QComboBox::activated(int index)

This signal is sent when the user chooses an item in the combobox. The item'sindex is passed. Note that this signal is sent even when the choice is not changed. If you need to know when the choice actually changes, use signalcurrentIndexChanged().

Note:Signalactivated is overloaded in this class. To connect to this one using the function pointer syntax, you must specify the signal type in a static cast, as shown in this example:

connect(comboBox,static_cast<void(QComboBox::*)(int)>(&QComboBox::activated),[=](int index){/* ... */ });

[signal]void QComboBox::activated(constQString & text)

This signal is sent when the user chooses an item in the combobox. The item'stext is passed. Note that this signal is sent even when the choice is not changed. If you need to know when the choice actually changes, use signalcurrentIndexChanged().

Note:Signalactivated is overloaded in this class. To connect to this one using the function pointer syntax, you must specify the signal type in a static cast, as shown in this example:

connect(comboBox,static_cast<void(QComboBox::*)(constQString&)>(&QComboBox::activated),[=](constQString&text){/* ... */ });

void QComboBox::addItem(constQString & text, constQVariant & userData = QVariant())

Adds an item to the combobox with the giventext, and containing the specifieduserData (stored in theQt::UserRole). The item is appended to the list of existing items.

void QComboBox::addItem(constQIcon & icon, constQString & text, constQVariant & userData = QVariant())

Adds an item to the combobox with the givenicon andtext, and containing the specifieduserData (stored in theQt::UserRole). The item is appended to the list of existing items.

void QComboBox::addItems(constQStringList & texts)

Adds each of the strings in the giventexts to the combobox. Each item is appended to the list of existing items in turn.

[virtual protected]void QComboBox::changeEvent(QEvent * e)

Reimplemented fromQWidget::changeEvent().

[slot]void QComboBox::clear()

Clears the combobox, removing all items.

Note: If you have set an external model on the combobox this model will still be cleared when calling this function.

[slot]void QComboBox::clearEditText()

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

QCompleter * QComboBox::completer() const

Returns the completer that is used to auto complete text input for the combobox.

This function was introduced in Qt 4.2.

See alsosetCompleter() andeditable.

[virtual protected]void QComboBox::contextMenuEvent(QContextMenuEvent * e)

Reimplemented fromQWidget::contextMenuEvent().

[signal]void QComboBox::editTextChanged(constQString & text)

This signal is emitted when the text in the combobox's line edit widget is changed. The new text is specified bytext.

[virtual]bool QComboBox::event(QEvent * event)

Reimplemented fromQObject::event().

int QComboBox::findData(constQVariant & data,int role = Qt::UserRole,Qt::MatchFlags flags = static_cast<Qt::MatchFlags> ( Qt::MatchExactly | Qt::MatchCaseSensitive )) const

Returns the index of the item containing the givendata for the givenrole; otherwise returns -1.

Theflags specify how the items in the combobox are searched.

int QComboBox::findText(constQString & text,Qt::MatchFlags flags = static_cast<Qt::MatchFlags> ( Qt::MatchExactly | Qt::MatchCaseSensitive )) const

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

Theflags specify how the items in the combobox are searched.

[virtual protected]void QComboBox::focusInEvent(QFocusEvent * e)

Reimplemented fromQWidget::focusInEvent().

[virtual protected]void QComboBox::focusOutEvent(QFocusEvent * e)

Reimplemented fromQWidget::focusOutEvent().

[virtual protected]void QComboBox::hideEvent(QHideEvent * e)

Reimplemented fromQWidget::hideEvent().

[virtual]void QComboBox::hidePopup()

Hides the list of items in the combobox if it is currently visible and resets the internal state, so that if the custom pop-up was shown inside the reimplementedshowPopup(), then you also need to reimplement the hidePopup() function to hide your custom pop-up and call the base class implementation to reset the internal state whenever your custom pop-up widget is hidden.

See alsoshowPopup().

[signal]void QComboBox::highlighted(int index)

This signal is sent when an item in the combobox popup list is highlighted by the user. The item'sindex is passed.

Note:Signalhighlighted is overloaded in this class. To connect to this one using the function pointer syntax, you must specify the signal type in a static cast, as shown in this example:

connect(comboBox,static_cast<void(QComboBox::*)(int)>(&QComboBox::highlighted),[=](int index){/* ... */ });

[signal]void QComboBox::highlighted(constQString & text)

This signal is sent when an item in the combobox popup list is highlighted by the user. The item'stext is passed.

Note:Signalhighlighted is overloaded in this class. To connect to this one using the function pointer syntax, you must specify the signal type in a static cast, as shown in this example:

connect(comboBox,static_cast<void(QComboBox::*)(constQString&)>(&QComboBox::highlighted),[=](constQString&text){/* ... */ });

[protected]void QComboBox::initStyleOption(QStyleOptionComboBox * option) const

Initializeoption with the values from thisQComboBox. This method is useful for subclasses when they need aQStyleOptionComboBox, but don't want to fill in all the information themselves.

See alsoQStyleOption::initFrom().

[virtual protected]void QComboBox::inputMethodEvent(QInputMethodEvent * e)

Reimplemented fromQWidget::inputMethodEvent().

[virtual protected]QVariant QComboBox::inputMethodQuery(Qt::InputMethodQuery query) const

Reimplemented fromQWidget::inputMethodQuery().

void QComboBox::insertItem(int index, constQString & text, constQVariant & userData = QVariant())

Inserts thetext anduserData (stored in theQt::UserRole) into the combobox at the givenindex.

If the index is equal to or higher than the total number of items, the new item is appended to the list of existing items. If the index is zero or negative, the new item is prepended to the list of existing items.

See alsoinsertItems().

void QComboBox::insertItem(int index, constQIcon & icon, constQString & text, constQVariant & userData = QVariant())

Inserts theicon,text anduserData (stored in theQt::UserRole) into the combobox at the givenindex.

If the index is equal to or higher than the total number of items, the new item is appended to the list of existing items. If the index is zero or negative, the new item is prepended to the list of existing items.

See alsoinsertItems().

void QComboBox::insertItems(int index, constQStringList & list)

Inserts the strings from thelist into the combobox as separate items, starting at theindex specified.

If the index is equal to or higher than the total number of items, the new items are appended to the list of existing items. If the index is zero or negative, the new items are prepended to the list of existing items.

See alsoinsertItem().

void QComboBox::insertSeparator(int index)

Inserts a separator item into the combobox at the givenindex.

If the index is equal to or higher than the total number of items, the new item is appended to the list of existing items. If the index is zero or negative, the new item is prepended to the list of existing items.

This function was introduced in Qt 4.4.

See alsoinsertItem().

QVariant QComboBox::itemData(int index,int role = Qt::UserRole) const

Returns the data for the givenrole in the givenindex in the combobox, orQVariant::Invalid if there is no data for this role.

See alsosetItemData().

QAbstractItemDelegate * QComboBox::itemDelegate() const

Returns the item delegate used by the popup list view.

See alsosetItemDelegate().

QIcon QComboBox::itemIcon(int index) const

Returns the icon for the givenindex in the combobox.

See alsosetItemIcon().

QString QComboBox::itemText(int index) const

Returns the text for the givenindex in the combobox.

See alsosetItemText().

[virtual protected]void QComboBox::keyPressEvent(QKeyEvent * e)

Reimplemented fromQWidget::keyPressEvent().

[virtual protected]void QComboBox::keyReleaseEvent(QKeyEvent * e)

Reimplemented fromQWidget::keyReleaseEvent().

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.

See alsosetLineEdit().

[virtual]QSize QComboBox::minimumSizeHint() const

Reimplemented fromQWidget::minimumSizeHint().

QAbstractItemModel * QComboBox::model() const

Returns the model used by the combobox.

See alsosetModel().

[virtual protected]void QComboBox::mousePressEvent(QMouseEvent * e)

Reimplemented fromQWidget::mousePressEvent().

[virtual protected]void QComboBox::mouseReleaseEvent(QMouseEvent * e)

Reimplemented fromQWidget::mouseReleaseEvent().

[virtual protected]void QComboBox::paintEvent(QPaintEvent * e)

Reimplemented fromQWidget::paintEvent().

void QComboBox::removeItem(int index)

Removes the item at the givenindex from the combobox. This will update the current index if the index is removed.

This function does nothing ifindex is out of range.

[virtual protected]void QComboBox::resizeEvent(QResizeEvent * e)

Reimplemented fromQWidget::resizeEvent().

QModelIndex QComboBox::rootModelIndex() const

Returns the root model item index for the items in the combobox.

See alsosetRootModelIndex().

void QComboBox::setCompleter(QCompleter * completer)

Sets thecompleter to use instead of the current completer. Ifcompleter is 0, auto completion is disabled.

By default, for an editable combo box, aQCompleter that performs case insensitive inline completion is automatically created.

This function was introduced in Qt 4.2.

See alsocompleter().

[slot]void QComboBox::setEditText(constQString & text)

Sets thetext in the combobox's text edit.

void QComboBox::setItemData(int index, constQVariant & value,int role = Qt::UserRole)

Sets the datarole for the item on the givenindex in the combobox to the specifiedvalue.

See alsoitemData().

void QComboBox::setItemDelegate(QAbstractItemDelegate * delegate)

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

Warning: You should not share the same instance of a delegate between comboboxes, widget mappers or views. Doing so can cause incorrect or unintuitive editing behavior since each view connected to a given delegate may receive thecloseEditor() signal, and attempt to access, modify or close an editor that has already been closed.

See alsoitemDelegate().

void QComboBox::setItemIcon(int index, constQIcon & icon)

Sets theicon for the item on the givenindex in the combobox.

See alsoitemIcon().

void QComboBox::setItemText(int index, constQString & text)

Sets thetext for the item on the givenindex in the combobox.

See alsoitemText().

void QComboBox::setLineEdit(QLineEdit * edit)

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

The combo box takes ownership of the line edit.

See alsolineEdit().

void QComboBox::setModel(QAbstractItemModel * model)

Sets the model to bemodel.model must not be 0. If you want to clear the contents of a model, callclear().

See alsomodel() andclear().

void QComboBox::setRootModelIndex(constQModelIndex & index)

Sets the root model itemindex for the items in the combobox.

See alsorootModelIndex().

void QComboBox::setValidator(constQValidator * validator)

Sets thevalidator to use instead of the current validator.

See alsovalidator().

void QComboBox::setView(QAbstractItemView * itemView)

Sets the view to be used in the combobox popup to the givenitemView. The combobox takes ownership of the view.

Note: If you want to use the convenience views (likeQListWidget,QTableWidget orQTreeWidget), make sure to callsetModel() on the combobox with the convenience widgets model before calling this function.

See alsoview().

[virtual protected]void QComboBox::showEvent(QShowEvent * e)

Reimplemented fromQWidget::showEvent().

[virtual]void QComboBox::showPopup()

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

If you reimplement this function to show a custom pop-up, make sure you callhidePopup() to reset the internal state.

See alsohidePopup().

[virtual]QSize QComboBox::sizeHint() const

Reimplemented fromQWidget::sizeHint().

This implementation caches the size hint to avoid resizing when the contents change dynamically. To invalidate the cached value change thesizeAdjustPolicy.

constQValidator * QComboBox::validator() const

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

See alsosetValidator() andeditable.

QAbstractItemView * QComboBox::view() const

Returns the list view used for the combobox popup.

See alsosetView().

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

Reimplemented fromQWidget::wheelEvent().