概要 - QMLとC++の統合

QMLは、C++コードを通じて容易に拡張できるよう設計されています。 Qt Qml モジュール内のクラスにより、C++ から QML オブジェクトを読み込んで操作することが可能であり、Qt Qml エンジンと Qtのメタオブジェクトシステムとの統合の仕組みにより、Qml から直接 C++ の機能を呼び出すことが可能です。これにより、Qml、JavaScript、および C++ コードを組み合わせて実装されたハイブリッドアプリケーションの開発が可能になります。

QMLとC++の統合により、次のようなさまざまな可能性が生まれます。

• QMLドキュメント内でQMLおよびJavaScriptを用いてユーザーインターフェースコードを実装し、C++を用いてアプリケーションロジックコードを実装することで、両者を分離する
• QML から一部の C++ 機能を使用および呼び出す（たとえば、アプリケーションロジックを呼び出したり、C++ で実装されたデータモデルを使用したり、サードパーティの C++ ライブラリ内の関数を呼び出したりするため）
• Qt Qml または Qt Quick C++ APIの機能にアクセスできる（例：QQuickImageProvider を使用して画像を動的に生成するなど）
• C++ から独自のQML オブジェクト型を実装します。これは、独自の特定のアプリケーション内で使用する場合でも、他者に配布する場合でも同様です

QML に C++ データや機能を提供するには、QObject を継承したクラスからそれらを利用可能にする必要があります。 QML エンジンはメタオブジェクトシステムと統合されているため、「C++ 型の属性を QML に公開する」で説明されているように、QObject を継承したクラスのプロパティ、メソッド、シグナルには QML からアクセスできます。必要な機能がそのようなクラスによって提供されると、さまざまな方法で QML に公開することができます。

• その クラスをインスタンス化可能なQML型として登録することで、QMLコードから通常のQMLオブジェクト型と同様にインスタンス化して使用できるようになります
• クラスをシングルトン型として登録することで、QMLコードからそのクラスの単一インスタンスをインポートできるようになり、QMLからそのインスタンスのプロパティ、メソッド、シグナルにアクセスできるようになります

これらは、QMLコードからC++の機能にアクセスするための最も一般的な方法です。QML Type Registration Macros には、他にも多くのオプションやバリエーションが用意されています。さらに、QMLからC++の機能にアクセスする機能に加え、 Qt Qml このモジュールは、その逆、つまりC++コードからQMLオブジェクトを操作する方法も提供しています。詳細については、「C++からQMLオブジェクトとの相互作用」を参照してください。

ある状態をグローバルプロパティとしてQMLに公開することが望ましい場合がよくあります。「C++からQMLへの状態の公開」では、その方法について説明しています。

C++コードは、スタンドアロンアプリケーションとして配布するか、ライブラリとして配布するかによって、C++アプリケーションまたはスタンドアロンのQMLモジュールのいずれかに統合することができます。 QMLモジュールにはC++プラグインを含めることができ、そのプラグインはQMLエンジンによって動的に読み込まれることができます。これにより、アプリケーションはバイナリにリンクされていないQMLモジュールを使用できるようになります。

また、スタンドアロンのプラグインを手動で作成することも可能です。詳細については、「C++プラグインでの型と機能の提供」を参照してください。ただし、この方法は推奨されません。

最後に、クラスのインスタンスをコンテキストプロパティまたはコンテキストオブジェクトとしてQMLコードに埋め込むことができます。これにより、QMLからそのインスタンスのプロパティ、メソッド、シグナルにアクセスできるようになります。コンテキストプロパティの使用は避けるべきです。

C++とQML間の適切な統合方法の選択

どの統合方法が自分の状況に適しているかを素早く判断するには、以下のフローチャートを参照してください。

フローチャート内のマクロの説明については、「C++ からの QML 型の定義」のドキュメントを参照してください。

C++クラスの属性をQMLに公開する

QMLエンジンはQtメタオブジェクトシステムと統合されているため、C++からQMLを容易に拡張できます。この統合により、QObject を継承するクラスのプロパティ、メソッド、シグナルにQMLからアクセスできるようになります。プロパティの読み取りや変更が可能で、JavaScript式からメソッドを呼び出すことができ、必要に応じてシグナルに対してシグナルハンドラが自動的に生成されます。 さらに、QObject を継承したクラスの列挙型値も、QMLからアクセス可能です。

詳細については、「C++ 型の属性を QML に公開する」を参照してください。

C++ からの QML 型の定義

QML 型は C++ で定義し、QML 型システムに登録することができます。これにより、C++ クラスをQML オブジェクト型としてインスタンス化できるようになり、C++ でカスタムオブジェクト型を実装して、既存の QML コードに統合することが可能になります。 C++ クラスは、他の目的でも登録することができます。たとえば、QML コードから単一のクラスインスタンスをインポートできるようにするためにシングルトン型として登録したり、インスタンス化できないクラスの列挙値を QML からアクセスできるようにするために登録したりすることができます。

さらに、 Qt Qml このモジュールは、アタッチドプロパティやデフォルトプロパティといったQMLの概念と統合するQML型を定義するためのメカニズムも提供します。

C++ からのカスタム QML タイプの登録および作成の詳細については、「C++ からの QML タイプの定義」のドキュメントを参照してください。

コンテキストプロパティを使用した C++ オブジェクトの QML への埋め込み

C++ オブジェクトや値は、コンテキストプロパティやコンテキストオブジェクトを使用して、ロードされた QML オブジェクトのコンテキスト（またはスコープ）に直接埋め込むことができます。これは、QQmlContext クラスによって実現されます。このクラスは Qt Qml xml-ph-0000@deepl.internalクラスを介して実現されます。このクラスは、QMLコンポーネントのコンテキストに対してデータを公開し、C++からQMLへデータを注入することを可能にします。

詳細については、「コンテキストプロパティを使用した C++ オブジェクトの QML への埋め込み」を参照してください。

C++ から QML オブジェクトとのやり取り

QML オブジェクト型は C++ からインスタンス化でき、そのプロパティへのアクセス、メソッドの呼び出し、シグナル通知の受信を行うために検査することができます。これは、すべての QML オブジェクト型が `QObject` の派生クラスを使用して実装されており、Qt メタオブジェクトシステムを通じて QML エンジンがオブジェクトを動的にロードおよびイントロスペクションできるためです。

C++ から QML オブジェクトにアクセスする方法の詳細については、「C++ からの QML オブジェクトとのやり取り」に関するドキュメント、および「ベストプラクティス」ページの「C++ から QML へのデータ公開」のセクションを参照してください。

QMLとC++間のデータ型変換

QMLとC++の間でデータ値がやり取りされる際、QMLエンジンは、QMLまたはC++での使用に適した正しいデータ型になるよう変換を行います。ただし、これには、関連するデータ型がエンジンに認識されていることが前提となります。

エンジンがサポートする組み込み型や、QMLとC++間でデータをやり取りする際にこれらの型がどのように変換されるかについては、「QMLとC++間のデータ型の変換」を参照してください。