Sur cette page

QListWidgetItem Class

La classe `QListWidgetItem` fournit un élément destiné à être utilisé avec la classe de vue d'élément ` QListWidget `. En savoir plus...

En-tête : #include <QListWidgetItem>
CMake : find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake : QT += widgets

Types publics

enum ItemType { Type, UserType }

Fonctions publiques

QListWidgetItem(QListWidget *parent = nullptr, int type = Type)
QListWidgetItem(const QString &text, QListWidget *parent = nullptr, int type = Type)
QListWidgetItem(const QIcon &icon, const QString &text, QListWidget *parent = nullptr, int type = Type)
QListWidgetItem(const QListWidgetItem &other)
virtual ~QListWidgetItem()
QBrush background() const
Qt::CheckState checkState() const
virtual QListWidgetItem *clone() const
virtual QVariant data(int role) const
Qt::ItemFlags flags() const
QFont font() const
QBrush foreground() const
QIcon icon() const
bool isHidden() const
bool isSelected() const
QListWidget *listWidget() const
virtual void read(QDataStream &in)
void setBackground(const QBrush &brush)
void setCheckState(Qt::CheckState state)
virtual void setData(int role, const QVariant &value)
void setFlags(Qt::ItemFlags flags)
void setFont(const QFont &font)
void setForeground(const QBrush &brush)
void setHidden(bool hide)
void setIcon(const QIcon &icon)
void setSelected(bool select)
void setSizeHint(const QSize &size)
void setStatusTip(const QString &statusTip)
void setText(const QString &text)
(since 6.4) void setTextAlignment(Qt::Alignment alignment)
void setToolTip(const QString &toolTip)
void setWhatsThis(const QString &whatsThis)
QSize sizeHint() const
QString statusTip() const
QString text() const
int textAlignment() const
QString toolTip() const
int type() const
QString whatsThis() const
virtual void write(QDataStream &out) const
virtual bool operator<(const QListWidgetItem &other) const
QListWidgetItem &operator=(const QListWidgetItem &other)
QDataStream &operator<<(QDataStream &out, const QListWidgetItem &item)
QDataStream &operator>>(QDataStream &in, QListWidgetItem &item)

Description détaillée

Un QListWidgetItem représente un élément unique dans un QListWidget. Chaque élément peut contenir plusieurs informations et les affichera de manière appropriée.

Les classes de commodité de la vue d’élément utilisent une interface classique basée sur les éléments plutôt qu’une approche modèle/vue pure. Pour un widget de vue de liste plus flexible, envisagez d’utiliser la classe ` QListView ` avec un modèle standard.

Les éléments de liste peuvent être insérés automatiquement dans une liste, lors de leur création, en spécifiant le widget de liste :

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

Il est également possible de créer des éléments de liste sans widget parent, puis de les insérer ultérieurement dans une liste à l’aide de la méthode ` QListWidget::insertItem()`.

Les éléments de liste sont généralement utilisés pour afficher text() et un icon(). Ceux-ci sont définis à l’aide des fonctions setText() et setIcon(). L’apparence du texte peut être personnalisée avec setFont(), setForeground() et setBackground(). Le texte des éléments de liste peut être aligné à l’aide de la fonction setTextAlignment(). Des infobulles, des messages d'état et l'aide « Qu'est-ce que c'est ? » peuvent être ajoutés aux éléments de la liste à l'aide des fonctions setToolTip(), setStatusTip() et setWhatsThis().

Par défaut, les éléments sont activés, sélectionnables, cochables et peuvent faire l'objet d'opérations de glisser-déposer.

Les indicateurs de chaque élément peuvent être modifiés en appelant la fonction setFlags() avec la valeur appropriée (voir Qt::ItemFlags). Les éléments cochables peuvent être cochés, décochés ou partiellement cochés à l’aide de la fonction setCheckState(). La fonction correspondante checkState() indique l’état de cochage actuel de l’élément.

La fonction isHidden() permet de déterminer si l’élément est masqué. Pour masquer un élément, utilisez setHidden().

Sous-classement

Lors de la création d’une sous-classe de `QListWidgetItem` pour fournir des éléments personnalisés, il est possible de définir de nouveaux types pour ces derniers, ce qui permet de les distinguer des éléments standard. Pour les sous-classes nécessitant cette fonctionnalité, veillez à appeler le constructeur de la classe de base avec une valeur de type « new » égale ou supérieure à ` UserType`, au sein de votre constructeur.

Voir également QListWidget, Programmation modèle/vue, QTreeWidgetItem et QTableWidgetItem.

Documentation sur les types de membres

enum QListWidgetItem::ItemType

Cette énumération décrit les types utilisés pour définir les éléments d'un widget de liste.

ConstanteValeurDescription
QListWidgetItem::Type0Type par défaut des éléments du widget de liste.
QListWidgetItem::UserType1000Valeur minimale pour les types personnalisés. Les valeurs inférieures à UserType sont réservées par Qt.

