QAbstractItemDelegate 类

QAbstractItemDelegate 类用于显示和编辑来自模型的数据项。 更多...

Header: #include <QAbstractItemDelegate>
CMake: find_package(Qt6 COMPONENTS Widgets REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
继承: QObject
继承者:

QItemDelegate and QStyledItemDelegate

公共类型

enum EndEditHint { NoHint, EditNextItem, EditPreviousItem, SubmitModelCache, RevertModelCache }

公共函数

QAbstractItemDelegate (QObject * parent = nullptr)
virtual ~QAbstractItemDelegate ()
virtual QWidget * createEditor (QWidget * parent , const QStyleOptionViewItem & option , const QModelIndex & index ) const
virtual void destroyEditor (QWidget * editor , const QModelIndex & index ) const
virtual bool editorEvent (QEvent * event , QAbstractItemModel * model , const QStyleOptionViewItem & option , const QModelIndex & index )
virtual bool helpEvent (QHelpEvent * event , QAbstractItemView * view , const QStyleOptionViewItem & option , const QModelIndex & index )
virtual void paint (QPainter * painter , const QStyleOptionViewItem & option , const QModelIndex & index ) const = 0
virtual void setEditorData (QWidget * editor , const QModelIndex & index ) const
virtual void setModelData (QWidget * editor , QAbstractItemModel * model , const QModelIndex & index ) const
virtual QSize sizeHint (const QStyleOptionViewItem & option , const QModelIndex & index ) const = 0
virtual void updateEditorGeometry (QWidget * editor , const QStyleOptionViewItem & option , const QModelIndex & index ) const

信号

void closeEditor (QWidget * editor , QAbstractItemDelegate::EndEditHint hint = NoHint)
void commitData (QWidget * editor )
void sizeHintChanged (const QModelIndex & index )

详细描述

QAbstractItemDelegate 为模型/视图体系结构中的委托,提供接口和公共功能。委托在视图中显示单个项,并处理模型数据的编辑。

QAbstractItemDelegate 类是一种 模型/视图类 且属于 Qt 的 模型/视图框架 .

要以自定义方式渲染项,必须实现 paint () 和 sizeHint ()。 QStyledItemDelegate 类为这些函数提供默认实现;若不需要自定义渲染,以子类化该类取而代之。

范例,在项中绘制进度条;在包管理程序范例中。

创建 WidgetDelegate 类,继承自 QStyledItemDelegate 。履行绘制在 paint () 函数:

void WidgetDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option,
                           const QModelIndex &index) const
{
    if (index.column() == 1) {
        int progress = index.data().toInt();
        QStyleOptionProgressBar progressBarOption;
        progressBarOption.rect = option.rect;
        progressBarOption.minimum = 0;
        progressBarOption.maximum = 100;
        progressBarOption.progress = progress;
        progressBarOption.text = QString::number(progress) + "%";
        progressBarOption.textVisible = true;
        QApplication::style()->drawControl(QStyle::CE_ProgressBar,
                                           &progressBarOption, painter);
    } else
        QStyledItemDelegate::paint(painter, option, index);
							

注意,使用 QStyleOptionProgressBar 并初始化其成员。然后可以使用当前 QStyle 来绘制它。

要提供自定义编辑,有 2 种方式可以使用。第 1 种方式是创建编辑器 Widget 并将其直接显示在项顶部。要做到这点,必须重实现 createEditor () 以提供编辑器 Widget, setEditorData () 以采用来自模型的数据填充编辑器,和 setModelData () 以便委托可以采用来自编辑器的数据更新模型。

第 2 种方式是直接处理用户事件通过重实现 editorEvent ().

另请参阅 模型/视图编程 , QStyledItemDelegate , 像素器范例 , QStyledItemDelegate ,和 QStyle .

成员类型文档编制

enum QAbstractItemDelegate:: EndEditHint

此枚举描述委托可以赋予模型和视图组件的不同提示,以使用户体验舒适地在模型中编辑数据。

常量 描述
QAbstractItemDelegate::NoHint 0 没有推荐要履行的操作。

这些提示让委托影响视图的行为:

常量 描述
QAbstractItemDelegate::EditNextItem 1 视图应使用委托来打开下一视图项的编辑器。
QAbstractItemDelegate::EditPreviousItem 2 视图应使用委托来打开上一视图项的编辑器。

注意,自定义视图可能将下一和上一解释成不同概念。

以下提示最有用,当使用模型缓存数据时,譬如:操纵本地数据以提高性能 (或节省网络带宽) 的那些模型。

常量 描述
QAbstractItemDelegate::SubmitModelCache 3 若模型缓存数据,应将缓存数据写出到底层数据存储。
QAbstractItemDelegate::RevertModelCache 4 若模型缓存数据,应丢弃缓存数据并将其替换为来自底层数据存储的数据。

Although models and views should respond to these hints in appropriate ways, custom components may ignore any or all of them if they are not relevant.

成员函数文档编制

QAbstractItemDelegate:: QAbstractItemDelegate ( QObject * parent = nullptr)

创建新的抽象项委托采用给定 parent .

[signal] void QAbstractItemDelegate:: closeEditor ( QWidget * editor , QAbstractItemDelegate::EndEditHint hint = NoHint)

This signal is emitted when the user has finished editing an item using the specified editor .

hint provides a way for the delegate to influence how the model and view behave after editing is completed. It indicates to these components what action should be performed next to provide a comfortable editing experience for the user. For example, if EditNextItem is specified, the view should use a delegate to open an editor on the next item in the model.

另请参阅 EndEditHint .

[signal] void QAbstractItemDelegate:: commitData ( QWidget * editor )

此信号必须被发射当 editor 小部件已完成数据编辑,且想要将其写回模型。

[signal] void QAbstractItemDelegate:: sizeHintChanged (const QModelIndex & index )

此信号必须被发射当 sizeHint () of index 改变。

视图自动连接到此信号并重新布局项,因为有必要。

[virtual] QAbstractItemDelegate:: ~QAbstractItemDelegate ()

销毁抽象项委托。

[virtual] QWidget *QAbstractItemDelegate:: createEditor ( QWidget * parent , const QStyleOptionViewItem & option , const QModelIndex & index ) const

Returns the editor to be used for editing the data item with the given index . Note that the index contains information about the model being used. The editor's parent widget is specified by parent , and the item options by option .

基实现返回 nullptr . If you want custom editing you will need to reimplement this function.

返回编辑器 Widget 应该拥有 Qt::StrongFocus ;否则, QMouseEvent s received by the widget will propagate to the view. The view's background will shine through unless the editor paints its own background (e.g., with setAutoFillBackground() ).

另请参阅 destroyEditor (), setModelData (),和 setEditorData ().

[virtual, since 5.0] void QAbstractItemDelegate:: destroyEditor ( QWidget * editor , const QModelIndex & index ) const

被调用当 editor is no longer needed for editing the data item with the given index and should be destroyed. The default behavior is a call to deleteLater on the editor. It is possible e.g. to avoid this delete by reimplementing this function.

该函数在 Qt 5.0 引入。

另请参阅 createEditor ().

[virtual] bool QAbstractItemDelegate:: editorEvent ( QEvent * event , QAbstractItemModel * model , const QStyleOptionViewItem & option , const QModelIndex & index )

当开始编辑项时,此函数被调用采用 event 触发编辑, model index 对于项,和 option 用于渲染项。

Mouse events are sent to editorEvent() even if they don't start editing of the item. This can, for instance, be useful if you wish to open a context menu when the right mouse button is pressed on an item.

基实现返回 false (指示它没有处理事件)。

[virtual] bool QAbstractItemDelegate:: helpEvent ( QHelpEvent * event , QAbstractItemView * view , const QStyleOptionViewItem & option , const QModelIndex & index )

Whenever a help event occurs, this function is called with the event view option index that corresponds to the item where the event occurs.

返回 true 若委托可以处理事件;否则返回 false . A return value of true indicates that the data obtained using the index had the required role.

For QEvent::ToolTip and QEvent::WhatsThis events that were handled successfully, the relevant popup may be shown depending on the user's system configuration.

另请参阅 QHelpEvent .

[pure virtual] void QAbstractItemDelegate:: paint ( QPainter * painter , const QStyleOptionViewItem & option , const QModelIndex & index ) const

This pure abstract function must be reimplemented if you want to provide custom rendering. Use the painter and style option to render the item specified by the item index .

若重实现此,还必须重实现 sizeHint ().

[virtual] void QAbstractItemDelegate:: setEditorData ( QWidget * editor , const QModelIndex & index ) const

Sets the contents of the given editor to the data for the item at the given index . Note that the index contains information about the model being used.

基实现什么都不做。若想要自定义编辑,需要重实现此函数。

另请参阅 setModelData ().

[virtual] void QAbstractItemDelegate:: setModelData ( QWidget * editor , QAbstractItemModel * model , const QModelIndex & index ) const

设置用于项的数据在给定 index model 到内容为给定 editor .

基实现什么都不做。若想要自定义编辑,需要重实现此函数。

另请参阅 setEditorData ().

[pure virtual] QSize QAbstractItemDelegate:: sizeHint (const QStyleOptionViewItem & option , const QModelIndex & index ) const

必须重实现此纯抽象函数,若想要提供自定义渲染。选项的指定通过 option 和模型项通过 index .

若重实现此,还必须重实现 paint ().

[virtual] void QAbstractItemDelegate:: updateEditorGeometry ( QWidget * editor , const QStyleOptionViewItem & option , const QModelIndex & index ) const

Updates the geometry of the editor for the item with the given index , according to the rectangle specified in the option . If the item has an internal layout, the editor will be laid out accordingly. Note that the index contains information about the model being used.

基实现什么都不做。若想要自定义编辑,必须重实现此函数。