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