source: trunk/doc/src/development/moc.qdoc@ 568

Last change on this file since 568 was 561, checked in by Dmitry A. Kuminov, 15 years ago

trunk: Merged in qt 4.6.1 sources.

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