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 !