Présentation - Intégration de QML et C++

QML est conçu pour être facilement extensible via du code C++. Les classes du Qt Qml module 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 depuis QML. Cela permet le développement d’applications hybrides implémentées à l’aide d’un mélange de code QML, JavaScript et C++.

L’intégration de QML et du C++ offre de nombreuses possibilités, notamment la capacité de :

• Séparer le code de l’interface utilisateur du code de la logique d’application, en implémentant le premier avec QML et JavaScript au sein de documents QML, et le second avec du C++
• Utiliser et appeler certaines fonctionnalités C++ depuis QML (par exemple, pour invoquer la logique de votre application, utiliser un modèle de données implémenté en C++ ou appeler certaines fonctions d’une bibliothèque C++ tierce)
• Accéder aux fonctionnalités du Qt Qml ou Qt Quick API C++ (par exemple, pour générer dynamiquement des images à l’aide de ` QQuickImageProvider`)
• Implémentez vos propres types d’objets QML à partir de C++ — que ce soit pour les utiliser au sein de votre application spécifique ou pour les distribuer à d’autres

Pour fournir des données ou des fonctionnalités C++ à QML, celles-ci doivent être rendues accessibles via une classe dérivée de ` QObject`. Grâce à l’intégration du moteur QML au système de méta-objets, les propriétés, méthodes et signaux de toute classe dérivée de ` QObject` sont accessibles depuis QML, comme décrit dans la section « Exposition des 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 » afin qu’une seule instance de la classe puisse être importée depuis le code QML, ce qui permet d’accéder aux propriétés, méthodes et signaux de cette instance depuis QML

Ce sont les méthodes les plus courantes pour accéder aux fonctionnalités C++ à partir du code QML. Les modules « QML Type Registration Macros » offrent un certain nombre d’autres options et variantes. De plus, outre la possibilité d’accéder aux fonctionnalités C++ depuis QML, le Qt Qml module propose également des moyens de faire l'inverse et de manipuler des objets QML depuis du code C++. Voir Interagir avec des objets QML depuis le C++ pour plus de détails.

Il est souvent souhaitable d’exposer certains états sous forme de propriétés globales à QML. La section « Exposition d’un état depuis le C++ vers QML » décrit comment procéder.

Le code C++ peut être intégré soit dans une application C++, soit dans un module QML autonome, selon qu’il doit être distribué sous forme d’application autonome ou de bibliothèque. Un module QML peut contenir un plugin C++ qui peut ensuite ê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. Reportez-vous à la section « Fournir des types et des fonctionnalités dans un plugin C++ » pour plus d’informations. Cette approche n’est toutefois pas recommandée.

Enfin, une instance de la classe peut être intégrée dans du 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 depuis QML. L’utilisation des propriétés de contexte est à éviter.

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

Pour déterminer rapidement quelle méthode d’intégration est adaptée à votre situation, vous pouvez utiliser l’organigramme suivant :

Pour une description des macros du diagramme, consultez la documentation « Définition de types QML à partir de C++ ».

Exposition des attributs des classes C++ vers QML

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

Voir Exposition des attributs des types C++ vers QML pour plus d’informations.

Définition de 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 d’instancier une classe C++ en tant que type d’objet QML, ce qui permet d’implémenter des types d’objets personnalisés en C++ et de les intégrer dans du 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 afin de permettre l’importation d’une instance unique de la classe par du code QML, ou encore pour rendre accessibles depuis QML les valeurs d’énumération d’une classe non instanciable.

De plus, le Qt Qml module fournit des mécanismes permettant de définir des types QML qui s’intègrent aux concepts QML tels que les propriétés associé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++, consultez la documentation « Définition de types QML à partir de C++ ».

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

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

Voir Intégration d’objets C++ dans QML à l’aide des propriétés de contexte pour plus d’informations.

Interaction avec les objets QML depuis le C++

Les types d’objets QML peuvent être instanciés depuis le C++ et inspectés afin d’accéder à leurs propriétés, d’appeler leurs méthodes et de recevoir leurs notifications de signaux. Cela est possible car tous les types d’objets QML sont implémentés à l’aide de classes dérivées de ` QObject`, ce qui permet au moteur QML de charger dynamiquement et d’introsecter des objets via le système de méta-objets Qt.

Pour plus d’informations sur l’accès aux objets QML depuis le C++, consultez la documentation intitulée « Interagir avec les objets QML depuis le C++ », ainsi que la section « Exposer des données du C++ vers le 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’adopter les types de données appropriés pour une utilisation en QML ou en C++, à condition que les types de données concernés soient reconnus par le moteur.

Consultez la section « Conversion des types de données entre QML et C++ » pour obtenir des 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 d’échanges entre QML et C++.