QListView Class

QListView 类为模型提供列表或图标视图。更多

Header: #include <QListView>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
继承: QAbstractItemView
继承于

QHelpIndexWidget,QListWidget, 以及QUndoView

公共类型

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

属性

公共函数

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

重新实现的公共函数

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

信号

void indexesMoved(const QModelIndexList &indexes)

受保护函数

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

重新实现的受保护函数

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

详细说明

QListView 可将存储在模型中的项目显示为简单的无层次列表或图标集合。该类用于提供以前由QListBoxQIconView 类提供的列表和图标视图,但使用 Qt 的模型/视图架构提供的更灵活的方法。

QListView 类是模型/视图类之一,也是 Qt模型/视图框架的一部分。

该视图不显示水平或垂直标题;要显示带有水平标题的项目列表,请使用QTreeView

QListView 实现了由QAbstractItemView 类定义的接口,允许它显示由源自QAbstractItemModel 类的模型提供的数据。

列表视图中的项目可使用两种视图模式之一显示:在ListMode 中,项目以简单列表的形式显示;在IconMode 中,列表视图以图标视图的形式显示,其中项目以图标显示,就像文件管理器中的文件一样。默认情况下,列表视图采用ListMode 。要更改视图模式,请使用setViewMode() 函数;要确定当前视图模式,请使用viewMode() 函数。

这些视图中的项目按照列表视图flow() 指定的方向排列。根据视图的movement() 状态,项目可以固定在原处,也可以允许移动。

如果模型中的项目不能完全按照流动方向布局,可以在视图 widget 的边界对其进行包装;这取决于isWrapping() 。当项目由图标视图表示时,该属性非常有用。

resizeMode() 和layoutMode() 规定了项目的布局方式和时间。项目的间距根据spacing() 确定,并可存在于由gridSize() 指定大小的概念网格中。项目可以根据其iconSize() 呈现为大图标或小图标。

提高性能

可以为视图处理的数据提供提示,以提高视图在显示大量项目时的性能。对于要显示相同大小项目的视图,可以采取的一种方法是将uniformItemSizes 属性设置为 true。

另请参阅 视图类QTreeViewQTableViewQListWidget

成员类型文档

enum QListView::Flow

常数说明
QListView::LeftToRight0项目在视图中从左到右排列。
QListView::TopToBottom1项目在视图中从上到下排列。

enum QListView::LayoutMode

常数说明
QListView::SinglePass0物品一次性摆放。
QListView::Batched1项目以batchSize 项目为批次排列。

另请参阅 batchSize

enum QListView::Movement

常数说明
QListView::Static0用户不能移动物品。
QListView::Free1用户可以自由移动项目。
QListView::Snap2移动时,项目会捕捉到指定的网格;请参阅setGridSize().

enum QListView::ResizeMode

常数说明
QListView::Fixed0只有在首次显示视图时才会布局项目。
QListView::Adjust1每次调整视图大小时,项目都会排布。

enum QListView::ViewMode

常数说明
QListView::ListMode0项目采用TopToBottom 流程布局,尺寸小,静态移动
QListView::IconMode1项目采用LeftToRight 流程布局,尺寸大,可自由移动

属性文档

batchSize : int

如果layoutMode 设置为Batched ,则此属性表示每批中的项目数。

默认值为 100。

访问功能:

int batchSize() const
void setBatchSize(int batchSize)

flow : Flow

此属性表示项目布局的方向。

如果该属性为LeftToRight ,项目将从左到右排列。如果isWrapping 属性为true ,则布局将在到达可视区域右侧时缠绕。如果此属性为TopToBottom ,项目将从可视区域的顶部开始布局,到达底部时进行包边。

在视图可见时设置此属性,将使项目重新布局。

默认情况下,此属性设置为TopToBottom

访问功能:

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

另请参阅 viewMode

gridSize : QSize

此属性表示布局网格的大小

该属性是项目布局网格的大小。默认值为空,表示没有网格,也不按网格进行布局。将此属性设置为非空大小后,就会开启网格布局。(当网格布局生效时,spacing 属性将被忽略)。

