1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the documentation of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** GNU Free Documentation License
10 ** Alternatively, this file may be used under the terms of the GNU Free
11 ** Documentation License version 1.3 as published by the Free Software
12 ** Foundation and appearing in the file included in the packaging of
16 ** Alternatively, this file may be used in accordance with the terms
17 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
30 \title The Property System
31 \brief An overview of Qt's property system.
33 \ingroup qt-basic-concepts
34 \target Qt's Property System
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}.
44 \section1 Requirements for Declaring Properties
46 To declare a property, use the \l {Q_PROPERTY()} {Q_PROPERTY()}
47 macro in a class that inherits QObject.
49 \snippet code/doc_src_properties.cpp 0
51 Here are some typical examples of property declarations taken from
54 \snippet code/doc_src_properties.cpp 1
56 A property behaves like a class data member, but it has additional
57 features accessible through the \l {Meta-Object System}.
61 \li 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().
67 \li 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.
74 \li 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.
82 \li 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.
86 \li 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.
90 \li 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
96 \li 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
101 \li 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.
109 \li 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.
116 \li 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.
122 \li 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.
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
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.
138 \snippet code/doc_src_properties.cpp 2
140 Because QDate is user-defined, you must include the \c{<QDate>}
141 header file with the property declaration.
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>.
151 \section1 Reading and Writing Properties with the Meta-Object System
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".
159 \snippet code/doc_src_properties.cpp 3
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}.
169 \snippet code/doc_src_properties.cpp 4
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}.
177 \section1 A Simple Example
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
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:
196 \snippet code/doc_src_properties.cpp 5
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
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:
207 \snippet code/doc_src_properties.cpp 6
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.
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.
225 \section1 Dynamic Properties
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
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.
248 Dynamic properties can be queried with QObject::property(), just
249 like properties declared at compile time with Q_PROPERTY().
251 \sa {Meta-Object System}, {Signals and Slots}
253 \section1 Properties and Custom Types
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.
261 \sa Q_DECLARE_METATYPE(), QMetaType, QVariant
263 \section1 Adding Additional Information to a Class
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:
269 \snippet code/doc_src_properties.cpp 7
271 Like other meta-data, class information is accessible at run-time
272 through the meta-object; see QMetaObject::classInfo() for details.