QDesignerPropertySheetExtension Class

QDesignerPropertySheetExtension 类允许您操作显示在Qt Designer 的属性编辑器中的 widget 属性。更多

Header: #include <QDesignerPropertySheetExtension>
CMake: find_package(Qt6 REQUIRED COMPONENTS Designer)
target_link_libraries(mytarget PRIVATE Qt6::Designer)
qmake: QT += designer

公共函数

virtual ~QDesignerPropertySheetExtension()
virtual int count() const = 0
virtual bool hasReset(int index) const = 0
virtual int indexOf(const QString &name) const = 0
virtual bool isAttribute(int index) const = 0
virtual bool isChanged(int index) const = 0
virtual bool isEnabled(int index) const = 0
virtual bool isVisible(int index) const = 0
virtual QVariant property(int index) const = 0
virtual QString propertyGroup(int index) const = 0
virtual QString propertyName(int index) const = 0
virtual bool reset(int index) = 0
virtual void setAttribute(int index, bool attribute) = 0
virtual void setChanged(int index, bool changed) = 0
virtual void setProperty(int index, const QVariant &value) = 0
virtual void setPropertyGroup(int index, const QString &group) = 0
virtual void setVisible(int index, bool visible) = 0

详细说明

QDesignerPropertySheetExtension 提供了一系列函数,这些函数通常用于查询 widget 的属性,以及在属性编辑器中操作属性的外观。例如

QDesignerPropertySheetExtension *propertySheet = nullptr;
QExtensionManager manager = formEditor->extensionManager();

propertySheet = qt_extension<QDesignerPropertySheetExtension*>(manager, widget);
int index = propertySheet->indexOf(u"margin"_s);

propertySheet->setProperty(index, 10);
propertySheet->setChanged(index, true);

delete propertySheet;

请注意,如果使用QDesignerPropertySheetExtension::setProperty() 函数更改属性值,撤销堆栈不会更新。为确保可以使用撤销堆栈恢复属性值,必须使用QDesignerFormWindowCursorInterface::setProperty() 函数或其好友setWidgetProperty() 函数。

在实现自定义 widget 插件时,QDesignerCustomWidgetInterface::initialize() 函数的参数会提供一个指向Qt Widgets Designer 当前QDesignerFormEditorInterface 对象(上例中为formEditor )的指针。

通过使用qt_extension() 函数查询Qt Widgets Designer 的扩展管理器,可以获取属性表或任何其他扩展。要释放扩展时,只需删除指针即可。

所有窗口部件都有一个默认的属性表,它将窗口部件的属性(即使用Q_PROPERTY() 宏定义的属性)填充到Qt Widgets Designer 的属性编辑器中。不过,QDesignerPropertySheetExtension 也提供了创建自定义属性表扩展的接口。

请注意以下限制:

  • Qt Widgets Designer QDesignerPropertySheetExtension 使用 QDesignerPropertySheetExtension 为其属性编辑器提供数据。每当在其工作区中选中一个部件时, 就会查询该部件的属性表扩展。如果所选部件有已实现的属性表扩展,该扩展将覆盖默认属性表。Qt Widgets Designer
  • 属性表用于某些属性的数据类型是不透明的自定义QVariant 类型,其中包含附加信息,而不是普通的 Qt 数据类型。例如,枚举、标志、图标、像素图和字符串就是这种情况。
  • Qt Widgets Designer对于使用Q_DECLARE_METATYPE() 声明的自定义类型,"属性编辑器 "没有处理Q_PROPERTY 类型的实现。

要创建属性表扩展,扩展类必须同时继承自QObject 和 QDesignerPropertySheetExtension。然后,由于我们正在实现一个接口,因此必须确保使用Q_INTERFACES() 宏将其告知元对象系统:

class MyPropertySheetExtension : public QObject,
        public QDesignerPropertySheetExtension
{
    Q_OBJECT
    Q_INTERFACES(QDesignerPropertySheetExtension)

public:
    ...
}

这样,Qt Widgets Designer 就可以使用qobject_cast() 查询支持的接口,而只需使用QObject 指针。

Qt Widgets Designer 中,只有在需要时才会创建扩展。因此,在实现属性表扩展时,您还必须创建一个QExtensionFactory ,即一个能够为您的扩展创建实例的类,并使用Qt Widgets Designerextension manager 对其进行注册。

当需要属性表扩展时,Qt Widgets Designerextension manager 会遍历所有已注册的工厂,每个工厂都会调用QExtensionFactory::createExtension() ,直到找到第一个能为选定部件创建属性表扩展的工厂。然后,该工厂将创建一个扩展实例。如果找不到这样的工厂,Qt Widgets Designer 将使用默认的属性表。

Qt Widgets Designer 中有四种可用的扩展类型:QDesignerContainerExtensionQDesignerMemberSheetExtension 、QDesignerPropertySheetExtension 和QDesignerTaskMenuExtension 。无论请求的扩展是与多页面容器、成员表、属性表还是任务菜单相关联,Qt Designer 的行为都是一样的。

QExtensionFactory 类提供了一个标准扩展工厂,也可用作自定义扩展工厂的接口。您可以创建一个新的QExtensionFactory 并重新实现QExtensionFactory::createExtension() 函数。例如

QObject *ANewExtensionFactory::createExtension(QObject *object,
        const QString &iid, QObject *parent) const
{
    if (iid != Q_TYPEID(QDesignerPropertySheetExtension))
        return 0;

    if (MyCustomWidget *widget = qobject_cast<MyCustomWidget*>
           (object))
        return new MyPropertySheetExtension(widget, parent);

    return 0;
}