在视图可见时设置该属性将使项目重新布局。

访问功能:

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

另请参阅 viewMode

isWrapping : bool

该属性用于设置项目布局是否应换行。

当可见区域内没有更多空间时,布局是否应换行。布局包围的时间点取决于flow 属性。

在视图可见时设置该属性将导致项目重新布局。

默认情况下,该属性为false

访问功能:

bool isWrapping() const
void setWrapping(bool enable)

另请参阅 viewMode

itemAlignment : Qt::Alignment

此属性保存单元格中每个项目的对齐方式。

该属性仅在ListModeTopToBottom flow 和启用包装的情况下受支持。默认对齐方式为 0,这意味着项目完全填满其单元格。

访问函数:

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

layoutMode : LayoutMode

决定项目的布局是立即进行还是延迟进行。

该属性用于保存项目的布局模式。当模式为SinglePass (默认)时,项目会一次性全部布局。当模式为Batched 时,会在处理事件的同时分批布局batchSize 项目。这样就可以在布局其他项目的同时,即时查看可见项目并与之交互。

访问功能:

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

另请参阅 viewMode

modelColumn : int

此属性表示模型中可见的列

默认情况下,此属性包含 0,表示将显示模型中的第一列。

访问功能:

int modelColumn() const
void setModelColumn(int column)

movement : Movement

该属性决定了项目是可以自由移动、固定到网格上还是根本不能移动。

Static 表示用户不能移动项目。Free 表示用户可以将项目拖放到视图中的任何位置。Snap 表示用户可以拖放项目,但只能拖放到gridSize 属性所指的概念网格中的位置。

在视图可见时设置该属性将使项目重新布局。

默认情况下,该属性设置为Static

访问功能:

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

另请参阅 gridSize,resizeMode, 和viewMode

resizeMode : ResizeMode

此属性用于确定调整视图大小时是否重新布局项目。

如果该属性的值为Adjust ,则在调整视图大小时,项目将重新布局。如果该属性值为Fixed ,则调整视图大小时不会重新布局项目。

默认情况下,此属性设置为Fixed

访问功能:

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

另请参阅 movement,gridSize, 和viewMode

selectionRectVisible : bool

选择矩形是否可见

如果该属性为true ,则矩形选区可见;否则将隐藏。

注意: 只有当选择模式为可选择多个项目时,矩形选区才可见;也就是说,如果选择模式为QAbstractItemView::SingleSelection ,则不会绘制矩形选区。

默认情况下,此属性为false

访问功能:

bool isSelectionRectVisible() const
void setSelectionRectVisible(bool show)

spacing : int

该属性用于保存布局中项目周围的空间

该属性是布局中项目周围填充的空白空间的大小。

在视图可见时设置此属性将使项目重新布局。

默认情况下,此属性的值为 0。

访问功能:

int spacing() const
void setSpacing(int space)

另请参阅 viewMode

uniformItemSizes : bool

该属性用于确定列表视图中的所有项目是否具有相同的大小。

只有保证视图中的所有项目大小相同时,才应将此属性设置为 true。这样,视图就能为性能目的进行一些优化。

默认情况下,该属性为false

访问功能:

bool uniformItemSizes() const
void setUniformItemSizes(bool enable)

viewMode : ViewMode

该属性用于保存QListView 的视图模式。

该属性将改变其他未设置的属性,使其与已设置的视图模式一致。QListView除非调用clearPropertyFlags() ,否则不会更改已设置的特定属性。

设置视图模式将根据所选的移动方式启用或禁用拖放功能。对于ListMode ,默认运动模式为Static (禁用拖放);对于IconMode ,默认运动模式为Free (启用拖放)。

访问功能:

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

另请参阅 isWrapping,spacing,gridSize,flow,movementresizeMode

wordWrap : bool

该属性用于保存项目文本的文字包装策略

如果该属性为true ,则项目文本在必要时会在分词处进行封装;否则根本不会封装。该属性默认为false

