QTreeWidget 类

QTreeWidget 类提供使用预定义树模型的树视图。更多...

头：	#include <QTreeWidget>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake:	QT += widgets
继承：	QTreeView

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

特性

columnCount : int
topLevelItemCount : const int

公共函数

	QTreeWidget (QWidget * parent = nullptr)
virtual	~QTreeWidget ()
void	addTopLevelItem (QTreeWidgetItem * item )
void	addTopLevelItems (const QList<QTreeWidgetItem > & items* )
void	closePersistentEditor (QTreeWidgetItem * item , int column = 0)
int	columnCount () const
int	currentColumn () const
QTreeWidgetItem *	currentItem () const
void	editItem (QTreeWidgetItem * item , int column = 0)
QList<QTreeWidgetItem *>	findItems (const QString & text , Qt::MatchFlags flags , int column = 0) const
QTreeWidgetItem *	headerItem () const
QModelIndex	indexFromItem (const QTreeWidgetItem * item , int column = 0) const
int	indexOfTopLevelItem (QTreeWidgetItem * item ) const
void	insertTopLevelItem (int index , QTreeWidgetItem * item )
void	insertTopLevelItems (int index , const QList<QTreeWidgetItem > & items* )
QTreeWidgetItem *	invisibleRootItem () const
bool	isPersistentEditorOpen (QTreeWidgetItem * item , int column = 0) const
QTreeWidgetItem *	itemAbove (const QTreeWidgetItem * item ) const
QTreeWidgetItem *	itemAt (const QPoint & p ) const
QTreeWidgetItem *	itemAt (int x , int y ) const
QTreeWidgetItem *	itemBelow (const QTreeWidgetItem * item ) const
QTreeWidgetItem *	itemFromIndex (const QModelIndex & index ) const
QWidget *	itemWidget (QTreeWidgetItem * item , int column ) const
void	openPersistentEditor (QTreeWidgetItem * item , int column = 0)
void	removeItemWidget (QTreeWidgetItem * item , int column )
QList<QTreeWidgetItem *>	selectedItems () const
void	setColumnCount (int columns )
void	setCurrentItem (QTreeWidgetItem * item )
void	setCurrentItem (QTreeWidgetItem * item , int column )
void	setCurrentItem (QTreeWidgetItem * item , int column , QItemSelectionModel::SelectionFlags command )
void	setHeaderItem (QTreeWidgetItem * item )
void	setHeaderLabel (const QString & label )
void	setHeaderLabels (const QStringList & labels )
void	setItemWidget (QTreeWidgetItem * item , int column , QWidget * widget )
int	sortColumn () const
void	sortItems (int column , Qt::SortOrder order )
QTreeWidgetItem *	takeTopLevelItem (int index )
QTreeWidgetItem *	topLevelItem (int index ) const
int	topLevelItemCount () const
QRect	visualItemRect (const QTreeWidgetItem * item ) const

重实现公共函数

virtual void

setSelectionModel (QItemSelectionModel * selectionModel ) override

公共槽

void	clear ()
void	collapseItem (const QTreeWidgetItem * item )
void	expandItem (const QTreeWidgetItem * item )
void	scrollToItem (const QTreeWidgetItem * item , QAbstractItemView::ScrollHint hint = EnsureVisible)

信号

void	currentItemChanged (QTreeWidgetItem * current , QTreeWidgetItem * previous )
void	itemActivated (QTreeWidgetItem * item , int column )
void	itemChanged (QTreeWidgetItem * item , int column )
void	itemClicked (QTreeWidgetItem * item , int column )
void	itemCollapsed (QTreeWidgetItem * item )
void	itemDoubleClicked (QTreeWidgetItem * item , int column )
void	itemEntered (QTreeWidgetItem * item , int column )
void	itemExpanded (QTreeWidgetItem * item )
void	itemPressed (QTreeWidgetItem * item , int column )
void	itemSelectionChanged ()

保护函数

virtual bool	dropMimeData (QTreeWidgetItem * parent , int index , const QMimeData * data , Qt::DropAction action )
virtual QMimeData *	mimeData (const QList<QTreeWidgetItem > & items* ) const
virtual QStringList	mimeTypes () const
virtual Qt::DropActions	supportedDropActions () const

重实现保护函数

