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 | */
|
---|