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

#include <qlistwidget.h>

Inheritance diagram for QListWidget:

Collaboration diagram for QListWidget:

Public Slots
void	scrollToItem (const QListWidgetItem *item, QAbstractItemView::ScrollHint hint=EnsureVisible)
	Scrolls the view if necessary to ensure that the item is visible.

void	clear ()
	Removes all items and selections in the view.

Public Slots inherited from QAbstractItemView
virtual void	reset ()
	Reset the internal state of the view.

virtual void	setRootIndex (const QModelIndex &index)
	Sets the root item to the item at the given index.

virtual void	doItemsLayout ()

virtual void	selectAll ()
	Selects all items in the view.

void	edit (const QModelIndex &index)
	Starts editing the item corresponding to the given index if it is editable.

void	clearSelection ()
	Deselects all selected items.

void	setCurrentIndex (const QModelIndex &index)
	Sets the current item to be the item at index.

void	scrollToTop ()

void	scrollToBottom ()

void	update (const QModelIndex &index)

Signals
void	itemPressed (QListWidgetItem *item)
	This signal is emitted with the specified item when a mouse button is pressed on an item in the widget.

void	itemClicked (QListWidgetItem *item)
	This signal is emitted with the specified item when a mouse button is clicked on an item in the widget.

void	itemDoubleClicked (QListWidgetItem *item)
	This signal is emitted with the specified item when a mouse button is double clicked on an item in the widget.

void	itemActivated (QListWidgetItem *item)
	This signal is emitted when the item is activated.

void	itemEntered (QListWidgetItem *item)
	This signal is emitted when the mouse cursor enters an item.

void	itemChanged (QListWidgetItem *item)
	This signal is emitted whenever the data of item has changed.

void	currentItemChanged (QListWidgetItem current, QListWidgetItem previous)
	This signal is emitted whenever the current item changes.

void	currentTextChanged (const QString &currentText)
	This signal is emitted whenever the current item changes.

void	currentRowChanged (int currentRow)
	This signal is emitted whenever the current item changes.

void	itemSelectionChanged ()
	This signal is emitted whenever the selection changes.

Signals inherited from QListView
void	indexesMoved (const QModelIndexList &indexes)

Signals inherited from QAbstractItemView
void	pressed (const QModelIndex &index)
	This signal is emitted when a mouse button is pressed.

void	clicked (const QModelIndex &index)
	This signal is emitted when a mouse button is left-clicked.

void	doubleClicked (const QModelIndex &index)
	This signal is emitted when a mouse button is double-clicked.

void	activated (const QModelIndex &index)
	This signal is emitted when the item specified by index is activated by the user.

void	entered (const QModelIndex &index)
	This signal is emitted when the mouse cursor enters the item specified by index.

void	viewportEntered ()
	This signal is emitted when the mouse cursor enters the viewport.

void	iconSizeChanged (const QSize &size)

Public Member Functions
	QListWidget (QWidget *parent=nullptr)
	Constructs an empty QListWidget with the given parent.

	~QListWidget ()
	Destroys the list widget and all its items.

void	setSelectionModel (QItemSelectionModel *selectionModel) override
	\reimp

QListWidgetItem *	item (int row) const
	Returns the item that occupies the given row in the list if one has been set; otherwise returns \nullptr.

int	row (const QListWidgetItem *item) const
	Returns the row containing the given item.

void	insertItem (int row, QListWidgetItem *item)
	Inserts the item at the position in the list given by row.

void	insertItem (int row, const QString &label)
	Inserts an item with the text label in the list widget at the position given by row.

void	insertItems (int row, const QStringList &labels)
	Inserts items from the list of labels into the list, starting at the given row.

void	addItem (const QString &label)
	Inserts an item with the text label at the end of the list widget.

void	addItem (QListWidgetItem *item)
	Inserts the item at the end of the list widget.

void	addItems (const QStringList &labels)
	Inserts items with the text labels at the end of the list widget.

QListWidgetItem *	takeItem (int row)
	Removes and returns the item from the given row in the list widget; otherwise returns \nullptr.

int	count () const

QListWidgetItem *	currentItem () const
	Returns the current item.

void	setCurrentItem (QListWidgetItem *item)
	Sets the current item to item.

void	setCurrentItem (QListWidgetItem *item, QItemSelectionModel::SelectionFlags command)

int	currentRow () const

void	setCurrentRow (int row)

void	setCurrentRow (int row, QItemSelectionModel::SelectionFlags command)

QListWidgetItem *	itemAt (const QPoint &p) const
	Returns a pointer to the item at the coordinates p.

QListWidgetItem *	itemAt (int x, int y) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Returns a pointer to the item at the coordinates (x, y).

QRect	visualItemRect (const QListWidgetItem *item) const
	Returns the rectangle on the viewport occupied by the item at item.

void	sortItems (Qt::SortOrder order=Qt::AscendingOrder)
	Sorts all the items in the list widget according to the specified order.

void	setSortingEnabled (bool enable)

bool	isSortingEnabled () const

void	editItem (QListWidgetItem *item)
	Starts editing the item if it is editable.

void	openPersistentEditor (QListWidgetItem *item)
	Opens an editor for the given item.

void	closePersistentEditor (QListWidgetItem *item)
	Closes the persistent editor for the given item.

bool	isPersistentEditorOpen (QListWidgetItem *item) const

QWidget *	itemWidget (QListWidgetItem *item) const