virtual void	dropEvent (QDropEvent * event ) override
virtual bool	event (QEvent * e ) override

详细描述

QTreeWidget 类是提供标准树 Widget 的方便类，采用基于项的经典接口类似使用 QListView 类在 Qt 3。此类基于 Qt 模型/视图体系结构，并使用默认模型来保持项，其中每个项是 QTreeWidgetItem .

不需要灵活模型/视图框架的开发者可以使用此类，非常轻松地创建简单分层列表。更灵活方式涉及组合 QTreeView 采用标准项模型。这允许将数据存储与其表示分开。

以最简单形式，可以按以下方式构造树 Widget：

QTreeWidget *treeWidget = new QTreeWidget();
treeWidget->setColumnCount(1);
QList<QTreeWidgetItem *> items;
for (int i = 0; i < 10; ++i)
    items.append(new QTreeWidgetItem(static_cast<QTreeWidget *>(nullptr), QStringList(QString("item: %1").arg(i))));
treeWidget->insertTopLevelItems(0, items);

在可以把项添加到树 Widget 之前，必须设置列数采用 setColumnCount ()。这允许每项拥有一个或多个标签或其它装饰。可以找到所用列数采用 columnCount () 函数。

树可以拥有包含 Widget 每列区间的 Header 头。为每区间设置标签的最简单方式是通过提供字符串列表采用 setHeaderLabels ()，但可以构造自定义 Header 头采用 QTreeWidgetItem 并插入树采用 setHeaderItem () 函数。

树中的项可以根据预定义排序次序按列排序。若排序被启用，用户可以通过点击列 Header 头排序项。可以启用或禁用排序通过调用 setSortingEnabled ()。 isSortingEnabled () function indicates whether sorting is enabled.

另请参阅 QTreeWidgetItem , QTreeWidgetItemIterator , QTreeView , 模型/视图编程，和设置编辑器范例 .

特性文档编制

columnCount : int

此特性保持在树 Widget 中显示的列数

默认情况下，此特性拥有 1 值。

访问函数：

int	columnCount () const
void	setColumnCount (int columns )

`[read-only]` topLevelItemCount : const int

此特性保持顶层项数

默认情况下，此特性拥有 0 值。

访问函数：

int	topLevelItemCount () const

另请参阅 columnCount () 和 currentItem ().

成员函数文档编制

`[explicit]` QTreeWidget:: QTreeWidget ( QWidget * parent = nullptr)

构造树 Widget 采用给定 parent .

`[virtual noexcept]` QTreeWidget:: ~QTreeWidget ()

销毁树 Widget 及其所有项。

void QTreeWidget:: addTopLevelItem ( QTreeWidgetItem * item )

追加 item 作为 Widget 顶层项。

另请参阅 insertTopLevelItem ().

void QTreeWidget:: addTopLevelItems (const QList < QTreeWidgetItem > & items* )

追加列表 items 作为 Widget 顶层项。

另请参阅 insertTopLevelItems ().

`[slot]` void QTreeWidget:: clear ()

通过移除其所有项和选定，清零树 Widget。

注意： 由于在删除之前会从树 Widget 移除各项，返回值对于 QTreeWidgetItem::treeWidget () 将无效，当从项析构函数调用时。

另请参阅 takeTopLevelItem (), topLevelItemCount ()，和 columnCount ().

void QTreeWidget:: closePersistentEditor ( QTreeWidgetItem * item , int column = 0)

关闭持久编辑器为 item 以给定 column .

此函数不起作用，若此项和列的组合没有打开持久编辑器。

另请参阅 openPersistentEditor () 和 isPersistentEditorOpen ().

`[slot]` void QTreeWidget:: collapseItem (const QTreeWidgetItem * item )

关闭 item 。这导致包含项子级的树被折叠。

另请参阅 expandItem (), currentItem (), itemAt ()，和 topLevelItem ().

int QTreeWidget:: currentColumn () const

返回树 Widget 当前列。

另请参阅 setCurrentItem () 和 columnCount ().

QTreeWidgetItem *QTreeWidget:: currentItem () const

返回树 Widget 中的当前项。

另请参阅 setCurrentItem () 和 currentItemChanged ().

`[signal]` void QTreeWidget:: currentItemChanged ( QTreeWidgetItem * current , QTreeWidgetItem * previous )

