Moduldefinitionsdateien „qmldir“

Es gibt zwei verschiedene Arten von „ qmldir “-Dateien:

• Dateien zur Auflistung des QML-Dokumentverzeichnisses
• QML-Moduldefinitionsdateien

Diese Dokumentation behandelt ausschließlich die zweite Form der „ qmldir “-Datei, die die unter einem Modul verfügbaren QML-Typen, JavaScript-Dateien und Plugins auflistet. Weitere Informationen zur ersten Form der „ qmldir “-Datei finden Sie unter Verzeichnisauflistungs-qmldir-Dateien.

Inhalt einer qmldir-Datei zur Moduldefinition

Eine „ qmldir “-Datei ist eine Klartextdatei, die die folgenden Befehle enthält:

• Deklaration des Modul-Identifikators
• Deklaration des Objekttyps
• Deklaration eines internen Objekttyps
• Deklaration von JavaScript-Ressourcen
• Plugin-Deklaration
• Deklaration des Plugin-Klassennamens
• Deklaration der Typbeschreibungsdatei
• Deklaration von Modulabhängigkeiten
• Modul-Import-Deklaration
• Deklaration der Designer-Unterstützung
• Deklaration des bevorzugten Pfads

Zusätzlich zu den Befehlen können Sie auch Kommentare hinzufügen, d. h. Zeilen, die mit „ # “ beginnen.

Deklaration des Modulbezeichners

module <ModuleIdentifier>

Deklariert die Modulkennung des Moduls. <ModuleIdentifier> ist die Kennung (in gepunkteter URI-Notation) für das Modul, die mit dem Installationspfad des Moduls übereinstimmen muss.

Die Modulbezeichner-Anweisung muss die erste Zeile der Datei sein. In der Datei „ qmldir “ darf genau eine Modulbezeichner-Anweisung vorhanden sein.

Beispiel:

module ExampleModule

Objekttyp-Deklaration

[singleton] <TypeName> <InitialVersion> <File>

Deklariert einen QML-Objekttyp, der vom Modul bereitgestellt werden soll.

• [singleton] Optional. Wird verwendet, um einen Singleton-Typ zu deklarieren.
• <TypeName> ist der zur Verfügung gestellte Typ
• <InitialVersion> ist die Modulversion, für die der Typ bereitgestellt werden soll
• <File> ist der (relative) Dateiname der QML-Datei, die den Typ definiert

In der Datei „ qmldir “ dürfen null oder mehr Objekttyp-Deklarationen vorhanden sein. Jeder Objekttyp muss jedoch innerhalb einer bestimmten Version des Moduls einen eindeutigen Typnamen haben.

Beispiel:

//Style.qml with custom singleton type definition
pragma Singleton
import QtQuick 2.0

QtObject {
    property int textSize: 20
    property color textColor: "green"
}

// qmldir declaring the singleton type
module CustomStyles
singleton Style 1.0 Style.qml

// singleton type in use
import QtQuick 2.0
import CustomStyles 1.0

Text {
    font.pixelSize: Style.textSize
    color: Style.textColor
    text: "Hello World"
}

Deklaration eines internen Objekttyps

internal <TypeName> <File>

Deklariert einen Objekttyp, der sich im Modul befindet, aber den Benutzern des Moduls nicht zur Verfügung gestellt werden soll.

In der Datei „ qmldir “ dürfen null oder mehr interne Objekttyp-Deklarationen vorhanden sein.

Beispiel:

internal MyPrivateType MyPrivateType.qml

Dies ist erforderlich, wenn das Modul remote importiert wird (siehe „Remote installierte identifizierte Module“), da die Engine, falls ein exportierter Typ von einem nicht exportierten Typ innerhalb des Moduls abhängt, auch den nicht exportierten Typ laden muss.

JavaScript-Ressourcendeklaration

<ResourceIdentifier> <InitialVersion> <File>

Deklariert eine JavaScript-Datei, die vom Modul bereitgestellt werden soll. Die Ressource wird über den angegebenen Bezeichner mit der angegebenen Versionsnummer bereitgestellt.

In der Datei „ qmldir “ dürfen null oder mehr JavaScript-Ressourcendeklarationen vorhanden sein. Jede JavaScript-Ressource muss jedoch innerhalb einer bestimmten Version des Moduls einen eindeutigen Bezeichner haben.

Beispiel:

MyScript 1.0 MyScript.js

