source: trunk/doc/src/moc.qdoc@ 321

Last change on this file since 321 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.

File size: 12.4 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information ([email protected])
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at [email protected].
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*/
Note: See TracBrowser for help on using the repository browser.