此信号被发射在当前项改变时。当前项指定通过 current ，且这替换 previous 当前项。

另请参阅 setCurrentItem ().

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

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

`[virtual protected]` bool QTreeWidget:: dropMimeData ( QTreeWidgetItem * parent , int index , const QMimeData * data , Qt::DropAction action )

处理 data 的提供是通过结束拖放操作，按给定 action 在 index 以给定 parent 项。

默认实现返回 true 若掉落成功处理通过解码 MIME 数据并将其插入模型；否则它返回 false .

另请参阅 supportedDropActions ().

void QTreeWidget:: editItem ( QTreeWidgetItem * item , int column = 0)

开始编辑 item 以给定 column 若它可编辑。

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

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

`[slot]` void QTreeWidget:: expandItem (const QTreeWidgetItem * item )

展开 item 。这导致包含项子级的树被展开。

另请参阅 collapseItem (), currentItem (), itemAt (), topLevelItem ()，和 itemExpanded ().

QList < QTreeWidgetItem > QTreeWidget:: findItems (const QString & text* , Qt::MatchFlags flags , int column = 0) const

返回的项列表匹配给定 text ，使用给定 flags ，在给定 column .

QTreeWidgetItem *QTreeWidget:: headerItem () const

返回用于树小部件 Header 头部的项。

另请参阅 setHeaderItem ().

QModelIndex QTreeWidget:: indexFromItem (const QTreeWidgetItem * item , int column = 0) const

返回 QModelIndex 关联给定 item 以给定 column .

注意： 在 Qt 5.7 之前的版本中，此函数接受非 const item .

另请参阅 itemFromIndex () 和 topLevelItem ().

int QTreeWidget:: indexOfTopLevelItem ( QTreeWidgetItem * item ) const

返回索引为给定顶层 item ，或 -1 若找不到项。

另请参阅 sortItems () 和 topLevelItemCount ().

void QTreeWidget:: insertTopLevelItem ( int index , QTreeWidgetItem * item )

插入 item at index 在视图的顶层。

不会插入，若项已插入在其它地方。

另请参阅 addTopLevelItem () 和 columnCount ().

void QTreeWidget:: insertTopLevelItems ( int index , const QList < QTreeWidgetItem > & items* )

插入列表 items at index 在视图的顶层。

不会被插入若项已插入在其它地方。

另请参阅 addTopLevelItems ().

QTreeWidgetItem *QTreeWidget:: invisibleRootItem () const

返回树 Widget 的不可见根项。

不可见根项提供对树 Widget 顶层项的访问透过 QTreeWidgetItem API，使编写可以按统一方式处理顶层项及其子级的函数成为可能；例如：递归函数。

bool QTreeWidget:: isPersistentEditorOpen ( QTreeWidgetItem * item , int column = 0) const

返回是否打开持久编辑器为项 item 在列 column .

另请参阅 openPersistentEditor () 和 closePersistentEditor ().

QTreeWidgetItem QTreeWidget:: itemAbove (const QTreeWidgetItem item ) const

返回上方项为给定 item .

`[signal]` void QTreeWidget:: itemActivated ( QTreeWidgetItem * item , int column )

此信号被发射当用户通过单击或双击激活项时 (从属平台，即：在 QStyle::SH_ItemView_ActivateItemOnSingleClick 样式提示) 或按下特殊键 (如： Enter ).

指定 item 是被点击项，或 nullptr 若没有点击项。 column 是被点击的项的列，或 -1 若没有点击项。

QTreeWidgetItem *QTreeWidget:: itemAt (const QPoint & p ) const

返回指针指向项在坐标 p 。坐标相对于树 Widget 的 viewport ().

另请参阅 visualItemRect ().

QTreeWidgetItem *QTreeWidget:: itemAt ( int x , int y ) const

这是重载函数。

返回指针指向项在坐标 ( x , y )。坐标相对于树 Widget 的 viewport ().

QTreeWidgetItem QTreeWidget:: itemBelow (const QTreeWidgetItem item ) const

返回下方可见项为给定 item .

`[signal]` void QTreeWidget:: itemChanged ( QTreeWidgetItem * item , int column )

此信号被发射当内容在 column 以指定 item 改变。

