|
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 metaobjects.html |
|
44 \title Meta-Object System |
|
45 \brief An overview of Qt's meta-object system and introspection capabilities. |
|
46 \keyword meta-object |
|
47 |
|
48 Qt's meta-object system provides the signals and slots mechanism for |
|
49 inter-object communication, run-time type information, and the dynamic |
|
50 property system. |
|
51 |
|
52 The meta-object system is based on three things: |
|
53 |
|
54 \list 1 |
|
55 \o The \l QObject class provides a base class for objects that can |
|
56 take advantage of the meta-object system. |
|
57 \o The Q_OBJECT macro inside the private section of the class |
|
58 declaration is used to enable meta-object features, such as |
|
59 dynamic properties, signals, and slots. |
|
60 \o The \l{moc}{Meta-Object Compiler} (\c moc) supplies each |
|
61 QObject subclass with the necessary code to implement |
|
62 meta-object features. |
|
63 \endlist |
|
64 |
|
65 The \c moc tool reads a C++ source file. If it finds one or more |
|
66 class declarations that contain the Q_OBJECT macro, it |
|
67 produces another C++ source file which contains the meta-object |
|
68 code for each of those classes. This generated source file is |
|
69 either \c{#include}'d into the class's source file or, more |
|
70 usually, compiled and linked with the class's implementation. |
|
71 |
|
72 In addition to providing the \l{signals and slots} mechanism for |
|
73 communication between objects (the main reason for introducing |
|
74 the system), the meta-object code provides the following |
|
75 additional features: |
|
76 |
|
77 \list |
|
78 \o QObject::metaObject() returns the associated |
|
79 \l{QMetaObject}{meta-object} for the class. |
|
80 \o QMetaObject::className() returns the class name as a |
|
81 string at run-time, without requiring native run-time type information |
|
82 (RTTI) support through the C++ compiler. |
|
83 \o QObject::inherits() function returns whether an object is an |
|
84 instance of a class that inherits a specified class within the |
|
85 QObject inheritance tree. |
|
86 \o QObject::tr() and QObject::trUtf8() translate strings for |
|
87 \l{Internationalization with Qt}{internationalization}. |
|
88 \o QObject::setProperty() and QObject::property() |
|
89 dynamically set and get properties by name. |
|
90 \o QMetaObject::newInstance() constructs a new instance of the class. |
|
91 \endlist |
|
92 |
|
93 \target qobjectcast |
|
94 It is also possible to perform dynamic casts using qobject_cast() |
|
95 on QObject classes. The qobject_cast() function behaves similarly |
|
96 to the standard C++ \c dynamic_cast(), with the advantages |
|
97 that it doesn't require RTTI support and it works across dynamic |
|
98 library boundaries. It attempts to cast its argument to the pointer |
|
99 type specified in angle-brackets, returning a non-zero pointer if the |
|
100 object is of the correct type (determined at run-time), or 0 |
|
101 if the object's type is incompatible. |
|
102 |
|
103 For example, let's assume \c MyWidget inherits from QWidget and |
|
104 is declared with the Q_OBJECT macro: |
|
105 |
|
106 \snippet doc/src/snippets/qtcast/qtcast.cpp 0 |
|
107 |
|
108 The \c obj variable, of type \c{QObject *}, actually refers to a |
|
109 \c MyWidget object, so we can cast it appropriately: |
|
110 |
|
111 \snippet doc/src/snippets/qtcast/qtcast.cpp 1 |
|
112 |
|
113 The cast from QObject to QWidget is successful, because the |
|
114 object is actually a \c MyWidget, which is a subclass of QWidget. |
|
115 Since we know that \c obj is a \c MyWidget, we can also cast it to |
|
116 \c{MyWidget *}: |
|
117 |
|
118 \snippet doc/src/snippets/qtcast/qtcast.cpp 2 |
|
119 |
|
120 The cast to \c MyWidget is successful because qobject_cast() |
|
121 makes no distinction between built-in Qt types and custom types. |
|
122 |
|
123 \snippet doc/src/snippets/qtcast/qtcast.cpp 3 |
|
124 \snippet doc/src/snippets/qtcast/qtcast.cpp 4 |
|
125 |
|
126 The cast to QLabel, on the other hand, fails. The pointer is then |
|
127 set to 0. This makes it possible to handle objects of different |
|
128 types differently at run-time, based on the type: |
|
129 |
|
130 \snippet doc/src/snippets/qtcast/qtcast.cpp 5 |
|
131 \snippet doc/src/snippets/qtcast/qtcast.cpp 6 |
|
132 |
|
133 While it is possible to use QObject as a base class without the |
|
134 Q_OBJECT macro and without meta-object code, neither signals |
|
135 and slots nor the other features described here will be available |
|
136 if the Q_OBJECT macro is not used. From the meta-object |
|
137 system's point of view, a QObject subclass without meta code is |
|
138 equivalent to its closest ancestor with meta-object code. This |
|
139 means for example, that QMetaObject::className() will not return |
|
140 the actual name of your class, but the class name of this |
|
141 ancestor. |
|
142 |
|
143 Therefore, we strongly recommend that all subclasses of QObject |
|
144 use the Q_OBJECT macro regardless of whether or not they |
|
145 actually use signals, slots, and properties. |
|
146 |
|
147 \sa QMetaObject, {Qt's Property System}, {Signals and Slots} |
|
148 */ |