カスタムウィジェットプラグイン

この例では、使用するカスタムウィジェットは「Analog Clock」の例を基にしており、カスタムシグナルやスロットは一切提供していません。

準備

Qt Widgets Designer で使用できるカスタムウィジェットを提供するには、自己完結型の実装を用意し、プラグインインターフェースを定義する必要があります。この例では、便宜上、Analog Clock の例を再利用します。

プロジェクトファイル

CMake

プロジェクトファイルでは、Qt Widgets Designer ライブラリにリンクするプラグインをビルドすることを明記する必要があります。

find_package(Qt6 REQUIRED COMPONENTS Core Gui UiPlugin Widgets)

qt_add_plugin(customwidgetplugin)

target_link_libraries(customwidgetplugin PUBLIC
    Qt::Core
    Qt::Gui
    Qt::UiPlugin
    Qt::Widgets
)

リンクライブラリのリストには `Qt::UiPlugin` を指定します。これは、プラグインが抽象インターフェース `QDesignerCustomWidgetInterface ` および `QDesignerCustomWidgetCollectionInterface ` のみを使用し、`Qt Widgets Designer ` ライブラリへのリンクを持たないことを示しています。リンク関係のある `Qt Widgets Designer ` の他のインターフェースにアクセスする場合は、代わりに `Designer ` を使用する必要があります。これにより、プラグインが `Qt Widgets Designer ` ライブラリに動的にリンクされ、実行時にそれらに依存することが保証されます。

以下の例は、ウィジェットのヘッダーファイルとソースファイルを追加する方法を示しています：

target_sources(customwidgetplugin PRIVATE
    analogclock.cpp analogclock.h
    customwidgetplugin.cpp customwidgetplugin.h
)

Qt Widgets Designer がカスタムウィジェットを使用できるように、プラグインインターフェースの実装を提供しています。

また、プラグインがQt Widgets Designer によって検索される場所にインストールされるようにすることも重要です。これを行うには、プロジェクトのターゲットパスを指定し、インストール対象の項目リストに追加します：

   set(INSTALL_EXAMPLEDIR "${QT6_INSTALL_PREFIX}/${QT6_INSTALL_PLUGINS}/designer")
install(TARGETS customwidgetplugin
    RUNTIME DESTINATION "${INSTALL_EXAMPLEDIR}"
    BUNDLE DESTINATION "${INSTALL_EXAMPLEDIR}"
    LIBRARY DESTINATION "${INSTALL_EXAMPLEDIR}"
)

カスタムウィジェットはライブラリとして作成されます。プロジェクトのインストール時（ninja install または同等のインストール手順を使用）、このウィジェットは他のQt Widgets Designer プラグインとともにインストールされます。

プラグインの詳細については、『Qt プラグインの作成方法』のドキュメントを参照してください。

qmake

以下の例は、プラグインをQt Widgets Designer ライブラリにリンクする方法を示しています：

CONFIG      += plugin
TEMPLATE    = lib

QT          += widgets uiplugin

QT 変数には、キーワードuiplugin が含まれています。これは、Qt::UiPlugin ライブラリに相当します。

以下の例は、ウィジェットのヘッダーファイルとソースファイルを追加する方法を示しています:

HEADERS     = analogclock.h \
              customwidgetplugin.h
SOURCES     = analogclock.cpp \
              customwidgetplugin.cpp
OTHER_FILES += analogclock.json

次の例は、Qt Widgets Designer のプラグインパスにプラグインをインストールする方法を示しています：

TARGET = $$qtLibraryTarget($$TARGET)

target.path = $$[QT_INSTALL_PLUGINS]/designer
INSTALLS += target

AnalogClock クラスの定義と実装

AnalogClock クラスは、「アナログ時計」の例で説明された方法とまったく同じように定義および実装されています。このクラスは自己完結型であり、外部からの設定を一切必要としないため、Qt Widgets Designer 内でカスタムウィジェットとしてそのまま使用できます。

AnalogClockPlugin クラスの定義

AnalogClock クラスは、AnalogClockPlugin クラスを通じてQt Widgets Designer に公開されます。このクラスは、QObject クラスとQDesignerCustomWidgetInterface クラスの両方を継承し、QDesignerCustomWidgetInterface で定義されたインターフェースを実装しています。

Qtがこのウィジェットをプラグインとして認識できるようにするには、Q_PLUGIN_METADATA() マクロを追加して、ウィジェットに関する関連情報をエクスポートします。

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;
};

これらの関数は、Qt Widgets Designer がウィジェットボックス内で使用できるウィジェットに関する情報を提供します。プライベートメンバー変数initialized は、プラグインがQt Widgets Designer によって初期化されたかどうかを記録するために使用されます。

なお、この特定のカスタムウィジェットに固有なクラス定義の部分は、クラス名のみであることに注意してください。

AnalogClockPlugin の実装