`[signal]` void QTreeWidget:: itemClicked ( QTreeWidgetItem * item , int column )

此信号被发射当用户在 Widget 内点击时。

指定 item 是被点击项。 column 是项的被点击列。若没有点击项，不会发射信号。

`[signal]` void QTreeWidget:: itemCollapsed ( QTreeWidgetItem * item )

此信号被发射当指定 item 被折叠以便不显示其子级。

注意： 此信号不会被发射若项改变其状态当 collapseAll () 被援引。

另请参阅 QTreeWidgetItem::isExpanded (), itemExpanded ()，和 collapseItem ().

`[signal]` void QTreeWidget:: itemDoubleClicked ( QTreeWidgetItem * item , int column )

此信号被发射当用户在 Widget 内双击时。

指定 item 是被点击项，或 nullptr 若没有点击项。 column 是项的被点击列。若没有项被双击，不会发射信号。

`[signal]` void QTreeWidget:: itemEntered ( QTreeWidgetItem * item , int column )

此信号被发射当鼠标光标进入 item 覆盖指定 column . QTreeWidget 鼠标追踪需要启用为使此特征能工作。

`[signal]` void QTreeWidget:: itemExpanded ( QTreeWidgetItem * item )

此信号被发射当指定 item 被展开以便显示其所有子级。

另请参阅 QTreeWidgetItem::isExpanded (), itemCollapsed ()，和 expandItem ().

QTreeWidgetItem QTreeWidget:: itemFromIndex (const QModelIndex & index* ) const

返回指针指向 QTreeWidgetItem 关联给定 index .

另请参阅 indexFromItem ().

`[signal]` void QTreeWidget:: itemPressed ( QTreeWidgetItem * item , int column )

此信号被发射当用户在 Widget 内按下鼠标按钮时。

指定 item 是被点击项，或 nullptr 若没有点击项。 column 是被点击的项的列，或 -1 若没有点击项。

`[signal]` void QTreeWidget:: itemSelectionChanged ()

此信号被发射当树 Widget 选定改变时。可以找到当前选定采用 selectedItems ().

QWidget QTreeWidget:: itemWidget ( QTreeWidgetItem item , int column ) const

返回单元格显示 Widget 指定通过 item 和给定 column .

另请参阅 setItemWidget ().

`[virtual protected]` QMimeData QTreeWidget:: mimeData (const QList < QTreeWidgetItem > & items ) const

返回的对象包含序列化描述为指定 items 。用于描述项的格式获取自 mimeTypes () 函数。

若项列表为空， nullptr 被返回而不是序列化空列表。

`[virtual protected]` QStringList QTreeWidget:: mimeTypes () const

返回可用于描述 treewidget 项列表的 MIME 类型列表。

另请参阅 mimeData ().

void QTreeWidget:: openPersistentEditor ( QTreeWidgetItem * item , int column = 0)

打开持久编辑器为 item 以给定 column .

另请参阅 closePersistentEditor () 和 isPersistentEditorOpen ().

void QTreeWidget:: removeItemWidget ( QTreeWidgetItem * item , int column )

删除设置 Widget 在给定 item 以给定 column .

`[slot]` void QTreeWidget:: scrollToItem (const QTreeWidgetItem * item , QAbstractItemView::ScrollHint hint = EnsureVisible)

确保 item 可见，卷动视图若有必要使用指定 hint .

另请参阅 currentItem (), itemAt ()，和 topLevelItem ().

QList < QTreeWidgetItem *> QTreeWidget:: selectedItems () const

返回所有选定的非隐藏项的列表。

另请参阅 itemSelectionChanged ().

void QTreeWidget:: setCurrentItem ( QTreeWidgetItem * item )

设置当前 item 在树 Widget。

除非选定模式为 NoSelection ，项还被选中。

另请参阅 currentItem () 和 currentItemChanged ().

void QTreeWidget:: setCurrentItem ( QTreeWidgetItem * item , int column )

设置当前 item 在树 Widget 和当前列到 column .

另请参阅 currentItem ().

void QTreeWidget:: setCurrentItem ( QTreeWidgetItem * item , int column , QItemSelectionModel::SelectionFlags command )

设置当前 item 在树 Widget 和当前列到 column ，使用给定 command .

