En esta página

QObjectBindableProperty Class

template <typename Class, typename T, auto Offset, auto Signal> class QObjectBindableProperty

La clase `QObjectBindableProperty` es una clase de plantilla que permite el enlace automático de propiedades para los datos almacenados en las clases derivadas de ` QObject `. Más información...

Encabezado: #include <QObjectBindableProperty>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Desde: Qt 6.0
Heredado de: QPropertyData

Comparaciones de QObjectBindableProperty

CategoríaTipos comparables
igualdadQObjectBindableProperty
igualdadT.

Funciones públicas

QObjectBindableProperty()
QObjectBindableProperty(Functor &&f)
QObjectBindableProperty(T &&initialValue)
QObjectBindableProperty(const T &initialValue)
QObjectBindableProperty(Class *owner, QPropertyBinding<T> &&binding)
QObjectBindableProperty(Class *owner, const QPropertyBinding<T> &binding)
~QObjectBindableProperty()
QPropertyNotifier addNotifier(Functor f)
QPropertyBinding<T> binding() const
bool hasBinding() const
void notify()
QPropertyChangeHandler<Functor> onValueChanged(Functor f)
QPropertyBinding<T> setBinding(const QPropertyBinding<T> &newBinding)
QPropertyBinding<T> setBinding(Functor f)
bool setBinding(const QUntypedPropertyBinding &newBinding)
void setValue(QObjectBindableProperty<Class, T, Offset, Signal>::parameter_type newValue)
void setValue(QObjectBindableProperty<Class, T, Offset, Signal>::rvalue_ref newValue)
QPropertyChangeHandler<Functor> subscribe(Functor f)
QPropertyBinding<T> takeBinding()
QObjectBindableProperty<Class, T, Offset, Signal>::parameter_type value() const

Macros

(since 6.0) Q_OBJECT_BINDABLE_PROPERTY(containingClass, type, name, signal)
(since 6.0) Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS(containingClass, type, name, initialvalue, signal)

Descripción detallada

QObjectBindableProperty es una clase de plantilla en la que el parámetro de plantilla Class especifica la clase derivada de QObject que la posee, T especifica el tipo de valor de la propiedad, Offset especifica la ubicación de la propiedad dentro de la clase y Signal especifica, de forma opcional, la señal de notificación que se emitirá cuando cambie el valor de la propiedad.

`QObjectBindableProperty` es un contenedor genérico que contiene una instancia de `T` y se comporta, en gran medida, como ` QProperty`. Es una de las clases que implementan las propiedades vinculables de Qt. A diferencia de ` QProperty`, almacena su estructura de datos de gestión en la clase envolvente ` QObject`. Los parámetros de plantilla adicionales se utilizan para identificar la clase envolvente y una función miembro de dicha clase que actúa como gestor de cambios.

Puedes utilizar `QObjectBindableProperty` para añadir compatibilidad con el enlace a código que utilice ` Q_PROPERTY`. Los métodos getter y setter deben adaptarse cuidadosamente de acuerdo con las reglas descritas en «Getters y setters de propiedades enlazables».

Para invocar la señal de cambio cuando se producen modificaciones en la propiedad, utiliza QObjectBindableProperty y pasa la señal de cambio como una llamada de retorno.

A continuación se ofrece un ejemplo sencillo.

#include <QObject>
#include <QProperty>
#include <QDebug>

class Foo : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int myVal READ myVal WRITE setMyVal BINDABLE bindableMyVal)
public:
    int myVal() { return myValMember.value(); }
   void setMyVal(int newvalue) { myValMember = newvalue; }
    QBindable<int> bindableMyVal() { return &myValMember; }
signals:
    void myValChanged();

private:
    Q_OBJECT_BINDABLE_PROPERTY(Foo, int, myValMember, &Foo::myValChanged);
};