このクラスのコンストラクタは、単に基底クラスであるQObject のコンストラクタを呼び出し、initialized 変数をfalse に設定するだけです。

AnalogClockPlugin::AnalogClockPlugin(QObject *parent)
    : QObject(parent)
{
}

Qt Widgets Designer は、initialize() 関数を呼び出すことで、プラグインが要求された際に初期化を行います：

void AnalogClockPlugin::initialize(QDesignerFormEditorInterface * /* core */)
{
    if (initialized)
        return;

    initialized = true;
}

この例では、initialized というプライベート変数がチェックされ、プラグインがまだ初期化されていない場合にのみtrue に設定されます。このプラグインは初期化時に特別なコードを実行する必要はありませんが、初期化チェックの後にそのようなコードを含めることも可能です。

isInitialized() 関数は、Qt Widgets Designer に対して、プラグインが使用可能な状態にあるかどうかを通知します：

bool AnalogClockPlugin::isInitialized() const
{
    return initialized;
}

カスタムウィジェットのインスタンスは、createWidget() 関数によって提供されます。アナログ時計の実装は単純明快です：

QWidget *AnalogClockPlugin::createWidget(QWidget *parent)
{
    return new AnalogClock(parent);
}

この場合、カスタムウィジェットに必要なのはparent の指定のみです。ウィジェットに他の引数を渡す必要がある場合は、ここで定義することができます。

以下の関数は、Qt Widgets Designer がウィジェットボックス内でウィジェットを表現するために使用する情報を提供します。name() 関数は、カスタムウィジェットを提供するクラスの名前を返します：

QString AnalogClockPlugin::name() const
{
    return u"AnalogClock"_s;
}

group() 関数は、カスタムウィジェットが属するウィジェットのタイプを記述するために使用されます：

QString AnalogClockPlugin::group() const
{
    return u"Display Widgets [Examples]"_s;
}

ウィジェットプラグインは、Qt Widgets Designer のウィジェットボックス内で、そのグループ名によって識別されるセクションに配置されます。ウィジェットボックス内でウィジェットを表すために使用されるアイコンは、icon() 関数によって返されます:

QIcon AnalogClockPlugin::icon() const
{
    return {};
}

この場合、ウィジェットを表すのに使用できるアイコンがないことを示すために、null アイコンを返します。

ウィジェットボックス内のカスタムウィジェットの項目には、ツールチップや「これは何？」ヘルプを設定できます。toolTip() 関数は、ウィジェットを説明する短いメッセージを返す必要があります：

QString AnalogClockPlugin::toolTip() const
{
    return {};
}

whatsThis() 関数では、より詳細な説明を返すこともできます：

QString AnalogClockPlugin::whatsThis() const
{
    return {};
}

isContainer() 関数は、そのウィジェットが他のウィジェットのコンテナとして使用されるべきかどうかをQt Widgets Designer に伝えます。そうでない場合、Qt Widgets Designer はユーザーがその中にウィジェットを配置することを許可しません。

bool AnalogClockPlugin::isContainer() const
{
    return false;
}

Qt Widgetsのほとんどのウィジェットは子ウィジェットを格納できますが、Qt Widgets Designer では、この目的のために専用のコンテナウィジェットを使用するのが理にかなっています。false を返すことで、カスタムウィジェットが他のウィジェットを格納できないことを示します。もしtrueを返した場合、Qt Widgets Designer はアナログ時計の中に他のウィジェットを配置し、レイアウトを定義することを許可します。

domXml() 関数は、Qt Widgets Designer で使用される標準的なXML形式で、ウィジェットのデフォルト設定を含める方法を提供します。この場合、ウィジェットのジオメトリのみを指定します：

QString AnalogClockPlugin::domXml() const
{
    return uR"(
<ui language="c++">
  <widget class="AnalogClock" name="analogClock">
)"
R"(
    <property name="geometry">
      <rect>
        <x>0</x>
        <y>0</y>
        <width>100</width>
        <height>100</height>
      </rect>
    </property>
")
R"(
    <property name="toolTip">
      <string>The current time</string>
    </property>
    <property name="whatsThis">
      <string>The analog clock widget displays the current time.</string>
    </property>
  </widget>
</ui>
)"_s;
}

ウィジェットが妥当なサイズヒントを提供している場合、ここでそれを定義する必要はありません。さらに、<widget> 要素の代わりに空の文字列を返すと、Qt Widgets Designer に対して、そのウィジェットをウィジェットボックスに配置しないよう指示することになります。

アナログ時計ウィジェットをアプリケーションで使用可能にするために、includeFile() 関数を実装し、カスタムウィジェットクラスの定義を含むヘッダーファイル名を返すようにします：

QString AnalogClockPlugin::includeFile() const
{
    return u"analogclock.h"_s;
}

サンプルプロジェクト @ code.qt.io