Les documents QML

Introduction

Un document QML est un bloc de code source QML. Les documents QML correspondent généralement à des fichiers stockés sur un disque ou sur un emplacement réseau, mais ils peuvent également être construits directement à partir de données texte.

Voici un exemple simple de document QML :

 import QtQuick 1.0
 
 Rectangle {
     width: 240; height: 320;
 
     resources: [
         Component {
             id: contactDelegate
             Text {
                 text: modelData.firstName + " " + modelData.lastName
             }
         }
     ]
 
     ListView {
         anchors.fill: parent
         model: contactModel
         delegate: contactDelegate
     }
 }

Les documents QML sont toujours encodés au format UTF-8.

Un document QML commence toujours par une ou plusieurs déclarations import. Pour éviter que des éléments introduits dans des versions ultérieures n?affectent les programmes QML existants, les types d?éléments disponibles dans un document sont contrôlés par les Modules QML importés. Ainsi, QML est un langage versionné.

Syntaxiquement, un document QML est autonome ; QML ne possède pas de préprocesseur qui modifie le document avant sa présentation à la routine d?exécution QML. Les déclarations import « n?incluent » pas de code dans le document, mais à la place donnent des instructions à la routine QML sur la façon de résoudre les références de type trouvées dans le document. Toute référence à un type présent dans un document QML ? comme par exemple Rectangle et ListView ? y compris ceux créés à l?intérieur d?un bloc JavaScript ou d?une liaison de propriété, est résolue en se basant exclusivement sur les déclarations import. QML n?importe aucun module par défaut, donc au moins une déclaration import doit être présente, sinon aucun élément ne sera disponible !

Chaque valeur id dans un document QML doit être unique à l'intérieur de ce document. Les valeurs id n?ont pas besoin d?être uniques dans un ensemble de différents documents, car elles sont résolues en respectant la portée du document.

Les documents en tant que définitions de composants

Un document QML définit un composant QML unique et de haut niveau. Un composant QML est un modèle (template) interprété par le moteur d'exécution QML pour créer un objet avec certains comportements prédéfinis. En tant que modèle, un composant QML unique peut être « exécuté » plusieurs fois pour produire plusieurs objets, ces objets sont nommés instances du composant.

Une fois créées, les instances ne sont plus dépendantes du composant qui les a créées, et peuvent donc opérer sur des données indépendantes. Voici un exemple d?un simple composant « Button » (défini dans le fichier Button.qml) qui est instancié quatre fois par application.qml. Chaque instance est créée avec une valeur différente pour sa propriété text :

 import QtQuick 1.0
 
 Rectangle {
     property alias text: textItem.text
 
     width: 100; height: 30
     border.width: 1
     radius: 5
     smooth: true
 
     gradient: Gradient {
         GradientStop { position: 0.0; color: "darkGray" }
         GradientStop { position: 0.5; color: "black" }
         GradientStop { position: 1.0; color: "darkGray" }
     }
 
     Text {
         id: textItem
         anchors.centerIn: parent
         font.pointSize: 20
         color: "white"
     }
 
 }

 import QtQuick 1.0
 
 Column {
     spacing: 10
 
     Button { text: "Apple" }
     Button { text: "Orange" }
     Button { text: "Pear" }
     Button { text: "Grape" }
 }

Toute portion de code QML peut devenir un composant, en la plaçant simplement dans le fichier  »<Nom>.qml » où <Nom> est le nom du nouvel élément, commençant par une lettre en majuscules. On notera que la casse de tous les caractères de <Nom> est importante dans certains systèmes de fichiers, particulièrement dans les systèmes de fichiers UNIX. Il est recommandé d'avoir une casse du nom de fichier correspondant exactement à la casse du nom du composant dans QML, indépendamment de la plateforme sur laquelle QML est déployé.

Ces fichiers de composants QML deviennent automatiquement disponibles en tant que nouveau type d?éléments QML pour les autres composants et applications QML dans le même répertoire.

Les composants inline

En plus des composants de haut niveau que tout document QML définit, et de tout composant réutilisable placé dans des fichiers séparés, les documents peuvent également inclure des composants inline. Les composants inline sont déclarés en utilisant l?élément Component, comme on peut le voir dans le premier exemple ci-dessus. Les composants inline partagent toutes les caractéristiques des composants de haut niveau habituels, et utilisent la même liste d?import que le document QML qui les contient. Les composants sont parmi les codes de construction les plus basiques dans QML, et sont souvent utilisés comme « usines » par les autres éléments. Par exemple, l?élément ListView utilise l?élément delegate comme modèle pour instancier la liste d?éléments ? chaque élément de la liste est simplement une nouvelle instance du composant avec ses données spécifiques fixées de manière appropriée.

Comme les autres éléments QML, l?élément Component est un objet et doit être affecté à une propriété. Les objets Component peuvent également posséder un identifiant d?objet. Dans le premier exemple de cette page, le composant inline est ajouté à la liste des ressources de Rectangle, puis la liaison de propriété est utilisée pour affecter le Component à la propriété delegate de ListView. L?utilisation de la liaison de propriété autorise le partage de l?objet Component (par exemple, si le document QML contient plusieurs ListView avec le même delegate), dans ce cas le Component aurait pu être affecté directement au delegate de ListView. Le langage QML contient même une optimisation syntaxique lors de l?attribution directe d?une propriété Component, dans ce cas il insère automatiquement la balise Component.

Ces deux derniers exemples ont un comportement identique au document original.

 import QtQuick 1.0
 
 Rectangle {
     width: 240; height: 320;
 
     ListView {
         anchors.fill: parent
         model: contactModel
         delegate: Component {
             Text {
                 text: modelData.firstName + " " + modelData.lastName
             }
         }
     }
 }

 import QtQuick 1.0
 
 Rectangle {
     width: 240; height: 320;
 
     ListView {
         anchors.fill: parent
         model: contactModel
         delegate: Text {
             text: modelData.firstName + " " + modelData.lastName
         }
     }
 }

Voir aussi QDeclarativeComponent.

Remerciements

Merci à Lo?c Leguay pour la traduction ainsi qu'à Ilya Diallo, Jonathan Courtois et Claude Leloup pour leur relecture !