void	setItemWidget (QListWidgetItem item, QWidget widget)

void	removeItemWidget (QListWidgetItem *item)

QList< QListWidgetItem * >	selectedItems () const
	Returns a list of all selected items in the list widget.

QList< QListWidgetItem * >	findItems (const QString &text, Qt::MatchFlags flags) const
	Finds items with the text that matches the string text using the given flags.

QList< QListWidgetItem * >	items (const QMimeData *data) const
	Returns a list of pointers to the items contained in the data object.

QModelIndex	indexFromItem (const QListWidgetItem *item) const
	Returns the QModelIndex associated with the given item.

QListWidgetItem *	itemFromIndex (const QModelIndex &index) const
	Returns a pointer to the QListWidgetItem associated with the given index.

bool	isPersistentEditorOpen (const QModelIndex &index) const

Public Member Functions inherited from QListView
	QListView (QWidget *parent=nullptr)
	Creates a new QListView with the given parent to view a model.

	~QListView ()
	Destroys the view.

void	setMovement (Movement movement)

Movement	movement () const

void	setFlow (Flow flow)

Flow	flow () const

void	setWrapping (bool enable)

bool	isWrapping () const

void	setResizeMode (ResizeMode mode)

ResizeMode	resizeMode () const

void	setLayoutMode (LayoutMode mode)

LayoutMode	layoutMode () const

void	setSpacing (int space)

int	spacing () const

void	setBatchSize (int batchSize)

int	batchSize () const

void	setGridSize (const QSize &size)

QSize	gridSize () const

void	setViewMode (ViewMode mode)

ViewMode	viewMode () const

void	clearPropertyFlags ()
	Clears the QListView-specific property flags.

bool	isRowHidden (int row) const
	Returns `true` if the row is hidden; otherwise returns `false`.

void	setRowHidden (int row, bool hide)
	If hide is true, the given row will be hidden; otherwise the row will be shown.

void	setModelColumn (int column)

int	modelColumn () const

void	setUniformItemSizes (bool enable)

bool	uniformItemSizes () const

void	setWordWrap (bool on)

bool	wordWrap () const

void	setSelectionRectVisible (bool show)

bool	isSelectionRectVisible () const

void	setItemAlignment (Qt::Alignment alignment)

Qt::Alignment	itemAlignment () const

QRect	visualRect (const QModelIndex &index) const override
	\reimp

void	scrollTo (const QModelIndex &index, ScrollHint hint=EnsureVisible) override
	\reimp

QModelIndex	indexAt (const QPoint &p) const override
	\reimp

void	doItemsLayout () override

void	reset () override

void	setRootIndex (const QModelIndex &index) override
	\reimp

Public Member Functions inherited from QAbstractItemView
	QAbstractItemView (QWidget *parent=nullptr)
	Constructs an abstract item view with the given parent.

	~QAbstractItemView ()
	Destroys the view.

virtual void	setModel (QAbstractItemModel *model)
	Sets the model for the view to present.

QAbstractItemModel *	model () const
	Returns the model that this view is presenting.

virtual void	setSelectionModel (QItemSelectionModel *selectionModel)
	Sets the current selection model to the given selectionModel.

QItemSelectionModel *	selectionModel () const
	Returns the current selection model.

void	setItemDelegate (QAbstractItemDelegate *delegate)
	Sets the item delegate for this view and its model to delegate.

QAbstractItemDelegate *	itemDelegate () const
	Returns the item delegate used by this view and model.

void	setSelectionMode (QAbstractItemView::SelectionMode mode)

QAbstractItemView::SelectionMode	selectionMode () const

void	setSelectionBehavior (QAbstractItemView::SelectionBehavior behavior)

QAbstractItemView::SelectionBehavior	selectionBehavior () const

QModelIndex	currentIndex () const
	Returns the model index of the current item.

QModelIndex	rootIndex () const
	Returns the model index of the model's root item.

void	setEditTriggers (EditTriggers triggers)

EditTriggers	editTriggers () const

void	setVerticalScrollMode (ScrollMode mode)

ScrollMode	verticalScrollMode () const

void	resetVerticalScrollMode ()

void	setHorizontalScrollMode (ScrollMode mode)

ScrollMode	horizontalScrollMode () const

void	resetHorizontalScrollMode ()

void	setAutoScroll (bool enable)

bool	hasAutoScroll () const

void	setAutoScrollMargin (int margin)

int	autoScrollMargin () const

void	setTabKeyNavigation (bool enable)

bool	tabKeyNavigation () const

void	setAlternatingRowColors (bool enable)

bool	alternatingRowColors () const

void	setIconSize (const QSize &size)

QSize	iconSize () const

void	setTextElideMode (Qt::TextElideMode mode)

Qt::TextElideMode	textElideMode () const

virtual void	keyboardSearch (const QString &search)
	Moves to and selects the item best matching the string search.

virtual QRect	visualRect (const QModelIndex &index) const =0
	Returns the rectangle on the viewport occupied by the item at index.

virtual void	scrollTo (const QModelIndex &index, ScrollHint hint=EnsureVisible)=0
	Scrolls the view if necessary to ensure that the item at index is visible.

virtual QModelIndex	indexAt (const QPoint &point) const =0
	Returns the model index of the item at the viewport coordinates point.

QSize	sizeHintForIndex (const QModelIndex &index) const
	Returns the size hint for the item with the specified index or an invalid size for invalid indexes.

