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

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

準備

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 変数には、Qt::UiPlugin ライブラリに相当するキーワード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