モジュール定義qmldirファイル

qmldir ファイルには2つの種類があります：

• QML 文書ディレクトリ一覧ファイル
• QMLモジュール定義ファイル

この文書では、2番目の形式であるqmldir ファイルのみを扱います。このファイルには、モジュールの下で利用可能な QML タイプ、JavaScript ファイル、プラグインが列挙されています。最初の形式であるqmldir ファイルについては、ディレクトリ一覧 qmldir ファイルを参照してください。

モジュール定義 qmldir ファイルの内容

qmldir ファイルは、以下のコマンドを含むプレーンテキストファイルです：

• モジュール識別子宣言
• オブジェクト・タイプの宣言
• 内部オブジェクト型の宣言
• JavaScript リソース宣言
• プラグイン宣言
• プラグインクラス名の宣言
• 型記述ファイル宣言
• モジュール依存宣言
• モジュールのインポート宣言
• デザイナー・サポート宣言
• 優先パス宣言

コマンドだけでなく、# で始まるコメントを追加することもできます。

モジュール識別子宣言

module <ModuleIdentifier>

モジュールのモジュール識別子を宣言します。<ModuleIdentifier>はモジュールの（ドットURI記法の）識別子で、モジュールのインストールパスと一致しなければなりません。

モジュール識別子ディレクティブはファイルの最初の行でなければなりません。qmldir ファイルには、正確に一つのモジュール識別子ディレクティブが存在します。

例

module ExampleModule

オブジェクト型の宣言

[singleton] <TypeName> <InitialVersion> <File>

モジュールで利用可能なQMLオブジェクトタイプを宣言します。

• [singleton] オプション。シングルトン型の宣言に使用します。
• <TypeName> は利用可能な型です。
• <InitialVersion> はその型が利用可能になるモジュールのバージョンです。
• <File> はその型を定義するQMLファイルの(相対的な)ファイル名です。

qmldir 、0個以上のオブジェクト型を宣言することができます。しかし、各オブジェクト型は、モジュールの特定のバージョン内で一意な型名を持っていなければなりません。

例

//Style.qml with custom singleton type definition
pragma Singleton
import QtQuick 2.0

QtObject {
    property int textSize: 20
    property color textColor: "green"
}

// qmldir declaring the singleton type
module CustomStyles
singleton Style 1.0 Style.qml

// singleton type in use
import QtQuick 2.0
import CustomStyles 1.0

Text {
    font.pixelSize: Style.textSize
    color: Style.textColor
    text: "Hello World"
}

内部オブジェクト型の宣言

internal <TypeName> <File>

モジュール内に存在するが、モジュールのユーザーには公開されるべきでないオブジェクト型を宣言します。

qmldir 、0個以上の内部オブジェクト型宣言が存在する可能性があります。

例

internal MyPrivateType MyPrivateType.qml

なぜなら、エクスポートされた型がモジュール内のエクスポートされていない型に依存している場合、エンジンはエクスポートされていない型もロードしなければならないからです。

JavaScript リソース宣言

<ResourceIdentifier> <InitialVersion> <File>

モジュールによって利用可能になる JavaScript ファイルを宣言します。リソースは、指定されたバージョン番号の指定された識別子を通して利用可能になります。

qmldir ファイルには、0 個以上の JavaScript リソース宣言があってもかまいません。ただし、各 JavaScript リソースは、モジュールの特定のバージョン内で一意な識別子を持たなければなりません。

例

MyScript 1.0 MyScript.js

詳細については、JavaScriptリソースの定義およびQMLにおけるJavaScriptリソースのインポートに関するドキュメントを参照してください。

プラグイン宣言

[optional] plugin <Name> [<Path>]

モジュールで利用可能なプラグインを宣言します。

• optional は、プラグイン自身は関連するコードを含まず、リンク先のライブラリをロードするためだけのものであることを示します。もしこの宣言が与えられ、そのモジュールの型がすでに利用可能で、そのライブラリが他の方法でロードされている場合、QMLはプラグインをロードしません。
• <Name> はプラグインのライブラリ名です。これは通常プラグインのバイナリのファイル名とは異なります。例えば というライブラリは Linux では を、Windows では を生成します。MyAppTypes libMyAppTypes.so MyAppTypes.dll
• <Path> (オプション) は次のいずれかを指定します：
  • プラグインファイルを含むディレクトリへの絶対パス、または
  • qmldir ファイルを含むディレクトリからプラグイン・ファイルを含むディレクトリへの相対パス。

