Using the Meta-Object Compiler (moc)

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_ENUM() 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) { m_priority = priority; }
    Priority priority() const { return m_priority; }

private:
    Priority m_priority;
};

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's 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.

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 the qmake makefile generation tool 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 $(DEFINES) $(INCPATH) $< -o $@

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

moc_foo.cpp: foo.h
        moc $(DEFINES) $(INCPATH) $< -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.

Both examples assume that $(DEFINES) and $(INCPATH) expand to the define and include path options that are passed to the C++ compiler. These are required by moc to preprocess the source files.

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 $(DEFINES) $(INCPATH) -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.

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

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.

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.

Including header moc files▲

// a.h
class A : public QObject
{
    Q_OBJECT

    public:
        // ...
};

// a.cpp
#include "a.h"

// ...

#include "moc_a.cpp"

// b.h
class B : public QObject
{
    Q_OBJECT

    public:
        // ...
};

// b.cpp
#include "b.h"

// ...

#include "moc_b.cpp"

moc does not handle all of C++. The main problem is that class templates cannot have the Q_OBJECT macro. Here is an example:

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

signals:
    void mySignal(int);
};

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▲

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

Function Pointers Cannot Be Signal or Slot Parameters▲

class SomeClass : public QObject
{
    Q_OBJECT

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

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

class SomeClass : public QObject
{
    Q_OBJECT

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

Enums and Typedefs Must Be Fully Qualified for Signal and Slot Parameters▲

class MyClass : public QObject
{
    Q_OBJECT

    enum Error {
        ConnectionRefused,
        RemoteHostClosed,
        UnknownError
    };

signals:
    void stateChanged(MyClass::Error error);
};

Nested Classes Cannot Have Signals or Slots▲

class A
{
public:
    class B
    {
        Q_OBJECT

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

Signal/Slot return types cannot be references▲

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

See also Meta-Object System, Signals and Slots, Qt's Property System