/****************************************************************************
**
** Copyright (C) 2004-2008 Trolltech ASA. All rights reserved.
**
** This file is part of the documentation of the Qt Toolkit.
**
** This file may be used under the terms of the GNU General Public
** License versions 2.0 or 3.0 as published by the Free Software
** Foundation and appearing in the files LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file.  Alternatively you may (at
** your option) use any later version of the GNU General Public
** License if such license has been publicly approved by Trolltech ASA
** (or its successors, if any) and the KDE Free Qt Foundation. 
**
** Please review the following information to ensure GNU General
** Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/. If
** you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** In addition, as a special exception, Trolltech, as the sole
** copyright holder for Qt Designer, grants users of the Qt/Eclipse
** Integration plug-in the right for the Qt/Eclipse Integration to
** link to functionality provided by Qt Designer and its related
** libraries.
**
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE. Trolltech reserves all rights not expressly
** granted herein.
**
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
**
****************************************************************************/

/*!
    \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.
    \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}
*/
