doc/src/objectmodel/properties.qdoc

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