QAbstractItemModel

一、概述

QAbstractItemModel 类定义了项目模型必须使用的标准接口，以便能够与模型/视图框架中的其他组件进行互操作。正确用法是将其子类化以创建新模型。

此类用作 QML 中的项目视图元素或 Qt Widgets 模块中的项目视图类的底层数据模型。

如果需要一个模型与项目视图一起使用，例如 QML 的列表视图元素或 C++ 小部件 QListView 或 QTableView，则应该考虑子类化 QAbstractListModel 或 QAbstractTableModel 而不是此类。

底层数据模型作为表的层次结构向视图和委托公开。如果不使用层次结构，那么模型就是一个简单的行和列表。

每个项目都有一个由 QModelIndex 指定的唯一索引。

1.1、子类化

在继承 QAbstractItemModel 时，至少必须实现：

index()
parent()
rowCount()
columnCount()
data()

这些函数用于所有只读模型，并构成可编辑模型的基础。

要在模型中启用编辑，还必须实现：

setData()

flags()（要确保返回 ItemIsEditable）

控制模型标题的显示方式，可以实现：

headerData()
setHeaderData()

在重新实现 setData() 和 setHeaderData() 函数时，必须分别显式地发出 dataChanged() 和 headerDataChanged() 信号。

二、成员类型

1、enum class QAbstractItemModel::CheckIndexOption：此枚举可用于控制由 checkIndex() （此函数检查 index 是否是该模型的合法模型索引）执行的检查。

NoOption：未指定选项。
IndexIsValid：传递给 checkIndex() 的模型索引被检查为有效的模型索引。
DoNotUseParent：不执行任何涉及传递给 checkIndex() 的索引的父项的使用的检查。
ParentIsInvalid：传递给checkIndex()的模型索引的父级被检查为无效的模型索引。如果同时指定了此选项和 DoNotUseParent，则忽略此选项。

2、enum QAbstractItemModel::LayoutChangeHint：此枚举描述模型更改布局的方式。

NoLayoutChangeHint：无。
VerticalSortHint：Rows 正在排序。
HorizontalSortHint：Columns 正在排序。

三、成员函数

3.1、私有信号

私有信号只能由 QAbstractItemModel 实现发出，不能在子类代码中显式发出。

私有信号可以用于信号连接，但不能由用户发射。

1、[私有] void columnsAboutToBeInserted(const QModelIndex &parent, int first, int last)

该信号在列插入模型之前发出。新项目将位于给定parent下的first和last之间。

连接到此信号的组件使用它来适应模型尺寸的变化。

2、[私有] void columnsAboutToBeMoved(const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationColumn)

该信号在列在模型内移动之前发出。将被移动的项目是在给定的 sourceParent 项目下的 sourceStart 和 sourceEnd 之间的项目。它们将被移动到destinationParent，从destinationColumn 列开始。

连接到此信号的组件使用它来适应模型尺寸的变化。

3、[私有] void columnsAboutToBeRemoved(const QModelIndex &parent, int first, int last)

该信号在列从模型中移除之前发出。要删除的项目是在给定 parent 下的 first 和 last 之间的项目。

连接到此信号的组件使用它来适应模型尺寸的变化。

4、[私有] void columnsInserted(const QModelIndex &parent, int first, int last)

在将列插入模型之后发出此信号。新项目是在给定parent下的first和last之间的项目。

连接到此信号的组件使用它来适应模型尺寸的变化。

5、[私有] void columnsMoved(const QModelIndex &parent, int start, int end, const QModelIndex &destination, int column)

在模型内移动列之后发出此信号。给parent下的 start 和 end 之间的项目已移至 column 列开始的destination。

连接到此信号的组件使用它来适应模型尺寸的变化。

6、[私有] void columnsRemoved(const QModelIndex &parent, int first, int last)

从模型中删除列后会发出此信号。删除的项目是在给parent下的first和last之间的项目。

连接到此信号的组件使用它来适应模型尺寸的变化。

7、[私有] void modelAboutToBeReset()

在调用 beginResetModel() 时，在模型的内部状态（例如，持久模型索引）失效之前，会发出此信号。

8、[私有] void modelReset()

在模型的内部状态（例如，持久模型索引）失效后，调用 endResetModel() 时会发出此信号。

9、[私有] void rowsAboutToBeInserted(const QModelIndex &parent, int start, int end)

该信号在行插入模型之前发出。新项目在给定的parent下将被定位在start和end之间。

连接到此信号的组件使用它来适应模型尺寸的变化。

10、[私有] void rowsAboutToBeMoved(const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationRow)

该信号在行在模型内移动之前发出。将被移动的项目是在给定的 sourceParent 项目下的 sourceStart 和 sourceEnd 之间的项目。它们将被移动到destinationParent 行，从destinationRow 开始。

连接到此信号的组件使用它来适应模型尺寸的变化。

11、[私有] void rowsAboutToBeRemoved(const QModelIndex &parent, int first, int last)

该信号在行从模型中移除之前发出。将被删除的项目是在给定parent下的first和last之间的项目。

连接到此信号的组件使用它来适应模型尺寸的变化。

12、[私有] void rowsInserted(const QModelIndex &parent, int first, int last)

在将行插入模型后发出此信号。新项目是在给定parent下的first和last之间的项目。

连接到此信号的组件使用它来适应模型尺寸的变化。

13、[私有] void rowsMoved(const QModelIndex &parent, int start, int end, const QModelIndex &destination, int row)

在模型内移动行后发出此信号。给定parent下的 start 和 end 之间的项已移动到从row行开始的destination。

连接到此信号的组件使用它来适应模型尺寸的变化。

