Back to Qt.io
Contact Us Blog Download Qt
本页内容

QDesignerContainerExtension Class

QDesignerContainerExtension 类允许您在Qt Widgets Designer 的工作区中向自定义的多页容器添加页面。更多内容...

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

公共函数

QDesignerContainerExtension()
QDesignerContainerExtension(const QDesignerContainerExtension &)
QDesignerContainerExtension(QDesignerContainerExtension &&)
virtual ~QDesignerContainerExtension()
virtual void addWidget(QWidget *page) = 0
virtual bool canAddWidget() const = 0
virtual bool canRemove(int index) const = 0
virtual int count() const = 0
virtual int currentIndex() const = 0
virtual void insertWidget(int index, QWidget *page) = 0
virtual void remove(int index) = 0
virtual void setCurrentIndex(int index) = 0
virtual QWidget *widget(int index) const = 0
QDesignerContainerExtension &operator=(QDesignerContainerExtension &&)
QDesignerContainerExtension &operator=(const QDesignerContainerExtension &)

详细说明

<span translate=Qt Widgets Designer UI 编辑器的截图，显示了在对象中“当前页面之前插入页面”的选项" src="images/containerextension-example.webp" title="Qt Widgets Designer UI 编辑器的截图，显示了在对象中“当前页面之前插入页面”的选项"/>

QDesignerContainerExtension 提供了一个用于创建自定义容器扩展的接口。一个容器扩展由一组函数组成，Qt Widgets Designer 需要这些函数来管理多页容器插件，以及该容器的页面列表。

警告：这 并非针对一般容器插件的扩展，仅适用于自定义的多页容器。

要创建容器扩展，您的扩展类必须同时继承自QObject 和 QDesignerContainerExtension。例如：

class MyContainerExtension : public QObject,
       public QDesignerContainerExtension
{
    Q_OBJECT
    Q_INTERFACES(QDesignerContainerExtension)

public:
    MyContainerExtension(MyCustomWidget *widget,
                         QObject *parent = 0);
    int count() const;
    QWidget *widget(int index) const;
    int currentIndex() const;
    void setCurrentIndex(int index);
    void addWidget(QWidget *widget);
    void insertWidget(int index, QWidget *widget);
    void remove(int index);

private:
    MyCustomWidget *myWidget;
};

由于我们正在实现一个接口，因此必须通过Q_INTERFACES()宏确保该接口被元对象系统所识别。这使得Qt Widgets Designer 能够仅通过一个QObject 指针，使用qobject_cast()函数查询所支持的接口。

您必须重写若干函数，以便Qt Widgets Designer 能够管理自定义的多页容器控件：Qt Widgets Designer 使用count() 来跟踪容器中的页面数量，使用widget() 返回容器页面列表中指定索引处的页面，并使用currentIndex() 返回所选页面的列表索引。Qt Widgets Designer 使用addWidget() 函数将给定页面添加到容器中，该函数会将页面追加到页面列表的末尾；而insertWidget() 函数则会将给定页面插入到容器中，并将其插入到指定索引位置。

在Qt Widgets Designer 中，扩展仅在被调用时才会被创建。因此，你还必须创建一个QExtensionFactory （即能够生成你的扩展实例的类），并使用Qt Widgets Designer 中的extension manager 进行注册。

当需要一个容器扩展时，Qt Widgets Designer 的extension manager 会遍历所有已注册的工厂，对每个工厂调用QExtensionFactory::createExtension()，直到找到第一个能够创建容器扩展的工厂。该工厂随后将为插件创建扩展。

Qt Widgets Designer 中提供了四种扩展类型：QDesignerContainerExtension、QDesignerMemberSheetExtension 、QDesignerPropertySheetExtension 和QDesignerTaskMenuExtension 。无论请求的扩展是与多页容器、成员表、属性表还是任务菜单相关联，Qt Widgets Designer 的行为都是一致的。

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

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

    if (MyCustomWidget *widget = qobject_cast<MyCustomWidget*>
           (object))
        return new MyContainerExtension(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(QDesignerContainerExtension))) {
        return new MyContainerExtension(widget, parent);

    } else {
        return 0;
    }
}

有关使用 QDesignerContainerExtension 类的完整示例，请参阅“容器扩展”示例。该示例演示了如何为Qt Widgets Designer 创建自定义的多页插件。

另请参阅 QExtensionFactory 、QExtensionManager 以及《创建自定义小部件扩展》。

成员函数文档

[constexpr noexcept default] QDesignerContainerExtension::QDesignerContainerExtension()

默认——构造一个QDesignerContainerExtension 实例。

[delete] QDesignerContainerExtension::QDesignerContainerExtension(const QDesignerContainerExtension &)

复制并构造一个QDesignerContainerExtension 实例。该函数已被删除。

[delete] QDesignerContainerExtension::QDesignerContainerExtension(QDesignerContainerExtension &&)

通过移动构造创建一个QDesignerContainerExtension 的实例。该函数已被删除。

[virtual constexpr noexcept default] QDesignerContainerExtension::~QDesignerContainerExtension()

删除该扩展程序。

[pure virtual] void QDesignerContainerExtension::addWidget(QWidget *page)

将给定的page 添加到容器中，方法是将其追加到扩展的页面列表中。

另请参阅 insertWidget()、remove() 和widget()。

[pure virtual] bool QDesignerContainerExtension::canAddWidget() const

返回该控件是否可被添加。这决定了上下文菜单中“添加”或“插入”页面的选项是否启用。

对于仅包含单个固定页面的容器，此函数应返回 false，例如QScrollArea 或QDockWidget 。

另请参阅 addWidget() 和canRemove()。

[pure virtual] bool QDesignerContainerExtension::canRemove(int index) const

返回位于指定index 的小部件是否可以被移除。这决定了“移除当前页面”的右键菜单选项是否启用。

对于仅包含单个固定页面的容器（例如QScrollArea 或QDockWidget ），此方法应返回 false。

另请参阅 remove() 和canAddWidget()。

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

返回容器中的页数。

[pure virtual] int QDesignerContainerExtension::currentIndex() const

返回容器中当前选定页面的索引。

另请参阅 setCurrentIndex()。

[pure virtual] void QDesignerContainerExtension::insertWidget(int index, QWidget *page)

将指定的page 添加到容器中，将其插入扩展程序页面列表中指定的index 位置。

另请参阅 addWidget()、remove() 和widget()。

[pure virtual] void QDesignerContainerExtension::remove(int index)

将位于指定index 的页面从该扩展程序的页面列表中移除。

另请参阅 addWidget() 和insertWidget()。

[pure virtual] void QDesignerContainerExtension::setCurrentIndex(int index)

将容器中当前选中的页面设置为扩展程序页面列表中位于指定index 的页面。

另请参阅 currentIndex()。

[pure virtual] QWidget *QDesignerContainerExtension::widget(int index) const

返回扩展程序页面列表中位于指定index 的页面。

另请参阅 addWidget() 和insertWidget()。

[delete] QDesignerContainerExtension &QDesignerContainerExtension::operator=(QDesignerContainerExtension &&)

将other 按移动赋值方式赋值给此QDesignerContainerExtension 实例。该函数已被删除。

[delete] QDesignerContainerExtension &QDesignerContainerExtension::operator=(const QDesignerContainerExtension &)

将other 复制并赋值给此QDesignerContainerExtension 实例。该函数已被删除。

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