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

この例では、使用するカスタムウィジェットはアナログ時計の例に基づいており、カスタムシグナルやスロットは提供しません。

準備

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}"
)

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

プラグインの詳細については、How to Create Qt Pluginsドキュメントを参照してください。

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 クラスの定義と実装は、Analog Clock の例で説明した方法とまったく同じです。このクラスは自己完結しており、外部設定を必要としないため、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アイコンを返します。

ツール・チップと "What's This? "ヘルプは、ウィジェット・ボックス内のカスタム・ウィジェットのエントリに提供できます。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 のほとんどのウィジェットは、子ウィジェットを含めることができますが、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