Modules

Les modules QML

Un module est un ensemble de fichiers QML formant une unité d'importation pour des applications QML. Les modules peuvent être utilisés pour organiser le contenu QML dans des unités indépendantes, et ils peuvent utiliser un mécanisme de versionnage qui autorise la mise à jour indépendante des modules.

Alors que les fichiers de composants QML du même répertoire sont automatiquement accessibles au sein de l'espace de noms global, les composants définis ailleurs doivent être explicitement importés par l'utilisation de la déclaration import pour les importer en tant que modules. Par exemple, la déclaration import est obligatoire pour utiliser :

• un composant défini dans un autre fichier QML qui n'est pas dans le même répertoire ;
• un composant défini dans un fichier QML situé sur un serveur distant ;
• une bibliothèque d'extension QML (à moins que l'extension soit installée dans le même répertoire) ;
• un fichier JavaScript (notez qu'il doit être importé en utilisant les imports nommés).

Une déclaration import inclut le nom du module et éventuellement un numéro de version. On la trouve en général au début des fichiers QML :

import QtQuick 1.0

Ce code importe la version 1.0 du module «QtQuick» dans l'espace de noms global (la bibliothèque QML elle-même doit être importée si on veut pouvoir utiliser les éléments QML, puisqu'ils ne sont pas inclus dans l'espace de noms global par défaut).

Le module Qt est un module installé, il se situe dans le chemin d'import. Il existe deux types de modules QML : les modules localisés (définis par une URL) et les modules installés (définis par une URI).

Les modules localisés

Les modules localisés peuvent se situer sur le système de fichier local ou sur une ressource du réseau, et sont référencés par une URL écrite entre guillemets qui spécifie leur emplacement. Ils permettent à n'importe quel répertoire possédant du contenu QML d'être importé en tant que module, qu'il réside sur le système de fichier local ou sur un serveur distant.

Par exemple, un projet QML peut contenir un dossier séparé pour un ensemble de composants graphiques personnalisés. Ces composants sont accessibles par importation du répertoire en utilisant un chemin relatif ou absolu, comme ceci :

MyQMLProject
     |- MyComponents
         |- CheckBox.qml
         |- Slider.qml
         |- Window.qml
     |- Main
         |- application.qml

import "../MyComponents"
 
 Window {
     Slider { ... }
     CheckBox { ... }
 }

De la même façon, si le répertoire se situe sur un serveur distant, il pourrait être importé comme ceci :

     import "http://www.my-server.com/MyQMLProject/MyComponents"
     import "http://www.my-server.com/MyQMLProject/MyComponents" 1.0

Un module localisé peut également être importé en tant que ressource réseau s'il possède un fichier qmldir dans son dossier spécifiant les fichiers QML auxquels le module donne accès. Par exemple, si le dossier MyComponents contient un fichier qmldir défini comme ceci :

 Slider 1.0 Slider.qml
 CheckBox 1.0 CheckBox.qml
 Window 1.0 Window.qml

Si le dossier MyComponents est accessible sous forme de ressource réseau, il peut être importé en tant que module, de cette façon :

 import "http://the-server-name.com/MyQMLProject/MyComponents"
 
 Window {
     Slider { ... }
     CheckBox { ... }
 }

avec une version spécifiée «1.0» optionnelle. Notez que l'import échouera si une version supérieure est utilisée, puisque le fichier qmldir spécifie que ces éléments sont seulement disponibles en version 1.0.

Notez que les modules importés en tant que ressource réseau autorisent seulement l'accès aux composants définis dans les fichiers QML. Les composants définis par des plug-ins d'extension QML en C++ ne sont pas disponibles.

Les modules installés

Les modules installés sont les modules qui sont mis à disposition par le biais du chemin d'import QML, défini par QDeclarativeEngine::importPathList(), ou bien les modules définis au sein du code de l'application C++. Un module installé est référencé par une URI, ce qui autorise le module à être importé depuis le code QML sans spécifier complètement le chemin dans le système de fichier ou l'URL de la ressource réseau.

Pour importer un module installé, une URI sans guillemets est utilisée, avec un numéro de version obligatoire :

     import QtQuick 1.0
     import com.nokia.qml.mymodule 1.0

Quand un module est importé, le moteur QML recherche dans le chemin d'import QML le module correspondant. Le dossier racine du module doit contenir un fichier qmldir qui définit les fichiers QML et/ou les plug-ins d'extensions QML en C++ qui sont mis à disposition pour le module.

Les modules qui sont installés dans le chemin d'installation traduisent les URI en noms de répertoires. Par exemple, le fichier qmldir du module com.nokia.qml.mymodule doit se situer dans le sous-chemin com/nokia/qml/mymodule/qmldir quelque part dans le chemin d'import QML. En outre, il est possible de stocker plusieurs versions du module dans ces sous-dossiers. Par exemple, une version 2.1 du module peut être située dans com/nokia/qml/mymodule.2/qmldir ou com/nokia/qml/mymodule.2.1/qmldir. Le moteur va automatiquement charger le module qui correspond le mieux.

Le chemin d'import, tel que retourné par QDeclarativeEngine::importPathList(), définit les emplacements par défaut où le moteur QML va chercher un module correspondant. Par défaut, cette liste contient :

• le dossier du fichier en cours ;
• l'emplacement spécifié par QLibraryInfo::ImportsPath ;
• les chemins spécifiés par la variable d'environnement QML_IMPORT_PATH.

Des chemins d?import supplémentaires peuvent être ajoutés via QDeclarativeEngine::addImportPath() ou la variable d'environnement QML_IMPORT_PATH. Vous pouvez également utiliser l'option -I pour ajouter un chemin d'import quand vous lancez le visualiseur QML.

Créer des modules installés

Par exemple, supposons que le dossier MyQMLProject de l'exemple précédent se trouve dans le système de fichier local dans C:\qml\projects\MyQMLProject. Le sous-dossier MyComponents peut être mis à disposition en tant que module installé en ajoutant au dossier MyComponents un fichier qmldir qui ressemble à ceci :

 Slider 1.0 Slider.qml
 CheckBox 1.0 CheckBox.qml
 Window 1.0 Window.qml

En supposant que le chemin C:\qml a été ajouté au chemin d'import QML par une des méthodes citées précédemment, un fichier QML situé n'importe où dans le système de fichiers local peut alors importer le module comme montré ci-dessous, sans référencer la position absolue du module dans le système de fichiers :

 import projects.MyQMLProject.MyComponents 1.0
 
 Window {
     Slider { ... }
     CheckBox { ... }
 }

Les modules installés sont aussi accessibles en tant que ressource réseau. Si le dossier C:\qml est accessible via http://www.some-server.com/qml et que cette URL a été ajoutée au chemin d'import QML, le code QML ci-dessus fonctionnera également.

Notez que les modules importés en tant que ressource réseau autorisent seulement les composants définis dans les fichiers QML. Les composants définis par les plug-ins d'extension QML en C++ ne sont pas disponibles.

Créer des modules installés en C++

Les applications C++ peuvent définir des modules installés directement au sein de l'application en utilisant qmlRegisterType(). Par exemple, le Tutoriel «Écrire des extensions QML avec C++» définit une classe C++ nommée PieChart et met ce type à disposition de QML en appelant qmlRegisterType() :

 qmlRegisterType<PieChart>("Charts", 1, 0, "PieChart");

Cela autorise les fichiers QML de l'application à utiliser le type PieChart en important le module Charts déclaré :

 import Charts 1.0

Pour les plug-ins QML, l'URI du module est automatiquement passé au QDeclarativeExtensionPlugin::registerTypes(). Cette méthode peut être réimplémentée par le développeur pour enregistrer les types nécessaires au module. Voici l'implémentation de registerTypes() de l'exemple plug-ins QML :

 class QExampleQmlPlugin : public QDeclarativeExtensionPlugin
 {
     Q_OBJECT
 public:
     void registerTypes(const char *uri)
     {
         Q_ASSERT(uri == QLatin1String("com.nokia.TimeExample"));
         qmlRegisterType<TimeModel>(uri, 1, 0, "Time");
     }
 };

Une fois que le plug-in est construit et installé, et qu'il inclut un fichier qmldir, le module peut être importé depuis QML, comme ceci :

 import com.nokia.TimeExample 1.0

Contrairement aux types QML définis dans les fichiers QML, un type QML défini dans un plug-in d'extension C++ ne peut pas être chargé par un module qui est importé en tant que ressource réseau.

Espaces de noms : Utiliser les imports nommés

Par défaut, quand un module est importé, son contenu est importé dans l'espace de noms (namespace) global. Vous pouvez choisir d'importer le module dans un autre espace de noms, soit pour permettre des références à des types aux noms identiques, soit purement pour la lisibilité.

Pour importer un module dans un espace de noms spécifique, utilisez le mot-clef as :

     import QtQuick 1.0 as QtLibrary
     import "../MyComponents" as MyComponents
     import com.nokia.qml.mymodule 1.0 as MyModule

Les types de ces modules ne peuvent ensuite être utilisés que s'ils sont qualifiés par l'espace de noms :

     QtLibrary.Rectangle { ... }
 
     MyComponents.Slider { ... }
 
     MyModule.SomeComponent { ... }

De la même façon que plusieurs modules peuvent être importés dans l'espace de noms global, plusieurs modules peuvent être importés dans le même espace de noms :

     import QtQuick 1.0 as Nokia
     import Ovi 1.0 as Nokia

Fichiers JavaScript

Les fichiers JavaScript doivent toujours être importés avec un import nommé :

     import "somescript.js" as MyScript
 
     Item {
         //...
         Component.onCompleted: MyScript.doSomething()
     }

Le qualificateur (« MyScript » dans l'exemple au-dessus) doit être unique à l'intérieur du document QML. Contrairement aux modules ordinaires, plusieurs scripts ne peuvent pas être importés dans le même espace de noms.

Écrire un fichier qmldir

Un fichier qmldir est un fichier de métadonnées pour un module qui fait la correspondance entre tous les noms de type du module et leur version dans les fichiers QML. Il est requis pour les modules installés et les modules localisés qui sont chargés depuis une source réseau.

Il est défini par un fichier texte nommé «qmldir» qui contient une ligne ou plus de la forme :

# <Comment>
 <TypeName> [<InitialVersion>] <File>
 internal <TypeName> <File>
 plugin <Name> [<Path>]

Les lignes # <Comment> sont utilisées pour les commentaires. Elles sont ignorées par le moteur QML.

Les lignes <TypeName> [<InitialVersion>] <File> sont utilisées pour ajouter des fichiers QML en tant que types. <TypeName> est le nom du type, <InitialVersion>, optionnel, est le numéro de version et <File> est le nom du chemin relatif du fichier QML qui définit ce type.

Les fichiers installés n'ont pas besoin d'importer les modules dont ils font partie, puisqu'ils peuvent faire référence à d'autres fichiers QML du module en tant que fichiers relatifs (locaux). Néanmoins si le module est importé depuis un emplacement distant, ces fichiers doivent être listés dans le fichier qmldir. Les types que vous ne voulez pas rendre visibles aux utilisateurs de votre module doivent être marqués avec le mot-clé internal : internal <TypeName> <File>.

Le même type peut être fourni par différents fichiers en différentes versions, auquel cas la dernière version (p. ex. 1.2) doit précéder les versions antérieures (p. ex. 1.0), étant donné que la première correspondance entre le nom et la version est utilisée et qu'une requête pour une version d'un type peut être satisfaite par définition venant d'une version antérieure du module. Si un utilisateur essaie d'importer une version antérieure à la plus ancienne fournie, ou postérieure à la dernière fournie, l'import va produire une erreur d'exécution, mais si l'utilisateur importe une version dans la plage de version fournie, même si aucun type n'est spécifique à cette version, il n'y aura aucune erreur.

Un module seul, toutes versions confondues, ne peut être fourni que dans un seul répertoire (et avec un seul fichier qmldir). Si plusieurs modules sont fournis, seul le premier du chemin de recherche sera utilisé (indépendamment du fait que d'autres versions soient fournies par d'autres répertoires plus loin dans le chemin de recherche).

Ce système de versionnage garantit qu'un fichier QML donné fonctionnera indépendamment de la version du logiciel installé, étant donné qu'un import versionné n'importe que les types de cette version, laissant les autres identifiants disponibles, même si la version actuellement installée pourrait sinon fournir ces identifiants.

Les lignes plugin <Name> [<Path>] sont utilisées pour ajouter des plug-ins QML C++ au module. <Name> est le nom de la bibliothèque. Il n'est habituellement pas le même que le nom du fichier du plug-in binaire, qui est dépendant de la plateforme. Par exemple la bibliothèque MyAppTypes produira libMyAppTypes.so sur GNU/Linux et MyAppTypes.dll sur Windows.

<Path> est un argument optionnel qui spécifie soit un chemin absolu du dossier contenant le fichier du plug-in, soit un chemin relatif partant du dossier contenant le fichier qmldir jusqu'au dossier contenant le fichier du plug-in. Par défaut, le moteur cherche la bibliothèque plug-in dans le dossier contenant le fichier qmldir. Le chemin de rechercher du plug-in peut être obtenu avec QDeclarativeEngine::pluginPathList() et modifié avec QDeclarativeEngine::addPluginPath(). Utiliser l?option -P pour ajouter des chemins au chemin de recherche du plug-in quand vous lancez le QML Viewer.

Débogage

La variable d'environnement QML_IMPORT_TRACE peut être utile pour le débogage en cas de problèmes avec la recherche et le chargement des modules. Voir Déboguer les imports de module pour plus d'informations.

Remerciements

Merci à Emmanuel Di Clemente pour la traduction ainsi qu'à Ilya Diallo, Jonathan Courtois et Claude Leloup pour leur relecture !