14、[私有] void rowsRemoved(const QModelIndex &parent, int first, int last)

从模型中删除行后会发出此信号。删除的项目是在给定parent下的first和last之间的项目。

连接到此信号的组件使用它来适应模型尺寸的变化。

3.2、非私有信号

1、void dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles = QList<int>())

只要现有项目中的数据发生变化，就会发出此信号。

如果项目属于同一父项，则受影响的项目是 topLeft 和 bottomRight 之间的项目。如果项目没有相同的父项，则行为未定义。

重新实现 setData() 函数时，必须显式发出此信号。

roles 可用于指定实际修改了哪些数据角色。roles 中元素的顺序没有任何相关性。

2、void headerDataChanged(Qt::Orientation orientation, int first, int last)

每当更改标题时都会发出此信号。orientation指示水平或垂直标题是否已更改。标题中从first到last的部分需要更新。

重新实现 setHeaderData() 函数时，必须显式发出此信号。

如果要更改列数或行数，则不需要发出此信号。

3、void layoutAboutToBeChanged(const QList<QPersistentModelIndex> &parents = QList<QPersistentModelIndex>(), QAbstractItemModel::LayoutChangeHint hint = QAbstractItemModel::NoLayoutChangeHint)

该信号在模型布局更改之前发出。连接到该信号的组件使用它来适应模型布局的变化。

子类应该在发出 layoutAboutToBeChanged() 后更新持久模型索引。

parent 参数用于提供有关模型布局的哪些部分正在更改的更具体的通知，空列表表示整个模型的布局发生了变化。列表中元素的顺序并不重要。hint 参数用于提示模型重新布局时发生的情况。

4、void layoutChanged(const QList<QPersistentModelIndex> &parents = QList<QPersistentModelIndex>(), QAbstractItemModel::LayoutChangeHint hint = QAbstractItemModel::NoLayoutChangeHint)

每当模型公开的项目布局发生变化时，就会发出此信号（例如，当模型已经排序）。当视图收到此信号时，它应更新项目的布局以反映此更改。

在继承 QAbstractItemModel 或 QAbstractProxyModel 时，请确保在更改项目顺序或更改向视图公开的数据结构之前发出 layoutAboutToBeChanged()，并在更改布局后发出 layoutChanged()。

子类应该在发出 layoutChanged() 之前更新持久模型索引。

当结构发生变化时：

发出 layoutAboutToBeChanged()

记住会改变的 QModelIndex

更新内部数据

调用 changePersistentIndex()

发出布局已更改

3.3、函数

1、void resetInternalData()

在模型的内部数据被清除后，当它正在被重置时会被调用。

2、void revert()

让模型知道它应该丢弃缓存的信息。此功能通常用于行编辑。

3、bool submit()

让模型知道它应该将缓存的信息提交到永久存储。此功能通常用于行编辑。如果没有错误则返回true.

4、void beginInsertColumns(const QModelIndex &parent, int first, int last)

开始列插入操作。

在子类中重新实现 insertColumns() 时，必须在将数据插入模型的底层数据存储之前调用此函数。

parent 对应于插入新列的父索引，first 和 last 是新列插入后的列号。

注意：此函数会发出 columnsAboutToBeInserted() 信号，连接的视图（或代理）在插入数据之前必须处理该信号。否则视图可能最终处于无效状态。

beginInsertColumns(parent, 4, 6);

beginInsertColumns(parent, 6, 8);

5、void beginInsertRows(const QModelIndex &parent, int first, int last)

开始行插入操作。

在子类中重新实现 insertRows() 时，必须在将数据插入模型的底层数据存储之前调用此函数。

parent 对应于插入新行的父索引，first 和 last 是新行插入后的行号。

注意：此函数发出rowsAboutToBeInserted() 信号，连接的视图（或代理）在插入数据之前必须处理该信号。否则，视图可能最终处于无效状态。

beginInsertRows(parent, 2, 4);

beginInsertRows(parent, 4, 5);

6、bool beginMoveColumns(const QModelIndex &sourceParent, int sourceFirst, int sourceLast, const QModelIndex &destinationParent, int destinationChild)

开始列移动操作。

重新实现子类时，此方法简化了模型中移动实体的过程。使用 beginMoveColumns() 和 endMoveColumns() 是直接与 changePersistentIndex() 一起发出 layoutAboutToBeChanged() 和 layoutChanged() 的替代方法。

sourceParent 索引对应于从中移动列的父级，sourceFirst 和 sourceLast 是要移动的列的第一个和最后一个列号。destinationParent 索引对应于将这些列移入的父项。 destinationChild 是列将移动到的列。也就是说，sourceParent 中列 sourceFirst 的索引将成为 destinationParent 中的列 destinationChild，然后是所有其他列，直到 sourceLast。

但是，在同一父级中向下移动列（sourceParent 和 destinationParent 相等）时，列将放置在 destinationChild 索引之前。也就是说，如果希望移动第 0 列和第 1 列使其成为第 1 列和第 2 列，则 destinationChild 应为 3。在这种情况下，源列 i（位于 sourceFirst 和 sourceLast 之间）的新索引等于 ( destinationChild-sourceLast-1+i)。

请注意，如果 sourceParent 和 destinationParent 相同，则必须确保 destinationChild 不在 sourceFirst 和 sourceLast + 1 的范围内。还必须确保不要尝试将列移动到其自己的子项或祖先之一。如果任一条件为真，则此方法返回 false，在这种情况下，应该中止移动操作。

7、bool beginMoveRows(const QModelIndex &sourceParent, int sourceFirst, int sourceLast, const QModelIndex &destinationParent, int destinationChild)