int main()
{
    bool debugout(true); // habilita el registro de depuración
    Foo myfoo;
    QProperty<int> prop(42);
    QObject::connect(&myfoo, &Foo::myValChanged, [&]() {
        if (debugout)
            qDebug() << myfoo.myVal();
    });
    myfoo.bindableMyVal().setBinding([&]() { return prop.value(); }); // muestra «42»

    prop = 5; // muestra «5»
    debugout = false;
    prop = 6; // no muestra nada
    debugout = true;
    prop = 7; // muestra «7»
}

#include "main.moc"

QObjectBindableProperty no suele utilizarse directamente, sino que se crea una instancia del mismo mediante la macro Q_OBJECT_BINDABLE_PROPERTY.

Utiliza la macro Q_OBJECT_BINDABLE_PROPERTY en la declaración de la clase para declarar la propiedad como enlazable.

class MyClass : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int x READ x WRITE setX NOTIFY xChanged BINDABLE bindableX)
public:
    int x() const { return xProp; }
    void setX(int x) { xProp = x; }
    QBindable<int> bindableX() { return QBindable<int>(&xProp); }

signals:
    void xChanged();

private:
    // Declare the instance of the bindable property data.
    Q_OBJECT_BINDABLE_PROPERTY(MyClass, int, xProp, &MyClass::xChanged)
};

Si necesitas inicializar directamente la propiedad con un valor distinto del predeterminado, puedes utilizar la macro ` Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS `. Esta macro acepta un valor para la inicialización como uno de sus parámetros.

class MyClass : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int x READ x WRITE setX NOTIFY xChanged BINDABLE bindableX)
public:
    int x() const { return xProp; }
    void setX(int x) { xProp = x; }
    QBindable<int> bindableX() { return QBindable<int>(&xProp); }

signals:
    void xChanged();

private:
    // Declare the instance of int bindable property data and
    // initialize it with the value 5.
    // This is similar to declaring
    // int xProp = 5;
    // without using the new QObjectBindableProperty class.
    Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS(MyClass, int, xProp, 5, &MyClass::xChanged)
};

Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS no admite varios argumentos directamente. Si tu propiedad requiere varios argumentos para su inicialización, llama explícitamente al constructor específico.

class CustomType
{
public:
    CustomType(int val, int otherVal) : value(val), anotherValue(otherVal) { }

private:
    int value = 0;
    int anotherValue = 0;
};

// later when using CustomType as a property
Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS(SomeClass, CustomType, xProp, CustomType(5, 10),
                                    &MyClass::xChanged)

El controlador de cambios puede aceptar opcionalmente un argumento, del mismo tipo que la propiedad, en cuyo caso se le pasa el nuevo valor de la propiedad. De lo contrario, no debe aceptar ningún argumento.

Si la propiedad no necesita una notificación de cambio, puedes omitir «NOTIFY xChanged» en la macro Q_PROPERTY, así como el último argumento de las macros Q_OBJECT_BINDABLE_PROPERTY y Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS.

Véase también Q_OBJECT_BINDABLE_PROPERTY, Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS, QProperty, QObjectComputedProperty, el sistema de propiedades de Qt y las propiedades vinculables de Qt.

Documentación de las funciones miembro

[default] QObjectBindableProperty::QObjectBindableProperty()

Crea una propiedad con una instancia de T generada por defecto.

[explicit] template <typename Functor> QObjectBindableProperty::QObjectBindableProperty(Functor &&f)

Crea una propiedad vinculada a la expresión de enlace proporcionada f. El valor de la propiedad se establece en el resultado de evaluar el nuevo enlace. Cada vez que cambie una dependencia del enlace, este se volverá a evaluar y el valor de la propiedad se actualizará en consecuencia.

[explicit] QObjectBindableProperty::QObjectBindableProperty(T &&initialValue)

Move: crea una propiedad con el initialValue proporcionado.

[explicit] QObjectBindableProperty::QObjectBindableProperty(const T &initialValue)

Crea una propiedad con el valor proporcionado en « initialValue ».

[implicit] QObjectBindableProperty::QObjectBindableProperty(Class *owner, QPropertyBinding<T> &&binding)

Crea una propiedad vinculada a la expresión binding proporcionada. El valor de la propiedad se establece en el resultado de evaluar el nuevo enlace. Cada vez que cambie una dependencia del enlace, este se volverá a evaluar y el valor de la propiedad se actualizará en consecuencia.

