source: trunk/doc/html/moc.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 17.1 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/moc.doc:39 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>Using the Meta Object Compiler</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>Using the Meta Object Compiler</h1>
33
34
35
36<p> <!-- index moc --><a name="moc"></a>
37<p> The Meta Object Compiler, moc among friends, is the program which
38handles Qt's <a href="metaobjects.html">C++ extensions.</a>
39<p> The moc reads a C++ source file. If it finds one or more class
40declarations that contain the <a href="metaobjects.html#Q_OBJECT">Q_OBJECT</a> macro, it produces another
41C++ source file which contains the <a href="metaobjects.html#meta-object">meta object</a> code for the classes
42that use the Q_OBJECT macro. Among other things, meta object code is
43required for the signal/slot mechanism, runtime type information and
44the dynamic property system.
45<p> The C++ source file generated by the moc must be compiled and linked
46with the implementation of the class (or it can be #included into the
47class's source file).
48<p> If you use <a href="qmake-manual.html">qmake</a> to create your
49Makefiles, build rules will be included that call the moc when
50required, so you will not need to use the moc directly. For more
51background information on moc, see <a href="templates.html">Why doesn't Qt
52use templates for signals and slots?</a>.
53<p> <h2> Usage
54</h2>
55<a name="1"></a><p> The moc is typically used with an input file containing class declarations
56like this:
57<p> <pre>
58 class MyClass : public <a href="qobject.html">QObject</a>
59 {
60 Q_OBJECT
61 public:
62 MyClass( <a href="qobject.html">QObject</a> * parent=0, const char * name=0 );
63 ~MyClass();
64
65 signals:
66 void mySignal();
67
68 public slots:
69 void mySlot();
70
71 };
72</pre>
73
74<p> In addition to the signals and slots shown above, the moc also
75implements object properties as in the next example. The Q_PROPERTY
76macro declares an object property, while Q_ENUMS declares a list of
77enumeration types within the class to be usable inside the
78<a href="properties.html">property system</a>. In this particular
79case we declare a property of the enumeration type <tt>Priority</tt> that is
80also called "priority" and has a get function <tt>priority()</tt> and a set
81function <tt>setPriority()</tt>.
82<p> <pre>
83 class MyClass : public <a href="qobject.html">QObject</a>
84 {
85 Q_OBJECT
86 Q_PROPERTY( Priority priority READ priority WRITE setPriority )
87 Q_ENUMS( Priority )
88 public:
89 MyClass( <a href="qobject.html">QObject</a> * parent=0, const char * name=0 );
90 ~MyClass();
91
92 enum Priority { High, Low, VeryHigh, VeryLow };
93 void setPriority( Priority );
94 Priority priority() const;
95 };
96</pre>
97
98<p> Properties can be modified in subclasses with the Q_OVERRIDE
99macro. The Q_SETS macro declares enums that are to be used as
100sets, i.e. OR'ed together. Another macro, Q_CLASSINFO, can be used to
101attach additional name/value-pairs to the class' meta object:
102<p> <pre>
103 class MyClass : public <a href="qobject.html">QObject</a>
104 {
105 Q_OBJECT
106 Q_CLASSINFO( "Author", "Oscar Peterson")
107 Q_CLASSINFO( "Status", "Active")
108 public:
109 MyClass( <a href="qobject.html">QObject</a> * parent=0, const char * name=0 );
110 ~MyClass();
111 };
112</pre>
113
114<p> The three concepts, signals and slots, properties and class
115meta-data, can be combined.
116<p> The output produced by the moc must be compiled and linked, just like
117the other C++ code in your program; otherwise the build will fail in
118the final link phase. By convention, this is done in one of the
119following two ways:
120<p> <dl>
121<p> <dt><b>Method A: The class declaration is found in a header
122(<em>.h</em>) file</b>
123<p> <dd>If the class declaration above is found in the file
124<em>myclass.h</em>, the moc output should be put in a file called
125<em>moc_myclass.cpp</em>. This file should then be compiled as
126usual, resulting in an object file <em>moc_myclass.o</em> (on Unix)
127or <em>moc_myclass.obj</em> (on Windows). This object should then be
128included in the list of object files that are linked together in the
129final building phase of the program.
130<p> <dt><b>Method B: The class declaration is found in an implementation
131(<em>.cpp</em>) file</b>
132<p> <dd>If the class declaration above is found in the file
133<em>myclass.cpp</em>, the moc output should be put in a file called
134<em>myclass.moc</em>. This file should be #included in the
135implementation file, i.e. <em>myclass.cpp</em> should contain the
136line
137<pre>
138 #include "myclass.moc"
139</pre>
140
141at the end. This will cause the moc-generated code to be compiled and
142linked together with the normal class definition in <em>myclass.cpp</em>, so
143it is not necessary to compile and link it separately, as in Method A.
144<p> </dl>
145<p> Method A is the normal method. Method B can be used in cases where you
146want the implementation file to be self-contained, or in cases where
147the Q_OBJECT class is implementation-internal and thus should not be
148visible in the header file.
149<p> <h2> Automating moc Usage with Makefiles
150</h2>
151<a name="2"></a><p> For anything but the simplest test programs, it is recommended that
152you automate running the moc. By adding some rules to your program's
153Makefile, <em>make</em> can take care of running moc when necessary and
154handling the moc output.
155<p> We recommend using Trolltech's free makefile generation tool, <a href="qmake-manual.html">qmake</a>, for building your Makefiles. This tool
156recognizes both Method A and B style source files, and generates a
157Makefile that does all the necessary moc handling.
158<p> If you want to create your Makefiles yourself, here are some tips on
159how to include moc handling.
160<p> For Q_OBJECT class declarations in header files, here is a useful
161makefile rule if you only use GNU make:
162<p> <pre>
163 moc_%.cpp: %.h
164 moc $&lt; -o $@
165</pre>
166
167<p> If you want to write portably, you can use individual rules with the
168following form:
169<p> <pre>
170 moc_NAME.cpp: NAME.h
171 moc $&lt; -o $@
172</pre>
173
174<p> You must also remember to add <em>moc_NAME.cpp</em> to your SOURCES
175(substitute your favorite name) variable and <em>moc_NAME.o</em> or
176<em>moc_NAME.obj</em> to your OBJECTS variable.
177<p> (While we prefer to name our C++ source files .cpp, the moc doesn't
178care, so you can use .C, .cc, .CC, .cxx or even .c++ if you
179prefer.)
180<p> For Q_OBJECT class declarations in implementation (.cpp) files, we
181suggest a makefile rule like this:
182<p> <pre>
183 NAME.o: NAME.moc
184
185 NAME.moc: NAME.cpp
186 moc -i $&lt; -o $@
187</pre>
188
189<p> This guarantees that make will run the moc before it compiles
190<em>NAME.cpp</em>. You can then put
191<p> <pre>
192 #include "NAME.moc"
193</pre>
194
195<p> at the end of <em>NAME.cpp</em>, where all the classes declared in
196that file are fully known.
197<p> <h2> Invoking moc
198</h2>
199<a name="3"></a><p> Here are the command-line options supported by the moc:
200<p> <center><table cellpadding="4" cellspacing="2" border="0">
201<tr bgcolor="#a2c511"> <th valign="top">Option <th valign="top">Meaning
202<tr bgcolor="#f0f0f0">
203<td valign="top">-o <em>file</em>
204<td valign="top">Write output to <em>file</em> rather than to stdout.
205<tr bgcolor="#d0d0d0">
206<td valign="top">-f
207<td valign="top">Force the generation of an #include statement in the
208output. This is the default for files whose name matches the <a href="qregexp.html#regular-expression">regular expression</a> &#92;.[hH][^.]* (i.e. the extension starts with H or h). This
209option is only useful if you have header files that do not follow the
210standard naming conventions.
211<tr bgcolor="#f0f0f0">
212<td valign="top">-i
213<td valign="top">Do not generate an #include statement in the output.
214This may be used to run the moc on on a C++ file containing one or
215more class declarations. You should then #include the meta object
216code in the .cpp
217file. If both -i and -f are present, the last one wins.
218<tr bgcolor="#d0d0d0">
219<td valign="top">-nw
220<td valign="top">Do not generate any warnings. Not recommended.
221<tr bgcolor="#f0f0f0">
222<td valign="top">-ldbg
223<td valign="top">Write a flood of lex debug information to stdout.
224<tr bgcolor="#d0d0d0">
225<td valign="top">-p <em>path</em>
226<td valign="top">Makes the moc prepend <em>path</em>/ to
227the file name in the generated #include statement (if one is
228generated).
229<tr bgcolor="#f0f0f0">
230<td valign="top">-q <em>path</em>
231<td valign="top">Makes the moc prepend <em>path</em>/ to
232the file name of qt #include files in the generated code.
233</table></center>
234<p> You can explicitly tell the moc not to parse parts of a header
235file. It recognizes any C++ comment (//) that contains the substrings
236MOC_SKIP_BEGIN or MOC_SKIP_END. They work as you would expect and you
237can have several levels of them. The net result as seen by the moc is
238as if you had removed all lines between a MOC_SKIP_BEGIN and a
239MOC_SKIP_END.
240<p> <h2> Diagnostics
241</h2>
242<a name="4"></a><p> The moc will warn you about a number of dangerous or illegal
243constructs in the Q_OBJECT class declarations.
244<p> If you get linkage errors in the final building phase of your
245program, saying that YourClass::className() is undefined or that
246YourClass lacks a vtbl, something has been done wrong. Most often,
247you have forgotten to compile or #include the moc-generated C++ code, or
248(in the former case) include that object file in the link command.
249<p> <h2> Limitations
250</h2>
251<a name="5"></a><p> The moc does not expand #include or #define, it simply skips any
252preprocessor directives it encounters. This is regrettable, but is
253not usually a problem in practice.
254<p> The moc does not handle all of C++. The main problem is that class
255templates cannot have signals or slots. Here is an example:
256<p> <pre>
257 class SomeTemplate&lt;int&gt; : public <a href="qframe.html">QFrame</a> {
258 Q_OBJECT
259 ...
260 signals:
261 void bugInMocDetected( int );
262 };
263</pre>
264
265<p> Less importantly, the following constructs are illegal. All of them
266have alternatives which we think are usually better, so removing these
267limitations is not a high priority for us.
268<p> <h3> Multiple inheritance requires <a href="qobject.html">QObject</a> to be first
269</h3>
270<a name="5-1"></a><p> If you are using multiple inheritance, moc assumes that the <em>first</em>
271inherited class is a subclass of QObject. Also, be sure that <em>only</em>
272the first inherited class is a QObject.
273<p> <pre>
274 class SomeClass : public <a href="qobject.html">QObject</a>, public OtherClass {
275 ...
276 };
277</pre>
278
279<p> (This limitation is almost impossible to remove; since the moc does not expand
280#include or #define, it cannot find out which one of the base classes
281is a QObject.)
282<p> <h3> Function pointers cannot be arguments to signals or slots
283</h3>
284<a name="5-2"></a><p> In most cases where you would consider using function pointers as
285signal/slot arguments, we think inheritance is a better alternative.
286Here is an example of illegal syntax:
287<p> <pre>
288 class SomeClass : public <a href="qobject.html">QObject</a> {
289 Q_OBJECT
290 ...
291 public slots:
292 // illegal
293 void apply( void (*apply)(List *, void *), char * );
294 };
295</pre>
296
297<p> You can work around this restriction like this:
298<pre>
299 typedef void (*ApplyFunctionType)( List *, void * );
300
301 class SomeClass : public <a href="qobject.html">QObject</a> {
302 Q_OBJECT
303 ...
304 public slots:
305 void apply( ApplyFunctionType, char * );
306 };
307</pre>
308
309<p> It may sometimes be even better to replace the function pointer with
310inheritance and virtual functions, signals or slots.
311<p> <h3> Friend declarations cannot be placed in signals or slots sections
312</h3>
313<a name="5-3"></a><p> Sometimes it will work, but in general, friend declarations cannot be
314placed in signals or slots sections. Put them in the private,
315protected or public sections instead. Here is an example of the
316illegal syntax:
317<p> <pre>
318 class SomeClass : public <a href="qobject.html">QObject</a> {
319 Q_OBJECT
320 ...
321 signals:
322 friend class ClassTemplate&lt;char&gt;; // WRONG
323 };
324</pre>
325
326<p> <h3> Signals and slots cannot be upgraded
327</h3>
328<a name="5-4"></a><p> The C++ feature of upgrading an inherited member function to
329public status is not extended to cover signals and slots. Here is an
330illegal example:
331<p> <pre>
332 class Whatever : public <a href="qbuttongroup.html">QButtonGroup</a> {
333 ...
334 public slots:
335 <a href="qbuttongroup.html">QButtonGroup</a>::buttonPressed; // WRONG
336 ...
337 };
338</pre>
339
340<p> The QButtonGroup::buttonPressed() slot is protected.
341<p> C++ quiz: What happens if you try to upgrade a protected member
342function which is overloaded?
343<ol type=1>
344<li> All the functions are overloaded.
345<li> That is not legal C++.
346</ol>
347<p>
348<p> <h3> Type macros cannot be used for signal and slot parameters
349</h3>
350<a name="5-5"></a><p> Since the moc does not expand #define, type macros that take an argument
351will not work in signals and slots. Here is an illegal example:
352<p> <pre>
353 #ifdef ultrix
354 #define SIGNEDNESS(a) unsigned a
355 #else
356 #define SIGNEDNESS(a) a
357 #endif
358
359 class Whatever : public <a href="qobject.html">QObject</a> {
360 ...
361 signals:
362 void someSignal( SIGNEDNESS(int) );
363 ...
364 };
365</pre>
366
367<p> A #define without parameters will work as expected.
368<p> <h3> Nested classes cannot be in the signals or slots sections nor have
369signals or slots
370</h3>
371<a name="5-6"></a><p> Here's an example:
372<p> <pre>
373 class A {
374 Q_OBJECT
375 public:
376 class B {
377 public slots: // WRONG
378 void b();
379 ...
380 };
381 signals:
382 class B { // WRONG
383 void b();
384 ...
385 }:
386 };
387</pre>
388
389<p> <h3> Constructors cannot be used in signals or slots sections
390</h3>
391<a name="5-7"></a><p> It is a mystery to us why anyone would put a constructor in
392either the signals or slots sections. You can't anyway (except
393that it happens to work in some cases). Put them in private,
394protected or public sections, where they belong. Here is an example
395of the illegal syntax:
396<p> <pre>
397 class SomeClass : public <a href="qobject.html">QObject</a> {
398 Q_OBJECT
399 public slots:
400 SomeClass( <a href="qobject.html">QObject</a> *parent, const char *name )
401 : <a href="qobject.html">QObject</a>( parent, name ) { } // WRONG
402 ...
403 };
404</pre>
405
406<p> <h3> Properties need to be declared before the public section that
407contains the respective get and set functions
408</h3>
409<a name="5-8"></a><p> Declaring the first property within or after the public section that
410contains the type definition and the respective get and set functions
411does not work as expected. The moc will complain that it can neither
412find the functions nor resolve the type. Here is an example of the
413illegal syntax:
414<p> <pre>
415 class SomeClass : public <a href="qobject.html">QObject</a> {
416 Q_OBJECT
417 public:
418 ...
419 Q_PROPERTY( Priority priority READ priority WRITE setPriority ) // WRONG
420 Q_ENUMS( Priority ) // WRONG
421 enum Priority { High, Low, VeryHigh, VeryLow };
422 void setPriority( Priority );
423 Priority priority() const;
424 ...
425 };
426</pre>
427
428<p> Work around this limitation by declaring all properties at the
429beginning of the class declaration, right after Q_OBJECT:
430<p> <pre>
431 class SomeClass : public <a href="qobject.html">QObject</a> {
432 Q_OBJECT
433 Q_PROPERTY( Priority priority READ priority WRITE setPriority )
434 Q_ENUMS( Priority )
435 public:
436 ...
437 enum Priority { High, Low, VeryHigh, VeryLow };
438 void setPriority( Priority );
439 Priority priority() const;
440 ...
441 };
442</pre>
443
444<p>
445<!-- eof -->
446<p><address><hr><div align=center>
447<table width=100% cellspacing=0 border=0><tr>
448<td>Copyright &copy; 2007
449<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
450<td align=right><div align=right>Qt 3.3.8</div>
451</table></div></address></body>
452</html>
Note: See TracBrowser for help on using the repository browser.