# QListBox Class Reference

The QListBox widget provides a single-column list of items that can be scrolled. More...

`#include <qlistbox.h>`

Inherits QTableView.

List of all member functions.

## Public Members

- QListBox ( QWidget * parent=0, const char * name=0, WFlags f=0 )
- ~QListBox ()
- virtual void setFont ( const QFont & )
- uint count () const
- void insertStrList ( const QStrList *, int index=-1 )
- void insertStrList ( const char **, int numStrings=-1, int index=-1 )
- void insertItem ( const QListBoxItem *, int index=-1 )
- void insertItem ( const char * text, int index=-1 )
- void insertItem ( const QPixmap & pixmap, int index=-1 )
- void inSort ( const QListBoxItem * )
- void inSort ( const char * text )
- void removeItem ( int index )
- void clear ()
- const char* text ( int index ) const
- const QPixmap* pixmap ( int index ) const
- void changeItem ( const QListBoxItem *, int index )
- void changeItem ( const char * text, int index )
- void changeItem ( const QPixmap & pixmap, int index )
- bool autoUpdate () const
- void setAutoUpdate ( bool )
- int numItemsVisible () const
- void setFixedVisibleLines ( int lines )
- int currentItem () const
- void setCurrentItem ( int index )
- void centerCurrentItem ()
- int topItem () const
- void setTopItem ( int index )
- void setBottomItem ( int index )
- bool dragSelect () const
- void setDragSelect ( bool )
- bool autoScroll () const
- void setAutoScroll ( bool )
- bool autoScrollBar () const
- void setAutoScrollBar ( bool )
- bool scrollBar () const
- void setScrollBar ( bool )
- bool autoBottomScrollBar () const
- void setAutoBottomScrollBar ( bool )
- bool bottomScrollBar () const
- void setBottomScrollBar ( bool )
- bool smoothScrolling () const
- void setSmoothScrolling ( bool )
- int itemHeight () const
- int itemHeight ( int index ) const
- long maxItemWidth () const
- long maxItemWidth ()
- bool isMultiSelection () const
- void setMultiSelection ( bool )
- void setSelected ( int, bool )
- bool isSelected ( int ) const
- virtual QSize sizeHint () const

## Public Slots

- void clearSelection ()

## Signals

- void highlighted ( int index )
- void selected ( int index )
- void highlighted ( const char * )
- void selected ( const char * )
- void selectionChanged ()

## Protected Members

- QListBoxItem* item ( int index ) const
- bool itemVisible ( int index )
- virtual int cellHeight ( int index = 0 )
- virtual void paintCell ( QPainter *, int row, int col )
- virtual void mousePressEvent ( QMouseEvent * )
- virtual void mouseReleaseEvent ( QMouseEvent * )
- virtual void mouseDoubleClickEvent ( QMouseEvent * )
- virtual void mouseMoveEvent ( QMouseEvent * )
- virtual void keyPressEvent ( QKeyEvent * e )
- virtual void focusInEvent ( QFocusEvent * e )
- virtual void focusOutEvent ( QFocusEvent * e )
- virtual void resizeEvent ( QResizeEvent * )
- virtual void timerEvent ( QTimerEvent * )
- int findItem ( int yPos ) const
- bool itemYPos ( int index, int * yPos ) const
- void updateItem ( int index, bool clear = TRUE )
- void clearList ()
- void updateCellWidth ()
- void toggleCurrentItem ()

## Detailed Description

The QListBox widget provides a single-column list of items that can be scrolled.

Each item in a QListBox contains a QListBoxItem. One of the items can be the current item. The highlighted() signal is emitted when the user highlights a new current item; selected() is emitted when the user double-clicks on an item or presses return when an item is highlighted.

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

A list box has `StrongFocus` as a default focusPolicy(), i.e. it can get keyboard focus both by tabbing and clicking.

New items may be inserted using either insertItem(), insertStrList() and inSort(). The list box is automatically updated to reflect the change; if you are going to insert a lot of data it may be worthwhile to wrap the insertion in calls to setAutoUpdate():

          listBix->setAutoUpdate( FALSE );
          for( i=1; i< hugeArray->count(); i++ )
              listBox->insertItem( hugeArray[i] );
          listBox->setAutoUpdate( TRUE );
          listBox->repaint();

Each change to insertItem() normally causes a screen update, and for a large change only a few of those updates are really necessary. Be careful to call repaint() when you re-enable updates, so the widget is completely repainted.

By default, vertical and horizontal scroll bars are added and removed as necessary. setAutoScrollBar() can be used to force a specific policy.

If you need to insert other types than texts 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 they are not needed.

See also: QListView, QComboBox, QButtonGroup and GUI Design Handbook: List Box (two sections)

Examples: widgets/widgets.cpp

## Member Function Documentation

