Définition du module Fichiers qmldir

Il existe deux types distincts de fichiers qmldir:

• les fichiers de liste de répertoires de documents QML
• Fichiers de définition de module QML

Cette documentation ne couvre que la deuxième forme de fichier qmldir, qui répertorie les types QML, les fichiers JavaScript et les plugins disponibles sous un module. Pour plus d'informations sur la première forme du fichier qmldir, voir la liste des fichiers qmldir.

Contenu d'un fichier qmldir de définition de module

Un fichier qmldir est un fichier en texte clair qui contient les commandes suivantes :

• Déclaration d'identifiant de module
• Déclaration du type d'objet
• Déclaration de type d'objet interne
• Déclaration de ressource JavaScript
• Déclaration de plugin
• Déclaration du nom de classe du plugin
• Déclaration de fichier de description de type
• Déclaration des dépendances du module
• Déclaration d'importation de module
• Déclaration de support du concepteur
• Déclaration de chemin d'accès préféré

Outre les commandes, vous pouvez également ajouter des commentaires, qui sont des lignes commençant par #.

Déclaration de l'identifiant du module

module <ModuleIdentifier>

Déclare l'identifiant du module. Le <ModuleIdentifier> est l'identifiant (notation URI pointée) du module, qui doit correspondre au chemin d'installation du module.

La directive relative à l'identifiant du module doit être la première ligne du fichier. Il ne peut y avoir qu'une seule directive d'identification de module dans le fichier qmldir.

Exemple :

module ExampleModule

Déclaration de type d'objet

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

Déclare un type d'objet QML qui doit être mis à disposition par le module.

• [singleton] Facultatif. Utilisé pour déclarer un type singleton.
• <TypeName> est le type mis à disposition
• <InitialVersion> est la version du module pour laquelle le type doit être mis à disposition
• <File> est le nom de fichier (relatif) du fichier QML qui définit le type.

Il peut y avoir zéro ou plusieurs déclarations de type d'objet dans le fichier qmldir. Cependant, chaque type d'objet doit avoir un nom de type unique dans toute version particulière du module.

Exemple :

//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"
}

Déclaration d'un type d'objet interne

internal <TypeName> <File>

Déclare un type d'objet qui se trouve dans le module mais qui ne doit pas être mis à la disposition des utilisateurs du module.

Il peut y avoir zéro ou plusieurs déclarations de type d'objet interne dans le fichier qmldir.

Exemple :

internal MyPrivateType MyPrivateType.qml

Cette déclaration est nécessaire si le module est importé à distance (voir Modules identifiés installés à distance), car si un type exporté dépend d'un type non exporté dans le module, le moteur doit également charger le type non exporté.

Déclaration de ressource JavaScript

<ResourceIdentifier> <InitialVersion> <File>

Déclare un fichier JavaScript qui doit être mis à disposition par le module. La ressource sera mise à disposition via l'identifiant spécifié avec le numéro de version spécifié.

Il peut y avoir zéro ou plusieurs déclarations de ressources JavaScript dans le fichier qmldir. Cependant, chaque ressource JavaScript doit avoir un identifiant unique dans toute version particulière du module.

Exemple :

MyScript 1.0 MyScript.js

Voir la documentation sur la définition des ressources JavaScript et l'importation de ressources JavaScript dans QML pour plus d'informations.

Déclaration de plugin

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

Déclare qu'un plugin doit être mis à disposition par le module.

• optional indique que le plugin lui-même ne contient pas de code pertinent et sert uniquement à charger une bibliothèque à laquelle il est lié. S'il est donné, et si des types pour le module sont déjà disponibles, indiquant que la bibliothèque a été chargée par un autre moyen, QML ne chargera pas le plugin.
• <Name> est le nom de la bibliothèque du plugin. Ce nom n'est généralement pas le même que le nom de fichier du binaire du plugin, qui dépend de la plate-forme. Par exemple, la bibliothèque MyAppTypes produira libMyAppTypes.so sous Linux et MyAppTypes.dll sous Windows.
• <Path> (facultatif) spécifie soit
  • un chemin absolu vers le répertoire contenant le fichier du plugin, ou
  • un chemin relatif entre le répertoire contenant le fichier qmldir et le répertoire contenant le fichier d'extension.

Par défaut, le moteur recherche la bibliothèque de plugins dans le répertoire contenant le fichier qmldir. (Le chemin de recherche des plugins peut être demandé avec QQmlEngine::pluginPathList() et modifié avec QQmlEngine::addPluginPath().)

