|  | Home · Overviews · Examples

# QListWidget Class Reference
[com.trolltech.qt.gui module]

The `QListWidget` class provides an item-based list widget. More...

Inherits `QListView`.

## Detailed Description

The `QListWidget` class provides an item-based list widget.

`QListWidget` is a convenience class that provides a list view similar to the one supplied by `QListView`, but with a classic item-based interface for adding and removing items. `QListWidget` uses an internal model to manage each `QListWidgetItem` in the list.

For a more flexible list view widget, use the `QListView` class with a standard model.

List widgets are constructed in the same way as other widgets:

            QListWidget *listWidget = new QListWidget(this);

The `selectionMode` of a list widget determines how many of the items in the list can be selected at the same time, and whether complex selections of items can be created. This can be set with the `setSelectionMode` function.

There are two ways to add items to the list: they can be constructed with the list widget as their parent widget, or they can be constructed with no parent widget and added to the list later. If a list widget already exists when the items are constructed, the first method is easier to use:

            new QListWidgetItem(tr("Oak"), listWidget);
            new QListWidgetItem(tr("Fir"), listWidget);
            new QListWidgetItem(tr("Pine"), listWidget);

If you need to insert a new item into the list at a particular position, it is more required to construct the item without a parent widget and use the `insertItem` function to place it within the list. The list widget will take ownership of the item.

            QListWidgetItem *newItem = new QListWidgetItem;
            newItem->setText(itemText);
            listWidget->insertItem(row, newItem);

For multiple items, `insertItems` can be used instead. The number of items in the list is found with the `count` function. To remove items from the list, use `takeItem`.

The current item in the list can be found with `currentItem`, and changed with `setCurrentItem`. The user can also change the current item by navigating with the keyboard or clicking on a different item. When the current item changes, the `currentItemChanged` signal is emitted with the new current item and the item that was previously current.

A Windows XP style list widget. | A Macintosh style list widget. | A Plastique style list widget.

See also `QListWidgetItem`, `QListView`, `QTreeView`, Model/View Programming, and Config Dialog Example.