doc/src/properties.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Lesser General Public License Usage
  17 ** Alternatively, this file may be used under the terms of the GNU Lesser
  18 ** General Public License version 2.1 as published by the Free Software
  19 ** Foundation and appearing in the file LICENSE.LGPL included in the
  20 ** packaging of this file.  Please review the following information to
  21 ** ensure the GNU Lesser General Public License version 2.1 requirements
  22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  23 **
  24 ** In addition, as a special exception, Nokia gives you certain additional
  25 ** rights.  These rights are described in the Nokia Qt LGPL Exception
  26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  27 **
  28 ** If you have questions regarding the use of this file, please contact
  29 ** Nokia at qt-info@nokia.com.
  30 **
  31 **
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 /*!
  43     \page properties.html
  44     \title Qt's Property System
  45     \ingroup architecture
  46     \brief An overview of Qt's property system.
  47
  48     Qt provides a sophisticated property system similar to the ones
  49     supplied by some compiler vendors. However, as a compiler- and
  50     platform-independent library, Qt does not rely on non-standard
  51     compiler features like \c __property or \c [property]. The Qt
  52     solution works with \e any standard C++ compiler on every platform
  53     Qt supports. It is based on the \l {Meta-Object System} that also
  54     provides inter-object communication via \l{signals and slots}.
  55
  56     \section1 Requirements for Declaring Properties
  57
  58     To declare a property, use the \l {Q_PROPERTY()} {Q_PROPERTY()}
  59     macro in a class that inherits QObject.
  60
  61     \snippet doc/src/snippets/code/doc_src_properties.qdoc 0
  62
  63     Here are some typical examples of property declarations taken from
  64     class QWidget.
  65
  66     \snippet doc/src/snippets/code/doc_src_properties.qdoc 1
  67
  68     A property behaves like a class data member, but it has additional
  69     features accessible through the \l {Meta-Object System}.
  70
  71     \list
  72
  73     \o A \c READ accessor function is required. It is for reading the
  74     property value. It must be const and must return either the
  75     property's type or a pointer or reference to that type. e.g.,
  76     QWidget::focus is a read-only property with \c READ function
  77     QWidget::hasFocus().
  78
  79     \o A \c WRITE accessor function is optional. It is for setting the
  80     property value. It must return void and must take exactly one
  81     argument, either of the property's type or a pointer or reference
  82     to that type. e.g., QWidget::enabled has the \c WRITE function
  83     QWidget::setEnabled().  Read-only properties do not need \c WRITE
  84     functions. e.g., QWidget::focus has no \c WRITE function.
  85
  86     \o A \c RESET function is optional. It is for setting the property
  87     back to its context specific default value. e.g., QWidget::cursor
  88     has the typical \c READ and \c WRITE functions, QWidget::cursor()
  89     and QWidget::setCursor(), and it also has a \c RESET function,
  90     QWidget::unsetCursor(), since no call to QWidget::setCursor() can
  91     mean \e {reset to the context specific cursor}. The \c RESET
  92     function must return void and take no parameters.
  93
  94     \o A \c NOTIFY signal is optional. If defined, the signal will be
  95     emitted whenever the value of the property changes. The signal must
  96     take one parameter, which must be of the same type as the property; the
  97     parameter will take the new value of the property.
  98
  99     \o The \c DESIGNABLE attribute indicates whether the property
 100     should be visible in the property editor of GUI design tool (e.g.,
 101     \l {Qt Designer}). Most properties are \c DESIGNABLE (default
 102     true). Instead of true or false, you can specify a boolean
 103     member function.
 104
 105     \o The \c SCRIPTABLE attribute indicates whether this property
 106     should be accessible by a scripting engine (default true).
 107     Instead of true or false, you can specify a boolean member
 108     function.
 109
 110     \o The \c STORED attribute indicates whether the property should
 111     be thought of as existing on its own or as depending on other
 112     values. It also indicates whether the property value must be saved
 113     when storing the object's state. Most properties are \c STORED
 114     (default true), but e.g., QWidget::minimumWidth() has \c STORED
 115     false, because its value is just taken from the width component
 116     of property QWidget::minimumSize(), which is a QSize.
 117
 118     \o The \c USER attribute indicates whether the property is
 119     designated as the user-facing or user-editable property for the
 120     class. Normally, there is only one \c USER property per class
 121     (default false). e.g., QAbstractButton::checked is the user
 122     editable property for (checkable) buttons. Note that QItemDelegate
 123     gets and sets a widget's \c USER property.
 124
 125     \endlist
 126
 127     The \c READ, \c WRITE, and \c RESET functions can be inherited.
 128     They can also be virtual. When they are inherited in classes where
 129     multiple inheritance is used, they must come from the first
 130     inherited class.
 131
 132     The property type can be any type supported by QVariant, or it can
 133     be a user-defined type. In this example, class QDate is considered
 134     to be a user-defined type.
 135
 136     \snippet doc/src/snippets/code/doc_src_properties.qdoc 2
 137
 138     Because QDate is user-defined, you must include the \c{<QDate>}
 139     header file with the property declaration.
 140
 141     For QMap, QList, and QValueList properties, the property value is
 142     a QVariant whose value is the entire list or map.  Note that the
 143     Q_PROPERTY string cannot contain commas, because commas separate
 144     macro arguments. Therefore, you must use \c QMap as the property
 145     type instead of \c QMap<QString,QVariant>. For consistency, also
 146     use \c QList and \c QValueList instead of \c QList<QVariant> and
 147     \c QValueList<QVariant>.
 148
 149     \section1 Reading and Writing Properties with the Meta-Object System
 150
 151     A property can be read and written using the generic functions
 152     QObject::property() and QObject::setProperty(), without knowing
 153     anything about the owning class except the property's name.  In
 154     the code snippet below, the call to QAbstractButton::setDown() and
 155     the call to QObject::setProperty() both set property "down".
 156
 157     \snippet doc/src/snippets/code/doc_src_properties.qdoc 3
 158
 159     Accessing a property through its \c WRITE accessor is the better
 160     of the two, because it is faster and gives better diagnostics at
 161     compile time, but setting the property this way requires that you
 162     know about the class at compile time. Accessing properties by name
 163     lets you access classes you don't know about at compile time. You
 164     can \e discover a class's properties at run time by querying its
 165     QObject, QMetaObject, and \l {QMetaProperty} {QMetaProperties}.
 166
 167     \snippet doc/src/snippets/code/doc_src_properties.qdoc 4
 168
 169     In the above snippet, QMetaObject::property() is used to get \l
 170     {QMetaProperty} {metadata} about each property defined in some
 171     unknown class. The property name is fetched from the metadata and
 172     passed to QObject::property() to get the \l {QVariant} {value} of
 173     the property in the current \l {QObject}{object}.
 174
 175     \section1 A Simple Example
 176
 177     Suppose we have a class MyClass, which is derived from QObject and
 178     which uses the Q_OBJECT macro in its private section. We want to
 179     declare a property in MyClass to keep track of a priorty
 180     value. The name of the property will be \e priority, and its type
 181     will be an enumeration type named \e Priority, which is defined in
 182     MyClass.
 183
 184     We declare the property with the Q_PROPERTY() macro in the private
 185     section of the class. The required \c READ function is named \c
 186     priority, and we include a \c WRITE function named \c setPriority.
 187     The enumeration type must be registered with the \l {Meta-Object
 188     System} using the Q_ENUMS() macro. Registering an enumeration type
 189     makes the enumerator names available for use in calls to
 190     QObject::setProperty(). We must also provide our own declarations
 191     for the \c READ and \c WRITE functions. The declaration of MyClass
 192     then might look like this:
 193
 194     \snippet doc/src/snippets/code/doc_src_properties.qdoc 5
 195
 196     The \c READ function is const and returns the property type. The
 197     \c WRITE function returns void and has exactly one parameter of
 198     the property type. The meta-object compiler enforces these
 199     requirements.
 200
 201     Given a pointer to an instance of MyClass or a pointer to an
 202     instance of QObject that happens to be an instance of MyClass, we
 203     have two ways to set its priority property.
 204
 205     \snippet doc/src/snippets/code/doc_src_properties.qdoc 6
 206
 207     In the example, the enumeration type used for the property type
 208     was locally declared in MyClass. Had it been declared in another
 209     class, its fully qualified name (i.e., OtherClass::Priority) would
 210     be required.  In addition, that other class must also inherit
 211     QObject and register the enum type using Q_ENUMS().
 212
 213     A similar macro, Q_FLAGS(), is also available. Like Q_ENUMS(), it
 214     registers an enumeration type, but it marks the type as being a
 215     set of \e flags, i.e. values that can be OR'd together. An I/O
 216     class might have enumeration values \c Read and \c Write and then
 217     QObject::setProperty() could accept \c{Read | Write}. Q_FLAGS()
 218     should be used to register this enumeration type.
 219
 220     \section1 Dynamic Properties
 221
 222     QObject::setProperty() can also be used to add \e new properties
 223     to an instance of a class at runtime. When it is called with a
 224     name and a value, if a property with the given name exists in the
 225     QObject, and if the given value is compatible with the property's
 226     type, the value is stored in the property, and true is returned.
 227     If the value is \e not compatible with the property's type, the
 228     property is \e not changed, and false is returned. But if the
 229     property with the given name doesn't exist in the QObject (i.e.,
 230     if it wasn't declared with Q_PROPERTY(), a new property with the
 231     given name and value is automatically added to the QObject, but
 232     false is still returned. This means that a return of false can't
 233     be used to determine whether a particular property was actually
 234     set, unless you know in advance that the property already exists
 235     in the QObject.
 236
 237     Note that \e dynamic properties are added on a per instance basis,
 238     i.e., they are added to QObject, not QMetaObject. A property can
 239     be removed from an instance by passing the property name and an
 240     invalid QVariant value to QObject::setProperty(). The default
 241     constructor for QVariant constructs an invalid QVariant.
 242
 243     Dynamic properties can be queried with QObject::property(), just
 244     like properties declared at compile time with Q_PROPERTY().
 245
 246     \sa {Meta-Object System}, {Signals and Slots}
 247
 248     \section1 Properties and Custom Types
 249
 250     Custom types used by properties need to be registered using the
 251     Q_DECLARE_METATYPE() macro so that their values can be stored in
 252     QVariant objects. This makes them suitable for use with both
 253     static properties declared using the Q_PROPERTY() macro in class
 254     definitions and dynamic properties created at run-time.
 255
 256     \sa Q_DECLARE_METATYPE(), QMetaType, QVariant
 257
 258     \section1 Adding Additional Information to a Class
 259
 260     Connected to the property system is an additional macro,
 261     Q_CLASSINFO(), that can be used to attach additional
 262     \e{name}--\e{value} pairs to a class's meta-object, for example:
 263
 264     \snippet doc/src/snippets/code/doc_src_properties.qdoc 7
 265
 266     Like other meta-data, class information is accessible at run-time
 267     through the meta-object; see QMetaObject::classInfo() for details.
 268 */