L'afficheur QML (QML Viewer)

Le module des interfaces déclaratives contient Qt QML Viewer, l'afficheur QML, un outil pour charger des documents QML permettant de développer et déboguer des applications QML facilement. Il appelle le moteur d'exécution QML pour charger les documents QML et fournit aussi des fonctionnalités additionnelles utiles pour le développement d'applications basées sur QML.

QML Viewer est un outil pour tester et développer des applications QML. Il n'est pas prévu pour fonctionner dans un environnement de production et ne doit pas être utilisé pour le déploiement d'applications QML. Dans ces cas, le moteur d'exécution QML devra être appelé à partir d'une application Qt ; voir le moteur d'exécution des interfaces déclaratives Qt pour plus d'information.

L'exécutable est situé dans le dossier QTDIR/bin et s'appelle qmlviewer. Pour charger un fichier .qml dans l'afficheur, exécutez-le et sélectionnez un fichier à ouvrir, ou fournissez le chemin au fichier en ligne de commande comme ceci :

 qmlviewer myqmlfile.qml

Sous Mac OS X, l'application QML Viewer a un nom différent, elle s'appelle « QMLViewer ». Vous pouvez lancer l'afficheur en ouvrant l'application QMLViewer à partir du « Finder » ou depuis la ligne de commande, comme ceci :

 QMLViewer.app/Contents/MacOS/QMLViewer myqmlfile.qml

L'afficheur QML possède de nombreuses options de configuration concernant des fonctionnalités comme l'affichage plein écran, la configuration de chemin d'importation de modules, l'enregistrement vidéo des animations QML, et le support d'OpenGL.

Pour connaître les options de configuration, exécutez qmlviewer avec l'argument -help.

Ajouter des chemins d'importation de modules

Des chemins d'importation de modules supplémentaires peuvent être fournis en utilisant l'indicateur -I. Par exemple, l'exemple de plug-ins QML crée un plug-in C++ identifié comme com.nokia.TimeExample. Comme son identificateur utilise un espace de noms, l'afficheur doit être exécuté avec l'indicateur -I à partir du dossier de base de l'exemple :

 qmlviewer -I . plugins.qml

Cela permet d'ajouter le dossier aux chemins d'importation permettant à l'afficheur de trouver le plug-in dans le dossier com/nokia/TimeExample.

Notez que, par défaut, le dossier courant est inclus dans les chemins d'importation, mais que les modules utilisant un espace de noms comme com.nokia.TimeExample ne seront pas localisés tant que le chemin ne sera pas spécifié explicitement.

Chargement de fichiers de traduction

Lorsque l'afficheur QML charge un fichier QML, il installe le fichier de traduction à partir du sous-dossier « i18n » relatif au fichier initial. Le dossier doit contenir un fichier de traduction nommé « qml_<langue>.qm », où <langue> est une langue ISO 639 sur deux lettres, comme « qml_fr.qm », optionnellement suivi par un tiret bas et un code de pays ISO 3166 en majuscules, tel que « qml_fr_FR.qm » ou « qml_fr_CA.qm ».

Ces fichiers peuvent être créés avec Qt Linguist.

Le fichier de traduction effectivement chargé dépend de la langue locale du système. De plus, l'afficheur va charger tout fichiers de traduction spécifiés via la ligne de commande avec l'option -translation.

Voir l'exemple i18n en QML pour un exemple. La documentation internationalisation dans Qt montre également la manière dont on peut faire utiliser des chaînes traduisibles à du code JavaScript dans des fichiers QML.

Chargement de données de remplacement avec QML Viewer

Souvent, les prototypes d'applications QML sont réalisés avec des données factices qui seront, plus tard, remplacées par les données réelles venant des plug-ins C++. QML Viewer vous aide à le faire en chargeant des données factices dans le contexte de l'application : il recherche un dossier nommé « dummydata » dans le même répertoire que le fichier QML cible et tous les fichiers .qml de ce dossier sont chargés comme objets QML et liés au contexte racine comme propriétés nommées d'après les fichiers.

Par exemple, ce document QML se réfère à la propriété lottoNumbers qui n'existe pas réellement dans le document :

 import QtQuick 1.0
 
 ListView {
     width: 200; height: 300
     model: lottoNumbers
     delegate: Text { text: number }
 }

Si, dans le dossier du document, il y a un dossier « dummydata » contenant un fichier lottoNumbers.qml qui contient :

 import QtQuick 1.0
 
 ListModel {
     ListElement { number: 23 }
     ListElement { number: 44 }
     ListElement { number: 78 }
 }

Ce modèle sera alors chargé automatiquement dans la ListView du document précédent.

Les propriétés enfants sont incluses lors du chargement à partir des données factices. Le document suivant se réfère à une propriété clock.time:

 import QtQuick 1.0
 Text { text: clock.time }

La valeur du texte pouvait être remplie par un fichier dummydata/clock.qml ayant une propriété time dans le contexte racine :

 import QtQuick 1.0
 QtObject { property int time: 54321 }

Pour remplacer ces données avec les données réelles, vous pouvez simplement lier l'objet réel avec le contexte racine en C++ grâce à la fonction QDeclarativeContext::setContextProperty(). Ce processus est décrit dans Utiliser les liaisons QML dans les applications C++.

Utiliser l'objet ''runtime''

Les applications QML qui sont chargées par l'afficheur QML ont accès à une propriété runtime spéciale dans le contexte racine. La propriété fournit des informations supplémentaires à propos de l'environnement de l'application à travers les propriétés suivantes :

Cette propriété indique si la fenêtre de l'afficheur QML est la fenêtre active actuelle du système. Cette information est utile pour mettre en pause une application, particulièrement ses animations, lorsque le QML Viewer perd le focus ou est déplacé en arrière-plan. Par exemple, l'animation suivante n'est jouée que lorsque la fenêtre de l'afficheur QML est active :

 Rectangle {
     width: 200; height: 200
 
     ColorAnimation on color {
         running: runtime.isActiveWindow
         loops: Animation.Infinite
         from: "green"; to: "blue"; duration: 2000
     }
 }

Cette propriété indique l'orientation actuelle de l'afficheur QML. Sur les N900 et la plupart des S60 5.0 ainsi que les nouveaux périphériques Symbian, cette propriété est automatiquement mise à jour pour correspondre à l'orientation réelle du périphérique ; sur les autres plateformes, elle indique l'orientation actuellement sélectionnée dans le menu Settings -> Properties du QML Viewer. L'orientation peut avoir l'une des valeurs suivantes :

• Orientation.Portrait (orientation portrait) ;
• Orientation.Landscape (orientation paysage) ;
• Orientation.PortraitInverted (orientation portrait inversée) ;
• Orientation.LandscapeInverted (orientation paysage inversée).

Lorsque l'orientation de l'afficheur change, l'apparence du document QML chargé ne change que s'il a été programmé pour réagir au changement de runtime.orientation. Par exemple, le Rectangle suivant change ses proportions selon l'orientation de l'afficheur QML :

 Rectangle {
     id: window
     width: 640; height: 480
 
     states: State {
         name: "landscape"
         PropertyChanges { target: window; width: 480; height: 640 }
     }
     state: (runtime.orientation == Orientation.Landscape
             || runtime.orientation == Orientation.LandscapeInverted) ? 'landscape' : ''
 }

Remerciements

Merci à Alexandre Laurent pour la traduction ainsi qu'à Ilya Diallo, Jonathan Courtois, Thibaut Cuvelier et Claude Leloup pour leur relecture !