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 : |
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 ¤t, 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

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
| Constante | Valeur | Description |
|---|---|---|
QListView::LeftToRight | 0 | Les éléments sont disposés dans la vue de gauche à droite. |
QListView::TopToBottom | 1 | Les éléments sont disposés dans la vue de haut en bas. |
enum QListView::LayoutMode
| Constante | Valeur | Description |
|---|---|---|
QListView::SinglePass | 0 | Les articles sont disposés en une seule fois. |
QListView::Batched | 1 | Les éléments sont disposés par lots de batchSize éléments. |
Voir également batchSize.
enum QListView::Movement
| Constante | Valeur | Description |
|---|---|---|
QListView::Static | 0 | Les éléments ne peuvent pas être déplacés par l'utilisateur. |
QListView::Free | 1 | Les éléments peuvent être déplacés librement par l'utilisateur. |
QListView::Snap | 2 | Les éléments s'accrochent à la grille spécifiée lorsqu'ils sont déplacés ; voir setGridSize(). |
enum QListView::ResizeMode
| Constante | Valeur | Description |
|---|---|---|
QListView::Fixed | 0 | Les éléments ne seront disposés que la première fois que la vue est affichée. |
QListView::Adjust | 1 | Les éléments seront disposés chaque fois que la vue sera redimensionnée. |
enum QListView::ViewMode
| Constante | Valeur | Description |
|---|---|---|
QListView::ListMode | 0 | Les éléments sont disposés selon le flux TopToBottom, avec une petite taille et un mouvement statique. |
QListView::IconMode | 1 | Les é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 ¤t, const QModelIndex &previous)
Réimplémente : QAbstractItemView::currentChanged(const QModelIndex ¤t, 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.