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

#include <qlistwidget.h>

Collaboration diagram for QListWidgetItem:

Public Types
enum	ItemType { Type = 0 , UserType = 1000 }
	This enum describes the types that are used to describe list widget items. More...

Public Member Functions
	QListWidgetItem (QListWidget *listview=nullptr, int type=Type)
	Constructs an empty list widget item of the specified type with the given parent.

	QListWidgetItem (const QString &text, QListWidget *listview=nullptr, int type=Type)
	Constructs an empty list widget item of the specified type with the given text and parent.

	QListWidgetItem (const QIcon &icon, const QString &text, QListWidget *listview=nullptr, int type=Type)
	Constructs an empty list widget item of the specified type with the given icon, text and parent.

	QListWidgetItem (const QListWidgetItem &other)

virtual	~QListWidgetItem ()
	Destroys the list item.

virtual QListWidgetItem *	clone () const
	Creates an exact copy of the item.

QListWidget *	listWidget () const
	Returns the list widget containing the item.

void	setSelected (bool select)

bool	isSelected () const

void	setHidden (bool hide)

bool	isHidden () const

Qt::ItemFlags	flags () const
	Returns the item flags for this item (see \l{Qt::ItemFlags}).

void	setFlags (Qt::ItemFlags flags)
	Sets the item flags for the list item to flags.

QString	text () const
	Returns the list item's text.

void	setText (const QString &text)
	Sets the text for the list widget item's to the given text.

QIcon	icon () const
	Returns the list item's icon.

void	setIcon (const QIcon &icon)
	Sets the icon for the list item to the given icon.

QString	statusTip () const
	Returns the list item's status tip.

void	setStatusTip (const QString &statusTip)
	Sets the status tip for the list item to the text specified by statusTip.

QFont	font () const
	Returns the font used to display this list item's text.

void	setFont (const QFont &font)
	Sets the font used when painting the item to the given font.

Qt::Alignment	textAlignment () const

void	setTextAlignment (Qt::Alignment alignment)
	\obsolete [6.4] Use the overload that takes a Qt::Alignment argument.

QBrush	background () const

void	setBackground (const QBrush &brush)

QBrush	foreground () const

void	setForeground (const QBrush &brush)

Qt::CheckState	checkState () const
	Returns the checked state of the list item (see \l{Qt::CheckState}).

void	setCheckState (Qt::CheckState state)
	Sets the check state of the list item to state.

QSize	sizeHint () const

void	setSizeHint (const QSize &size)

virtual QVariant	data (int role) const
	Returns the item's data for a given role.

virtual void	setData (int role, const QVariant &value)
	Sets the data for a given role to the given value.

virtual bool	operator< (const QListWidgetItem &other) const
	Returns `true` if this item's text is less then other item's text; otherwise returns `false`.

virtual void	read (QDataStream &in)
	Reads the item from stream in.

virtual void	write (QDataStream &out) const
	Writes the item to stream out.

QListWidgetItem &	operator= (const QListWidgetItem &other)
	Assigns other's data and flags to this item.

int	type () const
	Returns the type passed to the QListWidgetItem constructor.

Friends
class	QListModel

class	QListWidget

Related Symbols
(Note that these are not member symbols.)
QDataStream &	operator<< (QDataStream &out, const QListWidgetItem &item)
	Writes the list widget item item to stream out.

QDataStream &	operator>> (QDataStream &in, QListWidgetItem &item)
	Reads a list widget item from stream in into item.

Detailed Description

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

\inmodule QtWidgets

A QListWidgetItem represents a single item in a QListWidget. Each item can hold several pieces of information, and will display them appropriately.

The item view convenience classes use a classic item-based interface rather than a pure model/view approach. For a more flexible list view widget, consider using the QListView class with a standard model.

List items can be inserted automatically into a list, when they are constructed, by specifying the list widget:

new QListWidgetItem(tr("Hazel"), listWidget);

QListWidgetItem

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

Definition qlistwidget.h:23

QListWidgetItem::listWidget

QListWidget * listWidget() const

Returns the list widget containing the item.

Definition qlistwidget.h:37

tr

#define tr(X)

Definition qtemporaryfile.cpp:21

Alternatively, list items can also be created without a parent widget, and later inserted into a list using QListWidget::insertItem().

