Notions de base sur la syntaxe du QML

QML est un langage multiparadigme qui permet de définir des objets en fonction de leurs attributs, ainsi que de la manière dont ils interagissent et réagissent aux modifications apportées à d’autres objets. Contrairement au code purement impératif, où les modifications d’attributs et de comportement sont exprimées par une série d’instructions traitées étape par étape, la syntaxe déclarative de QML intègre directement les modifications d’attributs et de comportement dans les définitions des objets individuels. Ces définitions d’attributs peuvent ensuite inclure du code impératif, lorsque le comportement d’une application personnalisée est complexe.

Le code source QML est généralement chargé par le moteur via des documents QML, qui sont des documents autonomes contenant du code QML. Ceux-ci peuvent être utilisés pour définir des types d’objets QML qui peuvent ensuite être réutilisés dans toute l’application. Notez que les noms de types doivent commencer par une majuscule pour pouvoir être déclarés comme types d’objets QML dans un fichier QML.

Instructions d’importation

Un document QML peut comporter une ou plusieurs instructions d'importation en début de fichier. Une instruction d'importation peut prendre l'une des formes suivantes :

• un module QML
• un répertoire relatif contenant des définitions de types sous forme de documents QML
• un fichier JavaScript

Les importations de fichiers JavaScript doivent être qualifiées lors de l'importation, afin de pouvoir accéder aux propriétés et méthodes qu'elles fournissent.

La forme générique des différentes importations est la suivante :

• import <ModuleIdentifier> [<Version.Number>] [as <Qualifier>]
• import "<Directory>"
• import "<JavaScriptFile>" [as <ScriptIdentifier>]

Exemples :

• import QtQuick 2.0
• import QtQuick.LocalStorage 2.0 as Database
• import "../privateComponents"
• import "somefile.js" as Script

Veuillez consulter la documentation « Syntaxe QML - Instructions d'importation » pour obtenir des informations détaillées sur les importations QML.

Déclarations d'objets

D'un point de vue syntaxique, un bloc de code QML définit une arborescence d'objets QML à créer. Les objets sont définis à l'aide de déclarations d'objets qui décrivent le type d'objet à créer ainsi que les attributs à lui attribuer. Chaque objet peut également déclarer des objets enfants à l'aide de déclarations d'objets imbriquées.

Une déclaration d'objet se compose du nom de son type d'objet, suivi d'une paire d'accolades. Tous les attributs et objets enfants sont ensuite déclarés à l'intérieur de ces accolades.

Voici une déclaration d'objet simple :

Rectangle {
    width: 100
    height: 100
    color: "red"
}

Cela déclare un objet de type ` Rectangle`, suivi d’une paire d’accolades qui englobe les attributs définis pour cet objet. Le type ` Rectangle ` est un type mis à disposition par le module ` QtQuick `, et les attributs définis dans ce cas sont les valeurs des propriétés ` width`, ` height ` et ` color ` du rectangle. (Il s’agit de propriétés mises à disposition par le type ` Rectangle `, comme décrit dans la documentation Rectangle.)

L’objet ci-dessus peut être chargé par le moteur s’il fait partie d’un document QML. Autrement dit, si le code source est complété par une instruction d’importation qui importe le module ` QtQuick ` (afin de rendre le type ` Rectangle ` disponible), comme ci-dessous :

import QtQuick 2.0

Rectangle {
    width: 100
    height: 100
    color: "red"
}

Une fois placé dans un fichier .qml et chargé par le moteur QML, le code ci-dessus crée un objet Rectangle en utilisant le type Rectangle fourni par le module QtQuick:

Rectangle { width: 100; height: 100; color: "red" }

De toute évidence, l’objet ` Rectangle ` déclaré dans cet exemple est en effet très simple, puisqu’il ne définit rien de plus que quelques valeurs de propriétés. Pour créer des objets plus utiles, une déclaration d’objet peut définir de nombreux autres types d’attributs : ceux-ci sont abordés dans la documentation relative aux attributs d’objet QML. De plus, une déclaration d’objet peut définir des objets enfants, comme expliqué ci-dessous.

Objets enfants

Toute déclaration d’objet peut définir des objets enfants par le biais de déclarations d’objets imbriquées. De cette manière, toute déclaration d’objet déclare implicitement une arborescence d’objets pouvant contenir un nombre illimité d’objets enfants.

Par exemple, la déclaration d’objet Rectangle ci-dessous inclut une déclaration d’objet Gradient, qui contient à son tour deux déclarations GradientStop:

import QtQuick 2.0

Rectangle {
    width: 100
    height: 100

    gradient: Gradient {
        GradientStop { position: 0.0; color: "yellow" }
        GradientStop { position: 1.0; color: "green" }
    }
}

Lorsque ce code est chargé par le moteur, celui-ci crée une arborescence d’objets dont la racine est l’objet ` Rectangle ` ; cet objet possède un objet enfant ` Gradient `, qui possède lui-même deux enfants ` GradientStop `.

Notez toutefois qu’il s’agit d’une relation parent-enfant dans le contexte de l’arborescence d’objets QML, et non dans le contexte de la scène visuelle. Le concept de relation parent-enfant dans une scène visuelle est fourni par le type Item du module QtQuick, qui est le type de base de la plupart des types QML, car la plupart des objets QML sont destinés à être rendus visuellement. Par exemple, Rectangle et Text sont tous deux des types dérivés de ` Item`, et ci-dessous, un objet ` Text ` a été déclaré comme enfant visuel d’un objet ` Rectangle ` :

import QtQuick 2.0

Rectangle {
    width: 200
    height: 200
    color: "red"

    Text {
        anchors.centerIn: parent
        text: "Hello, QML!"
    }
}

Lorsque l’objet Text fait référence à sa valeur parent dans le code ci-dessus, il fait référence à son parent visuel, et non au parent dans l’arborescence des objets. Dans ce cas, les deux sont identiques : l’objet Rectangle est le parent de l’objet Text aussi bien dans le contexte de l’arborescence d’objets QML que dans celui de la scène visuelle. Cependant, alors que la propriété parent peut être modifiée pour changer le parent visuel, le parent d’un objet dans le contexte de l’arborescence d’objets ne peut pas être modifié depuis QML.

(Notez également que l’objet ` Text ` a été déclaré sans être affecté à une propriété de ` Rectangle`, contrairement à l’exemple précédent qui affectait un objet ` Gradient ` à la propriété ` gradient ` du rectangle. Cela s’explique par le fait que la propriété ` children ` de ` Item ` a été définie comme propriété par défaut du type afin de permettre cette syntaxe plus pratique.)

Consultez la documentation sur la parenté visuelle pour plus d'informations sur le concept de parenté visuelle avec le type ` Item `.

Commentaires

La syntaxe des commentaires en QML est similaire à celle de JavaScript :

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

Text {
    text: "Hello world!"    //a basic greeting
    /*
        We want this text to stand out from the rest so
        we give it a large size and different font.
     */
    font.family: "Helvetica"
    font.pointSize: 24
}

Les commentaires sont ignorés par le moteur lors du traitement du code QML. Ils sont utiles pour expliquer le fonctionnement d’une section de code, que ce soit pour s’y référer ultérieurement ou pour expliquer l’implémentation à d’autres personnes.

Les commentaires peuvent également être utilisés pour empêcher l'exécution du code, ce qui s'avère parfois utile pour localiser des problèmes.

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

Dans l’exemple ci-dessus, l’objet ` Text ` aura une opacité normale, puisque la ligne `opacity: 0.5` a été transformée en commentaire.