diff options
Diffstat (limited to 'doc/src/objectmodel/metaobjects.qdoc')
| -rw-r--r-- | doc/src/objectmodel/metaobjects.qdoc | 148 |
1 files changed, 148 insertions, 0 deletions
diff --git a/doc/src/objectmodel/metaobjects.qdoc b/doc/src/objectmodel/metaobjects.qdoc new file mode 100644 index 0000000..961a4c6 --- /dev/null +++ b/doc/src/objectmodel/metaobjects.qdoc @@ -0,0 +1,148 @@ +/**************************************************************************** +** +** 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. + \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} +*/ |