Synchronizer QML Type

Synchronise les valeurs entre deux ou plusieurs propriétés. En savoir plus…

• Liste de tous les membres, y compris les membres hérités

Propriétés

• sourceObject : QtObject
• sourceProperty : string
• targetObject : QtObject
• targetProperty : string

Signaux

• valueBounced(QtObject object, string property)
• valueIgnored(QtObject object, string property)

Description détaillée

Un objet Synchronizer lie deux ou plusieurs propriétés entre elles de sorte qu’une modification apportée à l’une d’entre elles mette automatiquement à jour toutes les autres. Ce faisant, aucun des liens entre les propriétés n’est rompu. Vous pouvez utiliser Synchronizer si le sens du flux de données entre deux propriétés n’est pas prédéterminé. Par exemple, une variable de type « TextInput » peut être initialisée avec une valeur du modèle, mais doit également mettre à jour cette valeur une fois la modification terminée.

Prenons l’exemple suivant.

Sans Synchronizer

// MyCustomTextInput.qml
Item {
    property string text
    function append(characters: string) { text += characters }
    [...]
}

Vous pourriez être tenté de remplir la propriété ` text ` à partir d’un modèle et de mettre à jour ce dernier à la réception du signal ` textChanged `.

// Does not work!
Item {
    id: root
    property string model: "lorem ipsum"
    MyCustomTextInput {
        text: root.model
        onTextChanged: root.model = text
    }
}

Cela ne fonctionne pas. Lorsque la fonction ` append ` est appelée, la propriété ` text ` est modifiée, et la liaison qui la met à jour à partir de la propriété ` model ` est rompue. La prochaine fois que ` model ` est mise à jour indépendamment, ` text ` n’est plus mise à jour.

Pour résoudre ce problème, vous pouvez omettre complètement la liaison et utiliser uniquement des signaux pour mettre à jour les deux propriétés. Dans ce cas, vous devrez renoncer à la commodité offerte par les liaisons.

Vous pouvez également utiliser Synchronizer.

Avec Synchronizer

Item {
    id: root
    property string model: "lorem ipsum"
    MyCustomTextInput {
        Synchronizer on text {
            property alias source: root.model
        }
    }
}

Synchronizer garantit que, dès que le modèle ou le texte change, l’autre est mis à jour.

Vous pouvez spécifier les propriétés à synchroniser de plusieurs façons :

• En utilisant la syntaxe « on »
• En renseignant les propriétés ` sourceObject ` et ` sourceProperty `
• En renseignant les propriétés ` targetObject ` et ` targetProperty `
• En créant des alias dans le champ d’application du synchroniseur

L'exemple suivant synchronise quatre propriétés différentes, en utilisant toutes les options disponibles :

Item {
    id: root
    property string model: "lorem ipsum"

    MyCustomTextInput {
        Synchronizer on text {
            sourceObject: other
            sourceProperty: "text"

            targetObject: root.children[0]
            targetProperty: "objectName"

            property alias source: root.model
            property alias another: root.objectName
        }
    }

    MyCustomTextInput {
        id: other
    }
}

Si vous le souhaitez, Synchronizer effectuera une synchronisation initiale :

• Si l’un des alias s’appelle source, il sera utilisé pour initialiser les autres propriétés.
• Sinon, si les valeurs attribuées à « sourceObject » et « sourceProperty » désignent une propriété, celle-ci sera utilisée comme source pour la synchronisation initiale.
• Sinon, si la syntaxe « on » est utilisée, la propriété sur laquelle le Synchronizer est créé de cette manière sert de source pour la synchronisation initiale.
• Sinon, aucune synchronisation initiale n’est effectuée. Ce n’est que lorsqu’une des propriétés change que les autres seront mises à jour.

Le Synchronizer effectue automatiquement une suppression des rebonds. Lorsqu’il effectue une synchronisation en utilisant une valeur donnée comme source, il n’accepte pas de nouvelles mises à jour provenant de l’une des propriétés censées être la cible de la mise à jour. Un tel comportement conduirait sinon facilement à des boucles de mise à jour infinies. Le Synchronizer utilise le signal « valueBounced » pour signaler cette condition. De plus, il détecte les propriétés qui refusent silencieusement une mise à jour et émet le signal « valueIgnored » pour celles-ci. Dans ce contexte, le « silence » est déterminé par l’absence de signal de modification après l’appel du setter de la propriété concernée.

Si les propriétés à synchroniser sont de types différents, les coercitions de types QML habituelles sont appliquées.

Documentation sur les propriétés

sourceObject : QtObject

Cette propriété contient la partie « sourceObject » de la paire « sourceObject/sourceProperty », qui, ensemble, permettent de spécifier l'une des propriétés que Synchronizer synchronisera.

sourceProperty : string

Cette propriété « sourceProperty » contient la partie « sourceProperty » du couple « sourceObject » / « sourceProperty » qui, ensemble, permettent de spécifier l'une des propriétés que Synchronizer synchronisera.

targetObject : QtObject

Cette propriété contient la partie « targetObject » du couple « targetObject/targetProperty », qui, ensemble, permettent de spécifier l'une des propriétés que Synchronizer synchronisera.

targetProperty : string

Cette propriété `targetProperty` contient la partie `targetProperty` de la paire ` targetObject/targetProperty` qui, ensemble, permettent de spécifier l'une des propriétés que Synchronizer synchronisera.

Documentation sur les signaux

valueBounced(QtObject object, string property)

Ce signal est émis si l'property de l'object a rejeté une tentative de définition de sa valeur dans le cadre de la synchronisation et a renvoyé une valeur différente en réponse. Ces valeurs rejetées sont ignorées et ne déclenchent pas un nouveau cycle de synchronisation.

valueIgnored(QtObject object, string property)

Ce signal est émis si l'property de l'object n'a pas répondu à une tentative de définition de sa valeur dans le cadre de la synchronisation.