Introduction au langage QML

QML est un langage déclaratif conçu pour décrire l'interface utilisateur d'un programme, tant son apparence que son comportement. En QML, une interface utilisateur est spécifiée comme un arbre d'objets avec des propriétés.

Cette introduction est destinée à ceux n'ayant que peu ou pas d'expérience en programmation. JavaScript est utilisé en tant que langage de script dans QML, il se peut donc que vous vouliez apprendre un peu plus à son sujet (voir le Guide JavaScript) avant d'aller plus loin en QML. Il est aussi utile d'avoir des notions de base dans d'autres technologies web comme HTML et CSS, mais ce n'est pas obligatoire.

Syntaxe QML de Base

Voici à quoi ressemble QML :

 import QtQuick 1.0
 
 Rectangle {
     width: 200
     height: 200
     color: "blue"
 
     Image {
         source: "pics/logo.png"
         anchors.centerIn: parent
     }
 }

Ici on crée deux objets, un objet Rectangle et son objet enfant Image. Les objets sont spécifiés par leur type, suivis d'une paire d'accolades entre lesquelles des données additionnelles de l'objet peuvent être définies, comme des valeurs de propriétés et des objets enfants.

Les propriétés sont spécifiées avec la syntaxe property: value. Dans l'exemple ci-dessus, on peut voir que l'objet Image possède une propriété nommée source, à laquelle a été affectée la valeur « pics/logo.png ». La propriété et sa valeur sont séparées par un deux-points.

Les propriétés peuvent être spécifiées avec une seule propriété par ligne :

 Rectangle {
     width: 100
     height: 100
 }

ou vous pouvez définir plusieurs propriétés sur une seule ligne :

 Rectangle { width: 100; height: 100 }

Quand plusieurs paires propriété/valeur sont spécifiées sur une seule ligne, elles doivent être séparées par un point-virgule.

La déclaration import importe le module QtQuick, qui contient tous les Elements QML standards. Sans cette déclaration import, les éléments Rectangle et Image ne seraient pas disponibles.

Commentaires

Les commentaires en QML sont similaires à ceux de JavaScript.

• Les commentaires d'une seule ligne commencent avec // et se terminent à la fin de la ligne.
• Les commentaires sur plusieurs lignes commencent avec /* et se terminent avec */.

 Text {
     text: "Hello world!"    // Salutation de base
     /*
        On veut que ce texte se démarque du reste alors
	 on lui donne une grande taille et une police différente.
      */
     font.family: "Helvetica"
     font.pointSize: 24
 }

Les commentaires sont ignorés par le moteur. Ils sont utiles pour expliquer ce qu'on est en train de faire - pour s'y référer plus tard ou pour des tiers lisant vos fichiers QML.

Les commentaires peuvent aussi être utilisés pour empêcher l'exécution d'un code, ce qui peut s'avérer utile pour identifier des problèmes.

 Text {
     text: "Hello world!"
     //opacity: 0.5
 }

Dans l'exemple ci-dessus, l'objet Text va avoir une opacité normale, vu que la ligne opacity: 0.5 a été transformée en commentaire.

Identificateurs d'Objets

À chaque objet on peut affecter une valeur id spéciale qui permet à l'objet d'être identifié et utilisé par d'autres objets.

Par exemple, nous avons ci-dessous deux objets Text. Le premier objet Text a une valeur id « text1 ». Le second objet Text peut maintenant définir la valeur de sa propre propriété text identique à celle du premier objet, en se référant à text1.text :

 import QtQuick 1.0
 
 Row {
     Text {
         id: text1
         text: "Hello World"
     }
 
     Text { text: text1.text }
 }

Un objet peut être référencé par son id depuis la totalité du composant dans lequel il est déclaré. Par conséquent, une valeur id doit toujours être unique dans un composant donné.

La valeur id est une valeur spéciale pour un objet QML et ne doit pas être considérée comme une propriété d'objet ordinaire ; par exemple, il n'est pas possible d'accéder à text1.id dans l'exemple ci-dessus. Une fois qu'un objet est créé, son id ne peut pas être changé.

Notez qu'un id doit commencer avec une lettre minuscule ou un tiret bas et ne peut pas contenir de caractères autres que des lettres, des chiffres et des tirets bas.

Expressions

Les expressions JavaScript peuvent être utilisées pour attribuer des valeurs de propriétés. Par exemple :

 Item {
     width: 100 * 3
     height: 50 + 22
 }

Ces expressions peuvent inclure des références à d'autres objets et propriétés, dans ce cas une liaison est établie : quand la valeur de l'expression change, la propriété à laquelle l'expression est affectée est automatiquement mise à jour à la nouvelle valeur. Par exemple :

 Item {
     width: 300
     height: 300
 
     Rectangle {
         width: parent.width - 50
         height: 100
         color: "yellow"
     }
 }

Ici, la propriété width de l'objet Rectangle est relative à la largeur de son parent. À chaque fois que la largeur du parent change, la largeur du Rectangle est automatiquement mise à jour.

Propriétés

Types de base des propriétés