List items are typically used to display text() and an icon(). These are set with the setText() and setIcon() functions. The appearance of the text can be customized with setFont(), setForeground(), and setBackground(). Text in list items can be aligned using the setTextAlignment() function. Tooltips, status tips and "What's This?" help can be added to list items with setToolTip(), setStatusTip(), and setWhatsThis().

By default, items are enabled, selectable, checkable, and can be the source of drag and drop operations.

Each item's flags can be changed by calling setFlags() with the appropriate value (see Qt::ItemFlags). Checkable items can be checked, unchecked and partially checked with the setCheckState() function. The corresponding checkState() function indicates the item's current check state.

The isHidden() function can be used to determine whether the item is hidden. To hide an item, use setHidden().

Definition at line 22 of file qlistwidget.h.

Member Enumeration Documentation

◆ ItemType

enum QListWidgetItem::ItemType

This enum describes the types that are used to describe list widget items.

\value Type The default type for list widget items. \value UserType The minimum value for custom types. Values below UserType are reserved by Qt.

You can define new user types in QListWidgetItem subclasses to ensure that custom items are treated specially.

See also: type()

Enumerator
Type
UserType

Definition at line 27 of file qlistwidget.h.

Constructor & Destructor Documentation

◆ QListWidgetItem() [1/4]

QListWidgetItem::QListWidgetItem	(	QListWidget *	parent = `nullptr`,
		int	type = `Type`
	)

explicit

Constructs an empty list widget item of the specified type with the given parent.

If parent is not specified, the item will need to be inserted into a list widget with QListWidget::insertItem().

This constructor inserts the item into the model of the parent that is passed to the constructor. If the model is sorted then the behavior of the insert is undetermined since the model will call the '<' operator method on the item which, at this point, is not yet constructed. To avoid the undetermined behavior, we recommend not to specify the parent and use QListWidget::insertItem() instead.

See also: type()

Definition at line 594 of file qlistwidget.cpp.

References model, and QSqlQueryModel::rowCount().

Here is the call graph for this function:

◆ QListWidgetItem() [2/4]

QListWidgetItem::QListWidgetItem	(	const QString &	text,
		QListWidget *	parent = `nullptr`,
		int	type = `Type`
	)

explicit

Constructs an empty list widget item of the specified type with the given text and parent.

If the parent is not specified, the item will need to be inserted into a list widget with QListWidget::insertItem().

This constructor inserts the item into the model of the parent that is passed to the constructor. If the model is sorted then the behavior of the insert is undetermined since the model will call the '<' operator method on the item which, at this point, is not yet constructed. To avoid the undetermined behavior, we recommend not to specify the parent and use QListWidget::insertItem() instead.

See also: type()

Definition at line 621 of file qlistwidget.cpp.

References Qt::DisplayRole, model, QSqlQueryModel::rowCount(), setData(), text(), and view.

Here is the call graph for this function:

◆ QListWidgetItem() [3/4]

QListWidgetItem::QListWidgetItem	(	const QIcon &	icon,
		const QString &	text,
		QListWidget *	parent = `nullptr`,
		int	type = `Type`
	)

explicit

Constructs an empty list widget item of the specified type with the given icon, text and parent.

If the parent is not specified, the item will need to be inserted into a list widget with QListWidget::insertItem().

This constructor inserts the item into the model of the parent that is passed to the constructor. If the model is sorted then the behavior of the insert is undetermined since the model will call the '<' operator method on the item which, at this point, is not yet constructed. To avoid the undetermined behavior, we recommend not to specify the parent and use QListWidget::insertItem() instead.

See also: type()

Definition at line 655 of file qlistwidget.cpp.

References Qt::DecorationRole, Qt::DisplayRole, icon(), model, QSqlQueryModel::rowCount(), setData(), text(), and view.

Here is the call graph for this function:

◆ QListWidgetItem() [4/4]

QListWidgetItem::QListWidgetItem ( const QListWidgetItem & other )

Since: 4.1

Constructs a copy of other. Note that type() and listWidget() are not copied.

This function is useful when reimplementing clone().

See also: data(), flags()

Definition at line 782 of file qlistwidget.cpp.

References other(), and QListWidgetItemPrivate::values.

Here is the call graph for this function:

◆ ~QListWidgetItem()

QListWidgetItem::~QListWidgetItem ( )

virtual

Destroys the list item.

Definition at line 677 of file qlistwidget.cpp.

References model.

Member Function Documentation

◆ background()

QBrush QListWidgetItem::background ( ) const

inline

Since: 4.2

Returns the brush used to display the list item's background.

See also: setBackground(), foreground()

Definition at line 93 of file qlistwidget.h.

References Qt::BackgroundRole.

◆ checkState()

Qt::CheckState QListWidgetItem::checkState ( ) const

inline

Returns the checked state of the list item (see \l{Qt::CheckState}).

See also: flags()

Definition at line 103 of file qlistwidget.h.

References Qt::CheckStateRole.

◆ clone()

QListWidgetItem * QListWidgetItem::clone ( ) const

virtual

Creates an exact copy of the item.

Definition at line 687 of file qlistwidget.cpp.

◆ data()

QVariant QListWidgetItem::data ( int role ) const

virtual

Returns the item's data for a given role.

Reimplement this function if you need extra roles or special behavior for certain roles.

See also: Qt::ItemDataRole, setData()

Definition at line 730 of file qlistwidget.cpp.

References QList< T >::at(), Qt::DisplayRole, Qt::EditRole, i, QWidgetItemData::role, QList< T >::size(), QWidgetItemData::value, and QListWidgetItemPrivate::values.

Referenced by QListModel::data().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ flags()

Qt::ItemFlags QListWidgetItem::flags ( ) const

inline

Returns the item flags for this item (see \l{Qt::ItemFlags}).

Definition at line 45 of file qlistwidget.h.

Referenced by QListModel::flags().

Here is the caller graph for this function:

◆ font()

QFont QListWidgetItem::font ( ) const

inline

Returns the font used to display this list item's text.

Definition at line 72 of file qlistwidget.h.

References Qt::FontRole.

◆ foreground()

QBrush QListWidgetItem::foreground ( ) const

inline

Since: 4.2

Returns the brush used to display the list item's foreground (e.g. text).

See also: setForeground(), background()

Definition at line 98 of file qlistwidget.h.

References Qt::ForegroundRole.

◆ icon()

QIcon QListWidgetItem::icon ( ) const

inline

Returns the list item's icon.

See also: setIcon(), {QAbstractItemView::iconSize}{iconSize}

Definition at line 52 of file qlistwidget.h.

References Qt::DecorationRole.

Referenced by QListWidgetItem().

Here is the caller graph for this function:

◆ isHidden()

bool QListWidgetItem::isHidden ( ) const

inline

Since: 4.2

Returns true if the item is hidden; otherwise returns false.

See also: setHidden()

Definition at line 285 of file qlistwidget.h.

References view.

◆ isSelected()

bool QListWidgetItem::isSelected ( ) const

Since: 4.2

Returns true if the item is selected; otherwise returns false.

See also: setSelected()

Definition at line 998 of file qlistwidget.cpp.

References QAbstractTableModel::index(), model, and view.

Here is the call graph for this function:

◆ listWidget()

QListWidget * QListWidgetItem::listWidget ( ) const

inline

Returns the list widget containing the item.

Definition at line 37 of file qlistwidget.h.

References view.

◆ operator<()

bool QListWidgetItem::operator< ( const QListWidgetItem & other ) const

virtual

Returns true if this item's text is less then other item's text; otherwise returns false.

Definition at line 743 of file qlistwidget.cpp.

References Qt::DisplayRole, other(), and QAbstractItemModelPrivate::variantLessThan().

Here is the call graph for this function:

◆ operator=()

QListWidgetItem & QListWidgetItem::operator= ( const QListWidgetItem & other )

Assigns other's data and flags to this item.

Note that type() and listWidget() are not copied.

This function is useful when reimplementing clone().

See also: data(), flags()

Definition at line 798 of file qlistwidget.cpp.

References other(), and QListWidgetItemPrivate::values.

Here is the call graph for this function:

◆ read()

void QListWidgetItem::read ( QDataStream & in )

virtual

Reads the item from stream in.

See also: write()

Definition at line 756 of file qlistwidget.cpp.

References QListWidgetItemPrivate::values.

◆ setBackground()

void QListWidgetItem::setBackground ( const QBrush & brush )