Vous pouvez définir de nouveaux types utilisateur dans les sous-classes de ` QListWidgetItem ` afin de garantir que les éléments personnalisés soient traités de manière spécifique.

Voir également type().

Documentation des fonctions membres

[explicit] QListWidgetItem::QListWidgetItem(QListWidget *parent = nullptr, int type = Type)

Construit un élément de widget de liste vide de l’ type spécifiée avec l’ parent donné. Si parent n’est pas spécifié, l’élément devra être inséré dans un widget de liste à l’aide de QListWidget::insertItem().

Ce constructeur insère l’élément dans le modèle du parent qui lui est transmis. Si le modèle est trié, le comportement de l’insertion est indéterminé, car le modèle appellera la méthode d’opérateur '<' sur l’élément qui, à ce stade, n’est pas encore construit. Pour éviter ce comportement indéterminé, nous recommandons de ne pas spécifier le parent et d’utiliser QListWidget::insertItem() à la place.

Voir également type().

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

Construit un élément de widget de liste vide de l’ type spécifié, avec les paramètres text et parent fournis. Si le parent n’est pas spécifié, l’élément devra être inséré dans un widget de liste à l’aide de la méthode QListWidget::insertItem().

Ce constructeur insère l’élément dans le modèle du parent transmis au constructeur. Si le modèle est trié, le comportement de l’insertion est indéterminé, car le modèle appellera la méthode d’opérateur '<' sur l’élément qui, à ce stade, n’est pas encore construit. Pour éviter ce comportement indéterminé, nous recommandons de ne pas spécifier le parent et d’utiliser QListWidget::insertItem() à la place.

Voir également type().

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

Construit un élément de widget de liste vide de l'type spécifié avec les paramètres icon, text et parent fournis. Si le parent n'est pas spécifié, l'élément devra être inséré dans un widget de liste à l'aide de QListWidget::insertItem().

Ce constructeur insère l’élément dans le modèle du parent qui lui est transmis. Si le modèle est trié, le comportement de l’insertion est indéterminé, car le modèle appellera la méthode d’opérateur '<' sur l’élément qui, à ce stade, n’est pas encore construit. Pour éviter ce comportement indéterminé, nous recommandons de ne pas spécifier le parent et d’utiliser QListWidget::insertItem() à la place.

Voir également type().

QListWidgetItem::QListWidgetItem(const QListWidgetItem &other)

Crée une copie de ` other`. Notez que ` type()` et ` listWidget()` ne sont pas copiés.

Cette fonction est utile lors de la réimplémentation de clone().

Voir également data() et flags().

[virtual noexcept] QListWidgetItem::~QListWidgetItem()

Supprime l'élément de la liste.

QBrush QListWidgetItem::background() const

Renvoie le pinceau utilisé pour afficher l'arrière-plan de l'élément de la liste.

Voir aussi setBackground() et foreground().

Qt::CheckState QListWidgetItem::checkState() const

Renvoie l'état de sélection de l'élément de la liste (voir Qt::CheckState).

Voir également setCheckState() et flags().

[virtual] QListWidgetItem *QListWidgetItem::clone() const

Crée une copie exacte de l'élément.

[virtual] QVariant QListWidgetItem::data(int role) const

Renvoie les données de l'élément pour un « role » donné. Réimplémentez cette fonction si vous avez besoin de rôles supplémentaires ou d'un comportement particulier pour certains rôles.

Voir également Qt::ItemDataRole et setData().

Qt::ItemFlags QListWidgetItem::flags() const

Renvoie les indicateurs associés à cet élément (voir Qt::ItemFlags).

Voir également setFlags().

QFont QListWidgetItem::font() const

Renvoie la police utilisée pour afficher le texte de cet élément de liste.

Voir aussi setFont().

QBrush QListWidgetItem::foreground() const

Renvoie le pinceau utilisé pour afficher le premier plan de l'élément de liste (par exemple, le texte).

Voir également setForeground() et background().

QIcon QListWidgetItem::icon() const

Renvoie l'icône de l'élément de la liste.

Voir également setIcon() et iconSize.

bool QListWidgetItem::isHidden() const

Renvoie « true » si l'élément est masqué ; sinon, renvoie « false ».

Voir également setHidden().

bool QListWidgetItem::isSelected() const

Renvoie « true » si l'élément est sélectionné ; sinon, renvoie « false ».

Voir également setSelected().

QListWidget *QListWidgetItem::listWidget() const

Renvoie le widget de liste contenant l'élément.

[virtual] void QListWidgetItem::read(QDataStream &in)

Lit l'élément à partir du flux in.

Voir également write().

void QListWidgetItem::setBackground(const QBrush &brush)

Définit le pinceau d'arrière-plan de l'élément de la liste sur l'brush spécifié. La définition d'un pinceau créé par défaut permettra à la vue d'utiliser la couleur par défaut du style.

Voir également background() et setForeground().

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

Définit l'état de sélection de l'élément de la liste sur « state ».

Voir également checkState().

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

Définit les données d'une « role » donnée sur la valeur indiquée dans « value ». Réimplémentez cette fonction si vous avez besoin de rôles supplémentaires ou d'un comportement particulier pour certains rôles.

