一、描述
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
从给定选择中的项目的视口返回区域。