Fichiers qmldir de définition de modules

Il existe deux types distincts de fichiers d'qmldir:

• Fichiers de liste des répertoires de documents QML
• Fichiers de définition de modules QML

Cette documentation ne traite que du deuxième type de fichier d’ qmldir, qui répertorie les types QML, les fichiers JavaScript et les plugins disponibles au sein d’un module. Pour plus d’informations sur le premier type de fichier d’ qmldir, consultez la section consacrée aux fichiers qmldir de liste de répertoires.

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

Un fichier d’ qmldir est un fichier en texte brut qui contient les commandes suivantes :

• Déclaration de l’identificateur 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 du fichier de description des types
• Déclaration des dépendances du module
• Déclaration d'importation de module
• Déclaration de prise en charge par le concepteur
• Déclaration du 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 (au format URI pointé) du module, qui doit correspondre au chemin d’installation du module.

La directive d’identifiant de module doit figurer sur la première ligne du fichier. Le fichier qmldir ne peut contenir qu’une seule directive d’identifiant de module.

Exemple :

module ExampleModule

Déclaration de type d’objet

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

Déclare un type d’objet QML qui sera mis à disposition par le module.

• [singleton] Facultatif. Permet de 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

Le fichier ` qmldir ` peut contenir zéro ou plusieurs déclarations de types d’objets. Cependant, chaque type d’objet doit porter un nom de type unique au sein d’une version donnée 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 de type d'objet interne

internal <TypeName> <File>

Déclare un type d’objet présent dans le module mais qui ne doit pas être accessible aux utilisateurs du module.

Le fichier qmldir peut contenir zéro ou plusieurs déclarations de types d’objets internes.

Exemple :

internal MyPrivateType MyPrivateType.qml

Ceci 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é au sein du 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 accessible via l’identifiant spécifié avec le numéro de version indiqué.

Le fichier ` qmldir ` peut contenir zéro ou plusieurs déclarations de ressources JavaScript. Cependant, chaque ressource JavaScript doit posséder un identifiant unique au sein d’une version donnée du module.

Exemple :

MyScript 1.0 MyScript.js

Consultez 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 un plugin qui sera mis à disposition par le module.

• optional indique que le plugin lui-même ne contient aucun code pertinent et sert uniquement à charger une bibliothèque à laquelle il est lié. Si cette option est spécifiée et si des types pour le module sont déjà disponibles, ce qui indique 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. Il ne s'agit généralement pas du nom de fichier du binaire du plugin, qui dépend de la plateforme. Par exemple, la bibliothèque MyAppTypes produirait 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 depuis le répertoire contenant le fichier qmldir vers le répertoire contenant le fichier du plugin.

Par défaut, le moteur recherche la bibliothèque du plugin dans le répertoire contenant le fichier d’ qmldir. (Le chemin de recherche du plugin peut être interrogé à l’aide de QQmlEngine::pluginPathList() et modifié à l’aide de QQmlEngine::addPluginPath().)

Le fichier ` qmldir ` peut contenir zéro ou plusieurs déclarations de plug-ins C++. Cependant, le chargement d'un plug-in étant une opération relativement coûteuse, il est conseillé aux clients de ne spécifier qu'un seul plug-in au maximum.

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 obligatoire pour tous les modules QML qui dépendent d’un plugin C++ pour bénéficier de fonctionnalités supplémentaires. Les applications Qt Quick compilées avec une liaison statique ne peuvent pas résoudre les importations de modules sans cette information.

Déclaration du fichier de description de type

typeinfo <File>

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

Exemple :

typeinfo mymodule.qmltypes

Sans un tel fichier, les outils QML pourraient ne pas être en mesure de proposer des fonctionnalités telles que la complétion de code pour les types définis dans vos plugins.

Déclaration des dépendances 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 lorsque la dépendance est cachée : par exemple, lorsque le code C++ d’un module est utilisé pour charger du QML (éventuellement de manière conditionnelle), qui dépend alors d’autres modules. Dans de tels 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 rendus disponibles dans le même espace de noms de types que celui dans lequel ce module est importé. Si la version n’est pas spécifiée, la dernière version disponible de l’autre module est importée. Si l’on spécifie auto comme version, la version importée correspond à celle de ce module indiquée dans l’instruction QML import.

Déclaration de prise en charge par le Designer

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 avoir été correctement testé. Cela signifie que le plugin ne plante pas lorsqu’il s’exécute au sein de qml2puppet, utilisé par Qt Quick Designer pour exécuter le QML. De manière générale, le plugin doit fonctionner correctement dans le Designer d’ Qt Quick et ne pas provoquer de problèmes majeurs, tels qu’une consommation excessive de mémoire, un ralentissement important de qml2puppet, ou tout autre élément rendant le plugin pratiquement inutilisable dans le Designer d’ Qt Quick.

Les éléments d’un plugin non pris en charge ne s’affichent pas dans le Designer d’ Qt Quick, mais ils restent disponibles sous forme de cases vides et leurs propriétés peuvent être modifiées.

Déclaration du chemin d’accès préféré

prefer <Path>

Cette propriété indique au moteur QML de charger tous les fichiers supplémentaires de ce module à partir de <path>, plutôt que depuis 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/. Ajoutez ensuite 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 des versions

Tous les types QML exportés pour une version majeure donnée sont disponibles avec la dernière version de cette 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 important la version 1.1 du module peuvent utiliser les types MyButton et MyWindow. Cependant, 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 plus ancienne ou antérieure. Dans l'exemple mentionné précédemment, si le client avait importé la version 1.0 du module, il ne pourrait 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 donne accès uniquement à 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 seul répertoire et un fichier qmldir, il est recommandé d’utiliser des répertoires distincts pour chaque version majeure. Si vous optez pour la première approche (un répertoire et un fichier qmldir ), essayez d’utiliser le suffixe de version dans les noms de fichiers. Par exemple, les artefacts appartenant à 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 ni 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, c’est la version la plus proche qui est utilisée lors de l’importation par les clients. Par exemple, si un module avait 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 de type MyButton fournie par MyButton11.qml, car il s’agit de la dernière version de ce type, ainsi que la définition de type MyRectangle fournie par MyRectangle12.qml.

Le système de gestion des versions garantit qu’un fichier QML donné fonctionne quelle que soit la version du logiciel installé, car une importation versionnée n’importe que les types correspondant à cette version, laissant les autres identifiants disponibles, même si la version effectivement installée pourrait autrement fournir ces identifiants.

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 les clients, et ce plugin peut enregistrer divers types définis en C++ auprès du 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 sous 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 (appartenant à 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 des types

Les modules QML peuvent faire référence à un ou plusieurs fichiers d'informations sur les types dans leur fichier qmldir. Ceux-ci portent généralement l’extension .qmltypes et sont lus par des outils externes afin d’obtenir des informations sur les types définis en C++ et généralement importés via des plugins.

À ce titre, les fichiers qmltypes n’ont aucun effet sur les fonctionnalités d’un module QML. Leur seule utilité est de permettre à des outils tels que Qt Creator de proposer la complétion de code, la vérification des erreurs et d'autres fonctionnalités aux utilisateurs de votre module.

Tout module définissant des types QML en C++ doit également être fourni avec un fichier de description des types.

La meilleure façon de créer un fichier `qmltypes` pour votre module est de le générer à l’aide du système de compilation et des 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 nommé plugins.qmltypes devrait être généré en même temps que le binaire du plugin proprement dit.

Ajoutez la ligne

typeinfo plugins.qmltypes

au fichier /tmp/imports/My/Module/qmldir pour l'enregistrer.