Sur cette page

QListView Class

La classe QListView permet d'afficher une liste ou une icône sur un modèle. Plus d'informations...

En-tête : #include <QListView>
CMake : find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake : QT += widgets
Hérite : QAbstractItemView
Hérités par :

QHelpIndexWidget, QListWidget, et QUndoView

Types publics

enum Flow { LeftToRight, TopToBottom }
enum LayoutMode { SinglePass, Batched }
enum Movement { Static, Free, Snap }
enum ResizeMode { Fixed, Adjust }
enum ViewMode { ListMode, IconMode }

Propriétés

Fonctions publiques

QListView(QWidget *parent = nullptr)
virtual ~QListView()
int batchSize() const
void clearPropertyFlags()
QListView::Flow flow() const
QSize gridSize() const
bool isRowHidden(int row) const
bool isSelectionRectVisible() const
bool isWrapping() const
Qt::Alignment itemAlignment() const
QListView::LayoutMode layoutMode() const
int modelColumn() const
QListView::Movement movement() const
QListView::ResizeMode resizeMode() const
void setBatchSize(int batchSize)
void setFlow(QListView::Flow flow)
void setGridSize(const QSize &size)
void setItemAlignment(Qt::Alignment alignment)
void setLayoutMode(QListView::LayoutMode mode)
void setModelColumn(int column)
void setMovement(QListView::Movement movement)
void setResizeMode(QListView::ResizeMode mode)
void setRowHidden(int row, bool hide)
void setSelectionRectVisible(bool show)
void setSpacing(int space)
void setUniformItemSizes(bool enable)
void setViewMode(QListView::ViewMode mode)
void setWordWrap(bool on)
void setWrapping(bool enable)
int spacing() const
bool uniformItemSizes() const
QListView::ViewMode viewMode() const
bool wordWrap() const

Fonctions publiques réimplémentées

virtual QModelIndex indexAt(const QPoint &p) const override
virtual void scrollTo(const QModelIndex &index, QAbstractItemView::ScrollHint hint = EnsureVisible) override
virtual void setRootIndex(const QModelIndex &index) override
virtual QRect visualRect(const QModelIndex &index) const override

Signaux

void indexesMoved(const QModelIndexList &indexes)

Fonctions protégées

QRect rectForIndex(const QModelIndex &index) const
void setPositionForIndex(const QPoint &position, const QModelIndex &index)

Fonctions protégées réimplémentées

virtual void currentChanged(const QModelIndex &current, const QModelIndex &previous) override
virtual void dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles = QList<int>()) override
virtual void dragLeaveEvent(QDragLeaveEvent *e) override
virtual void dragMoveEvent(QDragMoveEvent *e) override
virtual void dropEvent(QDropEvent *event) override
virtual bool event(QEvent *e) override
virtual int horizontalOffset() const override
virtual void initViewItemOption(QStyleOptionViewItem *option) const override
virtual bool isIndexHidden(const QModelIndex &index) const override
virtual void mouseMoveEvent(QMouseEvent *e) override
virtual void mouseReleaseEvent(QMouseEvent *e) override
virtual QModelIndex moveCursor(QAbstractItemView::CursorAction cursorAction, Qt::KeyboardModifiers modifiers) override
virtual void paintEvent(QPaintEvent *e) override
virtual void resizeEvent(QResizeEvent *e) override
virtual void rowsAboutToBeRemoved(const QModelIndex &parent, int start, int end) override
virtual void rowsInserted(const QModelIndex &parent, int start, int end) override
virtual void scrollContentsBy(int dx, int dy) override
virtual QModelIndexList selectedIndexes() const override
virtual void selectionChanged(const QItemSelection &selected, const QItemSelection &deselected) override
virtual void setSelection(const QRect &rect, QItemSelectionModel::SelectionFlags command) override
virtual void startDrag(Qt::DropActions supportedActions) override
virtual void timerEvent(QTimerEvent *e) override
virtual void updateGeometries() override
virtual int verticalOffset() const override
virtual QSize viewportSizeHint() const override
virtual QRegion visualRegionForSelection(const QItemSelection &selection) const override
virtual void wheelEvent(QWheelEvent *e) override

