QMetaType Class

The QMetaType class manages named types in the meta-object system. More...

• List of all members, including inherited members
• Obsolete members

Note: All functions in this class are thread-safe.

Public Types

Public Functions

Static Public Members

Related Non-Members

Macros

Detailed Description

The class is used as a helper to marshall types in QVariant and in queued signals and slots connections. It associates a type name to a type so that it can be created and destructed dynamically at run-time. Declare new types with Q_DECLARE_METATYPE() to make them available to QVariant and other template-based functions. Call qRegisterMetaType() to make types available to non-template based functions, such as the queued signal and slot connections.

Any class or struct that has a public default constructor, a public copy constructor, and a public destructor can be registered.

The following code allocates and destructs an instance of MyClass:

int id = QMetaType::type("MyClass");
if (id != QMetaType::UnknownType) {
    void *myClassPtr = QMetaType::create(id);
    ...
    QMetaType::destroy(id, myClassPtr);
    myClassPtr = 0;
}

If we want the stream operators operator<<() and operator>>() to work on QVariant objects that store custom types, the custom type must provide operator<<() and operator>>() operators.

See also Q_DECLARE_METATYPE(), QVariant::setValue(), QVariant::value(), and QVariant::fromValue().

Member Type Documentation

enum QMetaType::Type

These are the built-in types supported by QMetaType:

Additional types can be registered using Q_DECLARE_METATYPE().

See also type() and typeName().

enum QMetaType::TypeFlagflags QMetaType::TypeFlags

The enum describes attributes of a type supported by QMetaType.

The TypeFlags type is a typedef for QFlags<TypeFlag>. It stores an OR combination of TypeFlag values.

Member Function Documentation

QMetaType::QMetaType(const int typeId = QMetaType::UnknownType)

Constructs a QMetaType object that contains all information about type typeId.

Note: The default parameter was added in Qt 5.15.

This function was introduced in Qt 5.0.

QMetaType::~QMetaType()

Destructs this object.

[static] bool QMetaType::compare(const void *lhs, const void *rhs, int typeId, int *result)

Compares the objects at lhs and rhs. Both objects need to be of type typeId. result is set to less than, equal to or greater than zero, if lhs is less than, equal to or greater than rhs. Returns true, if the comparison succeeded, otherwise false.

This function was introduced in Qt 5.2.

[static] void *QMetaType::construct(int type, void *where, const void *copy)

Constructs a value of the given type in the existing memory addressed by where, that is a copy of copy, and returns where. If copy is zero, the value is default constructed.

This is a low-level function for explicitly managing the memory used to store the type. Consider calling create() if you don't need this level of control (that is, use "new" rather than "placement new").

You must ensure that where points to a location that can store a value of type type, and that where is suitably aligned. The type's size can be queried by calling sizeOf().

The rule of thumb for alignment is that a type is aligned to its natural boundary, which is the smallest power of 2 that is bigger than the type, unless that alignment is larger than the maximum useful alignment for the platform. For practical purposes, alignment larger than 2 * sizeof(void*) is only necessary for special hardware instructions (e.g., aligned SSE loads and stores on x86).

This function was introduced in Qt 5.0.

See also destruct() and sizeOf().

void *QMetaType::construct(void *where, const void *copy = 0) const

Constructs a value of the type that this QMetaType instance was constructed for in the existing memory addressed by where, that is a copy of copy, and returns where. If copy is zero, the value is default constructed.

This is a low-level function for explicitly managing the memory used to store the type. Consider calling create() if you don't need this level of control (that is, use "new" rather than "placement new").

You must ensure that where points to a location where the new value can be stored and that where is suitably aligned. The type's size can be queried by calling sizeOf().

The rule of thumb for alignment is that a type is aligned to its natural boundary, which is the smallest power of 2 that is bigger than the type, unless that alignment is larger than the maximum useful alignment for the platform. For practical purposes, alignment larger than 2 * sizeof(void*) is only necessary for special hardware instructions (e.g., aligned SSE loads and stores on x86).