开始行移动操作。与上面类似。

beginMoveRows(sourceParent, 2, 4, destinationParent, 2);

beginMoveRows(sourceParent, 2, 4, destinationParent, 6);

beginMoveRows(parent, 2, 2, parent, 0);

beginMoveRows(parent, 2, 2, parent, 4);

8、void beginRemoveColumns(const QModelIndex &parent, int first, int last)

开始列移除操作。

在子类中重新实现 removeColumns() 时，必须在从模型的底层数据存储中删除数据之前调用此函数。

parent 对应于从中删除新列的父索引，first 和 last 是要删除的第一列和最后一列的列号。

注意：此函数发出 columnsAboutToBeRemoved() 信号，连接的视图（或代理）在删除数据之前必须处理该信号。否则，视图可能最终处于无效状态。

beginRemoveColumns(parent, 4, 6);

9、void beginRemoveRows(const QModelIndex &parent, int first, int last)

开始行删除操作。

在子类中重新实现 removeRows() 时，必须在从模型的底层数据存储中删除数据之前调用此函数。

parent对应于从中删除新行的父索引，first 和 last 是要删除的行的行号。

注意：此函数发出rowsAboutToBeRemoved() 信号，连接的视图（或代理）在删除数据之前必须处理该信号。否则，视图可能最终处于无效状态。

beginRemoveRows(parent, 2, 3);

10、void beginResetModel()

开始模型重置操作。附加到此模型的任何视图也将被重置。

必须在重置模型或代理模型中的任何内部数据结构之前调用此函数。

此函数会发出信号 modelAboutToBeReset()。

11、QModelIndex buddy(const QModelIndex &index)

返回由index表示的项目的好友模型索引。

当用户想要编辑一个项目时，视图会调用这个函数来检查模型中的另一个项目是否应该被编辑。然后，视图将使用伙伴项返回的模型索引构造一个委托。

12、bool canDropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent)

如果模型可以接受拖拽数据，则返回 true。

13、[invokable] bool canFetchMore(const QModelIndex &parent)

如果父级有更多可用数据，则返回 true。默认实现始终返回 false。

如果 canFetchMore() 返回 true，则应调用 fetchMore() 函数。

这个函数可以通过元对象系统和 QML 调用。

14、bool checkIndex(const QModelIndex &index, QAbstractItemModel::CheckIndexOptions options = CheckIndexOption::NoOption)

此函数检查 index 是否是该模型的合法模型索引。

合法的模型索引要么是无效的模型索引，要么是满足以下所有条件的有效模型索引：

索引模型是this
索引的行大于或等于零
索引的行小于索引父级的行数
索引的列大于或等于零
索引的列小于索引的父级的列数

options 参数设置检查选项。

如果 options 包含 IndexIsValid，则 index 必须是有效索引。
如果 options 包含 DoNotUseParent，则省略调用 parent() 的检查。这允许从 parent() 重新实现中调用此函数（否则，这将导致无限递归和崩溃）。
如果 options 不包含 DoNotUseParent，并且包含 ParentIsInvalid，则执行附加检查，检查父索引是否无效。

15、bool clearItemData(const QModelIndex &index)

删除存储在给定索引的所有角色中的数据。成功则返回true。如果成功删除数据，则应发出 dataChanged() 信号。

16、[invokable] int columnCount(const QModelIndex &parent = QModelIndex())

返回给定父级的子级的列数。在大多数子类中，列数与父类无关。

这个函数可以通过元对象系统和 QML 调用。

17、QModelIndex createIndex(int row, int column, const void *ptr = nullptr)

使用内部指针 ptr 为给定的行和列创建模型索引。

当使用 QSortFilterProxyModel 时，它的索引有自己的内部指针。不建议在模型之外访问这个内部指针。请改用 data() 函数。

此函数提供了一个一致的接口，模型子类必须使用该接口来创建模型索引。

18、[invokable] QVariant data(const QModelIndex &index, int role = Qt::DisplayRole)

返回存储在给定角色下的数据，用于索引引用的项目。

如果您没有要返回的值，请返回无效的 QVariant 而不是返回 0。

这个函数可以通过元对象系统和 QML 调用。

19、bool dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent)

处理拖放拖入的数据。

指定的行、列、父项指示模型中操作结束的项目的位置。在正确的位置完成动作是模型的责任。

调用 mimeTypes() 成员以获取可接受的 MIME 类型列表。此默认实现假定 mimeTypes() 的默认实现，它返回单个默认 MIME 类型。如果在自定义模型中重新实现 mimeTypes() 以返回多个 MIME 类型，则必须重新实现此函数以使用它们。

20、void endInsertColumns()

结束列插入操作。在子类中重新实现 insertColumns() 时，必须在将数据插入模型的底层数据存储后调用此函数。

21、void endInsertRows()

结束行插入操作。在子类中重新实现 insertRows() 时，必须在将数据插入模型的底层数据存储后调用此函数。

22、void endMoveColumns()

结束列移动操作。实现子类时，必须在模型的底层数据存储中移动数据后调用此函数。

23、void endMoveRows()

结束行移动操作。实现子类时，必须在模型的底层数据存储中移动数据后调用此函数。

24、void endRemoveColumns()

结束列移除操作。在子类中重新实现 removeColumns() 时，必须在从模型的底层数据存储中删除数据后调用此函数。

25、void endRemoveRows()

结束行删除操作。在子类中重新实现 removeRows() 时，必须在从模型的底层数据存储中删除数据后调用此函数。

26、void endResetModel()