Description détaillée

Liste des icônes météo

Une QListView présente les éléments stockés dans un modèle, soit sous la forme d'une simple liste non hiérarchique, soit sous la forme d'une collection d'icônes. Cette classe est utilisée pour fournir des listes et des vues d'icônes qui étaient auparavant fournies par les classes QListBox et QIconView, mais en utilisant l'approche plus flexible fournie par l'architecture modèle/vue de Qt.

La classe QListView est l'une des classes Modèle/Vue et fait partie du cadre modèle/vue de Qt.

Cette vue n'affiche pas les en-têtes horizontaux ou verticaux ; pour afficher une liste d'éléments avec un en-tête horizontal, utilisez plutôt QTreeView.

QListView met en œuvre les interfaces définies par la classe QAbstractItemView pour lui permettre d'afficher les données fournies par les modèles dérivés de la classe QAbstractItemModel.

Les éléments d'une vue de liste peuvent être affichés selon l'un des deux modes d'affichage : Dans ListMode, les éléments sont affichés sous la forme d'une simple liste ; dans IconMode, la vue en liste prend la forme d'une vue en icônes dans laquelle les éléments sont affichés avec des icônes comme des fichiers dans un gestionnaire de fichiers. Par défaut, l'affichage de la liste se fait sur ListMode. Pour modifier le mode d'affichage, utilisez la fonction setViewMode(), et pour déterminer le mode d'affichage actuel, utilisez viewMode().

Les éléments de ces vues sont disposés dans la direction spécifiée par la fonction flow() de la vue en liste. Les éléments peuvent être fixés en place ou autorisés à se déplacer, en fonction de l'état de la vue movement().

Si les éléments du modèle ne peuvent pas être entièrement disposés dans le sens du flux, ils peuvent être enveloppés à la limite du widget de la vue ; cela dépend de isWrapping(). Cette propriété est utile lorsque les éléments sont représentés par une vue iconique.

Les propriétés resizeMode() et layoutMode() déterminent quand et comment les éléments sont disposés. Les éléments sont espacés en fonction de leur spacing() et peuvent exister à l'intérieur d'une grille fictive dont la taille est spécifiée par gridSize(). Les éléments peuvent être présentés sous la forme de grandes ou de petites icônes en fonction de leur iconSize().

Amélioration des performances

Il est possible de donner à la vue des indications sur les données qu'elle traite afin d'améliorer ses performances lors de l'affichage d'un grand nombre d'éléments. Une approche qui peut être adoptée pour les vues destinées à afficher des éléments de taille égale consiste à attribuer la valeur true à la propriété uniformItemSizes.

Voir aussi Classes de vues, QTreeView, QTableView, et QListWidget.

Documentation sur les types de membres

enum QListView::Flow

ConstanteValeurDescription
QListView::LeftToRight0Les éléments sont disposés dans la vue de gauche à droite.
QListView::TopToBottom1Les éléments sont disposés dans la vue de haut en bas.

enum QListView::LayoutMode

ConstanteValeurDescription
QListView::SinglePass0Les articles sont disposés en une seule fois.
QListView::Batched1Les éléments sont disposés par lots de batchSize éléments.

Voir également batchSize.

enum QListView::Movement

ConstanteValeurDescription
QListView::Static0Les éléments ne peuvent pas être déplacés par l'utilisateur.
QListView::Free1Les éléments peuvent être déplacés librement par l'utilisateur.
QListView::Snap2Les éléments s'accrochent à la grille spécifiée lorsqu'ils sont déplacés ; voir setGridSize().

enum QListView::ResizeMode

