以下の用途向けのカスタムウィジェットの作成Qt Widgets Designer

Qt Widgets Designerのプラグインベースのアーキテクチャにより、ユーザー定義のカスタムウィジェットやサードパーティ製のカスタムウィジェットを、標準のQt Widgetsと同様に編集することができます。 ウィジェットのプロパティ、シグナル、スロットなど、カスタムウィジェットのすべての機能が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 で提供されているコンテナのサブクラスではないものの、「現在のページ (Current Page)」の概念に基づいているコンテナに関連します。さらに、それらのコンテナにはコンテナ拡張機能を提供する必要があります。

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

<tooltip> タグは、プロパティにカーソルを合わせた際にプロパティエディタに表示されるツールチップを指定するために使用できます。プロパティ名はname 属性で指定され、要素のテキストがツールチップとなります。この機能はQt 5.6で追加されました。

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

stringプロパティの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()関数を呼び出す際に後でチェックできる内部フラグを設定することも可能です。

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

簡単なプラグイン

「カスタムウィジェットプラグイン」は、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 XML アプリケーションにおけるライブラリやプラグインのパスをカスタマイズする方法の詳細については、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 を使用する場合、ウィジェットのソースファイルも同様にアプリケーションプロジェクトに追加できます。

ライブラリを使用したウィジェットの共有

もう一つの方法は、ウィジェットをライブラリに格納し、そのライブラリをQt Widgets Designer プラグインおよびアプリケーションの両方にリンクさせることです。実行時にライブラリが見つからないといった問題を回避するため、静的ライブラリを使用することをお勧めします。

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

QUiLoader でのプラグインの使用

QUiLoader にカスタムウィジェットを追加する推奨される方法は、QUiLoader::createWidget()を再実装してそのサブクラスを作成することです。

ただし、Qt Widgets Designer のカスタムウィジェットプラグインを使用することも可能です（QUiLoader::pluginPaths()および関連関数を参照）。Qt Widgets Designer ライブラリをターゲットデバイスにデプロイする必要を避けるため、これらのプラグインはQt Widgets Designer ライブラリとのリンクを含んではいけません（QT = uiplugin 、「Qt Widgets Designer 用のカスタムウィジェットの作成」の「#プラグインのビルドとインストール」を参照）。

関連する例

Qt Widgets Designer Qt Widgets Designer でのカスタムウィジェットの使用に関する詳細については、「Custom Widget Plugin」および「Task Menu Extension」のサンプルを参照してください。また、 クラスを使用することで、複数のカスタムウィジェットを1つのライブラリにまとめることができます。QDesignerCustomWidgetCollectionInterface