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.

Public Types

Writable Properties

Read-Only Properties

Public Functions

Public Slots

Signals

Static Public Members

Protected Functions


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::NoInsertionThe string will not be inserted into the combobox.
QComboBox::AtTopThe string will be inserted as the first item in the combobox.
QComboBox::AtCurrentThe current item will be replaced by the string.
QComboBox::AtBottomThe string will be inserted after the last item in the combobox.
QComboBox::AfterCurrentThe string is inserted after the current item in the combobox.
QComboBox::BeforeCurrentThe 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:

See also editable.

autoHide : bool

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

Access functions:

count : int

This property holds the number of items in the combobox.

Access functions:

currentItem : int

Access functions:

currentText : QString

Access functions:

duplicatesEnabled : bool

This property holds whether the combobox can contain duplicate items.

Access functions:

editable : bool

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

Access functions:

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:

See also InsertionPolicy.

maxCount : int

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

Access functions:

sizeLimit : int

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

Access functions:


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]


Copyright © 2004 Trolltech Trademarks
Qt 4.0.0-b1