デフォルトでは、エンジンはqmldir ファイルを含むディレクトリでプラグインライブラリを検索します。(プラグイン検索パスは、QQmlEngine::pluginPathList() で照会し、QQmlEngine::addPluginPath() で変更することができます)。

qmldir ファイルには、0個以上のC++プラグイン宣言が存在する可能性があります。しかし、プラグインのロードは比較的負荷の高い操作であるため、クライアントは最大でも1つのプラグインを指定することをお勧めします。

例

plugin MyPluginLibrary

プラグインクラス名の宣言

classname <C++ plugin class>

モジュールで使用されるC++プラグインのクラス名を指定します。

この情報は、追加機能のためにC++プラグインに依存する全てのQMLモジュールに必要である。Qt Quick 静的リンクでビルドされたアプリケーションは、この情報がないとモジュールのインポートを解決できない。

型記述ファイルの宣言

typeinfo <File>

モジュールのプラグインによって定義された型に関する情報にアクセスするために、Qt Creator のような QML ツールが読み込むことのできるモジュールの型記述ファイルを宣言します。<File> は.qmltypes ファイルの（相対）ファイル名です。

例

typeinfo mymodule.qmltypes

このようなファイルがないと、QMLツールはプラグインで定義された型のコード補完などの機能を提供できない可能性があります。

モジュール依存宣言

depends <ModuleIdentifier> <InitialVersion>

このモジュールが他のモジュールに依存していることを宣言します。

例

depends MyOtherModule 1.0

この宣言が必要なのは、依存関係が隠されている場合だけです。例えば、あるモジュールの C++ コードを使用して QML を（おそらく条件付きで）ロードし、それが他のモジュールに依存している場合です。このような場合、depends 宣言は、他のモジュールをアプリケーションパッケージに含めるために必要です。

モジュールインポート宣言

import <ModuleIdentifier> [<Version>]

このモジュールが他のモジュールをインポートすることを宣言します。

例

import MyOtherModule 1.0

例：他のモジュールの型は、このモジュールがインポートされているのと同じ型名前空間で利用可能になります。バージョンを省略すると、他のモジュールの最新バージョンがインポートされます。version にauto を指定すると、QMLimport 。

デザイナーサポート宣言

designersupported

プラグインがQt Quick Designer でサポートされている場合、このプロパティを設定します。デフォルトでは、プラグインはサポートされません。

Qt Quick Designerでサポートされるプラグインは、適切にテストされなければなりません。これは、Qt Quick DesignerでQMLを実行するために使用されるqml2puppet内でプラグインを実行しても、プラグインがクラッシュしないことを意味します。一般的に、プラグインはQt Quick Designerで問題なく動作し、過剰な量のメモリを消費したり、qml2puppetの速度を著しく低下させたり、Qt Quick Designerでプラグインが事実上使用できなくなるようなショーストッパーを引き起こしてはなりません。

サポートされていないプラグインのアイテムはQt Quick Designer では描画されませんが、空のボックスとして使用でき、プロパティを編集できます。

優先パス宣言

prefer <Path>

このプロパティは、QMLエンジンに、このモジュールに追加するファイルを、カレントディレクトリではなく、<path>から読み込むように指示します。これはqmlcachegenでコンパイルされたファイルをロードするために使用できます。

例えば、あるモジュールの QML ファイルをリソースパス:/my/path/MyModule/ に追加します。そして、ファイルシステム内のファイルではなく、リソースシステム内のファイルを使用するために、qmldir ファイルにprefer :/my/path/MyModule を追加します。その後、qmlcachegenを使用することで、コンパイル済みのファイルをモジュールのクライアントが利用できるようになります。

バージョン管理

特定のメジャーバージョン用にエクスポートされた全てのQML型は、同じメジャーバージョン の最新版で利用可能です。例えば、あるモジュールがバージョン1.0でMyButton 型を、バージョン1.1でMyWindow 型を提供する場合、そのモジュールのバージョン1.1 をインポートしたクライアントはMyButton とMyWindow 型を使用することができます。しかし、その逆は真ではありません。特定のマイナーバージョン用にエクスポートされた型は、それ以前のマイナーバージョンをインポートしても使用できません。前述の例では、もしクライアントがモジュールのバージョン1.0 をインポートしていた場合、MyButton の型だけを使うことができ、MyWindow の型は使えません。

