Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions |

# Using the Meta-Object Compiler (moc)

The Meta-Object Compiler, `moc`, is the program that handles Qt's C++ extensions.

The `moc` tool reads a C++ header file. If it finds one or more class declarations that contain the `Q_OBJECT` macro, it produces a C++ source file containing the meta-object code for those classes. Among other things, meta-object code is required for the signals and slots mechanism, the run-time type information, and the dynamic property system.

The C++ source file generated by `moc` must be compiled and linked with the implementation of the class.

If you use qmake to create your Makefiles, build rules will be included that call the moc when required, so you will not need to use the moc directly. For more background information on `moc`, see Why doesn't Qt use templates for signals and slots?

## Usage

`moc` is typically used with an input file containing class declarations like this:

        class MyClass : public QObject
        {
            Q_OBJECT

        public:
            MyClass(QObject *parent = 0);
            ~MyClass();

        signals:
            void mySignal();

        public slots:
            void mySlot();
        };

In addition to the signals and slots shown above, `moc` also implements object properties as in the next example. The `Q_PROPERTY()` macro declares an object property, while `Q_ENUMS()` declares a list of enumeration types within the class to be usable inside the property system. In the following example, we declare a property of the enumeration type `Priority` that is also called `priority` and has a get function `priority()` and a set function `setPriority()`.

        class MyClass : public QObject
        {
            Q_OBJECT
            Q_PROPERTY(Priority priority READ priority WRITE setPriority)
            Q_ENUMS(Priority)

        public:
            enum Priority { High, Low, VeryHigh, VeryLow };

            MyClass(QObject *parent = 0);
            ~MyClass();

            void setPriority(Priority priority);
            Priority priority() const;
        };

Properties can be modified in subclasses with the `Q_OVERRIDE()` macro. The `Q_FLAGS()` macro declares enums that are to be used as flags, i.e. OR'd together. Another macro, `Q_CLASSINFO()`, allows you to attach additional name/value pairs to the class' meta-object:

        class MyClass : public QObject
        {
            Q_OBJECT
            Q_CLASSINFO("Author", "Oscar Peterson")
            Q_CLASSINFO("Status", "Active")

        public:
            MyClass(QObject *parent = 0);
            ~MyClass();
        };

The output produced by `moc` must be compiled and linked, just like the other C++ code in your program; otherwise, the build will fail in the final link phase. If you use `qmake`, this is done automatically. Whenever `qmake` is run, it parses the project's header files and generates make rules to invoke `moc` for those files that contain a `Q_OBJECT` macro.

If the class declaration is found in the file `myclass.h`, the moc output should be put in a file called `moc_myclass.cpp`. This file should then be compiled as usual, resulting in an object file, e.g. moc_myclass.obj on Windows. This object should then be included in the list of object files that are linked together in the final building phase of the program.

If the class declaration is found in an implementation file, say, `myclass.cpp`, the `moc` output should be put in a file called `myclass.moc`. This file should be `#include`'d in the implementation file; in other words, `myclass.cpp` should contain the line

        #include "myclass.moc"

at the end. This will cause the `moc`-generated code to be compiled and linked together with the normal class definition in myclass.cpp, so it is not necessary to compile and link it separately.

This approach can be used in cases where you want the implementation file to be self-contained, or in cases where the `Q_OBJECT` class is implementation-internal and thus should not be visible in the header file.

## Writing Make Rules for Invoking `moc`

For anything but the simplest test programs, it is recommended that you automate running the `moc`. By adding some rules to your program's Makefile, make can take care of running moc when necessary and handling the moc output.

We recommend using Trolltech's free makefile generation tool, qmake, for building your makefiles. This tool generates a makefile that does all the necessary `moc` handling.

If you want to create your makefiles yourself, here are some tips on how to include moc handling.

For `Q_OBJECT` class declarations in header files, here is a useful makefile rule if you only use GNU make:

        moc_%.cpp: %.h
                moc $< -o $@

If you want to write portably, you can use individual rules with the following form:

        moc_foo.cpp: foo.h
                moc $< -o $@

You must also remember to add `moc_foo.cpp` to your `SOURCES` (substitute your favorite name) variable and moc_foo.o or moc_foo.obj to your `OBJECTS` variable.

(While we prefer to name our C++ source files `.cpp`, you can use any other extension, such as `.C`, `.cc`, `.CC`, `.cxx`, and `.c++`, if you prefer.)

