Back to Qt.io
Contact Us Blog Download Qt

QDesignerCustomWidgetInterface Class

QDesignerCustomWidgetInterface 类使Qt Widgets Designer 能够访问和构造自定义部件。更多

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

公共函数

virtual ~QDesignerCustomWidgetInterface()
virtual QString codeTemplate() const
virtual QWidget *createWidget(QWidget *parent) = 0
virtual QString domXml() const
virtual QString group() const = 0
virtual QIcon icon() const = 0
virtual QString includeFile() const = 0
virtual void initialize(QDesignerFormEditorInterface *formEditor)
virtual bool isContainer() const = 0
virtual bool isInitialized() const
virtual QString name() const = 0
virtual QString toolTip() const = 0
virtual QString whatsThis() const = 0

宏

QDESIGNER_WIDGET_EXPORT

详细说明

QDesignerCustomWidgetInterface 为自定义 widget 提供了一个接口。该类包含一组必须子类化的函数，用于返回 widget 的基本信息，如类名和头文件名。还必须实现其他函数，以便在加载插件时对其进行初始化，并构建自定义 widget 的实例供Qt Widgets Designer 使用。

在实现自定义 widget 时，您必须子类化 QDesignerCustomWidgetInterface，以便向Qt Widgets Designer 公开您的 widget。例如，这是 "自定义部件插件 "示例中使用的插件声明，该插件可让Qt Widgets Designer 使用模拟时钟自定义部件：

class AnalogClockPlugin : public QObject, public QDesignerCustomWidgetInterface
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QDesignerCustomWidgetInterface")
    Q_INTERFACES(QDesignerCustomWidgetInterface)
public:
    explicit AnalogClockPlugin(QObject *parent = nullptr);

    bool isContainer() const override;
    bool isInitialized() const override;
    QIcon icon() const override;
    QString domXml() const override;
    QString group() const override;
    QString includeFile() const override;
    QString name() const override;
    QString toolTip() const override;
    QString whatsThis() const override;
    QWidget *createWidget(QWidget *parent) override;
    void initialize(QDesignerFormEditorInterface *core) override;

private:
    bool initialized = false;
};

请注意，类定义中唯一与该自定义部件相关的部分是类名。此外，由于我们实现的是一个接口，因此必须使用Q_INTERFACES() 宏确保元对象系统知道该接口。这样，Qt Widgets Designer 就可以使用qobject_cast() 函数查询支持的接口，而只需使用QObject 指针。

Qt Widgets Designer 加载自定义 widget 插件后，会调用接口的initialize() 函数，以便设置可能需要的任何资源。调用该函数时会带一个QDesignerFormEditorInterface 参数，该参数为插件提供了一个通向Qt Widgets Designer 所有 API 的网关。

Qt Widgets Designer 通过调用插件的 () 函数和一个合适的父窗口小部件来构建自定义窗口小部件的实例。插件必须使用指定的父 widget 构建并返回自定义 widget 实例。createWidget

使用Q_PLUGIN_METADATA() 宏将自定义 widget 插件导出到Qt Widgets Designer 。例如，如果一个名为libcustomwidgetplugin.so （Unix 上）或libcustomwidget.dll （Windows 上）的库包含一个名为MyCustomWidget 的 widget 类，我们可以在包含插件头的文件中添加以下一行来导出它：

Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QDesignerCustomWidgetInterface")

该宏确保Qt Widgets Designer 可以访问和构建自定义 widget。没有这个宏，Qt Widgets Designer 就无法使用它。

实施自定义 widget 插件时，应将其构建为一个单独的库。如果想在同一个库中包含多个自定义 widget 插件，则必须另外子类化QDesignerCustomWidgetCollectionInterface 。

警告： 如果您的自定义 widget 插件包含QVariant 属性，请注意只有以下types 受支持：

  • QVariant::ByteArray
  • QVariant::Bool
  • QVariant::颜色
  • QVariant::光标
  • QVariant::Date
  • QVariant::DateTime
  • QVariant::Double
  • QVariant::Int
  • QVariant::点
  • QVariant::Rect
  • QVariant::Size
  • QVariant::SizePolicy
  • QVariant::字符串
  • QVariant::时间
  • 变量::UInt

有关使用 QDesignerCustomWidgetInterface 类的完整示例，请参阅自定义窗口小部件示例。该示例展示了如何为Qt Widgets Designer 创建自定义 widget 插件。

另请参阅 QDesignerCustomWidgetCollectionInterface 和为Qt Widgets Designer 创建自定义部件。

成员函数文档

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

销毁自定义 widget 界面。

[virtual] QString QDesignerCustomWidgetInterface::codeTemplate() const

该功能由Qt Widgets Designer 保留，供今后使用。

[pure virtual] QWidget *QDesignerCustomWidgetInterface::createWidget(QWidget *parent)

返回自定义 widget 的新实例，其中包含给定的parent 。

[virtual] QString QDesignerCustomWidgetInterface::domXml() const

向Qt Widgets Designer 返回用于描述自定义 widget 属性的 XML。

[pure virtual] QString QDesignerCustomWidgetInterface::group() const

返回自定义 widget 所属组的名称。

[pure virtual] QIcon QDesignerCustomWidgetInterface::icon() const

返回用于在Qt Widgets Designer 的 widget 框中表示自定义 widget 的图标。

[pure virtual] QString QDesignerCustomWidgetInterface::includeFile() const

返回uic为自定义 widget 创建代码时使用的 include 文件的路径。

[virtual] void QDesignerCustomWidgetInterface::initialize(QDesignerFormEditorInterface *formEditor)

初始化 widget，以便与指定的formEditor 接口一起使用。

另请参阅 isInitialized().

[pure virtual] bool QDesignerCustomWidgetInterface::isContainer() const

如果自定义部件打算用作容器，则返回 true；否则返回 false。

大多数自定义 widget 并不用于容纳其他 widget，因此它们对该函数的实现将返回 false，但自定义容器将返回 true，以确保它们在Qt Widgets Designer 中行为正确。

[virtual] bool QDesignerCustomWidgetInterface::isInitialized() const

如果 widget 已初始化，则返回 true；否则返回 false。

另请参阅 initialize()。

[pure virtual] QString QDesignerCustomWidgetInterface::name() const

返回接口提供的自定义 widget 的类名。

返回的名称必须与自定义 widget 使用的类名相同。

[pure virtual] QString QDesignerCustomWidgetInterface::toolTip() const

返回 widget 的简短描述，Qt Widgets Designer ，可在工具提示中使用。

[pure virtual] QString QDesignerCustomWidgetInterface::whatsThis() const

返回 widget 的描述，该描述可用于Qt Widgets Designer 的 "这是什么？"帮助。

宏文档

QDESIGNER_WIDGET_EXPORT

该宏用于定义自定义 widget，以确保它们能从插件中正确导出，供Qt Widgets Designer 使用。

在某些平台上，Qt Widgets Designer 创建新部件所需的符号会被构建系统从插件中移除，导致无法使用。使用该宏可以确保在这些平台上保留这些符号，并且对其他平台没有副作用。

例如，自定义 widget 插件示例导出了一个自定义 widget 类，其声明如下：

class QDESIGNER_WIDGET_EXPORT AnalogClock : public QWidget
{
    Q_OBJECT
    ...
};

另请参阅 为Qt Widgets Designer 创建自定义部件。

© 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.