Binding QML Type

Permite la creación arbitraria de enlaces de propiedades. Más...

• Lista de todos los miembros, incluidos los heredados

Propiedades

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

Descripción detallada

En QML, los enlaces de propiedades resultan en una dependencia entre las propiedades de diferentes objetos.

Vinculación a una propiedad inaccesible

A veces es necesario vincular una propiedad de un objeto a la de otro objeto que no es instanciado directamente por QML, como una propiedad de una clase exportada a QML por C++. Puede utilizar el tipo Binding para establecer esta dependencia, vinculando cualquier valor a la propiedad de cualquier objeto.

Por ejemplo, en una aplicación C++ que asigna una propiedad "app.enteredText" a QML, puede utilizar Binding para actualizar la propiedad enteredText.

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

Cuando text cambie, la propiedad de C++ enteredText se actualizará automáticamente.

Enlaces condicionales

En algunos casos, es posible que desee modificar el valor de una propiedad cuando se cumpla una determinada condición, pero dejarla sin modificar en caso contrario. A menudo, no es posible hacer esto con vinculaciones directas, ya que tienes que suministrar valores para todas las ramas posibles.

Por ejemplo, el siguiente fragmento de código produce una advertencia cada vez que se suelta el ratón. Esto se debe a que el valor del enlace no está definido cuando el ratón no está pulsado.

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

El tipo Binding puede evitar esta advertencia.

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

El tipo de enlace restaura cualquier enlace directo previamente establecido en la propiedad.

Sin embargo, el enlace a la propiedad Binding's value se sigue evaluando incondicionalmente, incluso cuando when es false.

Esto puede causar advertencias cuando el enlace se utiliza, por ejemplo, para evitar que un valor sea null:

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

Hay dos formas de evitar este problema:

• Si el objetivo tiene una propiedad id, puede utilizar la sintaxis descrita en Multiple targets in one Binding, que también hace que la expresión de vinculación sólo se ejecute cuando Binding está activada:

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

• Puede repetir la comprobación en la vinculación y devolverla antes:

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

Múltiples objetivos en un enlace

Es posible especificar varios destinos para el mismo objeto en un elemento Binding:

Text {
    id: t1
}

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

También puede especificar varias vinculaciones con diferentes objetos de destino en un único elemento Binding:

Text {
    id: t1
}

Text {
    id: t2
}

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

Véase también Qt Qml.

Documentación de propiedades

delayed : bool

Esta propiedad indica si la vinculación debe retrasarse.

Una vinculación retardada no actualizará inmediatamente el destino, sino que esperará hasta que la cola de eventos se haya vaciado. Esto puede utilizarse como optimización, o para evitar que se asignen valores intermedios.

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

property : string

La propiedad a actualizar.

Puede ser una propiedad de grupo si la expresión da como resultado el acceso a una propiedad de tipo valor. Por ejemplo:

Item {
    id: item

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

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

Sólo necesita utilizar esta propiedad si no puede proporcionar el destino de la vinculación de forma declarativa. El siguiente fragmento de código es equivalente al enlace anterior, pero más compacto:

Binding { item.rectangle.x: 100 }

restoreMode : enumeration

Esta propiedad se puede utilizar para describir si se debe restaurar el valor original cuando se desactiva la vinculación, y cómo hacerlo.

Los valores posibles son

El valor por defecto es Binding.RestoreBindingOrValue.

target : QtObject

El objeto que se va a actualizar. Debe utilizar esta propiedad si el destino de la vinculación no tiene un atributo id (por ejemplo, cuando el destino es un singleton). En caso contrario, los dos fragmentos de código siguientes son equivalentes:

Binding { contactName.text: name }

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

El primero es mucho más compacto, pero no se puede reemplazar el objeto o la propiedad de destino en tiempo de ejecución. Con el segundo sí.

value : var

El valor que se establecerá en el objeto y la propiedad de destino. Puede ser una constante (que no es muy útil), o una expresión vinculada.

Sólo es necesario utilizar esta propiedad si no se puede proporcionar el destino de vinculación de forma declarativa. De lo contrario, puede enlazar directamente con el objetivo.

when : bool

Esta propiedad indica si el enlace está activo. Debe establecerse como una expresión que se evalúe como true cuando se desee que el enlace esté activo.

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

Por defecto, cualquier enlace o valor establecido anteriormente se restaura cuando el enlace se vuelve inactivo. Puede personalizar el comportamiento de restauración utilizando la propiedad restoreMode.

Véase también restoreMode.