For `Q_OBJECT` class declarations in implementation (`.cpp`) files, we suggest a makefile rule like this:

        foo.o: foo.moc

        foo.moc: foo.cpp
                moc -i $< -o $@

This guarantees that make will run the moc before it compiles `foo.cpp`. You can then put

        #include "foo.moc"

at the end of `foo.cpp`, where all the classes declared in that file are fully known.

## Command-Line Options

Here are the command-line options supported by the moc:

Option | Description
--- | ---
`-o<file>` | Write output to `<file>` rather than to standard output.
`-f[<file>]` | Force the generation of an `#include` statement in the output. This is the default for header files whose extension starts with `H` or `h`. This option is useful if you have header files that do not follow the standard naming conventions. The `<file>` part is optional.
`-i` | Do not generate an `#include` statement in the output. This may be used to run the moc on on a C++ file containing one or more class declarations. You should then `#include` the meta-object code in the `.cpp` file.
`-nw` | Do not generate any warnings. (Not recommended.)
`-p<path>` | Makes the moc prepend `<path>/` to the file name in the generated `#include` statement.
`-I<dir>` | Add dir to the include path for header files.
`-E` | Preprocess only; do not generate meta-object code.
`-D<macro>[=<def>]` | Define macro, with optional definition.
`-U<macro>` | Undefine macro.
`-h` | Display the usage and the list of options.
`-v` | Display `moc`'s version number.

You can explicitly tell the moc not to parse parts of a header file. `moc` defines the preprocessor symbol `Q_MOC_RUN`. Any code surrounded by

        #ifndef Q_MOC_RUN
            ...
        #endif

is skipped by the `moc`.

## Diagnostics

`moc` will warn you about a number of dangerous or illegal constructs in the `Q_OBJECT` class declarations.

If you get linkage errors in the final building phase of your program, saying that `YourClass::className()` is undefined or that `YourClass` lacks a vtable, something has been done wrong. Most often, you have forgotten to compile or `#include` the moc-generated C++ code, or (in the former case) include that object file in the link command. If you use `qmake`, try rerunning it to update your makefile. This should do the trick.

## Limitations

`moc` does not handle all of C++. The main problem is that class templates cannot have signals or slots. Here is an example:

        class SomeTemplate<int> : public QFrame
        {
            Q_OBJECT
            ...

        signals:
            void mySignal(int);
        };

Less importantly, the following constructs are illegal. All of them have alternatives which we think are usually better, so removing these limitations is not a high priority for us.

### Multiple Inheritance Requires QObject to Be First

If you are using multiple inheritance, `moc` assumes that the first inherited class is a subclass of QObject. Also, be sure that only the first inherited class is a QObject.

        // correct
        class SomeClass : public QObject, public OtherClass
        {
            ...
        };

Virtual inheritance with QObject is not supported.

### Function Pointers Cannot Be Signal or Slot Parameters

In most cases where you would consider using function pointers as signal or slot parameters, we think inheritance is a better alternative. Here is an example of illegal syntax:

        class SomeClass : public QObject
        {
            Q_OBJECT

        public slots:
            void apply(void (*apply)(List *, void *), char *); // WRONG
        };

You can work around this restriction like this:

        typedef void (*ApplyFunction)(List *, void *);

        class SomeClass : public QObject
        {
            Q_OBJECT

        public slots:
            void apply(ApplyFunction, char *);
        };

It may sometimes be even better to replace the function pointer with inheritance and virtual functions.

### Type Macros Cannot Be Used for Signal and Slot Parameters

Since `moc` doesn't expand `#define`s, type macros that take an argument will not work in signals and slots. Here is an illegal example:

        #ifdef ultrix
        #define SIGNEDNESS(a) unsigned a
        #else
        #define SIGNEDNESS(a) a
        #endif

        class Whatever : public QObject
        {
            Q_OBJECT

        signals:
            void someSignal(SIGNEDNESS(int));
        };

A macro without parameters will work.

### Nested Classes Cannot Have Signals or Slots

Here's an example of the offending construct:

        class A
        {
        public:
            class B
            {
                Q_OBJECT

            public slots:   // WRONG
                void b();
            };
        };

### Only Signals and Slots May Appear in the `signals` and `slots` Sections of a Class

`moc` will complain if you try to put other constructs in the `signals` or `slots` sections of a class than signals and slots.