inline

Since: 4.2

Sets the background brush of the list item to the given brush. Setting a default-constructed brush will let the view use the default color from the style.

See also: background(), setForeground()

Definition at line 95 of file qlistwidget.h.

References Qt::BackgroundRole, Qt::NoBrush, and setData().

Here is the call graph for this function:

◆ setCheckState()

void QListWidgetItem::setCheckState ( Qt::CheckState state )

inline

Sets the check state of the list item to state.

See also: checkState()

Definition at line 105 of file qlistwidget.h.

References Qt::CheckStateRole, setData(), and state.

Here is the call graph for this function:

◆ setData()

void QListWidgetItem::setData	(	int	role,
		const QVariant &	value
	)

virtual

Sets the data for a given role to the given value.

Reimplement this function if you need extra roles or special behavior for certain roles.

Note: The default implementation treats Qt::EditRole and Qt::DisplayRole as referring to the same data.

See also: Qt::ItemDataRole, data()

Definition at line 701 of file qlistwidget.cpp.

References QList< T >::append(), QList< T >::at(), Qt::DisplayRole, Qt::EditRole, i, model, QWidgetItemData::role, QList< T >::size(), QList< T >::value(), QWidgetItemData::value, and QListWidgetItemPrivate::values.

Referenced by QListWidgetItem(), QListWidgetItem(), QListModel::setData(), setFont(), setIcon(), setStatusTip(), and setText().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setFlags()

void QListWidgetItem::setFlags ( Qt::ItemFlags flags )

Sets the item flags for the list item to flags.

See also: Qt::ItemFlags

Definition at line 1014 of file qlistwidget.cpp.

References model.

◆ setFont()

void QListWidgetItem::setFont ( const QFont & font )

inline

Sets the font used when painting the item to the given font.

Definition at line 153 of file qlistwidget.h.

References Qt::FontRole, and setData().

Here is the call graph for this function:

◆ setForeground()

void QListWidgetItem::setForeground ( const QBrush & brush )

inline

Since: 4.2

Sets the foreground brush of the list item to the given brush. Setting a default-constructed brush will let the view use the default color from the style.

See also: foreground(), setBackground()

Definition at line 100 of file qlistwidget.h.

References Qt::ForegroundRole, Qt::NoBrush, and setData().

Here is the call graph for this function:

◆ setHidden()

void QListWidgetItem::setHidden ( bool hide )

inline

Since: 4.2

Hides the item if hide is true; otherwise shows the item.

See also: isHidden()

Definition at line 282 of file qlistwidget.h.

References view.

◆ setIcon()

void QListWidgetItem::setIcon ( const QIcon & icon )

inline

Sets the icon for the list item to the given icon.

See also: icon(), text(), {QAbstractItemView::iconSize}{iconSize}

Definition at line 137 of file qlistwidget.h.

References Qt::DecorationRole, and setData().

Here is the call graph for this function:

◆ setSelected()

void QListWidgetItem::setSelected ( bool select )

Since: 4.2

Sets the selected state of the item to select.

See also: isSelected()

Definition at line 971 of file qlistwidget.cpp.

References QItemSelectionModel::ClearAndSelect, QItemSelectionModel::Deselect, QAbstractTableModel::index(), model, QAbstractItemView::NoSelection, QItemSelectionModel::Select, select(), QAbstractItemView::SingleSelection, and view.

Here is the call graph for this function:

◆ setSizeHint()

void QListWidgetItem::setSizeHint ( const QSize & size )

inline

Since: 4.1

Sets the size hint for the list item to be size. If no size hint is set or size is invalid, the item delegate will compute the size hint based on the item data.

Definition at line 110 of file qlistwidget.h.

References setData(), and Qt::SizeHintRole.

Here is the call graph for this function:

◆ setStatusTip()

void QListWidgetItem::setStatusTip ( const QString & statusTip )

inline

Sets the status tip for the list item to the text specified by statusTip.

QListWidget mouseTracking needs to be enabled for this feature to work.

See also: statusTip(), setToolTip(), setWhatsThis(), QWidget::setMouseTracking()

Definition at line 140 of file qlistwidget.h.

References setData(), and Qt::StatusTipRole.

Here is the call graph for this function:

◆ setText()

