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

**

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

    \title Using the Meta-Object Compiler (moc)

    \ingroup qttools

    \keyword moc

    The Meta-Object Compiler, \c moc, is the program that handles

    \l{Meta-Object System}{Qt's C++ extensions}.

    The \c moc tool reads a C++ header file. If it finds one or more

    class declarations that contain the Q_OBJECT macro, it

    produces a C++ source file containing the meta-object code for

    those classes. Among other things, meta-object code is required

    for the signals and slots mechanism, the run-time type information,

    and the dynamic property system.

    The C++ source file generated by \c moc must be compiled and

    linked with the implementation of the class.

    If you use \l qmake to create your makefiles, build rules will be

    included that call the moc when required, so you will not need to

    use the moc directly. For more background information on \c moc,

    see \l{Why Doesn't Qt Use Templates for Signals and Slots?}

    \section1 Usage

    \c moc is typically used with an input file containing class

    declarations like this:

    \snippet doc/src/snippets/moc/myclass1.h 0

    In addition to the signals and slots shown above, \c moc also

    implements object properties as in the next example. The

    Q_PROPERTY() macro declares an object property, while

    Q_ENUMS() declares a list of enumeration types within the class

    to be usable inside the \l{Qt's Property System}{property

    system}.

    In the following example, we declare a property of the

    enumeration type \c Priority that is also called \c priority and

    has a get function \c priority() and a set function \c

    setPriority().

    \snippet doc/src/snippets/moc/myclass2.h 0

    The Q_FLAGS() macro declares enums that are to be used

    as flags, i.e. OR'd together. Another macro, Q_CLASSINFO(),

    allows you to attach additional name/value pairs to the class's

    meta-object:

    \snippet doc/src/snippets/moc/myclass3.h 0

    The output produced by \c moc must be compiled and linked, just

    like the other C++ code in your program; otherwise, the build

    will fail in the final link phase. If you use \c qmake, this is

    done automatically. Whenever \c qmake is run, it parses the

    project's header files and generates make rules to invoke \c moc

    for those files that contain a Q_OBJECT macro.

    If the class declaration is found in the file \c myclass.h, the

    moc output should be put in a file called \c moc_myclass.cpp.

    This file should then be compiled as usual, resulting in an

    object file, e.g., \c moc_myclass.obj on Windows. This object

    should then be included in the list of object files that are

    linked together in the final building phase of the program.

    \section1 Writing Make Rules for Invoking \c moc

    For anything but the simplest test programs, it is recommended

    that you automate running the \c{moc}. By adding some rules to

    your program's makefile, \c make can take care of running moc

    when necessary and handling the moc output.

    We recommend using the \l qmake makefile generation tool for

    building your makefiles. This tool generates a makefile that does

    all the necessary \c moc handling.

    If you want to create your makefiles yourself, here are some tips

    on how to include moc handling.

    For Q_OBJECT class declarations in header files, here is a

    useful makefile rule if you only use GNU make:

    \snippet doc/src/snippets/code/doc_src_moc.qdoc 0

    If you want to write portably, you can use individual rules of

    the following form:

    \snippet doc/src/snippets/code/doc_src_moc.qdoc 1

    You must also remember to add \c moc_foo.cpp to your \c SOURCES

    (substitute your favorite name) variable and \c moc_foo.o or \c

    moc_foo.obj to your \c OBJECTS variable.

    Both examples assume that \c $(DEFINES) and \c $(INCPATH) expand

    to the define and include path options that are passed to the C++

    compiler. These are required by \c moc to preprocess the source

    files.

    While we prefer to name our C++ source files \c .cpp, you can use

    any other extension, such as \c .C, \c .cc, \c .CC, \c .cxx, and

    \c .c++, if you prefer.

    For Q_OBJECT class declarations in implementation (\c .cpp)

    files, we suggest a makefile rule like this:

    \snippet doc/src/snippets/code/doc_src_moc.qdoc 2

    This guarantees that make will run the moc before it compiles

    \c foo.cpp. You can then put

    \snippet doc/src/snippets/code/doc_src_moc.qdoc 3

    at the end of \c foo.cpp, where all the classes declared in that

    file are fully known.

    \section1 Command-Line Options

    Here are the command-line options supported by the moc:

    \table

    \header \o Option \o Description

    \row

    \o \c{-o<file>}

    \o Write output to \c <file> rather than to standard output.

    \row

    \o \c{-f[<file>]}

    \o Force the generation of an \c #include statement in the

    output. This is the default for header files whose extension

    starts with \c H or \c h. This option is useful if you have

    header files that do not follow the standard naming conventions.

    The \c <file> part is optional.

    \row

    \o \c -i

    \o Do not generate an \c #include statement in the output.

    This may be used to run the moc on on a C++ file containing one or

    more class declarations. You should then \c #include the meta-object

    code in the \c .cpp file.

    \row

    \o \c -nw

    \o Do not generate any warnings. (Not recommended.)

    \row

    \o \c {-p<path>}

    \o Makes the moc prepend \c {<path>/} to the file name in the

    generated \c #include statement.

    \row

    \o \c {-I<dir>}

    \o Add dir to the include path for header files.

    \row

    \o \c{-E}

    \o Preprocess only; do not generate meta-object code.

    \row

    \o \c {-D<macro>[=<def>]}

    \o Define macro, with optional definition.

    \row

    \o \c{-U<macro>}

    \o Undefine macro.

    \row

    \o \c{@<file>}

    \o Read additional command-line options from \c{<file>}.

    Each line of the file is treated as a single option. Empty lines

    are ignored. Note that this option is not supported within the

    options file itself (i.e. an options file can't "include" another

    file).

    \row

    \o \c{-h}

    \o Display the usage and the list of options.

    \row

    \o \c {-v}

    \o Display \c{moc}'s version number.

    \row

    \o \c{-Fdir}

    \o Mac OS X. Add the framework directory \c{dir} to the head of

       the list of directories to be searched for header files. These

       directories are interleaved with those specified by -I options

       and are scanned in a left-to-right order (see the manpage for

       gcc). Normally, use -F /Library/Frameworks/

    \endtable

    You can explicitly tell the moc not to parse parts of a header

    file. \c moc defines the preprocessor symbol \c Q_MOC_RUN. Any

    code surrounded by

    \snippet doc/src/snippets/code/doc_src_moc.qdoc 4

    is skipped by the \c moc.

    \section1 Diagnostics

    \c moc will warn you about a number of dangerous or illegal

    constructs in the Q_OBJECT class declarations.

    If you get linkage errors in the final building phase of your

    program, saying that \c YourClass::className() is undefined or

    that \c YourClass lacks a vtable, something has been done wrong.

    Most often, you have forgotten to compile or \c #include the

    moc-generated C++ code, or (in the former case) include that

    object file in the link command. If you use \c qmake, try

    rerunning it to update your makefile. This should do the trick.

    \section1 Limitations

    \c moc does not handle all of C++. The main problem is that class

    templates cannot have signals or slots. Here is an example:

    \snippet doc/src/snippets/code/doc_src_moc.qdoc 5

    Another limitation is that moc does not expand macros, so you

    for example cannot use a macro to declare a signal/slot

    or use one to define a base class for a QObject.

    Less importantly, the following constructs are illegal. All of

    them have alternatives which we think are usually better, so

    removing these limitations is not a high priority for us.

    \section2 Multiple Inheritance Requires QObject to Be First

    If you are using multiple inheritance, \c moc assumes that the

    first inherited class is a subclass of QObject. Also, be sure

    that only the first inherited class is a QObject.

    \snippet doc/src/snippets/code/doc_src_moc.qdoc 6

    Virtual inheritance with QObject is \e not supported.

    \section2 Function Pointers Cannot Be Signal or Slot Parameters

    In most cases where you would consider using function pointers as

    signal or slot parameters, we think inheritance is a better

    alternative. Here is an example of illegal syntax:

    \snippet doc/src/snippets/code/doc_src_moc.qdoc 7

    You can work around this restriction like this:

    \snippet doc/src/snippets/code/doc_src_moc.qdoc 8

    It may sometimes be even better to replace the function pointer

    with inheritance and virtual functions.

    \section2 Enums and Typedefs Must Be Fully Qualified for Signal and Slot Parameters

    When checking the signatures of its arguments, QObject::connect()

    compares the data types literally. Thus,

    \l{Qt::Alignment}{Alignment} and \l{Qt::Alignment} are treated as

    two distinct types. To work around this limitation, make sure to

    fully qualify the data types when declaring signals and slots,

    and when establishing connections. For example:

    \snippet doc/src/snippets/code/doc_src_moc.qdoc 9

    \section2 Type Macros Cannot Be Used for Signal and Slot Parameters

    Since \c moc doesn't expand \c{#define}s, type macros that take

    an argument will not work in signals and slots. Here is an

    illegal example:

    \snippet doc/src/snippets/code/doc_src_moc.qdoc 10

    A macro without parameters will work.

    \section2 Nested Classes Cannot Have Signals or Slots

    Here's an example of the offending construct:

    \snippet doc/src/snippets/code/doc_src_moc.qdoc 11

    \section2 Signal/Slot return types cannot be references

    Signals and slots can have return types, but signals or slots returning references

    will be treated as returning void.

    \section2 Only Signals and Slots May Appear in the \c signals and \c slots Sections of a Class

    \c moc will complain if you try to put other constructs in the \c

    signals or \c slots sections of a class than signals and slots.

    \sa {Meta-Object System}, {Signals and Slots}, {Qt's Property System}

*/