Définition de types d'objets via des documents QML

L'une des fonctionnalités principales de QML est qu'il permet de définir facilement et de manière légère des types d'objets QML via des documents QML, afin de répondre aux besoins de chaque application QML. Le module standard Qt Quick fournit divers types tels que Rectangle, Text et Image pour la création d’une application QML ; au-delà de ceux-ci, vous pouvez facilement définir vos propres types QML afin de les réutiliser au sein de votre application. Cette capacité à créer vos propres types constitue la base de toute application QML.

Définition d’un type d’objet à l’aide d’un fichier QML

Nommage des types d’objets QML personnalisés

Pour créer un type d’objet, un document QML doit être placé dans un fichier texte nommé <TypeName>.qml, où <TypeName> correspond au nom souhaité pour le type. Le nom du type doit respecter les contraintes suivantes :

• Il doit être composé de caractères alphanumériques ou de traits de soulignement.
• Il doit commencer par une lettre majuscule.

Ce document est alors automatiquement reconnu par le moteur comme une définition de type QML. De plus, un type défini de cette manière est automatiquement mis à la disposition des autres fichiers QML situés dans le même répertoire local, car le moteur effectue une recherche dans le répertoire immédiat lors de la résolution des noms de types QML.

Définition personnalisée d’un type QML

Par exemple, voici un document qui déclare un ` Rectangle ` avec un enfant ` MouseArea`. Le document a été enregistré dans un fichier nommé ` SquareButton.qml` :

// SquareButton.qml
import QtQuick 2.0

Rectangle {
    property int side: 100
    width: side; height: side
    color: "red"

    MouseArea {
        anchors.fill: parent
        onClicked: console.log("Button clicked!")
    }
}

Comme le fichier s’appelle SquareButton.qml, celui-ci peut désormais être utilisé en tant que type nommé SquareButton par n’importe quel autre fichier QML situé dans le même répertoire. Par exemple, s’il existait un fichier myapplication.qml dans le même répertoire, celui-ci pourrait faire référence au type SquareButton:

// myapplication.qml
import QtQuick 2.0

SquareButton {}

Cela crée un « Rectangle » rouge de 100 x 100 contenant un « MouseArea », tel que défini dans SquareButton.qml. Lorsque ce document myapplication.qml est chargé par le moteur, celui-ci charge le document SquareButton.qml en tant que composant et l’instancie pour créer un objet SquareButton.

Le type SquareButton encapsule l’arborescence des objets QML déclarés dans SquareButton.qml. Lorsque le moteur QML instancie un objet SquareButton à partir de ce type, il instancie un objet issu de l’arborescence Rectangle déclarée dans SquareButton.qml.

Composants intégrés

Il peut parfois s’avérer peu pratique de créer un nouveau fichier pour un type, par exemple lorsque l’on réutilise un petit délégué dans plusieurs vues. Si vous n’avez pas réellement besoin d’exposer le type, mais seulement d’en créer une instance, Component est une option envisageable. Mais si vous souhaitez déclarer des propriétés avec les types de composants, ou si vous souhaitez l’utiliser dans plusieurs fichiers, l’ Component e n’est pas une option. Dans ce cas, vous pouvez utiliser des composants en ligne. Les composants en ligne déclarent un nouveau composant à l’intérieur d’un fichier. La syntaxe pour cela est la suivante

component <component name> : BaseType {
    // declare properties and bindings here
}

Dans le fichier qui déclare le composant en ligne, le type peut être référencé simplement par son nom.

// Images.qml
import QtQuick

Item {
    component LabeledImage: Column {
        property alias source: image.source
        property alias caption: text.text

        Image {
            id: image
            width: 50
            height: 50
        }
        Text {
            id: text
            font.bold: true
        }
    }

    Row {
        LabeledImage {
            id: before
            source: "before.png"
            caption: "Before"
        }
        LabeledImage {
            id: after
            source: "after.png"
            caption: "After"
        }
    }
    property LabeledImage selectedImage: before
}

Dans les autres fichiers, il doit être préfixé par le nom du composant qui le contient.

// LabeledImageBox.qml
import QtQuick

Rectangle {
    property alias caption: image.caption
    property alias source: image.source
    border.width: 2
    border.color: "black"
    Images.LabeledImage {
        id: image
    }
}

// A.qml
import QtQuick

Item {
    id: root
    property string message: "From A"
    component MyInlineComponent : Item {
        Component.onCompleted: console.log(root.message)
    }
}
// B.qml
import QtQuick

Item {
    A.MyInlineComponent {}
}

Importation de types définis en dehors du répertoire courant

Si SquareButton.qml ne se trouvait pas dans le même répertoire que myapplication.qml, le type SquareButton devrait être explicitement rendu disponible via une instruction d’import dans myapplication.qml. Il pourrait être importé à partir d’un chemin relatif sur le système de fichiers, ou en tant que module installé ; voir la section « module » pour plus de détails.

Attributs accessibles des types personnalisés

La définition de l’objet racine dans un fichier .qml définit les attributs disponibles pour un type QML. Toutes les propriétés, tous les signaux et toutes les méthodes appartenant à cet objet racine — qu’ils soient déclarés de manière personnalisée ou qu’ils proviennent du type QML de l’objet racine — sont accessibles de l’extérieur et peuvent être lus et modifiés pour les objets de ce type.

Par exemple, le type d’objet racine dans le fichier SquareButton.qml ci-dessus est Rectangle. Cela signifie que toutes les propriétés définies par le type Rectangle peuvent être modifiées pour un objet SquareButton. Le code ci-dessous définit trois objets SquareButton avec des valeurs personnalisées pour certaines des propriétés de l’objet racine Rectangle du type SquareButton:

// application.qml
import QtQuick 2.0

Column {
    SquareButton { side: 50 }
    SquareButton { x: 50; color: "blue" }
    SquareButton { radius: 10 }
}

Les attributs accessibles aux objets du type QML personnalisé incluent toutes les propriétés, méthodes et signaux personnalisés qui ont été définis en plus pour un objet. Par exemple, supposons que l’ Rectangle dans SquareButton.qml ait été défini comme suit, avec des propriétés, méthodes et signaux supplémentaires :

// SquareButton.qml
import QtQuick 2.0

Rectangle {
    id: root

    property bool pressed: mouseArea.pressed

    signal buttonClicked(real xPos, real yPos)

    function randomizeColor() {
        root.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1)
    }

    property int side: 100
    width: side; height: side
    color: "red"

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        onClicked: (mouse)=> root.buttonClicked(mouse.x, mouse.y)
    }
}

Tout objet ` SquareButton ` pourrait utiliser la propriété ` pressed `, le signal ` buttonClicked ` et la méthode ` randomizeColor() ` qui ont été ajoutés à l’objet racine ` Rectangle` :

// application.qml
import QtQuick 2.0

SquareButton {
    id: squareButton

    onButtonClicked: (xPos, yPos)=> {
        console.log("Clicked", xPos, yPos)
        randomizeColor()
    }

    Text { text: squareButton.pressed ? "Down" : "Up" }
}

Notez qu’aucune des valeurs « id » définies dans « SquareButton.qml » n’est accessible aux objets « SquareButton », car les valeurs d’identifiant ne sont accessibles qu’au sein de la portée du composant dans lequel celui-ci est déclaré. La définition de l’objet SquareButton ci-dessus ne peut pas faire référence à mouseArea pour désigner l’enfant MouseArea, et si son id était root plutôt que squareButton, cela n’entrerait pas en conflit avec le id de même valeur pour l’objet racine défini dans SquareButton.qml, car les deux seraient déclarés dans des portées distinctes.