QListWidget Class

The QListWidget class provides a list of items, one on each row. More…

List of all members, including inherited members

Public Functions

Public Slots

Signals

Reimplemented Protected Functions

Detailed Description

A list shows its items as rows of text, and the user selects with the mouse or the keys. It scrolls when there are more rows than fit. Add items with addItem() and read the choice from currentItem(), or connect to the signals:

QListWidget *list = new QListWidget(window);
list->addItems({"Inbox", "Drafts", "Sent", "Archive"});
list->setCurrentRow(0);
connect(list, &QListWidget::currentTextChanged, [](const QString &text) { qDebug() << text; });

The list allows one selected item. Set the selection mode with setSelectionMode(): with MultiSelection a click toggles an item, and with ExtendedSelection the Control and Shift keys add items and ranges, as in other applications. The arrow keys, Page Up, Page Down, Home and End move the current item, and typing a letter goes to the next item that starts with it.

A list with a selected item, an item that is current, a colored item, one that is disabled, and a tool tip.

See also QListWidgetItem, QAbstractItemView and QComboBox.

Differences from Qt

Member Function Documentation

[explicit] QListWidget::QListWidget(QWidget *parent = nullptr)

Constructs an empty list with the given parent.

[override] QListWidget::~QListWidget()

Destroys the list, and the items in it.

void QListWidget::addItem(QListWidgetItem *item)

Adds item at the end of the list, which takes it over.

See also insertItem().

void QListWidget::addItem(const QString &text)

This is an overloaded function.

Adds an item with the given text at the end of the list.

void QListWidget::addItems(const QStringList &labels)

Adds an item for each of the labels at the end of the list.

[override, protected] void QListWidget::changeEvent(QEvent *event)

Reimplements QAbstractItemView::changeEvent().

[slot] void QListWidget::clear()

Removes and deletes every item.

int QListWidget::count() const

Returns the number of items.

QListWidgetItem * QListWidget::currentItem() const

Returns the current item, or nullptr if there is none.

See also setCurrentItem() and currentRow().

[signal] void QListWidget::currentItemChanged(QListWidgetItem *current, QListWidgetItem *previous)

This signal is emitted when the current item changes from previous to current, either of which may be nullptr.

int QListWidget::currentRow() const

Returns the row of the current item, or -1 if there is none.

See also setCurrentRow().

[signal] void QListWidget::currentRowChanged(int currentRow)

This signal is emitted when the current row changes to currentRow, or -1 if there is none.

[signal] void QListWidget::currentTextChanged(const QString &currentText)

This signal is emitted when the current item changes, with the currentText of the new one, which is empty if there is none.

[override, protected] void QListWidget::focusInEvent(QFocusEvent *event)

Reimplements QAbstractItemView::focusInEvent().

[override, protected] void QListWidget::focusOutEvent(QFocusEvent *event)

Reimplements QAbstractItemView::focusOutEvent().

void QListWidget::insertItem(int row, QListWidgetItem *item)

Inserts item at row, which is brought into the range 0 to count(); the items from row on move down. An item that is in another list or in this one moves.

See also addItem() and takeItem().

void QListWidget::insertItem(int row, const QString &text)

This is an overloaded function.

Inserts an item with the given text at row.

void QListWidget::insertItems(int row, const QStringList &labels)

Inserts an item for each of the labels at row.

QListWidgetItem * QListWidget::item(int row) const

Returns the item at row, or nullptr if there is none.

See also row().

[signal] void QListWidget::itemActivated(QListWidgetItem *item)

This signal is emitted when the user activates item: double-clicks it, or presses Return or Enter while it is the current item.

QListWidgetItem * QListWidget::itemAt(const QPoint &pos) const

Returns the item at pos, a position in the viewport, or nullptr if there is none.

See also visualItemRect().

QListWidgetItem * QListWidget::itemAt(int x, int y) const

This is an overloaded function.

Returns the item at (x, y) in the viewport.

[signal] void QListWidget::itemClicked(QListWidgetItem *item)

This signal is emitted when the user clicks item.

[signal] void QListWidget::itemDoubleClicked(QListWidgetItem *item)

This signal is emitted when the user double-clicks item.

[signal] void QListWidget::itemSelectionChanged()

This signal is emitted when the selection changes.

[override, protected] void QListWidget::keyPressEvent(QKeyEvent *event)

Reimplements QAbstractItemView::keyPressEvent().

The arrow keys, Page Up, Page Down, Home and End move the current item, skipping items that are not enabled; Space selects it, or toggles it in a list with MultiSelection or with Control in an ExtendedSelection list; Control+A selects all; Return and Enter activate it, and a letter goes to the next item that starts with it.

[override, protected] void QListWidget::mouseDoubleClickEvent(QMouseEvent *event)

Reimplements QAbstractItemView::mouseDoubleClickEvent().

[override, protected] void QListWidget::mousePressEvent(QMouseEvent *event)

Reimplements QAbstractItemView::mousePressEvent().

[override, protected] void QListWidget::mouseReleaseEvent(QMouseEvent *event)

Reimplements QAbstractItemView::mouseReleaseEvent().

[override, protected] void QListWidget::paintEvent(QPaintEvent *event)

Reimplements QAbstractItemView::paintEvent().

[override, protected] void QListWidget::resizeEvent(QResizeEvent *event)

Reimplements QAbstractItemView::resizeEvent().

int QListWidget::row(const QListWidgetItem *item) const

Returns the row of item, or -1 if it is not in this list.

See also item().

int QListWidget::rowHeight() const

Returns the height of every row: that of a line of text in the font of the list.

[override, protected] void QListWidget::scrollContentsBy(int dx, int dy)

Reimplements QAbstractItemView::scrollContentsBy().

void QListWidget::scrollToItem(const QListWidgetItem *item)

Scrolls the list so that item is in view. Does nothing if item is not in this list.

See also setCurrentItem().

[slot] void QListWidget::selectAll()

Selects all the items that can be selected, if the selection mode allows more than one selected item.

QList<QListWidgetItem *> QListWidget::selectedItems() const

Returns the selected items, in the order of the list.

void QListWidget::setCurrentItem(QListWidgetItem *item)

Makes item the current item, which selects it if the list allows that, and scrolls it into view. Does nothing if item is not in this list, or the user cannot make it current.

See also currentItem().

[slot] void QListWidget::setCurrentRow(int row)

Makes the item at row the current item, which selects it if the list allows that, and scrolls it into view. Does nothing if there is no such row, or the user cannot make it current.

See also currentRow().

[override, protected] void QListWidget::showEvent(QShowEvent *event)

Reimplements QAbstractItemView::showEvent().

void QListWidget::sortItems(Qt::SortOrder order = Qt::AscendingOrder)

Sorts the items by their text: from the smallest to the largest if order is Qt::AscendingOrder, otherwise the other way. Equal items keep their order. The current item stays the current item.

See also insertItem().

QListWidgetItem * QListWidget::takeItem(int row)

Removes the item at row from the list and returns it; the caller owns it. Returns nullptr if there is no such row. If it was the current item, the one that takes its place is.

See also insertItem().

[override, protected] bool QListWidget::viewportEvent(QEvent *event)

Reimplements QAbstractItemView::viewportEvent().

QRect QListWidget::visualItemRect(const QListWidgetItem *item) const

Returns the rectangle of item in the viewport, whether it is in view or not. It is empty if item is not in this list.

See also itemAt().