Long live Qt 4.5!

1 files changed, 336 insertions, 0 deletions

diff --git a/doc/src/moc.qdoc b/doc/src/moc.qdoc
new file mode 100644
index 0000000..b7283c4
--- /dev/null
+++ b/doc/src/moc.qdoc
@@ -0,0 +1,336 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page moc.html
+    \title Using the Meta-Object Compiler (moc)
+    \ingroup buildsystem
+    \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}
+*/