QItemDelegate 类

QItemDelegate 类提供了模型中的数据项的显示和编辑功能。更多信息...

头文件	#include <QItemDelegate>
CMake	find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake	QT += widgets
继承	QAbstractItemDelegate

所有成员的列表，包括继承而来的成员

属性

clipping : bool

公共函数

	QItemDelegate(QObject *parent = nullptr)
virtual	~QItemDelegate()
bool	hasClipping() const
QItemEditorFactory *	itemEditorFactory() const
void	setClipping(bool clip)
void	setItemEditorFactory(QItemEditorFactory *factory)

重新实现公共函数

virtual QWidget *	createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const override
virtual void	paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const override
virtual void	setEditorData(QWidget *editor, const QModelIndex &index) const override
virtual void	setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const override
virtual QSize	sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const override
virtual void	updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const override

保护函数

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

重新实现保护函数

virtual bool	editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index) override
virtual bool	eventFilter(QObject *editor, QEvent *event) override

详细描述

QItemDelegate可用于为基于QAbstractItemView子类的项视图提供自定义显示功能和编辑小部件。使用委托来实现这一目的允许显示和编辑机制在模型和视图之外独立定制和开发。

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

在标准视图中显示自定义模型中的项时，通常只需要确保模型为确定视图中项外观的每个角色返回适当的数据。Qt标准视图使用的默认代理使用此角色信息在大多数用户期望的常见表单中显示项。然而，有时需要对项外观的控件比默认代理能提供的还要多。

此类提供了在视图中绘制项数据和从项模型编辑数据的功能的默认实现。为了确保代理实现了视图所需的基本行为，提供了定义在QAbstractItemDelegate中的paint()和sizeHint()虚拟函数的默认实现。您可以在子类中重实现这些函数以自定义项的外观。

在项视图中编辑数据时，QItemDelegate提供了一个编辑小部件，这是在编辑进行时放置在视图顶部的小部件。编辑器是用QItemEditorFactory创建的；由QItemEditorFactory提供的默认静态实例已安装到所有项代理中。您可以使用setItemEditorFactory()设置自定义工厂，或使用QItemEditorFactory::setDefaultFactory()设置新的默认工厂。被编辑的是项模型中存储的带有Qt::EditRole的数据。

此处仅重实现了基于小部件的代理的标准编辑功能

createEditor()返回用于更改模型数据的控件，并且可以重实现以自定义编辑行为。
setEditorData()提供用于操作的数据的控件。
updateEditorGeometry()确保编辑器正确地显示在项视图范围内。
setModelData()将更新后的数据返回给模型。

closeEditor()信号表示用户已完成编辑数据，并且可以销毁编辑器小部件。

标准角色和数据类型

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

