Porter les modules QML vers CMake

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

Voir aussi Moderniser les 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 possède une cible CMake _qmllint que vous pouvez utiliser pour identifier les problèmes potentiels ou les améliorations. Pour un module QML appelé MyQmlLibrary, utilisez MyQmlLibrary_qmllint, par exemple. Pour exécuter qmllint sur tous les modules QML, utilisez all_qmllint.

Les catégories d'avertissement de qmllint qui indiquent des problèmes liés aux modules QML sont les suivantes :

• [import]
• [unused-imports]
• [unresolved-type]
• [alias non résolu]
• [missing-enum-entry] [missing-property]
• [missing-property] [missing-type] [missing-entry] [missing-enum-entry]
• [missing-type]

Préparer 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 de premier niveau CMakeLists.txt du projet :

find_package(Qt6 REQUIRED COMPONENTS Core Qml)

Utiliser qt_standard_project_setup

qt_standard_project_setup met en place les politiques Qt CMake nécessaires pour qt_add_qml_module, entre autres choses.

Appeler qt_standard_project_setup dans le fichier de premier niveau du projet CMakeLists.txt avant tout appel à qt_add_qml_module:

qt_standard_project_setup(REQUIRES 6.8)

Utiliser qt_add_qml_module

qt_add_qml_module est la fonction CMake qui se charge de générer les modules QML. Elle génère automatiquement les fichiers qmldir et qmltypes, et met en place des outils comme qmlcachegen ou qmllint.

Les modules QML peuvent être ajoutés aux cibles exécutables et bibliothèques dans CMake. Les modules QML attachés à la cible exécutable ne peuvent pas être utilisés ou liés par d'autres exécutables, alors que les modules QML attachés aux cibles bibliothèques peuvent l'être.

Ajouter un module QML à votre cible exécutable

Dans ce cas, les fichiers sources du module QML sont traités comme faisant partie de l'exécutable lui-même, plutôt que d'être compilés dans une bibliothèque séparée. Cela signifie que ni un module ni une bibliothèque de plugins pour ce module ne sont créés - le module est entièrement intégré dans 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 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'adresse Main.qml doit commencer par une lettre majuscule afin qu'elle puisse être instanciée par les méthodes loadFromModule comme QQmlApplicationEngine::loadFromModule ou QQmlComponent::loadFromModule. De plus, l'URI du module QML doit être différent du nom de la cible afin d'éviter les conflits de noms dans le dossier de construction.

Ajouter un module QML à la cible de votre bibliothèque

Pour ajouter un module QML à votre bibliothèque, dans votre 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");

Supprimer les fichiers qmldir écrits à la main

qt_add_qml_module génère automatiquement des fichiers qmldir. Si vous avez des singletons dans votre qmldir, déclarez-les dans votre CMakeLists.txt avant l'appel de qt_add_qml_module avec :

set_source_files_properties(MySingleton.qml PROPERTIES QT_QML_SINGLETON_TYPE TRUE)

Supprimez ensuite le qmldir écrit à la main.

Supprimer 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 élimine le besoin de générer des fichiers qmltypes à la main à l'aide d'outils comme qmlplugindump.

Pour ce faire, supprimez les appels manuels à qmlRegisterType et à ses variantes. Ensuite, enregistrez vos types de manière déclarative en utilisant 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
    ....
};

Voir Enregistrer des types C++ avec le système de types QML pour savoir comment gérer des cas d'enregistrement plus compliqués comme l'enregistrement de types étrangers.

Supprimez ensuite les fichiers qmltypes écrits à la main.

Supprimer les plugins d'enregistrement de types manuscrits

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

Assurez-vous de supprimer les arguments NO_PLUGIN, NO_PLUGIN_OPTIONAL, NO_CREATE_PLUGIN_TARGET, et NO_GENERATE_PLUGIN_SOURCE de qt_add_qml_module pour permettre la génération automatique du plugin.

Supprimer les fichiers qrc

qt_add_qml_module génère automatiquement des fichiers qrc. Pour lister les ressources dans les fichiers qrc, comme les images ou les fichiers son, ajoutez-les à l'argument RESOURCES de qt_add_qml_module. Vous pouvez trouver les ressources du module à l'adresse :/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, les fichiers à l'intérieur d'un module QML ne sont pas importés,

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

SomeType {
    ...
}

Notez que les fichiers à l'intérieur d'un module QML importent automatiquement leur propre module QML. Vous pouvez supprimer les importations automatiques.