Sur cette page

QListWidgetItem Class

La classe QListWidgetItem fournit un élément à utiliser avec la classe de vue d'élément QListWidget. Plus d'informations...

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 seul élément d'une liste QListWidget. Chaque élément peut contenir plusieurs informations et les afficher de manière appropriée.

Les classes de commodité pour l'affichage des éléments utilisent une interface classique basée sur les éléments plutôt qu'une approche modèle/vue pure. Pour obtenir un widget de vue de liste plus souple, il est préférable d'utiliser la classe QListView avec un modèle standard.

Les éléments d'une liste peuvent être insérés automatiquement dans une liste, lorsqu'ils sont construits, 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 dans une liste à l'aide de QListWidget::insertItem().

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

Par défaut, les éléments sont activés, sélectionnables, vérifiables et peuvent être la source d'opérations de glisser-déposer.

Les drapeaux de chaque élément peuvent être modifiés en appelant setFlags() avec la valeur appropriée (voir Qt::ItemFlags). Les éléments vérifiables peuvent être vérifiés, décochés et partiellement vérifiés à l'aide de la fonction setCheckState(). La fonction checkState() correspondante indique l'état de contrôle actuel de l'élément.

La fonction isHidden() peut être utilisée pour déterminer si l'élément est caché. Pour masquer un élément, utilisez la fonction setHidden().

Sous-classement

Lorsque l'on sous-classe QListWidgetItem pour fournir des éléments personnalisés, il est possible de définir de nouveaux types permettant de les distinguer des éléments standard. Pour les sous-classes qui ont besoin de cette fonctionnalité, assurez-vous d'appeler le constructeur de la classe de base avec une valeur de nouveau type égale ou supérieure à UserType, dans votre constructeur.

Voir également QListWidget, Model/View Programming, QTreeWidgetItem, et QTableWidgetItem.

Documentation sur les types de membres

enum QListWidgetItem::ItemType

Cette énumération décrit les types utilisés pour décrire les éléments des widgets de liste.

ConstanteValeurDescription
QListWidgetItem::Type0Type par défaut des éléments de 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 d'utilisateurs dans les sous-classes de QListWidgetItem pour garantir un traitement spécial des éléments personnalisés.

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'adresse type spécifiée avec l'adresse parent donnée. Si parent n'est pas spécifié, l'élément devra être inséré dans un widget de liste avec 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é puisque le modèle appellera la méthode de l'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 aussi type().

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

Construit un élément de widget de liste vide de l'adresse type spécifiée avec les adresses text et parent. Si le parent n'est pas spécifié, l'élément devra être inséré dans un widget de liste avec 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é puisque le modèle appellera la méthode de l'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 aussi 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 du modèle type spécifié avec les éléments icon, text et parent. 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é puisque le modèle appellera la méthode de l'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 aussi type().

QListWidgetItem::QListWidgetItem(const QListWidgetItem &other)

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

Cette fonction est utile pour réimplémenter clone().

Voir aussi data() et flags().

[virtual noexcept] QListWidgetItem::~QListWidgetItem()

Détruit l'élément de la liste.

QBrush QListWidgetItem::background() const

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

Voir aussi setBackground() et foreground().

Qt::CheckState QListWidgetItem::checkState() const

Renvoie l'état vérifié 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 spécial pour certains rôles.

Voir aussi Qt::ItemDataRole et setData().

Qt::ItemFlags QListWidgetItem::flags() const

Renvoie les drapeaux de 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 la brosse utilisée pour afficher l'avant-plan de l'élément de liste (par exemple, le texte).

Voir aussi setForeground() et background().

QIcon QListWidgetItem::icon() const

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

Voir aussi setIcon() et iconSize.

bool QListWidgetItem::isHidden() const

Renvoie true si l'élément est caché ; sinon, renvoie false.

Voir aussi setHidden().

bool QListWidgetItem::isSelected() const

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

Voir aussi setSelected().

QListWidget *QListWidgetItem::listWidget() const

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

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

Lit l'élément dans le flux in.

Voir aussi write().