QML gère de nombreux types de propriétés (voir Types de Base QML). Les types de bases incluent int, real, bool, string et color.

 Item {
     x: 10.5             // une propriété 'réel'
     state: "détails"    // une propriété 'chaîne de caractères'
     focus: true         // une propriété 'booléen'
     ...
 }

Les propriétés QML respectent ce qu'on appelle la règle de typage sûr ; cela signifie que vous ne pouvez affecter que des valeurs correspondant au type de la propriété. Par exemple, la propriété x de item est un réel et si vous essayez de lui affecter une chaine de caractères vous obtiendrez une erreur.

 Item {
     x: "hello"  // illégal!
 }

Notez qu'à l'exception des Propriétés Attachées, les propriétés commencent toujours par une lettre minuscule.

Les notifications de changement de propriété

Quand une propriété change de valeur, elle peut envoyer un signal pour notifier d'autres éléments de ce changement.

Afin de recevoir ces signaux, créez simplement un gestionnaire de signal nommé avec une syntaxe on<Property>Changed. Par exemple, l'élément Rectangle possède les propriétés width et color. Ci-dessous nous avons un objet Rectangle pour lequel ont été définis deux gestionnaires de signaux, onWidthChanged et onColorChanged, qui vont être automatiquement appelés à chaque fois que ces propriétés sont modifiées :

 Rectangle {
     width: 100; height: 100
 
     onWidthChanged: console.log("La largeur est maintenant :", width)
     onColorChanged: console.log("La couleur est maintenant :", color)
 }

Les gestionnaires de signaux sont expliqués plus en détail ci-dessous.

Les propriétés de liste

Les propriétés de liste ressemblent à ceci :

 Item {
     children: [
         Image {},
         Text {}
     ]
 }

La liste est délimitée par des crochets, avec une virgule séparant les éléments de la liste. Dans les cas où vous attribuez un seul élément à une liste, vous pouvez omettre les crochets :

 Image {
     children: Rectangle {}
 }

Les éléments dans la liste sont accessibles par index. Voir la documentation du type liste pour plus de détails sur les propriétés des listes et les opérations possibles.

Les propriétés par défaut

Chaque type d'objet peut spécifier l'une de ses propriétés (liste ou objet) comme sa propriété par défaut. Si une propriété a été déclarée comme propriété par défaut, le tag property peut être omis.

Par exemple ce code :

 State {
     changes: [
         PropertyChanges {},
         PropertyChanges {}
     ]
 }

peut être simplifié en :

 State {
     PropertyChanges {}
     PropertyChanges {}
 }

parce que changes est la propriété par défaut du type State.

Les propriétés groupées

Dans certains cas les propriétés forment un groupe logique et utilisent un ‹point› ou une notation groupée pour le montrer.

Les propriétés groupées peuvent être écrites comme suit :

 Text {
     font.pixelSize: 12
     font.bold: true
 }

ou de cette manière :

 Text {
     font { pixelSize: 12; bold: true }
 }

La documentation des éléments utilise la notation ‹point› pour les propriétés groupées.

Les propriétés attachées

Certains objets attachent des propriétés aux autres objets. Les propriétés attachées sont de la forme Type.property où Type est le type de l'élément qui attache property.

Par exemple, l'élément ListView attache la propriété ListView.isCurrentItem à chaque délégué qu'elle crée :

 Component {
     id: myDelegate
     Text {
         text: "Hello"
         color: ListView.isCurrentItem ? "red" : "blue"
     }
 }
 ListView {
     delegate: myDelegate
 }

Un autre exemple de propriétés attachées est l'élément Keys qui attache des propriétés pour gérer les appuis de touches aux éléments visuels, par exemple :

 Item {
     focus: true
     Keys.onSelectPressed: console.log("Sélectionné")
 }

Les Gestionnaires de Signaux

Les gestionnaires de signaux permettent au code JavaScript d'être exécuté en réponse à un événement. Par exemple, l'élément MouseArea possède un gestionnaire onClicked qui peut être utilisé pour répondre à un clic de souris. Ci-dessous on utilise ce gestionnaire pour imprimer un message à chaque fois que la souris est cliquée :

 Item {
     width: 100; height: 100
 
     MouseArea {
         anchors.fill: parent
         onClicked: {
             console.log("Bouton de souris cliqué")
         }
     }
 }

Tous les gestionnaires de signaux commencent par « on ».

Certains signaux incluent un paramètre optionnel. Par exemple le gestionnaire de signal MouseArea onPressed possède un paramètre mouse qui contient des informations sur l'appui des boutons de la souris. On peut se référer à ce paramètre dans le code JavaScript comme suit :

 MouseArea {
     acceptedButtons: Qt.LeftButton | Qt.RightButton
     onPressed: {
         if (mouse.button == Qt.RightButton)
             console.log("Bouton droit de la souris appuyé")
     }
 }

Remerciements

Merci à Houssem Lamti pour la traduction ainsi qu'à Ilya Diallo, Jonathan Courtois et Claude Leloup pour leur relecture !