Qt デザイナ用のカスタムウィジットの作成

Qt デザイナのプラグインに基づいたアーキテクチャはユーザー定義やサードパーティー製のカスタムウィジットを標準の Qt のウィジットと同様に扱うことができます。プロパティ、シグナル、スロットなどの全てのカスタムウィジットの機能は Qt デザイナで使用できるように作られます。 Qt デザイナ は実際のウィジットをフォームのデザイン時に使用するため、カスタムウィジットはプレビュー時と同じように表示されるでしょう。

Qt デザイナ でも QtDesigner モジュールの機能の一部を使用してカスタムウィジットを作成することができます。

はじめに
インターフェースの説明

Notes on the domXml() 関数

プラグインが要求するもの
行儀のよいウィジットの作成
プラグインのビルドとインストール
関連サンプル

はじめに

既存のカスタムウィジットを Qt デザイナ で使えるようにするために必要なものはウィジットの適当な説明と適切なプロジェクトファイルだけです。

インターフェースの説明

提供するウィジットのタイプを Qt デザイナ に教えるためには QDesignerCustomWidgetInterface のサブクラスを作成しなければなりません。このインターフェースクラスは様々な外に現れるプロパティを定義します。これらのほとんどはプラグインの作者がこの情報を提供するべきなので、純粋仮想関数で提供されます。

関数	返り値の説明
`name()`	ウィジットが提供するクラスの名前。
`group()`	ウィジットが属する Qt デザイナのグループ。
`toolTip()`	短い説明( Qt デザイナのユーザーのための)。
`whatsThis()`	長めの説明( Qt デザイナのユーザーのための)。
`includeFile()`	このウィジットを使用するためにアプリケーションにインクルードするヘッダーファイル。この情報は .ui ファイルの中に納められ、 `uic` がカスタムウィジットを含んだフォームのコードを作成する際に、適切な `#includes` 文を作成する為に使用されます。
`icon()`	ウィジットが Qt デザイナのウィジットボックスに表示される際に使用されるアイコン。
`isContainer()`	もしウィジットが子ウィジットを含むことができる場合は true；そうでなければ false。
`createWidget()`	カスタムウィジットのインスタンスの QWidget 型のポインタ。parent を指定して作成される。
`domXml()`	ウィジットの名前やサイズヒントや他の標準的な QWidget のプロパティなどを記述したものを返す。
`codeTemplate()`	この関数は Qt デザイナで将来つかわれる為に予約されています。

他の２つの仮想関数も再実装されるべきです：

`initialize()`	カスタムウィジットの拡張機能や他の機能のセットアップ。カスタムコンテナの拡張( QDesignerContainerExtensionを参照) や、タスクメニューの拡張( QDesignerTaskMenuExtensionを参照) もこの関数で行うべきです。
`isInitialized()`	もしウィジットの初期化が完了していれば true を返します；そうでなければ false を返します。再実装時は initialize() 関数が実行されたかをチェックし、その結果を返します。

Notes on the `domXml()` Function

The domXml() function returns a .ui file snippet that is used by Qt デザイナ's widget factory to create a custom widget and its applicable properties.

Since Qt 4.4, Qt デザイナ's widget box allows for a complete UI file describing one custom widget. The UI file can be loaded using the <ui> tag. Specifying the <ui> tag allows for adding the <customwidget> element that contains additional information for custom widgets. The <widget> tag is sufficient if no additional information is required

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

     ...
            " <property name=\"geometry\">\n"
            "  <rect>\n"
            "   <x>0</x>\n"
            "   <y>0</y>\n"
            "   <width>100</width>\n"
            "   <height>100</height>\n"
            "  </rect>\n"
            " </property>\n"
     ...

domXml() のさらなる機能として、もし空文字列を返す場合はこのウィジットは Qt デザイナのウィジットボックスにインストールされません。フォーム内の他のウィジットでは使用することができます。この機能はユーザーは作成できないけれども他のウィジットの為に必要なウィジットを(デザイナのウィジットボックスから)隠すために使用されます。

If you would like to use a container widget that is not a subclass of the containers provided in Qt デザイナ, but the container is still based on the notion of Current Page, you need to provide a container extension and tell Qt デザイナ which method to use to add the pages. This can be done using the <addpagemethod> XML tag.

プラグインが要求するもの

全てのプラットフォームでプラグインが正常に動作するためには、 Qt デザイナが必要とするシンボルが正しく export されている必要があります。

まず初めに、 Qt デザイナがプラグインのクラスをロードできるように、プラグイン自体が export されている必要があります。 Q_EXPORT_PLUGIN2() マクロがこれを行います。

次に、プラグイン内の Qt デザイナ がインスタンスを作成するそれぞれのカスタムウィジットクラスは QDESIGNER_WIDGET_EXPORT マクロによって定義されている必要があります。

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

いくつかのカスタムウィジットは Qt デザイナの標準的なウィジットの多くのものと異なる振る舞いの特別なユーザーインターフェースを持ちます。具体的には、もしカスタムウィジットが QWidget::grabKeyboard() を呼んでキーボードをグラブすると、 Qt デザイナ の挙動に影響がでます。

カスタムウィジットが Qt デザイナで使用される際に特別な動作をさせるには、 initialize() 関数を Qt デザイナ 専用にウィジットを作成するような作りにしてください。この関数は一番初め(createWidget() より前)に呼ばれるようになっていて、その後で Qt デザイナ がプラグインの createWidget() 関数を呼び出す際に参照できるような内部のフラグを設定できます。

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

プラグイン用のプロジェクトファイルにはカスタムウィジット自体とプラグイン用のヘッダファイルとソースファイルを指定しなければなりません。基本的にはプロジェクトファイルは単にプラグインのプロジェクトがライブラリで、 Qt デザイナ用のプラグインのサポートをすることを必要とします。これは下記のような定義になります：

 CONFIG      += designer plugin
 TARGET      = $$qtLibraryTarget($$TARGET)
 TEMPLATE    = lib

Qt が debug と release の両方のモードに対応している場合、 Qt デザイナ はリリースモードでビルドされるでしょう。この時、プラグインもプラグインもリリースモードでビルドされることを保証する必要があります。このため、プラグインのプロジェクトファイルに下記の定義を含めてください：

 CONFIG += release

もしプラグインが Qt デザイナと異なるモードでビルドされた場合、それはロードもインストールもされないでしょう。プラグインに関するより詳しい情報は Plugins HOWTO を参照してください。

さらには、プラグインが Qt デザイナ の他のウィジットのプラグインと同じ場所にインストールされることを保証する必要があります：

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

$[QT_INSTALL_PLUGINS] 変数は Qt のプラグインがインストールされている場所を表します。 Qt デザイナ に他の場所のプラグインを探させるのは、アプリケーションの実行前に環境変数 QT_PLUGIN_PATH を設定することで可能です。 Qt デザイナ は指定された各パスの designer サブディレクトリの中を探します。

Qt アプリケーションのライブラリとプラグインのパスのカスタマイズに関する詳細な情報は QCoreApplication::libraryPaths() を参照してください。