Les bases de la syntaxe QML

QML est un langage multi-paradigme qui permet de définir les objets en fonction de leurs attributs et de la manière dont ils sont liés et réagissent aux changements survenant dans d'autres objets. Contrairement au code purement impératif, où les changements d'attributs et de comportement sont exprimés par une série de déclarations qui sont traitées étape par étape, la syntaxe déclarative de QML intègre les changements d'attributs et de comportement directement dans les définitions des objets individuels. Ces définitions d'attributs peuvent ensuite inclure du code impératif, dans le cas où un comportement d'application personnalisé complexe est nécessaire.

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

Déclarations d'importation

Un document QML peut comporter un ou plusieurs imports en tête de fichier. Un import peut être l'un des éléments suivants

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

Les importations de fichiers JavaScript doivent être qualifiées lors de l'importation, afin que les propriétés et les méthodes qu'ils fournissent puissent être accessibles.

La forme générique des différents imports 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 - Déclarations 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 un arbre 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 à donner à l'objet. Chaque objet peut également déclarer des objets enfants à l'aide de déclarations d'objets imbriqués.

Une déclaration d'objet se compose du nom de son type d'objet, suivi d'un ensemble d'accolades. Tous les attributs et les 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"
}

Elle déclare un objet de type Rectangle, suivi d'un ensemble 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. En d'autres termes, si le code source est complété par une déclaration d'importation qui importe le module QtQuick (pour rendre le type Rectangle disponible), comme ci-dessous :

import QtQuick 2.0

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

Lorsqu'il est 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" }

Il est évident que l'objet Rectangle déclaré dans cet exemple est très simple, puisqu'il ne définit 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 QML Object Attributes. En outre, une déclaration d'objet peut définir des objets enfants, comme indiqué 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. Ainsi, toute déclaration d'objet déclare implicitement un arbre d'objets qui peut contenir un nombre quelconque 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, il crée un arbre d'objets avec un objet Rectangle à la racine ; cet objet a un objet enfant Gradient, qui à son tour a deux enfants GradientStop.

Notez cependant qu'il s'agit d'une relation parent-enfant dans le contexte de l'arbre 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 pour 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 basés sur 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 à son parent dans l'arbre des objets. Dans ce cas, il s'agit d'une seule et même chose : l'objet Rectangle est le parent de l'objet Text à la fois dans le contexte de l'arbre d'objets QML et dans le contexte 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'arbre d'objets ne peut pas être modifié à partir de QML.

(En outre, remarquez 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 la propriété par défaut du type pour permettre cette syntaxe plus pratique).

Voir la documentation sur le parent visuel pour plus d'informations sur le concept de parent visuel 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 multilignes 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 ce que fait une section de code, que ce soit pour s'y référer ultérieurement ou pour expliquer la mise en œuvre à d'autres personnes.

Les commentaires peuvent également être utilisés pour empêcher l'exécution du code, ce qui est parfois utile pour localiser les 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.