class QItemDelegate#

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

Inheritance diagram of PySide6.QtWidgets.QItemDelegate

概要#

属性#

  • clipping - 如果委托应剪辑绘制事件

方法#

虚拟方法#

静态函数#

注：

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

详细说明#

QItemDelegate 可用于为基于 QAbstractItemView 子类的项视图提供自定义显示特性和编辑小部件。使用代理来实现此目的允许显示和编辑机制能够自定义并独立于模型和视图开发。

QItemDelegate 类是 模型/视图类 之一，并且是 Qt 的 模型/视图框架 的组成部分。请注意，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 来提供自定义编辑器。在 颜色编辑器工厂示例 中，展示了如何通过默认项目编辑器工厂将自定义编辑器提供给委托。这样，不需要子类化 QItemDelegate 。另一种方法是重写 createEditor() 、 setEditorData() 、 setModelData() 和 updateEditorGeometry() 。该过程在 模型/视图编程概述文档 中有描述。

QStyledItemDelegate 与 QItemDelegate#

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

注：

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

属性clippingᅟ: bool#

此属性用于指定代理是否应该剪辑绘图事件。

此属性会将绘制剪辑设置为项目的大小。默认值为启用。当图像大小超过项目大小时，这种情况下很有用。

访问函数
__init__([parent=None])#
参数：:

parent – QObject

构造一个具有给定 parent 的项目代理。

decoration(option, variant)#
参数：:
返回类型：:

QPixmap

doCheck(option, bounding, variant)#
参数：:
返回类型：:

QRect

drawBackground(painter, option, index)#
参数：:

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

drawCheck(painter, option, rect, state)#
参数：:

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

drawDecoration(painter, option, rect, pixmap)#
参数：:

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

drawDisplay(painter, option, rect, text)#
参数：:

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

drawFocus(painter, option, rect)#
参数：:

使用给定的 painter 和样式 option 在由 rect 指定的矩形内绘制表示具有焦点的区域。

hasClipping()#
返回类型：:

布尔值

属性 clippingᅟ 的获取器。

itemEditorFactory()#
返回类型：:

QItemEditorFactory

返回项目代理使用的编辑器工厂。如果没有设置编辑器工厂，函数将返回 null。

另请参阅

setItemEditorFactory()

rect(option, index, role)#
参数：:
返回类型：:

QRect

静态selectedPixmap(pixmap, palette, enabled)#
参数：:
返回类型：:

QPixmap

setClipping(clip)#
参数：:

clip - bool

另请参阅

hasClipping()

属性 clippingᅟ 的设置器。

setItemEditorFactory(factory)#
参数：:

factory - QItemEditorFactory

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

另请参阅

itemEditorFactory()

setOptions(index, option)#
参数：:
返回类型：:

QStyleOptionViewItem

textRectangle(painter, rect, font, text)#
参数：:
返回类型：:

QRect