### QListBox::QListBox ( QWidget * parent=0, const char * name=0, WFlags f=0 )

Constructs a list box. The arguments are passed directly to the QTableView constructor.

Note that the f argument is not table flags but rather widget flags.

### QListBox::~QListBox ()

Destroys the list box. Deletes all list box items.

### bool QListBox::autoBottomScrollBar () const

Returns TRUE if the list box has an automatic bottom scroll bar.

See also: setAutoBottomScrollBar() and autoScrollBar().

### bool QListBox::autoScroll () const

Returns TRUE if auto-scrolling is enabled, otherwise FALSE.

See also: setAutoScroll and dragSelect().

### bool QListBox::autoScrollBar () const

Returns TRUE if the list box has an automatic (vertical) scroll bar.

See also: setAutoScrollBar() and autoBottomScrollBar().

### bool QListBox::autoUpdate () const

Returns TRUE if the list box updates itself automatically when items are inserted or removed.

The default setting is TRUE.

See also: setAutoUpdate().

### bool QListBox::bottomScrollBar () const

Returns TRUE if the list box has a bottom scroll bar.

See also: setBottomScrollBar(), autoBottomScrollBar() and scrollBar().

### int QListBox::cellHeight ( int index = 0 ) `[virtual protected]`

Returns the height of the item at position index in pixels.

Reimplemented from QTableView.

### void QListBox::centerCurrentItem ()

Scrolls the list box so the current (highlighted) item is centered in the list box.

See also: currentItem() and setTopItem().

### void QListBox::changeItem ( const QListBoxItem * lbi, int index )

Replaces the item at posistion index with lbi. If index is negative or too large, changeItem() does nothing.

See also: insertItem() and removeItem().

### void QListBox::changeItem ( const QPixmap & pixmap, int index )

Replaces the item at position index with pixmap.

The operation is ignored if index is out of range.

See also: insertItem() and removeItem().

### void QListBox::changeItem ( const char * text, int index )

Replaces the item at position index with text.

The operation is ignored if index is out of range.

See also: insertItem() and removeItem().

### void QListBox::clear ()

Deletes all items in the list.

See also: removeItem() and setStrList().

### void QListBox::clearList () `[protected]`

Deletes all items in the list. Protected function that does NOT update the list box.

### void QListBox::clearSelection () `[slot]`

Deselects all items. Note that a single-selection listbox will automatically select its first item if it has keyboard focus.

### uint QListBox::count () const

Returns the number of items in the list box.

### int QListBox::currentItem () const

Returns the index of the current (highlighted) item of the list box, or -1 if no item has been selected.

See also: topItem().

### bool QListBox::dragSelect () const

Returns TRUE if drag-selection is enabled, otherwise FALSE.

See also: setDragSelect() and autoScroll().

### int QListBox::findItem ( int yPos ) const `[protected]`

Returns the index of the list box item at the vertical pixel-coordinate yPos.

See also: itemYPos().

### void QListBox::focusInEvent ( QFocusEvent * ) `[virtual protected]`

Handles focus events. Repaints the current item (if not set, topItem() is made current).

See also: keyPressEvent() and focusOutEvent().

Reimplemented from QWidget.

### void QListBox::focusOutEvent ( QFocusEvent * ) `[virtual protected]`

Handles focus out events. Repaints the current item, if set.

See also: keyPressEvent() and focusOutEvent().

Reimplemented from QWidget.

### void QListBox::highlighted ( const char * ) `[signal]`

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

### void QListBox::highlighted ( int index ) `[signal]`

This signal is emitted when the user highlights a new current item. The argument is the index of the new item, which is already current.

See also: selected(), currentItem() and selectionChanged().

### void QListBox::inSort ( const QListBoxItem * lbi )

Inserts lbi at its sorted position in the list box.

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

### void QListBox::inSort ( const char * text )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

### void QListBox::insertItem ( const QListBoxItem * lbi, int index=-1 )

Inserts the item lbi into the list at index.

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: widgets/widgets.cpp

### void QListBox::insertItem ( const QPixmap & pixmap, int index=-1 )

Inserts pixmap into the list at index.

If index is negative, pixmap is inserted at the end of the list.

See also: insertStrList().

### void QListBox::insertItem ( const char * text, int index=-1 )

Inserts text into the list at index.

If index is negative, text is inserted at the end of the list.

See also: insertStrList().

### void QListBox::insertStrList ( const QStrList * list, int index=-1 )

Inserts the string list list into the list at item index.

If index is negative, list is inserted at the end of the list. If index is too large, the operation is ignored.

See also: insertItem() and inSort().

### void QListBox::insertStrList ( const char ** strings, int numStrings=-1, int index=-1 )

Inserts the numStrings strings of the array strings into the list at itemindex.

