1 /****************************************************************************
3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
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
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.
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.
28 ** If you have questions regarding the use of this file, please contact
29 ** Nokia at qt-info@nokia.com.
40 ****************************************************************************/
44 \title Qt's Property System
46 \brief An overview of Qt's property system.
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}.
56 \section1 Requirements for Declaring Properties
58 To declare a property, use the \l {Q_PROPERTY()} {Q_PROPERTY()}
59 macro in a class that inherits QObject.
61 \snippet doc/src/snippets/code/doc_src_properties.qdoc 0
63 Here are some typical examples of property declarations taken from
66 \snippet doc/src/snippets/code/doc_src_properties.qdoc 1
68 A property behaves like a class data member, but it has additional
69 features accessible through the \l {Meta-Object System}.
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
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.
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.
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.
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
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
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.
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.
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
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.
136 \snippet doc/src/snippets/code/doc_src_properties.qdoc 2
138 Because QDate is user-defined, you must include the \c{<QDate>}
139 header file with the property declaration.
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>.
149 \section1 Reading and Writing Properties with the Meta-Object System
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".
157 \snippet doc/src/snippets/code/doc_src_properties.qdoc 3
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}.
167 \snippet doc/src/snippets/code/doc_src_properties.qdoc 4
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}.
175 \section1 A Simple Example
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
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:
194 \snippet doc/src/snippets/code/doc_src_properties.qdoc 5
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
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.
205 \snippet doc/src/snippets/code/doc_src_properties.qdoc 6
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().
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.
220 \section1 Dynamic Properties
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
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.
243 Dynamic properties can be queried with QObject::property(), just
244 like properties declared at compile time with Q_PROPERTY().
246 \sa {Meta-Object System}, {Signals and Slots}
248 \section1 Properties and Custom Types
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.
256 \sa Q_DECLARE_METATYPE(), QMetaType, QVariant
258 \section1 Adding Additional Information to a Class
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:
264 \snippet doc/src/snippets/code/doc_src_properties.qdoc 7
266 Like other meta-data, class information is accessible at run-time
267 through the meta-object; see QMetaObject::classInfo() for details.