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

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

準備

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

プロジェクト・ファイル

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 または同等のインストール手順を使用）。

プラグインの詳細については、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アイコンを返します。

ツール・チップと "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