This function was introduced in Qt 5.0.

[static] bool QMetaType::convert(const void *from, int fromTypeId, void *to, int toTypeId)

Converts the object at from from fromTypeId to the preallocated space at to typed toTypeId. Returns true, if the conversion succeeded, otherwise false.

This function was introduced in Qt 5.2.

[static] void *QMetaType::create(int type, const void *copy = nullptr)

Returns a copy of copy, assuming it is of type type. If copy is zero, creates a default constructed instance.

See also destroy(), isRegistered(), and Type.

void *QMetaType::create(const void *copy = 0) const

Returns a copy of copy, assuming it is of the type that this QMetaType instance was created for. If copy is nullptr, creates a default constructed instance.

This function was introduced in Qt 5.0.

See also QMetaType::destroy().

[static] bool QMetaType::debugStream(QDebug &dbg, const void *rhs, int typeId)

Streams the object at rhs of type typeId to the debug stream dbg. Returns true on success, otherwise false.

This function was introduced in Qt 5.2.

[static] void QMetaType::destroy(int type, void *data)

Destroys the data, assuming it is of the type given.

See also create(), isRegistered(), and Type.

void QMetaType::destroy(void *data) const

Destroys the data, assuming it is of the type that this QMetaType instance was created for.

This function was introduced in Qt 5.0.

See also QMetaType::create().

[static] void QMetaType::destruct(int type, void *where)

Destructs the value of the given type, located at where.

Unlike destroy(), this function only invokes the type's destructor, it doesn't invoke the delete operator.

This function was introduced in Qt 5.0.

See also construct().

void QMetaType::destruct(void *data) const

Destructs the value, located at data, assuming that it is of the type for which this QMetaType instance was constructed for.

Unlike destroy(), this function only invokes the type's destructor, it doesn't invoke the delete operator.

This function was introduced in Qt 5.0.

See also QMetaType::construct().

[static] bool QMetaType::equals(const void *lhs, const void *rhs, int typeId, int *result)

Compares the objects at lhs and rhs. Both objects need to be of type typeId. result is set to zero, if lhs equals to rhs. Returns true, if the comparison succeeded, otherwise false.

This function was introduced in Qt 5.5.

QMetaType::TypeFlags QMetaType::flags() const

Returns flags of the type for which this QMetaType instance was constructed.

This function was introduced in Qt 5.0.

See also QMetaType::TypeFlags and QMetaType::typeFlags().

[static] template <typename T> QMetaType QMetaType::fromType()

Returns the QMetaType corresponding to the type in the template parameter.

This function was introduced in Qt 5.15.

[static] template <typename T> bool QMetaType::hasRegisteredComparators()

Returns true, if the meta type system has registered comparators for type T.

This function was introduced in Qt 5.2.

[static] bool QMetaType::hasRegisteredComparators(int typeId)

Returns true, if the meta type system has registered comparators for type id typeId.

This function was introduced in Qt 5.2.

[static] bool QMetaType::hasRegisteredConverterFunction(int fromTypeId, int toTypeId)

Returns true, if the meta type system has a registered conversion from meta type id fromTypeId to toTypeId

This function was introduced in Qt 5.2.

[static] template <typename From, typename To> bool QMetaType::hasRegisteredConverterFunction()

Returns true, if the meta type system has a registered conversion from type From to type To.

This is an overloaded function.

This function was introduced in Qt 5.2.

[static] template <typename T> bool QMetaType::hasRegisteredDebugStreamOperator()

Returns true, if the meta type system has a registered debug stream operator for type T.

This function was introduced in Qt 5.2.

[static] bool QMetaType::hasRegisteredDebugStreamOperator(int typeId)

Returns true, if the meta type system has a registered debug stream operator for type id typeId.

This function was introduced in Qt 5.2.

int QMetaType::id() const