virtual int	sizeHintForRow (int row) const
	Returns the height size hint for the specified row or -1 if there is no model.

virtual int	sizeHintForColumn (int column) const
	Returns the width size hint for the specified column or -1 if there is no model.

void	openPersistentEditor (const QModelIndex &index)
	Opens a persistent editor on the item at the given index.

void	closePersistentEditor (const QModelIndex &index)
	Closes the persistent editor for the item at the given index.

bool	isPersistentEditorOpen (const QModelIndex &index) const

void	setIndexWidget (const QModelIndex &index, QWidget *widget)

QWidget *	indexWidget (const QModelIndex &index) const

void	setItemDelegateForRow (int row, QAbstractItemDelegate *delegate)

QAbstractItemDelegate *	itemDelegateForRow (int row) const

void	setItemDelegateForColumn (int column, QAbstractItemDelegate *delegate)

QAbstractItemDelegate *	itemDelegateForColumn (int column) const

virtual QAbstractItemDelegate *	itemDelegateForIndex (const QModelIndex &index) const

virtual QVariant	inputMethodQuery (Qt::InputMethodQuery query) const override
	\reimp

Protected Member Functions
bool	event (QEvent *e) override
	\reimp

virtual QStringList	mimeTypes () const
	Returns a list of MIME types that can be used to describe a list of listwidget items.

virtual QMimeData *	mimeData (const QList< QListWidgetItem * > &items) const
	Returns an object that contains a serialized description of the specified items.

Protected Member Functions inherited from QListView
	QListView (QListViewPrivate &, QWidget *parent=nullptr)

bool	event (QEvent *e) override
	\reimp

void	scrollContentsBy (int dx, int dy) override
	\reimp

void	resizeContents (int width, int height)

QSize	contentsSize () const

void	dataChanged (const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList< int > &roles=QList< int >()) override
	\reimp

void	rowsInserted (const QModelIndex &parent, int start, int end) override
	\reimp

void	rowsAboutToBeRemoved (const QModelIndex &parent, int start, int end) override
	\reimp

void	mouseMoveEvent (QMouseEvent *e) override
	\reimp

void	mouseReleaseEvent (QMouseEvent *e) override
	\reimp

void	timerEvent (QTimerEvent *e) override
	\reimp

void	resizeEvent (QResizeEvent *e) override
	\reimp

void	initViewItemOption (QStyleOptionViewItem *option) const override
	\reimp

void	paintEvent (QPaintEvent *e) override
	\reimp

int	horizontalOffset () const override
	\reimp

int	verticalOffset () const override
	\reimp

QModelIndex	moveCursor (CursorAction cursorAction, Qt::KeyboardModifiers modifiers) override
	\reimp

QRect	rectForIndex (const QModelIndex &index) const
	Returns the rectangle of the item at position index in the model.

void	setPositionForIndex (const QPoint &position, const QModelIndex &index)

void	setSelection (const QRect &rect, QItemSelectionModel::SelectionFlags command) override
	\reimp

QRegion	visualRegionForSelection (const QItemSelection &selection) const override
	\reimp

QModelIndexList	selectedIndexes () const override
	\reimp

void	updateGeometries () override
	\reimp

bool	isIndexHidden (const QModelIndex &index) const override
	\reimp

void	selectionChanged (const QItemSelection &selected, const QItemSelection &deselected) override
	\reimp

void	currentChanged (const QModelIndex &current, const QModelIndex &previous) override
	\reimp

QSize	viewportSizeHint () const override

Protected Member Functions inherited from QAbstractItemView
	QAbstractItemView (QAbstractItemViewPrivate &, QWidget *parent=nullptr)

virtual QModelIndex	moveCursor (CursorAction cursorAction, Qt::KeyboardModifiers modifiers)=0
	Returns a QModelIndex object pointing to the next object in the view, based on the given cursorAction and keyboard modifiers specified by modifiers.

virtual int	horizontalOffset () const =0
	Returns the horizontal offset of the view.

virtual int	verticalOffset () const =0
	Returns the vertical offset of the view.

virtual bool	isIndexHidden (const QModelIndex &index) const =0
	Returns `true` if the item referred to by the given index is hidden in the view, otherwise returns `false`.

virtual void	setSelection (const QRect &rect, QItemSelectionModel::SelectionFlags command)=0
	Applies the selection flags to the items in or touched by the rectangle, rect.

virtual QRegion	visualRegionForSelection (const QItemSelection &selection) const =0
	Returns the region from the viewport of the items in the given selection.

virtual QModelIndexList	selectedIndexes () const
	This convenience function returns a list of all selected and non-hidden item indexes in the view.

virtual bool	edit (const QModelIndex &index, EditTrigger trigger, QEvent *event)
	Starts editing the item at index, creating an editor if necessary, and returns `true` if the view's \l{State} is now EditingState; otherwise returns `false`.

virtual QItemSelectionModel::SelectionFlags	selectionCommand (const QModelIndex &index, const QEvent *event=nullptr) const
	Returns the SelectionFlags to be used when updating a selection model for the specified index.

virtual void	initViewItemOption (QStyleOptionViewItem *option) const

State	state () const
	Returns the item view's state.

void	setState (State state)
	Sets the item view's state to the given state.

void	scheduleDelayedItemsLayout ()
	Schedules a layout of the items in the view to be executed when the event processing starts.

void	executeDelayedItemsLayout ()
	Executes the scheduled layouts without waiting for the event processing to begin.

