summaryrefslogtreecommitdiffstats
path: root/doc/src/metaobjects.qdoc
blob: c11cf4d15ef1436b7e476d9e3daed2ea515569bf (plain)
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
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** 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.0, 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 are unsure which license is appropriate for your use, please
** contact the sales department at http://qt.nokia.com/contact.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page metaobjects.html
    \title Meta-Object System
    \brief An overview of Qt's meta-object system and introspection capabilities.
    \ingroup architecture
    \keyword meta-object

    Qt's meta-object system provides the signals and slots mechanism for
    inter-object communication, run-time type information, and the dynamic
    property system.

    The meta-object system is based on three things:

    \list 1
    \o The \l QObject class provides a base class for objects that can
       take advantage of the meta-object system.
    \o The Q_OBJECT macro inside the private section of the class
       declaration is used to enable meta-object features, such as
       dynamic properties, signals, and slots.
    \o The \l{moc}{Meta-Object Compiler} (\c moc) supplies each
       QObject subclass with the necessary code to implement
       meta-object features.
    \endlist

    The \c moc tool reads a C++ source file. If it finds one or more
    class declarations that contain the Q_OBJECT macro, it
    produces another C++ source file which contains the meta-object
    code for each of those classes. This generated source file is
    either \c{#include}'d into the class's source file or, more
    usually, compiled and linked with the class's implementation.

    In addition to providing the \l{signals and slots} mechanism for
    communication between objects (the main reason for introducing
    the system), the meta-object code provides the following
    additional features:

    \list
    \o QObject::metaObject() returns the associated
       \l{QMetaObject}{meta-object} for the class.
    \o QMetaObject::className() returns the class name as a
       string at run-time, without requiring native run-time type information
       (RTTI) support through the C++ compiler.
    \o QObject::inherits() function returns whether an object is an
       instance of a class that inherits a specified class within the
       QObject inheritance tree.
    \o QObject::tr() and QObject::trUtf8() translate strings for
       \l{Internationalization with Qt}{internationalization}.
    \o QObject::setProperty() and QObject::property()
       dynamically set and get properties by name.
    \o QMetaObject::newInstance() constructs a new instance of the class.
    \endlist

    \target qobjectcast
    It is also possible to perform dynamic casts using qobject_cast()
    on QObject classes. The qobject_cast() function behaves similarly
    to the standard C++ \c dynamic_cast(), with the advantages
    that it doesn't require RTTI support and it works across dynamic
    library boundaries. It attempts to cast its argument to the pointer
    type specified in angle-brackets, returning a non-zero pointer if the
    object is of the correct type (determined at run-time), or 0
    if the object's type is incompatible.

    For example, let's assume \c MyWidget inherits from QWidget and
    is declared with the Q_OBJECT macro:

    \snippet doc/src/snippets/qtcast/qtcast.cpp 0

    The \c obj variable, of type \c{QObject *}, actually refers to a
    \c MyWidget object, so we can cast it appropriately:

    \snippet doc/src/snippets/qtcast/qtcast.cpp 1

    The cast from QObject to QWidget is successful, because the
    object is actually a \c MyWidget, which is a subclass of QWidget.
    Since we know that \c obj is a \c MyWidget, we can also cast it to
    \c{MyWidget *}:

    \snippet doc/src/snippets/qtcast/qtcast.cpp 2

    The cast to \c MyWidget is successful because qobject_cast()
    makes no distinction between built-in Qt types and custom types.

    \snippet doc/src/snippets/qtcast/qtcast.cpp 3
    \snippet doc/src/snippets/qtcast/qtcast.cpp 4

    The cast to QLabel, on the other hand, fails. The pointer is then
    set to 0. This makes it possible to handle objects of different
    types differently at run-time, based on the type:

    \snippet doc/src/snippets/qtcast/qtcast.cpp 5
    \snippet doc/src/snippets/qtcast/qtcast.cpp 6

    While it is possible to use QObject as a base class without the
    Q_OBJECT macro and without meta-object code, neither signals
    and slots nor the other features described here will be available
    if the Q_OBJECT macro is not used. From the meta-object
    system's point of view, a QObject subclass without meta code is
    equivalent to its closest ancestor with meta-object code. This
    means for example, that QMetaObject::className() will not return
    the actual name of your class, but the class name of this
    ancestor.

    Therefore, we strongly recommend that all subclasses of QObject
    use the Q_OBJECT macro regardless of whether or not they
    actually use signals, slots, and properties.

    \sa QMetaObject, {Qt's Property System}, {Signals and Slots}
*/