Returns id type hold by this QMetatype instance.

This function was introduced in Qt 5.13.

[static] bool QMetaType::isRegistered(int type)

Returns true if the datatype with ID type is registered; otherwise returns false.

See also type(), typeName(), and Type.

bool QMetaType::isRegistered() const

Returns true if this QMetaType object contains valid information about a type, false otherwise.

This function was introduced in Qt 5.0.

bool QMetaType::isValid() const

Returns true if this QMetaType object contains valid information about a type, false otherwise.

This function was introduced in Qt 5.0.

[static] bool QMetaType::load(QDataStream &stream, int type, void *data)

Reads the object of the specified type from the given stream into data. Returns true if the object is loaded successfully; otherwise returns false.

The type must have been registered with qRegisterMetaType() and qRegisterMetaTypeStreamOperators() beforehand.

Normally, you should not need to call this function directly. Instead, use QVariant's operator>>(), which relies on load() to stream custom types.

See also save() and qRegisterMetaTypeStreamOperators().

const QMetaObject *QMetaType::metaObject() const

return a QMetaObject relative to this type.

If the type is a pointer type to a subclass of QObject, flags() contains QMetaType::PointerToQObject and this function returns the corresponding QMetaObject. This can be used to in combinaison with QMetaObject::construct to create QObject of this type.

If the type is a Q_GADGET, flags() contains QMetaType::IsGadget, and this function returns its QMetaObject. This can be used to retrieve QMetaMethod and QMetaProperty and use them on a pointer of this type. (given by QVariant::data for example)

If the type is an enumeration, flags() contains QMetaType::IsEnumeration, and this function returns the QMetaObject of the enclosing object if the enum was registered as a Q_ENUM or nullptr otherwise

This function was introduced in Qt 5.5.

See also QMetaType::metaObjectForType() and QMetaType::flags().

[static] const QMetaObject *QMetaType::metaObjectForType(int type)

returns QMetaType::metaObject for type

This function was introduced in Qt 5.0.

See also metaObject().

::QByteArray QMetaType::name() const

Returns the type name associated with this QMetaType, or a null pointer if no matching type was found. The returned pointer must not be deleted.

This function was introduced in Qt 5.15.

See also typeName().

[static] template <typename T> bool QMetaType::registerComparators()

Registers comparison operators for the user-registered type T. This requires T to have both an operator== and an operator<. Returns true if the registration succeeded, otherwise false.

This function was introduced in Qt 5.2.

[static] template <typename From, typename To> bool QMetaType::registerConverter()

Registers the possibility of an implicit conversion from type From to type To in the meta type system. Returns true if the registration succeeded, otherwise false.

This function was introduced in Qt 5.2.

[static] template <typename MemberFunction, int> bool QMetaType::registerConverter(MemberFunction function)

This is an overloaded function.

Registers a method function like To From::function() const as converter from type From to type To in the meta type system. Returns true if the registration succeeded, otherwise false.

This function was introduced in Qt 5.2.

[static] template <typename MemberFunctionOk, char> bool QMetaType::registerConverter(MemberFunctionOk function)

This is an overloaded function.

Registers a method function like To From::function(bool *ok) const as converter from type From to type To in the meta type system. Returns true if the registration succeeded, otherwise false.

This function was introduced in Qt 5.2.

[static] template <typename UnaryFunction> bool QMetaType::registerConverter(UnaryFunction function)

This is an overloaded function.

Registers a unary function object function as converter from type From to type To in the meta type system. Returns true if the registration succeeded, otherwise false.

This function was introduced in Qt 5.2.

[static] template <typename T> bool QMetaType::registerDebugStreamOperator()

Registers the debug stream operator for the user-registered type T. This requires T to have an operator<<(QDebug dbg, T). Returns true if the registration succeeded, otherwise false.

[static] template <typename T> bool QMetaType::registerEqualsComparator()

