Q3ListBox Class Reference
[Qt3Support module]

Detailed Description

The Q3ListBox widget provides a list of selectable, read-only items.

This is typically a single-column list in which either no item or one item is selected, but it can also be used in many other ways.

Q3ListBox will add scroll bars as necessary, but it isn't intended for really big lists. If you want more than a few thousand items, it's probably better to use a different widget mainly because the scroll bars won't provide very good navigation, but also because Q3ListBox may become slow with huge lists. (See Q3ListView and Q3Table for possible alternatives.)

There are a variety of selection modes described in the Q3ListBox::SelectionMode documentation. The default is Single selection mode, but you can change it using setSelectionMode(). (setMultiSelection() is still provided for compatibility with Qt 1.x. We recommend using setSelectionMode() in all code.)

Because Q3ListBox offers multiple selection it must display keyboard focus and selection state separately. Therefore there are functions both to set the selection state of an item, i.e. setSelected(), and to set which item displays keyboard focus, i.e. setCurrentItem().

The list box normally arranges its items in a single column and adds a vertical scroll bar if required. It is possible to have a different fixed number of columns (setColumnMode()), or as many columns as will fit in the list box's assigned screen space (setColumnMode(FitToWidth)), or to have a fixed number of rows (setRowMode()) or as many rows as will fit in the list box's assigned screen space (setRowMode(FitToHeight)). In all these cases Q3ListBox will add scroll bars, as appropriate, in at least one direction.

If multiple rows are used, each row can be as high as necessary (the normal setting), or you can request that all items will have the same height by calling setVariableHeight(false). The same applies to a column's width, see setVariableWidth().

The Q3ListBox's items are Q3ListBoxItem objects. Q3ListBox provides methods to insert new items as strings, as pixmaps, and as Q3ListBoxItem * (insertItem() with various arguments), and to replace an existing item with a new string, pixmap or Q3ListBoxItem (changeItem() with various arguments). You can also remove items singly with removeItem() or clear() the entire list box. Note that if you create a Q3ListBoxItem yourself and insert it, Q3ListBox takes ownership of the item.

You can also create a Q3ListBoxItem, such as Q3ListBoxText or Q3ListBoxPixmap, with the list box as first parameter. The item will then append itself. When you delete an item it is automatically removed from the list box.

The list of items can be arbitrarily large; Q3ListBox will add scroll bars if necessary. Q3ListBox can display a single-column (the common case) or multiple-columns, and offers both single and multiple selection. Q3ListBox does not support multiple-column items (but Q3ListView and Q3Table do), or tree hierarchies (but Q3ListView does).

The list box items can be accessed both as Q3ListBoxItem objects (recommended) and using integer indexes (the original Q3ListBox implementation used an array of strings internally, and the API still supports this mode of operation). Everything can be done using the new objects, and most things can be done using indexes.

Each item in a Q3ListBox contains a Q3ListBoxItem. One of the items can be the current item. The currentChanged() signal and the highlighted() signal are emitted when a new item becomes current, e.g. because the user clicks on it or Q3ListBox::setCurrentItem() is called. The selected() signal is emitted when the user double-clicks on an item or presses Enter on the current item.

If the user does not select anything, no signals are emitted and currentItem() returns -1.

A list box has Qt::WheelFocus as a default focusPolicy(), i.e. it can get keyboard focus by tabbing, clicking and through the use of the mouse wheel.

New items can be inserted using insertItem(), insertStrList() or insertStringList().

By default, vertical and horizontal scroll bars are added and removed as necessary. setHScrollBarMode() and setVScrollBarMode() can be used to change this policy.

If you need to insert types other than strings and pixmaps, you must define new classes which inherit Q3ListBoxItem.

Warning: The list box assumes ownership of all list box items and will delete them when it does not need them any more.

See also Q3ListView, QComboBox, and QButtonGroup.

Member Type Documentation