Q3ComboBox Class Reference
[Qt3Support module]

Detailed Description

The Q3ComboBox widget is a combined button and popup list.

A combobox is a selection widget which displays the current item and can pop up a list of items. A combobox may be editable in which case the user can enter arbitrary strings.

Comboboxes provide a means of showing the user's current choice out of a list of options in a way that takes up the minimum amount of screen space.

Q3ComboBox 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. Q3ComboBox provides both.

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

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

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

 Q3ComboBox *c1 = new Q3ComboBox(false, this, tr("read-only combobox"));
 Q3ComboBox *c2 = new Q3ComboBox(true, this, tr("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.

If the combobox is not editable then it has a default focusPolicy() of TabFocus, i.e. it will not grab focus if clicked. This differs from both Windows and Motif. If the combobox is editable then it has a default focusPolicy() of StrongFocus, i.e. it will grab focus if clicked.

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().

Depending on the style, Q3ComboBox will use a list box or a popup menu to display the list of items. See setListBox() for more information.

{GUI Design Handbook}{GUI Design Handbook: Combo Box, Drop-Down List Box}

See also QComboBox, QLineEdit, and QSpinBox.

Member Type Documentation

 static const char* items[] = { "red", "green", "blue", 0 };
 combo->insertStrList( items );