void	setDirtyRegion (const QRegion &region)

void	scrollDirtyRegion (int dx, int dy)
	Prepares the view for scrolling by ({dx},{dy}) pixels by moving the dirty regions in the opposite direction.

QPoint	dirtyRegionOffset () const
	Returns the offset of the dirty regions in the view.

void	startAutoScroll ()

void	stopAutoScroll ()

void	doAutoScroll ()

bool	focusNextPrevChild (bool next) override
	\reimp

bool	event (QEvent *event) override
	\reimp

bool	viewportEvent (QEvent *event) override
	This function is used to handle tool tips, and What's This? mode, if the given event is a QEvent::ToolTip,or a QEvent::WhatsThis.

void	mousePressEvent (QMouseEvent *event) override
	This function is called with the given event when a mouse button is pressed while the cursor is inside the widget.

void	mouseMoveEvent (QMouseEvent *event) override
	This function is called with the given event when a mouse move event is sent to the widget.

void	mouseReleaseEvent (QMouseEvent *event) override
	This function is called with the given event when a mouse button is released, after a mouse press event on the widget.

void	mouseDoubleClickEvent (QMouseEvent *event) override
	This function is called with the given event when a mouse button is double clicked inside the widget.

void	focusInEvent (QFocusEvent *event) override
	This function is called with the given event when the widget obtains the focus.

void	focusOutEvent (QFocusEvent *event) override
	This function is called with the given event when the widget loses the focus.

void	keyPressEvent (QKeyEvent *event) override
	This function is called with the given event when a key event is sent to the widget.

void	resizeEvent (QResizeEvent *event) override
	This function is called with the given event when a resize event is sent to the widget.

void	timerEvent (QTimerEvent *event) override
	This function is called with the given event when a timer event is sent to the widget.

void	inputMethodEvent (QInputMethodEvent *event) override
	\reimp

bool	eventFilter (QObject object, QEvent event) override
	\reimp

QSize	viewportSizeHint () const override

Properties
int	count
	the number of items in the list including any hidden items.

int	currentRow
	the row of the current item.

bool	sortingEnabled
	whether sorting is enabled

Properties inherited from QListView
Movement	movement
	whether the items can be moved freely, are snapped to a grid, or cannot be moved at all.

Flow	flow
	which direction the items layout should flow.

bool	isWrapping
	whether the items layout should wrap.

ResizeMode	resizeMode
	whether the items are laid out again when the view is resized.

LayoutMode	layoutMode
	determines whether the layout of items should happen immediately or be delayed.

int	spacing
	the space around the items in the layout

QSize	gridSize
	the size of the layout grid

ViewMode	viewMode
	the view mode of the QListView.

int	modelColumn
	the column in the model that is visible

bool	uniformItemSizes
	whether all items in the listview have the same size

int	batchSize
	the number of items laid out in each batch if \l layoutMode is set to \l Batched

bool	wordWrap
	the item text word-wrapping policy

bool	selectionRectVisible
	if the selection rectangle should be visible

Qt::Alignment	itemAlignment
	the alignment of each item in its cell

Properties inherited from QAbstractItemView
bool	autoScroll
	whether autoscrolling in drag move events is enabled

int	autoScrollMargin
	the size of the area when auto scrolling is triggered

EditTriggers	editTriggers
	which actions will initiate item editing

bool	tabKeyNavigation
	whether item navigation with tab and backtab is enabled.

bool	alternatingRowColors
	whether to draw the background using alternating colors

SelectionMode	selectionMode
	which selection mode the view operates in

SelectionBehavior	selectionBehavior
	which selection behavior the view uses

QSize	iconSize
	the size of items' icons

Qt::TextElideMode	textElideMode
	the position of the "..." in elided text.

ScrollMode	verticalScrollMode
	how the view scrolls its contents in the vertical direction

ScrollMode	horizontalScrollMode
	how the view scrolls its contents in the horizontal direction

Private Member Functions
void	setModel (QAbstractItemModel *model) override

Friends
class	QListWidgetItem

class	QListModel

Additional Inherited Members
Public Types inherited from QListView
enum	Movement { Static , Free , Snap }
	\value Static The items cannot be moved by the user. More...

enum	Flow { LeftToRight , TopToBottom }
	\value LeftToRight The items are laid out in the view from the left to the right. More...

enum	ResizeMode { Fixed , Adjust }
	\value Fixed The items will only be laid out the first time the view is shown. More...

enum	LayoutMode { SinglePass , Batched }
	\value SinglePass The items are laid out all at once. More...

enum	ViewMode { ListMode , IconMode }
	\value ListMode The items are laid out using TopToBottom flow, with Small size and Static movement \value IconMode The items are laid out using LeftToRight flow, with Large size and Free movement More...

Public Types inherited from QAbstractItemView
enum	SelectionMode { NoSelection , SingleSelection , MultiSelection , ExtendedSelection , ContiguousSelection }
	This enum indicates how the view responds to user selections: More...

enum	SelectionBehavior { SelectItems , SelectRows , SelectColumns }
	\value SelectItems Selecting single items. More...

enum	ScrollHint { EnsureVisible , PositionAtTop , PositionAtBottom , PositionAtCenter }
	\value EnsureVisible Scroll to ensure that the item is visible. More...

enum	EditTrigger { NoEditTriggers = 0 , CurrentChanged = 1 , DoubleClicked = 2 , SelectedClicked = 4 , EditKeyPressed = 8 , AnyKeyPressed = 16 , AllEditTriggers = 31 }
	This enum describes actions which will initiate item editing. More...

