PySide6.QtWidgets.QItemDelegate

class QItemDelegate

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

PySide6.QtWidgets.QItemDelegate 的继承图

概要

属性

方法

虚拟方法

静态函数

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

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

QItemDelegate 类是 Model/View Classes 之一，并且是 Qt 的 model/view framework 的一部分。请注意，QStyledItemDelegate 已经接管了绘制 Qt 项目视图的工作。我们建议在创建新的委托时使用 QStyledItemDelegate。

在标准视图中显示自定义模型的项目时，通常只需确保模型为确定视图中项目外观的每个角色返回适当的数据即可。Qt的标准视图使用的默认委托使用此角色信息以用户期望的大多数常见形式显示项目。然而，有时需要对项目的外观进行比默认委托提供的更多控制。

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

在项目视图中编辑数据时，QItemDelegate 提供了一个编辑器小部件，这是一个在编辑时放置在视图顶部的小部件。编辑器由 QItemEditorFactory 创建；所有项目委托都安装了由 QItemEditorFactory 提供的默认静态实例。您可以使用 setItemEditorFactory() 设置自定义工厂，或使用 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提供自定义编辑器。以下代码展示了如何通过默认的项目编辑器工厂使自定义编辑器可用于委托。

editorFactory = QItemEditorFactory()
creator = QStandardItemEditorCreator()<MyFancyDateTimeEdit>()
editorFactory.registerEditor(QMetaType.QDateTime, creator)
QItemEditorFactory.setDefaultFactory(editorFactory)

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

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

另一种选择是重新实现 createEditor()、setEditorData()、setModelData() 和 updateEditorGeometry()。这个过程在 Model/View Programming overview documentation 中有描述。

QStyledItemDelegate 与 QItemDelegate

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

注意

当使用from __feature__ import true_property时，属性可以直接使用，否则通过访问器函数使用。

property clippingᅟ: bool

此属性表示委托是否应裁剪绘制事件。

此属性将设置绘制剪辑为项目的大小。默认值为开启。这对于图像大于项目大小的情况非常有用。

Access functions:
__init__([parent=None])
Parameters:

父对象 – QObject

使用给定的 parent 构造一个项目委托。

decoration(option, variant)
Parameters:
Return type:

QPixmap

doCheck(option, bounding, variant)
Parameters:
Return type:

QRect

drawBackground(painter, option, index)
Parameters:

使用给定的painter和样式option，为指定的index渲染项目背景。

drawCheck(painter, option, rect, state)
Parameters:

在由rect指定的矩形内渲染一个检查指示器，使用给定的painter和样式option，并使用给定的state。

drawDecoration(painter, option, rect, pixmap)
Parameters:

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

drawDisplay(painter, option, rect, text)
Parameters:

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

drawFocus(painter, option, rect)
Parameters:

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

hasClipping()
Return type:

布尔

属性 clippingᅟ 的获取器。

itemEditorFactory()
Return type:

QItemEditorFactory

返回项目委托使用的编辑器工厂。如果未设置编辑器工厂，函数将返回null。

另请参阅

setItemEditorFactory()

rect(option, index, role)
Parameters:
Return type:

QRect

static selectedPixmap(pixmap, palette, enabled)
Parameters:
Return type:

QPixmap

setClipping(clip)
Parameters:

clip – 布尔值

另请参阅

hasClipping()

属性 clippingᅟ 的设置器。

setItemEditorFactory(factory)
Parameters:

工厂 – QItemEditorFactory

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

另请参阅

itemEditorFactory()

setOptions(index, option)
Parameters:
Return type:

QStyleOptionViewItem

textRectangle(painter, rect, font, text)
Parameters:
Return type:

QRect