Erstellen eines wiederverwendbaren QML-Moduls

Das folgende Beispiel zeigt, wie eine Bibliothek erstellt wird, die C++ für QML zugänglich macht. Die Verzeichnisstruktur für das Beispiel sieht wie folgt aus:

├── CMakeLists.txt
└── example
    └── mylib
        ├── CMakeLists.txt
        ├── mytype.cpp
        ├── mytype.h

Die Toplevel-Datei CMakeLists.txt nimmt einige grundlegende Einstellungen mit qt_standard_project_setup vor und verwendet dann add_subdirectory, um die Datei in mylib einzubinden:

cmake_minimum_required(VERSION 3.16)

project(qmlmodule VERSION 1.0.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Qt6 REQUIRED COMPONENTS Qml)
qt_standard_project_setup(REQUIRES 6.5)

add_subdirectory(example/mylib)

Die Unterverzeichnisse sind so strukturiert, dass sie der URI des QML-Moduls entsprechen, wobei die Punkte durch Schrägstriche ersetzt sind. Das ist die gleiche Logik, die die Maschine verwendet, wenn sie in den Importpfaden nach einem Modul sucht. Das Befolgen dieser Unterverzeichnisstruktur hilft beim Tooling.

mytype.h deklariert eine Klasse und verwendet die deklarativen Registrierungsmakros, um sie der Engine zugänglich zu machen.

Im CMakeLists.txt des Unterverzeichnisses rufen wir qt_add_qml_module auf. Im Vergleich zum Erstellen einer QML-Anwendung ist der Aufruf etwas anders:

qt_add_qml_module(mylib
    URI example.mylib
    VERSION 1.0
    SOURCES
        mytype.h mytype.cpp
    QML_FILES
        MyQmlType.qml
)

Das Ziel für mylib wurde noch nicht erstellt. Wenn das Ziel, das an qt6_add_qml_module übergeben wird, nicht existiert, wird automatisch ein Bibliotheksziel erstellt. Dies vermeidet einen separaten Aufruf von qt_add_library. Um in C++ definierte QML-Typen zu registrieren, fügen Sie deren Header- und Quelldateien als Argumente zum SOURCES-Parameter hinzu.

Wenn das Projekt erstellt wird, wird zusätzlich zur Bibliothek auch ein QML-Plugin erstellt. Die automatisch generierte Klasse des Plugins wird von QQmlEngineExtensionPlugin erweitert. Die mylib-Bibliothek selbst enthält bereits den Code zur Registrierung der Typen bei der Engine. Dies ist jedoch nur in Fällen nützlich, in denen wir gegen die Bibliothek linken können. Um das Modul in einer QML-Datei nutzbar zu machen, die von qml, dem QML Runtime Tool, geladen wird, ist ein Plugin erforderlich, das geladen werden kann. Das Plugin ist dann für die eigentliche Verknüpfung mit der Bibliothek verantwortlich und sorgt dafür, dass die Typen registriert werden.

Beachten Sie, dass die automatische Plugin-Generierung nur möglich ist, wenn das Modul nichts anderes tut als die Typen zu registrieren. Wenn es etwas Anspruchsvolleres tun muss, wie z.B. die Registrierung eines Bildanbieters in initializeEngine, müssen Sie das Plugin immer noch manuell schreiben. qt6_add_qml_module unterstützt dies mit NO_GENERATE_PLUGIN_SOURCE.

Auch das Befolgen der Verzeichnis-Layout-Konvention hilft beim Tooling. Dieses Layout wird im Build-Verzeichnis widergespiegelt. Das bedeutet, dass Sie dem QML-Tool den Pfad zu Ihrem Build-Verzeichnis übergeben können (über das -I -Flag), und es wird das Plugin finden.