Weitere Informationen finden Sie in der Dokumentation zum Definieren von JavaScript-Ressourcen und zum Importieren von JavaScript-Ressourcen in QML.

Plugin-Deklaration

[optional] plugin <Name> [<Path>]

Deklariert ein Plugin, das vom Modul bereitgestellt werden soll.

• optional bedeutet, dass das Plugin selbst keinen relevanten Code enthält und lediglich dazu dient, eine Bibliothek zu laden, auf die es verweist. Wenn dieser Parameter angegeben wird und bereits Typen für das Modul verfügbar sind – was darauf hindeutet, dass die Bibliothek auf andere Weise geladen wurde –, lädt QML das Plugin nicht.
• <Name> ist der Name der Plugin-Bibliothek. Dieser entspricht in der Regel nicht dem Dateinamen der Plugin-Binärdatei, da dieser plattformabhängig ist. Beispielsweise würde die Bibliothek „ MyAppTypes “ unter Linux die Datei „ libMyAppTypes.so “ und unter Windows die Datei „ MyAppTypes.dll “ erzeugen.
• <Path> (optional) gibt entweder Folgendes an:
  • einen absoluten Pfad zu dem Verzeichnis, das die Plugin-Datei enthält, oder
  • einen relativen Pfad vom Verzeichnis, das die Datei „ qmldir “ enthält, zum Verzeichnis, das die Plugin-Datei enthält.

Standardmäßig sucht die Engine nach der Plugin-Bibliothek in dem Verzeichnis, das die Datei „ qmldir “ enthält. (Der Suchpfad für Plugins kann mit ` QQmlEngine::pluginPathList()` abgefragt und mit ` QQmlEngine::addPluginPath()` geändert werden.)

In der Datei „ qmldir “ dürfen null oder mehr C++-Plugin-Deklarationen vorhanden sein. Da das Laden von Plugins jedoch relativ ressourcenintensiv ist, wird empfohlen, höchstens ein einziges Plugin anzugeben.

Beispiel:

plugin MyPluginLibrary

Deklaration des Plugin-Klassennamens

classname <C++ plugin class>

Gibt den Klassennamen des vom Modul verwendeten C++-Plugins an.

Diese Angabe ist für alle QML-Module erforderlich, die für zusätzliche Funktionalität auf ein C++-Plugin angewiesen sind. Mit statischer Verknüpfung erstellte „ Qt Quick “-Anwendungen können die Modulimporte ohne diese Angabe nicht auflösen.

Deklaration der Typbeschreibungsdatei

typeinfo <File>

Deklariert eine Typbeschreibungsdatei für das Modul, die von QML-Tools wie Qt Creator , um auf Informationen zu den von den Plugins des Moduls definierten Typen zuzugreifen. „ <File> “ ist der (relative) Dateiname einer „ .qmltypes “-Datei.

Beispiel:

typeinfo mymodule.qmltypes

Ohne eine solche Datei können QML-Tools möglicherweise keine Funktionen wie die Code-Vervollständigung für die in Ihren Plugins definierten Typen anbieten.

Deklaration von Modulabhängigkeiten

depends <ModuleIdentifier> <InitialVersion>

Deklariert, dass dieses Modul von einem anderen Modul abhängt.

Beispiel:

depends MyOtherModule 1.0

Diese Deklaration ist nur in Fällen erforderlich, in denen die Abhängigkeit verborgen ist: beispielsweise wenn der C++-Code eines Moduls verwendet wird, um QML (möglicherweise bedingt) zu laden, das dann von anderen Modulen abhängt. In solchen Fällen ist die Deklaration „ depends “ erforderlich, um die anderen Module in Anwendungspakete einzubinden.

Deklaration des Modulimports

import <ModuleIdentifier> [<Version>]

Deklariert, dass dieses Modul ein anderes importiert.

Beispiel:

import MyOtherModule 1.0

Die Typen aus dem anderen Modul werden im selben Typ-Namespace zur Verfügung gestellt, in den dieses Modul importiert wird. Wird die Versionsangabe weggelassen, wird die neueste verfügbare Version des anderen Moduls importiert. Durch die Angabe von „ auto “ als Version wird dieselbe Version importiert wie die in der QML-Anweisung „ import “ angegebene Version dieses Moduls.

Erklärung zur Designer-Unterstützung

designersupported

