Creación de tipos Qt personalizados
Descripción general
Al crear interfaces de usuario con Qt, especialmente aquellas con controles y funciones especializados, los desarrolladores a veces necesitan crear nuevos tipos de datos que puedan utilizarse junto con el conjunto de tipos de valor existentes de Qt o en su lugar.
Los tipos estándar, como « QSize », « QColor » y « QString », pueden almacenarse en objetos « QVariant », utilizarse como tipos de propiedades en clases basadas en « QObject » y emitirse en la comunicación de señales y ranuras.
En este documento, tomamos un tipo personalizado y describimos cómo integrarlo en el modelo de objetos de Qt para que pueda almacenarse de la misma forma que los tipos estándar de Qt. A continuación, mostramos cómo registrar el tipo personalizado para permitir su uso en conexiones de señales y ranuras.
Creación de un tipo personalizado
Antes de empezar, debemos asegurarnos de que el tipo personalizado que vamos a crear cumple todos los requisitos establecidos en QMetaType. En otras palabras, debe proporcionar:
- un constructor predeterminado público,
- un constructor de copia público, y
- un destructor público.
La siguiente definición de la clase ` Message ` incluye estos miembros:
class Message
{
public:
Message() = default;
~Message() = default;
Message(const Message &) = default;
Message &operator=(const Message &) = default;
Message(const QString &body, const QStringList &headers);
QStringView body() const;
QStringList headers() const;
private:
QString m_body;
QStringList m_headers;
};La clase también proporciona un constructor para uso normal y dos funciones miembro públicas que se utilizan para obtener los datos privados.
Declaración del tipo con QMetaType
La clase ` Message ` solo necesita una implementación adecuada para poder utilizarse. Sin embargo, el sistema de tipos de Qt no podrá entender cómo almacenar, recuperar y serializar instancias de esta clase sin algo de ayuda. Por ejemplo, no podremos almacenar valores de ` Message ` en ` QVariant`.
La clase de Qt responsable de los tipos personalizados es ` QMetaType`. Para que esta clase reconozca el tipo, invocamos la macro ` Q_DECLARE_METATYPE()` sobre la clase en el archivo de cabecera donde está definida:
Q_DECLARE_METATYPE(Message);Esto permite ahora que los valores de ` Message ` se almacenen en objetos ` QVariant ` y se recuperen posteriormente:
QVariant stored;
stored.setValue(message);
...
Message retrieved = qvariant_cast<Message>(stored);
qDebug() << "Retrieved:" << retrieved;
retrieved = qvariant_cast<Message>(stored);
qDebug() << "Retrieved:" << retrieved;La macro ` Q_DECLARE_METATYPE()` también permite que estos valores se utilicen como argumentos de las señales, pero solo en conexiones directas entre señales y ranuras. Para que el tipo personalizado se pueda utilizar de forma generalizada con el mecanismo de señales y ranuras, debemos realizar algunos pasos adicionales.
Creación y destrucción de objetos personalizados
Aunque la declaración de la sección anterior permite utilizar el tipo en conexiones directas de señal-ranura, no puede utilizarse para conexiones de señal-ranura en cola, como las que se establecen entre objetos en diferentes subprocesos. Esto se debe a que el sistema de metobjetos no sabe cómo gestionar la creación y destrucción de objetos del tipo personalizado en tiempo de ejecución.
Para permitir la creación de objetos en tiempo de ejecución, llama a la función plantilla ` qRegisterMetaType()` para registrarlo en el sistema de metaobjetos. Esto también hace que el tipo esté disponible para la comunicación de señales y ranuras en cola, siempre y cuando lo llames antes de establecer la primera conexión que utilice dicho tipo.
El ejemplo «Queued Custom Type» declara una clase ` Block `, que se registra en el archivo ` main.cpp `:
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
...
qRegisterMetaType<Block>();
...
return app.exec();
}Este tipo se utiliza posteriormente en una conexión de señal-ranura en el archivo window.cpp:
Window::Window(QWidget *parent)
: QWidget(parent), thread(new RenderThread(this))
{
...
connect(thread, &RenderThread::sendBlock,
this, &Window::addBlock);
...
setWindowTitle(tr("Queued Custom Type"));
}Si se utiliza un tipo en una conexión en cola sin haberlo registrado, se mostrará una advertencia en la consola; por ejemplo:
QObject::connect: Cannot queue arguments of type 'Block'
(Make sure 'Block' is registered using qRegisterMetaType().)Hacer que el tipo sea imprimible
A menudo resulta muy útil hacer que un tipo personalizado sea imprimible con fines de depuración, como en el siguiente código:
Message message(body, headers);
qDebug() << "Original:" << message;Esto se consigue creando un operador de streaming para el tipo, que suele definirse en el archivo de cabecera de dicho tipo:
La implementación para el tipo ` Message ` que se muestra aquí se esfuerza por hacer que la representación imprimible sea lo más legible posible:
QDebug operator<<(QDebug dbg, const Message &message)
{
QDebugStateSaver saver(dbg);
const QList<QStringView> pieces = message.body().split(u"\r\n", Qt::SkipEmptyParts);
if (pieces.isEmpty())
dbg.nospace() << "Message()";
else if (pieces.size() == 1)
dbg.nospace() << "Message(" << pieces.first() << ")";
else
dbg.nospace() << "Message(" << pieces.first() << " ...)";
return dbg;
}La salida enviada al flujo de depuración puede, por supuesto, ser tan sencilla o tan compleja como se desee. Ten en cuenta que el valor devuelto por esta función es el propio objeto ` QDebug `, aunque a menudo se obtiene llamando a la función miembro ` maybeSpace()` de ` QDebug `, que rellena el flujo con caracteres de espacio para hacerlo más legible.
Más información
La documentación de la macro Q_DECLARE_METATYPE() y de la función qRegisterMetaType() contiene información más detallada sobre sus usos y limitaciones.
El ejemplo «Queued Custom Type» muestra cómo implementar un tipo personalizado con las características descritas en este documento.
El documento «Técnicas de depuración» ofrece una visión general de los mecanismos de depuración mencionados anteriormente.
© 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.