If index is negative, insertStrList() inserts strings at the end of the list. If index is too large, the operation is ignored.

See also: insertItem() and inSort().

### bool QListBox::isMultiSelection () const

Returns TRUE if the listbox is in multi-selection mode, and FALSE if it is in single-selection mode.

See also: setMultiSelection().

### bool QListBox::isSelected ( int i ) const

Returns TRUE if item i is selected. Returns FALSE if it is not selected or if there is an error.

### QListBoxItem * QListBox::item ( int index ) const `[protected]`

Returns a pointer to the item at position index.

### int QListBox::itemHeight () const

Returns the standard item height (in pixels), or -1 if the list box has variable item height.

### int QListBox::itemHeight ( int index ) const

Returns the height (in pixels) of item at index.

### bool QListBox::itemVisible ( int index ) `[protected]`

Returns TRUE if the item at position index is at least partly visible.

### bool QListBox::itemYPos ( int index, int * yPos ) const `[protected]`

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.

See also: findItem.

### void QListBox::keyPressEvent ( QKeyEvent * e ) `[virtual protected]`

Handles key press events.

`Up` and `down` arrow keys make the highlighted item move and if necessary scroll the list box.

`Enter` makes the list box emit the selected() signal.

See also: selected() and setCurrentItem().

Reimplemented from QWidget.

### long QListBox::maxItemWidth ()

For binary compatibility.

### long QListBox::maxItemWidth () const

Returns the width in pixels of the widest item.

### void QListBox::mouseDoubleClickEvent ( QMouseEvent * e ) `[virtual protected]`

Handles mouse double click events. Emits the selected() signal for the item that was double-clicked.

Reimplemented from QWidget.

### void QListBox::mouseMoveEvent ( QMouseEvent * e ) `[virtual protected]`

Handles mouse move events. Scrolls the list box if auto-scroll is enabled.

See also: autoScroll().

Reimplemented from QWidget.

### void QListBox::mousePressEvent ( QMouseEvent * e ) `[virtual protected]`

Handles mouse press events. Makes the clicked item the current item.

See also: currentItem().

Reimplemented from QWidget.

### void QListBox::mouseReleaseEvent ( QMouseEvent * e ) `[virtual protected]`

Handles mouse release events.

Reimplemented from QWidget.

### int QListBox::numItemsVisible () const

Returns the number of visible items. This may change at any time since the user may resize the widget.

See also: setFixedVisibleLines().

### void QListBox::paintCell ( QPainter * p, int row, int col ) `[virtual protected]`

Repaints the cell at position row using p. The col argument is ignored, it is present because QTableView is more general. This function has the responsibility of showing focus and highlighting.

See also: QTableView::paintCell().

Reimplemented from QTableView.

### const QPixmap * QListBox::pixmap ( int index ) const

Returns a pointer to the pixmap at position index, or 0 if there is no pixmap there.

See also: text().

### void QListBox::removeItem ( int index )

Removes the item at position index. If index is equal to currentItem(), a new item gets selected and the highlighted() signal is emitted.

See also: insertItem() and clear().

### void QListBox::resizeEvent ( QResizeEvent * e ) `[virtual protected]`

Handles resize events. Updates internal parameters for the new list box size.

Reimplemented from QWidget.

### bool QListBox::scrollBar () const

Returns TRUE if the list box has a (vertical) scroll bar.

See also: setScrollBar(), autoScrollBar() and bottomScrollBar().

### void QListBox::selected ( const char * ) `[signal]`

This signal is emitted when the user double-clicks on an item or presses return 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().

### void QListBox::selected ( int index ) `[signal]`

This signal is emitted when the user double-clicks on an item or presses return when an item is highlighted. The argument is the index of the selected item.

See also: highlighted() and selectionChanged().

### void QListBox::selectionChanged () `[signal]`

This signal is emitted when the selection set of a multiple-choice listbox changes. 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().

### void QListBox::setAutoBottomScrollBar ( bool enable )

Enables an automatic bottom scroll bar if enable is TRUE, or disables it if enable is FALSE.

If it is enabled, then the list box will get a bottom scroll bar if the maximum list box item width exceeds the list box width.

The default setting is TRUE.

See also: autoBottomScrollBar(), setBottomScrollBar() and setAutoScrollBar().

### void QListBox::setAutoScroll ( bool enable )

Sets auto-scrolling if enable is TRUE, or disables it if enable is FALSE.

If auto-scrolling is enabled, the list box will scroll its contents when the user drags the mouse outside (below or above) the list box. Auto-scrolling only works if drag-selection is enabled.

The default setting is TRUE.

See also: autoScroll() and setDragSelect().

### void QListBox::setAutoScrollBar ( bool enable )

Enables an automatic (vertical) scroll bar if enable is TRUE, or disables it if enable is FALSE.