Registers equals operator for the user-registered type T. This requires T to have an operator==. Returns true if the registration succeeded, otherwise false.

This function was introduced in Qt 5.5.

[static] bool QMetaType::save(QDataStream &stream, int type, const void *data)

Writes the object pointed to by data with the ID type to the given stream. Returns true if the object is saved successfully; otherwise returns false.

The type must have been registered with qRegisterMetaType() and qRegisterMetaTypeStreamOperators() beforehand.

Normally, you should not need to call this function directly. Instead, use QVariant's operator<<(), which relies on save() to stream custom types.

See also load() and qRegisterMetaTypeStreamOperators().

[static] int QMetaType::sizeOf(int type)

Returns the size of the given type in bytes (i.e. sizeof(T), where T is the actual type identified by the type argument).

This function is typically used together with construct() to perform low-level management of the memory used by a type.

This function was introduced in Qt 5.0.

See also construct().

int QMetaType::sizeOf() const

Returns the size of the type in bytes (i.e. sizeof(T), where T is the actual type for which this QMetaType instance was constructed for).

This function is typically used together with construct() to perform low-level management of the memory used by a type.

This function was introduced in Qt 5.0.

See also QMetaType::construct() and QMetaType::sizeOf().

[static] int QMetaType::type(const char *typeName)

Returns a handle to the type called typeName, or QMetaType::UnknownType if there is no such type.

See also isRegistered(), typeName(), and Type.

[static] int QMetaType::type(const ::QByteArray &typeName)

This is an overloaded function.

Returns a handle to the type called typeName, or 0 if there is no such type.

This function was introduced in Qt 5.5.

See also isRegistered() and typeName().

[static] QMetaType::TypeFlags QMetaType::typeFlags(int type)

Returns flags of the given type.

This function was introduced in Qt 5.0.

See also QMetaType::TypeFlags.

[static] const char *QMetaType::typeName(int typeId)

Returns the type name associated with the given typeId, or a null pointer if no matching type was found. The returned pointer must not be deleted.

See also type(), isRegistered(), Type, and name().

int id = qMetaTypeId<QString>();    // id is now QMetaType::QString
id = qMetaTypeId<MyStruct>();       // compile error if MyStruct not declared

qRegisterMetaType<MyClass>("MyClass");

typedef QString CustomString;
qRegisterMetaType<CustomString>("CustomString");

int id = qRegisterMetaType<MyStruct>();

qRegisterMetaTypeStreamOperators<MyClass>("MyClass");

QDataStream &operator<<(QDataStream &out, const MyClass &myObj);
QDataStream &operator>>(QDataStream &in, MyClass &myObj);

#include <unordered_list>

Q_DECLARE_ASSOCIATIVE_CONTAINER_METATYPE(std::unordered_map)

void someFunc()
{
    std::unordered_map<int, bool> container;
    QVariant var = QVariant::fromValue(container);
    // ...
}

struct MyStruct
{
    int i;
    ...
};

Q_DECLARE_METATYPE(MyStruct)

namespace MyNamespace
{
    ...
}

Q_DECLARE_METATYPE(MyNamespace::MyStruct)

MyStruct s;
QVariant var;
var.setValue(s); // copy s into the variant

...

// retrieve the value
MyStruct s2 = var.value<MyStruct>();

#include <deque>

Q_DECLARE_SEQUENTIAL_CONTAINER_METATYPE(std::deque)

void someFunc()
{
    std::deque<QFile*> container;
    QVariant var = QVariant::fromValue(container);
    // ...
}

#include <memory>

Q_DECLARE_SMART_POINTER_METATYPE(std::shared_ptr)

void someFunc()
{
    auto smart_ptr = std::make_shared<QFile>();
    QVariant var = QVariant::fromValue(smart_ptr);
    // ...
    if (var.canConvert<QObject*>()) {
        QObject *sp = var.value<QObject*>();
        qDebug() << sp->metaObject()->className(); // Prints 'QFile'.
    }
}