Qt模型视图框架：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 &current, 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

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