diff options
Diffstat (limited to 'doc/man/man1/moc.1')
| -rw-r--r-- | doc/man/man1/moc.1 | 449 |
1 files changed, 449 insertions, 0 deletions
diff --git a/doc/man/man1/moc.1 b/doc/man/man1/moc.1 new file mode 100644 index 000000000..5f806ec98 --- /dev/null +++ b/doc/man/man1/moc.1 @@ -0,0 +1,449 @@ +.TH moc 1 "24 June 2001" "Trolltech AS" \" -*- nroff -*- +.\" +.\" $Id: qt/moc.1 3.3.8 edited Jan 11 14:38 $ +.\" +.\" Copyright (C) 1992-2007 Trolltech ASA. All rights reserved. +.\" +.\" This file is part of Qt and may be distributed and used according to +.\" the terms and conditions described in the LICENSE file. +.\" +.nh +.SH NAME +moc \- generate Qt meta object support code +.SH SYNOPSIS +.B moc +[-o file] [-i] [-f] [-k] [-ldbg] [-nw] [-p path] [-q path] [-v] file +.SH DESCRIPTION +This page documents the +.B Meta Object Compiler +for the Qt GUI application framework. The +.B moc +reads one or more C++ class declarations from a C++ header or source +file and generates one C++ source file containing meta object +information for the classes. The C++ source file generated by the +.B moc +must be compiled and linked with the implementation of the class (or it +can be #included into the class's source file). +.PP +If you use +.B qmake +to create your Makefiles, build rules will be included that call the +.B moc +when retquired, so you will not need to use the +.B moc +directly. +.PP +In brief, the meta object system is a structure used by Qt (see +.BR http://doc.trolltech.com ")" +for component programming and run time type information. It adds +properties and inheritance information to (some) classes and +provides a new type of communication between those instances of those +classes, signal-slot +connections. +.SH OPTIONS +.TP +.I "-o file" +Write output to +.I file +rather than to stdout. +.TP +.I -f +Force the generation of an #include statement in the output. +This is the default for files whose name matches the regular +expression .[hH][^.]* (i.e. the extension starts with +.B H +or +.B h +). This +option is only useful if you have header files that do not follow the +standard naming conventions. +.TP +.I "-i" +Do not generate an #include statement in the output. This may be used +to run +.B moc +on a C++ file containing one or more class declarations. You should then +#include the meta object code in the .cpp file (see USAGE below). If both +.I -f +and +.I -i +are present, the last one wins. +.TP +.I "-nw" +Do not generate any warnings. Not recommended. +.TP +.I "-ldbg" +Write a flood of lex debug information to stdout. +.TP +.I "-p path" +Makes +.B moc +prepend +.IR path / +to the file name in the generated #include statement (if one is generated). +.TP +.I "-q path" +Makes +.B moc +prepend +.IR path / +to the file name of qt #include files in the generated code. +.TP +.I "-v" +Displays the version of +.B moc +and Qt. +.PP +You can explicitly tell the +.B moc +not to parse parts of a header +file. It recognizes any C++ comment (//) that contains the substrings +MOC_SKIP_BEGIN or MOC_SKIP_END. They work as you would expect and you +can have several levels of them. The net result as seen by the +.B moc +is as if you had removed all lines between a MOC_SKIP_BEGIN and a +MOC_SKIP_END +.SH USAGE +.B moc +is almost always invoked by +.BR make (1), +not by hand. +.PP +.B moc +is typically used with an input file containing class declarations +like this: +.PP +.in +4 +.nf +class YourClass : public QObject { + Q_OBJECT + Q_PROPERTY( ... ) + Q_CLASSINFO( ... ) + +public: + YourClass( QObject * parent=0, const char * name=0 ); + ~YourClass(); + +signals: + +public slots: + +}; +.fi +.in -4 +.PP +Here is a useful makefile rule if you only use GNU make: +.PP +.in +4 +.nf +m%.cpp: %.h + moc $< -o $@ +.fi +.in -4 +.PP +If you want to write portably, you can use individual rules of the +following form: +.PP +.in +4 +.nf +mNAME.cpp: NAME.h + moc $< -o $@ +.fi +.in -4 +.PP +You must also remember to add +.I mNAME.cpp +to your SOURCES (substitute your favorite name) variable and +.I mNAME.o +to your OBJECTS variable. +.PP +(While we prefer to name our C++ source files .cpp, the +.B moc +doesn't know that, so you can use .C, .cc, .CC, .cxx or even .c++ if +you prefer.) +.PP +If you have class declarations in C++ files, we recommend that you use +a makefile rule like this: +.PP +.in +4 +.nf +NAME.o: mNAME.cpp + +mNAME.cpp: NAME.cpp + moc -i $< -o $@ +.fi +.in -4 +.PP +This guarantees that +.BR make (1) +will run the +.B moc +before it compiles +.IR NAME.cpp . +You can then put +.PP +.ti +4 +#include "nNAME.cpp" +.PP +at the end of +.IR NAME.cpp , +where all the classes declared in that file are fully known. +.SH DIAGNOSTICS +Sometimes you may get linkage errors, saying that +YourClass::className() is undefined or that YourClass lacks a vtbl. +Those errors happen most often when you forget to compile the +moc-generated C++ code or include that object file in the link +command. +.PP +The +.B moc +will warn you about a number of dangerous or illegal constructs. +.SH BUGS + +The +.B moc +does not expand #include or #define, it simply skips any preprocessor +directives it encounters. This is regrettable, but is normally not a +problem in practice. + +The +.B moc +does not handle all of C++. The main problem is that class templates +cannot have signals or slots. This is an important bug. Here is an +example: +.PP +.in +4 +.nf +class SomeTemplate<int> : public QFrame { + Q_OBJECT + .... +signals: + void bugInMocDetected( int ); +}; +.fi +.in -4 +.PP +Less importantly, the following constructs are illegal. All of them +have have alternatives which we think are usually better, so removing +these limitations is not a high priority for us. +.SS "Multiple inheritance retquires QObject to be first." +If you are using multiple inheritance, +.B moc +assumes that the +.B first +inherited class is a subclass of QObject. Also, be sure that +.B only +the first inherited class is a QObject. +.PP +.in +4 +.nf +class SomeClass : public QObject, public OtherClass { + ... +}; +.fi +.in -4 +.PP +This bug is almost impossible to fix; since the +.B moc +does not expand +#include or #define, it cannot find out which one of the base classes is a +QObject. +.SS "Function pointers cannot be arguments to signals or slots." +In most cases where you would consider that, we think inheritance is a +better alternative. Here is an example of illegal syntax: +.PP +.in +4 +.nf +class SomeClass : public QObject { + Q_OBJECT + ... +public slots: + // illegal + void apply( void (*apply)(List *, void *), void * ); +}; +.fi +.in -4 +.PP +You can work around this restriction like this: +.PP +.in +4 +.nf +typedef void (*ApplyFunctionType)( List *, void * ); + +class SomeClass : public QObject { + Q_OBJECT + ... +public slots: + void apply( ApplyFunctionType, char * ); +}; +.fi +.in -4 +.PP +It may sometimes be even better to replace the function pointer with +inheritance and virtual functions, signals or slots. +.SS "Friend declarations cannot be placed in signals or slots sections" +Sometimes it will work, but in general, friend declarations cannot be +placed in +.B signals +or +.B slots +sections. Put them in the good old +.BR private ", " protected +or +.B public +sections instead. Here is an example of the illegal syntax: +.PP +.in +4 +.nf +class SomeClass : public QObject { + Q_OBJECT + ... +signals: + friend class ClassTemplate<char>; // illegal +}; +.fi +.in -4 +.SS "Signals and slots cannot be upgraded" +The C++ feature of upgrading an inherited member function to +.B public +status is not extended to cover signals and slots. Here is an illegal +example: +.PP +.in +4 +.nf +class Whatever : public QButtonGroup { + ... +public slots: + QButtonGroup::buttonPressed; // illegal + ... +}; +.fi +.in -4 +.PP +The QButtonGroup::buttonPressed() slot is protected. +.PP +C++ tquiz: What happens if you try to upgrade a protected member +function which is overloaded? +.IP +- All the functions are upgraded. +.IP +- That is not legal C++. +.\" Good idea, but look in the SEE ALSO section... +.SS "Type macros cannot be used for signal and slot arguments" + +Since the +.B moc +does not expand #define, type macros that take an argument +will not work in signals and slots. Here is an illegal example: +.PP +.in +4 +.nf +#ifdef ultrix +#define SIGNEDNESS(a) unsigned a +#else +#define SIGNEDNESS(a) a +#endif +class Whatever : public QObject { + ... +signals: + void someSignal( SIGNEDNESS(int) ); // illegal +}; +.PP +A #define without arguments works. +.fi +.in -4 +.SS "Nested classes cannot be in the signals or slots sections nor have signals or slots" +Here's an example: +.PP +.in +4 +.nf +class A { + Q_OBJECT +public: + class B { + public slots: // illegal + void b(); + ... + }; +signals: + class B { // illegal + void b(); + ... + }: +}; +.fi +.in -4 +.PP +.SS "Constructors cannot be used in signals or slots sections" +It is a mystery to us why anyone would put a constructor on either the +.B signals +or +.B slots +sections. You can't, anyway (except that it happens to work in some +cases). Put them in +.BR private ", " protected +or +.B public +sections, where they belong. Here is an example of the illegal syntax: +.PP +.in +4 +.nf +class SomeClass : public QObject { + Q_OBJECT +public slots: + SomeClass( QObject *parent, const char *name ) + : QObject( parent, name ) {} // illegal + ... +}; +.fi +.in -4 +.SS "Properties need to be declared before the public section that contains the respective get and set functions" +.PP +Declaring the first property within or after the public section that +contains the type definition and the respective get and set functions +does not work as expected. The +.B moc +will complain that it can neither +find the functions nor resolve the type. Here is an example of the +illegal syntax: +.PP +.in +4 +.nf +class SomeClass : public QObject { + Q_OBJECT +public: + ... + // illegal + Q_PROPERTY( Priority priority READ priority WRITE setPriority ) + Q_ENUMS( Priority ) + enum Priority { High, Low, VeryHigh, VeryLow }; + void setPriority( Priority ); + Priority priority() const; + ... +}; +.fi +.in -4 +.PP +Work around this limitation by declaring all properties at the +beginning of the class declaration, right after Q_OBJECT: +.PP +.in +4 +.nf +class SomeClass : public QObject { + Q_OBJECT + Q_PROPERTY( Priority priority READ priority WRITE setPriority ) + Q_ENUMS( Priority ) +public: + ... + enum Priority { High, Low, VeryHigh, VeryLow }; + void setPriority( Priority ); + Priority priority() const; + ... +}; +.fi +.in -4 +.PP +.SH "SEE ALSO" +.BR http://www.trolltech.com ", " +.BR "C++ ARM, section r.11.3" " (for the answer to the tquiz), and" +.BR http://doc.trolltech.com " (for complete Qt documentation)." |