void QListWidgetItem::setBackground(const QBrush &brush)

Définit la brosse d'arrière-plan de l'élément de liste à l'adresse brush. La définition d'une brosse construite par défaut permet à 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 vérification de l'élément de la liste à state.

Voir aussi checkState().

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

Définit les données pour un role donné vers le value donné. Réimplémentez cette fonction si vous avez besoin de rôles supplémentaires ou d'un comportement spécial pour certains rôles.

Remarque : l'implémentation par défaut considère que Qt::EditRole et Qt::DisplayRole renvoient aux mêmes données.

Voir aussi Qt::ItemDataRole et data().

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

Définit les drapeaux de l'élément de la liste à flags.

Voir aussi flags() et Qt::ItemFlags.

void QListWidgetItem::setFont(const QFont &font)

Définit la police utilisée pour peindre l'élément à la valeur donnée font.

Voir aussi font().

void QListWidgetItem::setForeground(const QBrush &brush)

Définit la brosse d'avant-plan de l'élément de liste à l'adresse brush. La définition d'une brosse construite par défaut permet à la vue d'utiliser la couleur par défaut du style.

Voir également foreground() et setBackground().

void QListWidgetItem::setHidden(bool hide)

Cache l'élément si hide est vrai ; sinon, affiche l'élément.

Voir également isHidden().

void QListWidgetItem::setIcon(const QIcon &icon)

Définit l'icône de l'élément de la liste à l'adresse icon.

Voir aussi icon(), text() et iconSize.

void QListWidgetItem::setSelected(bool select)

Définit l'état sélectionné de l'élément à select.

Voir aussi isSelected().

void QListWidgetItem::setSizeHint(const QSize &size)

Définit l'indice de taille pour l'élément de la liste à être size. Si aucun indice de taille n'est défini ou si size n'est pas valide, le délégué de l'élément calculera l'indice de taille en fonction des données de l'élément.

Voir également sizeHint().

void QListWidgetItem::setStatusTip(const QString &statusTip)

Définit l'astuce d'état pour l'élément de liste au texte spécifié par statusTip. QListWidget mouseTracking doit être activé pour que cette fonctionnalité fonctionne.

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

void QListWidgetItem::setText(const QString &text)

Fixe le texte des éléments du widget de liste à la valeur donnée text.

Voir aussi text().

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

Définit l'alignement du texte de l'élément de liste à alignment.

Cette fonction a été introduite dans Qt 6.4.

Voir aussi textAlignment().

void QListWidgetItem::setToolTip(const QString &toolTip)

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

Voir aussi toolTip(), setStatusTip() et setWhatsThis().

void QListWidgetItem::setWhatsThis(const QString &whatsThis)

Définit l'aide "Qu'est-ce que c'est ?" pour l'élément de liste au texte spécifié par whatsThis.

Voir aussi whatsThis(), setStatusTip() et setToolTip().

QSize QListWidgetItem::sizeHint() const

Renvoie le jeu d'indices de taille pour l'élément de la liste.

Voir aussi setSizeHint().

QString QListWidgetItem::statusTip() const

Renvoie l'info-bulle 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 également setText().

int QListWidgetItem::textAlignment() const

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

Note : Cette fonction renvoie un int pour des raisons historiques. Elle sera corrigée pour retourner Qt::Alignment dans Qt 7.

Voir aussi setTextAlignment() et Qt::Alignment.

QString QListWidgetItem::toolTip() const

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

Voir aussi setToolTip(), statusTip() et whatsThis().

int QListWidgetItem::type() const

Renvoie le type transmis au constructeur de QListWidgetItem.

QString QListWidgetItem::whatsThis() const

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

Voir aussi 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 au texte de l'élément other; sinon, renvoie false.

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

Attribue les données et les drapeaux 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 aussi data() et flags().

Non-membres apparentés

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

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

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

Voir aussi Serializing Qt Data Types (Sérialisation des types de données Qt).

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

Lit un élément de widget de liste du flux in dans item.

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

Voir aussi Serializing Qt Data Types (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.