角色	接受的数据类型
Qt::BackgroundRole	QBrush (
Qt::CheckStateRole	Qt::CheckState
Qt::DecorationRole	QIcon、QPixmap 以及 QColor
Qt::DisplayRole	QString 和具有字符串表示的类型
Qt::EditRole	有关详细信息，请参阅 QItemEditorFactory
Qt::FontRole	QFont
Qt::SizeHintRole	QSize
Qt::TextAlignmentRole	Qt::Alignment
Qt::ForegroundRole	QBrush (

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

子类化

在子类化 QItemDelegate 以创建使用自定义渲染器显示项的委托时，确保委托可以适当地渲染所有所需状态的项目非常重要，例如选中、禁用、勾选。有关如何实现此功能的提示，请参阅 paint() 函数的文档。

您可以通过使用 QItemEditorFactory 来提供自定义编辑器。以下代码演示了如何通过默认项编辑器工厂使自定义编辑器可用于委托。

QItemEditorFactory *editorFactory = new QItemEditorFactory;
QItemEditorCreatorBase *creator = new QStandardItemEditorCreator<MyFancyDateTimeEdit>();
editorFactory->registerEditor(QMetaType::QDateTime, creator);

QItemEditorFactory::setDefaultFactory(editorFactory);

设置默认工厂后，所有标准项委托都将使用它（也包括在设置默认工厂之前创建的委托）。

这样，您可以避免子类化 QItemDelegate，并使用提供的编辑器（如上述示例中的 MyFancyDateTimeEdit）编辑指定类型的所有值。

另一种选择是重新实现 createEditor()、setEditorData()、setModelData() 以及 updateEditorGeometry()。有关此过程的描述，请参阅模型/视图编程概述文档。

QStyledItemDelegate 与 QItemDelegate 对比

自 Qt 4.4 以来，存在两个委托类：QItemDelegate 和 QStyledItemDelegate。但是，默认委托是 QStyledItemDelegate。这两个类是绘制和为视图中的项目提供编辑器的独立替代品。它们之间的区别在于 QStyledItemDelegate 使用当前样式来绘制其项。因此，我们建议在实现自定义委托或使用 Qt 样式表时使用 QStyledItemDelegate 作为基类。除非自定义委托需要使用样式进行绘制，否则两个类所需的代码应相等。

另请参阅 委托类、QStyledItemDelegate 以及 QAbstractItemDelegate。

属性文档

裁剪 : bool

如果委托应裁剪绘制事件

此属性将绘制裁剪设置为项的大小。默认值为开启。在图像大小超过项大小时很有用。

访问函数

bool	hasClipping() const
void	setClipping(bool clip)

成员函数文档

`[显式]` QItemDelegate::QItemDelegate(QObject **parent* = nullptr)

使用给定的父对象构建一个项目委托。

`[虚函数 noexcept]` QItemDelegate::~QItemDelegate()

销毁项目委托。

`[重写虚函数]` QWidget *QItemDelegate::createEditor(QWidget **parent, const QStyleOptionViewItem &option, const QModelIndex &index*) const

重写： QAbstractItemDelegate::createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const.

返回用于编辑由 index 指定项的 widget。使用 parent widget 和样式 option 来控制编辑器 widget 的外观。

另请参阅QAbstractItemDelegate::createEditor.

`[受保护]` void QItemDelegate::drawBackground(QPainter **painter, const QStyleOptionViewItem &option, const QModelIndex &index*) const

使用给定的 painter 和样式 option 绘制给定 index 的项背景。

`[虚受保护]` void QItemDelegate::drawCheck(QPainter **painter, const QStyleOptionViewItem &option, const QRect &rect, Qt::CheckState state*) const

使用给定的 painter 和样式 option，在由 rect 指定的矩形内绘制复选指示器，并使用给定的 state。

`[虚受保护]` void QItemDelegate::drawDecoration(QPainter **painter, const QStyleOptionViewItem &option, const QRect &rect, const QPixmap &pixmap*) const

使用给定的 painter 和样式 option 在由 rect 指定的矩形内绘制装饰 pixmap。

`[虚受保护]` void QItemDelegate::drawDisplay(QPainter **painter, const QStyleOptionViewItem &option, const QRect &rect, const QString &text*) const

使用给定的 painter 和样式 option，在由 rect 指定的矩形内绘制项视图 text。

`[虚受保护]` void QItemDelegate::drawFocus(QPainter **painter, const QStyleOptionViewItem &option, const QRect &rect*) const

使用指定的 painter 和样式 option 渲染矩形 rect 指定的区域，表示它具有焦点。

`[继承虚保护]` bool QItemDelegate::editorEvent(QEvent **event*, QAbstractItemModel **model, const QStyleOptionViewItem &option, const QModelIndex &index*)

重写: QAbstractItemDelegate::editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index).

`[继承虚保护]` bool QItemDelegate::eventFilter(QObject **editor*, QEvent **event*)

重写: QObject::eventFilter(QObject *watched, QEvent *event).

如果给定的 editor 是有效的 QWidget，并且给定的 event 被处理，则返回 true；否则返回 false。以下按键事件默认被处理：

Tab
Backtab
Enter
Return
Esc

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

如果事件是 Esc 按键事件，编辑器将关闭 而不提交 其数据。

另请参阅 commitData() 和 closeEditor().

QItemEditorFactory *QItemDelegate::itemEditorFactory() const

返回由项代理使用的编辑器工厂。如果没有设置编辑器工厂，该函数将返回空指针。

另请参阅 setItemEditorFactory().

`[继承虚]` void QItemDelegate::paint(QPainter **painter, const QStyleOptionViewItem &option, const QModelIndex &index*) const

重写: QAbstractItemDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const.

使用指定的 painter 和样式 option，根据 index 为指定的项目渲染代理。

在子类中重写此函数时，您应使用选项的 rect 变量更新选项持有的区域，并使用选项的 state 变量来确定要显示的项目状态，并根据此调整其绘制方式。

例如，选中的项目可能需要以与未选中的项目不同的方式显示，如下面的代码所示

if (option.state & QStyle::State_Selected)
    painter->fillRect(option.rect, option.palette.highlight());

绘画后，应确保画家恢复到调用此函数时提供的初始状态。例如，在绘画前调用 QPainter::save() 以及绘画后调用 QPainter::restore() 可能很有用。

另请参阅 QStyle::State。

`[重写虚函数]` void QItemDelegate::setEditorData(QWidget **editor, const QModelIndex &index*) const

重写：QAbstractItemDelegate::setEditorData(QWidget *editor, const QModelIndex &index) const。

将显示和由编辑器编辑的数据设置为模型指定项的数据。

默认实现将数据存储在编辑器小部件的用户属性中。

另请参阅 QMetaProperty::isUser。

void QItemDelegate::setItemEditorFactory(QItemEditorFactory **factory*)

将编辑器工厂设置为要由项目委托使用的指定 factory。如果没有设置编辑器工厂，项目委托将使用默认的编辑器工厂。

另请参阅 itemEditorFactory。

`[重写虚函数]` void QItemDelegate::setModelData(QWidget **editor*, QAbstractItemModel **model, const QModelIndex &index*) const

重写：QAbstractItemDelegate::setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const。

从编辑器小部件获取数据并将其存储在指定 model 项 index 的位置。

默认实现从编辑器小部件的用户属性获取要存储的数据模型中的值。

另请参阅 QMetaProperty::isUser。

`[重写虚函数]` QSize QItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const

重写：QAbstractItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const。

根据提供的样式信息返回由委托在显示由 index 指定的项所需的尺寸。

在重写此函数时，请注意，对于文本项，QItemDelegate 会为文本的长度添加一个边距（即 2 * QStyle::PM_FocusFrameHMargin）。

`[重写虚函数]` void QItemDelegate::updateEditorGeometry(QWidget **editor, const QStyleOptionViewItem &option, const QModelIndex &index*) const

重写：QAbstractItemDelegate::updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const。

根据提供的样式信息更新由 index 指定项的 editor。

QItemDelegate 类

属性

公共函数

重新实现公共函数

保护函数

重新实现保护函数

详细描述

标准角色和数据类型

子类化

QStyledItemDelegate 与 QItemDelegate 对比

属性文档

裁剪 : bool

成员函数文档

[显式] QItemDelegate::QItemDelegate(QObject *parent = nullptr)

[虚函数 noexcept] QItemDelegate::~QItemDelegate()

[重写虚函数] QWidget *QItemDelegate::createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const

[受保护] void QItemDelegate::drawBackground(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const

[虚受保护] void QItemDelegate::drawCheck(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, Qt::CheckState state) const

[虚受保护] void QItemDelegate::drawDecoration(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QPixmap &pixmap) const

[虚受保护] void QItemDelegate::drawDisplay(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QString &text) const

[虚受保护] void QItemDelegate::drawFocus(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect) const

[继承虚保护] bool QItemDelegate::editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index)

[继承虚保护] bool QItemDelegate::eventFilter(QObject *editor, QEvent *event)