或者使用现有的工厂,扩展QExtensionFactory::createExtension() 函数,使工厂也能创建属性表扩展。例如

QObject *AGeneralExtensionFactory::createExtension(QObject *object,
        const QString &iid, QObject *parent) const
{
    MyCustomWidget *widget = qobject_cast<MyCustomWidget*>(object);

    if (widget && (iid == Q_TYPEID(QDesignerTaskMenuExtension))) {
        return new MyTaskMenuExtension(widget, parent);

    } else if (widget && (iid == Q_TYPEID(QDesignerPropertySheetExtension))) {
        return new MyPropertySheetExtension(widget, parent);

    } else {
        return 0;
    }
}

有关使用扩展类的完整示例,请参阅任务菜单扩展示例。该示例展示了如何为Qt Designer 创建自定义 widget 插件,以及如何使用QDesignerTaskMenuExtension 类向Qt Widgets Designer 的任务菜单添加自定义项目。

另请参阅 QDesignerDynamicPropertySheetExtension,QExtensionFactory,QExtensionManager, 以及创建自定义部件扩展

成员函数文档

[virtual constexpr noexcept] QDesignerPropertySheetExtension::~QDesignerPropertySheetExtension()

销毁属性表扩展名。

[pure virtual] int QDesignerPropertySheetExtension::count() const

返回所选部件的属性数。

[pure virtual] bool QDesignerPropertySheetExtension::hasReset(int index) const

如果给定index 的属性在Qt Widgets Designer 的属性编辑器中有重置按钮,则返回 true,否则返回 false。

另请参阅 indexOf() 和reset()。

[pure virtual] int QDesignerPropertySheetExtension::indexOf(const QString &name) const

返回给定属性的索引name

另请参阅 propertyName() 。

[pure virtual] bool QDesignerPropertySheetExtension::isAttribute(int index) const

如果index 处的属性是属性,则返回 true,否则返回 false。

另请参阅 indexOf() 和setAttribute()。

[pure virtual] bool QDesignerPropertySheetExtension::isChanged(int index) const

如果给定index 处的属性值不同于属性的默认值,则返回 true,否则返回 false。

另请参阅 indexOf()、setChanged() 和reset()。

[pure virtual] bool QDesignerPropertySheetExtension::isEnabled(int index) const

如果给定index 的属性在Qt Widgets Designer 的属性编辑器中启用,则返回 true,否则返回 false。

另请参阅 indexOf().

[pure virtual] bool QDesignerPropertySheetExtension::isVisible(int index) const

如果index 上的属性在Qt Widgets Designer 的属性编辑器中可见,则返回 true,否则返回 false。

另请参阅 indexOf() 和setVisible() 。

[pure virtual] QVariant QDesignerPropertySheetExtension::property(int index) const

返回给定index 处的属性值。

另请参阅 indexOf()、setProperty() 和propertyGroup()。

[pure virtual] QString QDesignerPropertySheetExtension::propertyGroup(int index) const

返回位于index 的属性的属性组。

Qt Widgets Designer属性编辑器支持属性组,即相关属性的部分。可以使用setPropertyGroup() 函数将一个属性与一个组相关联。任何属性的默认组都是定义该属性的类的名称。例如,QObject::objectName 属性出现在QObject 属性组中。

另请参阅 indexOf() 和setPropertyGroup()。

[pure virtual] QString QDesignerPropertySheetExtension::propertyName(int index) const

返回给定index 的属性名称。

另请参见 indexOf()。

[pure virtual] bool QDesignerPropertySheetExtension::reset(int index)

将给定index 处的属性值重置为默认值。如果能找到默认值,则返回 true,否则返回 false。

另请参阅 indexOf()、hasReset() 和isChanged()。

[pure virtual] void QDesignerPropertySheetExtension::setAttribute(int index, bool attribute)

如果attribute 为 true,则index 处的属性将成为属性,并从 UI 文件中排除;否则将包括在内。

另请参阅 indexOf() 和isAttribute()。

[pure virtual] void QDesignerPropertySheetExtension::setChanged(int index, bool changed)

根据changed 参数,设置给定index 的属性是否与默认值不同。

另请参阅 indexOf() 和isChanged()。

[pure virtual] void QDesignerPropertySheetExtension::setProperty(int index, const QVariant &value)

在给定的index 上设置属性的value

警告: 如果使用此函数更改了属性值,撤销堆栈将不会更新。为确保可以使用撤销堆栈恢复属性值,必须使用QDesignerFormWindowCursorInterface::setProperty() 函数或其好友setWidgetProperty() 函数。

另请参阅 indexOf()、property() 和propertyGroup()。

[pure virtual] void QDesignerPropertySheetExtension::setPropertyGroup(int index, const QString &group)

将给定index 的属性的属性组设置为group

将属性与组关联后,该属性就会出现在属性编辑器中的该组区域内。任何属性的默认属性组都是定义该属性的类的名称。例如,QObject::objectName 属性显示在QObject 属性组中。

另请参阅 indexOf()、property() 和propertyGroup()。

[pure virtual] void QDesignerPropertySheetExtension::setVisible(int index, bool visible)

如果visible 为 true,给定index 的属性在Qt Widgets Designer 的属性编辑器中是可见的;否则,该属性是隐藏的。

另请参阅 indexOf() 和isVisible() 。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.