Vue d'ensemble - Intégration de QML et de C++

QML est conçu pour être facilement extensible par le biais du code C++. Les classes du module Qt Qml permettent de charger et de manipuler des objets QML à partir de C++, et la nature de l'intégration du moteur QML avec le système de méta-objets de Qt permet d'invoquer des fonctionnalités C++ directement à partir de QML. Cela permet de développer des applications hybrides qui sont mises en œuvre avec un mélange de code QML, JavaScript et C++.

L'intégration de QML et de C++ offre de nombreuses possibilités, notamment celle de

• séparer le code de l'interface utilisateur du code logique de l'application, en mettant en œuvre le premier avec QML et JavaScript dans les documents QML, et le second avec C++
• d'utiliser et d'invoquer certaines fonctionnalités C++ à partir de QML (par exemple, pour invoquer votre logique d'application, utiliser un modèle de données mis en œuvre en C++ ou appeler certaines fonctions d'une bibliothèque C++ tierce)
• Accéder à des fonctionnalités dans les bibliothèques Qt Qml ou de l'API Qt Quick (par exemple, pour générer dynamiquement des images à l'aide de QQuickImageProvider).
• Implémenter vos propres types d'objets QML à partir de C++ - que ce soit pour une utilisation au sein de votre propre application ou pour une distribution à d'autres.

Pour fournir des données ou des fonctionnalités C++ à QML, il faut les rendre disponibles à partir d'une classe dérivée de QObject. En raison de l'intégration du moteur QML avec le système de métaobjets, les propriétés, méthodes et signaux de toute classe dérivée de QObject sont accessibles à partir de QML, comme décrit dans Exposing Attributes of C++ Types to QML (Exposer les attributs des types C++ à QML). Une fois que la fonctionnalité requise est fournie par une telle classe, elle peut être exposée à QML de différentes manières :

• La classe peut être enregistrée en tant que type QML instanciable, de sorte qu'elle puisse être instanciée et utilisée comme n'importe quel type d'objet QML ordinaire à partir du code QML
• La classe peut être enregistrée en tant que type Singleton, de sorte qu'une instance unique de la classe peut être importée à partir du code QML, ce qui permet d'accéder aux propriétés, méthodes et signaux de l'instance à partir de QML.

Il s'agit là des méthodes les plus courantes d'accès aux fonctionnalités C++ à partir du code QML. Le site QML Type Registration Macros offre un certain nombre d'autres options et variantes. En outre, outre la possibilité d'accéder à des fonctionnalités C++ à partir de QML, le module Qt Qml permet également de faire l'inverse et de manipuler des objets QML à partir de code C++. Voir Interagir avec les objets QML à partir de C++ pour plus de détails.

Il est souvent souhaitable d'exposer certains états sous forme de propriétés globales à QML. Exposer l'état de C++ à QML décrit comment le faire.

Le code C++ peut être intégré dans une application C++ ou dans un module QML autonome, selon qu'il doit être distribué en tant qu'application autonome ou en tant que bibliothèque. Un module QML peut contenir un plugin C++ qui peut alors être chargé dynamiquement par le moteur QML. Cela permet à une application d'utiliser des modules QML qui n'ont pas été liés au binaire.

Vous pouvez également créer manuellement des plugins autonomes. Voir Fournir des types et des fonctionnalités dans un plugin C++ pour plus d'informations. Cette méthode n'est pas recommandée.

Enfin, une instance de la classe peut être intégrée dans le code QML en tant que propriété de contexte ou objet de contexte, ce qui permet d'accéder aux propriétés, méthodes et signaux de l'instance à partir de QML. Les propriétés de contexte sont à éviter.

Choisir la bonne méthode d'intégration entre C++ et QML

Pour déterminer rapidement la méthode d'intégration qui convient à votre situation, vous pouvez utiliser l'organigramme suivant :

Pour une description des macros de l'organigramme, voir la documentation Defining QML Types from C++.

Exposition des attributs des classes C++ à QML

QML peut facilement être étendu à partir de C++ grâce à l'intégration du moteur QML avec le méta-système d'objets de Qt. Cette intégration permet aux propriétés, méthodes et signaux de toute classe dérivée de QObject d'être accessibles à partir de QML : les propriétés peuvent être lues et modifiées, les méthodes peuvent être invoquées à partir d'expressions JavaScript et des gestionnaires de signaux sont automatiquement créés pour les signaux si nécessaire. En outre, les valeurs d'énumération d'une classe dérivée de QObject sont accessibles à partir de QML.

Voir Exposer les attributs des types C++ à QML pour plus d'informations.

Définition des types QML à partir de C++

Les types QML peuvent être définis en C++, puis enregistrés dans le système de types QML. Cela permet à une classe C++ d'être instanciée en tant que type d'objet QML, ce qui permet de mettre en œuvre des types d'objets personnalisés en C++ et de les intégrer dans le code QML existant. Une classe C++ peut également être enregistrée à d'autres fins : par exemple, elle peut être enregistrée en tant que type Singleton pour permettre à une instance de classe unique d'être importée par le code QML, ou elle peut être enregistrée pour permettre aux valeurs d'énumération d'une classe non substantielle d'être accessibles à partir de QML.

En outre, le module Qt Qml fournit des mécanismes pour définir des types QML qui s'intègrent aux concepts QML tels que les propriétés attachées et les propriétés par défaut.

Pour plus d'informations sur l'enregistrement et la création de types QML personnalisés à partir de C++, voir la documentation Définir des types QML à partir de C++.

Intégration d'objets C++ dans QML à l'aide de propriétés contextuelles

Les objets et les valeurs C++ peuvent être intégrés directement dans le contexte (ou la portée) des objets QML chargés à l'aide de propriétés de contexte et d'objets de contexte. Cela est possible grâce à la classe QQmlContext fournie par le module Qt Qml qui expose des données au contexte d'un composant QML, ce qui permet d'injecter des données C++ dans QML.

Voir Embedding C++ Objects into QML with Context Properties pour plus d'informations.

Interagir avec des objets QML à partir de C++

Les types d'objets QML peuvent être instanciés à partir de C++ et inspectés afin d'accéder à leurs propriétés, d'invoquer leurs méthodes et de recevoir leurs notifications de signaux. Cela est possible car tous les types d'objets QML sont mis en œuvre à l'aide de classes dérivées de QObject, ce qui permet au moteur QML de charger et d'inspecter dynamiquement les objets par le biais du méta-système d'objets Qt.

Pour plus d'informations sur l'accès aux objets QML à partir de C++, voir la documentation Interagir avec les objets QML à partir de C++ et la section Exposer les données de C++ à QML de la page Meilleures pratiques.

Conversion des types de données entre QML et C++

Lorsque des valeurs de données sont échangées entre QML et C++, elles sont converties par le moteur QML afin d'avoir les types de données appropriés pour une utilisation à partir de QML ou de C++, à condition que les types de données concernés soient connus du moteur.

Voir Conversion des types de données entre QML et C++ pour plus d'informations sur les types intégrés pris en charge par le moteur et sur la manière dont ces types sont convertis pour être utilisés lors des échanges entre QML et C++.