モジュールは複数のメジャーバージョンを提供することができますが、クライアントは一度に一つのメジャーバージョンにしかアクセスできません。例えば、MyExampleModule 2.0 をインポートすると、そのメジャー・バージョンのみにアクセスでき、前のメジャー・バージョンにはアクセスできません。異なるメジャーバージョンに属する成果物をsigleディレクトリとqmldir ファイルの下に整理することはできますが、メジャーバージョンごとに異なるディレクトリを使用することをお勧めします。以前の方法（1つのディレクトリとqmldir ファイル）を選択した場合は、ファイル名にバージョンの接尾辞を使用するようにしてください。例えば、MyExampleModule 2.0 に属する成果物は、.2 という接尾辞をファイル名に使用できます。

そのバージョン用に明示的にエクスポートされた型がない場合、そのバージョンをインポートすることはできません。あるモジュールがバージョン1.0でMyButton 、バージョン1.1でMyWindow 型を提供している場合、そのモジュールのバージョン1.2やバージョン2.0をインポートすることはできません。

ある型が、異なるマイナー・バージョンの異なるファイルによって定義されることがある。この場合、クライアントがインポートするときには、最も近いバージョンが使われます。例えば、あるモジュールがqmldir ：

module ExampleModule
MyButton 1.0 MyButton.qml
MyButton 1.1 MyButton11.qml
MyButton 1.3 MyButton13.qml
MyRectangle 1.2 MyRectangle12.qml

ExampleModule のバージョン1.2 をインポートするクライアントは、MyButton11.qml が提供するMyButton 型の定義がその型の最新バージョンであり、MyRectangle12.qml が提供するMyRectangle 型の定義を使うことができます。

バージョンシステムは、インストールされているソフトウェアのバージョンに関係なく、あるQMLファイルが動作することを保証します。バージョン指定されたインポートでは、そのバージョンの型のみがインポートされるため、実際にインストールされているバージョンがそのような識別子を提供していたとしても、他の識別子を利用することができます。

qmldirファイルの例

qmldir ：

module ExampleModule
CustomButton 2.0 CustomButton20.qml
CustomButton 2.1 CustomButton21.qml
plugin examplemodule
MathFunctions 2.0 mathfuncs.js

上記のqmldir ファイルは "ExampleModule "というモジュールを定義しています。このファイルでは、CustomButton QMLオブジェクトタイプをバージョン2.0と2.1で定義しています。また、このモジュールがクライアントからインポートされたときに、エンジンがロードする必要のあるプラグインを指定しており、このプラグインは様々なC++で定義された型をQMLの型システムに登録することができます。Unix 系システムでは、QML エンジンはlibexamplemodule.so をQQmlExtensionPlugin としてロードしようとし、Windows ではexamplemodule.dll をQQmlExtensionPlugin としてロードします。 最後に、qmldir ファイルはJavaScript リソースを指定します。このリソースは、バージョン 2.0 またはそれ以降のバージョン（同じメジャーバージョン）のモジュールがインポートされた場合にのみ利用可能です。

このモジュールがQMLのインポートパスにインストールされている場合、クライアントは以下のようにモジュールをインポートして使用することができます：

import QtQuick 2.0
import ExampleModule 2.1

Rectangle {
    width: 400
    height: 400
    color: "lightsteelblue"

    CustomButton {
        color: "gray"
        text: "Click Me!"
        onClicked: MathFunctions.generateRandom() > 10 ? color = "red" : color = "gray";
    }
}

上記で使用したCustomButton 型はCustomButton21.qml ファイルで定義されたものであり、MathFunctions 識別子で識別される JavaScript リソースはmathfuncs.js ファイルで定義されたものです。

型記述ファイル

QMLモジュールは、qmldir の中で1つ以上の型情報ファイルを参照することができます。これらのファイルは通常.qmltypes という拡張子を持ち、C++で定義された型に関する情報を得るために外部ツールによって読み込まれ、通常はプラグインを介してインポートされます。

このようなqmltypesファイルはQMLモジュールの機能には何の影響も与えません。唯一の用途は、Qt Creator のようなツールにコード補完やエラーチェックなどの機能を提供させることです。

C++でQMLの型を定義しているモジュールは、必ず型記述ファイルを同梱する 必要があります。

モジュールのqmltypesファイルを作成する最良の方法は、ビルドシステムとQML_ELEMENT マクロを使って生成することです。qmltyperegistrarは自動的に.qmltypes 。

例あなたのモジュールが/tmp/imports/My/Module にある場合、plugins.qmltypes というファイルが実際のプラグインバイナリと一緒に生成されるはずです。

登録するには

typeinfo plugins.qmltypes

を/tmp/imports/My/Module/qmldir に追加してください。