QMLモジュールのCMakeへの移植

Qt 6 では、Qml モジュールがより強力になり、使いやすくなりました。以下のセクションでは、Qml モジュールをqt_add_qml_moduleCMake API に移植する方法について説明します。

また、すでにqt_add_qml_module を使用している QML モジュールを最新化する方法については、「QML モジュールの最新化」を参照してください。

修正すべき問題の特定

このプロセスでは、qmllintを活用してください。

qt_add_qml_moduleで定義された各 QML モジュールには、_qmllint という CMake ターゲットがあり、これを使用して潜在的な問題や改善点を特定できます。たとえば、MyQmlLibrary という QML モジュールの場合は、MyQmlLibrary_qmllint を実行します。すべての QML モジュールに対してqmllintを実行するには、all_qmllint を使用します。

QML モジュールの問題を暗示するqmllintの警告カテゴリは以下の通りです：

• [import]
• [unused-imports]
• [unresolved-type]
• [unresolved-alias]
• [missing-enum-entry]
• [プロパティ欠落]
• [型欠落]

qt_add_qml_module 用のプロジェクトを準備する

CMakeでqt_add_qml_moduleを利用可能にする

CMakeでqt_add_qml_moduleを利用可能にするには、プロジェクトの最上位にあるCMakeLists.txt ファイル内のfind_package 呼び出しに、Core およびQml を追加してください：

find_package(Qt6 REQUIRED COMPONENTS Core Qml)

qt_standard_project_setup を使用する

qt_standard_project_setup は、qt_add_qml_module に必要なQt CMake ポリシーなどを設定します。

プロジェクトの最上位にあるCMakeLists.txt ファイル内で、qt_add_qml_moduleを呼び出す前にqt_standard_project_setup を呼び出してください:

qt_standard_project_setup(REQUIRES 6.8)

qt_add_qml_module の使用

qt_add_qml_moduleは、QML モジュールの生成を担当する CMake 関数です。この関数は、qmldir およびqmltypes ファイルを自動的に生成し、qmlcachegenやqmllint などのツールを設定します。

QMLモジュールは、CMakeの実行ファイルターゲットとライブラリターゲットの両方に追加できます。実行ファイルターゲットに紐付けられたQMLモジュールは、他の実行ファイルから使用したりリンクしたりすることはできませんが、ライブラリターゲットに紐付けられたQMLモジュールは可能です。

実行可能ターゲットに QML モジュールを追加する

この場合、QML モジュールのソースファイルは、個別のライブラリとしてコンパイルされるのではなく、実行ファイル自体の一部として扱われます。つまり、このモジュール用のモジュールやプラグインライブラリは作成されず、モジュールは実行ファイルに完全に統合されます。 その結果、そのモジュールは当該プログラムに紐付けられ、他の実行ファイルやライブラリでは再利用できません。

実行可能ファイルに QML モジュールを追加するには、CMakeLists.txt 内で次のように指定します：

# pre-existing:
qt_add_executable(MyApp main.cpp)

# add this
qt_add_qml_module(MyApp
    URI MyAppModule
    QML_FILES
        Main.qml # and possibly more .qml files
)

Main.qml は、QQmlApplicationEngine::loadFromModule やQQmlComponent::loadFromModule といったloadFromModule メソッドによってインスタンス化されるように、大文字で始まるようにしてください。また、ビルドフォルダ内での名前衝突を避けるため、QMLモジュールのURIはターゲット名とは異なるものにしてください。

ライブラリターゲットに QML モジュールを追加する

ライブラリに QML モジュールを追加するには、CMakeLists.txt 内で次のように記述します。

qt_add_qml_module(MyQmlLibrary
    URI MyQmlModule
    QML_FILES MyQmlComponent1.qml MyQmlComponent2.qml...
    SOURCES MyCppComponent1.h MyCppComponent1.cpp MyCppComponent2.h MyCppComponent2.cpp...
    RESOURCES MyResource1.png MyResource2.png...
)

qt_add_qml_module は、この例のようにMyQmlLibrary ターゲットがまだ存在しない場合、qt_add_libraryを通じてSHARED ライブラリを作成します。

QMLファイルを読み込むには `loadFromModule` を使用します

loadFromModule を使用して QML ファイルをロードします。例：

engine.load(QUrl(QStringLiteral("qrc:/MyQmlModule/Main.qml")));
// becomes
engine.loadFromModule("MyQmlModule", "Main");

手動で作成された qmldir ファイルを削除する

qt_add_qml_module は qmldir ファイルを自動的に生成します。qmldir にシングルトンがある場合は、CMakeLists.txt 内でqt_add_qml_moduleを呼び出す前に、次のように宣言してください:

set_source_files_properties(MySingleton.qml PROPERTIES QT_QML_SINGLETON_TYPE TRUE)

その後、手動で作成したqmldir を削除してください。

qmlplugindump によって生成された qmltypes ファイルを削除してください

qt_add_qml_module は、すべての型が宣言型登録を使用している場合にqmltypes ファイルを自動生成します。これにより、qmlplugindump などのツールを使用してqmltypes ファイルを手動で生成する必要がなくなります。

これを実現するには、qmlRegisterType およびその派生関数への手動呼び出しを削除してください。その後、QML_ELEMENT を使用して型を宣言的に登録します。例：

// add this header
#include <QtQml/qqmlregistrations.h>

class MyComponent: public QObject {
    Q_OBJECT

    // add this line to register MyComponent as 'MyComponent' in QML.
    QML_ELEMENT
    ....
};

外部型の登録など、より複雑な登録ケースの扱い方については、「QML タイプシステムへの C++ 型の登録」を参照してください。

その後、手動で作成したqmltypes ファイルを削除してください。

手動で作成した型登録プラグインの削除

qt_add_qml_moduleを使用すると、QML モジュールプラグインを自動的に生成できます。プラグインの唯一の役割が型登録である場合は、手動で作成したプラグインは必要ありません。宣言型登録への切り替えによってプラグイン内のコードがすべて削除された場合は、そのプラグインを完全に削除してください。

自動プラグイン生成を可能にするため、qt_add_qml_moduleからNO_PLUGIN 、NO_PLUGIN_OPTIONAL 、NO_CREATE_PLUGIN_TARGET 、およびNO_GENERATE_PLUGIN_SOURCE 引数を必ず削除してください。

qrc ファイルの削除

qt_add_qml_module は qrc ファイルを自動的に生成します。qrc ファイルに画像や音声ファイルなどのリソースを記載するには、それらをqt_add_qml_module の RESOURCES 引数に追加してください。モジュールのリソースは:/qt/qml/MyQmlLibraryModule/ にあります。

ディレクトリインポートを QML モジュールインポートに置き換える

ディレクトリインポートを QML モジュールインポートに置き換えてください。例えば、

import "content" // contains SomeType.qml
// becomes
import MyQmlModule // contains SomeType.qml

SomeType {
    ...
}

QMLモジュール内のファイルは、自動的に自身のQMLモジュールをインポートすることに注意してください。これらの自己インポートは削除できます。