ConstanteValeurDescription
QListView::Fixed0Les éléments ne seront disposés que la première fois que la vue est affichée.
QListView::Adjust1Les éléments seront disposés chaque fois que la vue sera redimensionnée.

enum QListView::ViewMode

ConstanteValeurDescription
QListView::ListMode0Les éléments sont disposés selon le flux TopToBottom, avec une petite taille et un mouvement statique.
QListView::IconMode1Les éléments sont disposés en utilisant le flux LeftToRight, avec une grande taille et un mouvement libre.

Propriété Documentation

batchSize : int

Cette propriété indique le nombre d'articles disposés dans chaque lot si layoutMode est défini sur Batched.

La valeur par défaut est 100.

Fonctions d'accès :

int batchSize() const
void setBatchSize(int batchSize)

flow : Flow

Cette propriété indique le sens dans lequel les éléments doivent être disposés.

Si la valeur de cette propriété est LeftToRight, les éléments seront disposés de gauche à droite. Si la propriété isWrapping est true, la mise en page s'enroulera lorsqu'elle atteindra le côté droit de la zone visible. Si cette propriété est TopToBottom, les éléments seront disposés à partir du haut de la zone visible et s'enrouleront lorsqu'ils atteindront le bas.

Si vous définissez cette propriété lorsque la vue est visible, les éléments seront à nouveau disposés.

Par défaut, cette propriété est définie sur TopToBottom.

Fonctions d'accès :

QListView::Flow flow() const
void setFlow(QListView::Flow flow)

Voir également viewMode.

gridSize : QSize

Cette propriété définit la taille de la grille de présentation

Cette propriété indique la taille de la grille dans laquelle les éléments sont disposés. La valeur par défaut est une taille vide, ce qui signifie qu'il n'y a pas de grille et que la mise en page n'est pas effectuée dans une grille. La définition de cette propriété à une taille non vide active la disposition en grille. (Lorsqu'une disposition en grille est en vigueur, la propriété spacing est ignorée).

La définition de cette propriété lorsque la vue est visible entraîne une nouvelle disposition des éléments.

Fonctions d'accès :

QSize gridSize() const
void setGridSize(const QSize &size)

Voir également viewMode.

isWrapping : bool

Cette propriété indique si la mise en page des éléments doit s'étendre.

Cette propriété indique si la mise en page doit s'enrouler lorsqu'il n'y a plus d'espace dans la zone visible. Le moment où la disposition s'enroule dépend de la propriété flow.

Si vous définissez cette propriété lorsque la vue est visible, les éléments seront à nouveau disposés.

Par défaut, cette propriété est false.

Fonctions d'accès :

bool isWrapping() const
void setWrapping(bool enable)

Voir également viewMode.

itemAlignment : Qt::Alignment

Cette propriété définit l'alignement de chaque élément dans sa cellule

Cette propriété n'est prise en charge que sur le site ListMode avec le flux TopToBottom et avec l'activation de l'habillage. L'alignement par défaut est 0, ce qui signifie qu'un élément remplit entièrement sa cellule.

Fonctions d'accès :

Qt::Alignment itemAlignment() const
void setItemAlignment(Qt::Alignment alignment)

layoutMode : LayoutMode

détermine si la mise en page des éléments doit être immédiate ou différée.

Cette propriété contient le mode de présentation des éléments. Lorsque le mode est SinglePass (valeur par défaut), les éléments sont disposés en une seule fois. Lorsque le mode est Batched, les éléments sont disposés par lots de batchSize éléments, pendant le traitement des événements. Cela permet de visualiser et d'interagir instantanément avec les éléments visibles pendant que les autres sont mis en page.

Fonctions d'accès :

QListView::LayoutMode layoutMode() const
void setLayoutMode(QListView::LayoutMode mode)

Voir également viewMode.

modelColumn : int

Cette propriété indique la colonne du modèle qui est visible

Par défaut, cette propriété contient 0, ce qui indique que la première colonne du modèle sera affichée.

