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)
	Constructs a copy of 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)
	Sets the selected state of the item to select.

bool	isSelected () const
	Returns `true` if the item is selected; otherwise returns `false`.

void	setHidden (bool hide)
	Hides the item if hide is true; otherwise shows the item.

bool	isHidden () const
	Returns `true` if the item is hidden; otherwise returns `false`.

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
	Returns the brush used to display the list item's background.

void	setBackground (const QBrush &brush)
	Sets the background brush of the list item to the given brush.

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

void	setForeground (const QBrush &brush)
	Sets the foreground brush of the list item to the given 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
	Returns the size hint set for the list item.

void	setSizeHint (const QSize &size)
	Sets the size hint for the list item to be 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);

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 549 of file qlistwidget.cpp.

◆ 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 576 of file qlistwidget.cpp.

◆ 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 610 of file qlistwidget.cpp.

◆ QListWidgetItem() [4/4]

QListWidgetItem::QListWidgetItem ( const QListWidgetItem & other )

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 735 of file qlistwidget.cpp.

◆ ~QListWidgetItem()

QListWidgetItem::~QListWidgetItem ( )

virtual

Destroys the list item.

Definition at line 632 of file qlistwidget.cpp.

Member Function Documentation

◆ background()

QBrush QListWidgetItem::background ( ) const

inline

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

See also: setBackground(), foreground()

Definition at line 93 of file qlistwidget.h.

◆ 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.

◆ clone()

QListWidgetItem * QListWidgetItem::clone ( ) const

virtual

Creates an exact copy of the item.

Definition at line 642 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 685 of file qlistwidget.cpp.

◆ 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.

◆ 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.

◆ foreground()

QBrush QListWidgetItem::foreground ( ) const

inline

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.

◆ 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.

◆ isHidden()

bool QListWidgetItem::isHidden ( ) const

inline

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

See also: setHidden()

Definition at line 275 of file qlistwidget.h.

◆ isSelected()

bool QListWidgetItem::isSelected ( ) const

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

See also: setSelected()

Definition at line 945 of file qlistwidget.cpp.

◆ listWidget()

QListWidget * QListWidgetItem::listWidget ( ) const

inline

Returns the list widget containing the item.

Definition at line 37 of file qlistwidget.h.

◆ 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 698 of file qlistwidget.cpp.

◆ 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 751 of file qlistwidget.cpp.

◆ read()

void QListWidgetItem::read ( QDataStream & in )

virtual

Reads the item from stream in.

See also: write()

Definition at line 711 of file qlistwidget.cpp.

◆ setBackground()

void QListWidgetItem::setBackground ( const QBrush & brush )

inline

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.

◆ 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.

◆ 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 656 of file qlistwidget.cpp.

◆ setFlags()

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

Sets the item flags for the list item to flags.

See also: Qt::ItemFlags

Definition at line 961 of file qlistwidget.cpp.

◆ 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.

◆ setForeground()

void QListWidgetItem::setForeground ( const QBrush & brush )

inline

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.

◆ setHidden()

void QListWidgetItem::setHidden ( bool hide )

inline

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

See also: isHidden()

Definition at line 272 of file qlistwidget.h.

◆ 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.

◆ setSelected()

void QListWidgetItem::setSelected ( bool select )

Sets the selected state of the item to select.

See also: isSelected()

Definition at line 919 of file qlistwidget.cpp.

◆ setSizeHint()

void QListWidgetItem::setSizeHint ( const QSize & size )

inline

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.

◆ 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.

◆ 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.

◆ 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.

◆ sizeHint()

QSize QListWidgetItem::sizeHint ( ) const

inline

Returns the size hint set for the list item.

Definition at line 108 of file qlistwidget.h.

◆ statusTip()

QString QListWidgetItem::statusTip ( ) const

inline

Returns the list item's status tip.

See also: setStatusTip()

Definition at line 56 of file qlistwidget.h.

◆ text()

QString QListWidgetItem::text ( ) const

inline

Returns the list item's text.

See also: setText()

Definition at line 48 of file qlistwidget.h.

◆ textAlignment()

Qt::Alignment 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.

◆ 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 721 of file qlistwidget.cpp.

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 778 of file qlistwidget.cpp.

◆ operator>>()

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

This operator uses QListWidgetItem::read().

See also: {Serializing Qt Data Types}

Definition at line 793 of file qlistwidget.cpp.

◆ 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 (3ad6bdcc62e920401239bec548261f759a49d8b1)
qtbase/src/widgets/itemviews/qlistwidget.cpp (10e0ce7f8251fb4449152ba9979076930424d011)

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