完成模型重置操作。必须在重置模型或代理模型中的任何内部数据结构后调用此函数。此函数会发出信号modelReset()。

27、[invokable] void fetchMore(const QModelIndex &parent)

获取具有由父索引指定的父项的项的任何可用数据。如果以增量方式填充模型，需要重新实现它。

默认实现什么都不做。这个函数可以通过元对象系统和 QML 调用。

28、[invokable] Qt::ItemFlags flags(const QModelIndex &index)

返回给定索引的项目标志。

基类实现返回启用项目 (ItemIsEnabled) 并允许选择项目 (ItemIsSelectable) 的标志组合。

这个函数可以通过元对象系统和 QML 调用。

29、[invokable] bool hasChildren(const QModelIndex &parent = QModelIndex())

parent 是否有子项。如果同一索引设置了标志 Qt::ItemNeverHasChildren，则调用此函数会产生未定义的行为。

这个函数可以通过元对象系统和 QML 调用。

30、[invokable] bool hasIndex(int row, int column, const QModelIndex &parent = QModelIndex())

如果模型为具有父级的行和列返回有效的 QModelIndex，则返回 true。

这个函数可以通过元对象系统和 QML 调用。

31、[invokable] QVariant headerData(int section, Qt::Orientation orientation, int role = Qt::DisplayRole)

返回具有指定方向的标题中给定角色和部分的数据。对于水平标题，节号对应于列号。同样，对于垂直标题，节号对应于行号。

这个函数可以通过元对象系统和 QML 调用。

32、[invokable] QModelIndex index(int row, int column, const QModelIndex &parent = QModelIndex())

返回由给定的行、列和父索引指定的模型中项目的索引。

在子类中重新实现此函数时，调用 createIndex() 生成模型索引，其他组件可以使用这些索引来引用模型中的项。

这个函数可以通过元对象系统和 QML 调用。

33、bool insertColumn(int column, const QModelIndex &parent = QModelIndex())

在指定的父项的子项中的给定列之前插入单列。如果成功插入了列则返回 true。实际上是调用insertColumns()。

34、bool insertColumns(int column, int count, const QModelIndex &parent = QModelIndex())

在支持此功能的模型上，在给定列之前将计数新列插入模型中。每个新列中的项目将是由父模型索引表示的项目的子项。

35、bool insertRow(int row, const QModelIndex &parent = QModelIndex())

bool insertRows(int row, int count, const QModelIndex &parent = QModelIndex())

插入行，与上面类似。

36、QMap<int, QVariant> itemData(const QModelIndex &index)

返回一个map，其中包含index处的项目的模型中所有预定义角色的值。

37、[invokable] QModelIndexList match(const QModelIndex &start, int role, const QVariant &value, int hits = 1, Qt::MatchFlags flags = Qt::MatchFlags(Qt::MatchStartsWith|Qt::MatchWrap))

返回 start 索引列中项目的索引列表，其中存储在给定角色下的数据与 role 匹配。执行搜索的方式由 flags 定义。

列表中结果的顺序可能与模型中的顺序不一致。

默认情况下，此函数将对所有项目执行基于字符串的换行比较，搜索以 value 指定的搜索词开头的项目。

此函数的默认实现仅搜索列。重新实现此函数以包含不同的搜索行为。

此函数可以通过元对象系统和 QML 调用。

enum Qt::MatchFlag：此枚举描述了在模型中搜索项目时可以使用的匹配类型。

Qt::MatchExactly：执行基于 QVariant 的匹配。
Qt::MatchFixedString：基于字符串的匹配。除非还指定了 MatchCaseSensitive 标志，否则基于字符串的比较不区分大小写。
Qt::MatchContains：搜索词包含在项目中。
Qt::MatchStartsWith：搜索词匹配项的开头。
Qt::MatchEndsWith：搜索词匹配项的结尾。
Qt::MatchCaseSensitive：搜索区分大小写。
Qt::MatchRegularExpression：使用正则表达式作为搜索词来执行基于字符串的匹配。
Qt::MatchWildcard：使用带有通配符的字符串作为搜索词来执行基于字符串的匹配。
Qt::MatchWrap：执行环绕搜索，这样当搜索到达模型中的最后一项时，它会再次从第一项开始，一直持续到检查完所有项为止。
Qt::MatchRecursive：搜索整个层次结构。

38、QMimeData * mimeData(const QModelIndexList &indexes)

返回一个对象，其中包含与指定索引列表相对应的序列化数据项。用于描述编码数据的格式是从 mimeTypes() 函数获得的。此默认实现使用 mimeTypes() 的默认实现返回的默认 MIME 类型。

39、QStringList mimeTypes()

返回允许的 MIME 类型列表。默认情况下，内置模型和视图使用内部 MIME 类型：application/x-qabstractitemmodeldatalist。

在自定义模型中实现拖放支持时，如果将以默认内部 MIME 类型以外的格式返回数据，请重新实现此函数以返回您的 MIME 类型列表。

在自定义模型中重新实现此函数，则还必须重新实现调用它的成员函数：mimeData() 和 dropMimeData()。

40、bool moveColumn(const QModelIndex &sourceParent, int sourceColumn, const QModelIndex &destinationParent, int destinationChild)

在支持此功能的模型上，将 sourceColumn 从 sourceParent 移动到 destinationParent 下的 destinationChild。

如果列成功移动则返回 true。

41、bool moveColumns(const QModelIndex &sourceParent, int sourceColumn, int count, const QModelIndex &destinationParent, int destinationChild)

在支持此功能的模型上，将从父 sourceParent 下的给定 sourceColumn 开始的列移动到父 destinationParent 下的列 destinationChild。