Fonctions d'accès :

int modelColumn() const
void setModelColumn(int column)

movement : Movement

Cette propriété indique si les éléments peuvent être déplacés librement, s'ils sont accrochés à une grille ou s'ils ne peuvent pas être déplacés du tout.

Cette propriété détermine comment l'utilisateur peut déplacer les éléments dans la vue. Static signifie que les éléments ne peuvent pas être déplacés par l'utilisateur. Free signifie que l'utilisateur peut faire glisser et déposer les éléments à n'importe quelle position dans la vue. Snap signifie que l'utilisateur peut faire glisser et déposer les éléments, mais uniquement aux positions d'une grille fictive signifiée par la propriété gridSize.

La définition de cette propriété lorsque la vue est visible entraînera une nouvelle disposition des éléments.

Par défaut, cette propriété est définie sur Static.

Fonctions d'accès :

QListView::Movement movement() const
void setMovement(QListView::Movement movement)

Voir également gridSize, resizeMode, et viewMode.

resizeMode : ResizeMode

Cette propriété indique si les éléments sont redisposés lorsque la vue est redimensionnée.

Si la valeur de cette propriété est Adjust, les éléments seront à nouveau disposés lorsque la vue sera redimensionnée. Si la valeur est Fixed, les éléments ne seront pas redisposés lorsque la vue sera redimensionnée.

Par défaut, cette propriété est définie sur Fixed.

Fonctions d'accès :

QListView::ResizeMode resizeMode() const
void setResizeMode(QListView::ResizeMode mode)

Voir également movement, gridSize, et viewMode.

selectionRectVisible : bool

si le rectangle de sélection doit être visible

Si cette propriété vaut true, le rectangle de sélection est visible ; sinon, il est caché.

Note : Le rectangle de sélection ne sera visible que si le mode de sélection est dans un mode où plus d'un élément peut être sélectionné ; c'est-à-dire qu'il ne dessinera pas de rectangle de sélection si le mode de sélection est QAbstractItemView::SingleSelection.

Par défaut, cette propriété a la valeur false.

Fonctions d'accès :

bool isSelectionRectVisible() const
void setSelectionRectVisible(bool show)

spacing : int

Cette propriété définit l'espace autour des éléments de la mise en page

Cette propriété indique la taille de l'espace vide autour d'un élément de la mise en page.

En définissant cette propriété lorsque la vue est visible, les éléments seront à nouveau disposés.

Par défaut, cette propriété contient une valeur de 0.

Fonctions d'accès :

int spacing() const
void setSpacing(int space)

Voir aussi viewMode.

uniformItemSizes : bool

Cette propriété indique si tous les éléments de la vue en liste ont la même taille

Cette propriété ne doit être définie à true que s'il est garanti que tous les éléments de la vue ont la même taille. Cela permet à la vue d'effectuer certaines optimisations à des fins de performance.

Par défaut, cette propriété vaut false.

Fonctions d'accès :

bool uniformItemSizes() const
void setUniformItemSizes(bool enable)

viewMode : ViewMode

Cette propriété définit le mode d'affichage du site QListView.

Cette propriété modifiera les autres propriétés non définies pour les rendre conformes au mode d'affichage défini. QListView Les propriétés spécifiques qui ont déjà été définies ne seront pas modifiées, à moins que clearPropertyFlags() n'ait été appelé.

La définition du mode d'affichage activera ou désactivera le glisser-déposer en fonction du mouvement sélectionné. Pour ListMode, le mouvement par défaut est Static (glisser-déposer désactivé) ; pour IconMode, le mouvement par défaut est Free (glisser-déposer activé).

Fonctions d'accès :

QListView::ViewMode viewMode() const
void setViewMode(QListView::ViewMode mode)

Voir aussi isWrapping, spacing, gridSize, flow, movement, et resizeMode.

wordWrap : bool

Cette propriété définit la politique d'habillage du texte de l'élément