enum	ScrollMode { ScrollPerItem , ScrollPerPixel }

Protected Types inherited from QAbstractItemView
enum	CursorAction { MoveUp , MoveDown , MoveLeft , MoveRight , MoveHome , MoveEnd , MovePageUp , MovePageDown , MoveNext , MovePrevious }
	This enum describes the different ways to navigate between items,. More...

enum	State { NoState , DraggingState , DragSelectingState , EditingState , ExpandingState , CollapsingState , AnimatingState }
	Describes the different states the view can be in. More...

Protected Slots inherited from QAbstractItemView
virtual void	dataChanged (const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList< int > &roles=QList< int >())
	This slot is called when items with the given roles are changed in the model.

virtual void	rowsInserted (const QModelIndex &parent, int start, int end)
	This slot is called when rows are inserted.

virtual void	rowsAboutToBeRemoved (const QModelIndex &parent, int start, int end)
	This slot is called when rows are about to be removed.

virtual void	selectionChanged (const QItemSelection &selected, const QItemSelection &deselected)
	This slot is called when the selection is changed.

virtual void	currentChanged (const QModelIndex &current, const QModelIndex &previous)
	This slot is called when a new item becomes the current item.

virtual void	updateEditorData ()

virtual void	updateEditorGeometries ()

virtual void	updateGeometries ()

virtual void	verticalScrollbarAction (int action)

virtual void	horizontalScrollbarAction (int action)

virtual void	verticalScrollbarValueChanged (int value)

virtual void	horizontalScrollbarValueChanged (int value)

virtual void	closeEditor (QWidget *editor, QAbstractItemDelegate::EndEditHint hint)
	Closes the given editor, and releases it.

virtual void	commitData (QWidget *editor)
	Commit the data in the editor to the model.

virtual void	editorDestroyed (QObject *editor)
	This function is called when the given editor has been destroyed.

Detailed Description

The QListWidget class provides an item-based list widget.

\inmodule QtWidgets

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);

QListWidget

The QListWidget class provides an item-based list widget.

Definition qlistwidget.h:164

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, then it should be constructed without a parent widget. The insertItem() function should then be used to place it within the list. The list widget will take ownership of the item.

QListWidgetItem *newItem = new QListWidgetItem;

newItem->setText(itemText);

QListWidgetItem

The QListWidgetItem class provides an item for use with the QListWidget item view class.

Definition qlistwidget.h:23

QListWidgetItem::setText

void setText(const QString &text)

Sets the text for the list widget item's to the given text.

Definition qlistwidget.h:134

listWidget->insertItem(row, newItem);

QListWidget::insertItem

void insertItem(int row, QListWidgetItem *item)

Inserts the item at the position in the list given by row.

Definition qlistwidget.cpp:1471

row

GLenum GLenum GLsizei void * row

Definition qopenglext.h:2747

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.

See also: QListWidgetItem, QListView, QTreeView, {Model/View Programming}, {Tab Dialog Example}

Definition at line 163 of file qlistwidget.h.

Constructor & Destructor Documentation

◆ QListWidget()

QListWidget::QListWidget ( QWidget * parent = nullptr )

explicit

Constructs an empty QListWidget with the given parent.

Definition at line 1397 of file qlistwidget.cpp.

References d.

◆ ~QListWidget()

QListWidget::~QListWidget ( )

Destroys the list widget and all its items.

Definition at line 1408 of file qlistwidget.cpp.

Member Function Documentation

◆ addItem() [1/2]

void QListWidget::addItem ( const QString & label )

inline

Inserts an item with the text label at the end of the list widget.

Definition at line 184 of file qlistwidget.h.

◆ addItem() [2/2]

void QListWidget::addItem ( QListWidgetItem * item )

inline

Inserts the item at the end of the list widget.

Warning: A QListWidgetItem can only be added to a QListWidget once. Adding the same QListWidgetItem multiple times to a QListWidget will result in undefined behavior.

See also: insertItem()

Definition at line 276 of file qlistwidget.h.

◆ addItems()

void QListWidget::addItems ( const QStringList & labels )

inline

Inserts items with the text labels at the end of the list widget.

See also: insertItems()

Definition at line 186 of file qlistwidget.h.

◆ clear

void QListWidget::clear ( )

slot

Removes all items and selections in the view.

Warning: All items will be permanently deleted.

Definition at line 1806 of file qlistwidget.cpp.

References QItemSelectionModel::clear(), d, and QAbstractItemView::selectionModel().

Here is the call graph for this function:

◆ closePersistentEditor()

void QListWidget::closePersistentEditor ( QListWidgetItem * item )

Closes the persistent editor for the given item.

See also: openPersistentEditor(), isPersistentEditorOpen()

Definition at line 1700 of file qlistwidget.cpp.

References QAbstractItemView::closePersistentEditor(), d, and item.

Here is the call graph for this function:

◆ count()

int QListWidget::count ( ) const

Definition at line 1527 of file qlistwidget.cpp.

References d.

◆ currentItem()

QListWidgetItem * QListWidget::currentItem ( ) const

Returns the current item.

Definition at line 1536 of file qlistwidget.cpp.

References QAbstractItemView::currentIndex(), and d.

Here is the call graph for this function:

◆ currentItemChanged

void QListWidget::currentItemChanged	(	QListWidgetItem *	current,
		QListWidgetItem *	previous
	)

