QListWidgetItem Class▲
-
Header: QListWidgetItem
-
CMake:
find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
-
qmake: QT += widgets
-
Group: QListWidgetItem is part of model-view
Detailed Description▲
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().
Subclassing▲
When subclassing QListWidgetItem to provide custom items, it is possible to define new types for them enabling them to be distinguished from standard items. For subclasses that require this feature, ensure that you call the base class constructor with a new type value equal to or greater than UserType, within your constructor.
See Also▲
Member Type Documentation▲
enum QListWidgetItem::ItemType▲
This enum describes the types that are used to describe list widget items.
|
Constant |
Value |
Description |
|---|---|---|
|
QListWidgetItem::Type |
0 |
The default type for list widget items. |
|
QListWidgetItem::UserType |
1000 |
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▲
See also type()
Member Function Documentation▲
[explicit] QListWidgetItem::QListWidgetItem(QListWidget *parent = nullptr, int type = Type)▲
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▲
See also type()
[explicit] QListWidgetItem::QListWidgetItem(const QString &text, QListWidget *parent = nullptr, int type = Type)▲
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▲
See also type()
[explicit] QListWidgetItem::QListWidgetItem(const QIcon &icon, const QString &text, QListWidget *parent = nullptr, int type = Type)▲
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▲
See also type()
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▲
[virtual] QListWidgetItem::~QListWidgetItem()▲
Destroys the list item.
QBrush QListWidgetItem::background() const▲
Returns the brush used to display the list item's background.
See Also▲
See also setBackground(), foreground()
Qt::CheckState QListWidgetItem::checkState() const▲
Returns the checked state of the list item (see Qt::CheckState).
See Also▲
See also setCheckState(), flags()
[virtual] QListWidgetItem *QListWidgetItem::clone() const▲
Creates an exact copy of the item.
[virtual] QVariant QListWidgetItem::data(int role) const▲
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▲
See also Qt::ItemDataRole, setData()
Qt::ItemFlags QListWidgetItem::flags() const▲
QFont QListWidgetItem::font() const▲
QBrush QListWidgetItem::foreground() const▲
Returns the brush used to display the list item's foreground (e.g. text).
See Also▲
See also setForeground(), background()
QIcon QListWidgetItem::icon() const▲
bool QListWidgetItem::isHidden() const▲
bool QListWidgetItem::isSelected() const▲
QListWidget *QListWidgetItem::listWidget() const▲
Returns the list widget containing the item.
[virtual] void QListWidgetItem::read(QDataStream &in)▲
void QListWidgetItem::setBackground(const QBrush &brush)▲
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▲
See also background(), setForeground()
void QListWidgetItem::setCheckState(Qt::CheckState state)▲
[virtual] void QListWidgetItem::setData(int role, const QVariant &value)▲
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.
The default implementation treats Qt::EditRole and Qt::DisplayRole as referring to the same data.
See Also▲
See also Qt::ItemDataRole, data()
void QListWidgetItem::setFlags(Qt::ItemFlags flags)▲
void QListWidgetItem::setFont(const QFont &font)▲
void QListWidgetItem::setForeground(const QBrush &brush)▲
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▲
See also foreground(), setBackground()
void QListWidgetItem::setHidden(bool hide)▲
void QListWidgetItem::setIcon(const QIcon &icon)▲
void QListWidgetItem::setSelected(bool select)▲
void QListWidgetItem::setSizeHint(const QSize &size)▲
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.
See Also▲
See also sizeHint()
void QListWidgetItem::setStatusTip(const QString &statusTip)▲
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▲
See also statusTip(), setToolTip(), setWhatsThis(), QWidget::setMouseTracking()
void QListWidgetItem::setText(const QString &text)▲
[since 6.4] void QListWidgetItem::setTextAlignment(Qt::Alignment alignment)▲
Sets the list item's text alignment to alignment.
This function was introduced in Qt 6.4.
void QListWidgetItem::setToolTip(const QString &toolTip)▲
Sets the tooltip for the list item to the text specified by toolTip.
See Also▲
See also toolTip(), setStatusTip(), setWhatsThis()
void QListWidgetItem::setWhatsThis(const QString &whatsThis)▲
Sets the "What's This?" help for the list item to the text specified by whatsThis.
See Also▲
See also whatsThis(), setStatusTip(), setToolTip()
QSize QListWidgetItem::sizeHint() const▲
QString QListWidgetItem::statusTip() const▲
QString QListWidgetItem::text() const▲
int QListWidgetItem::textAlignment() const▲
Returns the text alignment for the list item.
This function returns an int for historical reasons. It will be corrected to return Qt::Alignment in Qt 7.
See Also▲
See also setTextAlignment(), Qt::Alignment
QString QListWidgetItem::toolTip() const▲
int QListWidgetItem::type() const▲
Returns the type passed to the QListWidgetItem constructor.
QString QListWidgetItem::whatsThis() const▲
Returns the list item's "What's This?" help text.
See Also▲
See also setWhatsThis(), statusTip(), toolTip()
[virtual] void QListWidgetItem::write(QDataStream &out) const▲
[virtual] bool QListWidgetItem::operator<(const QListWidgetItem &other) const▲
Returns true if this item's text is less then other item's text; otherwise returns false.
QListWidgetItem &QListWidgetItem::operator=(const QListWidgetItem &other)▲
Related Non-Members▲
QDataStream &operator<<(QDataStream &out, const QListWidgetItem &item)▲
Writes the list widget item item to stream out.
This operator uses QListWidgetItem::write().
See Also▲
See also Serializing Qt Data Types
QDataStream &operator>>(QDataStream &in, QListWidgetItem &item)▲
Reads a list widget item from stream in into item.
This operator uses QListWidgetItem::read().
See Also▲
See also Serializing Qt Data Types
Obsolete Members for QListWidgetItem▲
The following members of class QListWidgetItem are deprecated. We strongly advise against using them in new code.
Obsolete Member Function Documentation▲
void QListWidgetItem::setTextAlignment(int alignment)▲
This function is deprecated. We strongly advise against using it in new code.
Use the overload that takes a Qt::Alignment argument.
Sets the list item's text alignment to alignment.
See Also▲
See also textAlignment(), Qt::Alignment