path: root/doc/src/corelib/objectmodel/properties.qdoc
diff options
Diffstat (limited to 'doc/src/corelib/objectmodel/properties.qdoc')
1 files changed, 273 insertions, 0 deletions
diff --git a/doc/src/corelib/objectmodel/properties.qdoc b/doc/src/corelib/objectmodel/properties.qdoc
new file mode 100644
index 0000000000..0350f19be4
--- /dev/null
+++ b/doc/src/corelib/objectmodel/properties.qdoc
@@ -0,0 +1,273 @@
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (
+** This file is part of the documentation of the Qt Toolkit.
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+ \page properties.html
+ \title The Property System
+ \brief An overview of Qt's property system.
+ \ingroup qt-basic-concepts
+ \target Qt's Property System
+ Qt provides a sophisticated property system similar to the ones
+ supplied by some compiler vendors. However, as a compiler- and
+ platform-independent library, Qt does not rely on non-standard
+ compiler features like \c __property or \c [property]. The Qt
+ solution works with \e any standard C++ compiler on every platform
+ Qt supports. It is based on the \l {Meta-Object System} that also
+ provides inter-object communication via \l{signals and slots}.
+ \section1 Requirements for Declaring Properties
+ To declare a property, use the \l {Q_PROPERTY()} {Q_PROPERTY()}
+ macro in a class that inherits QObject.
+ \snippet doc/src/snippets/code/doc_src_properties.cpp 0
+ Here are some typical examples of property declarations taken from
+ class QWidget.
+ \snippet doc/src/snippets/code/doc_src_properties.cpp 1
+ A property behaves like a class data member, but it has additional
+ features accessible through the \l {Meta-Object System}.
+ \list
+ \o A \c READ accessor function is required. 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 pointer or
+ reference to that type. e.g., QWidget::focus is a read-only property
+ with \c READ function, QWidget::hasFocus().
+ \o 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.
+ \o A \c RESET function is optional. It is for setting the property
+ back to its context specific default value. e.g., QWidget::cursor
+ has the typical \c READ and \c WRITE functions, QWidget::cursor()
+ and QWidget::setCursor(), and it also has a \c RESET function,
+ QWidget::unsetCursor(), since no call to QWidget::setCursor() can
+ mean \e {reset to the context specific cursor}. The \c RESET
+ function must return void and take no parameters.
+ \o A \c NOTIFY signal is optional. If defined, it should specify one
+ existing signal in that class that is emitted whenever the value
+ of the property changes.
+ \o A \c REVISION number is optional. If included, it defines the
+ the property and its notifier signal to be used in a particular
+ revision of the API that is exposed to QML.
+ \o The \c DESIGNABLE attribute indicates whether the property
+ should be visible in the property editor of GUI design tool (e.g.,
+ \l {Qt Designer}). Most properties are \c DESIGNABLE (default
+ true). Instead of true or false, you can specify a boolean
+ member function.
+ \o The \c SCRIPTABLE attribute indicates whether this property
+ should be accessible by a scripting engine (default true).
+ Instead of true or false, you can specify a boolean member
+ function.
+ \o The \c STORED attribute indicates whether the property should
+ be thought of as existing on its own or as depending on other
+ values. It also indicates whether the property value must be saved
+ when storing the object's state. Most properties are \c STORED
+ (default true), but e.g., QWidget::minimumWidth() has \c STORED
+ false, because its value is just taken from the width component
+ of property QWidget::minimumSize(), which is a QSize.
+ \o The \c USER attribute indicates whether the property is
+ designated as the user-facing or user-editable property for the
+ class. Normally, there is only one \c USER property per class
+ (default false). e.g., QAbstractButton::checked is the user
+ editable property for (checkable) buttons. Note that QItemDelegate
+ gets and sets a widget's \c USER property.
+ \o The presence of the \c CONSTANT attibute indicates that the property
+ value is constant. For a given object instance, the READ method of a
+ constant property must return the same value every time it is called. This
+ constant value may be different for different instances of the object. A
+ constant property cannot have a WRITE method or a NOTIFY signal.
+ \o The presence of the \c FINAL attribute indicates that the property
+ will not be overridden by a derived class. This can be used for performance
+ optimizations in some cases, but is not enforced by moc. Care must be taken
+ never to override a \c FINAL property.
+ \endlist
+ The \c READ, \c WRITE, and \c RESET functions can be inherited.
+ They can also be virtual. When they are inherited in classes where
+ multiple inheritance is used, they must come from the first
+ inherited class.
+ The property type can be any type supported by QVariant, or it can
+ be a user-defined type. In this example, class QDate is considered
+ to be a user-defined type.
+ \snippet doc/src/snippets/code/doc_src_properties.cpp 2
+ Because QDate is user-defined, you must include the \c{<QDate>}
+ header file with the property declaration.
+ For QMap, QList, and QValueList properties, the property value is
+ a QVariant whose value is the entire list or map. Note that the
+ Q_PROPERTY string cannot contain commas, because commas separate
+ macro arguments. Therefore, you must use \c QMap as the property
+ type instead of \c QMap<QString,QVariant>. For consistency, also
+ use \c QList and \c QValueList instead of \c QList<QVariant> and
+ \c QValueList<QVariant>.
+ \section1 Reading and Writing Properties with the Meta-Object System
+ A property can be read and written using the generic functions
+ QObject::property() and QObject::setProperty(), without knowing
+ anything about the owning class except the property's name. In
+ the code snippet below, the call to QAbstractButton::setDown() and
+ the call to QObject::setProperty() both set property "down".
+ \snippet doc/src/snippets/code/doc_src_properties.cpp 3
+ Accessing a property through its \c WRITE accessor is the better
+ of the two, because it is faster and gives better diagnostics at
+ compile time, but setting the property this way requires that you
+ know about the class at compile time. Accessing properties by name
+ lets you access classes you don't know about at compile time. You
+ can \e discover a class's properties at run time by querying its
+ QObject, QMetaObject, and \l {QMetaProperty} {QMetaProperties}.
+ \snippet doc/src/snippets/code/doc_src_properties.cpp 4
+ In the above snippet, QMetaObject::property() is used to get \l
+ {QMetaProperty} {metadata} about each property defined in some
+ unknown class. The property name is fetched from the metadata and
+ passed to QObject::property() to get the \l {QVariant} {value} of
+ the property in the current \l {QObject}{object}.
+ \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 priorty
+ 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.
+ We declare the property with the Q_PROPERTY() macro in the private
+ section of the class. The required \c READ function is named \c
+ priority, and we include a \c WRITE function named \c setPriority.
+ The enumeration type must be registered with the \l {Meta-Object
+ System} using the Q_ENUMS() 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
+ then might look like this:
+ \snippet doc/src/snippets/code/doc_src_properties.cpp 5
+ 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.
+ 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
+ its priority property:
+ \snippet doc/src/snippets/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}
+ using the Q_ENUMS() macro. This makes the enumeration values
+ available as strings for use as in the call to 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_ENUMS() macro.
+ A similar macro, Q_FLAGS(), is also available. Like Q_ENUMS(), 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
+ class might have enumeration values \c Read and \c Write and then
+ QObject::setProperty() could accept \c{Read | Write}. Q_FLAGS()
+ should be used to register this enumeration type.
+ \section1 Dynamic Properties
+ QObject::setProperty() can also be used to add \e new properties
+ to an instance of a class at runtime. When it is called with a
+ name and a value, if a property with the given name exists in the
+ QObject, and if the given value is compatible with the property's
+ type, the value is stored in the property, and true is returned.
+ If the value is \e not compatible with the property's type, the
+ property is \e not changed, and false is returned. But if the
+ property with the given name doesn't exist in the QObject (i.e.,
+ if it wasn't declared with Q_PROPERTY(), a new property with the
+ given name and value is automatically added to the QObject, but
+ false is still returned. This means that a return of false can't
+ be used to determine whether a particular property was actually
+ set, unless you know in advance that the property already exists
+ in the QObject.
+ Note that \e dynamic properties are added on a per instance basis,
+ i.e., they are added to QObject, not QMetaObject. A property can
+ be removed from an instance by passing the property name and an
+ invalid QVariant value to QObject::setProperty(). The default
+ constructor for QVariant constructs an invalid QVariant.
+ Dynamic properties can be queried with QObject::property(), just
+ like properties declared at compile time with Q_PROPERTY().
+ \sa {Meta-Object System}, {Signals and Slots}
+ \section1 Properties and Custom Types
+ Custom types used by properties need to be registered using the
+ Q_DECLARE_METATYPE() macro so that their values can be stored in
+ QVariant objects. This makes them suitable for use with both
+ static properties declared using the Q_PROPERTY() macro in class
+ definitions and dynamic properties created at run-time.
+ \sa Q_DECLARE_METATYPE(), QMetaType, QVariant
+ \section1 Adding Additional Information to a Class
+ 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:
+ \snippet doc/src/snippets/code/doc_src_properties.cpp 7
+ Like other meta-data, class information is accessible at run-time
+ through the meta-object; see QMetaObject::classInfo() for details.