Remarque : l’implémentation par défaut considère que ` Qt::EditRole ` et ` Qt::DisplayRole ` font référence aux mêmes données.

Voir également Qt::ItemDataRole et data().

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

Définit les indicateurs de l'élément de la liste sur « flags ».

Voir également flags() et Qt::ItemFlags.

void QListWidgetItem::setFont(const QFont &font)

Définit la police utilisée pour l'affichage de l'élément sur la police spécifiée font.

Voir également font().

void QListWidgetItem::setForeground(const QBrush &brush)

Définit le pinceau de premier plan de l'élément de liste sur l'brush spécifié. La définition d'un pinceau créé par défaut permettra à la vue d'utiliser la couleur par défaut du style.

Voir également foreground() et setBackground().

void QListWidgetItem::setHidden(bool hide)

Masque l'élément si la valeur de « hide » est « true » ; sinon, l'affiche.

Voir également isHidden().

void QListWidgetItem::setIcon(const QIcon &icon)

Définit l'icône de l'élément de liste sur l'icon fournie.

Voir également icon(), text() et iconSize.

void QListWidgetItem::setSelected(bool select)

Définit l'état sélectionné de l'élément sur « select ».

Voir également isSelected().

void QListWidgetItem::setSizeHint(const QSize &size)

Définit l'indication de taille de l'élément de liste sur size. Si aucune indication de taille n'est définie ou si size n'est pas valide, le délégué de l'élément calculera l'indication de taille en fonction des données de l'élément.

Voir également sizeHint().

void QListWidgetItem::setStatusTip(const QString &statusTip)

Définit l'info-bulle de l'élément de la liste sur le texte spécifié par statusTip. QListWidget La fonctionnalité « mouseTracking » doit être activée pour que cette fonctionnalité fonctionne.

Voir également statusTip(), setToolTip(), setWhatsThis() et QWidget::setMouseTracking().

void QListWidgetItem::setText(const QString &text)

Définit le texte des éléments du widget de liste selon l'text.

Voir également text().

[since 6.4] void QListWidgetItem::setTextAlignment(Qt::Alignment alignment)

Définit l'alignement du texte de l'élément de liste sur « alignment ».

Cette fonction a été introduite dans Qt 6.4.

Voir également ` textAlignment()`.

void QListWidgetItem::setToolTip(const QString &toolTip)

Définit l'info-bulle de l'élément de la liste sur le texte spécifié par toolTip.

Voir également toolTip(), setStatusTip() et setWhatsThis().

void QListWidgetItem::setWhatsThis(const QString &whatsThis)

Définit l'aide « Qu'est-ce que c'est ? » de l'élément de la liste sur le texte spécifié par whatsThis.

Voir également whatsThis(), setStatusTip() et setToolTip().

QSize QListWidgetItem::sizeHint() const

Renvoie la valeur de « size hint » définie pour l'élément de la liste.

Voir aussi setSizeHint().

QString QListWidgetItem::statusTip() const

Renvoie l'info-bulle relative au statut de l'élément de la liste.

Voir aussi setStatusTip().

QString QListWidgetItem::text() const

Renvoie le texte de l'élément de la liste.

Voir aussi setText().

int QListWidgetItem::textAlignment() const

Renvoie l'alignement du texte pour l'élément de la liste.

Remarque : pour des raisons historiques,cette fonction renvoie un entier. Elle sera corrigée pour renvoyer « Qt::Alignment » dans Qt 7.

Voir également ` setTextAlignment()` et ` Qt::Alignment`.

QString QListWidgetItem::toolTip() const

Renvoie l'info-bulle de l'élément de la liste.

Voir également setToolTip(), statusTip() et whatsThis().

int QListWidgetItem::type() const

Renvoie le type transmis au constructeur ` QListWidgetItem `.

QString QListWidgetItem::whatsThis() const

Renvoie le texte d'aide « Qu'est-ce que c'est ? » de l'élément de la liste.

Voir également setWhatsThis(), statusTip() et toolTip().

[virtual] void QListWidgetItem::write(QDataStream &out) const

Écrit l'élément dans le flux out.

Voir également read().

[virtual] bool QListWidgetItem::operator<(const QListWidgetItem &other) const

Renvoie « true » si le texte de cet élément est inférieur à celui de l'élém other; sinon, renvoie « false ».

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

Attribue les données et les indicateurs de ` other` à cet élément. Notez que ` type()` et ` listWidget()` ne sont pas copiés.

Cette fonction est utile lors de la réimplémentation de ` clone()`.

Voir également data() et flags().

Éléments non membres associés

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

Écrit l'élément « item » du widget de liste dans le flux « out ».

Cet opérateur utilise la fonction QListWidgetItem::write().

Voir également Sérialisation des types de données Qt.

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

Lit un élément du widget de liste à partir du flux in et l'enregistre dans item.

Cet opérateur utilise la fonction QListWidgetItem::read().

Voir également Sérialisation des types de données Qt.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.