1 /****************************************************************************
3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
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
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.
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.
28 ** If you have questions regarding the use of this file, please contact
29 ** Nokia at qt-info@nokia.com.
40 ****************************************************************************/
44 \title Using the Meta-Object Compiler (moc)
49 The Meta-Object Compiler, \c moc, is the program that handles
50 \l{Meta-Object System}{Qt's C++ extensions}.
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.
59 The C++ source file generated by \c moc must be compiled and
60 linked with the implementation of the class.
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?}
69 \c moc is typically used with an input file containing class
70 declarations like this:
72 \snippet doc/src/snippets/moc/myclass1.h 0
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
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
86 \snippet doc/src/snippets/moc/myclass2.h 0
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
93 \snippet doc/src/snippets/moc/myclass3.h 0
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.
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.
109 \section1 Writing Make Rules for Invoking \c moc
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.
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.
120 If you want to create your makefiles yourself, here are some tips
121 on how to include moc handling.
123 For Q_OBJECT class declarations in header files, here is a
124 useful makefile rule if you only use GNU make:
126 \snippet doc/src/snippets/code/doc_src_moc.qdoc 0
128 If you want to write portably, you can use individual rules of
131 \snippet doc/src/snippets/code/doc_src_moc.qdoc 1
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.
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
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.
146 For Q_OBJECT class declarations in implementation (\c .cpp)
147 files, we suggest a makefile rule like this:
149 \snippet doc/src/snippets/code/doc_src_moc.qdoc 2
151 This guarantees that make will run the moc before it compiles
152 \c foo.cpp. You can then put
154 \snippet doc/src/snippets/code/doc_src_moc.qdoc 3
156 at the end of \c foo.cpp, where all the classes declared in that
157 file are fully known.
159 \section1 Command-Line Options
161 Here are the command-line options supported by the moc:
164 \header \o Option \o Description
168 \o Write output to \c <file> rather than to standard output.
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.
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.
187 \o Do not generate any warnings. (Not recommended.)
191 \o Makes the moc prepend \c {<path>/} to the file name in the
192 generated \c #include statement.
196 \o Add dir to the include path for header files.
200 \o Preprocess only; do not generate meta-object code.
203 \o \c {-D<macro>[=<def>]}
204 \o Define macro, with optional definition.
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
220 \o Display the usage and the list of options.
224 \o Display \c{moc}'s version number.
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/
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
241 \snippet doc/src/snippets/code/doc_src_moc.qdoc 4
243 is skipped by the \c moc.
245 \section1 Diagnostics
247 \c moc will warn you about a number of dangerous or illegal
248 constructs in the Q_OBJECT class declarations.
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.
258 \section1 Limitations
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:
263 \snippet doc/src/snippets/code/doc_src_moc.qdoc 5
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.
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.
273 \section2 Multiple Inheritance Requires QObject to Be First
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.
279 \snippet doc/src/snippets/code/doc_src_moc.qdoc 6
281 Virtual inheritance with QObject is \e not supported.
283 \section2 Function Pointers Cannot Be Signal or Slot Parameters
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:
289 \snippet doc/src/snippets/code/doc_src_moc.qdoc 7
291 You can work around this restriction like this:
293 \snippet doc/src/snippets/code/doc_src_moc.qdoc 8
295 It may sometimes be even better to replace the function pointer
296 with inheritance and virtual functions.
298 \section2 Enums and Typedefs Must Be Fully Qualified for Signal and Slot Parameters
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:
307 \snippet doc/src/snippets/code/doc_src_moc.qdoc 9
309 \section2 Type Macros Cannot Be Used for Signal and Slot Parameters
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
315 \snippet doc/src/snippets/code/doc_src_moc.qdoc 10
317 A macro without parameters will work.
319 \section2 Nested Classes Cannot Have Signals or Slots
321 Here's an example of the offending construct:
323 \snippet doc/src/snippets/code/doc_src_moc.qdoc 11
325 \section2 Signal/Slot return types cannot be references
327 Signals and slots can have return types, but signals or slots returning references
328 will be treated as returning void.
330 \section2 Only Signals and Slots May Appear in the \c signals and \c slots Sections of a Class
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.
335 \sa {Meta-Object System}, {Signals and Slots}, {Qt's Property System}