diff options
Diffstat (limited to 'src/corelib/doc/src/objectmodel')
4 files changed, 41 insertions, 16 deletions
diff --git a/src/corelib/doc/src/objectmodel/bindableproperties.qdoc b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc index f9f129df97..9b3ea6ae66 100644 --- a/src/corelib/doc/src/objectmodel/bindableproperties.qdoc +++ b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc @@ -32,7 +32,7 @@ different objects. The \l {Introductory Example} below demonstrates the usage of bindable - properties in C++ code. You can also check \l {Bindable Properties Example} + properties in C++ code. You can also check \l {Bindable Properties} example to see how the bindable properties can help to improve your code. \section1 Introductory Example @@ -247,4 +247,18 @@ be called for the current value of the property, register your callback using subscribe() instead. + \section1 Interaction with Q_PROPERTYs + + A \l {The Property System}{Q_PROPERTY} that defines \c BINDABLE can be bound and + used in binding expressions. You can implement such properties using \l {QProperty}, + \l {QObjectBindableProperty}, or \l {QObjectComputedProperty}. + + Q_PROPERTYs without \c BINDABLE can also be bound and be used in binding expressions, + as long as they define a \c NOTIFY signal. You must wrap the property in a \l QBindable + using the \c {QBindable(QObject* obj, const char* property)} constructor. Then, the + property can be bound using \l QBindable::setBinding() or used in a binding + expression via \l QBindable::value(). You must use \c QBindable::value() in binding + expressions instead of the normal property \c READ function (or \c MEMBER) to enable + dependency tracking if the property is not \c BINDABLE. + */ diff --git a/src/corelib/doc/src/objectmodel/metaobjects.qdoc b/src/corelib/doc/src/objectmodel/metaobjects.qdoc index 62226ca466..3d7685447f 100644 --- a/src/corelib/doc/src/objectmodel/metaobjects.qdoc +++ b/src/corelib/doc/src/objectmodel/metaobjects.qdoc @@ -5,7 +5,7 @@ \page metaobjects.html \title The Meta-Object System \brief An overview of Qt's meta-object system and introspection capabilities. - + \ingroup explanations-basics \ingroup qt-basic-concepts \keyword meta-object \keyword Meta-Object System diff --git a/src/corelib/doc/src/objectmodel/properties.qdoc b/src/corelib/doc/src/objectmodel/properties.qdoc index 94078b5b6c..99a3e60d88 100644 --- a/src/corelib/doc/src/objectmodel/properties.qdoc +++ b/src/corelib/doc/src/objectmodel/properties.qdoc @@ -5,7 +5,7 @@ \page properties.html \title The Property System \brief An overview of Qt's property system. - + \ingroup explanations-basics \ingroup qt-basic-concepts \keyword Qt's Property System @@ -44,14 +44,21 @@ specified. It is for reading the property value. Ideally, a const function is used for this purpose, and it must return either the property's type or a const reference to that type. e.g., QWidget::focus is a read-only - property with \c READ function, QWidget::hasFocus(). + property with \c READ function, QWidget::hasFocus(). If a \c BINDABLE is + specified, you can write \c{READ default} to have the \c READ accessor + generated from the \c BINDABLE. \li A \c WRITE accessor function is optional. It is for setting the property value. It must return void and must take exactly one argument, either of the property's type or a pointer or reference to that type. e.g., QWidget::enabled has the \c WRITE function QWidget::setEnabled(). Read-only properties do not need \c WRITE - functions. e.g., QWidget::focus has no \c WRITE function. + functions. e.g., QWidget::focus has no \c WRITE function. If you specify + both a \c BINDABLE and \c{WRITE default}, a \c WRITE accessor will be + generated from the \c BINDABLE. The generated \c WRITE accessor will \e not + explicitly emit any signal declared with \c NOTIFY. You should register + the signal as change handler to the \c BINDABLE, for example using + \l{Q_OBJECT_BINDABLE_PROPERTY}. \li A \c MEMBER variable association is required if no \c READ accessor function is specified. This makes the given member variable @@ -75,8 +82,9 @@ which must be of the same type as the property. The parameter will take the new value of the property. The \c NOTIFY signal should only be emitted when the property has really been changed, to avoid bindings being unnecessarily - re-evaluated in QML, for example. Qt emits automatically that signal when - needed for MEMBER properties that do not have an explicit setter. + re-evaluated in QML, for example. The signal is emitted automatically when + the property is changed via the Qt API (QObject::setProperty, + QMetaProperty, etc.), but not when the MEMBER is changed directly. \li A \c REVISION number or \c REVISION() macro is optional. If included, it defines the property and its notifier signal to be used in a particular @@ -85,7 +93,7 @@ \li The \c DESIGNABLE attribute indicates whether the property should be visible in the property editor of GUI design tool (e.g., - \l {Qt Designer Manual}{Qt Designer}). Most properties are \c DESIGNABLE + \l {Qt Widgets Designer Manual}{\QD}). Most properties are \c DESIGNABLE (default true). Valid values are true and false. \li The \c SCRIPTABLE attribute indicates whether this property @@ -200,7 +208,10 @@ The \c READ function is const and returns the property type. The \c WRITE function returns void and has exactly one parameter of the property type. The meta-object compiler enforces these - requirements. + requirements. The equality check in the \c WRITE function, while not + mandatory, is good practice as there is no point in notifying and + potentially forcing re-evaluation in other places if nothing has + changed. Given a pointer to an instance of MyClass or a pointer to a QObject that is an instance of MyClass, we have two ways to set @@ -266,7 +277,9 @@ Connected to the property system is an additional macro, Q_CLASSINFO(), that can be used to attach additional - \e{name}--\e{value} pairs to a class's meta-object, for example: + \e{name}--\e{value} pairs to a class's meta-object. This is + used for instance to mark a property as the \e default one + in the context of \l{QML Object Types}: \snippet code/doc_src_properties.cpp 7 @@ -288,5 +301,5 @@ and the general tips on implementing and using \l {Qt Bindable Properties}{bindable properties}. - \sa {Qt Bindable Properties} + \sa {Qt Bindable Properties}, {Defining QML Types from C++} */ diff --git a/src/corelib/doc/src/objectmodel/signalsandslots.qdoc b/src/corelib/doc/src/objectmodel/signalsandslots.qdoc index 1b427f5775..f0eeb20048 100644 --- a/src/corelib/doc/src/objectmodel/signalsandslots.qdoc +++ b/src/corelib/doc/src/objectmodel/signalsandslots.qdoc @@ -8,7 +8,7 @@ \ingroup qt-basic-concepts \brief An overview of Qt's signals and slots inter-object communication mechanism. - + \ingroup explanations-basics Signals and slots are used for communication between objects. The signals and slots mechanism is a central feature of Qt and probably the part that differs most from the features provided by @@ -109,8 +109,7 @@ when the signal is emitted. Signals are automatically generated by the \l moc and must not be - implemented in the \c .cpp file. They can never have return types - (i.e. use \c void). + implemented in the \c .cpp file. A note about arguments: Our experience shows that signals and slots are more reusable if they do not use special types. If @@ -297,8 +296,7 @@ callbacks, you'd have to find five different names and keep track of the types yourself. - \sa QLCDNumber, QObject::connect(), {Digital Clock Example}, - {Tetrix Example} + \sa QLCDNumber, QObject::connect() \section1 Signals And Slots With Default Arguments |