| Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions | |
The QListBox widget provides a list of selectable, read-only items. More...
#include <qlistbox.h>
Inherits QScrollView.
This is typically a single-column list in which zero or one item is selected, but it can also be used in many other ways.
QListBox 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 QListBox may become slow with huge lists.
There are a variety of selection modes described in the QListBox::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 recomment using setSelectionMode() in all code.)
Because QListBox 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 select 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 QListBox 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 items discussed are QListBoxItem objects. QListBox provides methods to insert new items as strings, as pixmaps, and as QListBoxItem * (insertItem() with various arguments), and to replace an existing item with a new string, pixmap or QListBoxItem (changeItem() with various arguments). You can also remove items singly with removeItem() or clear() the entire list box. Note that if you create a QListBoxItem yourself and insert it, it becomes the property of QListBox and you must not delete it. (QListBox will delete it when appropriate.)
You can also create a QListBoxItem, such as QListBoxText or QListBoxPixmap, 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; QListBox will add scroll bars if necessary. QListBox can display a single-column (the common case) or multiple-columns, and offers both single and multiple selection. (QListBox does not support multiple-column items, or tree hierarchies; use QListView if you require such functionality.)
The list box items can be accessed both as QListBoxItem objects (recommended) and using integer indexes (the original QListBox implementation used an array of strings internally, and the API still supports this mode of operation). Everything can be done using the new objects; most things can be done using the indexes, too, but unfortunately not everything.
Each item in a QListBox contains a QListBoxItem. One of the items can be the current item. The highlighted() signal is emitted when a new item gets highlighted, e.g. because the user clicks on it or QListBox::setCurrentItem() is called. The selected() signal is emitted when the user double-clicks on an item or presses Enter when an item is highlighted.
If the user does not select anything, no signals are emitted and currentItem() returns -1.
A list box has 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(). inSort() is obsolete because this method is quite inefficient. It's preferable to insert the items normally and call sort() afterwards, or to insert a sorted QStringList().
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 QListBoxItem.
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 QListView, QComboBox, QButtonGroup, GUI Design Handbook: List Box (two sections) and Advanced Widgets.
This enum type is used to specify how QListBox lays out its rows and columns.
The possible values for each row or column mode are:
Example: When you call setRowMode( FitToHeight ), columnMode() automatically becomes Variable to accommodate the row mode you've set.
This enumerated type is used by QListBox to indicate how it reacts to selection by the user. It has four values:
In other words, Single is a real single-selection list box, Multi is a real multi-selection list box, Extended is a list box in which users can select multiple items but usually want to select either just one or a range of contiguous items, and NoSelection is for a list box where the user can look but not touch.
Performance is boosted by modifying the widget flags f so that only part of the QListBoxItem children is redrawn. This may be unsuitable for custom QListBoxItem classes, in which case WStaticContents and WRepaintNoErase should be cleared immediately after construction.
See also QWidget::clearWFlags() and Qt::WidgetFlags.
Returns the item height of item i.
See also itemHeight().
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Returns the item height of the first item, item 0.
See also itemHeight().
Returns the maximum item width.
See also maxItemWidth().
See also QListBox::ensureCurrentVisible().
The item that has been changed will become selected.
See also insertItem() and removeItem().
Replaces the item at position index with a new list box text item with text text.
The operation is ignored if index is out of range.
See also insertItem() and removeItem().
Replaces the item at position index with a new list box pixmap item with pixmap pixmap.
The operation is ignored if index is out of range.
See also insertItem() and removeItem().
Replaces the item at position index with a new list box pixmap item with pixmap pixmap and text text.
The operation is ignored if index is out of range.
See also insertItem() and removeItem().
See also removeItem().
Note that a Single selection list box will automatically select an item if it has keyboard focus.
Example: listbox/listbox.cpp.
This signal is emitted when the user clicks any mouse button. If item is non-null, the cursor is on item. If item is null, the mouse cursor isn't on any item.
Note that you must not delete any QListBoxItem objects in slots connected to this signal.
This signal is emitted when the user clicks any mouse button. If item is non-null, the cursor is on item. If item is null, the mouse cursor isn't on any item.
pnt is the position of the mouse cursor in the global coordinate system (QMouseEvent::globalPos()). (If the click's press and release differ by a pixel or two, pnt is the position at release time.)
Note that you must not delete any QListBoxItem objects in slots connected to this signal.
Returns the column layout mode for this list box. See the "columnMode" property for details.
This signal is emitted when the user invokes a context menu with the right mouse button or with special system keys, with item being the item under the mouse cursor or the current item, respectively.
pos is the position for the context menu in the global coordinate system.
Returns the number of items in the list box. See the "count" property for details.
This signal is emitted when the user highlights a new current item. item is the new current list box item.
See also currentItem and currentItem.
Returns the current highlighted item. See the "currentItem" property for details.
Returns the text of the current item. See the "currentText" property for details.
This signal is emitted whenever an item is double-clicked. It's emitted on the second button press, not the second button release. item is the item item on which the user did the double-click. item may be 0.
See also Qt::StringComparisonMode.
Returns the index of the item a point (0, yPos).
See also index() and itemAt().
This signal is emitted when the user highlights a new current item. index is the index of the highlighted item.
See also selected(), currentItem and selectionChanged().
This signal is emitted when the user highlights a new current item and the new item is a string. The argument is the text of the new current item.
See also selected(), currentItem and selectionChanged().
This signal is emitted when the user highlights a new current item. The argument is a pointer to the new current item.
See also selected(), currentItem and selectionChanged().
Using this method is quite inefficient. We suggest to use insertItem() for inserting and sort() afterwards.
Inserts lbi at its sorted position in the list box and returns the position.
All items must be inserted with inSort() to maintain the sorting order. inSort() treats any pixmap (or user-defined type) as lexicographically less than any string.
See also insertItem() and sort().
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Using this method is quite inefficient. We suggest to use insertItem() for inserting and sort() afterwards.
Inserts a new item of text at its sorted position in the list box and returns the position.
All items must be inserted with inSort() to maintain the sorting order. inSort() treats any pixmap (or user-defined type) as lexicographically less than any string.
See also insertItem() and sort().
See also item().
If index is negative or larger than the number of items in the list box, lbi is inserted at the end of the list.
See also insertStrList().
Examples: i18n/mywidget.cpp, listbox/listbox.cpp, listboxcombo/listboxcombo.cpp and tabdialog/tabdialog.cpp.
Inserts the item lbi into the list after the item after.
If after is 0, lbi is inserted at the beginning.
See also insertStrList().
Inserts a new list box text item with the text text into the list at position index.
If index is negative, text is inserted at the end of the list.
See also insertStrList().
Inserts a new list box pixmap item with the pixmap pixmap into the list at position index.
If index is negative, pixmap is inserted at the end of the list.
See also insertStrList().
Inserts a new list box pixmap item with the pixmap pixmap and the text text into the list at position index.
If index is negative, pixmap is inserted at the end of the list.
See also insertStrList().
If index is negative, list is inserted at the end of the list. If index is too large, the operation is ignored.
Warning: This function uses const char * rather than QString, so we recommend against using it. It is provided so that legacy code will continue to work, and so that programs that certainly will not need to handle code outside a single 8-bit locale can use it. See insertStringList() which uses real QStrings.
Warning: This function is never significantly faster than a loop around insertItem().
See also insertItem() and insertStringList().
Inserts the string list list into the list at position index.
If index is negative, list is inserted at the end of the list. If index is too large, the operation is ignored.
Warning: This function uses const char * rather than QString, so we recommend against using it. It is provided so that legacy code will continue to work, and so that programs that certainly will not need to handle code outside a single 8-bit locale can use it. See insertStringList() which uses real QStrings.
Warning: This function is never significantly faster than a loop around insertItem().
See also insertItem() and insertStringList().
Inserts the numStrings strings of the array strings into the list at position index.
If index is negative, insertStrList() inserts strings at the end of the list. If index is too large, the operation is ignored.
Warning: This function uses const char * rather than QString, so we recommend against using it. It is provided so that legacy code will continue to work, and so that programs that certainly will not need to handle code outside a single 8-bit locale can use it. See insertStringList() which uses real QStrings.
Warning: This function is never significantly faster than a loop around insertItem().
See also insertItem() and insertStringList().
If index is negative, list is inserted at the end of the list. If index is too large, the operation is ignored.
Warning: This function is never significantly faster than a loop around insertItem().
See also insertItem() and insertStrList().
Returns TRUE if or not the list box is in Multi selection mode; otherwise returns FALSE. See the "multiSelection" property for details.
Returns TRUE if item i is selected; otherwise returns FALSE.
See also index().
Example: listboxcombo/listboxcombo.cpp.
If index is too large, this function returns 0.
Returns TRUE if item is at least partly visible; otherwise returns FALSE.
Returns the vertical pixel-coordinate in *yPos, of the list box item at position index in the list. Returns FALSE if the item is outside the visible area.
This signal is emitted when the user clicks mouse button button. If item is non-null, the cursor is on item. If item is null, the mouse cursor isn't on any item.
pos is the position of the mouse cursor in the global coordinate system (QMouseEvent::globalPos()). (If the click's press and release differ by a pixel or two, pos is the position at release time.)
Note that you must not delete any QListBoxItem objects in slots connected to this signal.
This signal is emitted when the user presses mouse button button. If item is non-null, the cursor is on item. If item is null, the mouse cursor isn't on any item.
pos is the position of the mouse cursor in the global coordinate system (QMouseEvent::globalPos()).
Note that you must not delete any QListBoxItem objects in slots connected to this signal.
Returns the number of columns.
See also numColumns.
Returns the number of columns in the list box. See the "numColumns" property for details.
Returns the number of visible items. See the "numItemsVisible" property for details.
Returns the number of rows in the list box. See the "numRows" property for details.
Repaints the cell at row, col using painter p.
See also text().
This signal is emitted when the user presses any mouse button. If item is non-null, the cursor is on item. If item is null, the mouse cursor isn't on any item.
Note that you must not delete any QListBoxItem objects in slots connected to this signal.
This signal is emitted when the user presses any mouse button. If item is non-null, the cursor is on item. If item is null, the mouse cursor isn't on any item.
pnt is the position of the mouse cursor in the global coordinate system (QMouseEvent::globalPos()). (If the click's press and release differ by a pixel or two, pnt is the position at release time.)
Note that you must not delete any QListBoxItem objects in slots connected to this signal.
See also mouseButtonPressed(), rightButtonPressed() and clicked().
See also insertItem() and clear().
This signal is emitted when Enter or Return is pressed. The argument is currentItem().
This signal is emitted when the right button is clicked (i.e. when it's released at the same point where it was pressed). The arguments are the relevant QListBoxItem (may be 0) and the point in global coordinates.
This signal is emitted when the right button is pressed. The arguments are the relevant QListBoxItem (may be 0) and the point in global coordinates.
Returns the row layout mode for this list box. See the "rowMode" property for details.
In Single and NoSelection modes, this function only changes the selection status of currentItem().
This signal is emitted when the user double-clicks on an item or presses Enter when an item is highlighted. index is the index of the selected item.
See also highlighted() and selectionChanged().
This signal is emitted when the user double-clicks on an item or presses Enter while an item is highlighted, and the selected item is (or has) a string. The argument is the text of the selected item.
See also highlighted() and selectionChanged().
This signal is emitted when the user double-clicks on an item or presses Enter when an item is highlighted. The argument is a pointer to the new selected item.
See also highlighted() and selectionChanged().
This signal is emitted when the selection set of a list box changes. This signal is emitted in each selection mode. If the user selects five items by drag-selecting, QListBox tries to emit just one selectionChanged() signal so the signal can be connected to computationally expensive slots.
See also selected() and currentItem.
This signal is emitted when the selection in a Single selection list box changes. item is the new selected list box item.
See also selected() and currentItem.
Returns the selection mode of the list box. See the "selectionMode" property for details.
See also topItem.
Sets the column layout mode for this list box. See the "columnMode" property for details.
Sets the column layout mode for this list box to columns. See the "columnMode" property for details.
Sets the current highlighted item to index. See the "currentItem" property for details.
Sets the current item to the QListBoxItem i.
Sets whether or not the list box is in Multi selection mode to multi. See the "multiSelection" property for details.
Sets the row layout mode for this list box. See the "rowMode" property for details.
Sets the row layout mode for this list box to rows. See the "rowMode" property for details.
If the list box is a Single selection list box and select is TRUE, setSelected() calls setCurrentItem().
If the list box is a Single selection list box, select is FALSE, setSelected() calls clearSelection().
See also multiSelection, currentItem, clearSelection() and currentItem.
If select is TRUE the item at position index is selected; otherwise the item is deselected.
Sets the selection mode of the list box. See the "selectionMode" property for details.
Sets the index of an item at the top of the screen to index. See the "topItem" property for details.
Sets whether this list box has variable-height rows. See the "variableHeight" property for details.
Sets whether this list box has variable-width columns. See the "variableWidth" property for details.
To compare the items, the text (QListBoxItem::text()) of the items is used.
Example: listbox/listbox.cpp.
See also QListBox::insertItem().
See also pixmap().
See also multiSelection.
Returns the index of an item at the top of the screen. See the "topItem" property for details.
Returns contentsHeight().
Returns contentsWidth().
Repaints the QListBoxItem i.
Returns TRUE if this list box has variable-height rows; otherwise returns FALSE. See the "variableHeight" property for details.
Returns TRUE if this list box has variable-width columns; otherwise returns FALSE. See the "variableWidth" property for details.
This property holds the column layout mode for this list box.
Set this property's value with setColumnMode() and get this property's value with columnMode().
See also rowMode.
setColumnMode() sets the layout mode and adjusts the number of displayed columns. The row layout mode automatically becomes Variable, unless the column mode is Variable.
See also rowMode.
This property holds the number of items in the list box.
Get this property's value with count().
This property holds the current highlighted item.
When setting this property, the highlighting is moved and the list box scrolled as necessary.
If no item has been highlighted, currentItem() returns -1.
Set this property's value with setCurrentItem() and get this property's value with currentItem().
This property holds the text of the current item.
This is equivalent to text(currentItem()).
Get this property's value with currentText().
This property holds whether or not the list box is in Multi selection mode.
Consider using the QListBox::selectionMode property instead of this property.
When setting this property, Multi selection mode is used if set to TRUE and to Single selection mode if set to FALSE.
When getting this property, TRUE is returned if the list box is in Multi selection mode or Extended selection mode, and FALSE if it is in Single selection mode or NoSelection mode.
See also selectionMode.
Set this property's value with setMultiSelection() and get this property's value with isMultiSelection().
This property holds the number of columns in the list box.
This is normally 1, but can be different if QListBox::columnMode or QListBox::rowMode has been set.
See also columnMode, rowMode and numRows.
Get this property's value with numColumns().
This property holds the number of visible items.
Both partially and entirely visible items are counted.
Get this property's value with numItemsVisible().
This property holds the number of rows in the list box.
This is equal to the number of items in the default single-column layout, but can be different.
See also columnMode, rowMode and numColumns.
Get this property's value with numRows().
This property holds the row layout mode for this list box.
This property is normally Variable.
setRowMode() sets the layout mode and adjusts the number of displayed rows. The column layout mode automatically becomes Variable, unless the row mode is Variable.
See also columnMode.
Set this property's value with setRowMode() and get this property's value with rowMode().
This property holds the selection mode of the list box.
Sets the list box's selection mode, which may be one of Single (the default), Extended, Multi or NoSelection.
See also SelectionMode.
Set this property's value with setSelectionMode() and get this property's value with selectionMode().
This property holds the index of an item at the top of the screen.
When getting this property and the listbox has multiple columns, an arbitrary item is selected and returned.
When setting this property, the list box is scrolled so the item at position index in the list is displayed in the top row of the list box.
Set this property's value with setTopItem() and get this property's value with topItem().
This property holds whether this list box has variable-height rows.
When the list box has variable-height rows (the default), each row is as high as the highest item in that row. When it has same-sized rows, all rows are as high as the highest item in the list box.
See also variableWidth.
Set this property's value with setVariableHeight() and get this property's value with variableHeight().
This property holds whether this list box has variable-width columns.
When the list box has variable-width columns, each column is as wide as the widest item in that column. When it has same-sized columns (the default), all columns are as wide as the widest item in the list box.
See also variableHeight.
Set this property's value with setVariableWidth() and get this property's value with variableWidth().
This file is part of the Qt toolkit. Copyright © 1995-2002 Trolltech. All Rights Reserved.
| Copyright © 2002 Trolltech | Trademarks | Qt version 3.0.5
|