signal

This signal is emitted whenever the current item changes.

previous is the item that previously had the focus; current is the new current item.

◆ currentRow()

int QListWidget::currentRow ( ) const

Definition at line 1570 of file qlistwidget.cpp.

References QAbstractItemView::currentIndex(), and QModelIndex::row().

Here is the call graph for this function:

◆ currentRowChanged

void QListWidget::currentRowChanged ( int currentRow )

signal

This signal is emitted whenever the current item changes.

currentRow is the row of the current item. If there is no current item, the currentRow is -1.

◆ currentTextChanged

void QListWidget::currentTextChanged ( const QString & currentText )

signal

This signal is emitted whenever the current item changes.

currentText is the text data in the current item. If there is no current item, the currentText is invalid.

◆ editItem()

void QListWidget::editItem ( QListWidgetItem * item )

Starts editing the item if it is editable.

Definition at line 1676 of file qlistwidget.cpp.

References d, QAbstractItemView::edit(), and item.

Here is the call graph for this function:

◆ event()

bool QListWidget::event ( QEvent * e )

overrideprotected

\reimp

Definition at line 1941 of file qlistwidget.cpp.

References e, and QListView::event().

Here is the call graph for this function:

◆ findItems()

QList< QListWidgetItem * > QListWidget::findItems	(	const QString &	text,
		Qt::MatchFlags	flags
	)		const

Finds items with the text that matches the string text using the given flags.

Definition at line 1775 of file qlistwidget.cpp.

References QList< T >::append(), QList< T >::at(), d, Qt::DisplayRole, i, items, QAbstractItemView::model(), QList< T >::reserve(), QModelIndex::row(), QList< T >::size(), and text.

Here is the call graph for this function:

◆ indexFromItem()

QModelIndex QListWidget::indexFromItem ( const QListWidgetItem * item ) const

Returns the QModelIndex associated with the given item.

Note: In Qt versions prior to 5.10, this function took a non-{const} item.

Definition at line 1912 of file qlistwidget.cpp.

References d, and item.

Referenced by mimeData().

Here is the caller graph for this function:

◆ insertItem() [1/2]

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

Inserts an item with the text label in the list widget at the position given by row.

See also: addItem()

Definition at line 1485 of file qlistwidget.cpp.

References d, and QListWidgetItem.

◆ insertItem() [2/2]

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

Inserts the item at the position in the list given by row.

See also: addItem()

Definition at line 1471 of file qlistwidget.cpp.

References d, and item.

◆ insertItems()

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

Inserts items from the list of labels into the list, starting at the given row.

See also: insertItem(), addItem()

Definition at line 1498 of file qlistwidget.cpp.

References d.

◆ isPersistentEditorOpen() [1/2]

bool QAbstractItemView::isPersistentEditorOpen ( const QModelIndex & index ) const

Since: 5.10

Returns whether a persistent editor is open for the item at index index.

See also: openPersistentEditor(), closePersistentEditor()

Definition at line 182 of file qabstractitemview.cpp.

References QAbstractItemViewPrivate::oldCurrent, and QAbstractItemViewPrivate::oldSelection.

◆ isPersistentEditorOpen() [2/2]

bool QListWidget::isPersistentEditorOpen ( QListWidgetItem * item ) const

Since: 5.10

Returns whether a persistent editor is open for item item.

See also: openPersistentEditor(), closePersistentEditor()

Definition at line 1714 of file qlistwidget.cpp.

References d, QAbstractItemView::isPersistentEditorOpen(), and item.

Here is the call graph for this function:

◆ isSortingEnabled()

bool QListWidget::isSortingEnabled ( ) const

Definition at line 1657 of file qlistwidget.cpp.

References d.

◆ item()

QListWidgetItem * QListWidget::item ( int row ) const

Returns the item that occupies the given row in the list if one has been set; otherwise returns \nullptr.

See also: row()

Definition at line 1444 of file qlistwidget.cpp.

References d.

◆ itemActivated

void QListWidget::itemActivated ( QListWidgetItem * item )

signal

This signal is emitted when the item is activated.

The item is activated when the user clicks or double clicks on it, depending on the system configuration. It is also activated when the user presses the activation key (on Windows and X11 this is the \uicontrol Return key, on Mac OS X it is \uicontrol{Command+O}).

◆ itemAt() [1/2]

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

Returns a pointer to the item at the coordinates p.

The coordinates are relative to the list widget's \l{QAbstractScrollArea::}{viewport()}.

Definition at line 1603 of file qlistwidget.cpp.

References d, and QListView::indexAt().

Here is the call graph for this function:

◆ itemAt() [2/2]

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

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Returns a pointer to the item at the coordinates (x, y).

The coordinates are relative to the list widget's \l{QAbstractScrollArea::}{viewport()}.

Definition at line 279 of file qlistwidget.h.

◆ itemChanged

void QListWidget::itemChanged ( QListWidgetItem * item )

signal

This signal is emitted whenever the data of item has changed.

◆ itemClicked

void QListWidget::itemClicked ( QListWidgetItem * item )

signal

This signal is emitted with the specified item when a mouse button is clicked on an item in the widget.

See also: itemPressed(), itemDoubleClicked()

◆ itemDoubleClicked

void QListWidget::itemDoubleClicked ( QListWidgetItem * item )

signal

This signal is emitted with the specified item when a mouse button is double clicked on an item in the widget.

