このブログは「What's new in QML Tooling in 6.11, part 3: context property support」を翻訳したものです。
最新のQtリリースであるQt 6.11の公開が間近に迫っています。この短いブログ記事シリーズでは、Qt 6.11でQMLツール群がもたらす新機能をご紹介します。qmllsの新機能に関する第1部はこちら、qmllintの新しい警告に関する第2部はこちらでご覧いただけます。
このブログ記事では、まずcontextプロパティについて簡単に振り返り、その後、qmllintおよびQML Language Serverにおける新しいcontextプロパティのサポートについて解説していきます。
コンテキストプロパティは、C++オブジェクトをQMLに組み込みます。これらはQObjectのQQmlContext上で実行時に定義され、QMLからアクセスすることができます。以下に例を示します：
このC++コードでは、engine.rootContext()->setContextProperty(...)を使用して実行時にコンテキストプロパティを定義し、QMLコードではmyPropertyを介してこれにアクセスします。上記のプログラムを実行すると、setContextProperty()の呼び出し中にQDateTime::currentDateTime()から取得した日付と時刻が出力されます。
上記の例は、コンテキストプロパティを使用しているため、いくつかの問題を抱えています。
contextプロパティを使用しているQMLファイルは、たとえそのファイル内に依存関係が明示されていなくても、特定のQQmlContextに依存しています。そのため、あなたのコードを再利用しようとする人は、再利用先の環境にあなたのコードに必要なQQmlContextが存在するかどうかを判断するのが困難になります。
前回の例では、Main.qmlを別のコンテキストで再利用すると、次のような実行時エラーが発生します：
qrc:/qt/qml/contextproperties/Main.qml:6: ReferenceError: myProperty is not defined
qrc:/qt/qml/contextproperties/Main.qml:4: ReferenceError: myProperty is not definedQMLツールはコンテキストプロパティの定義を認識しておらず、修飾されていないアクセスとコンテキストプロパティの使用を区別することができません。前のスクリーンショットでご覧になったかもしれませんが、QML Language Serverは、myPropertyの使用が修飾されていないアクセスであると警告しています
ドキュメントには、これらをシングルトンや必須プロパティに置き換える方法に関するガイドが掲載されています（注意：ネタバレが含まれている可能性があります！）。
コンテキストプロパティの使用箇所を置き換えることが不可能な場合もあります。例えば、その使用範囲が広すぎる場合や、サードパーティのAPIに由来する場合などが挙げられます。このブログ記事の残りの部分では、コンテキストプロパティを使用する際に「未修飾のアクセス」に関する警告が表示されないように、QMLツールにコンテキストプロパティを認識させる方法について説明します。
qmllintは、Qt 6.11においてコンテキストプロパティの基本的なサポートを追加しました。6.11以前のバージョンでは、qmllintは修飾子なしのアクセスとコンテキストプロパティへのアクセスを区別せずに扱っていました。そのため、コンテキストプロパティの使用に関する警告を無効にすると、本来警告されるべき修飾子なしのアクセスに関する警告まで消えてしまうという問題がありました。
実際の無条件アクセスとコンテキストプロパティへのアクセスを区別するため、コード内に存在するコンテキストプロパティを宣言できる新しい設定ファイルを追加しました。この新しいコンテキストプロパティ設定ファイルを使用するには、プロジェクトのソースフォルダ内に、以下の内容を含む.contextProperties.iniファイルを作成してください。
[General]
disableUnqualifiedAccess = "myContextProperty1,myContextProperty2"
warnOnUsage = "myContextProperty3,myContextProperty4,myContextProperty5"
disableHeuristic = falseこの例における各設定キーについては、次のセクションで説明します。.contextProperties.iniファイルがない場合の警告は、以下の通りです。
コンテキストプロパティをより良い代替案で置き換えることができない、あるいは置き換えないと判断し、そのコンテキストプロパティに対するすべての非修飾アクセス警告を無効にしたい場合は、disableUnqualifiedAccessが最適です。この設定キーには、非修飾アクセス警告を無効にするべきすべてのコンテキストプロパティ名を指定する必要があります。複数のコンテキストプロパティ名を区切るには、「,」を使用してください。
qmllintは、それらのプロパティ名に関する未修飾アクセスの警告をすべて非表示にし、他の関連する未修飾アクセスの警告に集中できるようにします。
この例では、コンテキストプロパティ名にdisableUnqualifiedAccessを追加することで、警告が消えます：
コンテキストプロパティの使用をやはり排除したい（当然のことながら！）とお考えかもしれません。そのため、disableUnqualifiedAccessを使って警告を無効にし、コンテキストプロパティのことを忘れてしまうという方法は、ご自身にとって現実的ではないかもしれません。その場合は、無修飾アクセス（unqualified access ）に対して無修飾アクセス警告を、コンテキストプロパティへのアクセスに対してコンテキストプロパティ関連の警告を出力するように設定することをお勧めします。そのためには、warnOnUsageキーにコンテキストプロパティ名を追加してください。複数のコンテキストプロパティ名を区切るには、「,」を使用します。
qmllintは、warnOnUsageリストに含まれるプロパティに対する修飾なしのアクセスに対して、別の警告カテゴリで異なる警告を出力します。これにより、修飾なしの警告カテゴリを整理することができます。
この例では、コンテキストプロパティ名にwarnOnUsageを追加すると、qmllintは別の警告を出力します：
「これは良いことですが、本当にこの設定ファイルの中にコンテキストプロパティの名前をすべて入力しなければならないのでしょうか？もし、ずっと前に付けたコンテキストプロパティの名前を思い出せなかったらどうするのでしょうか？」と、今、疑問に思われるかもしれません。幸いなことに、コンテキストプロパティを見つけるのに役立つヒントがあります。
6.11のCMakeスクリプトには、C++コード内のコンテキストプロパティ定義を探索するヒューリスティック検索機能が含まれています。これは、ソースフォルダ内でsetContextProperty()の呼び出しをgrepで検索し、その結果をビルドフォルダに保存します。これにより、qmllintは実行時にコンテキストプロパティの定義を検出し、それらにアクセスする際に警告を表示できるようになります。
大規模なプロジェクトでは、ヒューリスティックを使用してソースフォルダを検索するのに時間がかかるため、デフォルトでは無効になっています。ヒューリスティックを手動で実行するには、dump_qml_context_properties CMakeターゲットを呼び出してください。ヒューリスティック検索の結果はビルドフォルダに保存され、リンティング中にqmllintによって読み込まれます。
例えばall_qmllintのようなCMakeのリンティングターゲットの実行中にヒューリスティック検索を自動的に実行するには、リンティングターゲットを呼び出す前に、CMake変数QT_QMLLINT_CONTEXT_PROPERTY_DUMPをONに設定してください。
エディタのCMake拡張機能を通じて、例えばQt Creatorのロケーターにcm dump_qml_context_propertiesと入力してEnterキーを押すなどして、dump_qml_context_propertiesターゲットを実行すると、コンテキストプロパティの使用に関して次のような警告が表示されます：
無条件の警告だけが存在するわけではありません。コンテキストプロパティへのアクセスが検出された可能性があるという新しい警告が追加されました。また、警告メッセージ全体を確認すると、そのコンテキストプロパティの「定義」の場所も表示されます：
myPropertyが本当にコンテキストプロパティなのか、それとも誤検知なのかを確認するために使用できる「定義」の場所です。もし本当にコンテキストプロパティである場合は、.contextProperties.ini内のwarnOnUsageに追加することで、修飾子なしのアクセスに関する警告を解除できます。ヒューリスティックによって検出されたコンテキストプロパティ名の全リストは、ビルドフォルダ内の<build>/.qt/.contextPropertyDump.iniにあります。
ヒューリスティックによって検出されたコンテキストプロパティ名に関する警告を無効にするには、設定ファイル内のdisableHeuristicキーをtrueに設定するか、ビルドフォルダから.contextPropertyDump.iniファイルを削除してください。
まずはコンテキストプロパティとは何かを改めておさらいし、QMLツールにおける新しいコンテキストプロパティのサポートについて解説しました。これで本シリーズの最終回となります。お楽しみいただけたでしょうか。もし期待通りに動作しない場合や、ドキュメントが不十分な点がありましたら、JIRAにてバグ報告をぜひご提出ください。