Portierung von QML-Modulen auf CMake

Qt Qml-Module sind in Qt 6 leistungsfähiger und benutzerfreundlicher geworden. In den folgenden Abschnitten wird beschrieben, wie Qml-Module auf die CMake-API `qt_add_qml_module ` portiert werden.

Siehe auch „Modernisierung von QML-Modulen“ für Informationen zur Modernisierung eines QML-Moduls, das bereits „qt_add_qml_module“ verwendet.

Identifizieren Sie zu behebende Probleme

Verwenden Sie „qmllint“, um Sie bei diesem Prozess zu unterstützen.

Jedes mit „qt_add_qml_module“ definierte QML-Modul verfügt über ein CMake-Ziel „ _qmllint “, mit dem Sie potenzielle Probleme oder Verbesserungsmöglichkeiten identifizieren können. Für ein QML-Modul namens „ MyQmlLibrary “ verwenden Sie beispielsweise „ MyQmlLibrary_qmllint “. Um „qmllint“ für alle QML-Module auszuführen, verwenden Sie „ all_qmllint “.

Die Warnkategorien von qmllint, die auf Probleme in QML-Modulen hinweisen, sind:

• [import]
• [unused-imports]
• [unresolved-type]
• [unresolved-alias]
• [fehlender-Enum-Eintrag]
• [fehlende-Eigenschaft]
• [fehlender-Typ]

Bereiten Sie das Projekt für „qt_add_qml_module“ vor

qt_add_qml_module in CMake verfügbar machen

Um `qt_add_qml_module` in CMake verfügbar zu machen, fügen Sie ` Core ` und ` Qml ` zu Ihrem ` find_package `-Aufruf in der obersten ` CMakeLists.txt `-Datei des Projekts hinzu:

find_package(Qt6 REQUIRED COMPONENTS Core Qml)

Verwenden Sie `qt_standard_project_setup`

qt_standard_project_setup richtet unter anderem die für qt_add_qml_module erforderlichen Qt-CMake-Richtlinien ein.

Rufen Sie `qt_standard_project_setup` in der obersten ` CMakeLists.txt `-Datei des Projekts vor jedem Aufruf von ` qt_add_qml_module ` auf:

qt_standard_project_setup(REQUIRES 6.8)

Verwenden Sie `qt_add_qml_module`

`qt_add_qml_module` ist die CMake-Funktion, die für die Generierung von QML-Modulen zuständig ist. Sie generiert automatisch die Dateien ` qmldir ` und ` qmltypes ` und richtet Tools wie `qmlcachegen ` oder `qmllint` ein.

QML-Module können in CMake sowohl zu ausführbaren Zielen als auch zu Bibliothekszielen hinzugefügt werden. QML-Module, die an ein ausführbares Ziel angehängt sind, können nicht von anderen ausführbaren Programmen verwendet oder eingebunden werden, während dies bei QML-Modulen, die an Bibliotheksziele angehängt sind, möglich ist.

Fügen Sie Ihrem ausführbaren Ziel ein QML-Modul hinzu

In diesem Fall werden die Quelldateien des QML-Moduls als Teil der ausführbaren Datei selbst behandelt und nicht zu einer separaten Bibliothek kompiliert. Das bedeutet, dass weder ein Modul noch eine Plugin-Bibliothek für dieses Modul erstellt wird – das Modul ist vollständig in die ausführbare Datei integriert. Infolgedessen ist das Modul an dieses bestimmte Programm gebunden und kann nicht von anderen ausführbaren Dateien oder Bibliotheken wiederverwendet werden.

Um ein QML-Modul zu Ihrer ausführbaren Datei hinzuzufügen, gehen Sie in Ihrer Datei „ CMakeLists.txt “ wie folgt vor:

# 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
)

Der „ Main.qml “ sollte mit einem Großbuchstaben beginnen, damit er von „ loadFromModule “-Methoden wie „ QQmlApplicationEngine::loadFromModule “ oder „ QQmlComponent::loadFromModule “ instanziiert werden kann. Außerdem sollte sich die QML-Modul-URI vom Zielnamen unterscheiden, um Namenskonflikte im Build-Ordner zu vermeiden.

