模型视图(18)：【类】QItemDelegate[官翻]

QItemDelegate 类

QItemDelegate类为来自模型的数据项提供显示和编辑工具。

Header:	#include < QItemDelegate >
qmake:	QT += widgets
Inherits:	QAbstractItemDelegate
Inherited By:	QSqlRelationalDelegate

详述

QItemDelegate可用于为基于QAbstractItemView子类的项目视图提供自定义显示功能和编辑器小部件。 为此，使用委托可以自定义以及开发独立于模型和视图的显示和编辑机制。

QItemDelegate类是模型/视图类之一，是Qt模型/视图框架的一部分。注意，QStyledItemDelegate已经接管了绘制Qt项目视图的工作。我们建议在创建新的委托时使用QStyledItemDelegate。

当在标准视图中显示自定义模型中的项时，通常只需确保模型为确定项在视图中的外观的每个角色返回适当的数据就足够了。Qt标准视图使用的默认委托使用这个角色信息来显示用户期望的大多数常见表单中的项。然而，有时需要对项的外观拥有比默认委托更大的控制。

这个类提供了在视图中绘制项数据和从项模型中编辑数据的函数的默认实现。提供在QAbstractItemDelegate中定义的paint()和sizeHint()虚函数的默认实现，以确保委托实现视图所期望的正确的基本行为。您可以在子类中重新实现这些函数，以自定义项的外观。

在编辑项视图中的数据时，QItemDelegate提供一个编辑器小部件，编辑时，这个小部件位于视图顶部。编辑器使用QItemEditorFactory创建;在所有项委托上安装QItemEditorFactory提供的默认静态实例。您可以使用setItemEditorFactory()来设置一个自定义工厂，或者使用QItemEditorFactory::setDefaultFactory()来设置一个新的默认工厂。要编辑的是存储在item模型中的Qt::EditRole数据。

这里只重新实现了基于widget的委托的标准编辑功能:

• createEditor()返回用于从模型中更改数据的小部件，并且可以重新实现以定制编辑行为。
• setEditorData()为小部件提供要操作的数据。
• updateEditorGeometry()确保编辑器相对于项视图正确显示。
• setModelData()返回更新后的数据到模型。

closeEditor()信号表明用户已经完成了数据编辑，编辑器小部件可以被销毁。

标准角色和数据类型

Qt提供的标准视图使用的默认委托将每个标准角色(由Qt::ItemDataRole定义)与特定的数据类型关联起来。以这些类型返回数据的模型可以影响委托的外观，如下表所述。

Role	Accepted Types
Qt::BackgroundRole	QBrush
Qt::BackgroundColorRole	QColor (obsolete; use Qt::BackgroundRole instead)
Qt::CheckStateRole	Qt::CheckState
Qt::DecorationRole	QIcon, QPixmap and QColor
Qt::DisplayRole	使用字符串表示的QString和类型
Qt::EditRole	参见QItemEditorFactory了解详细信息
Qt::FontRole	QFont
Qt::SizeHintRole	QSize
Qt::TextAlignmentRole	Qt::Alignment
Qt::ForegroundRole	QBrush
Qt::TextColorRole	QColor (obsolete; use Qt::ForegroundRole instead)

如果默认委托不允许您所需的定制级别(无论是用于显示目的还是用于编辑数据)，则可以子类化QItemDelegate来实现所需的行为。

子类化

当子类化QItemDelegate以创建使用自定义呈现器显示项的委托时，重要的是要确保委托能够为所有需要的状态呈现项;例如选中、禁用、选中。paint()函数的文档包含一些提示，说明如何实现这一点。

您可以使用QItemEditorFactory提供自定义编辑器。Color Editor Factory Example展示了如何使用默认项编辑器工厂的委托使用自定义编辑器。这样，就不需要继承QItemDelegate的子类。另一种方法是重新实现createEditor()、setEditorData()、setModelData()和updateEditorGeometry()。这个过程在Spin Box Delegate Example中进行了描述。

QStyledItemDelegate与QItemDelegate

从Qt 4.4开始，有两个委托类:QItemDelegate和QStyledItemDelegate。但是，默认的委托是QStyledItemDelegate。这两个类独立于绘制视图项和为视图项提供编辑器。它们之间的区别是QStyledItemDelegate使用当前样式来绘制它的项。因此，我们建议在实现自定义委托或使用Qt样式表时使用QStyledItemDelegate作为基类。任何类所需的代码都应该是相等的，除非自定义委托需要使用绘图样式。

属性

1. clipping : bool 委托是否剪辑绘画事件
   这个属性将把绘画剪辑设置为项目的大小。默认值是on。它对于图像大于项目大小的情况非常有用。

公共函数

1. QItemDelegate(QObject *parent = nullptr)
2. virtual ~QItemDelegate()
3. bool hasClipping() const
4. void setClipping(bool clip)
5. QItemEditorFactory * itemEditorFactory() const 返回项目委托使用的编辑器工厂
   如果没有设置编辑器工厂，函数将返回null。
6. void setItemEditorFactory(QItemEditorFactory *factory) 将项委托使用的编辑器工厂设置为指定的工厂
   如果未设置编辑器工厂，则项委托将使用默认的编辑器工厂。

重新实现的公共函数

1. virtual QWidget * createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const override
2. virtual void paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const override
3. virtual void setEditorData(QWidget *editor, const QModelIndex &index) const override
4. virtual void setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const override
5. virtual QSize sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const override
6. virtual void updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const override

受保护的函数

1. void drawBackground(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const
2. virtual void drawCheck(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, Qt::CheckState state) const
3. virtual void drawDecoration(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QPixmap &pixmap) const
4. virtual void drawDisplay(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QString &text) const
5. virtual void drawFocus(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect) const

重新实现的受保护的函数

1. virtual bool editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index) override

2. virtual bool eventFilter(QObject *editor, QEvent *event) override
   如果给定的编辑器是有效的QWidget并且处理了给定的事件，则返回true;否则返回false。默认情况下处理以下按键事件:

   • Tab
   • Backtab
   • Enter
   • Return
   • Esc

   在Tab、Backtab、Enter和Return键按下事件的情况下，编辑器的数据被提交给模型，编辑器关闭。如果事件是Tab键按下，视图将打开视图中下一个项目的编辑器。同样，如果事件是按下Backtab键，视图将在视图中的前一项上打开编辑器。

   如果事件是Esc按键事件，编辑器将在不提交其数据的情况下关闭。

参考

• Color Editor Factory Example
• Spin Box Delegate Example
• Settings Editor Example
• Icons Example