/**************************************************************************** ** ** 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$ ** 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 Technology Preview License Agreement accompanying ** this package. ** ** 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. ** ** If you have questions regarding the use of this file, please contact ** Nokia at qt-info@nokia.com. ** ** ** ** ** ** ** ** ** $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} */