Cuando cambia el valor de la propiedad, se notifica a owner a través de la función Callback.

[implicit] QObjectBindableProperty::QObjectBindableProperty(Class *owner, const QPropertyBinding<T> &binding)

Crea una propiedad vinculada a la expresión binding proporcionada. El valor de la propiedad se establece en el resultado de la evaluación de la nueva vinculación. Cada vez que cambie una dependencia de la vinculación, esta se volverá a evaluar y el valor de la propiedad se actualizará en consecuencia.

Cuando cambia el valor de la propiedad, se notifica a owner a través de la función de devolución de llamada.

[implicit] QObjectBindableProperty::~QObjectBindableProperty()

Destruye la propiedad.

template <typename Functor> QPropertyNotifier QObjectBindableProperty::addNotifier(Functor f)

Suscribe el functor indicado f como una función de devolución de llamada que se activa cada vez que cambia el valor de la propiedad.

Se espera que la llamada de retorno f sea de un tipo que tenga un operador de llamada simple () sin ningún parámetro. Esto significa que puedes proporcionar una expresión lambda de C++, un std::function o incluso una estructura personalizada con un operador de llamada.

El objeto de controlador de cambios de propiedad devuelto realiza un seguimiento de la suscripción. Cuando sale del ámbito, se da de baja la función de llamada.

Este método resulta, en algunos casos, más fácil de usar que ` onValueChanged()`, ya que el objeto devuelto no es una plantilla. Por lo tanto, se puede almacenar más fácilmente, por ejemplo, como miembro de una clase.

Véanse también ` onValueChanged()` y ` subscribe()`.

QPropertyBinding<T> QObjectBindableProperty::binding() const

Devuelve la expresión de enlace asociada a esta propiedad. Si no existe dicha asociación, se devolverá un objeto QPropertyBinding<T> creado por defecto.

Véase también setBinding().

bool QObjectBindableProperty::hasBinding() const

Devuelve «true» si la propiedad está asociada a un enlace; en caso contrario, devuelve «false».

void QObjectBindableProperty::notify()

Indica mediante programación un cambio en la propiedad. Se notificará a cualquier enlace que dependa de ella y, si la propiedad tiene una señal, esta se emitirá.

Esto puede resultar útil en combinación con `setValueBypassingBindings` para aplazar la señalización del cambio hasta que se haya restablecido una invariante de la clase.

Nota: Si esta propiedad tiene un enlace (es decir, si hasBinding() devuelve true), dicho enlace no se reevalúa cuando se llama a notify(). Cualquier enlace que dependa de esta propiedad se reevalúa como de costumbre.

Véase también Qt::beginPropertyUpdateGroup() y setValueBypassingBindings().

template <typename Functor> QPropertyChangeHandler<Functor> QObjectBindableProperty::onValueChanged(Functor f)

Registra el functor dado f como una función de llamada posterior que se invocará cada vez que cambie el valor de la propiedad. Ante cada cambio de valor, el controlador se invoca de forma inmediata o se aplaza, dependiendo del contexto.

Se espera que la llamada de retorno f sea de un tipo que tenga un operador de llamada simple () sin ningún parámetro. Esto significa que puedes proporcionar una expresión lambda de C++, una std::function o incluso una estructura personalizada con un operador de llamada.

El objeto de controlador de cambios de propiedad devuelto realiza un seguimiento del registro. Cuando sale del ámbito, se da de baja la llamada de retorno.

QPropertyBinding<T> QObjectBindableProperty::setBinding(const QPropertyBinding<T> &newBinding)

Asocia el valor de esta propiedad a la expresión « newBinding » proporcionada y devuelve la vinculación asociada anteriormente. El valor de la propiedad se establece en el resultado de evaluar la nueva vinculación. Cada vez que cambie una dependencia de la vinculación, esta se volverá a evaluar y el valor de la propiedad se actualizará en consecuencia. Cuando cambia el valor de la propiedad, se notifica al propietario a través de la función de devolución de llamada.

