カスタムウィジェットの作成Qt Widgets Designer

Qt Widgets Designerのプラグイン・ベース・アーキテクチャでは、ユーザ定義ウィジェットやサードパーティ製カスタムウィジェットを、標準 Qt ウィジェットと同じように編集することができます。カスタムウィジェットの機能は、ウィジェットのプロパティ、シグナル、スロットを含め、すべてQt Widgets Designer で利用できます。Qt Widgets Designer は、フォーム設計プロセスで実際のウィジェットを使用するため、カスタムウィジェットはプレビュー時と同じように表示されます。

QtDesigner モジュールは、Qt Widgets Designer でカスタムウィジェットを作成する機能を提供します。

はじめに

カスタムウィジェットをQt Widgets Designer に統合するには、ウィジェットの適切な説明と適切なプロジェクトファイルが必要です。

インターフェース説明の提供

提供したいウィジェットのタイプをQt Widgets Designer に知らせるには、QDesignerCustomWidgetInterface のサブクラスを作成して、ウィジェットが公開するさまざまなプロパティを記述します。プラグインの作者だけがこの情報を提供できるので、これらのほとんどは、基底クラスの純粋な仮想関数によって提供されます。

他の2つの仮想関数も再実装できる：

domXml() 関数に関する注意事項

domXml() 関数は、Qt Widgets Designer のウィジェットファクトリーがカスタムウィジェットとその適用プロパティを作成するために使用する UI ファイルスニペットを返します。

Qt 4.4 以降、Qt Widgets Designer のウィジェットボックスでは、1つのカスタムウィジェットを完全な UI ファイルで記述することができます。UI ファイルは、<ui> タグを使用して読み込むことができます。<ui>タグを指定すると、カスタムウィジェットの追加情報を含む<customwidget>要素を追加できます。追加情報が必要ない場合は、<widget> タグで十分です。

カスタムウィジェットが適切なサイズのヒントを提供しない場合、サブクラスのdomXml() 関数が返す文字列でデフォルトのジオメトリを指定する必要があります。例えば、Custom Widget Plugin の例で提供されているAnalogClockPlugin では、以下のようにデフォルトの widgetgeometry を定義しています：

    ...
R"(
    <property name="geometry">
      <rect>
        <x>0</x>
        <y>0</y>
        <width>100</width>
        <height>100</height>
      </rect>
    </property>
")
    ...

domXml() 関数の追加機能として、空の文字列を返した場合、そのウィジェットはQt Widgets Designer のウィジェット・ボックスにインストールされません。しかし、フォーム内の他のウィジェットで使用することはできます。この機能は、ユーザが明示的に作成すべきでないが、他のウィジェットが必要とするウィジェットを隠すために使用されます。

完全なカスタムウィジェットの仕様は、次のようになります：

<ui language="c++"> displayname="MyWidget">
    <widget class="widgets::MyWidget" name="mywidget"/>
    <customwidgets>
        <customwidget>
            <class>widgets::MyWidget</class>
            <addpagemethod>addPage</addpagemethod>
            <propertyspecifications>
                <stringpropertyspecification name="fileName" notr="true" type="singleline"/>
                <stringpropertyspecification name="text" type="richtext"/>
                <tooltip name="text">Explanatory text to be shown in Property Editor</tooltip>
            </propertyspecifications>
        </customwidget>
    </customwidgets>
</ui>

<ui> タグの属性：

<addpagemethod> タグは、コンテナウィジェットにページを追加するためにどのメソッドを使うべきかをQt Widgets Designer とuicに伝えます。これは、親を渡して子を追加するのではなく、特定のメソッドを呼び出して子を追加する必要があるコンテナウィジェットに適用されます。特に、Qt Widgets Designer で提供されるコンテナのサブクラスではなく、カレント・ページの概念に基づくコンテナに関連します。さらに、それらのコンテナ用にコンテナ拡張を提供する必要があります。

<propertyspecifications> 要素は、プロパティのメタ情報のリストを含むことができる。

<tooltip> タ グ を用いて、 プ ロ パテ ィ に カー ソ ルを置 く と プ ロ パテ ィ ・ エデ ィ タ に表示 さ れ る ツールチ ッ プを指定す る こ と がで き ます。プロパティ名は属性name で与えられ、要素テキストはツールチップです。この機能は Qt 5.6 で追加されました。

文字列型のプロパティには、<stringpropertyspecification> タグを使用することができます。このタグには以下の属性があります：

文字列プロパティのtype 属性の値：

プラグインの要件

プラグインがすべてのプラットフォームで正しく動作するためには、Qt Widgets Designer で必要とされるシンボルを確実にエクスポートする必要があります。

まず、Qt Widgets Designer でプラグインを読み込むためには、プラグインクラスがエクスポートされていなければなりません。これにはQ_PLUGIN_METADATA() マクロを使用します。また、Qt Widgets Designer がインスタンス化するプラグイン内の各カスタム・ウィジェット・クラスを定義するには、QDESIGNER_WIDGET_EXPORT マクロを使用する必要があります。

お行儀のよいウィジェットの作成