另请参阅 currentItem ().

void QTreeWidget:: setHeaderItem ( QTreeWidgetItem * item )

设置 Header 头 item 为树小部件。头中每列的标签由项相应标签提供。

树 Widget 拥有项的所有权。

另请参阅 headerItem () 和 setHeaderLabels ().

void QTreeWidget:: setHeaderLabel (const QString & label )

如同 setHeaderLabels ( QStringList ( label )).

void QTreeWidget:: setHeaderLabels (const QStringList & labels )

为每项添加 Header 头部列按 labels 列表, 并为每列设置标签。

注意：setHeaderLabels() 不会移除现有列。

另请参阅 setHeaderItem () 和 setHeaderLabel ().

void QTreeWidget:: setItemWidget ( QTreeWidgetItem * item , int column , QWidget * widget )

设置给定 widget 以显示在指定单元格通过给定 item and column .

给定 widget 's autoFillBackground 特性必须被设为 true，否则 Widget 背景将透明，同时展示模型数据和树 Widget 项。

此函数只应该用于在树 Widget 项位置处显示静态内容。若想要显示自定义动态内容或实现自定义编辑器 Widget，使用 QTreeView 和子类 QStyledItemDelegate 代替。

不可以调用此函数在设置项层次结构之前，即 QTreeWidgetItem 将保持 widget 必须被添加到视图之后 widget 有设置。

注意： 树拥有 Widget 的所有权。

另请参阅 itemWidget () 和委托类 .

`[override virtual]` void QTreeWidget:: setSelectionModel ( QItemSelectionModel * selectionModel )

重实现： QTreeView::setSelectionModel (QItemSelectionModel *selectionModel).

int QTreeWidget:: sortColumn () const

返回用于排序 Widget 内容的列。

另请参阅 sortItems ().

void QTreeWidget:: sortItems ( int column , Qt::SortOrder order )

排序 Widget 项按指定 order 通过值在给定 column .

另请参阅 sortColumn ().

`[virtual protected]` Qt::DropActions QTreeWidget:: supportedDropActions () const

返回由此视图所支持的掉落动作。

另请参阅 Qt::DropActions .

QTreeWidgetItem QTreeWidget:: takeTopLevelItem ( int index* )

移除顶层项位于给定 index 在树中并返回它，否则返回 nullptr ;

另请参阅 insertTopLevelItem (), topLevelItem ()，和 topLevelItemCount ().

QTreeWidgetItem QTreeWidget:: topLevelItem ( int index* ) const

返回顶层项位于给定 index ，或 nullptr 若项不存在。

另请参阅 topLevelItemCount () 和 insertTopLevelItem ().

QRect QTreeWidget:: visualItemRect (const QTreeWidgetItem * item ) const

返回项所占据的视口矩形为 item .

另请参阅 itemAt ().

QTreeWidget 类

特性

公共函数

重实现公共函数

公共槽

信号

保护函数

重实现保护函数

详细描述

特性文档编制

columnCount : int

[read-only] topLevelItemCount : const int

成员函数文档编制

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

[virtual noexcept] QTreeWidget:: ~QTreeWidget ()

void QTreeWidget:: addTopLevelItem ( QTreeWidgetItem * item )

void QTreeWidget:: addTopLevelItems (const QList < QTreeWidgetItem *> & items )

[slot] void QTreeWidget:: clear ()

void QTreeWidget:: closePersistentEditor ( QTreeWidgetItem * item , int column = 0)

[slot] void QTreeWidget:: collapseItem (const QTreeWidgetItem * item )

int QTreeWidget:: currentColumn () const

QTreeWidgetItem *QTreeWidget:: currentItem () const

[signal] void QTreeWidget:: currentItemChanged ( QTreeWidgetItem * current , QTreeWidgetItem * previous )

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

[virtual protected] bool QTreeWidget:: dropMimeData ( QTreeWidgetItem * parent , int index , const QMimeData * data , Qt::DropAction action )

void QTreeWidget:: editItem ( QTreeWidgetItem * item , int column = 0)

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

[slot] void QTreeWidget:: expandItem (const QTreeWidgetItem * item )

QList < QTreeWidgetItem *> QTreeWidget:: findItems (const QString & text , Qt::MatchFlags flags , int column = 0) const