内容

• 公共类型
• 特性
• 公共函数
• 重实现公共函数
• 信号
• 保护函数
• 重实现保护函数
• 详细描述
• 改善性能

QListView 类

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

头：	#include <QListView>
CMake:	find_package(Qt6 COMPONENTS Widgets REQUIRED) target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake:	QT += widgets
继承：	QAbstractItemView
继承者：	QListWidget and QUndoView

• 所有成员列表，包括继承成员

公共类型

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

特性

batchSize : int flow : Flow gridSize : QSize isWrapping : bool itemAlignment : Qt::Alignment layoutMode : LayoutMode modelColumn : int

movement : Movement resizeMode : ResizeMode selectionRectVisible : bool spacing : int uniformItemSizes : bool viewMode : ViewMode wordWrap : bool

公共函数

	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 命令 ) 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 以简单非分层列表 (或图标的集合) 形式呈现模型中存储的项。此类用于提供列表和图标视图，以前提供是通过 QListBox and QIconView 类，但使用由 Qt 模型/视图体系结构提供的方式更灵活。

QListView 类是一种 模型/视图类 且属于 Qt 的 模型/视图框架 .

此视图不显示水平或垂直标题；要显示具有水平标题的项列表，使用 QTreeView 代替。

QListView 实现接口的定义是通过 QAbstractItemView 类以允许它显示提供数据，通过模型派生自 QAbstractItemModel 类。

可以使用 2 种视图模式之一显示列表视图中的项：按 ListMode ，项以简单列表形式显示；按 IconMode ，列表视图接受的形式为 图标视图 其中项按图标显示 (像：文件管理器中的文件)。默认情况下，列表视图按 ListMode 。要改变视图模式，使用 setViewMode () 函数，和要确定当前视图模式，使用 viewMode ().

这些视图项的布置方向指定通过 flow () 对于列表视图。项可能固定在到位，或允许移动，从属视图 movement () 状态。

若模型中的项无法完全按流方向布置，可以在视图 Widget 边界处换行它们；这取决于 isWrapping ()。此特性很有用，当按图标视图表示项时。

resizeMode () 和 layoutMode () 支配如何及何时布置项。项间隔按照其 spacing ()，且可以存在于名义大小栅格中指定通过 gridSize ()。项可以渲染为大图标 (或小图标) 从属其 iconSize ().

改善性能

赋予正处理数据的有关视图提示是可能的，为改善其性能当显示大量项时。对于旨在显示带有相等大小的项的视图而言，可以采纳的一种方式是设置 uniformItemSizes 特性为 true。

另请参阅 视图类 , 项视图拼图范例 , QTreeView , QTableView ，和 QListWidget .

成员类型文档编制

enum QListView:: Flow

常量	值	描述
QListView::LeftToRight	0	项从左到右布置在视图中。
QListView::TopToBottom	1	项从上到下布置在视图中。

enum QListView:: LayoutMode

常量	值	描述
QListView::SinglePass	0	一次性布置所有项。
QListView::Batched	1	项的布置是每批 batchSize 项。

另请参阅 batchSize .

enum QListView:: Movement

常量	值	描述
QListView::Static	0	用户无法移动项。
QListView::Free	1	用户可以自由移动项。
QListView::Snap	2	项捕捉到指定栅格当移动时；见 setGridSize ().

enum QListView:: ResizeMode

常量	值	描述
QListView::Fixed	0	仅首次布置项时展示视图。
QListView::Adjust	1	每当重置布置项视图大小时。

enum QListView:: ViewMode

常量	值	描述
QListView::ListMode	0	布置项使用 TopToBottom 流，采用 Small 尺寸和 Static 移动
QListView::IconMode	1	布置项使用 LeftToRight 流，采用 Large 尺寸和 Free 移动

特性文档编制

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 .

[since 5.12] itemAlignment : Qt::Alignment

此特性保持单元格中每项的对齐方式

这才支持在 ListMode with TopToBottom 流并启用换行。默认对齐方式为 0，意味着项完全填充其单元格。

该特性在 Qt 5.12 引入。

访问函数：

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，指示将展示模型中的第 1 列。

访问函数：

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 , movement ，和 resizeMode .

wordWrap : bool

此特性保持项文本的自动换行策略

若此特性为 true 那么有必要在单词分割处换行项文本；否则，根本不换行。此特性为 false 在默认情况下。

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

访问函数：

bool	wordWrap () const
void	setWordWrap (bool on )

成员函数文档编制

QListView:: QListView ( QWidget * parent = nullptr)

创建新的 QListView 采用给定 parent 以查看模型。使用 setModel () 来设置模型。

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

此信号被发射当指定 indexes 在视图中被移动。

[虚拟] QListView:: ~QListView ()

销毁视图。

void QListView:: clearPropertyFlags ()

清零 QListView 特定特性标志。见 viewMode .

特性继承自 QAbstractItemView 未被特性标志涵盖。具体来说， dragEnabled and acceptsDrops 的计算是通过 QListView 当调用 setMovement () 或 setViewMode ().

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

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

重实现： 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.

[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

返回 true 若 row 被隐藏；否则返回 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).

卷动视图内容按 dx and dy .

[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 。若列表视图的移动模式为 Static 或其视图模式为 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 命令 )

重实现： 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, since 5.2] QSize QListView:: viewportSizeHint () const

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

该函数在 Qt 5.2 引入。

[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) const.

从 4.7 起，返回区域仅包含 (或包括在) 视口相交矩形。

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

重实现： QAbstractScrollArea::wheelEvent (QWheelEvent *e).