Le fichier qmldir peut contenir zéro ou plusieurs déclarations de greffons C++. Cependant, le chargement des plugins étant une opération relativement coûteuse, il est conseillé aux clients de ne spécifier qu'un seul plugin.

Exemple :

plugin MyPluginLibrary

Déclaration du nom de classe du plugin

classname <C++ plugin class>

Fournit le nom de la classe du plugin C++ utilisé par le module.

Cette information est requise pour tous les modules QML qui dépendent d'un plugin C++ pour des fonctionnalités supplémentaires. Les applications Qt Quick construites avec des liens statiques ne peuvent pas résoudre les importations de modules sans cette information.

Déclaration de fichier de description de type

typeinfo <File>

Déclare un fichier de description de type pour le module qui peut être lu par des outils QML tels que Qt Creator pour accéder aux informations sur les types définis par les modules d'extension du module. <File> est le nom de fichier (relatif) d'un fichier .qmltypes.

Exemple :

typeinfo mymodule.qmltypes

Sans un tel fichier, les outils QML peuvent être incapables d'offrir des fonctionnalités telles que la complétion de code pour les types définis dans vos plugins.

Déclaration de dépendance du module

depends <ModuleIdentifier> <InitialVersion>

Déclare que ce module dépend d'un autre.

Exemple :

depends MyOtherModule 1.0

Cette déclaration n'est nécessaire que dans les cas où la dépendance est cachée : par exemple, lorsque le code C++ d'un module est utilisé pour charger QML (éventuellement de manière conditionnelle), qui dépend alors d'autres modules. Dans ce cas, la déclaration depends est nécessaire pour inclure les autres modules dans les paquets d'application.

Déclaration d'importation de module

import <ModuleIdentifier> [<Version>]

Déclare que ce module en importe un autre.

Exemple :

import MyOtherModule 1.0

Les types de l'autre module sont disponibles dans le même espace de noms de types que celui dans lequel ce module est importé. L'omission de la version permet d'importer la dernière version disponible de l'autre module. En spécifiant auto comme version, on importe la même version que la version de ce module spécifiée dans la déclaration QML import.

Déclaration de prise en charge du concepteur

designersupported

Définissez cette propriété si le plugin est pris en charge par Qt Quick Designer. Par défaut, le plugin n'est pas pris en charge.

Un plugin pris en charge par Qt Quick Designer doit être correctement testé. Cela signifie que le plugin ne se bloque pas lorsqu'il est exécuté dans la marionnette qml2puppet utilisée par Qt Quick Designer pour exécuter QML. En règle générale, le plugin doit bien fonctionner dans Qt Quick Designer et ne pas provoquer de blocage, comme une consommation excessive de mémoire, un ralentissement important de qml2puppet ou toute autre chose qui rendrait le plugin inutilisable dans Qt Quick Designer.

Les éléments d'un plugin non pris en charge ne sont pas peints dans le concepteur Qt Quick, mais ils sont toujours disponibles sous forme de boîtes vides et leurs propriétés peuvent être modifiées.

Déclaration du chemin préféré

prefer <Path>

Cette propriété indique au moteur QML de charger tous les autres fichiers de ce module à partir de <chemin>, plutôt que dans le répertoire actuel. Elle peut être utilisée pour charger des fichiers compilés avec qmlcachegen.

Par exemple, vous pouvez ajouter les fichiers QML d'un module en tant que ressources à un chemin de ressources :/my/path/MyModule/. Ensuite, ajoutez prefer :/my/path/MyModule au fichier qmldir afin d'utiliser les fichiers du système de ressources plutôt que ceux du système de fichiers. Si vous utilisez ensuite qmlcachegen pour ces fichiers, les fichiers précompilés seront disponibles pour tous les clients du module.

Sémantique de versionnement

Tous les types QML exportés pour une version majeure particulière sont disponibles avec la dernière version de la même version majeure. Par exemple, si un module fournit un type MyButton dans la version 1.0 et un type MyWindow dans la version 1.1, les clients qui importent la version 1.1 du module peuvent utiliser les types MyButton et MyWindow. Toutefois, l'inverse n'est pas vrai : un type exporté pour une version mineure particulière ne peut pas être utilisé en important une version mineure antérieure ou plus ancienne. Dans l'exemple mentionné plus haut, si le client a importé la version 1.0 du module, il ne peut utiliser que le type MyButton, mais pas le type MyWindow.

