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