如果列成功移动则返回 true。

42、bool moveRow(const QModelIndex &sourceParent, int sourceRow, const QModelIndex &destinationParent, int destinationChild)

bool moveRows(const QModelIndex &sourceParent, int sourceRow, int count, const QModelIndex &destinationParent, int destinationChild)

移动行。同上。

43、void multiData(const QModelIndex &index, QModelRoleDataSpan roleDataSpan)

使用给定索引的请求数据填充 roleDataSpan。

44、[invokable] QModelIndex parent(const QModelIndex &index)

返回具有给定索引的模型项的父项。如果该项没有父项，则返回无效的 QModelIndex。

这个函数可以通过元对象系统和 QML 调用。

45、QModelIndexList persistentIndexList()

返回在模型中存储为持久索引的索引列表。

46、bool removeColumn(int column, const QModelIndex &parent = QModelIndex())

从指定的父项的子项中删除给定列。如果列被删除返回 true。实际上是调用removeColumns()。

47、bool removeColumns(int column, int count, const QModelIndex &parent = QModelIndex())

在支持此功能的模型上，从模型中删除 parent 下的给定 column 开头的 count列。如果列被成功删除则返回 true。

48、bool removeRow(int row, const QModelIndex &parent = QModelIndex())

bool removeRows(int row, int count, const QModelIndex &parent = QModelIndex())

与上面类似，删除行。

49、QHash<int, QByteArray> roleNames()

返回模型的角色名称。

Qt 设置的默认角色名称是：

Qt::DisplayRole：display
Qt::DecorationRole：decoration
Qt::EditRole：edit
Qt::ToolTipRole：toolTip
Qt::StatusTipRole：statusTip
Qt::WhatsThisRole：whatsThis

50、[invokable] int rowCount(const QModelIndex &parent = QModelIndex())

返回给定父项下的行数。

这个函数可以通过元对象系统和 QML 调用。

51、[invokable] bool setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole)

设置索引处项目的角色数据。成功则返回true。如果成功设置了数据，则应发出 dataChanged() 信号。

此函数可以通过元对象系统和 QML 调用。

52、bool setHeaderData(int section, Qt::Orientation orientation, const QVariant &value, int role = Qt::EditRole)

设置标题的值。如果标题的数据已更新则返回 true。

重新实现此函数时，必须显式发出 headerDataChanged() 信号。

53、bool setItemData(const QModelIndex &index, const QMap<int, QVariant> &roles)

对于每个 Qt::ItemDataRole，将 index 处项目的角色数据设置为角色中的关联值。不在角色中的角色将不会被修改。

54、[invokable] QModelIndex sibling(int row, int column, const QModelIndex &index)

返回索引处项目的行和列的兄弟，如果该位置没有兄弟，则返回无效的 QModelIndex。

这个函数可以通过元对象系统和 QML 调用。

55、void sort(int column, Qt::SortOrder order = Qt::AscendingOrder)

按给定顺序按列对模型进行排序。

enum Qt::SortOrder：此枚举描述了widget中的项目是如何排序的。

Qt::AscendingOrder：按升序排序，例如在 Latin-1 语言环境中以 'AAA' 开头以 'ZZZ' 结尾
Qt::DescendingOrder：按降序排序，例如在 Latin-1 语言环境中以“ZZZ”开头以“AAA”结尾

56、QSize span(const QModelIndex &index)

返回由索引表示的项目的行和列跨度。

57、Qt::DropActions supportedDragActions()

返回此模型中数据支持的操作。

58、Qt::DropActions supportedDropActions()

返回此模型支持的放置操作。

默认实现返回 Qt::CopyAction。如果希望支持其他操作，需重新实现此功能。还必须重新实现 dropMimeData() 函数来处理附加操作。

本文福利，莬费领取Qt开发学习资料包、技术视频，内容包括（C++语言基础，Qt编程入门，QT信号与槽机制，QT界面开发-图像绘制，QT网络，QT数据库编程，QT项目实战，QT嵌入式开发，Quick模块等等）↓↓↓↓↓↓见下面↓↓文章底部点击莬费领取↓↓

QAbstractItemView

一、描述

QAbstractItemView 类是每个使用 QAbstractItemModel 的标准视图的基类。 QAbstractItemView 是一个抽象类，本身不能被实例化。它提供了一个标准接口，用于通过信号和槽机制与模型进行互操作，使子类能够随着模型的变化保持最新。此类为键盘和鼠标导航、视口滚动、项目编辑和选择提供标准支持。键盘导航实现了这个功能：

方向键更改当前项目并选择它。

Ctrl方向键更改当前项目但不选择它。
Shift+方向键键更改当前项目并选择它。
Ctr+Space 切换当前项目的选择。
Tab/Backtab 将当前项目更改为下一个/上一个项目。
Home/End 选择模型中的第一个/最后一个项目。
Page up/Page down 按视图中的可见行数向上/向下滚动显示的行。

Ctrl+A 选择模型中的所有项目。

上面的操作假设选择模式允许操作。例如，如果选择模式为 QAbstractItemView::NoSelection，则无法选择项目。

如果继承 QAbstractItemView 并打算更新视口的内容，应该使用 viewport->update() 而不是 update() 因为所有绘画操作都在视口上进行。

二、类型成员

1、enum QAbstractItemView::CursorAction：此枚举描述了在项目之间导航的不同方式。

MoveUp：移动到当前项目上方的项目。
MoveDown：移动到当前项下的项。
MoveLeft：移动到当前项的左侧。
MoveRight：移动到当前项目的右侧。
MoveHome：移动到左上角的项目。
MoveEnd：移动到右下角的项目。
MovePageUp：在当前项目上方移动一页。
MovePageDown：在当前项目下方向下移动一页。
MoveNext：移动到当前项之后的项。
MovePrevious：移动到当前项之前的项。