Setzen Sie diese Eigenschaft, wenn das Plugin vom Qt Quick Designer unterstützt wird. Standardmäßig wird das Plugin nicht unterstützt.

Ein vom „ Qt Quick Designer“ unterstütztes Plugin muss ordnungsgemäß getestet worden sein. Das bedeutet, dass das Plugin nicht abstürzt, wenn es innerhalb des „qml2puppet“ ausgeführt wird, das vom „ Qt Quick Designer“ zur Ausführung von QML verwendet wird. Im Allgemeinen sollte das Plugin im „ Qt Quick “-Designer einwandfrei funktionieren und keine schwerwiegenden Probleme verursachen, wie z. B. übermäßigen Speicherverbrauch, eine erhebliche Verlangsamung von „qml2puppet“ oder andere Probleme, die das Plugin im „ Qt Quick “-Designer praktisch unbrauchbar machen.

Die Elemente eines nicht unterstützten Plugins werden im „ Qt Quick “-Designer nicht dargestellt, sind jedoch weiterhin als leere Felder verfügbar, und die Eigenschaften können bearbeitet werden.

Deklaration des bevorzugten Pfads

prefer <Path>

Diese Eigenschaft weist die QML-Engine an, weitere Dateien für dieses Modul aus <path> statt aus dem aktuellen Verzeichnis zu laden. Dies kann genutzt werden, um mit qmlcachegen kompilierte Dateien zu laden.

Sie können beispielsweise die QML-Dateien eines Moduls als Ressourcen zu einem Ressourcenpfad im „ :/my/path/MyModule/ “ hinzufügen. Fügen Sie anschließend „ prefer :/my/path/MyModule “ zur Datei „qmldir“ hinzu, um die Dateien im Ressourcensystem anstelle derjenigen im Dateisystem zu verwenden. Wenn Sie anschließend qmlcachegen für diese Dateien verwenden, stehen die vorkompilierten Dateien allen Clients des Moduls zur Verfügung.

Versionssemantik

Alle QML-Typen, die für eine bestimmte Hauptversion exportiert werden, stehen in der neuesten Version derselben Hauptversion zur Verfügung. Wenn ein Modul beispielsweise den Typ „ MyButton “ in Version 1.0 und den Typ „ MyWindow “ in Version 1.1 bereitstellt, können Clients, die die Version „ 1.1 “ des Moduls importieren, die Typen „ MyButton “ und „ MyWindow “ verwenden. Das Gegenteil trifft jedoch nicht zu: Ein für eine bestimmte Nebenversion exportierter Typ kann nicht durch den Import einer älteren oder früheren Nebenversion verwendet werden. Hätte der Client im zuvor genannten Beispiel die Version 1.0 des Moduls importiert, könnte er nur den Typ „ MyButton “ verwenden, nicht jedoch den Typ „ MyWindow “.

Ein Modul kann mehrere Hauptversionen anbieten, doch die Clients haben jeweils nur Zugriff auf eine Hauptversion. Der Import von „ MyExampleModule 2.0 “ gewährt beispielsweise nur Zugriff auf diese Hauptversion und nicht auf die vorherige Hauptversion. Obwohl Sie die Artefakte, die zu verschiedenen Hauptversionen gehören, unter einem einzigen Verzeichnis und einer „ qmldir “-Datei organisieren können, wird empfohlen, für jede Hauptversion separate Verzeichnisse zu verwenden. Wenn Sie sich für den erstgenannten Ansatz entscheiden (ein Verzeichnis und eine „ qmldir “-Datei), sollten Sie versuchen, das Versionssuffix in den Dateinamen zu verwenden. Beispielsweise können Artefakte, die zu „ MyExampleModule 2.0 “ gehören, das Suffix „ .2 “ in ihrem Dateinamen verwenden.

Eine Version kann nicht importiert werden, wenn für diese Version keine Typen explizit exportiert wurden. Wenn ein Modul in Version 1.0 den Typ „ MyButton “ und in Version 1.1 den Typ „ MyWindow “ bereitstellt, können Sie weder Version 1.2 noch Version 2.0 dieses Moduls importieren.

Ein Typ kann in verschiedenen Nebenversionen durch unterschiedliche Dateien definiert sein. In diesem Fall wird beim Import durch Clients die am besten passende Version verwendet. Wenn ein Modul beispielsweise über seine Datei „ qmldir “ die folgenden Typen festgelegt hat:

module ExampleModule
MyButton 1.0 MyButton.qml
MyButton 1.1 MyButton11.qml
MyButton 1.3 MyButton13.qml
MyRectangle 1.2 MyRectangle12.qml

kann ein Client, der die Version „ 1.2 “ von „ ExampleModule “ importiert, die Typdefinition „ MyButton “ aus „ MyButton11.qml “ verwenden, da dies die aktuellste Version dieses Typs ist, sowie die Typdefinition „ MyRectangle “ aus „ MyRectangle12.qml “.

Das Versionssystem stellt sicher, dass eine bestimmte QML-Datei unabhängig von der Version der installierten Software funktioniert, da ein versionierter Import nur Typen für diese Version importiert und andere Bezeichner verfügbar lässt – selbst wenn die tatsächlich installierte Version diese Bezeichner ansonsten bereitstellen würde.

Beispiel für eine „qmldir“-Datei

Es folgt ein Beispiel für eine „ qmldir “-Datei:

module ExampleModule
CustomButton 2.0 CustomButton20.qml
CustomButton 2.1 CustomButton21.qml
plugin examplemodule
MathFunctions 2.0 mathfuncs.js

Die obige „ qmldir “-Datei definiert ein Modul namens „ExampleModule“. Sie definiert den QML-Objekttyp „ CustomButton “ in den Versionen 2.0 und 2.1 des Moduls, mit unterschiedlichen Implementierungen für jede Version. Sie legt ein Plugin fest, das von der Engine geladen werden muss, wenn das Modul von Clients importiert wird, und dieses Plugin kann verschiedene in C++ definierte Typen im QML-Typsystem registrieren. Auf Unix-ähnlichen Systemen versucht die QML-Engine, „ libexamplemodule.so “ als „ QQmlExtensionPlugin “ zu laden, und unter Windows lädt sie „ examplemodule.dll “ als „ QQmlExtensionPlugin “. Schließlich definiert die Datei „ qmldir “ eine JavaScript-Ressource, die nur verfügbar ist, wenn Version 2.0 oder eine spätere Version (innerhalb derselben Hauptversion) des Moduls importiert wird.

Wenn das Modul im QML-Importpfad installiert ist, könnten Clients das Modul wie folgt importieren und verwenden:

import QtQuick 2.0
import ExampleModule 2.1

Rectangle {
    width: 400
    height: 400
    color: "lightsteelblue"

    CustomButton {
        color: "gray"
        text: "Click Me!"
        onClicked: MathFunctions.generateRandom() > 10 ? color = "red" : color = "gray";
    }
}

Der oben verwendete Typ ` CustomButton ` stammte aus der in der Datei ` CustomButton21.qml ` angegebenen Definition, und die durch den Bezeichner ` MathFunctions ` identifizierte JavaScript-Ressource wäre in der Datei ` mathfuncs.js ` definiert.

Typbeschreibungsdateien

QML-Module können in ihrer Datei „ qmldir “ auf eine oder mehrere Typinformationsdateien verweisen. Diese haben in der Regel die Erweiterung „ .qmltypes “ und werden von externen Tools gelesen, um Informationen über in C++ definierte Typen zu erhalten, die typischerweise über Plugins importiert werden.

Daher haben „qmltypes“-Dateien keinen Einfluss auf die Funktionalität eines QML-Moduls. Ihr einziger Zweck besteht darin, Tools wie Qt Creator den Benutzern Ihres Moduls Code-Vervollständigung, Fehlerprüfung und andere Funktionen bereitzustellen.

Jedes Modul, das QML-Typen in C++ definiert, sollte auch eine Typbeschreibungsdatei enthalten.

Am besten erstellen Sie eine `qmltypes`-Datei für Ihr Modul, indem Sie sie mithilfe des Build-Systems und der Makros ` QML_ELEMENT ` generieren. Wenn Sie die entsprechende Dokumentation befolgen, sind keine weiteren Schritte erforderlich. `qmltyperegistrar` generiert die ` .qmltypes `-Dateien automatisch.

Beispiel: Befindet sich Ihr Modul im Verzeichnis „ /tmp/imports/My/Module “, sollte neben der eigentlichen Plugin-Binärdatei eine Datei namens „ plugins.qmltypes “ generiert werden.

Fügen Sie die Zeile

typeinfo plugins.qmltypes

in die Datei „ /tmp/imports/My/Module/qmldir “ ein, um das Modul zu registrieren.