Portée dans QML

Les liaisons de propriété de QML, les fonctions inline et les fichiers JavaScript importés sont tous exécutés dans la portée (scope) du JavaScript. Les règles de portée contrôlent les variables auxquelles une expression peut accéder et quelles variables auront la priorité si deux ou plusieurs noms rentrent en conflit.

Comme le mécanisme interne des portées du JavaScript est très simple, le QML l'améliore pour l'adapter plus naturellement aux extensions du langage QML.

Portée dans JavaScript

Les extensions du QML sur les portées n'interfèrent pas avec les règles du JavaScript. Les programmeurs JavaScript peuvent réutiliser leurs connaissances lors de la programmation des fonctions, des liaisons de propriété et des importations de fichiers JavaScript.

Dans l'exemple suivant, la méthode addConstante() ajoutera 13 au paramètre passé. Comme tout programmeur doit s'y attendre, les valeurs des propriétés a et b de l'objet QML sont indépendantes.

 QtObject {
     property int a: 3
     property int b: 9
 
     function addConstante(b) {
         var a = 13;
         return b + a;
     }
 }

QML respecte les règles de portée du JavaScript même dans les liaisons. Cette diabolique, abominable liaison assignera 12 à la propriété a de l'objet QML.

 QtObject {
     property int a
 
     a: { var a = 12; a; }
 }

Chaque expression JavaScript, fonction ou fichier dans QML possède ses propres variables uniques. Les variables locales déclarées dans l'un d'entre eux ne rentreront jamais en conflit avec les variables locales d'un autre.

Noms d'éléments et fichiers JavaScript importés

Les documents QML ont des lignes d'importations qui définissent les noms d'éléments et les fichiers JavaScript visibles pour le document. En plus de leur usage dans la déclaration de QML, les noms d'éléments sont utilisés par le code JavaScript lors de l'accès aux propriétés attachées et valeurs d'énumération.

L'effet de ces importations s'applique à toutes les liaisons de propriété et fonctions JavaScript dans le document QML, même dans les composants imbriqués. L'exemple suivant présente un simple fichier QML qui accède à des valeurs d'énumération et appelle une fonction JavaScript importée.

 import QtQuick 1.0
 import "code.js" as Code
 
 ListView {
     snapMode: ListView.SnapToItem
 
     delegate: Component {
         Text {
             elide: Text.ElideMiddle
             text: "A really, really long string that will require eliding."
             color: Code.defaultColor()
         }
     }
 }

Portée des liaisons

Les liaisons de propriété sont l'usage le plus commun du JavaScript dans QML. Les liaisons de propriété associent le résultat d'une expression JavaScript avec la propriété d'un objet. L'expression appartient à la portée de l'objet liant. Dans cette déclaration simple de QML, l'objet Item est la portée.

 Item {
     anchors.left: parent.left
 }

Les liaisons ont accès à la portée des propriétés de l'objet sans aucune restriction. Dans l'exemple précédent, la liaison accède à la propriété parent de Item directement, sans nécessiter un préfixe d'objet. QML introduit une approche orientée objet plus structurée au JavaScript et par conséquent ne nécessite pas l'utilisation de la propriété JavaScript this.

Des précautions doivent être prises lors de l'accès aux propriétés attachées à partir des liaisons à cause de leur interaction avec la portée de l'objet. En théorie, les propriétés attachées existent dans tous les objets, même s'ils n'ont qu'un effet sur un sous-ensemble de ceux-ci. Par conséquent, des lectures non permises à partir de propriétés attachées seront toujours effectuées sur une propriété attachée dans la portée d'un objet, ce qui n'est pas toujours ce que le programmeur souhaite.

Par exemple, l'élément PathView attache des valeurs de propriété interpolées à son délégué selon sa position dans le chemin. Comme le PathView attache seulement ces propriétés à l'élément racine root dans le délégué, tout sous-ensemble qui y accède doit explicitement spécifier l'objet racine, comme présenté ci-dessous :

 PathView {
     delegate: Component {
         Rectangle {
             id: root
             Image {
                 scale: root.PathView.scale
             }
         }
     }
 }

Si l'élément Image oublie le préfixe root, il accèderait à la propriété non définie PathView.scale attachant la propriété avec elle-même.

Portée des composants