2、enum QAbstractItemView::DragDropMode：描述视图可以操作的各种拖放事件。默认情况下，视图不支持拖放（NoDragDrop）。（注意使用的模型需要提供对拖放操作的支持）

NoDragDrop：不支持拖放。
DragOnly：视图只接受支持拖拽自己的item
DropOnly：视图只接受支持放下
DragDrop：视图同时支持拖和放
InternalMove：视图仅接受来自自身的移动（而非复制）操作

3、enum QAbstractItemView::DropIndicatorPosition：此枚举指示放置指示器相对于当前鼠标位置处的索引的位置。

OnItem：项将被拖放到索引上
AboveItem：项将被拖放在索引上方
BelowItem：项将被拖放在索引下方
OnViewport：该项目将被拖放在没有项目的视口区域上

4、enum QAbstractItemView::EditTrigger：此枚举描述将启动项目编辑的操作。

NoEditTriggers：无法编辑。
CurrentChanged：每当当前项目更改时开始编辑。
DoubleClicked：双击项目时开始编辑。
SelectedClicked：单击已选择的项目时开始编辑。
EditKeyPressed：当在项目上按下平台编辑键时开始编辑。
AnyKeyPressed：在项目上按下任意键时开始编辑。
AllEditTriggers：上述所有操作都开始编辑。

5、enum QAbstractItemView::ScrollHint

EnsureVisible：滚动以确保该项目可见
PositionAtTop：滚动以将项目放置在视口的顶部
PositionAtBottom：滚动以将项目定位在视口底部
PositionAtCenter：滚动以将项目定位在视口的中心

6、enum QAbstractItemView::ScrollMode：描述滚动条的行为方式。将滚动模式设置为 ScrollPerPixel 时，除非使用 setSingleStep() 明确设置，否则单步大小将自动调整。可以通过将单步长设置为-1 来恢复自动调整。

ScrollPerItem：该视图将一次滚动一项内容。
ScrollPerPixel：该视图将一次滚动一个像素的内容。

7、enum QAbstractItemView::SelectionBehavior：

SelectItems：选择单个项目
SelectRows：只选择行
SelectColumns：只选择列

8、enum QAbstractItemView::SelectionMode：此枚举指示视图如何响应用户选择。最常用的模式是 SingleSelection 和 ExtendedSelection。

SingleSelection：单选。单击所选项目时按下 Ctrl 键则取消选择该项目

ContiguousSelection：按下单选。但如果单击项目的同时按下 Shift 键，则当前项目和单击项目之间的所有项目都将被选中或取消选中，具体取决于单击项目的状态

ExtendedSelection：按下单选。但如果在单击某个项目时按下 Ctrl 键，则单击的项目将被切换，而所有其他项目都保持不变。如果单击项目时按下 Shift 键，则当前项目和单击项目之间的所有项目都被选中或取消选中，具体取决于单击项目的状态。可以通过将鼠标拖到多个项目上来选择它们

MultiSelection：多选
NoSelection：无法选择项目

9、enum QAbstractItemView::State：描述视图可以处于的不同状态。通常重新实现视图才用到。

NoState：默认状态
DraggingState：用户正在拖动项目
DragSelectingState：用户正在选择项目
EditingState：用户正在小部件编辑器中编辑项目
ExpandingState；用户正在打开项目的一个分支
CollapsingState：用户正在关闭项目的一个分支
AnimatingState：项目视图正在执行动画

三、属性成员

1、alternatingRowColors : bool

此属性保存是否使用交替颜色绘制背景。默认为 false。

如果此属性为true，项目背景将使用 QPalette::Base 和 QPalette::AlternateBase 绘制；否则背景将使用 QPalette::Base 颜色绘制。

2、autoScroll : bool

此属性保存是否启用拖动移动事件中的自动滚动。默认为 true。

如果此属性设置为 true，则如果用户在视口边缘的 16 像素内拖动，QAbstractItemView 会自动滚动视图的内容。如果当前项发生变化，则视图将自动滚动以确保当前项完全可见。

此属性仅在视口接受放置（drop）时才有效。

3、autoScrollMargin : int

此属性保存触发自动滚动时区域的大小。默认值为 16 像素。

4、defaultDropAction : Qt::DropAction

此属性保存将在 drag() 中默认使用的放置操作。

如果未设置该属性，则当支持的操作支持 CopyAction 时，放置操作为 CopyAction。

enum Qt::DropAction：

Qt::CopyAction：将数据复制到目标
Qt::MoveAction：将数据从源移动到目标
Qt::LinkAction：创建从源到目标的链接
Qt::ActionMask
Qt::IgnoreAction：对数据不做任何处理
Qt::TargetMoveAction：在 Windows 上，当拖拽数据的所有权应该由目标应用程序接管时使用该值，即源应用程序不应删除数据。在 X11 上，此值用于进行移动。 Mac 上不使用 TargetMoveAction。

5、dragDropMode : DragDropMode

此属性保存视图的拖拽模式。

6、dragDropOverwriteMode : bool

此属性保存视图的拖放行为。

如果为true，则选中的数据在放下时将覆盖现有的项目数据，而移动数据将清除该项目。

如果为false，则在删除数据时，所选数据将作为新项目插入。移动数据时，项目也会被删除。

7、dragEnabled : bool

该属性持有视图是否支持拖拽自己的items。

8、editTriggers : EditTriggers

