/****************************************************************************+
−
**+
−
** Copyright (C) 2010 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}+
−
*/+
−