Portage des modules QML vers CMake

Les modules Qml sont désormais plus puissants et plus faciles à utiliser dans Qt 6. Les sections suivantes décrivent comment porter des modules Qml vers l'API CMake qt_add_qml_module.

Voir également Modernisation des modules QML pour savoir comment moderniser un module QML qui utilise déjà qt_add_qml_module.

Identifier les problèmes à corriger

Utilisez qmllint pour vous aider tout au long du processus.

Chaque module QML défini avec `qt_add_qml_module` dispose d’une cible CMake ` _qmllint ` que vous pouvez utiliser pour identifier les problèmes potentiels ou les améliorations possibles. Pour un module QML nommé ` MyQmlLibrary `, utilisez par exemple ` MyQmlLibrary_qmllint`. Pour exécuter `qmllint` sur tous les modules QML, utilisez ` all_qmllint`.

Les catégories d’avertissements de qmllint qui indiquent des problèmes dans les modules QML sont les suivantes :

• [import]
• [unused-imports]
• [unresolved-type]
• [alias non résolu]
• [entrée-d'énumération-manquante]
• [propriété manquante]
• [type manquant]

Préparez le projet pour qt_add_qml_module

Rendre qt_add_qml_module disponible dans CMake

Pour rendre qt_add_qml_module disponible dans CMake, ajoutez Core et Qml à votre appel à find_package dans le fichier d'CMakeLists.txt e de niveau supérieur du projet :

find_package(Qt6 REQUIRED COMPONENTS Core Qml)

Utilisez qt_standard_project_setup

qt_standard_project_setup configure, entre autres, les règles CMake Qt nécessaires à qt_add_qml_module.

Appelez qt_standard_project_setup dans le fichier CMakeLists.txt situé au niveau racine du projet avant tout appel à qt_add_qml_module:

qt_standard_project_setup(REQUIRES 6.8)

Utilisation de qt_add_qml_module

qt_add_qml_module est la fonction CMake chargée de générer les modules QML. Elle génère automatiquement les fichiers qmldir et qmltypes, et configure des outils tels que qmlcachegen ou qmllint.

Les modules QML peuvent être ajoutés à la fois aux cibles « exécutables » et aux cibles « bibliothèques » dans CMake. Les modules QML associés à une cible « exécutable » ne peuvent pas être utilisés ni liés par d’autres exécutables, contrairement à ceux associés à une cible « bibliothèque ».

Ajouter un module QML à votre cible exécutable

Dans ce cas, les fichiers source du module QML sont traités comme faisant partie intégrante de l’exécutable lui-même, plutôt que d’être compilés dans une bibliothèque distincte. Cela signifie qu’aucun module ni aucune bibliothèque de plug-ins n’est créé pour ce module : celui-ci est entièrement intégré à l’exécutable. Par conséquent, le module est lié à ce programme spécifique et ne peut pas être réutilisé par d’autres exécutables ou bibliothèques.

Pour ajouter un module QML à votre exécutable, dans votre fichier ` 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
)

L’ Main.qml doit commencer par une majuscule afin de pouvoir être instancié par des méthodes d’ loadFromModule telles que QQmlApplicationEngine::loadFromModule ou QQmlComponent::loadFromModule. De plus, l’URI du module QML doit être différent du nom de la cible afin d’éviter tout conflit de noms dans le dossier de compilation.

Ajouter un module QML à votre cible de bibliothèque

Pour ajouter un module QML à votre bibliothèque, dans votre fichier ` 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 crée une bibliothèque « SHARED » via qt_add_library si la cible « MyQmlLibrary » n’existe pas encore, comme dans cet exemple.

Utilisez `loadFromModule` pour charger vos fichiers QML

Utilisez ` loadFromModule ` pour charger votre fichier QML, par exemple :

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

Supprimez les fichiers `qmldir` créés manuellement

qt_add_qml_module génère automatiquement des fichiers ` qmldir `. Si votre ` qmldir` contient des singletons, déclarez-les dans votre ` CMakeLists.txt ` avant l’appel à ` qt_add_qml_module ` à l’aide de :

set_source_files_properties(MySingleton.qml PROPERTIES QT_QML_SINGLETON_TYPE TRUE)

Supprimez ensuite les fichiers ` qmldir ` créés manuellement.

Supprimez les fichiers qmltypes générés par qmlplugindump

qt_add_qml_module génère automatiquement des fichiers « qmltypes » lorsque tous vos types utilisent l’enregistrement déclaratif des types, ce qui rend inutile la génération manuelle de fichiers « qmltypes » à l’aide d’outils tels que qmlplugindump.

Pour ce faire, supprimez les appels manuels à ` qmlRegisterType ` et à ses variantes. Ensuite, enregistrez vos types de manière déclarative à l’aide de ` QML_ELEMENT`, par exemple :

// 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
    ....
};

Consultez la section « Enregistrement des types C++ avec le système de types QML » pour savoir comment gérer des cas d’enregistrement plus complexes, tels que l’enregistrement de types externes.

Supprimez ensuite les fichiers « qmltypes » créés manuellement.

Supprimez les plugins d’enregistrement de types créés manuellement

qt_add_qml_module peut générer automatiquement un plugin de module QML pour vous. Vous n'avez pas besoin d'un plugin écrit manuellement si la seule tâche de votre plugin est d'effectuer l'enregistrement des types. Supprimez complètement le plugin si le passage à l'enregistrement déclaratif des types a bien supprimé tout le code de votre plugin.

Veillez à supprimer les arguments NO_PLUGIN, NO_PLUGIN_OPTIONAL, NO_CREATE_PLUGIN_TARGET et NO_GENERATE_PLUGIN_SOURCE de qt_add_qml_module afin de permettre la génération automatique du plugin.

Supprimer les fichiers qrc

qt_add_qml_module génère automatiquement des fichiers qrc. Pour répertorier les ressources dans les fichiers qrc, telles que des images ou des fichiers audio, ajoutez-les à l’argument RESOURCES de qt_add_qml_module. Vous trouverez les ressources du module sous :/qt/qml/MyQmlLibraryModule/.

Remplacer les importations de répertoires par des importations de modules QML

Remplacez les importations de répertoires par des importations de modules QML. Par exemple,

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

SomeType {
    ...
}

Notez que les fichiers contenus dans un module QML importent automatiquement leur propre module QML. Vous pouvez supprimer ces auto-importations.