Un module peut proposer plusieurs versions majeures, mais les clients n'ont accès qu'à une seule version majeure à la fois. Par exemple, l'importation de MyExampleModule 2.0 ne donne accès qu'à cette version majeure et non à la version majeure précédente. Bien que vous puissiez organiser les artefacts appartenant à différentes versions majeures dans un répertoire sigle et un fichier qmldir, il est recommandé d'utiliser des répertoires différents pour chaque version majeure. Si vous optez pour l'approche précédente (un répertoire et un fichier qmldir ), essayez d'utiliser le suffixe de la version pour les noms de fichiers. Par exemple, les artefacts qui appartiennent à MyExampleModule 2.0 peuvent utiliser le suffixe .2 dans leur nom de fichier.

Une version ne peut pas être importée si aucun type n'a été explicitement exporté pour cette version. Si un module fournit un type MyButton dans la version 1.0 et un type MyWindow dans la version 1.1, vous ne pouvez pas importer la version 1.2 ou la version 2.0 de ce module.

Un type peut être défini par différents fichiers dans différentes versions mineures. Dans ce cas, la version la plus proche est utilisée lors de l'importation par les clients. Par exemple, si un module a spécifié les types suivants via son fichier qmldir:

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

un client qui importe la version 1.2 de ExampleModule peut utiliser la définition du type MyButton fournie par MyButton11.qml, car il s'agit de la dernière version de ce type, et la définition du type MyRectangle fournie par MyRectangle12.qml.

Le système de version garantit qu'un fichier QML donné fonctionne quelle que soit la version du logiciel installé, car une importation par version n'importe que les types de cette version, laissant les autres identificateurs disponibles, même si la version installée pourrait autrement fournir ces identificateurs.

Exemple de fichier qmldir

Voici un exemple de fichier qmldir:

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

Le fichier qmldir ci-dessus définit un module appelé "ExampleModule". Il définit le type d'objet QML CustomButton dans les versions 2.0 et 2.1 du module, avec des implémentations différentes pour chaque version. Il spécifie un plugin qui doit être chargé par le moteur lorsque le module est importé par des clients, et ce plugin peut enregistrer divers types définis en C++ avec le système de types QML. Sur les systèmes de type Unix, le moteur QML tente de charger libexamplemodule.so en tant que QQmlExtensionPlugin, et sur Windows, il charge examplemodule.dll en tant que QQmlExtensionPlugin. Enfin, le fichier qmldir spécifie une ressource JavaScript, qui n'est disponible que si la version 2.0 ou une version ultérieure (sous la même version majeure) du module est importée.

Si le module est installé dans le chemin d'importation QML, les clients peuvent l'importer et l'utiliser de la manière suivante :

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";
    }
}

Le type CustomButton utilisé ci-dessus proviendrait de la définition spécifiée dans le fichier CustomButton21.qml, et la ressource JavaScript identifiée par l'identifiant MathFunctions serait définie dans le fichier mathfuncs.js.

Fichiers de description de type

Les modules QML peuvent faire référence à un ou plusieurs fichiers d'informations sur les types dans leur fichier qmldir. Ces fichiers portent généralement l'extension .qmltypes et sont lus par des outils externes pour obtenir des informations sur les types définis en C++ et généralement importés par l'intermédiaire de modules d'extension.

En tant que tels, les fichiers qmltypes n'ont aucun effet sur la fonctionnalité d'un module QML. Leur seule utilité est de permettre à des outils tels que Qt Creator de fournir des compléments de code, des vérifications d'erreurs et d'autres fonctionnalités aux utilisateurs de votre module.

Tout module qui définit des types QML en C++ doit également fournir un fichier de description de type.

La meilleure façon de créer un fichier qmltypes pour votre module est de le générer en utilisant le système de construction et les macros QML_ELEMENT. Si vous suivez la documentation à ce sujet, aucune autre action n'est nécessaire. qmltyperegistrar générera automatiquement les fichiers .qmltypes.

Exemple : Si votre module se trouve dans /tmp/imports/My/Module, un fichier appelé plugins.qmltypes doit être généré avec le binaire du plugin.

Ajoutez la ligne

typeinfo plugins.qmltypes

à /tmp/imports/My/Module/qmldir pour l'enregistrer.