Fügen Sie Ihrer Bibliothek ein QML-Modul hinzu

Um ein QML-Modul zu Ihrer Bibliothek hinzuzufügen, fügen Sie in Ihrer Datei „ CMakeLists.txt “ Folgendes ein:

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` erstellt über `qt_add_library` eine Bibliothek „ SHARED “, falls das Ziel „ MyQmlLibrary “ noch nicht existiert, wie in diesem Beispiel.

Verwenden Sie `loadFromModule`, um Ihre QML-Dateien zu laden

Verwenden Sie ` loadFromModule `, um Ihre QML-Datei zu laden, zum Beispiel:

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

Entfernen Sie manuell erstellte `qmldir`-Dateien

„qt_add_qml_module“ generiert automatisch „ qmldir “-Dateien. Wenn Ihr „ qmldir “ Singletons enthält, deklarieren Sie diese in Ihrer „ CMakeLists.txt “-Datei vor dem Aufruf von „qt_add_qml_module“ wie folgt:

set_source_files_properties(MySingleton.qml PROPERTIES QT_QML_SINGLETON_TYPE TRUE)

Löschen Sie anschließend die manuell erstellten „ qmldir “-Dateien.

Entfernen Sie die von `qt_plugindump` generierten `qmltypes`-Dateien

„qt_add_qml_module“ generiert automatisch „ qmltypes “-Dateien, wenn alle Ihre Typen die deklarative Typregistrierung verwenden. Dadurch entfällt die Notwendigkeit, „ qmltypes “-Dateien manuell mit Tools wie „ qmlplugindump “ zu erstellen.

Um dies zu erreichen, entfernen Sie manuelle Aufrufe von ` qmlRegisterType ` und dessen Varianten. Registrieren Sie Ihre Typen anschließend deklarativ mithilfe von ` QML_ELEMENT`, zum Beispiel:

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

Informationen zur Handhabung komplexerer Registrierungsfälle wie der Registrierung fremder Typen finden Sie unter „Registrierung von C++-Typen im QML-Typsystem “.

Löschen Sie anschließend die manuell erstellten „ qmltypes “-Dateien.

Entfernen Sie manuell erstellte Plugins zur Typregistrierung

„qt_add_qml_module“ kann automatisch ein QML-Modul-Plugin für Sie generieren. Sie benötigen kein manuell erstelltes Plugin, wenn die einzige Aufgabe Ihres Plugins darin besteht, die Typregistrierung durchzuführen. Entfernen Sie das Plugin vollständig, wenn durch die Umstellung auf die deklarative Typregistrierung der gesamte Code aus Ihrem Plugin entfernt wurde.

Stellen Sie sicher, dass Sie die Argumente „ NO_PLUGIN “, „ NO_PLUGIN_OPTIONAL “, „ NO_CREATE_PLUGIN_TARGET “ und „ NO_GENERATE_PLUGIN_SOURCE “ aus „qt_add_qml_module“ entfernen, um die automatische Plugin-Generierung zu ermöglichen.

qrc-Dateien entfernen

qt_add_qml_module generiert automatisch „ qrc “-Dateien. Um Ressourcen in den „ qrc “-Dateien aufzulisten, wie z. B. Bilder oder Audiodateien, fügen Sie diese dem Argument „ RESOURCES “ von qt_add_qml_module hinzu. Sie finden die Ressourcen des Moduls unter „ :/qt/qml/MyQmlLibraryModule/ “.

Ersetzen Sie Verzeichnisimporte durch QML-Modulimporte

Ersetzen Sie Verzeichnisimporte durch QML-Modulimporte. Zum Beispiel:

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

SomeType {
    ...
}

Beachten Sie, dass Dateien innerhalb eines QML-Moduls automatisch ihr eigenes QML-Modul importieren. Sie können die Selbstimporte entfernen.