If it is enabled, then the list box will get a (vertical) scroll bar if the list box items exceed the list box height.

The default setting is TRUE.

See also: autoScrollBar(), setScrollBar() and setAutoBottomScrollBar().

### void QListBox::setAutoUpdate ( bool enable )

Specifies whether the list box should update itself automatically when items are inserted or removed.

Auto-update is enabled by default.

If enable is TRUE, the list box will update itself. If enable is FALSE, the list box will not update itself.

Warning: Do not leave the view in this state for a long time (i.e. between events ). If the user interacts with the view when auto-update is off, strange things can happen.

See also: autoUpdate().

### void QListBox::setBottomItem ( int index )

Scrolls the list box so the item at position index in the list becomes the bottom row of the list box.

See also: setTopItem().

### void QListBox::setBottomScrollBar ( bool enable )

Enables a bottom scroll bar if enable is TRUE, or disables it if enable is FALSE.

The default setting is FALSE.

See also: bottomScrollBar(), setAutoBottomScrollBar() and setScrollBar().

### void QListBox::setCurrentItem ( int index )

Sets the highlighted item to the item at position index in the list. The highlighting is moved and the list box scrolled as necessary.

See also: currentItem().

### void QListBox::setDragSelect ( bool enable )

Sets drag-selection if enable is TRUE, or disables it if enable is FALSE.

If drag-selection is enabled, the list box will highlight new items when the user drags the mouse inside the list box.

The default setting is TRUE.

See also: drawSelect() and setAutoScroll().

### void QListBox::setFixedVisibleLines ( int lines )

Sets a fixed height for the widget, so that it shows the given number of lines of text for the current font size.

### void QListBox::setFont ( const QFont & font ) `[virtual]`

Reimplements QWidget::setFont() to update the list box line height and maxItemWidth().

Reimplemented from QWidget.

### void QListBox::setMultiSelection ( bool enable )

Sets the list box to multi-selection mode if enable is TRUE, and to single-selection mode if enable is FALSE.

Single- and multi-selections modes work the same, except that the highlighted() and selected() signals are emitted at different times.

See also: isMultiSelection().

### void QListBox::setScrollBar ( bool enable )

Enables a (vertical) scroll bar if enable is TRUE, or disables it if enable is FALSE.

The default setting is FALSE.

See also: scrollBar(), setAutoScrollBar() and setBottomScrollBar().

### void QListBox::setSelected ( int index, bool select )

Selects the item at position index if select is TRUE, or unselects it if select is FALSE. May also repaint the item.

If the listbox is a single-selection listbox and and select is TRUE, setCurrentItem will be called.

If the listbox is a single-selection listbox and and select is FALSE, clearSelection() will be called if index is the currently selected item.

See also: setMultiSelection(), setCurrentItem(), clearSelection() and currentItem().

### void QListBox::setSmoothScrolling ( bool enable )

Enables smooth list box scrolling if enable is TRUE, or disables it if enable is FALSE.

The default setting is TRUE.

See also: smoothScrolling().

### void QListBox::setTopItem ( int index )

Scrolls the list box so the item at position index in the list becomes the top row of the list box.

See also: topItem() and centerCurrentItem().

### QSize QListBox::sizeHint () const `[virtual]`

Returns a size mased on maxItemWidth() and any value set by setFixedVisibleLines().

Reimplemented from QWidget.

### bool QListBox::smoothScrolling () const

Returns TRUE if smooth list box scrolling is enabled, otherwise FALSE.

See also: setSmoothScrolling().

### const char * QListBox::text ( int index ) const

Returns a pointer to the text at position index, or 0 if there is no text there.

See also: pixmap().

### void QListBox::timerEvent ( QTimerEvent * ) `[virtual protected]`

Handles timer events. Does auto-scrolling.

Reimplemented from QObject.

### void QListBox::toggleCurrentItem () `[protected]`

Toggles the selection status of currentItem() and repaints, if the listbox is a multi-selection listbox.

Does nothing if the listbox is a single-selection listbox.

See also: setMultiSelection().

### int QListBox::topItem () const

Returns index of the item that is on the top line of the list box.

See also: setTopItem() and currentItem().

### void QListBox::updateCellWidth () `[protected]`

Traverses the list and finds an item with the maximum width, and updates the internal list box structures accordingly.

### void QListBox::updateItem ( int index, bool erase = TRUE ) `[protected]`

Repaints the item at position index in the list. Erases the line first if erase is TRUE.

Search the documentation, FAQ, qt-interest archive and more (uses www.troll.no):

This file is part of the Qt toolkit, copyright © 1995-99 Troll Tech, all rights reserved.

It was generated from the following files:

- qlistbox.h: 1998/08/21
- qlistbox.cpp: 1999/02/13