模型视图(19)：【类】QStyledItemDelegate[官翻]

QStyledItemDelegate 类

QStyledItemDelegate类为模型中的数据项提供了显示和编辑工具。

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

详述

当在Qt项目视图中显示来自模型的数据时，例如，一个QTableView，单个项目是由委托绘制的。此外，在编辑项时，它还提供一个编辑器小部件，在进行编辑时，该小部件被放置在项视图的顶部。QStyledItemDelegate是所有Qt项视图的默认委托，并且在创建它们时安装在它们上面。

QStyledItemDelegate类是一个模型/视图类，是Qt模型/视图框架的一部分。委托允许独立于模型和视图开发项的显示和编辑。

对模型中项目的数据赋一个ItemDataRole;每个项目可以为每个角色存储一个QVariant。QStyledItemDelegate实现了用户期望的最常见数据类型的显示和编辑，包括布尔值、整数和字符串。

根据它们在模型中所扮演的角色，将绘制不同的数据。下表描述了角色和委托可以为每个角色处理的数据类型。通常，确保模型为每个角色返回适当的数据，以确定视图中项的外观就足够了。

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)

编辑器使用QItemEditorFactory创建;在所有项委托上安装QItemEditorFactory提供的默认静态实例。您可以使用setItemEditorFactory()来设置一个自定义工厂，或者使用QItemEditorFactory::setDefaultFactory()来设置一个新的默认工厂。要编辑的是存储在item模型中的具有EditRole的数据。有关项目编辑器工厂的更高级介绍，请参阅QItemEditorFactory类。颜色编辑器工厂示例展示了如何使用工厂创建自定义编辑器。

子类化QStyledItemDelegate

如果委托不支持绘制你需要的数据类型，或者你想定制项的绘制，你需要继承QStyledItemDelegate的子类，并重新实现paint()，可能还有sizeHint()。paint()函数会为每一项单独调用，使用sizeHint()，您可以为每一项指定提示。

当重新实现paint()时，人们通常会处理想要绘制的数据类型，并对其他类型使用超类实现。

复选框指示符的绘制由当前样式执行。样式还指定了为不同的数据角色绘制数据的大小和边框。项目本身的边界矩形也是根据样式计算的。当绘制已经支持的数据类型时，询问这些包围矩形的样式是一个好主意。QStyle类描述更详细地描述了这一点。

如果您希望改变任何由样式或绘制复选框指示符计算出的边框，您可以子类化QStyle。但是请注意，项目的大小也会受到重新实现sizeHint()的影响。

自定义委托可以提供编辑器而不使用编辑器项工厂。在这种情况下，以下虚函数必须重新实现:

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

Star Delegate示例通过重新实现这些方法来创建编辑器。

QStyledItemDelegate与QItemDelegate

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

如果您希望自定义项视图的绘制，则应该实现自定义样式。有关详细信息，请参阅QStyle类文档。

公共函数

1. QStyledItemDelegate(QObject *parent = nullptr)

2. virtual ~QStyledItemDelegate()

3. virtual QString displayText(const QVariant &value, const QLocale &locale) const
   这个函数返回一个字符串，委托将使用这个字符串在地区中显示模型的Qt::DisplayRole。value是模型提供的Qt::DisplayRole的值。

   默认实现使用QLocale::toString将值转换为QString。

   对于空的模型索引，即模型返回无效QVariant的索引，不会调用此函数。

4. QItemEditorFactory * itemEditorFactory() const

5. void setItemEditorFactory(QItemEditorFactory *factory) 将项委托使用的编辑器工厂设置为指定的工厂
   如果未设置编辑器工厂，则项委托将使用默认的编辑器工厂。

重写的公共函数

1. virtual QWidget * createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const override
   返回用于编辑由index指定要编辑的项的小部件 父小部件和样式选项用于控制编辑器小部件的显示方式。

2. virtual void paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const override 使用给定的画家和样式选项为索引指定的项目呈现委托
   这个函数使用视图的QStyle绘制项目。

   在子类中重新实现paint时, 使用initStyleOption()以与QStyledItemDelegate相同的方式设置选项。

   只要有可能，在绘制时使用该选项。特别是它的rect变量来决定在哪里绘制，以及它的状态来决定它是启用还是选中。
   绘制完成后，应该确保画家返回到调用此函数时提供的状态。例如，在绘制之前调用QPainter::save()，在绘制之后调用QPainter::restore()可能是有用的。

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
   考虑选项提供的样式信息，返回委托显示由index指定的项所需的大小
   这个函数使用视图的QStyle来确定项目的大小。

6. virtual void updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const override
   根据给定的样式选项更新由index指定的项的编辑器

受保护的函数

1. virtual void initStyleOption(QStyleOptionViewItem *option, const QModelIndex &index) 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

   如果编辑器的类型是QTextEdit或QPlainTextEdit，则不处理输入和返回键。

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

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

参考

• Star Delegate Example
• Spin Box Delegate Example
• Color Editor Factory Example