doc/src/moc.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Lesser General Public License Usage
  17 ** Alternatively, this file may be used under the terms of the GNU Lesser
  18 ** General Public License version 2.1 as published by the Free Software
  19 ** Foundation and appearing in the file LICENSE.LGPL included in the
  20 ** packaging of this file.  Please review the following information to
  21 ** ensure the GNU Lesser General Public License version 2.1 requirements
  22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  23 **
  24 ** In addition, as a special exception, Nokia gives you certain additional
  25 ** rights.  These rights are described in the Nokia Qt LGPL Exception
  26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  27 **
  28 ** If you have questions regarding the use of this file, please contact
  29 ** Nokia at qt-info@nokia.com.
  30 **
  31 **
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 /*!
  43     \page moc.html
  44     \title Using the Meta-Object Compiler (moc)
  45     \ingroup buildsystem
  46     \ingroup qttools
  47     \keyword moc
  48
  49     The Meta-Object Compiler, \c moc, is the program that handles
  50     \l{Meta-Object System}{Qt's C++ extensions}.
  51
  52     The \c moc tool reads a C++ header file. If it finds one or more
  53     class declarations that contain the Q_OBJECT macro, it
  54     produces a C++ source file containing the meta-object code for
  55     those classes. Among other things, meta-object code is required
  56     for the signals and slots mechanism, the run-time type information,
  57     and the dynamic property system.
  58
  59     The C++ source file generated by \c moc must be compiled and
  60     linked with the implementation of the class.
  61
  62     If you use \l qmake to create your makefiles, build rules will be
  63     included that call the moc when required, so you will not need to
  64     use the moc directly. For more background information on \c moc,
  65     see \l{Why Doesn't Qt Use Templates for Signals and Slots?}
  66
  67     \section1 Usage
  68
  69     \c moc is typically used with an input file containing class
  70     declarations like this:
  71
  72     \snippet doc/src/snippets/moc/myclass1.h 0
  73
  74     In addition to the signals and slots shown above, \c moc also
  75     implements object properties as in the next example. The
  76     Q_PROPERTY() macro declares an object property, while
  77     Q_ENUMS() declares a list of enumeration types within the class
  78     to be usable inside the \l{Qt's Property System}{property
  79     system}.
  80
  81     In the following example, we declare a property of the
  82     enumeration type \c Priority that is also called \c priority and
  83     has a get function \c priority() and a set function \c
  84     setPriority().
  85
  86     \snippet doc/src/snippets/moc/myclass2.h 0
  87
  88     The Q_FLAGS() macro declares enums that are to be used
  89     as flags, i.e. OR'd together. Another macro, Q_CLASSINFO(),
  90     allows you to attach additional name/value pairs to the class's
  91     meta-object:
  92
  93     \snippet doc/src/snippets/moc/myclass3.h 0
  94
  95     The output produced by \c moc must be compiled and linked, just
  96     like the other C++ code in your program; otherwise, the build
  97     will fail in the final link phase. If you use \c qmake, this is
  98     done automatically. Whenever \c qmake is run, it parses the
  99     project's header files and generates make rules to invoke \c moc
 100     for those files that contain a Q_OBJECT macro.
 101
 102     If the class declaration is found in the file \c myclass.h, the
 103     moc output should be put in a file called \c moc_myclass.cpp.
 104     This file should then be compiled as usual, resulting in an
 105     object file, e.g., \c moc_myclass.obj on Windows. This object
 106     should then be included in the list of object files that are
 107     linked together in the final building phase of the program.
 108
 109     \section1 Writing Make Rules for Invoking \c moc
 110
 111     For anything but the simplest test programs, it is recommended
 112     that you automate running the \c{moc}. By adding some rules to
 113     your program's makefile, \c make can take care of running moc
 114     when necessary and handling the moc output.
 115
 116     We recommend using the \l qmake makefile generation tool for
 117     building your makefiles. This tool generates a makefile that does
 118     all the necessary \c moc handling.
 119
 120     If you want to create your makefiles yourself, here are some tips
 121     on how to include moc handling.
 122
 123     For Q_OBJECT class declarations in header files, here is a
 124     useful makefile rule if you only use GNU make:
 125
 126     \snippet doc/src/snippets/code/doc_src_moc.qdoc 0
 127
 128     If you want to write portably, you can use individual rules of
 129     the following form:
 130
 131     \snippet doc/src/snippets/code/doc_src_moc.qdoc 1
 132
 133     You must also remember to add \c moc_foo.cpp to your \c SOURCES
 134     (substitute your favorite name) variable and \c moc_foo.o or \c
 135     moc_foo.obj to your \c OBJECTS variable.
 136
 137     Both examples assume that \c $(DEFINES) and \c $(INCPATH) expand
 138     to the define and include path options that are passed to the C++
 139     compiler. These are required by \c moc to preprocess the source
 140     files.
 141
 142     While we prefer to name our C++ source files \c .cpp, you can use
 143     any other extension, such as \c .C, \c .cc, \c .CC, \c .cxx, and
 144     \c .c++, if you prefer.
 145
 146     For Q_OBJECT class declarations in implementation (\c .cpp)
 147     files, we suggest a makefile rule like this:
 148
 149     \snippet doc/src/snippets/code/doc_src_moc.qdoc 2
 150
 151     This guarantees that make will run the moc before it compiles
 152     \c foo.cpp. You can then put
 153
 154     \snippet doc/src/snippets/code/doc_src_moc.qdoc 3
 155
 156     at the end of \c foo.cpp, where all the classes declared in that
 157     file are fully known.
 158
 159     \section1 Command-Line Options
 160
 161     Here are the command-line options supported by the moc:
 162
 163     \table
 164     \header \o Option \o Description
 165
 166     \row
 167     \o \c{-o<file>}
 168     \o Write output to \c <file> rather than to standard output.
 169
 170     \row
 171     \o \c{-f[<file>]}
 172     \o Force the generation of an \c #include statement in the
 173     output. This is the default for header files whose extension
 174     starts with \c H or \c h. This option is useful if you have
 175     header files that do not follow the standard naming conventions.
 176     The \c <file> part is optional.
 177
 178     \row
 179     \o \c -i
 180     \o Do not generate an \c #include statement in the output.
 181     This may be used to run the moc on on a C++ file containing one or
 182     more class declarations. You should then \c #include the meta-object
 183     code in the \c .cpp file.
 184
 185     \row
 186     \o \c -nw
 187     \o Do not generate any warnings. (Not recommended.)
 188
 189     \row
 190     \o \c {-p<path>}
 191     \o Makes the moc prepend \c {<path>/} to the file name in the
 192     generated \c #include statement.
 193
 194     \row
 195     \o \c {-I<dir>}
 196     \o Add dir to the include path for header files.
 197
 198     \row
 199     \o \c{-E}
 200     \o Preprocess only; do not generate meta-object code.
 201
 202     \row
 203     \o \c {-D<macro>[=<def>]}
 204     \o Define macro, with optional definition.
 205
 206     \row
 207     \o \c{-U<macro>}
 208     \o Undefine macro.
 209
 210     \row
 211     \o \c{@<file>}
 212     \o Read additional command-line options from \c{<file>}.
 213     Each line of the file is treated as a single option. Empty lines
 214     are ignored. Note that this option is not supported within the
 215     options file itself (i.e. an options file can't "include" another
 216     file).
 217
 218     \row
 219     \o \c{-h}
 220     \o Display the usage and the list of options.
 221
 222     \row
 223     \o \c {-v}
 224     \o Display \c{moc}'s version number.
 225
 226     \row
 227     \o \c{-Fdir}
 228
 229     \o Mac OS X. Add the framework directory \c{dir} to the head of
 230        the list of directories to be searched for header files. These
 231        directories are interleaved with those specified by -I options
 232        and are scanned in a left-to-right order (see the manpage for
 233        gcc). Normally, use -F /Library/Frameworks/
 234
 235     \endtable
 236
 237     You can explicitly tell the moc not to parse parts of a header
 238     file. \c moc defines the preprocessor symbol \c Q_MOC_RUN. Any
 239     code surrounded by
 240
 241     \snippet doc/src/snippets/code/doc_src_moc.qdoc 4
 242
 243     is skipped by the \c moc.
 244
 245     \section1 Diagnostics
 246
 247     \c moc will warn you about a number of dangerous or illegal
 248     constructs in the Q_OBJECT class declarations.
 249
 250     If you get linkage errors in the final building phase of your
 251     program, saying that \c YourClass::className() is undefined or
 252     that \c YourClass lacks a vtable, something has been done wrong.
 253     Most often, you have forgotten to compile or \c #include the
 254     moc-generated C++ code, or (in the former case) include that
 255     object file in the link command. If you use \c qmake, try
 256     rerunning it to update your makefile. This should do the trick.
 257
 258     \section1 Limitations
 259
 260     \c moc does not handle all of C++. The main problem is that class
 261     templates cannot have signals or slots. Here is an example:
 262
 263     \snippet doc/src/snippets/code/doc_src_moc.qdoc 5
 264
 265     Another limitation is that moc does not expand macros, so you
 266     for example cannot use a macro to declare a signal/slot
 267     or use one to define a base class for a QObject.
 268
 269     Less importantly, the following constructs are illegal. All of
 270     them have alternatives which we think are usually better, so
 271     removing these limitations is not a high priority for us.
 272
 273     \section2 Multiple Inheritance Requires QObject to Be First
 274
 275     If you are using multiple inheritance, \c moc assumes that the
 276     first inherited class is a subclass of QObject. Also, be sure
 277     that only the first inherited class is a QObject.
 278
 279     \snippet doc/src/snippets/code/doc_src_moc.qdoc 6
 280
 281     Virtual inheritance with QObject is \e not supported.
 282
 283     \section2 Function Pointers Cannot Be Signal or Slot Parameters
 284
 285     In most cases where you would consider using function pointers as
 286     signal or slot parameters, we think inheritance is a better
 287     alternative. Here is an example of illegal syntax:
 288
 289     \snippet doc/src/snippets/code/doc_src_moc.qdoc 7
 290
 291     You can work around this restriction like this:
 292
 293     \snippet doc/src/snippets/code/doc_src_moc.qdoc 8
 294
 295     It may sometimes be even better to replace the function pointer
 296     with inheritance and virtual functions.
 297
 298     \section2 Enums and Typedefs Must Be Fully Qualified for Signal and Slot Parameters
 299
 300     When checking the signatures of its arguments, QObject::connect()
 301     compares the data types literally. Thus,
 302     \l{Qt::Alignment}{Alignment} and \l{Qt::Alignment} are treated as
 303     two distinct types. To work around this limitation, make sure to
 304     fully qualify the data types when declaring signals and slots,
 305     and when establishing connections. For example:
 306
 307     \snippet doc/src/snippets/code/doc_src_moc.qdoc 9
 308
 309     \section2 Type Macros Cannot Be Used for Signal and Slot Parameters
 310
 311     Since \c moc doesn't expand \c{#define}s, type macros that take
 312     an argument will not work in signals and slots. Here is an
 313     illegal example:
 314
 315     \snippet doc/src/snippets/code/doc_src_moc.qdoc 10
 316
 317     A macro without parameters will work.
 318
 319     \section2 Nested Classes Cannot Have Signals or Slots
 320
 321     Here's an example of the offending construct:
 322
 323     \snippet doc/src/snippets/code/doc_src_moc.qdoc 11
 324
 325     \section2 Signal/Slot return types cannot be references
 326
 327     Signals and slots can have return types, but signals or slots returning references
 328     will be treated as returning void.
 329
 330     \section2 Only Signals and Slots May Appear in the \c signals and \c slots Sections of a Class
 331
 332     \c moc will complain if you try to put other constructs in the \c
 333     signals or \c slots sections of a class than signals and slots.
 334
 335     \sa {Meta-Object System}, {Signals and Slots}, {Qt's Property System}
 336 */