diff options
Diffstat (limited to 'src/corelib/doc/src/objectmodel/properties.qdoc')
| -rw-r--r-- | src/corelib/doc/src/objectmodel/properties.qdoc | 56 |
1 files changed, 34 insertions, 22 deletions
diff --git a/src/corelib/doc/src/objectmodel/properties.qdoc b/src/corelib/doc/src/objectmodel/properties.qdoc index 94078b5b6c..0e66c8445c 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 @@ -178,12 +186,11 @@ \section1 A Simple Example - Suppose we have a class MyClass, which is derived from QObject and - which uses the Q_OBJECT macro in its private section. We want to - declare a property in MyClass to keep track of a priority - value. The name of the property will be \e priority, and its type - will be an enumeration type named \e Priority, which is defined in - MyClass. + Suppose we have a class \c MyClass, which is derived from QObject and which + uses the Q_OBJECT macro. We want to declare a property in \c MyClass to keep + track of a priority value. The name of the property will be \c priority, and + its type will be an enumeration type named \c Priority, which is defined in + \c MyClass. We declare the property with the Q_PROPERTY() macro in the private section of the class. The required \c READ function is named \c @@ -192,7 +199,7 @@ System} using the Q_ENUM() macro. Registering an enumeration type makes the enumerator names available for use in calls to QObject::setProperty(). We must also provide our own declarations - for the \c READ and \c WRITE functions. The declaration of MyClass + for the \c READ and \c WRITE functions. The declaration of \c MyClass then might look like this: \snippet code/doc_src_properties.cpp 5 @@ -200,26 +207,29 @@ 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 + Given a pointer to an instance of \c MyClass or a pointer to a + QObject that is an instance of \c MyClass, we have two ways to set its priority property: \snippet code/doc_src_properties.cpp 6 In the example, the enumeration type that is the property type is - declared in MyClass and registered with the \l{Meta-Object System} + declared in \c MyClass and registered with the \l{Meta-Object System} using the Q_ENUM() macro. This makes the enumeration values - available as strings for use as in the call to \l{QObject::}{setProperty()}. Had - the enumeration type been declared in another class, its fully + available as strings for use as in the call to \l{QObject::}{setProperty()}. + Had the enumeration type been declared in another class, its fully qualified name (i.e., OtherClass::Priority) would be required, and that other class would also have to inherit QObject and register the enumeration type there using the Q_ENUM() macro. A similar macro, Q_FLAG(), is also available. Like Q_ENUM(), it registers an enumeration type, but it marks the type as being a - set of \e flags, i.e. values that can be OR'd together. An I/O + set of \e flags, i.e., values that can be OR'd together. An I/O class might have enumeration values \c Read and \c Write and then QObject::setProperty() could accept \c{Read | Write}. Q_FLAG() should be used to register this enumeration type. @@ -266,7 +276,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 +300,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++} */ |