moc(1) - f31

1moc(1)                      General Commands Manual                     moc(1)
2
3
4

NAME

6       moc - generate Qt meta object support code
7

SYNOPSIS

9       moc  [-o  file]  [-i]  [-f] [-k] [-ldbg] [-nw] [-p path] [-q path] [-v]
10       file
11

DESCRIPTION

13       This page documents the Meta Object Compiler for the Qt GUI application
14       framework.  The moc reads one or more C++ class declarations from a C++
15       header or source file and generates one C++ source file containing meta
16       object  information  for  the classes. The C++ source file generated by
17       the moc must be compiled and linked  with  the  implementation  of  the
18       class (or it can be #included into the class's source file).
19
20       If you use qmake to create your Makefiles, build rules will be included
21       that call the moc when required, so you will not need to  use  the  moc
22       directly.
23
24       In  brief,  the  meta  object  system  is  a  structure used by Qt (see
25       http://doc.trolltech.com) for component programming and run  time  type
26       information.   It adds properties and inheritance information to (some)
27       classes  and  provides  a  new  type  of  communication  between  those
28       instances of those classes, signal-slot connections.
29

OPTIONS

31       -o file
32              Write output to file rather than to stdout.
33
34       -f     Force  the  generation  of  an #include statement in the output.
35              This is the default for files whose  name  matches  the  regular
36              expression  .[hH][^.]* (i.e. the extension starts with H or h ).
37              This option is only useful if you have header files that do  not
38              follow the standard naming conventions.
39
40       -i     Do  not  generate an #include statement in the output.  This may
41              be used to run moc on a C++ file containing one  or  more  class
42              declarations.  You  should then #include the meta object code in
43              the .cpp file (see USAGE below).  If both -f and -i are present,
44              the last one wins.
45
46       -nw    Do not generate any warnings. Not recommended.
47
48       -ldbg  Write a flood of lex debug information to stdout.
49
50       -p path
51              Makes  moc  prepend  path/  to  the  file  name in the generated
52              #include statement (if one is generated).
53
54       -q path
55              Makes moc prepend path/ to the file name of qt #include files in
56              the generated code.
57
58       -v     Displays the version of moc and Qt.
59
60       You can explicitly tell the moc not to parse parts of a header file. It
61       recognizes  any  C++  comment  (//)  that   contains   the   substrings
62       MOC_SKIP_BEGIN  or  MOC_SKIP_END. They work as you would expect and you
63       can have several levels of them. The net result as seen by the  moc  is
64       as  if  you  had  removed  all  lines  between  a  MOC_SKIP_BEGIN and a
65       MOC_SKIP_END
66

USAGE

68       moc is almost always invoked by make(1), not by hand.
69
70       moc is typically used with an input file containing class  declarations
71       like this:
72
73           class YourClass : public QObject {
74               Q_OBJECT
75               Q_PROPERTY( ... )
76               Q_CLASSINFO( ... )
77
78           public:
79               YourClass( QObject * parent=0, const char * name=0 );
80               ~YourClass();
81
82           signals:
83
84           public slots:
85
86           };
87
88       Here is a useful makefile rule if you only use GNU make:
89
90           m%.cpp: %.h
91                   moc $< -o $@
92
93       If  you  want  to  write  portably, you can use individual rules of the
94       following form:
95
96           mNAME.cpp: NAME.h
97                   moc $< -o $@
98
99       You must also remember to add mNAME.cpp  to  your  SOURCES  (substitute
100       your favorite name) variable and mNAME.o to your OBJECTS variable.
101
102       (While  we  prefer  to  name our C++ source files .cpp, the moc doesn't
103       know that, so you can use .C, .cc,  .CC,  .cxx  or  even  .c++  if  you
104       prefer.)
105
106       If  you have class declarations in C++ files, we recommend that you use
107       a makefile rule like this:
108
109           NAME.o: mNAME.cpp
110
111           mNAME.cpp: NAME.cpp
112                   moc -i $< -o $@
113
114       This guarantees that make(1)  will  run  the  moc  before  it  compiles
115       NAME.cpp.  You can then put
116
117           #include "nNAME.cpp"
118
119       at the end of NAME.cpp, where all the classes declared in that file are
120       fully known.
121

DIAGNOSTICS

123       Sometimes    you    may    get    linkage    errors,    saying     that
124       YourClass::className()  is  undefined  or  that YourClass lacks a vtbl.
125       Those errors happen most often when you  forget  to  compile  the  moc-
126       generated C++ code or include that object file in the link command.
127
128       The  moc  will  warn  you  about  a  number  of  dangerous  or  illegal
129       constructs.
130

BUGS

132       The moc does not expand  #include  or  #define,  it  simply  skips  any
133       preprocessor  directives  it  encounters.  This  is regrettable, but is
134       normally not a problem in practice.
135
136       The moc does not handle all of C++.  The main  problem  is  that  class
137       templates  cannot  have  signals  or  slots.  This is an important bug.
138       Here is an example:
139
140           class SomeTemplate<int> : public QFrame {
141               Q_OBJECT
142               ....
143           signals:
144               void bugInMocDetected( int );
145           };
146
147       Less importantly, the following constructs are illegal.   All  of  them
148       have  have  alternatives which we think are usually better, so removing
149       these limitations is not a high priority for us.
150
151   Multiple inheritance requires QObject to be first.
152       If you are using multiple  inheritance,  moc  assumes  that  the  first
153       inherited  class is a subclass of QObject.  Also, be sure that only the
154       first inherited class is a QObject.
155
156           class SomeClass : public QObject, public OtherClass {
157               ...
158           };
159
160       This bug is almost impossible to fix; since the  moc  does  not  expand
161       #include  or  #define, it cannot find out which one of the base classes
162       is a QObject.
163
164   Function pointers cannot be arguments to signals or slots.
165       In most cases where you would consider that, we think inheritance is  a
166       better alternative.  Here is an example of illegal syntax:
167
168           class SomeClass : public QObject {
169               Q_OBJECT
170               ...
171           public slots:
172               // illegal
173               void apply( void (*apply)(List *, void *), void * );
174           };
175
176       You can work around this restriction like this:
177
178           typedef void (*ApplyFunctionType)( List *, void * );
179
180           class SomeClass : public QObject {
181               Q_OBJECT
182               ...
183           public slots:
184               void apply( ApplyFunctionType, char * );
185           };
186
187       It  may  sometimes  be even better to replace the function pointer with
188       inheritance and virtual functions, signals or slots.
189
190   Friend declarations cannot be placed in signals or slots sections
191       Sometimes it will work, but in general, friend declarations  cannot  be
192       placed in signals or slots sections.  Put them in the good old private,
193       protected or public sections  instead.   Here  is  an  example  of  the
194       illegal syntax:
195
196           class SomeClass : public QObject {
197               Q_OBJECT
198               ...
199           signals:
200               friend class ClassTemplate<char>; // illegal
201           };
202
203   Signals and slots cannot be upgraded
204       The  C++  feature  of  upgrading an inherited member function to public
205       status is not extended to cover signals and slots.  Here is an  illegal
206       example:
207
208           class Whatever : public QButtonGroup {
209               ...
210           public slots:
211               QButtonGroup::buttonPressed; // illegal
212               ...
213           };
214
215       The QButtonGroup::buttonPressed() slot is protected.
216
217       C++  quiz:  What  happens  if  you  try  to  upgrade a protected member
218       function which is overloaded?
219
220              - All the functions are upgraded.
221
222              - That is not legal C++.
223
224   Type macros cannot be used for signal and slot arguments
225       Since the moc does  not  expand  #define,  type  macros  that  take  an
226       argument  will  not  work  in  signals  and  slots.  Here is an illegal
227       example:
228
229           #ifdef ultrix
230           #define SIGNEDNESS(a) unsigned a
231           #else
232           #define SIGNEDNESS(a) a
233           #endif
234           class Whatever : public QObject {
235               ...
236           signals:
237               void someSignal( SIGNEDNESS(int) ); // illegal
238           };
239
240       A #define without arguments works.
241
242   Nested classes cannot be in the signals or slots sections nor have  signals
243       or slots
244       Here's an example:
245
246           class A {
247               Q_OBJECT
248           public:
249               class B {
250               public slots: // illegal
251                   void b();
252                   ...
253               };
254           signals:
255               class B {  // illegal
256                   void b();
257                ...
258               }:
259           };
260
261   Constructors cannot be used in signals or slots sections
262       It  is a mystery to us why anyone would put a constructor on either the
263       signals or slots sections.  You can't, anyway (except that  it  happens
264       to  work  in  some  cases).   Put  them in private, protected or public
265       sections, where they belong.  Here is an example of the illegal syntax:
266
267           class SomeClass : public QObject {
268               Q_OBJECT
269           public slots:
270               SomeClass( QObject *parent, const char *name )
271                   : QObject( parent, name ) {} // illegal
272               ...
273           };
274
275   Properties need to be declared before the public section that contains  the
276       respective get and set functions
277       Declaring  the  first  property within or after the public section that
278       contains the type definition and the respective get and  set  functions
279       does  not  work  as expected. The moc will complain that it can neither
280       find the functions nor resolve the type. Here  is  an  example  of  the
281       illegal syntax:
282
283           class SomeClass : public QObject {
284               Q_OBJECT
285           public:
286               ...
287               // illegal
288               Q_PROPERTY( Priority priority READ priority WRITE setPriority )
289               Q_ENUMS( Priority )
290               enum Priority { High, Low, VeryHigh, VeryLow };
291               void setPriority( Priority );
292               Priority priority() const;
293               ...
294           };
295
296       Work  around  this  limitation  by  declaring  all  properties  at  the
297       beginning of the class declaration, right after Q_OBJECT:
298
299           class SomeClass : public QObject {
300               Q_OBJECT
301               Q_PROPERTY( Priority priority READ priority WRITE setPriority )
302               Q_ENUMS( Priority )
303           public:
304               ...
305               enum Priority { High, Low, VeryHigh, VeryLow };
306               void setPriority( Priority );
307               Priority priority() const;
308               ...
309           };
310