1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
|
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights. These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page properties.html
\title Qt's Property System
\brief An overview of 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.qdoc 0
Here are some typical examples of property declarations taken from
class QWidget.
\snippet doc/src/snippets/code/doc_src_properties.qdoc 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, the signal will be
emitted whenever the value of the property changes. The signal must
take one parameter, which must be of the same type as the property; the
parameter will take the new value of the property.
\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.qdoc 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.qdoc 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.qdoc 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.qdoc 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 an
instance of QObject that happens to be an instance of MyClass, we
have two ways to set its priority property.
\snippet doc/src/snippets/code/doc_src_properties.qdoc 6
In the example, the enumeration type used for the property type
was locally declared in MyClass. Had it been declared in another
class, its fully qualified name (i.e., OtherClass::Priority) would
be required. In addition, that other class must also inherit
QObject and register the enum type using Q_ENUMS().
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.qdoc 7
Like other meta-data, class information is accessible at run-time
through the meta-object; see QMetaObject::classInfo() for details.
*/
|
