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

從給定選擇中的項目的視口傳回區域。