请注意,即使启用了换行,单元格也不会因为要为文本腾出空间而展开。根据视图textElideMode ,无法显示的文本将打印省略号。

访问函数:

bool wordWrap() const
void setWordWrap(bool on)

成员函数文档

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

创建一个新的 QListView,使用给定的parent 查看模型。使用setModel() 设置模型。

[virtual noexcept] QListView::~QListView()

破坏景观。

void QListView::clearPropertyFlags()

清除QListView 特有的属性标志。请参见viewMode

属性标志不包括从QAbstractItemView 继承的属性。具体来说,在调用setMovement() 或setViewMode() 时,QListView 会计算dragEnabledacceptsDrops

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

重实现: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>())

重实现:QAbstractItemView::dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles)。

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

重实现:QAbstractItemView::dragLeaveEvent(QDragLeaveEvent *event).

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

重实现:QAbstractItemView::dragMoveEvent(QDragMoveEvent *event).

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

重实现:QAbstractItemView::dropEvent(QDropEvent *event).

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

重实现:QAbstractItemView::event(QEvent *event).

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

重实现:QAbstractItemView::horizontalOffset() const.

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

重实现:QAbstractItemView::indexAt(const QPoint &point) const.

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

当指定的indexes 在视图中移动时,会发出该信号。

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

重实现:QAbstractItemView::initViewItemOption(QStyleOptionViewItem *option) const.

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

重实现:QAbstractItemView::isIndexHidden(const QModelIndex &index) const.

bool QListView::isRowHidden(int row) const

如果row 隐藏,则返回true ;否则返回false

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

重实现:QAbstractItemView::mouseMoveEvent(QMouseEvent *event).

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

重实现:QAbstractItemView::mouseReleaseEvent(QMouseEvent *event).

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

重实现:QAbstractItemView::moveCursor(QAbstractItemView::CursorAction cursorAction, Qt::KeyboardModifiers modifiers)。

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

重实现:QAbstractScrollArea::paintEvent(QPaintEvent *event).

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

返回项目在模型中index 位置的矩形。该矩形的坐标为内容坐标。

另请参见 visualRect()。

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

重实现:QAbstractItemView::resizeEvent(QResizeEvent *event).

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

重实现:QAbstractItemView::rowsAboutToBeRemoved(const QModelIndex &parent, int start, int end)。

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

重实现:QAbstractItemView::rowsInserted(const QModelIndex &parent, int start, int end)。

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

重实现:QAbstractScrollArea::scrollContentsBy(int dx, int dy)。

通过dxdy 滚动视图内容。

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

重实现:QAbstractItemView::scrollTo(const QModelIndex &index, QAbstractItemView::ScrollHint hint)。

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

重实现:QAbstractItemView::selectedIndexes() const.

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

重实现:QAbstractItemView::selectionChanged(const QItemSelection &selected, const QItemSelection &deselected).

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

将位于index 的项目在模型中的内容位置设置为给定的position 。如果列表视图的移动模式为静态或视图模式为ListView ,此函数将不起作用。

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

重实现:QAbstractItemView::setRootIndex(const QModelIndex &index).

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

如果hide 为 true,给定的row 将被隐藏;否则row 将被显示。

另请参阅 isRowHidden().

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

重实现:QAbstractItemView::setSelection(const QRect &rect, QItemSelectionModel::SelectionFlags flags)。

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

重实现:QAbstractItemView::startDrag(Qt::DropActions supportedActions)。

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

重实现:QAbstractItemView::timerEvent(QTimerEvent *event).

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

重新实现:QAbstractItemView::updateGeometries().

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

重实现:QAbstractItemView::verticalOffset() const.

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

重实现:QAbstractItemView::viewportSizeHint() const.

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

重实现:QAbstractItemView::visualRect(const QModelIndex &index) const.

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

重实现:QAbstractItemView::visualRegionForSelection(const QItemSelection &selection) 常量。

自 4.7 版起,返回的区域只包含与视口相交(或包含在视口中)的矩形。

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

重实现:QAbstractScrollArea::wheelEvent(QWheelEvent *e)。

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