Binding QML Type

Permet la création arbitraire de liaisons de propriétés. Plus d'informations...

• 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 entraînent une dépendance entre les propriétés de différents objets.

Liaison avec 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 la propriété d'une classe exportée vers QML par C++. Vous pouvez utiliser le type Binding pour établir cette dépendance, en liant 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" en QML, vous pouvez utiliser le type Binding pour mettre à jour la propriété enteredText.

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

Lorsque text est modifié, la propriété C++ enteredText est automatiquement mise à jour.

Liaisons conditionnelles

Dans certains cas, vous pouvez souhaiter modifier la valeur d'une propriété lorsqu'une certaine condition est remplie, mais ne pas la modifier dans le cas contraire. Souvent, il n'est pas possible de le faire 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 lorsque vous relâchez la souris. En effet, la valeur de la liaison est indéfinie lorsque la souris n'est pas enfoncée.

// 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é.

Toutefois, la liaison avec la propriété value de Binding est toujours évaluée sans condition, même si when est false.

Cela peut provoquer des avertissements lorsque la liaison est utilisée, par exemple, pour éviter qu'une valeur soit 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 a un id, vous pouvez utiliser la syntaxe décrite dans Multiple targets in one Binding, qui fait également en sorte que l'expression de liaison ne s'exécute que lorsque le Binding est activé :

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

• Vous pouvez répéter la vérification dans l'expression de liaison et revenir plus tôt :

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

Plusieurs cibles dans une même liaison

Vous pouvez spécifier plusieurs liaisons pour le même objet dans un élément de liaison :

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 de liaison :

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é indique si la liaison doit être retardée.

Une liaison retardée ne mettra pas immédiatement à jour la cible, mais attendra jusqu'à ce que la file d'attente des événements ait été vidée. Ceci peut être utilisé comme une optimisation, ou pour éviter que des valeurs intermédiaires ne soient assignées.

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 permet d'accéder à une propriété de type valeur. Par exemple, vous ne devez utiliser cette propriété que si vous ne pouvez pas fournir la cible de liaison de manière déclarative :

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 la liaison de manière déclarative. L'extrait de code suivant est équivalent à la liaison ci-dessus, mais il est plus compact :

Binding { item.rectangle.x: 100 }

restoreMode : enumeration

Cette propriété peut être utilisée pour décrire si et comment la valeur originale 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 n'a pas d'attribut id (par exemple, lorsque la cible est un singleton). Dans le cas contraire, les deux morceaux de code suivants sont équivalents :

Binding { contactName.text: name }

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

Le premier est beaucoup plus compact, mais vous ne pouvez pas remplacer l'objet ou la propriété cible au moment de l'exécution. Avec le second, c'est possible.

value : var

La valeur à définir sur 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 fournir la cible de liaison de manière déclarative. Dans le cas contraire, vous pouvez directement lier la cible.

when : bool

Cette propriété détermine si la liaison est active. Elle doit être définie par une expression qui s'évalue à true 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.