Liaison de propriétés

Une propriété d’un objet peut se voir attribuer une valeur statique qui reste constante jusqu’à ce qu’une nouvelle valeur lui soit explicitement attribuée. Cependant, pour tirer pleinement parti de QML et de sa prise en charge intégrée des comportements dynamiques des objets, la plupart des objets QML utilisent des liaisons de propriétés.

Les liaisons de propriétés constituent une fonctionnalité essentielle de QML qui permet aux développeurs de définir des relations entre différentes propriétés d'objets. Lorsque la valeur des dépendances d'une propriété change, celle-ci est automatiquement mise à jour conformément à la relation spécifiée.

En arrière-plan, le moteur QML surveille les dépendances de la propriété (c'est-à-dire les variables de l'expression de liaison). Lorsqu'un changement est détecté, le moteur QML réévalue l'expression de liaison et applique le nouveau résultat à la propriété.

Présentation générale

Pour créer une liaison de propriété, on attribue à une propriété une expression JavaScript dont le résultat correspond à la valeur souhaitée. Dans sa forme la plus simple, une liaison peut être une référence à une autre propriété. Prenons l’exemple suivant, dans lequel la hauteur de l’ Rectangle e bleue est liée à la hauteur de son parent :

Rectangle {
    width: 200; height: 200

    Rectangle {
        width: 100
        height: parent.height
        color: "blue"
    }
}

Chaque fois que la hauteur du rectangle parent change, celle du rectangle bleu est automatiquement mise à jour pour prendre la même valeur.

Un lien peut contenir n'importe quelle expression ou instruction JavaScript valide, car QML utilise un moteur JavaScript conforme aux normes. Les liens peuvent accéder aux propriétés d'un objet, appeler des méthodes et utiliser des objets JavaScript intégrés tels que Date et Math. Voici d'autres liens possibles pour l'exemple précédent :

height: parent.height / 2

height: Math.min(parent.width, parent.height)

height: parent.height > 100 ? parent.height : parent.height/2

height: {
    if (parent.height > 100)
        return parent.height
    else
        return parent.height / 2
}

height: someMethodThatReturnsHeight()

Voici un exemple plus complexe impliquant davantage d’objets et de types :

Column {
    id: column
    width: 200
    height: 200

    Rectangle {
        id: topRect
        width: Math.max(bottomRect.width, parent.width/2)
        height: (parent.height / 3) + 10
        color: "yellow"

        TextInput {
            id: myTextInput
            text: "Hello QML!"
        }
    }

    Rectangle {
        id: bottomRect
        width: 100
        height: 50
        color: myTextInput.text.length <= 10 ? "red" : "blue"
    }
}

Dans l'exemple précédent,

• topRect.width dépend de bottomRect.width et column.width
• topRect.height dépend de column.height
• bottomRect.color dépend de myTextInput.text.length

De plus, toutes les propriétés référencées au sein d’une fonction JavaScript qui est elle-même utilisée comme liaison seront réévaluées. Par exemple, dans l’extrait de code ci-dessous, chaque fois que la propriété enabled de l’ Rectangle change, les liaisons pour les propriétés x et y seront réévaluées :

Rectangle {
    x: rectPosition()
    y: rectPosition()
    width: 200
    height: 200
    color: "lightblue"

    function rectPosition() {
        return enabled ? 0 : 100
    }
}

D'un point de vue syntaxique, les liaisons peuvent présenter une complexité arbitraire. Cependant, si une liaison est trop complexe — par exemple si elle comporte plusieurs lignes ou des boucles impératives —, cela peut indiquer qu’elle est utilisée à d’autres fins que la simple description des relations entre propriétés. Les liaisons complexes peuvent nuire aux performances, à la lisibilité et à la maintenabilité du code. Il peut être judicieux de repenser les composants comportant des liaisons complexes, ou au moins d’extraire la liaison dans une fonction distincte. En règle générale, les utilisateurs ne doivent pas se fier à l’ordre d’évaluation des liaisons.

Création de liaisons de propriétés à partir de JavaScript

Une propriété dotée d’un lien est automatiquement mise à jour si nécessaire. Cependant, si une valeur statique est ultérieurement attribuée à la propriété via une instruction JavaScript, le lien sera supprimé.

Par exemple, l'Rectangle ci-dessous garantit initialement que sa propriété height est toujours le double de sa propriété width. Cependant, lorsque la touche espace est enfoncée, la valeur actuelle de width*3 est attribuée à height en tant que valeur statique. Par la suite, la propriété height restera fixée à cette valeur, même si la propriété width change. L'attribution de la valeur statique supprime le lien.

import QtQuick 2.0

Rectangle {
    width: 100
    height: width * 2

    focus: true
    Keys.onSpacePressed: {
        height = width * 3
    }
}

Si l’objectif est de donner au rectangle une hauteur fixe et d’empêcher les mises à jour automatiques, cela ne pose aucun problème. En revanche, si l’objectif est d’établir une nouvelle relation entre width et height, la nouvelle expression de liaison doit alors être placée dans la fonction Qt.binding() :

import QtQuick 2.0

Rectangle {
    width: 100
    height: width * 2

    focus: true
    Keys.onSpacePressed: {
        height = Qt.binding(function() { return width * 3 })
    }
}

Désormais, lorsque l'on appuie sur la touche espace, la hauteur du rectangle continuera à s'ajuster automatiquement pour rester toujours trois fois supérieure à sa largeur.

Débogage de la réécriture des liaisons

Une cause fréquente de bogues dans les applications QML est la réécriture accidentelle de liaisons par des valeurs statiques issues d'instructions JavaScript. Pour aider les développeurs à identifier ce type de problèmes, le moteur QML est capable d'émettre des messages chaque fois qu'une liaison est perdue à la suite d'affectations impératives.

Pour générer ces messages, vous devez activer la sortie d'informations pour la catégorie de journalisation « qt.qml.binding.removal », par exemple en appelant :

QLoggingCategory::setFilterRules(QStringLiteral("qt.qml.binding.removal.info=true"));

Veuillez vous reporter à la documentation d’ QLoggingCategory pour plus d’informations sur l’activation de la sortie des catégories de journalisation.

Notez qu’il est tout à fait raisonnable, dans certaines circonstances, de remplacer les liaisons. Tout message généré par le moteur QML doit être considéré comme une aide au diagnostic, et non nécessairement comme la preuve d’un problème sans enquête plus approfondie.

Utilisation de ` this ` avec les liaisons de propriétés

Lors de la création d’un liaisons de propriété à partir de JavaScript, le mot-clé ` this ` peut être utilisé pour désigner l’objet qui reçoit la liaison. Cela permet de résoudre les ambiguïtés liées aux noms de propriétés.

Par exemple, le gestionnaire « Component.onCompleted » ci-dessous est défini dans la portée de « Item ». Dans cette portée, « width » fait référence à la largeur de « Item », et non à celle de « Rectangle ». Pour lier la propriété « height » de « Rectangle » à sa propre propriété « width », l'expression de liaison doit faire explicitement référence à « this.width » (ou, alternativement, à « rect.width ») :

Item {
    width: 500
    height: 500

    Rectangle {
        id: rect
        width: 100
        color: "yellow"
    }

    Component.onCompleted: {
        rect.height = Qt.binding(function() { return this.width * 2 })
        console.log("rect.height = " + rect.height) // prints 200, not 1000
    }
}