Si cette propriété vaut true, le texte de l'élément est enveloppé si nécessaire aux coupures de mots ; sinon, il n'est pas enveloppé du tout. Cette propriété vaut false par défaut.

Veuillez noter que même si l'habillage est activé, la cellule ne sera pas agrandie pour faire de la place au texte. Elle imprimera des points de suspension pour le texte qui ne peut pas être affiché, conformément à la vue textElideMode.

Fonctions d'accès :

bool wordWrap() const
void setWordWrap(bool on)

Documentation des fonctions membres

[explicit] QListView::QListView(QWidget *parent = nullptr)

Crée une nouvelle QListView avec l'adresse parent pour afficher un modèle. Utilisez setModel() pour définir le modèle.

[virtual noexcept] QListView::~QListView()

Détruit la vue.

void QListView::clearPropertyFlags()

Efface les drapeaux de propriété spécifiques à QListView. Voir viewMode.

Les propriétés héritées de QAbstractItemView ne sont pas couvertes par les drapeaux de propriétés. En particulier, dragEnabled et acceptsDrops sont calculées par QListView lors de l'appel à setMovement() ou setViewMode().

[override virtual protected] void QListView::currentChanged(const QModelIndex &current, const QModelIndex &previous)

Réimplémente : QAbstractItemView::currentChanged(const QModelIndex &current, const QModelIndex &previous).

[override virtual protected] void QListView::dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles = QList<int>())

Réimplémente : QAbstractItemView::dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles).

[override virtual protected] void QListView::dragLeaveEvent(QDragLeaveEvent *e)

Réimplémente : QAbstractItemView::dragLeaveEvent(QDragLeaveEvent *event).

[override virtual protected] void QListView::dragMoveEvent(QDragMoveEvent *e)

Réimplémente : QAbstractItemView::dragMoveEvent(QDragMoveEvent *event).

[override virtual protected] void QListView::dropEvent(QDropEvent *event)

Réimplémente : QAbstractItemView::dropEvent(QDropEvent *event).

[override virtual protected] bool QListView::event(QEvent *e)

Réimplémente : QAbstractItemView::event(QEvent *event).

[override virtual protected] int QListView::horizontalOffset() const

Réimplémente : QAbstractItemView::horizontalOffset() const.

[override virtual] QModelIndex QListView::indexAt(const QPoint &p) const

Réimplémente : QAbstractItemView::indexAt(const QPoint &point) const.

[signal] void QListView::indexesMoved(const QModelIndexList &indexes)

Ce signal est émis lorsque les indexes spécifiés sont déplacés dans la vue.

[override virtual protected] void QListView::initViewItemOption(QStyleOptionViewItem *option) const

Réimplémente : QAbstractItemView::initViewItemOption(QStyleOptionViewItem *option) const.

[override virtual protected] bool QListView::isIndexHidden(const QModelIndex &index) const

Réimplémente : QAbstractItemView::isIndexHidden(const QModelIndex &index) const.

bool QListView::isRowHidden(int row) const

Renvoie true si row est caché ; sinon, renvoie false.

[override virtual protected] void QListView::mouseMoveEvent(QMouseEvent *e)

Réimplémente : QAbstractItemView::mouseMoveEvent(QMouseEvent *event).

[override virtual protected] void QListView::mouseReleaseEvent(QMouseEvent *e)

Réimplémente : QAbstractItemView::mouseReleaseEvent(QMouseEvent *event).

[override virtual protected] QModelIndex QListView::moveCursor(QAbstractItemView::CursorAction cursorAction, Qt::KeyboardModifiers modifiers)

Réimplémente : QAbstractItemView::moveCursor(QAbstractItemView::CursorAction cursorAction, Qt::KeyboardModifiers modifiers).

[override virtual protected] void QListView::paintEvent(QPaintEvent *e)

Réimplémente : QAbstractScrollArea::paintEvent(QPaintEvent *event).

