Propiedades vinculables de Qt
Qt ofrece propiedades vinculables. Las propiedades vinculables son aquellas que tienen un valor o que se especifican mediante cualquier función de C++, normalmente una expresión lambda de C++. En caso de que se especifiquen mediante una función de C++, se actualizan automáticamente cada vez que cambian sus dependencias.
Las propiedades vinculables se implementan en la clase ` QProperty`, que consta del objeto de datos y un puntero a una estructura de datos de gestión, y en la clase ` QObjectBindableProperty`, que consta únicamente del objeto de datos y utiliza la clase encapsuladora ` QObject ` para almacenar el puntero a la estructura de datos de gestión.
¿Por qué utilizar propiedades vinculables?
Los enlaces de propiedades son una de las características fundamentales de QML. Permiten especificar relaciones entre diferentes propiedades de objetos y actualizar automáticamente los valores de las propiedades cada vez que cambian sus dependencias. Las propiedades vinculables permiten lograr lo mismo no solo en el código QML, sino también en C++. El uso de propiedades vinculables puede ayudar a simplificar tu programa, al eliminar gran parte del código repetitivo necesario para realizar un seguimiento y reaccionar ante las actualizaciones de las dependencias de diferentes objetos.
El ejemplo introductorio que aparece a continuación muestra el uso de las propiedades vinculables en código C++. También puedes consultar el ejemplo de propiedades vinculables para ver cómo estas pueden ayudarte a mejorar tu código.
Ejemplo introductorio
La expresión de enlace calcula el valor leyendo los valores de otras propiedades « QProperty ». Esta dependencia se gestiona en segundo plano. Cada vez que se detecta un cambio en la dependencia de cualquier propiedad, la expresión de enlace se vuelve a evaluar y el nuevo resultado se aplica a la propiedad. Por ejemplo:
QProperty<QString> firstname("John");
QProperty<QString> apellido("Smith");
QProperty<int> edad(41);
QProperty<QString> nombreCompleto;
nombreCompleto.setBinding([&]() { return nombre.value() + " " + apellido.value() + " edad: " + QString::number(edad.valor()); });
qDebug() << fullname.value(); // Prints "John Smith age: 41"
nombre = "Emma"; // Provoca una reevaluación de los enlaces
qDebug() << fullname.value(); // Prints the new value "Emma Smith age: 41"
// Se acerca el cumpleaños
age.setValue(age.value() + 1); // Activa la reevaluación
qDebug() << fullname.value(); // Prints "Emma Smith age: 42"Cuando se asigna un nuevo valor a la propiedad ` firstname `, se vuelve a evaluar la expresión de enlace de ` fullname `. Por lo tanto, cuando la última instrucción ` qDebug() ` intenta leer el valor del nombre de la propiedad ` fullname `, se devuelve el nuevo valor.
Dado que los enlaces son funciones de C++, pueden realizar cualquier operación posible en C++. Esto incluye llamar a otras funciones. Si dichas funciones acceden a valores almacenados en QProperty, se convierten automáticamente en dependencias del enlace.
Las expresiones de enlace pueden utilizar propiedades de cualquier tipo, por lo que en el ejemplo anterior la edad es un entero y se integra en el valor de cadena mediante la conversión a entero, pero la dependencia se rastrea por completo.
Métodos getter y setter de propiedades vinculables
Cuando una clase tiene una propiedad vinculable, ya sea mediante ` QProperty ` o ` QObjectBindableProperty`, hay que prestar especial atención al definir los métodos getter y setter para dicha propiedad.
Métodos getter de propiedades vinculables
Para garantizar el correcto funcionamiento del sistema automático de seguimiento de dependencias, todas las rutas de código posibles en un getter deben leer el objeto de propiedad subyacente. Además, no se debe escribir en la propiedad dentro del getter. Los patrones de diseño que recalculan o actualizan cualquier dato en el getter no son compatibles con las propiedades vinculables.
Por lo tanto, se recomienda utilizar únicamente getter triviales con propiedades vinculables.
Setter de propiedades vinculables
Para garantizar el correcto funcionamiento del sistema automático de seguimiento de dependencias, todas las rutas de código posibles en un setter deben escribir en el objeto de propiedad subyacente, incluso si el valor no ha cambiado.
Cualquier otro código en un setter tiene una alta probabilidad de ser incorrecto. Cualquier código que realice actualizaciones basadas en el nuevo valor es muy probable que sea un error, ya que este código no se ejecutará cuando la propiedad se modifique a través de un enlace.
Por lo tanto, se recomienda utilizar únicamente setters triviales con propiedades vinculables.
Escritura en una propiedad vinculable
Las propiedades vinculables informan a sus propiedades dependientes de cada cambio. Esto podría activar controladores de cambios, que a su vez podrían llamar a código arbitrario. Por lo tanto, cada escritura en una propiedad vinculable debe inspeccionarse cuidadosamente. Podrían producirse los siguientes problemas.
Escribir valores intermedios en propiedades vinculables
Las propiedades vinculables no deben utilizarse como variables en algoritmos. Cada valor escrito se comunicaría a las propiedades dependientes. Por ejemplo, en el código siguiente, a las demás propiedades que dependen de myProperty se les informaría primero del cambio a 42 y, a continuación, del cambio a maxValue.
myProperty = somecomputation(); // returning, say, 42
if (myProperty.value() > maxValue)
myProperty = maxValue;En su lugar, realiza el cálculo en una variable independiente. El uso correcto se muestra en el siguiente ejemplo.
int newValue = someComputation();
if (newValue > maxValue)
newValue = maxValue;
myProperty = newValue; // only write to the property onceEscribir en propiedades vinculables en estados transitorios
Cuando una propiedad vinculable es miembro de una clase, cada escritura en dicha propiedad podría exponer el estado actual al exterior. Por lo tanto, las propiedades vinculables no deben escribirse en estados transitorios, cuando no se cumplen las invariantes de la clase.
Por ejemplo, en una clase que representa un círculo y que mantiene consistentes dos miembros, «radius» y «area», un setter podría tener este aspecto (donde «radius» es una propiedad vinculable):
void setRadius(double newValue)
{
radius = newValue; // this might trigger change handlers
area = M_PI * radius * radius;
emit radiusChanged();
}En este caso, el código ejecutado en los controladores de cambios podría utilizar el círculo, que ya tiene el nuevo radio, pero aún conserva el área anterior.
Propiedades vinculables con setters y getters virtuales
Los setters y getters de propiedades deberían ser, normalmente, mínimos y no hacer nada más que establecer el valor de la propiedad; por lo tanto, no suele ser adecuado que dichos setters y getters sean virtuales. No hay nada que tenga sentido que haga la clase derivada.
Sin embargo, algunas clases de Qt pueden tener propiedades con setters virtuales. Al crear una subclase de una clase de Qt de este tipo, la sobrescritura de dichos setters requiere un cuidado especial.
En cualquier caso, debe llamarse a la implementación base para que el enlace funcione correctamente.
A continuación se ilustra este enfoque.
void DerivedClass::setValue(int val)
{
// do something
BaseClass::setValue(val);
// probably do something else
}Todas las reglas y recomendaciones comunes relativas a la escritura en propiedades enlazables también se aplican aquí. En cuanto se invoca la implementación de la clase base, se notifica a todos los observadores el cambio en la propiedad. Esto significa que deben cumplirse las invariantes de clase antes de invocar la implementación de la clase base.
En el caso excepcional en que sean necesarios dichos getter o setter virtuales, la clase base debe documentar los requisitos que impone a las sobrescrituras.
Formulación de un enlace de propiedad
Cualquier expresión de C++ cuyo resultado sea del tipo correcto puede utilizarse como expresión de enlace y pasarse al método setBinding(). Sin embargo, para formular un enlace correcto, deben seguirse algunas reglas.
El seguimiento de dependencias solo funciona con propiedades vinculables. Es responsabilidad del desarrollador asegurarse de que todas las propiedades utilizadas en la expresión de enlace sean propiedades vinculables. Cuando se utilizan propiedades no vinculables en una expresión de enlace, los cambios en dichas propiedades no provocan actualizaciones en la propiedad vinculada. No se genera ninguna advertencia ni error, ni en tiempo de compilación ni en tiempo de ejecución. La propiedad vinculada solo se actualizará cuando se modifiquen las propiedades vinculables utilizadas en la expresión de enlace. Las propiedades no vinculables pueden utilizarse en un enlace si es posible garantizar que se llame a `markDirty` en la propiedad vinculada cada vez que se produzca un cambio en la dependencia no vinculable.
La propiedad vinculada puede evaluar su enlace varias veces a lo largo de su vida útil. El desarrollador debe asegurarse de que todos los objetos utilizados en la expresión de enlace tengan una vida útil más larga que la del propio enlace.
El sistema de propiedades vinculables no es seguro para subprocesos. Las propiedades utilizadas en la expresión de enlace en un subproceso no deben ser leídas ni modificadas por ningún otro subproceso. Un objeto de una clase derivada de ` QObject` que tenga una propiedad con un enlace no debe trasladarse a un subproceso diferente. Asimismo, un objeto de una clase derivada de ` QObject` que tenga una propiedad utilizada en un enlace no debe trasladarse a otro hilo. En este contexto, es irrelevante si se utiliza en un enlace de una propiedad del mismo objeto o en un enlace de una propiedad de otro objeto.
La expresión de enlace no debe leer la propiedad a la que está vinculada. De lo contrario, se produce un bucle de evaluación.
La expresión de enlace no debe escribir en la propiedad a la que está vinculada.
Las funciones utilizadas como enlaces, así como todo el código que se invoca dentro de un enlace, no deben utilizar co_await. Hacerlo puede confundir el seguimiento de las dependencias por parte del sistema de propiedades.
Propiedades enlazables y multihilo
Las propiedades vinculables no son seguras para subprocesos, salvo que se indique lo contrario. Una propiedad vinculable no debe ser leída ni modificada por ningún subproceso que no sea aquel en el que se creó.
Seguimiento de propiedades vinculables
A veces, las relaciones entre propiedades no pueden expresarse mediante enlaces. En su lugar, puede que necesites ejecutar código personalizado cada vez que cambie el valor de una propiedad y, en lugar de asignar el valor a otra propiedad, pasarlo a otras partes de tu aplicación. Por ejemplo, escribir datos en un socket de red o imprimir salida de depuración. QProperty ofrece dos mecanismos para el seguimiento.
Puedes registrar una función de devolución de llamada para que se ejecute cada vez que cambie el valor de una propiedad, utilizando onValueChanged(). Si deseas que la función de devolución de llamada también se ejecute para obtener el valor actual de la propiedad, registra tu función de devolución de llamada utilizando subscribe() en su lugar.
Interacción con Q_PROPERTY
Una Q_PROPERTY que defina « BINDABLE » puede vincularse y utilizarse en expresiones de enlace. Puedes implementar dichas propiedades utilizando « QProperty », « QObjectBindableProperty » o « QObjectComputedProperty ».
Las Q_PROPERTY sin BINDABLE también pueden vincularse y utilizarse en expresiones de enlace, siempre que definan una señal NOTIFY. Debes envolver la propiedad en un ` QBindable ` utilizando el constructor ` QBindable(QObject* obj, const char* property) `. A continuación, la propiedad se puede vincular mediante ` QBindable::setBinding()` o utilizarse en una expresión de enlace mediante ` QBindable::value()`. Debes utilizar ` QBindable::value() ` en las expresiones de enlace en lugar de la función habitual de la propiedad ` READ ` (o ` MEMBER`) para habilitar el seguimiento de dependencias si la propiedad no es ` BINDABLE`.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.