void QListWidgetItem::setText ( const QString & text )

inline

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

See also: text()

Definition at line 134 of file qlistwidget.h.

References Qt::DisplayRole, and setData().

Referenced by ClipWindow::updateClipboard().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setTextAlignment()

void QListWidgetItem::setTextAlignment ( Qt::Alignment alignment )

inline

\obsolete [6.4] Use the overload that takes a Qt::Alignment argument.

Sets the list item's text alignment to alignment.

See also: Qt::Alignment

Since: 6.4

Sets the list item's text alignment to alignment.

Definition at line 90 of file qlistwidget.h.

References alignment, QVariant::fromValue(), setData(), and Qt::TextAlignmentRole.

Here is the call graph for this function:

◆ sizeHint()

QSize QListWidgetItem::sizeHint ( ) const

inline

Since: 4.1

Returns the size hint set for the list item.

Definition at line 108 of file qlistwidget.h.

References Qt::SizeHintRole.

◆ statusTip()

QString QListWidgetItem::statusTip ( ) const

inline

Returns the list item's status tip.

See also: setStatusTip()

Definition at line 56 of file qlistwidget.h.

References Qt::StatusTipRole.

◆ text()

QString QListWidgetItem::text ( ) const

inline

Returns the list item's text.

See also: setText()

Definition at line 48 of file qlistwidget.h.

References Qt::DisplayRole.

Referenced by QListWidgetItem(), QListWidgetItem(), and QListWidgetPrivate::_q_emitCurrentItemChanged().

Here is the caller graph for this function:

◆ textAlignment()

int QListWidgetItem::textAlignment ( ) const

inline

Returns the text alignment for the list item.

Note: This function returns an int for historical reasons. It will be corrected to return Qt::Alignment in Qt 7.

See also: Qt::Alignment

Definition at line 80 of file qlistwidget.h.

References Qt::TextAlignmentRole.

◆ type()

int QListWidgetItem::type ( ) const

inline

Returns the type passed to the QListWidgetItem constructor.

Definition at line 124 of file qlistwidget.h.

◆ write()

void QListWidgetItem::write ( QDataStream & out ) const

virtual

Writes the item to stream out.

See also: read()

Definition at line 766 of file qlistwidget.cpp.

References out, and QListWidgetItemPrivate::values.

Friends And Related Symbol Documentation

◆ operator<<()

QDataStream & operator<<	(	QDataStream &	out,
		const QListWidgetItem &	item
	)

This operator uses QListWidgetItem::write().

See also: {Serializing Qt Data Types}

Definition at line 825 of file qlistwidget.cpp.

References item, and out.

◆ operator>>()

QDataStream & operator>>	(	QDataStream &	in,
		QListWidgetItem &	item
	)

This operator uses QListWidgetItem::read().

See also: {Serializing Qt Data Types}

Definition at line 840 of file qlistwidget.cpp.

References item.

◆ QListModel

friend class QListModel

friend

Definition at line 24 of file qlistwidget.h.

◆ QListWidget

friend class QListWidget

friend

Definition at line 25 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 Types

Public Member Functions

Friends

Related Symbols

Detailed Description

Member Enumeration Documentation

◆ ItemType

Constructor & Destructor Documentation

◆ QListWidgetItem() [1/4]

◆ QListWidgetItem() [2/4]

◆ QListWidgetItem() [3/4]

◆ QListWidgetItem() [4/4]

◆ ~QListWidgetItem()

Member Function Documentation

◆ background()

◆ checkState()

◆ clone()

◆ data()

◆ flags()

◆ font()

◆ foreground()

◆ icon()

◆ isHidden()

◆ isSelected()

◆ listWidget()

◆ operator<()

◆ operator=()

◆ read()

◆ setBackground()

◆ setCheckState()

◆ setData()

◆ setFlags()

◆ setFont()

◆ setForeground()

◆ setHidden()

◆ setIcon()

◆ setSelected()

◆ setSizeHint()

◆ setStatusTip()

◆ setText()

◆ setTextAlignment()

◆ sizeHint()

◆ statusTip()

◆ text()

◆ textAlignment()

◆ type()

◆ write()

Friends And Related Symbol Documentation

◆ operator<<()

◆ operator>>()

◆ QListModel

◆ QListWidget