Back to Qt.io
Contact Us Blog Download Qt
このページでは

QDesignerCustomWidgetInterface Class

QDesignerCustomWidgetInterface クラスにより、Qt Widgets Designer はカスタムウィジェットへのアクセスや生成が可能になります。詳細...

ヘッダー: #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 は、カスタムウィジェットにインターフェースを提供します。このクラスには、ウィジェットのクラス名やヘッダーファイル名といった基本情報を返すために、サブクラスで実装しなければならない一連の関数が含まれています。 また、プラグインの読み込み時に初期化を行うため、およびQt Widgets Designer が使用するカスタムウィジェットのインスタンスを生成するために、その他の関数を実装する必要があります。

カスタムウィジェットを実装する際は、Qt Widgets Designer でそのウィジェットを利用できるようにするために、QDesignerCustomWidgetInterface をサブクラス化する必要があります。例えば、以下は「カスタムウィジェットプラグイン」の例で使用されているプラグインの宣言であり、これにより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 ポインタのみを使用して、qobject_cast() 関数を通じてサポートされているインターフェースを照会できるようになります。

Qt Widgets Designer がカスタムウィジェットプラグインを読み込んだ後、そのインターフェースのinitialize()関数を呼び出し、プラグインが必要とするリソースの設定を可能にします。この関数は、QDesignerFormEditorInterface パラメータを引数として呼び出され、これによりプラグインはQt Widgets Designer のすべてのAPIへのゲートウェイを利用できるようになります。

Qt Widgets Designer 適切な親ウィジェットを引数としてプラグインのcreateWidget()関数を呼び出すことで、カスタムウィジェットのインスタンスを生成します。プラグインは、指定された親ウィジェットを持つカスタムウィジェットのインスタンスを生成し、それを返さなければなりません。

Q_PLUGIN_METADATA() マクロを使用して、カスタムウィジェットプラグインをQt Widgets Designer にエクスポートします。たとえば、libcustomwidgetplugin.so （Unix）またはlibcustomwidget.dll （Windows）というライブラリにMyCustomWidget というウィジェットクラスが含まれている場合、プラグインヘッダーを含むファイルに次の行を追加することで、それをエクスポートできます。

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

このマクロにより、Qt Widgets Designer がカスタムウィジェットにアクセスし、それを生成できるようになります。このマクロがない場合、Qt Widgets Designer がそれを使用する方法はありません。

カスタムウィジェットプラグインを実装する際は、それを独立したライブラリとしてビルドします。複数のカスタムウィジェットプラグインを同じライブラリに含めたい場合は、さらに `QDesignerCustomWidgetCollectionInterface` をサブクラス化する必要があります。

警告: カスタムウィジェットプラグインに `QVariant ` のプロパティが含まれている場合 、サポートされている `types ` は以下のもののみであることに注意してください:

  • QVariant::ByteArray
  • QVariant::Bool
  • QVariant::Color
  • QVariant::Cursor
  • QVariant::Date
  • QVariant::DateTime
  • QVariant::Double
  • QVariant::Int
  • QVariant::Point
  • QVariant::Rect
  • QVariant::Size
  • QVariant::SizePolicy
  • QVariant::String
  • QVariant::Time
  • QVariant::UInt

QDesignerCustomWidgetInterface クラスを使用した完全な例については、「カスタムウィジェットの例」を参照してください。この例では、Qt Widgets Designer 用のカスタムウィジェットプラグインの作成方法を示しています。

「 QDesignerCustomWidgetCollectionInterface 」および「Qt Widgets Designer 用のカスタムウィジェットの作成」も参照してください 。

メンバ関数のドキュメント

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

カスタムウィジェットのインターフェースを破棄します。

[virtual] QString QDesignerCustomWidgetInterface::codeTemplate() const

この関数は、Qt Widgets Designer による将来の使用のために予約されています。

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

指定されたparent を持つ、カスタムウィジェットの新しいインスタンスを返します。

[virtual] QString QDesignerCustomWidgetInterface::domXml() const

Qt Widgets Designer に対して、カスタムウィジェットのプロパティを記述するために使用される XML を返します。

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

カスタムウィジェットが属するグループの名前を返します。

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

Qt Widgets Designer のウィジェットボックスで、カスタムウィジェットを表すために使用されるアイコンを返します。

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

uicがカスタムウィジェットのコードを生成する際に使用するインクルードファイルへのパスを返します。

C++で使用されるカスタムウィジェットや Qt for Pythonでは、以下に示すように、プレフィックスを使用して、返される文字列内に言語固有の情報を指定してください：

"C++:myheader.h,Python:MyModule"

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

指定されたformEditor インターフェースで使用するためのウィジェットを初期化します。

isInitialized()も参照してください 。

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

カスタムウィジェットがコンテナとして使用されることを意図している場合は true を返し、そうでない場合は false を返します。

ほとんどのカスタムウィジェットは他のウィジェットを格納するために使用されないため、この関数の実装では false を返しますが、カスタムコンテナは、Qt Widgets Designer 内で正しく動作するように、true を返します。

[virtual] bool QDesignerCustomWidgetInterface::isInitialized() const

ウィジェットが初期化されている場合は true を返し、そうでない場合は false を返します。

initialize()も参照してください 。

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

インターフェースによって提供されたカスタムウィジェットのクラス名を返します。

返される名前は、そのカスタムウィジェットに使用されているクラス名と完全に一致している必要があります。

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

Qt Widgets Designer がツールチップで表示できる、ウィジェットの簡単な説明を返します。

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

Qt Widgets Designer の「これは何？」ヘルプで、そのウィジェットの説明として使用できるウィジェットの説明を返します。

マクロのドキュメント

QDESIGNER_WIDGET_EXPORT

このマクロは、カスタムウィジェットを定義する際に、Qt Widgets Designer で使用できるよう、プラグインから正しくエクスポートされるようにするために使用されます。

一部のプラットフォームでは、Qt Widgets Designer が新しいウィジェットを作成するために必要とするシンボルが、ビルドシステムによってプラグインから削除され、使用できなくなってしまうことがあります。このマクロを使用することで、それらのプラットフォームでもシンボルが確実に保持され、他のプラットフォームには何の影響も与えません。

たとえば、「Custom Widget Plugin」のサンプルでは、以下の宣言を用いてカスタムウィジェットクラスをエクスポートしています。

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

「Qt Widgets Designer 用のカスタムウィジェットの作成」も参照してください 。

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