/****************************************************************************

**

** 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.

    \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}

*/