Binding QML Type

Permet de créer librement des liaisons de propriétés. En savoir plus…

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

Propriétés

• delayed : bool
• property : string
• restoreMode : enumeration
• target : QtObject
• value : var
• when : bool

Description détaillée

En QML, les liaisons de propriétés créent une dépendance entre les propriétés de différents objets.

Liaison à une propriété inaccessible

Il est parfois nécessaire de lier la propriété d'un objet à celle d'un autre objet qui n'est pas directement instancié par QML, comme une propriété d'une classe exportée vers QML par C++. Vous pouvez utiliser le type Binding pour établir cette dépendance ; cela permet de lier n'importe quelle valeur à la propriété de n'importe quel objet.

Par exemple, dans une application C++ qui mappe une propriété « app.enteredText » vers QML, vous pouvez utiliser Binding pour mettre à jour la propriété enteredText.

TextEdit { id: myTextField; text: "Please type here..." }
Binding { app.enteredText: myTextField.text }

Lorsque « text » change, la propriété C++ « enteredText » se met automatiquement à jour.

Liaisons conditionnelles

Dans certains cas, vous pouvez souhaiter modifier la valeur d’une propriété lorsqu’une certaine condition est remplie, mais la laisser inchangée dans le cas contraire. Souvent, cela n’est pas possible avec des liaisons directes, car vous devez fournir des valeurs pour toutes les branches possibles.

Par exemple, l'extrait de code ci-dessous génère un avertissement chaque fois que vous relâchez le bouton de la souris. En effet, la valeur de la liaison est indéfinie lorsque le bouton de la souris n'est pas enfoncé.

// produces warning: "Unable to assign [undefined] to double value"
targetProperty: if (mouse.pressed) mouse.mouseX

Le type « Binding » permet d’éviter cet avertissement.

Binding on targetProperty {
    when: mouse.pressed
    value: mouse.mouseX
}

Le type Binding rétablit toutes les liaisons directes précédemment définies sur la propriété.

Cependant, le lien vers la propriété value de Binding est toujours évalué sans condition, même lorsque when est false.

Cela peut générer des avertissements lorsque la liaison est, par exemple, utilisée pour empêcher qu’une valeur ne soit de type null:

Binding on targetProperty {
    when: root.object !== null
    //  produces warning: "TypeError: Cannot read property 'someProperty' of null"
    value: root.object.someProperty
}

Il existe deux façons d’éviter ce problème :

• Si la cible dispose d’une restriction de type « id », vous pouvez utiliser la syntaxe décrite à l’adresse Multiple targets in one Binding, qui fait également en sorte que l’expression de liaison ne s’exécute que lorsque la restriction de type « Binding » est activée :

  Binding {
      when: root.object !== null
      root.targetProperty: root.object.someProperty
  }

• Vous pouvez répéter la vérification dans la liaison et sortir prématurément :

  Binding on targetProperty {
      when: root.object !== null
      value: {
          if (root.object === null)
              return
          return root.object.someProperty
      }
  }

Plusieurs cibles dans un seul élément `Binding`

Vous pouvez spécifier plusieurs liaisons vers le même objet dans un seul élément `Binding` :

Text {
    id: t1
}

Binding {
    t1 {
        color: "#00FF00"
        text: "green text"
    }
}

Vous pouvez également spécifier plusieurs liaisons avec des objets cibles différents dans un seul élément « Binding » :

Text {
    id: t1
}

Text {
    id: t2
}

Binding {
    t1.text: "Foo"
    t2.text: "Bar"
}

Voir aussi Qt Qml.

Documentation sur les propriétés

delayed : bool

Cette propriété détermine si la liaison doit être différée.

Une liaison différée ne mettra pas immédiatement à jour la cible, mais attendra que la file d'attente des événements ait été vidée. Cela peut être utilisé à des fins d'optimisation ou pour empêcher l'affectation de valeurs intermédiaires.

Binding {
    contactName.text.value: givenName + " " + familyName
    when: list.ListView.isCurrentItem
    delayed: true
}

property : string

La propriété à mettre à jour.

Il peut s'agir d'une propriété de groupe si l'expression aboutit à l'accès à une propriété de type valeur. Par exemple :

Item {
    id: item

    property rect rectangle: Qt.rect(0, 0, 200, 200)
}

Binding {
    target: item
    property: "rectangle.x"
    value: 100
}

Vous ne devez utiliser cette propriété que si vous ne pouvez pas fournir la cible de liaison de manière déclarative. L'extrait de code suivant est équivalent à la liaison ci-dessus, mais plus concis :

Binding { item.rectangle.x: 100 }

restoreMode : enumeration

Cette propriété permet de définir si et comment la valeur d'origine doit être restaurée lorsque la liaison est désactivée.

Les valeurs possibles sont les suivantes :

La valeur par défaut est « Binding.RestoreBindingOrValue ».

target : QtObject

L'objet à mettre à jour. Vous devez utiliser cette propriété si la cible de la liaison ne dispose pas d'un attribut ` id ` (par exemple, lorsque la cible est un singleton). Sinon, les deux extraits de code suivants sont équivalents :

Binding { contactName.text: name }

Binding {
    target: contactName
    property: "text"
    value: name
}

Le premier est beaucoup plus concis, mais il ne permet pas de remplacer l'objet ou la propriété cible lors de l'exécution. Le second, lui, le permet.

value : var

Valeur à attribuer à l'objet et à la propriété cibles. Il peut s'agir d'une constante (ce qui n'est pas très utile) ou d'une expression liée.

Vous ne devez utiliser cette propriété que si vous ne pouvez pas spécifier la cible de liaison de manière déclarative. Sinon, vous pouvez lier directement à la cible.

when : bool

Cette propriété s'applique lorsque la liaison est active. Elle doit être définie sur une expression dont la valeur est « vrai » lorsque vous souhaitez que la liaison soit active.

Binding {
    contactName.text: name
    when: list.ListView.isCurrentItem
}

Par défaut, toute liaison ou valeur définie précédemment est restaurée lorsque la liaison devient inactive. Vous pouvez personnaliser le comportement de restauration à l'aide de la propriété restoreMode.

Voir également restoreMode.