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

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

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 で提供されるコンテナのサブクラスではなく、Current Page の概念に基づくコンテナに関連します。さらに、それらのコンテナ用にコンテナ拡張機能を提供する必要があります。

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

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

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

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

プラグインの要件

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

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

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

カスタムウィジェットの中には、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 と互換性のないモードでビルドされている場合、プラグインはロードおよびインストールされません。プラグインの詳細については、Plugins 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 Qt Widgets Designer でのカスタム ウィジェットの使用に関する詳細は、Custom Widget PluginおよびTask Menu Extensionの例を参照してください。また、 クラスを使用して、複数のカスタム ウィジェットを 1 つのライブラリにまとめることができます。QDesignerCustomWidgetCollectionInterface