カスタムウィジェットの中には、Qt Widgets Designer にある標準ウィジェットの多くとは異なる動作をさせる特別なユーザーインターフェイス機能を持つものがあります。具体的には、QWidget::grabKeyboard() の呼び出しの結果、カスタムウィジェットがキーボードをつかんだ場合、Qt Widgets Designer の動作が影響を受けます。

Qt Widgets Designer でカスタムウィジェットに特別な動作を与えるには、Qt Widgets Designer 特有の動作のためにウィジェット構築プロセスを構成する initialize() 関数の実装を提供します。この関数は、createWidget()を呼び出す前に初めて呼び出され、後でQt Widgets Designer がプラグインのcreateWidget()関数を呼び出すときにテストできる内部フラグを設定できるかもしれません。

プラグインのビルドとインストール

シンプルなプラグイン

Custom Widget Pluginは、シンプルなQt Widgets Designer プラグインを示します。

プラグインのプロジェクトファイルは、カスタムウィジェットとプラグインインターフェイスの両方のヘッダーとソースを指定しなければなりません。通常、このファイルは、プラグインのプロジェクトがライブラリとしてビルドされ、Qt Widgets Designer 用の特定のプラグインがサポートされることを指定するだけでよい。CMake の場合、これは以下の宣言で行われます：

find_package(Qt6 REQUIRED COMPONENTS Core Gui UiPlugin Widgets)

qt_add_plugin(customwidgetplugin)
target_sources(customwidgetplugin PRIVATE
    analogclock.cpp analogclock.h
    customwidgetplugin.cpp customwidgetplugin.h
)
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 ライブラリに動的にリンクされ、実行時に依存するようになります。

また、プラグインが他の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}"
)

qmake の場合：

CONFIG      += plugin
TEMPLATE    = lib
HEADERS     = analogclock.h \
              customwidgetplugin.h
SOURCES     = analogclock.cpp \
              customwidgetplugin.cpp
OTHER_FILES += analogclock.json

QT 変数にはキーワードuiplugin が含まれており、これはQt::UiPlugin ライブラリと同等である。

また、このプラグインが他のQt Widgets Designer ウィジェット・プラグインと一緒にインストールされていることを確認する必要があります：

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

$[QT_INSTALL_PLUGINS] 変数は、インストールされた Qt プラグインの場所を示すプレースホルダです。アプリケーションを実行する前にQT_PLUGIN_PATH 環境変数を設定することで、他の場所にあるプラグインを探すようにQt Widgets Designer を設定することができます。

Qt アプリケーションでライブラリやプラグインのパスをカスタマイズする方法については、QCoreApplication::libraryPaths() を参照してください。

プラグインがQt Widgets Designer と互換性のないモードでビルドされている場合、プラグインはロードおよびインストールされません。プラグインの詳細については、プラグイン HOWTOドキュメントを参照してください。

プラグインの分割

上記で説明した単純なアプローチでは、Qt Widgets Designer の他のインターフェイスを使用する際に、特にリンクが発生するという問題が発生します：カスタムウィジェットを使うアプリケーションは、Qt Widgets Designer のヘッダーとライブラリに依存することになります。実世界のシナリオでは、これは望ましいことではありません。

以下のセクションでは、これを解決する方法を説明します。

ウィジェットをアプリケーションにリンクする

qmake を使用する場合、インクルード用の.pri ファイルを作成することで、カスタムウィジェットのソースとヘッダーファイルをアプリケーションとQt Widgets Designer の間で共有できます：

INCLUDEPATH += $$PWD
HEADERS += $$PWD/analogclock.h
SOURCES += $$PWD/analogclock.cpp

このファイルは、プラグインとアプリケーションの.pro ファイルによってインクルードされます：

include(customwidget.pri)

CMake を使用する場合、ウィジェットのソースファイルも同様にアプリケーションプロジェクトに追加できます。

ライブラリを使用してウィジェットを共有する

もう1つのアプローチは、アプリケーションと同様にQt Widgets Designer プラグインにリンクされるライブラリにウィジェットを配置することです。実行時にライブラリの場所を特定する問題を避けるために、静的ライブラリを使用することを推奨します。

共有ライブラリについては、共有ライブラリの作成を参照してください。

QUiLoaderでプラグインを使う

QUiLoader にカスタムウィジェットを追加する好ましい方法は、QUiLoader::createWidget() を再実装してサブクラス化することです。

しかし、Qt Widgets Designer カスタムウィジェットプラグインを使用することも可能です（QUiLoader::pluginPaths() および関連関数を参照）。Qt Widgets Designer ライブラリをターゲット・デバイスにデプロイする手間を省くため、これらのプラグインはQt Widgets Designer ライブラリにリンクしていない必要があります (QT = uiplugin 、 Qt Widgets Designer 用カスタムウィジェットの作成#BuildingandInstalling thePlugin を参照)。

関連する例

Qt Widgets Designer でのカスタムウィジェットの使用に関する詳細については、カスタムウィジェットプラグインと タスクメニュー拡張の例を参照してください。Qt Widgets Designer 。また、QDesignerCustomWidgetCollectionInterface クラスを使用すると、複数のカスタムウィジェットを 1 つのライブラリにまとめることができます。