[protected] QRect QListView::rectForIndex(const QModelIndex &index) const

Renvoie le rectangle de l'élément situé à la position index dans le modèle. Le rectangle est en coordonnées de contenu.

Voir aussi visualRect().

[override virtual protected] void QListView::resizeEvent(QResizeEvent *e)

Réimplémente : QAbstractItemView::resizeEvent(QResizeEvent *event).

[override virtual protected] void QListView::rowsAboutToBeRemoved(const QModelIndex &parent, int start, int end)

Réimplémente : QAbstractItemView::rowsAboutToBeRemoved(const QModelIndex &parent, int start, int end).

[override virtual protected] void QListView::rowsInserted(const QModelIndex &parent, int start, int end)

Réimplémente : QAbstractItemView::rowsInserted(const QModelIndex &parent, int start, int end).

[override virtual protected] void QListView::scrollContentsBy(int dx, int dy)

Réimplémente : QAbstractScrollArea::scrollContentsBy(int dx, int dy).

Fait défiler le contenu de la vue par dx et dy.

[override virtual] void QListView::scrollTo(const QModelIndex &index, QAbstractItemView::ScrollHint hint = EnsureVisible)

Réimplémente : QAbstractItemView::scrollTo(const QModelIndex &index, QAbstractItemView::ScrollHint hint).

[override virtual protected] QModelIndexList QListView::selectedIndexes() const

Réimplémente : QAbstractItemView::selectedIndexes() const.

[override virtual protected] void QListView::selectionChanged(const QItemSelection &selected, const QItemSelection &deselected)

Réimplémente : QAbstractItemView::selectionChanged(const QItemSelection &selected, const QItemSelection &deselected).

[protected] void QListView::setPositionForIndex(const QPoint &position, const QModelIndex &index)

Définit la position du contenu de l'élément à index dans le modèle à position. Si le mode de déplacement de la vue en liste est Statique ou si son mode d'affichage est ListView, cette fonction n'aura aucun effet.

[override virtual] void QListView::setRootIndex(const QModelIndex &index)

Réimplémente : QAbstractItemView::setRootIndex(const QModelIndex &index).

void QListView::setRowHidden(int row, bool hide)

Si hide est vrai, le site row sera caché, sinon le site row sera affiché.

Voir aussi isRowHidden().

[override virtual protected] void QListView::setSelection(const QRect &rect, QItemSelectionModel::SelectionFlags command)

Réimplémente : QAbstractItemView::setSelection(const QRect &rect, QItemSelectionModel::SelectionFlags flags).

[override virtual protected] void QListView::startDrag(Qt::DropActions supportedActions)

Réimplémente : QAbstractItemView::startDrag(Qt::DropActions supportedActions).

[override virtual protected] void QListView::timerEvent(QTimerEvent *e)

Réimplémente : QAbstractItemView::timerEvent(QTimerEvent *event).

[override virtual protected] void QListView::updateGeometries()

Réimplémente : QAbstractItemView::updateGeometries().

[override virtual protected] int QListView::verticalOffset() const

Réimplémente : QAbstractItemView::verticalOffset() const.

[override virtual protected] QSize QListView::viewportSizeHint() const

Réimplémente : QAbstractItemView::viewportSizeHint() const.

[override virtual] QRect QListView::visualRect(const QModelIndex &index) const

Réimplémente : QAbstractItemView::visualRect(const QModelIndex &index) const.

[override virtual protected] QRegion QListView::visualRegionForSelection(const QItemSelection &selection) const

Réimplémente : QAbstractItemView::visualRegionForSelection(const QItemSelection &selection) const.

Depuis la version 4.7, la région retournée ne contient que les rectangles intersectant (ou inclus dans) la fenêtre de visualisation.

[override virtual protected] void QListView::wheelEvent(QWheelEvent *e)

Réimplémente : QAbstractScrollArea::wheelEvent(QWheelEvent *e).

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