See also: itemClicked(), itemPressed()

◆ itemEntered

void QListWidget::itemEntered ( QListWidgetItem * item )

signal

This signal is emitted when the mouse cursor enters an item.

The item is the item entered. This signal is only emitted when mouseTracking is turned on, or when a mouse button is pressed while moving into an item.

See also: QWidget::setMouseTracking()

◆ itemFromIndex()

QListWidgetItem * QListWidget::itemFromIndex ( const QModelIndex & index ) const

Returns a pointer to the QListWidgetItem associated with the given index.

Definition at line 1922 of file qlistwidget.cpp.

References d.

◆ itemPressed

void QListWidget::itemPressed ( QListWidgetItem * item )

signal

This signal is emitted with the specified item when a mouse button is pressed on an item in the widget.

See also: itemClicked(), itemDoubleClicked()

◆ items()

QList< QListWidgetItem * > QListWidget::items ( const QMimeData * data ) const

Returns a list of pointers to the items contained in the data object.

If the object was not created by a QListWidget in the same process, the list is empty.

Definition at line 1898 of file qlistwidget.cpp.

References QListWidgetMimeData::items.

◆ itemSelectionChanged

void QListWidget::itemSelectionChanged ( )

signal

This signal is emitted whenever the selection changes.

See also: selectedItems(), QListWidgetItem::isSelected(), currentItemChanged()

Referenced by setSelectionModel().

Here is the caller graph for this function:

◆ itemWidget()

QWidget * QListWidget::itemWidget ( QListWidgetItem * item ) const

Since: 4.1

Returns the widget displayed in the given item.

See also: setItemWidget(), removeItemWidget()

Definition at line 1728 of file qlistwidget.cpp.

References d, QAbstractItemView::indexWidget(), and item.

Here is the call graph for this function:

◆ mimeData()

QMimeData * QListWidget::mimeData ( const QList< QListWidgetItem * > & items ) const

protectedvirtual

Returns an object that contains a serialized description of the specified items.

The format used to describe the items is obtained from the mimeTypes() function.

If the list of items is empty, \nullptr is returned instead of a serialized empty list.

Definition at line 1832 of file qlistwidget.cpp.

References QList< T >::clear(), d, indexFromItem(), QList< T >::isEmpty(), item, items, QList< T >::reserve(), and QList< T >::size().

Here is the call graph for this function:

◆ mimeTypes()

QStringList QListWidget::mimeTypes ( ) const

protectedvirtual

Returns a list of MIME types that can be used to describe a list of listwidget items.

See also: mimeData()

Definition at line 1819 of file qlistwidget.cpp.

◆ openPersistentEditor()

void QListWidget::openPersistentEditor ( QListWidgetItem * item )

Opens an editor for the given item.

The editor remains open after editing.

See also: closePersistentEditor(), isPersistentEditorOpen()

Definition at line 1688 of file qlistwidget.cpp.

References d, item, and QAbstractItemView::openPersistentEditor().

Here is the call graph for this function:

◆ removeItemWidget()

void QListWidget::removeItemWidget ( QListWidgetItem * item )

inline

Since: 4.3

Removes the widget set on the given item.

To remove an item (row) from the list entirely, either delete the item or use takeItem().

See also: itemWidget(), setItemWidget()

Definition at line 273 of file qlistwidget.h.

◆ row()

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

Returns the row containing the given item.

See also: item()

Definition at line 1458 of file qlistwidget.cpp.

References d, and item.

◆ scrollToItem

void QListWidget::scrollToItem	(	const QListWidgetItem *	item,
		QAbstractItemView::ScrollHint	hint = `EnsureVisible`
	)

slot

Scrolls the view if necessary to ensure that the item is visible.

hint specifies where the item should be located after the operation.

Definition at line 1794 of file qlistwidget.cpp.

References d, hint(), item, and QListView::scrollTo().

Here is the call graph for this function:

◆ selectedItems()

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

Returns a list of all selected items in the list widget.

Definition at line 1758 of file qlistwidget.cpp.

References QList< T >::append(), QList< T >::at(), d, i, items, QList< T >::reserve(), QModelIndex::row(), QItemSelectionModel::selectedIndexes, QAbstractItemView::selectionModel(), and QList< T >::size().

Here is the call graph for this function:

◆ setCurrentItem() [1/2]

void QListWidget::setCurrentItem ( QListWidgetItem * item )

Sets the current item to item.

Unless the selection mode is \l{QAbstractItemView::}{NoSelection}, the item is also selected.

Definition at line 1549 of file qlistwidget.cpp.

References item, and setCurrentRow().

Here is the call graph for this function:

◆ setCurrentItem() [2/2]

void QListWidget::setCurrentItem	(	QListWidgetItem *	item,
		QItemSelectionModel::SelectionFlags	command
	)

Since: 4.4 Set the current item to item, using the given command.

Definition at line 1558 of file qlistwidget.cpp.

References item, and setCurrentRow().

Here is the call graph for this function:

◆ setCurrentRow() [1/2]

void QListWidget::setCurrentRow ( int row )

Definition at line 1575 of file qlistwidget.cpp.

References QItemSelectionModel::ClearAndSelect, d, QAbstractItemView::NoSelection, QItemSelectionModel::NoUpdate, QItemSelectionModel::SelectCurrent, QAbstractItemView::selectionModel(), QItemSelectionModel::setCurrentIndex(), and QAbstractItemView::SingleSelection.

