QObjectBindableProperty 类

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

QObjectBindableProperty 类是启用自动特性绑定的模板类，为存储特性数据在 QObject 派生类。更多...

头：	#include <QObjectBindableProperty>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake:	QT += core
Since:	Qt 6.0
继承：	QPropertyData

所有成员列表，包括继承成员

公共函数

	QObjectBindableProperty ()
	QObjectBindableProperty (const T & initialValue )
	QObjectBindableProperty (T && initialValue )
	QObjectBindableProperty (Functor && f )
	QObjectBindableProperty (Class * owner , const QPropertyBinding<T> & binding )
	QObjectBindableProperty (Class * owner , 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 )
bool	setBinding (const QUntypedPropertyBinding & newBinding )
QPropertyBinding<T>	setBinding (Functor f )
void	setValue (QObjectBindableProperty::parameter_type newValue )
void	setValue (QObjectBindableProperty::rvalue_ref newValue )
QPropertyChangeHandler<Functor>	subscribe (Functor f )
QPropertyBinding<T>	takeBinding ()
QObjectBindableProperty::parameter_type	value () const

宏

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

详细描述

QObjectBindableProperty is a generic container that holds an instance of T and behaves mostly like QProperty . It is one of the classes implementing Qt Bindable Properties 。不像 QProperty , it stores its management data structure in the surrounding QObject . The extra template parameters are used to identify the surrounding class and a member function of that class acting as a change handler.

You can use QObjectBindableProperty to add binding support to code that uses Q_PROPERTY . The getter and setter methods must be adapted carefully according to the rules described in Bindable Property Getters and Setters .

In order to invoke the change signal on property changes, use QObjectBindableProperty and pass the change signal as a callback.

A simple example is given in the following.

#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); // enable debug log
    Foo myfoo;
    QProperty<int> prop(42);
    QObject::connect(&myfoo, &Foo::myValChanged, [&]() {
        if (debugout)
            qDebug() << myfoo.myVal();
    });
    myfoo.bindableMyVal().setBinding([&]() { return prop.value(); }); // prints "42"
    prop = 5; // prints "5"
    debugout = false;
    prop = 6; // prints nothing
    debugout = true;
    prop = 7; // prints "7"
}
#include "main.moc"

QObjectBindableProperty is usually not used directly, instead an instance of it is created by using the Q_OBJECT_BINDABLE_PROPERTY 宏。

使用 Q_OBJECT_BINDABLE_PROPERTY macro in the class declaration to declare the property as bindable.

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)
};

If you need to directly initialize the property with some non-default value, you can use the Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS macro. It accepts a value for the initialization as one of its parameters.

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 does not support multiple arguments directly. If your property requires multiple arguments for initialization, please explicitly call the specific constructor.

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(MyClass, CustomType xProp, CustomType(5, 10),
                                     &MyClass::xChanged)

The change handler can optionally accept one argument, of the same type as the property, in which case it is passed the new value of the property. Otherwise, it should take no arguments.

If the property does not need a changed notification, you can leave out the "NOTIFY xChanged" in the Q_PROPERTY macro as well as the last argument of the Q_OBJECT_BINDABLE_PROPERTY and Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS 宏。

另请参阅 Q_OBJECT_BINDABLE_PROPERTY , Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS , QProperty , QObjectComputedProperty , Qt 的特性系统，和 Qt Bindable Properties .

成员函数文档编制

void QObjectBindableProperty:: setValue ( QObjectBindableProperty::parameter_type newValue )

void QObjectBindableProperty:: setValue ( QObjectBindableProperty::rvalue_ref newValue )

赋值 newValue to this property and removes the property's associated binding, if present. If the property value changes as a result, calls the Callback function on owner .

QObjectBindableProperty:: QObjectBindableProperty ()

Constructs a property with a default constructed instance of T.

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

Constructs a property with the provided initialValue .

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

Move-Constructs a property with the provided initialValue .

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

Constructs a property that is tied to the provided binding expression f . The property's value is set to the result of evaluating the new binding. Whenever a dependency of the binding changes, the binding will be re-evaluated, and the property's value gets updated accordingly.

`[default]` QObjectBindableProperty:: QObjectBindableProperty ( 类 * owner , const QPropertyBinding < T > & binding )