Véase también binding().

template <typename Functor> QPropertyBinding<T> QObjectBindableProperty::setBinding(Functor f)

Asocia el valor de esta propiedad con el functor proporcionado f y devuelve el enlace asociado anteriormente. El valor de la propiedad se establece en el resultado de evaluar el nuevo enlace mediante la invocación del operador de llamada () de f. Cada vez que cambie una dependencia del enlace, este se reevaluará y el valor de la propiedad se actualizará en consecuencia.

Cuando cambia el valor de la propiedad, se notifica al propietario a través de la función de devolución de llamada.

Se trata de una función sobrecargada.

Véase también «Formulación deun enlace de propiedad».

bool QObjectBindableProperty::setBinding(const QUntypedPropertyBinding &newBinding)

Asocia el valor de esta propiedad a la expresión newBinding proporcionada. El valor de la propiedad se establece en el resultado de la evaluación del nuevo enlace. Cada vez que cambie una dependencia del enlace, este se volverá a evaluar y el valor de la propiedad se actualizará en consecuencia.

Devuelve ` true ` si el tipo de esta propiedad es el mismo que el tipo que devuelve la función de enlace; en caso contrario, devuelve ` false `.

Se trata de una función sobrecargada.

void QObjectBindableProperty::setValue(QObjectBindableProperty<Class, T, Offset, Signal>::parameter_type newValue)

void QObjectBindableProperty::setValue(QObjectBindableProperty<Class, T, Offset, Signal>::rvalue_ref newValue)

Asigna « newValue » a esta propiedad y elimina el enlace asociado a la misma, si existe. Si, como consecuencia, cambia el valor de la propiedad, se invoca la función de llamada de retorno en « owner ».

template <typename Functor> QPropertyChangeHandler<Functor> QObjectBindableProperty::subscribe(Functor f)

Suscribe el functor dado f como una función de devolución de llamada que se invoca inmediatamente y cada vez que el valor de la propiedad cambie en el futuro. En cada cambio de valor, el controlador se invoca de forma inmediata o se aplaza, dependiendo del contexto.

Se espera que la llamada de retorno f sea de un tipo que cuente con un operador de llamada simple () sin parámetros. Esto significa que puedes proporcionar una expresión lambda de C++, una std::function o incluso una estructura personalizada con un operador de llamada.

El objeto de controlador de cambios de propiedad devuelto realiza el seguimiento de la suscripción. Cuando sale del ámbito, se da de baja la llamada de retorno.

QPropertyBinding<T> QObjectBindableProperty::takeBinding()

Desvincula la expresión de enlace de esta propiedad y la devuelve. Tras llamar a esta función, el valor de la propiedad solo cambiará si se le asigna un nuevo valor o cuando se establezca un nuevo enlace.

QObjectBindableProperty<Class, T, Offset, Signal>::parameter_type QObjectBindableProperty::value() const

Devuelve el valor de la propiedad. Es posible que, antes de devolver el valor, se evalúe una expresión de enlace vinculada a esta propiedad.

Véase también setValue().

Documentación de macros

[since 6.0] Q_OBJECT_BINDABLE_PROPERTY(containingClass, type, name, signal)

Declara una señal « QObjectBindableProperty » dentro de « containingClass » de tipo « type » con el nombre « name ». Si se proporciona el argumento opcional « signal », esta señal se emitirá cuando la propiedad se marque como «dirty».

Esta macro se introdujo en Qt 6.0.

Véase también «Sistema de propiedades de Qt » y «Propiedades vinculables de Qt».

[since 6.0] Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS(containingClass, type, name, initialvalue, signal)

Declara un objeto de tipo ` QObjectBindableProperty ` dentro de ` containingClass `, de tipo ` type ` y con el nombre ` name `, que se inicializa con ` initialvalue`. Si se proporciona el argumento opcional ` signal `, esta señal se emitirá cuando la propiedad se marque como «sucia».

Esta macro se introdujo en Qt 6.0.

Véase también el sistema de propiedades de Qt y las propiedades vinculables de Qt.

© 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.