Uso del generador de código « Meta-Object Compiler » (moc)
El generador de código « Meta-Object Compiler » (moc), moc, es el programa que gestiona las extensiones de C++ de Qt.
La herramienta moc lee un archivo de cabecera de C++. Si encuentra una o más declaraciones de clase que contengan la macro Q_OBJECT, genera un archivo fuente de C++ que contiene el código de metaobjetos para esas clases. Entre otras cosas, el código de metaobjetos es necesario para el mecanismo de señales y ranuras, la información de tipos en tiempo de ejecución y el sistema de propiedades dinámicas.
El archivo fuente de C++ generado por moc debe compilarse y enlazarse con la implementación de la clase.
Tanto qmake como CMake generan archivos makefile con reglas de compilación que invocarán a moc según corresponda, por lo que no será necesario utilizar moc directamente. qmake añadirá estas reglas de compilación de forma predeterminada, mientras que con CMake se puede utilizar la propiedad AUTOMOC para gestionar moc automáticamente. Para obtener más información sobre moc, consulta «¿Por qué utiliza Qt Moc para las señales y ranuras?».
Uso
moc Se suele utilizar con un archivo de entrada que contenga declaraciones de clases como esta:
class MyClass : public QObject
{
Q_OBJECT
public:
MyClass(QObject *parent = 0);
~MyClass();
signals:
void mySignal();
public slots:
void mySlot();
};Además de las señales y ranuras mostradas anteriormente, moc también implementa propiedades de objeto, como se ve en el siguiente ejemplo. La macro Q_PROPERTY() declara una propiedad de objeto, mientras que Q_ENUM() declara una lista de tipos de enumeración dentro de la clase para que puedan utilizarse dentro del sistema de propiedades.
En el siguiente ejemplo, declaramos una propiedad del tipo de enumeración Priority, que también se denomina priority y tiene una función get priority() y una función set setPriority().
class MyClass : public QObject
{
Q_OBJECT
Q_PROPERTY(Priority priority READ priority WRITE setPriority)
public:
enum Priority { High, Low, VeryHigh, VeryLow };
Q_ENUM(Priority)
MyClass(QObject *parent = 0);
~MyClass();
void setPriority(Priority priority) { m_priority = priority; }
Priority priority() const { return m_priority; }
private:
Priority m_priority;
};La macro Q_FLAG() declara enumeraciones que se van a utilizar como indicadores, es decir, que se combinan mediante la operación OR. Otra macro, Q_CLASSINFO(), permite adjuntar pares nombre/valor adicionales al metobjeto de la clase:
class MyClass : public QObject
{
Q_OBJECT
Q_CLASSINFO("Author", "Oscar Peterson")
Q_CLASSINFO("Status", "Active")
public:
MyClass(QObject *parent = 0);
~MyClass();
};El código generado por « moc » debe compilarse y enlazarse, al igual que el resto del código C++ de tu programa; de lo contrario, la compilación fallará en la fase final de enlace. Si utilizas qmake, esto se hace automáticamente. Cada vez que se ejecuta qmake, analiza los archivos de cabecera del proyecto y genera reglas de make para invocar moc para aquellos archivos que contengan la macro Q_OBJECT. Del mismo modo, al configurar AUTOMOC en ON, CMake escaneará los archivos de cabecera y de código fuente en el momento de la compilación e invocará moc según corresponda.
Si se encuentra la declaración de clase en el archivo myclass.h, la salida de moc debe guardarse en un archivo llamado moc_myclass.cpp. A continuación, este archivo debe compilarse como de costumbre, lo que dará como resultado un archivo objeto, por ejemplo, moc_myclass.obj en Windows. Este archivo objeto debe incluirse entonces en la lista de archivos objeto que se enlazan entre sí en la fase final de compilación del programa.
Escribir reglas de Make para ejecutar moc
Salvo en el caso de los programas de prueba más sencillos, se recomienda automatizar la ejecución de moc. Al añadir algunas reglas al archivo Makefile de tu programa, make se encargará de ejecutar moc cuando sea necesario y de gestionar la salida de moc.
Puedes utilizar CMake o qmake para generar archivos «makefile» que se encarguen de todas las tareas necesarias relacionadas con moc.
Si quieres crear tus propios archivos «makefile», aquí tienes algunos consejos sobre cómo incluir la gestión de moc.
Para las declaraciones de clases « Q_OBJECT » en archivos de cabecera, aquí tienes una regla útil para el archivo «makefile» si solo utilizas GNU make:
moc_%.cpp: %.h
moc $(DEFINES) $(INCPATH) $< -o $@Si quieres escribir código portable, puedes utilizar reglas individuales con el siguiente formato:
moc_foo.cpp: foo.h
moc $(DEFINES) $(INCPATH) $< -o $@También debes recordar añadir moc_foo.cpp a tu variable SOURCES (sustituye por el nombre que prefieras) y moc_foo.o o moc_foo.obj a tu variable OBJECTS.
En ambos ejemplos se da por hecho que $(DEFINES) y $(INCPATH) se expanden a las opciones de ruta de definición e inclusión que se pasan al compilador de C++. Estas son necesarias para que moc pueda preprocesar los archivos fuente.
Aunque preferimos nombrar nuestros archivos fuente de C++ como .cpp, puedes utilizar cualquier otra extensión, como .C, .cc, .CC, .cxx y .c++, si lo prefieres.
Para las declaraciones de clase « Q_OBJECT » en los archivos de implementación (.cpp), te recomendamos una regla de makefile como esta:
foo.o: foo.moc
foo.moc: foo.cpp
moc $(DEFINES) $(INCPATH) -i $< -o $@Esto garantiza que make ejecutará moc antes de compilar foo.cpp. A continuación, puedes colocar
#include "foo.moc"al final de ` foo.cpp`, donde ya se conocen por completo todas las clases declaradas en ese archivo.
Opciones de la línea de comandos
Estas son las opciones de línea de comandos que admite moc:
| Opción | Descripción |
|---|---|
-D<macro>[=<def>] | Define una macro, con definición opcional. |
-E | Solo preprocesar; no generar código de metaobjeto. |
-f[<file>] | Fuerza la generación de una instrucción « #include » en la salida. Este es el valor predeterminado para los archivos de cabecera cuya extensión comience por « H » o « h ». Esta opción resulta útil si tienes archivos de cabecera que no siguen las convenciones de nomenclatura estándar. La parte « <file> » es opcional. |
-Fdir | macOS. Añade el directorio del marco de trabajo dir al principio de la lista de directorios en los que se buscarán los archivos de cabecera. Estos directorios se intercalan con los especificados por las opciones -I y se exploran de izquierda a derecha (consulta la página de manual de gcc). Normalmente, utiliza -F /Library/Frameworks/ |
-h | Muestra el uso y la lista de opciones. |
-i | No genera una instrucción « #include » en la salida. Esto puede utilizarse para ejecutar moc en un archivo C++ que contenga una o más declaraciones de clase. A continuación, debe utilizar « #include » para generar el código de metobjeto en el archivo « .cpp ». |
-I<dir> | Añade «dir» a la ruta de inclusión de archivos de cabecera. |
-M<key=value> | Añade metadatos adicionales a los complementos. Si una clase tiene especificado « Q_PLUGIN_METADATA », el par clave-valor se añadirá a sus metadatos. Esto acabará en el objeto JSON que se resuelve para el complemento en tiempo de ejecución (accesible desde « QPluginLoader »). Este argumento se utiliza normalmente para etiquetar complementos estáticos con información resuelta por el sistema de compilación. |
-nw | No generar ninguna advertencia. (No recomendado.) |
-o<file> | Escribe la salida en <file> en lugar de en la salida estándar. |
-p<path> | Hace que el moc anteponga « <path>/ » al nombre del archivo en la instrucción « #include » generada. |
-U<macro> | Desdefine la macro. |
@<file> | Lee opciones adicionales de la línea de comandos desde <file>. Cada línea del archivo se trata como una única opción. Las líneas vacías se ignoran. Ten en cuenta que esta opción no es compatible dentro del propio archivo de opciones (es decir, un archivo de opciones no puede «incluir» otro archivo). |
-v | Muestra el número de versión de moc. |
Se puede indicar explícitamente a moc que no analice partes de un archivo de cabecera. moc define el símbolo del preprocesador Q_MOC_RUN. Cualquier código rodeado por
#ifndef Q_MOC_RUN
...
#endifes omitido por moc.
Diagnósticos
moc te advertirá de una serie de construcciones peligrosas o ilegales en las declaraciones de clase de Q_OBJECT.
Si te aparecen errores de enlace en la fase final de compilación de tu programa, indicando que « YourClass::className() » no está definido o que « YourClass » carece de una tabla de funciones virtuales (vtable), es que se ha cometido algún error. Lo más habitual es que te hayas olvidado de compilar o de ejecutar « #include » sobre el código C++ generado por moc, o (en el primer caso) de incluir ese archivo objeto en el comando de enlace. Si utilizas « qmake », prueba a volver a ejecutarlo para actualizar tu makefile. Esto debería solucionar el problema.
Sistemas de compilación
Inclusión de archivos moc de cabecera
qmake y CMake se comportan de forma diferente en lo que respecta a la inclusión de archivos moc de cabecera.
Para ilustrarlo con un ejemplo, supongamos que tienes dos cabeceras con sus correspondientes archivos fuente: a.h, a.cpp, b.h y b.cpp. Cada cabecera tiene una macro Q_OBJECT:
// 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"Con qmake, si no incluyes el archivo generado por moc (moc_a.cpp/moc_b.cpp), a.cpp, b.cpp, moc_a.cpp y moc_b.cpp se compilarán por separado. Esto puede ralentizar las compilaciones. Si incluyes los archivos generados por moc, solo será necesario compilar a.cpp y b.cpp, ya que el código generado por moc está incluido en esos archivos.
Con CMake, si no se incluyen los archivos, moc genera un único archivo adicional (llamémoslo cmake.cpp a modo de ejemplo). cmake.cpp incluiría tanto moc_a.cpp como moc_b.cpp. Con CMake sigue estando permitido incluir el archivo generado por moc, pero no es necesario.
Para obtener más información sobre la compatibilidad de CMake con moc en relación con este tema, consulta «Incluir archivos moc de cabecera en las fuentes».
Limitaciones
moc No es compatible con todo el C++. El principal problema es que las plantillas de clase no pueden tener la macro « Q_OBJECT ». He aquí un ejemplo:
class SomeTemplate<int> : public QFrame
{
Q_OBJECT
...
signals:
void mySignal(int);
};Las siguientes construcciones son ilegales. Todas ellas tienen alternativas que, en nuestra opinión, suelen ser mejores, por lo que eliminar estas limitaciones no es una prioridad para nosotros.
La herencia múltiple requiere que QObject sea la primera
Si utilizas herencia múltiple, « moc » asume que la primera clase heredada es una subclase de « QObject ». Además, asegúrate de que solo la primera clase heredada sea una « QObject ».
// correct
class SomeClass : public QObject, public OtherClass
{
...
};No se admite la herencia virtual con QObject.
Los punteros a funciones no pueden ser parámetros de señal o ranura
En la mayoría de los casos en los que se plantearía utilizar punteros a funciones como parámetros de señal o ranura, creemos que la herencia es una alternativa mejor. A continuación se muestra un ejemplo de sintaxis incorrecta:
class SomeClass : public QObject
{
Q_OBJECT
public slots:
void apply(void (*apply)(List *, void *), char *); // WRONG
};Puedes sortear esta restricción de la siguiente manera:
typedef void (*ApplyFunction)(List *, void *);
class SomeClass : public QObject
{
Q_OBJECT
public slots:
void apply(ApplyFunction, char *);
};A veces puede ser incluso mejor sustituir el puntero a función por herencia y funciones virtuales.
Las enumeraciones y los typedefs deben estar completamente calificados para los parámetros de señales y ranuras
Al comprobar las firmas de sus argumentos, QObject::connect() compara los tipos de datos de forma literal. Por lo tanto, Alignment y Qt::Alignment se tratan como dos tipos distintos. Para sortear esta limitación, asegúrate de calificar completamente los tipos de datos al declarar señales y ranuras, y al establecer conexiones. Por ejemplo:
class MyClass : public QObject
{
Q_OBJECT
enum Error {
ConnectionRefused,
RemoteHostClosed,
UnknownError
};
signals:
void stateChanged(MyClass::Error error);
};Las clases anidadas no pueden tener señales ni ranuras
A continuación se muestra un ejemplo de la construcción problemática:
class A
{
public:
class B
{
Q_OBJECT
public slots: // WRONG
void b();
};
};Los tipos de retorno de señales y ranuras no pueden ser referencias
Las señales y las ranuras pueden tener tipos de retorno, pero aquellas que devuelvan referencias se tratarán como si devolvieran `void`.
Solo las señales y las ranuras pueden aparecer en las secciones « signals » y « slots » de una clase
moc El compilador generará un error si intentas incluir en las secciones « signals » o « slots » de una clase otras construcciones que no sean señales y ranuras.
Véase también «Sistema de metaobjetos», «Señales y ranuras» y «Sistema de propiedades de Qt».
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.