Chaque composant QML dans le document QML définit une portée logique. Chaque document possède au moins un composant racine mais peut aussi avoir d'autres sous-composants imbriqués. La portée du composant est l'union des identifiants de l'objet compris dans le composant et les propriétés de l'élément du composant racine.

 Item {
     property string title
 
     Text {
         id: titleElement
         text: "<b>" + title + "</b>"
         font.pixelSize: 22
         anchors.top: parent.top
     }
 
     Text {
         text: titleElement.text
         font.pixelSize: 18
         anchors.bottom: parent.bottom
     }
 }

L'exemple ci-dessus présente un composant QML simple qui affiche un titre et une copie plus petite de ce même texte en bas. Le premier élément Text accède directement à la propriété titre title du composant lors de la définition du texte à afficher. Le fait que les propriétés de l'élément racine soient directement accessibles rend la distribution des données à travers le composant plus facile.

Le second élément Text utilise un identifiant pour accéder directement au texte du premier. Les identifiants sont spécifiés explicitement par le programmeur QML donc ils ont toujours la priorité sur les noms de propriétés (sauf pour ceux étant dans la portée du JavaScript). Par exemple, dans le cas improbable que la portée de la liaison possède une propriété titre d'élément titleElement dans l'exemple précédent, l'identifiant titleElement aurait été prioritaire.

Hiérarchie des instances de composants

Dans QML, les instances de composants connectent leurs portées des composants ensemble pour former une portée de hiérarchie. Les instances de composants peuvent directement accéder à la portée des composants de leurs ancêtres.

La façon la plus facile de montrer ceci est avec des sous-composants imbriqués dont les portées sont implicitement définies comme enfants du composant supérieur.

 Item {
     property color defaultColor: "blue"
 
     ListView {
         delegate: Component {
             Rectangle {
                 color: defaultColor
             }
         }
     }
 }

La hiérarchie des instances de composants permet aux instances du composant délégué d'accéder à la propriété, couleur par défaut defaultColor de l'élément Item. Bien sûr, si le composant délégué possède une propriété appelée defaultColor elle aurait la priorité.

La portée d'une hiérarchie d'instance de composant s'étend aussi aux composants en dehors. Dans l'exemple suivant, le composant TitlePage.qml crée deux instances de TitleText. Même si l'élément TitleText est dans un fichier séparé, il peut toujours avoir accès à la propriété title lorsqu'il est utilisé à l'intérieur de TitlePage. Le QML est un langage à portée dynamique - selon l'endroit où il est utilisé, la propriété title peut être différente.

 // TitlePage.qml
 import QtQuick 1.0
 Item {
     property string title
 
     TitleText {
         size: 22
         anchors.top: parent.top
     }
 
     TitleText {
         size: 18
         anchors.bottom: parent.bottom
     }
 }
 
 // TitleText.qml
 import QtQuick 1.0
 Text {
     property int size
     text: "<b>" + title + "</b>"
     font.pixelSize: size
 }

Les portées dynamiques sont très puissantes mais doivent être utilisées avec prudence pour éviter que le comportement du code QML ne soit difficile à prévoir. En général, elles doivent être utilisées seulement dans les cas où deux composants sont déjà couplés d'une autre façon. Lors de la construction de composants réutilisables, il est préférable d'utiliser une interface avec des propriétés, comme suit :

 // TitlePage.qml
 import QtQuick 1.0
 Item {
     id: root
     property string title
 
     TitleText {
         title: root.title
         size: 22
         anchors.top: parent.top
     }
 
     TitleText {
         title: root.title
         size: 18
         anchors.bottom: parent.bottom
     }
 }
 
 // TitleText.qml
 import QtQuick 1.0
 Text {
     property string title
     property int size
 
     text: "<b>" + title + "</b>"
     font.pixelSize: size
 }

Objet global de JavaScript

En plus de toutes les propriétés que le développeur doit attendre venant de l'objet global de JavaScript, QML ajoute quelques extensions pour faciliter la conception d'interface utilisateur ou des tâches QML. Ces extensions sont décrites dans la documentation de l'objet global de QML.

QML désactive les noms des éléments, identifiants et propriétés qui rentrent en conflit avec l'objet global afin d'éviter toute confusion. Les programmeurs peuvent être certains que Math.min(10, 9) fonctionnera toujours comme voulu !

Remerciements

Merci à Alexandre Laurent pour la traduction ainsi qu'à Dimitry Ernot, Jonathan Courtois et Claude Leloup pour leur relecture !