1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
|
/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see http://www.qt.io/terms-conditions. For further
** information use the contact form at http://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $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.cpp 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.cpp 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.cpp 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.cpp 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.cpp 7
You can work around this restriction like this:
\snippet doc/src/snippets/code/doc_src_moc.cpp 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.cpp 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.cpp 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.cpp 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}
*/
|