qlistbox.3qt

Linux下的基于X11的图形开发环境。

.BI "void \fBhighlighted\fR ( int index )"
.br
.ti -1c
.BI "void \fBselected\fR ( int index )"
.br
.ti -1c
.BI "void \fBhighlighted\fR ( const QString & )"
.br
.ti -1c
.BI "void \fBselected\fR ( const QString & )"
.br
.ti -1c
.BI "void \fBhighlighted\fR ( QListBoxItem * )"
.br
.ti -1c
.BI "void \fBselected\fR ( QListBoxItem * )"
.br
.ti -1c
.BI "void \fBselectionChanged\fR ()"
.br
.ti -1c
.BI "void \fBselectionChanged\fR ( QListBoxItem * item )"
.br
.ti -1c
.BI "void \fBcurrentChanged\fR ( QListBoxItem * item )"
.br
.ti -1c
.BI "void \fBclicked\fR ( QListBoxItem * item )"
.br
.ti -1c
.BI "void \fBclicked\fR ( QListBoxItem * item, const QPoint & pnt )"
.br
.ti -1c
.BI "void \fBpressed\fR ( QListBoxItem * item )"
.br
.ti -1c
.BI "void \fBpressed\fR ( QListBoxItem * item, const QPoint & pnt )"
.br
.ti -1c
.BI "void \fBdoubleClicked\fR ( QListBoxItem * item )"
.br
.ti -1c
.BI "void \fBreturnPressed\fR ( QListBoxItem * )"
.br
.ti -1c
.BI "void \fBrightButtonClicked\fR ( QListBoxItem *, const QPoint & )"
.br
.ti -1c
.BI "void \fBrightButtonPressed\fR ( QListBoxItem *, const QPoint & )"
.br
.ti -1c
.BI "void \fBmouseButtonPressed\fR ( int button, QListBoxItem * item, const QPoint & pos )"
.br
.ti -1c
.BI "void \fBmouseButtonClicked\fR ( int button, QListBoxItem * item, const QPoint & pos )"
.br
.ti -1c
.BI "void \fBcontextMenuRequested\fR ( QListBoxItem * item, const QPoint & pos )"
.br
.ti -1c
.BI "void \fBonItem\fR ( QListBoxItem * i )"
.br
.ti -1c
.BI "void \fBonViewport\fR ()"
.br
.in -1c
.SS "Properties"
.in +1c
.ti -1c
.BI "LayoutMode \fBcolumnMode\fR - the column layout mode for this list box"
.br
.ti -1c
.BI "uint \fBcount\fR - the number of items in the list box  \fI(read " "only" ")\fR"
.br
.ti -1c
.BI "int \fBcurrentItem\fR - the current highlighted item"
.br
.ti -1c
.BI "QString \fBcurrentText\fR - the text of the current item  \fI(read " "only" ")\fR"
.br
.ti -1c
.BI "bool multiSelection - whether or not the list box is in Multi selection mode  \fI(obsolete)\fR"
.br
.ti -1c
.BI "int \fBnumColumns\fR - the number of columns in the list box  \fI(read " "only" ")\fR"
.br
.ti -1c
.BI "int \fBnumItemsVisible\fR - the number of visible items  \fI(read " "only" ")\fR"
.br
.ti -1c
.BI "int \fBnumRows\fR - the number of rows in the list box  \fI(read " "only" ")\fR"
.br
.ti -1c
.BI "LayoutMode \fBrowMode\fR - the row layout mode for this list box"
.br
.ti -1c
.BI "SelectionMode \fBselectionMode\fR - the selection mode of the list box"
.br
.ti -1c
.BI "int \fBtopItem\fR - the index of an item at the top of the screen"
.br
.ti -1c
.BI "bool \fBvariableHeight\fR - whether this list box has variable-height rows"
.br
.ti -1c
.BI "bool \fBvariableWidth\fR - whether this list box has variable-width columns"
.br
.in -1c
.SS "Protected Members"
.in +1c
.ti -1c
.BI "void \fBupdateItem\fR ( int index )"
.br
.ti -1c
.BI "void \fBupdateItem\fR ( QListBoxItem * i )"
.br
.ti -1c
.BI "int totalWidth () const  \fI(obsolete)\fR"
.br
.ti -1c
.BI "int totalHeight () const  \fI(obsolete)\fR"
.br
.ti -1c
.BI "virtual void \fBpaintCell\fR ( QPainter * p, int row, int col )"
.br
.ti -1c
.BI "void \fBtoggleCurrentItem\fR ()"
.br
.ti -1c
.BI "bool \fBisRubberSelecting\fR () const"
.br
.ti -1c
.BI "void \fBdoLayout\fR () const"
.br
.ti -1c
.BI "bool itemYPos ( int index, int * yPos ) const  \fI(obsolete)\fR"
.br
.ti -1c
.BI "int findItem ( int yPos ) const  \fI(obsolete)\fR"
.br
.in -1c
.SH DESCRIPTION
The QListBox widget provides a list of selectable, read-only items.
.PP
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.
.PP
QListBox will add scroll bars as necessary, but it isn't intended for \fIreally\fR 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. (See QListView and QTable for possible alternatives.)
.PP
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.)
.PP
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().
.PP
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.
.PP
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().
.PP
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.)
.PP
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.
.PP
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 (but QListView and QTable do), or tree hierarchies (but QListView does).
.PP
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.
.PP
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.
.PP
If the user does not select anything, no signals are emitted and currentItem() returns -1.
.PP
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.
.PP
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().
.PP
By default, vertical and horizontal scroll bars are added and removed as necessary. setHScrollBarMode() and setVScrollBarMode() can be used to change this policy.
.PP
If you need to insert types other than strings and pixmaps, you must define new classes which inherit QListBoxItem.
.PP
\fBWarning:\fR The list box assumes ownership of all list box items and will delete them when it does not need them any more.
.PP
.ce 1
.B "[Image Omitted]"
.PP