此属性保存哪些操作将启动项目编辑。

此属性是 EditTrigger 定义的标志选择，使用 OR 运算符组合。

9、horizontalScrollMode : ScrollMode

此属性控制视图如何水平滚动其内容。滚动可以按像素或按项目完成。

它的默认值来自通过 QStyle::SH_ItemView_ScrollMode （样式指定的默认垂直和水平滚动模式。可以用 QAbstractItemView::setVerticalScrollMode() 和 QAbstractItemView::setHorizontalScrollMode() 覆盖）样式提示的样式。

10、iconSize : QSize

此属性保存项目图标的大小。

当视图可见时设置此属性将导致项目再次布局。

11、selectionBehavior : SelectionBehavior

此属性保存视图使用的选择行为。

12、selectionMode : SelectionMode

此属性保存视图在哪种选择模式下运行。

是否可以选择一个或多个项目，以及在多项目选择中，选择是否必须是连续范围的项目。

13、showDropIndicator : bool

此属性保存拖放项目时是否显示放置指示器。

14、tabKeyNavigation : bool

此属性保存是否启用带有 tab 和 backtab 的项目导航。

15、textElideMode : Qt::TextElideMode

此属性保存“...”在被省略的文本中的位置。

所有项目视图的默认值是 Qt::ElideRight。

enum Qt::TextElideMode：此枚举指定显示不适合的文本时省略号应出现的位置。

Qt::ElideLeft：文本的开头
Qt::ElideRight：文本的末尾
Qt::ElideMiddle：文本的中间
Qt::ElideNone：省略号不应出现在文本中

16、verticalScrollMode : ScrollMode

视图如何在垂直方向滚动其内容。和第9项类似。

四、成员函数

4.1、信号

1、void activated(const QModelIndex &index)

当用户激活由 index 指定的项目时，会发出此信号。

2、void clicked(const QModelIndex &index)

当鼠标左键单击时会发出此信号。鼠标点击的项目由索引指定。该信号仅在索引有效时发出。

3、void doubleClicked(const QModelIndex &index)

当双击鼠标按钮时会发出此信号。鼠标双击的项目由索引指定。该信号仅在索引有效时发出。

4、void entered(const QModelIndex &index)

当鼠标光标进入索引指定的项目时，会发出此信号。需要启用鼠标跟踪才能使用此功能。

5、void pressed(const QModelIndex &index)

当按下鼠标按钮时会发出此信号。鼠标按下的项目由索引指定。该信号仅在索引有效时发出。

使用 QGuiApplication::mouseButtons() 函数获取鼠标按钮的状态。

6、void viewportEntered()

当鼠标光标进入视口时发出此信号。需要启用鼠标跟踪才能使用此功能。

4.2、函数

1、void clearSelection()

取消选择所有选定的项目。当前索引不会改变。

2、void closeEditor(QWidget *editor, QAbstractItemDelegate::EndEditHint hint)

关闭给定的编辑器，然后释放它。hint 用于指定视图应如何响应编辑操作的结束。（用于委托）

3、void commitData(QWidget *editor)

将编辑器中的数据提交给模型。（用于委托）

4、void currentChanged(const QModelIndex ¤t, const QModelIndex &previous)

当前索引改变时会调用此槽函数。

5、void dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles = QList<int>())

当模型中具有给定角色的项目发生更改时，将调用此槽函数。更改的项目是从topLeft到bottomRight的项目。

注意：dataChanged() 不支持 Qt::ToolTipRole。

6、void edit(const QModelIndex &index)

如果可编辑，则开始编辑与给定索引对应的项目。

7、void editorDestroyed(QObject *editor)

当给定的编辑器被销毁时调用此函数。（用于委托）

8、void reset()

重置视图的内部状态。

9、void rowsAboutToBeRemoved(const QModelIndex &parent, int start, int end)

当行即将被删除时调用此槽函数。删除的行是parent项下从start到end的那些行。

10、void rowsInserted(const QModelIndex &parent, int start, int end)

类似，删除列。

11、void scrollToBottom() / void scrollToTop()

将视图滚动到底部 / 顶部。

12、void selectAll()

选择视图中的所有项目。

13、void selectionChanged(const QItemSelection &selected, const QItemSelection &deselected)

更改选择时调用此槽函数。先前的选择（可能为空）由 deselected 指定，新选择由 selected 指定。

14、void setCurrentIndex(const QModelIndex &index)

将当前项设置为索引处的项。

除非当前选择模式为 NoSelection，否则项目也会被选中。

要将项目设置为当前项目而不选择它，请调用：

selectionModel()->setCurrentIndex(index, QItemSelectionModel::NoUpdate);

15、void setRootIndex(const QModelIndex &index)

设置根项目。

16、void update(const QModelIndex &index)

更新给定索引占用的区域。

17、void updateGeometries()

更新视图的子小部件的几何形状。

18、void closePersistentEditor(const QModelIndex &index)

关闭给定索引处项目的持久编辑器。

19、QModelIndex currentIndex()

返回当前项目的模型索引。

20、void dragEnterEvent(QDragEnterEvent *event)

void dragLeaveEvent(QDragLeaveEvent *event)
void dragMoveEvent(QDragMoveEvent *event)
void dropEvent(QDropEvent *event)

拖拽相关事件。Qt拖放。

21、int horizontalOffset() / verticalOffset()

返回视图的水平/垂直偏移量。

22、QModelIndex indexAt(const QPoint &point)

返回视口坐标点处项目的模型索引。

23、QWidget * indexWidget(const QModelIndex &index)

返回给定索引处项目的小部件。

24、void initViewItemOption(QStyleOptionViewItem *option)