Constructs a property that is tied to the provided binding expression. The property's value is set to the result of evaluating the new binding. Whenever a dependency of the binding changes, the binding will be re-evaluated, and the property's value gets updated accordingly.

When the property value changes, owner is notified via the Callback function.

`[default]` QObjectBindableProperty:: QObjectBindableProperty ( 类 * owner , QPropertyBinding < T > && binding )

When the property value changes, owner is notified via the Callback function.

`[default]` QObjectBindableProperty:: ~QObjectBindableProperty ()

销毁特性。

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

Subscribes the given functor f as a callback that is called whenever the value of the property changes.

The callback f is expected to be a type that has a plain call operator () without any parameters. This means that you can provide a C++ lambda expression, a std::function or even a custom struct with a call operator.

The returned property change handler object keeps track of the subscription. When it goes out of scope, the callback is unsubscribed.

This method is in some cases easier to use than onValueChanged (), as the returned object is not a template. It can therefore more easily be stored, e.g. as a member in a class.

另请参阅 onValueChanged () 和 subscribe ().

QPropertyBinding < T > QObjectBindableProperty:: binding () const

Returns the binding expression that is associated with this property. A default constructed QPropertyBinding<T> will be returned if no such association exists.

另请参阅 setBinding ().

bool QObjectBindableProperty:: hasBinding () const

Returns true if the property is associated with a binding; false otherwise.

void QObjectBindableProperty:: notify ()

Programmatically signals a change of the property. Any binding which depend on it will be notified, and if the property has a signal, it will be emitted.

This can be useful in combination with setValueBypassingBindings to defer signalling the change until a class invariant has been restored.

注意： If this property has a binding (i.e. hasBinding () returns true), that binding is not reevaluated when notify() is called. Any binding depending on this property is still reevaluated as usual.

另请参阅 Qt::beginPropertyUpdateGroup () 和 setValueBypassingBindings ().

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

Registers the given functor f as a callback that shall be called whenever the value of the property changes. On each value change, the handler is either called immediately, or deferred, depending on the context.

The returned property change handler object keeps track of the registration. When it goes out of scope, the callback is de-registered.

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

Associates the value of this property with the provided newBinding expression and returns the previously associated binding. The property's value is set to the result of evaluating the new binding. Whenever a dependency of the binding changes, the binding will be re-evaluated, and the property's value gets updated accordingly. When the property value changes, the owner is notified via the Callback function.

另请参阅 binding ().

bool QObjectBindableProperty:: setBinding (const QUntypedPropertyBinding & newBinding )

这是重载函数。

Associates the value of this property with the provided newBinding expression. The property's value is set to the result of evaluating the new binding. Whenever a dependency of the binding changes, the binding will be re-evaluated, and the property's value gets updated accordingly.

返回 true if the type of this property is the same as the type the binding function returns; false 否则。

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

这是重载函数。

Associates the value of this property with the provided functor f and returns the previously associated binding. The property's value is set to the result of evaluating the new binding by invoking the call operator () of f . Whenever a dependency of the binding changes, the binding will be re-evaluated, and the property's value gets updated accordingly.

When the property value changes, the owner is notified via the Callback function.

另请参阅 Formulating a Property Binding .

Subscribes the given functor f as a callback that is called immediately and whenever the value of the property changes in the future. On each value change, the handler is either called immediately, or deferred, depending on the context.

The returned property change handler object keeps track of the subscription. When it goes out of scope, the callback is unsubscribed.

QPropertyBinding < T > QObjectBindableProperty:: takeBinding ()

Disassociates the binding expression from this property and returns it. After calling this function, the value of the property will only change if you assign a new value to it, or when a new binding is set.

QObjectBindableProperty::parameter_type QObjectBindableProperty:: value () const

Returns the value of the property. This may evaluate a binding expression that is tied to this property, before returning the value.

另请参阅 setValue ().

宏文档编制

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

Declares a QObjectBindableProperty inside containingClass 类型 type with name name . If the optional argument signal is given, this signal will be emitted when the property is marked dirty.

该宏在 Qt 6.0 引入。

另请参阅 Qt 的特性系统 and Qt Bindable Properties .

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

Declares a QObjectBindableProperty inside containingClass 类型 type with name name which is initialized to initialvalue . If the optional argument signal is given, this signal will be emitted when the property is marked dirty.