doc/src/objectmodel/metaobjects.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 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: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
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \page metaobjects.html
  30     \title The Meta-Object System
  31     \brief An overview of Qt's meta-object system and introspection capabilities.
  32
  33     \ingroup qt-basic-concepts
  34     \keyword meta-object
  35     \target Meta-Object System
  36
  37     Qt's meta-object system provides the signals and slots mechanism for
  38     inter-object communication, run-time type information, and the dynamic
  39     property system.
  40
  41     The meta-object system is based on three things:
  42
  43     \list 1
  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
  51        meta-object features.
  52     \endlist
  53
  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.
  60
  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
  64     additional features:
  65
  66     \list
  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.
  80     \endlist
  81
  82     \target qobjectcast
  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.
  91
  92     For example, let's assume \c MyWidget inherits from QWidget and
  93     is declared with the Q_OBJECT macro:
  94
  95     \snippet doc/src/snippets/qtcast/qtcast.cpp 0
  96
  97     The \c obj variable, of type \c{QObject *}, actually refers to a
  98     \c MyWidget object, so we can cast it appropriately:
  99
 100     \snippet doc/src/snippets/qtcast/qtcast.cpp 1
 101
 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
 105     \c{MyWidget *}:
 106
 107     \snippet doc/src/snippets/qtcast/qtcast.cpp 2
 108
 109     The cast to \c MyWidget is successful because qobject_cast()
 110     makes no distinction between built-in Qt types and custom types.
 111
 112     \snippet doc/src/snippets/qtcast/qtcast.cpp 3
 113     \snippet doc/src/snippets/qtcast/qtcast.cpp 4
 114
 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:
 118
 119     \snippet doc/src/snippets/qtcast/qtcast.cpp 5
 120     \snippet doc/src/snippets/qtcast/qtcast.cpp 6
 121
 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
 130     ancestor.
 131
 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.
 135
 136     \sa QMetaObject, {Qt's Property System}, {Signals and Slots}
 137 */