.ce 1
.B "[Image Omitted]"
.PP
See also QListView, QComboBox, QButtonGroup, GUI Design Handbook: List Box (two sections), and Advanced Widgets.
.SS "Member Type Documentation"
.SH "QListBox::LayoutMode"
This enum type is used to specify how QListBox lays out its rows and columns.
.TP
\fCQListBox::FixedNumber\fR - There is a fixed number of rows (or columns).
.TP
\fCQListBox::FitToWidth\fR - There are as many columns as will fit on-screen.
.TP
\fCQListBox::FitToHeight\fR - There are as many rows as will fit on-screen.
.TP
\fCQListBox::Variable\fR - There are as many rows as are required by the column mode. (Or as many columns as required by the row mode.)
.PP
Example: When you call setRowMode( FitToHeight ), columnMode() automatically becomes Variable to accommodate the row mode you've set.
.SH "QListBox::SelectionMode"
This enumerated type is used by QListBox to indicate how it reacts to selection by the user.
.TP
\fCQListBox::Single\fR - When the user selects an item, any already-selected item becomes unselected and the user cannot unselect the selected item. This means that the user can never clear the selection, even though the selection may be cleared by the application programmer using QListBox::clearSelection().
.TP
\fCQListBox::Multi\fR - When the user selects an item the selection status of that item is toggled and the other items are left alone.
.TP
\fCQListBox::Extended\fR - When the user selects an item the selection is cleared and the new item selected. However, if the user presses the Ctrl key when clicking on an item, the clicked item gets toggled and all other items are left untouched. And if the user presses the Shift key while clicking on an item, all items between the current item and the clicked item get selected or unselected, depending on the state of the clicked item. Also, multiple items can be selected by dragging the mouse while the left mouse button is kept pressed.
.TP
\fCQListBox::NoSelection\fR - Items cannot be selected.
.PP
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.
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QListBox::QListBox ( QWidget * parent = 0, const char * name = 0, WFlags f = 0 )"
Constructs a new empty list box called \fIname\fR and with parent \fIparent\fR.
.PP
Performance is boosted by modifying the widget flags \fIf\fR 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.
.PP
See also QWidget::clearWFlags() and Qt::WidgetFlags.
.SH "QListBox::~QListBox ()"
Destroys the list box. Deletes all list box items.
.SH "bool QListBox::autoBottomScrollBar () const"
Returns TRUE if hScrollBarMode() is Auto; otherwise returns FALSE.
.SH "bool QListBox::autoScrollBar () const"
Returns TRUE if vScrollBarMode() is Auto; otherwise returns FALSE.
.SH "bool QListBox::bottomScrollBar () const"
Returns FALSE if vScrollBarMode() is AlwaysOff; otherwise returns TRUE.
.SH "int QListBox::cellHeight ( int i ) const"
\fBThis function is obsolete.\fR It is provided to keep old source working. We strongly advise against using it in new code.
.PP
Returns the item height of item \fIi\fR.
.PP
See also itemHeight().
.SH "int QListBox::cellHeight () const"
\fBThis function is obsolete.\fR It is provided to keep old source working. We strongly advise against using it in new code.
.PP
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Returns the item height of the first item, item 0.
.PP
See also itemHeight().
.SH "int QListBox::cellWidth () const"
\fBThis function is obsolete.\fR It is provided to keep old source working. We strongly advise against using it in new code.
.PP
Returns the maximum item width.
.PP
See also maxItemWidth().
.SH "void QListBox::centerCurrentItem ()"
If there is a current item, the list box is scrolled so that this item is displayed centered.
.PP
See also QListBox::ensureCurrentVisible().
.SH "void QListBox::changeItem ( const QListBoxItem * lbi, int index )"
Replaces the item at position \fIindex\fR with \fIlbi\fR. If \fIindex\fR is negative or too large, changeItem() does nothing.
.PP
The item that has been changed will become selected.
.PP
See also insertItem() and removeItem().
.SH "void QListBox::changeItem ( const QString & text, int index )"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Replaces the item at position \fIindex\fR with a new list box text item with text \fItext\fR.
.PP
The operation is ignored if \fIindex\fR is out of range.
.PP
See also insertItem() and removeItem().
.SH "void QListBox::changeItem ( const QPixmap & pixmap, int index )"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Replaces the item at position \fIindex\fR with a new list box pixmap item with pixmap \fIpixmap\fR.
.PP
The operation is ignored if \fIindex\fR is out of range.
.PP
See also insertItem() and removeItem().
.SH "void QListBox::changeItem ( const QPixmap & pixmap, const QString & text, int index )"