diff options
Diffstat (limited to 'src/corelib/doc/src/objectmodel/properties.qdoc')
| -rw-r--r-- | src/corelib/doc/src/objectmodel/properties.qdoc | 31 |
1 files changed, 22 insertions, 9 deletions
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++} */ |