使用视图的调色板、字体、状态、对齐方式等初始化选项结构。

25、bool isIndexHidden(const QModelIndex &index)

如果给定索引引用的项目隐藏在视图中，则返回 true。

隐藏是视图特定的功能。例如，在 TableView 中，可以将列标记为隐藏或 TreeView 中的一行。

26、bool isPersistentEditorOpen(const QModelIndex &index)

返回是否为索引索引处的项目打开了持久编辑器。

27、QAbstractItemDelegate * itemDelegate() / void setItemDelegate(QAbstractItemDelegate *delegate)

QAbstractItemView 不取得委托的所有权。

警告：您不应在视图之间共享同一委托实例。这样做会导致不正确或不直观的编辑行为，因为连接到给定委托的每个视图都可能收到 closeEditor() 信号，并尝试访问、修改或关闭已关闭的编辑器。

28、QAbstractItemDelegate * itemDelegateForColumn(int column)

void setItemDelegateForColumn(int column, QAbstractItemDelegate *delegate)

为给定的列设置此视图和模型使用的给定项目委托。

列上的所有项目都将由委托绘制和管理，而不是使用默认委托（即 itemDelegate()）。

29、void setItemDelegateForRow(int row, QAbstractItemDelegate *delegate)

QAbstractItemDelegate * itemDelegateForRow(int row)

与上面类似，行。

30、QAbstractItemDelegate * itemDelegateForIndex(const QModelIndex &index)

返回此视图和模型为给定index使用的项目委托。

31、void keyboardSearch(const QString &search)

移动到并选中与字符串最匹配的项目。

32、void openPersistentEditor(const QModelIndex &index)

在给定索引处的项目上打开持久编辑器。如果不存在编辑器，则委托将创建一个新编辑器。

33、QModelIndex rootIndex()

返回模型根项的模型索引。根项是视图顶级项的父项。根可能无效。

34、void scheduleDelayedItemsLayout()

在事件处理开始时安排要执行的视图中项目的布局。

即使在处理事件之前多次调用 scheduleDelayedItemsLayout()，视图也只会进行一次布局。

35、void scrollTo(const QModelIndex &index, QAbstractItemView::ScrollHint hint = EnsureVisible)

如有必要，滚动视图以确保索引处的项目可见。视图将尝试根据给定的提示定位项目。

36、QModelIndexList selectedIndexes()

此便利函数返回视图中所有选定和非隐藏项索引的列表。该列表不包含重复项，并且未排序。

37、QItemSelectionModel::SelectionFlags selectionCommand(const QModelIndex &index, const QEvent *event = nullptr)

返回在更新选择以包含指定的索引时要使用的 SelectionFlags。event 是用户输入事件，例如鼠标或键盘事件。

38、QItemSelectionModel * selectionModel()

返回当前选择模型。

39、void setIndexWidget(const QModelIndex &index, QWidget *widget)

在给定索引处的项目上设置给定小部件，将小部件的所有权传递给视口。

给定小部件的 autoFillBackground 属性必须设置为 true，否则小部件的背景将是透明的，同时显示模型数据和给定索引处的项目。

如果索引小部件 A 被索引小部件 B 替换，则索引小部件 A 将被删除。

此函数应该只用于在与数据项对应的可见区域内显示静态内容。如果要显示自定义动态内容或实现自定义编辑器小部件，应改为委托（QStyledItemDelegate）。

40、void setModel(QAbstractItemModel *model)

设置要呈现的视图的模型。

此函数将创建并设置一个新的选择模型，替换之前使用 setSelectionModel() 设置的任何模型。但是，旧的选择模型不会被删除，因为它可能在多个视图之间共享。如果不再需要旧的选择模型，应手动删除。

QItemSelectionModel *m = view->selectionModel();
view->setModel(new model);
delete m;

如果旧模型和旧选择模型都没有父对象，或者它们的父对象是长期存在的对象，则最好调用它们的 deleteLater() 函数来显式删除它们。

除非它是模型的父对象，否则视图不会获得模型的所有权，因为模型可能在许多不同的视图之间共享。

41、void setSelection(const QRect &rect, QItemSelectionModel::SelectionFlags flags)

将选择标志应用于矩形 rect 中或与之接触的项目。

42、void setSelectionModel(QItemSelectionModel *selectionModel)

设置选择模型。

43、int sizeHintForColumn(int column) / int sizeHintForRow(int row)

返回指定列的宽度 / 高度大小提示。（项目的最大高度 / 宽度）（要控制行的高度，您必须重新实现 QAbstractItemDelegate::sizeHint() 函数。）

44、QSize sizeHintForIndex(const QModelIndex &index)

返回具有指定索引的项目的大小提示。

45、void startDrag(Qt::DropActions supportedActions)

通过使用给定的supportedActions 调用drag->exec() 开始拖动。

46、QRect visualRect(const QModelIndex &index)

返回索引处的项目占据的视口上的矩形。

47、QRegion visualRegionForSelection(const QItemSelection &selection) const

从给定选择中的项目的视口返回区域。

本文福利，莬费领取Qt开发学习资料包、技术视频，内容包括（C++语言基础，Qt编程入门，QT信号与槽机制，QT界面开发-图像绘制，QT网络，QT数据库编程，QT项目实战，QT嵌入式开发，Quick模块等等）↓↓↓↓↓↓见下面↓↓文章底部点击莬费领取↓↓

原文链接：https://blog.csdn.net/kenfan1647/article/details/119277723

Qt模型视图框架：QAbstractItemModel、QAbstractItemView

QAbstractItemModel

QAbstractItemView

猜你喜欢