Referenced by setCurrentItem(), and setCurrentItem().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setCurrentRow() [2/2]

void QListWidget::setCurrentRow	(	int	row,
		QItemSelectionModel::SelectionFlags	command
	)

Since: 4.4

Sets the current row to be the given row, using the given command,

Definition at line 1592 of file qlistwidget.cpp.

References d.

◆ setItemWidget()

void QListWidget::setItemWidget	(	QListWidgetItem *	item,
		QWidget *	widget
	)

Since: 4.1

Sets the widget to be displayed in the given item.

This function should only be used to display static content in the place of a list widget item. If you want to display custom dynamic content or implement a custom editor widget, use QListView and subclass QStyledItemDelegate instead.

See also: itemWidget(), removeItemWidget(), {Delegate Classes}

Definition at line 1747 of file qlistwidget.cpp.

References d, item, QAbstractItemView::setIndexWidget(), and widget.

Here is the call graph for this function:

◆ setModel()

void QListWidget::setModel ( QAbstractItemModel * model )

overrideprivatevirtual

Reimplemented from QAbstractItemView.

Definition at line 1933 of file qlistwidget.cpp.

References Q_ASSERT.

◆ setSelectionModel()

void QListWidget::setSelectionModel ( QItemSelectionModel * selectionModel )

overridevirtual

\reimp

Reimplemented from QAbstractItemView.

Definition at line 1416 of file qlistwidget.cpp.

References QObject::connect(), QAbstractItemView::currentChanged(), d, QObject::disconnect(), itemSelectionChanged(), QAbstractItemView::selectionChanged(), QAbstractItemView::selectionModel(), QAbstractItemView::setSelectionModel(), SIGNAL, and SLOT.

Here is the call graph for this function:

◆ setSortingEnabled()

void QListWidget::setSortingEnabled ( bool enable )

Definition at line 1651 of file qlistwidget.cpp.

References d.

◆ sortItems()

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

Sorts all the items in the list widget according to the specified order.

Definition at line 1634 of file qlistwidget.cpp.

References d.

◆ takeItem()

QListWidgetItem * QListWidget::takeItem ( int row )

Removes and returns the item from the given row in the list widget; otherwise returns \nullptr.

Items removed from a list widget will not be managed by Qt, and will need to be deleted manually.

See also: insertItem(), addItem()

Definition at line 1514 of file qlistwidget.cpp.

References d.

◆ visualItemRect()

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

Returns the rectangle on the viewport occupied by the item at item.

Definition at line 1624 of file qlistwidget.cpp.

References d, item, and QListView::visualRect().

Here is the call graph for this function:

Friends And Related Symbol Documentation

◆ QListModel

friend class QListModel

friend

Definition at line 172 of file qlistwidget.h.

◆ QListWidgetItem

friend class QListWidgetItem

friend

Definition at line 171 of file qlistwidget.h.

Referenced by insertItem().

Property Documentation

◆ count

QListWidget::count

read

the number of items in the list including any hidden items.

Definition at line 131 of file qlistwidget.h.

◆ currentRow

QListWidget::currentRow

readwrite

the row of the current item.

Depending on the current selection mode, the row may also be selected.

Definition at line 131 of file qlistwidget.h.

◆ sortingEnabled

QListWidget::sortingEnabled

readwrite

whether sorting is enabled

Since: 4.2

If this property is true, sorting is enabled for the list; if the property is false, sorting is not enabled.

The default value is false.

Definition at line 131 of file qlistwidget.h.

The documentation for this class was generated from the following files:

qtbase/src/widgets/itemviews/qlistwidget.h
qtbase/src/widgets/itemviews/qlistwidget.cpp

Public Slots

Signals

Public Member Functions

Protected Member Functions

Properties

Private Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ QListWidget()

◆ ~QListWidget()

Member Function Documentation

◆ addItem() [1/2]

◆ addItem() [2/2]

◆ addItems()

◆ clear

◆ closePersistentEditor()

◆ count()

◆ currentItem()

◆ currentItemChanged

◆ currentRow()

◆ currentRowChanged

◆ currentTextChanged

◆ editItem()

◆ event()

◆ findItems()

◆ indexFromItem()

◆ insertItem() [1/2]

◆ insertItem() [2/2]

◆ insertItems()

◆ isPersistentEditorOpen() [1/2]

◆ isPersistentEditorOpen() [2/2]

◆ isSortingEnabled()

◆ item()

◆ itemActivated

◆ itemAt() [1/2]

◆ itemAt() [2/2]

◆ itemChanged

◆ itemClicked

◆ itemDoubleClicked

◆ itemEntered

◆ itemFromIndex()

◆ itemPressed

◆ items()

◆ itemSelectionChanged

◆ itemWidget()

◆ mimeData()

◆ mimeTypes()

◆ openPersistentEditor()

◆ removeItemWidget()

◆ row()

◆ scrollToItem

◆ selectedItems()

◆ setCurrentItem() [1/2]

◆ setCurrentItem() [2/2]

◆ setCurrentRow() [1/2]

◆ setCurrentRow() [2/2]

◆ setItemWidget()

◆ setModel()

◆ setSelectionModel()

◆ setSortingEnabled()

◆ sortItems()

◆ takeItem()

◆ visualItemRect()

Friends And Related Symbol Documentation

◆ QListModel

◆ QListWidgetItem

Property Documentation

◆ count

◆ currentRow

◆ sortingEnabled