QMetaType Class

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

Header: #include <QMetaType>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core

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

Public Types

ConverterFunction
MutableViewFunction
enum Type { Void, Bool, Int, UInt, Double, …, UnknownType }
enum TypeFlag { NeedsConstruction, NeedsCopyConstruction, NeedsMoveConstruction, NeedsDestruction, RelocatableType, …, IsConst }
flags TypeFlags

Public Functions

QMetaType()
QMetaType(const QtPrivate::QMetaTypeInterface *d)
QMetaType(int typeId)
qsizetype alignOf() const
QPartialOrdering compare(const void *lhs, const void *rhs) const
void *construct(void *where, const void *copy = nullptr) const
void *create(const void *copy = nullptr) const
bool debugStream(QDebug &dbg, const void *rhs)
void destroy(void *data) const
void destruct(void *data) const
bool equals(const void *lhs, const void *rhs) const
QMetaType::TypeFlags flags() const
bool hasRegisteredDataStreamOperators() const
bool hasRegisteredDebugStreamOperator() const
int id() const
const QtPrivate::QMetaTypeInterface *iface()
const QtPrivate::QMetaTypeInterface *iface() const
bool isCopyConstructible() const
bool isDefaultConstructible() const
bool isDestructible() const
bool isEqualityComparable() const
bool isMoveConstructible() const
bool isOrdered() const
bool isRegistered() const
bool isValid() const
bool load(QDataStream &stream, void *data) const
const QMetaObject *metaObject() const
const char *name() const
void registerType() const
bool save(QDataStream &stream, const void *data) const
qsizetype sizeOf() const

Static Public Members

bool canConvert(QMetaType fromType, QMetaType toType)
bool canView(QMetaType fromType, QMetaType toType)
bool convert(QMetaType fromType, const void *from, QMetaType toType, void *to)
bool equals(const void *lhs, const void *rhs, int typeId, int *result)
QMetaType fromName(QByteArrayView typeName)
QMetaType fromType()
bool hasRegisteredConverterFunction(QMetaType fromType, QMetaType toType)
bool hasRegisteredConverterFunction()
bool hasRegisteredMutableViewFunction(QMetaType fromType, QMetaType toType)
bool hasRegisteredMutableViewFunction()
bool isRegistered(int type)
bool registerConverter()
bool registerConverter(To (From::*)() const function)
bool registerConverter(To (From::*)(bool *) const function)
bool registerConverter(UnaryFunction function)
bool registerMutableView(To (From::*)() function)
bool registerMutableView(UnaryFunction function)
bool view(QMetaType fromType, void *from, QMetaType toType, void *to)
size_t qHash(QMetaType type, size_t seed = 0)
int qMetaTypeId()
int qRegisterMetaType(QMetaType meta)
int qRegisterMetaType()
int qRegisterMetaType(QMetaType meta)
bool operator!=(QMetaType a, QMetaType b)
QDebug operator<<(QDebug d, QMetaType m)
bool operator==(QMetaType a, QMetaType b)

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.

Type names can be registered with QMetaType by using either qRegisterMetaType() or registerType(). Registration is not required for most operations; it's only required for operations that attempt to resolve a type name in string form back to a QMetaType object or the type's ID. Those include some old-style signal-slot connections using QObject::connect(), reading user-types from QDataStream to QVariant, or binding to other languages and IPC mechanisms, like QML, D-Bus, JavaScript, etc.

The following code allocates and destructs an instance of MyClass by its name, which requires that MyClass have been previously registered:

QMetaType type = QMetaType::fromName("MyClass");
if (type.isValid()) {
    void *myClassPtr = type.create();
    ...
    type.destroy(myClassPtr);
    myClassPtr = nullptr;
}

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

[alias] QMetaType::ConverterFunction

[alias] QMetaType::MutableViewFunction

enum QMetaType::Type

These are the built-in types supported by QMetaType:

ConstantValueDescription
QMetaType::Void43void
QMetaType::Bool1bool
QMetaType::Int2int
QMetaType::UInt3unsigned int
QMetaType::Double6double
QMetaType::QChar7QChar
QMetaType::QString10QString
QMetaType::QByteArray12QByteArray
QMetaType::Nullptr51std::nullptr_t
QMetaType::VoidStar31void *
QMetaType::Long32long
QMetaType::LongLong4LongLong
QMetaType::Short33short
QMetaType::Char34char
QMetaType::Char1656char16_t
QMetaType::Char3257char32_t
QMetaType::ULong35unsigned long
QMetaType::ULongLong5ULongLong
QMetaType::UShort36unsigned short
QMetaType::SChar40signed char
QMetaType::UChar37unsigned char
QMetaType::Float38float
QMetaType::QObjectStar39QObject *
QMetaType::QVariant41QVariant
QMetaType::QCursor0x100aQCursor
QMetaType::QDate14QDate
QMetaType::QSize21QSize
QMetaType::QTime15QTime
QMetaType::QVariantList9QVariantList
QMetaType::QPolygon0x1007QPolygon
QMetaType::QPolygonF0x1016QPolygonF
QMetaType::QColor0x1003QColor
QMetaType::QColorSpace0x1017QColorSpace (introduced in Qt 5.15)
QMetaType::QSizeF22QSizeF
QMetaType::QRectF20QRectF
QMetaType::QLine23QLine
QMetaType::QTextLength0x100dQTextLength
QMetaType::QStringList11QStringList
QMetaType::QVariantMap8QVariantMap
QMetaType::QVariantHash28QVariantHash
QMetaType::QVariantPair58QVariantPair
QMetaType::QIcon0x1005QIcon
QMetaType::QPen0x100cQPen
QMetaType::QLineF24QLineF
QMetaType::QTextFormat0x100eQTextFormat
QMetaType::QRect19QRect
QMetaType::QPoint25QPoint
QMetaType::QUrl17QUrl
QMetaType::QRegularExpression44QRegularExpression
QMetaType::QDateTime16QDateTime
QMetaType::QPointF26QPointF
QMetaType::QPalette0x1004QPalette
QMetaType::QFont0x1000QFont
QMetaType::QBrush0x1002QBrush
QMetaType::QRegion0x1008QRegion
QMetaType::QBitArray13QBitArray
QMetaType::QImage0x1006QImage
QMetaType::QKeySequence0x100bQKeySequence
QMetaType::QSizePolicy0x2000QSizePolicy
QMetaType::QPixmap0x1001QPixmap
QMetaType::QLocale18QLocale
QMetaType::QBitmap0x1009QBitmap
QMetaType::QTransform0x1010QTransform
QMetaType::QMatrix4x40x1011QMatrix4x4
QMetaType::QVector2D0x1012QVector2D
QMetaType::QVector3D0x1013QVector3D
QMetaType::QVector4D0x1014QVector4D
QMetaType::QQuaternion0x1015QQuaternion
QMetaType::QEasingCurve29QEasingCurve
QMetaType::QJsonValue45QJsonValue
QMetaType::QJsonObject46QJsonObject
QMetaType::QJsonArray47QJsonArray
QMetaType::QJsonDocument48QJsonDocument
QMetaType::QCborValue53QCborValue
QMetaType::QCborArray54QCborArray
QMetaType::QCborMap55QCborMap
QMetaType::QCborSimpleType52QCborSimpleType
QMetaType::QModelIndex42QModelIndex
QMetaType::QPersistentModelIndex50QPersistentModelIndex (introduced in Qt 5.5)
QMetaType::QUuid30QUuid
QMetaType::QByteArrayList49QByteArrayList
QMetaType::User65536Base value for user types
QMetaType::UnknownType0This is an invalid type id. It is returned from QMetaType for types that are not registered

Additional types can be registered using qRegisterMetaType() or by calling registerType().

See also type() and typeName().

enum QMetaType::TypeFlag
flags QMetaType::TypeFlags

The enum describes attributes of a type supported by QMetaType.

ConstantValueDescription
QMetaType::NeedsConstruction0x1This type has a non-trivial default constructor. If the flag is not set, instances can be safely initialized with memset to 0.
QMetaType::NeedsCopyConstruction0x4000(since 6.5) This type has a non-trivial copy construtcor. If the flag is not set, instances can be copied with memcpy.
QMetaType::NeedsMoveConstruction0x8000(since 6.5) This type has a non-trivial move constructor. If the flag is not set, instances can be moved with memcpy.
QMetaType::NeedsDestruction0x2This type has a non-trivial destructor. If the flag is not set calls to the destructor are not necessary before discarding objects.
QMetaType::RelocatableType0x4An instance of a type having this attribute can be safely moved to a different memory location using memcpy.
QMetaType::IsEnumeration0x10This type is an enumeration.
QMetaType::IsUnsignedEnumeration0x100If the type is an Enumeration, its underlying type is unsigned.
QMetaType::PointerToQObject0x8This type is a pointer to a derived of QObject.
QMetaType::IsPointer0x800This type is a pointer to another type.
QMetaType::IsConst0x2000Indicates that values of this types are immutable; for instance because they are pointers to const objects.

Note: Before Qt 6.5, both the NeedsConstruction and NeedsDestruction flags were incorrectly set if the either copy construtor or destructor were non-trivial (that is, if the type was not trivial).

Note that the Needs flags may be set but the meta type may not have a publicly-accessible constructor of the relevant type or a publicly-accessible destructor.

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

Member Function Documentation

QMetaType::QMetaType()

Default constructs an instance of QMetaType.

QMetaType::QMetaType(const QtPrivate::QMetaTypeInterface *d)

Default constructs an instance of QMetaType.

[since 5.0] QMetaType::QMetaType(int typeId)

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

This function was introduced in Qt 5.0.

[since 6.0] qsizetype QMetaType::alignOf() const

Returns the alignment of the type in bytes (i.e. alignof(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 6.0.

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

[static] bool QMetaType::canConvert(QMetaType fromType, QMetaType toType)

Returns true if QMetaType::convert can convert from fromType to toType.

The following conversions are supported by Qt:

TypeAutomatically Cast To
QMetaType::BoolQMetaType::QChar, QMetaType::Double, QMetaType::Int, QMetaType::LongLong, QMetaType::QString, QMetaType::UInt, QMetaType::ULongLong
QMetaType::QByteArrayQMetaType::Double, QMetaType::Int, QMetaType::LongLong, QMetaType::QString, QMetaType::UInt, QMetaType::ULongLong, QMetaType::QUuid
QMetaType::QCharQMetaType::Bool, QMetaType::Int, QMetaType::UInt, QMetaType::LongLong, QMetaType::ULongLong
QMetaType::QColorQMetaType::QString
QMetaType::QDateQMetaType::QDateTime, QMetaType::QString
QMetaType::QDateTimeQMetaType::QDate, QMetaType::QString, QMetaType::QTime
QMetaType::DoubleQMetaType::Bool, QMetaType::Int, QMetaType::LongLong, QMetaType::QString, QMetaType::UInt, QMetaType::ULongLong
QMetaType::QFontQMetaType::QString
QMetaType::IntQMetaType::Bool, QMetaType::QChar, QMetaType::Double, QMetaType::LongLong, QMetaType::QString, QMetaType::UInt, QMetaType::ULongLong
QMetaType::QKeySequenceQMetaType::Int, QMetaType::QString
QMetaType::QVariantListQMetaType::QStringList (if the list's items can be converted to QStrings)
QMetaType::LongLongQMetaType::Bool, QMetaType::QByteArray, QMetaType::QChar, QMetaType::Double, QMetaType::Int, QMetaType::QString, QMetaType::UInt, QMetaType::ULongLong
QMetaType::QPointQMetaType::QPointF
QMetaType::QRectQMetaType::QRectF
QMetaType::QStringQMetaType::Bool, QMetaType::QByteArray, QMetaType::QChar, QMetaType::QColor, QMetaType::QDate, QMetaType::QDateTime, QMetaType::Double, QMetaType::QFont, QMetaType::Int, QMetaType::QKeySequence, QMetaType::LongLong, QMetaType::QStringList, QMetaType::QTime, QMetaType::UInt, QMetaType::ULongLong, QMetaType::QUuid
QMetaType::QStringListQMetaType::QVariantList, QMetaType::QString (if the list contains exactly one item)
QMetaType::QTimeQMetaType::QString
QMetaType::UIntQMetaType::Bool, QMetaType::QChar, QMetaType::Double, QMetaType::Int, QMetaType::LongLong, QMetaType::QString, QMetaType::ULongLong
QMetaType::ULongLongQMetaType::Bool, QMetaType::QChar, QMetaType::Double, QMetaType::Int, QMetaType::LongLong, QMetaType::QString, QMetaType::UInt
QMetaType::QUuidQMetaType::QByteArray, QMetaType::QString

Casting between primitive type (int, float, bool etc.) is supported.

Converting between pointers of types derived from QObject will also return true for this function if a qobject_cast from the type described by fromType to the type described by toType would succeed.

A cast from a sequential container will also return true for this function if the toType is QVariantList.

Similarly, a cast from an associative container will also return true for this function the toType is QVariantHash or QVariantMap.

See also convert(), QSequentialIterable, Q_DECLARE_SEQUENTIAL_CONTAINER_METATYPE(), QAssociativeIterable, and Q_DECLARE_ASSOCIATIVE_CONTAINER_METATYPE().

[static] bool QMetaType::canView(QMetaType fromType, QMetaType toType)

Returns true if QMetaType::view can create a mutable view of type toType on type fromType.

Converting between pointers of types derived from QObject will return true for this function if a qobject_cast from the type described by fromType to the type described by toType would succeed.

You can create a mutable view of type QSequentialIterable on any container registered with Q_DECLARE_SEQUENTIAL_CONTAINER_METATYPE().

Similarly you can create a mutable view of type QAssociativeIterable on any container registered with Q_DECLARE_ASSOCIATIVE_CONTAINER_METATYPE().

See also convert(), QSequentialIterable, Q_DECLARE_SEQUENTIAL_CONTAINER_METATYPE(), QAssociativeIterable, and Q_DECLARE_ASSOCIATIVE_CONTAINER_METATYPE().

[since 6.0] QPartialOrdering QMetaType::compare(const void *lhs, const void *rhs) const

Compares the objects at lhs and rhs for ordering.

Returns QPartialOrdering::Unordered if comparison is not supported or the values are unordered. Otherwise, returns QPartialOrdering::Less, QPartialOrdering::Equivalent or QPartialOrdering::Greater if lhs is less than, equivalent to or greater than rhs, respectively.

Both objects must be of the type described by this metatype. If either lhs or rhs is nullptr, the values are unordered. Comparison is only supported if the type's less than operator was visible to the metatype declaration.

If the type's equality operator was also visible, values will only compare equal if the equality operator says they are. In the absence of an equality operator, when neither value is less than the other, values are considered equal; if equality is also available and two such values are not equal, they are considered unordered, just as NaN (not a number) values of a floating point type lie outside its ordering.

Note: If no less than operator was visible to the metatype declaration, values are unordered even if an equality operator visible to the declaration considers them equal: compare() == 0 only agrees with equals() if the less than operator was visible.

This function was introduced in Qt 6.0.

See also equals() and isOrdered().

[since 5.0] void *QMetaType::construct(void *where, const void *copy = nullptr) 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, since 5.2] bool QMetaType::convert(QMetaType fromType, const void *from, QMetaType toType, void *to)

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

Both from and to have to be valid pointers.

This function was introduced in Qt 5.2.

[since 5.0] void *QMetaType::create(const void *copy = nullptr) 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().

[since 5.2] bool QMetaType::debugStream(QDebug &dbg, const void *rhs)

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

This function was introduced in Qt 5.2.

[since 5.0] 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().

[since 5.0] 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().

[since 6.0] bool QMetaType::equals(const void *lhs, const void *rhs) const

Compares the objects at lhs and rhs for equality.

Both objects must be of the type described by this metatype. Can only compare the two objects if a less than or equality operator for the type was visible to the metatype declaration. Otherwise, the metatype never considers values equal. When an equality operator was visible to the metatype declaration, it is authoritative; otherwise, if less than is visible, when neither value is less than the other, the two are considered equal. If values are unordered (see compare() for details) they are not equal.

Returns true if the two objects compare equal, otherwise false.

This function was introduced in Qt 6.0.

See also isEqualityComparable() and compare().

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

[since 5.0] QMetaType::TypeFlags QMetaType::flags() const

Returns flags of the type for which this QMetaType instance was constructed. To inspect specific type traits, prefer using one of the "is-" functions rather than the flags directly.

This function was introduced in Qt 5.0.

See also QMetaType::TypeFlags, QMetaType::flags(), isDefaultConstructible(), isCopyConstructible(), isMoveConstructible(), isDestructible(), isEqualityComparable(), and isOrdered().

[static] QMetaType QMetaType::fromName(QByteArrayView typeName)

Returns a QMetaType matching typeName. The returned object is not valid if the typeName is not known to QMetaType

[static, since 5.15] 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, since 5.2] bool QMetaType::hasRegisteredConverterFunction(QMetaType fromType, QMetaType toType)

Returns true, if the meta type system has a registered conversion from meta type id fromType to toType

This function was introduced in Qt 5.2.

[static, since 5.2] 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.

[since 6.1] bool QMetaType::hasRegisteredDataStreamOperators() const

Returns true, if the meta type system has registered data stream operators for this meta type.

This function was introduced in Qt 6.1.

[since 6.0] bool QMetaType::hasRegisteredDebugStreamOperator() const

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

This function was introduced in Qt 6.0.

[static, since 5.2] bool QMetaType::hasRegisteredMutableViewFunction(QMetaType fromType, QMetaType toType)

Returns true, if the meta type system has a registered mutable view on meta type id fromType of meta type id toType.

This function was introduced in Qt 5.2.

[static, since 6.0] template <typename From, typename To> bool QMetaType::hasRegisteredMutableViewFunction()

Returns true, if the meta type system has a registered mutable view on type From of type To.

This is an overloaded function.

This function was introduced in Qt 6.0.

[since 5.13] int QMetaType::id() const

Returns id type held by this QMetatype instance.

This function was introduced in Qt 5.13.

const QtPrivate::QMetaTypeInterface *QMetaType::iface()

const QtPrivate::QMetaTypeInterface *QMetaType::iface() const

[since 6.5] bool QMetaType::isCopyConstructible() const

Returns true if this type can be copy-constructed. If it can be, then construct() and create() can be used with a copy parameter that is not null.

This function was introduced in Qt 6.5.

See also flags(), isDefaultConstructible(), isMoveConstructible(), and isDestructible().

[since 6.5] bool QMetaType::isDefaultConstructible() const

Returns true if this type can be default-constructed. If it can be, then construct() and create() can be used with a copy parameter that is null.

This function was introduced in Qt 6.5.

See also flags(), isCopyConstructible(), isMoveConstructible(), and isDestructible().

[since 6.5] bool QMetaType::isDestructible() const

Returns true if this type can be destroyed. If it can be, then destroy() and destruct() can be called.

This function was introduced in Qt 6.5.

See also flags(), isDefaultConstructible(), isCopyConstructible(), and isMoveConstructible().

bool QMetaType::isEqualityComparable() const

Returns true if a less than or equality operator for the type described by this metatype was visible to the metatype declaration, otherwise false.

See also equals() and isOrdered().

[since 6.5] bool QMetaType::isMoveConstructible() const

Returns true if this type can be move-constructed. QMetaType currently does not have an API to make use of this trait.

This function was introduced in Qt 6.5.

See also flags(), isDefaultConstructible(), isCopyConstructible(), and isDestructible().

bool QMetaType::isOrdered() const

Returns true if a less than operator for the type described by this metatype was visible to the metatype declaration, otherwise false.

See also compare() and isEqualityComparable().

[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.

[since 5.0] bool QMetaType::isRegistered() const

Returns true if this QMetaType object has been registered with the Qt global metatype registry. Registration allows the type to be found by its name (using QMetaType::fromName()) or by its ID (using the constructor).

This function was introduced in Qt 5.0.

See also qRegisterMetaType() and isValid().

[since 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.

See also isRegistered().

bool QMetaType::load(QDataStream &stream, void *data) const

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

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().

[since 5.5] const QMetaObject *QMetaType::metaObject() const

Returns 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 in combination with QMetaObject::newInstance() to create QObjects of this type.

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

If the type is an enumeration, flags() contains QMetaType::IsEnumeration. In this case, 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::flags().

[since 5.15] const char *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, since 5.2] 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.

class Counter {
  int number = 0;
public:
  int value() const { return number; }
  operator int() const { return value(); }
  void increment() {++number;}
};
QMetaType::registerConverter<Counter, int>();

This function was introduced in Qt 5.2.

[static, since 5.2] template <typename From, typename To> bool QMetaType::registerConverter(To (From::*)() const 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.

struct Coordinates {
  int x;
  int y;
  int z;

  QString toString() const { return u"[x: %1; y: %2, z: %3]"_s.arg(QString::number(x),
    QString::number(y),
    QString::number(z)); }
};
QMetaType::registerConverter<Coordinates, QString>(&Coordinates::toString);

This function was introduced in Qt 5.2.

[static, since 5.2] template <typename From, typename To> bool QMetaType::registerConverter(To (From::*)(bool *) const 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.

The ok pointer can be used by the function to indicate whether the conversion succeeded.

struct BigNumber {
    long long l;

    int toInt(bool *ok = nullptr) const {
      const bool canConvertSafely = l < std::numeric_limits<int>::max();
      if (ok)
        *ok = canConvertSafely;
      return l;
    }
};
QMetaType::registerConverter<BigNumber, int>(&BigNumber::toInt);

This function was introduced in Qt 5.2.

[static, since 5.2] template <typename From, typename To, 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.

function must take an instance of type From and return an instance of To. It can be a function pointer, a lambda or a functor object.

QMetaType::registerConverter<CustomStringType, QString>([](const CustomStringType &str) {
    return QString::fromUtf8(str.data());
});

This function was introduced in Qt 5.2.

[static, since 6.0] template <typename From, typename To> bool QMetaType::registerMutableView(To (From::*)() function)

This is an overloaded function.

Registers a method function like To From::function() as mutable view of type To on type From in the meta type system. Returns true if the registration succeeded, otherwise false.

This function was introduced in Qt 6.0.

[static, since 6.0] template <typename From, typename To, typename UnaryFunction> bool QMetaType::registerMutableView(UnaryFunction function)

This is an overloaded function.

Registers a unary function object function as mutable view of type To on type From in the meta type system. Returns true if the registration succeeded, otherwise false.

This function was introduced in Qt 6.0.

[since 6.5] void QMetaType::registerType() const

Registers this QMetaType with the type registry so it can be found by name, using QMetaType::fromName().

This function was introduced in Qt 6.5.

See also qRegisterMetaType().

bool QMetaType::save(QDataStream &stream, const void *data) const

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

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().

[since 5.0] qsizetype 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(), QMetaType::sizeOf(), and QMetaType::alignOf().

[static, since 6.0] bool QMetaType::view(QMetaType fromType, void *from, QMetaType toType, void *to)

Creates a mutable view on the object at from of fromType in the preallocated space at to typed toType. Returns true if the conversion succeeded, otherwise false.

This function was introduced in Qt 6.0.

Related Non-Members

[since 6.4] size_t qHash(QMetaType type, size_t seed = 0)

Returns the hash value for the type, using seed to seed the calculation.

This function was introduced in Qt 6.4.

template <typename T> int qMetaTypeId()

Returns the meta type id of type T at compile time. If the type was not declared with Q_DECLARE_METATYPE(), compilation will fail.

Typical usage:

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

QMetaType::type() returns the same ID as qMetaTypeId(), but does a lookup at runtime based on the name of the type. QMetaType::type() is a bit slower, but compilation succeeds if a type is not registered.

See also Q_DECLARE_METATYPE() and QMetaType::type().

int qRegisterMetaType(QMetaType meta)

template <typename T> int qRegisterMetaType()

Call this function to register the type T. Returns the meta type Id.

Example:

int id = qRegisterMetaType<MyStruct>();

This function requires that T is a fully defined type at the point where the function is called. For pointer types, it also requires that the pointed to type is fully defined. Use Q_DECLARE_OPAQUE_POINTER() to be able to register pointers to forward declared types.

To use the type T in QMetaType, QVariant, or with the QObject::property() API, registration is not necessary.

To use the type T in queued signal and slot connections, qRegisterMetaType<T>() must be called before the first connection is established. That is typically done in the constructor of the class that uses T, or in the main() function.

After a type has been registered, it can be found by its name using QMetaType::fromName().

See also Q_DECLARE_METATYPE().

[since 6.5] int qRegisterMetaType(QMetaType meta)

Registers the meta type meta and returns its type Id.

This function requires that T is a fully defined type at the point where the function is called. For pointer types, it also requires that the pointed to type is fully defined. Use Q_DECLARE_OPAQUE_POINTER() to be able to register pointers to forward declared types.

To use the type T in QMetaType, QVariant, or with the QObject::property() API, registration is not necessary.

To use the type T in queued signal and slot connections, qRegisterMetaType<T>() must be called before the first connection is established. That is typically done in the constructor of the class that uses T, or in the main() function.

After a type has been registered, it can be found by its name using QMetaType::fromName().

This function was introduced in Qt 6.5.

[since 5.15] bool operator!=(QMetaType a, QMetaType b)

This is an overloaded function.

Returns true if the QMetaType a represents a different type than the QMetaType b, otherwise returns false.

This function was introduced in Qt 5.15.

[since 6.5] QDebug operator<<(QDebug d, QMetaType m)

Writes the QMetaType m to the stream d, and returns the stream.

This function was introduced in Qt 6.5.

[since 5.15] bool operator==(QMetaType a, QMetaType b)

This is an overloaded function.

Returns true if the QMetaType a represents the same type as the QMetaType b, otherwise returns false.

This function was introduced in Qt 5.15.

Macro Documentation

Q_DECLARE_ASSOCIATIVE_CONTAINER_METATYPE(Container)

This macro makes the container Container known to QMetaType as an associative container. This makes it possible to put an instance of Container<T, U> into a QVariant, if T and U are themselves known to QMetaType.

Note that all of the Qt associative containers already have built-in support, and it is not necessary to use this macro with them. The std::map container also has built-in support.

This example shows a typical use of Q_DECLARE_ASSOCIATIVE_CONTAINER_METATYPE():

#include <unordered_list>

Q_DECLARE_ASSOCIATIVE_CONTAINER_METATYPE(std::unordered_map)

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

Q_DECLARE_METATYPE(Type)

This macro makes the type Type known to QMetaType as long as it provides a public default constructor, a public copy constructor and a public destructor. It is needed to use the type Type as a custom type in QVariant.

This macro requires that Type is a fully defined type at the point where it is used. For pointer types, it also requires that the pointed to type is fully defined. Use in conjunction with Q_DECLARE_OPAQUE_POINTER() to register pointers to forward declared types.

Ideally, this macro should be placed below the declaration of the class or struct. If that is not possible, it can be put in a private header file which has to be included every time that type is used in a QVariant.

Adding a Q_DECLARE_METATYPE() makes the type known to all template based functions, including QVariant. Note that if you intend to use the type in queued signal and slot connections or in QObject's property system, you also have to call qRegisterMetaType() since the names are resolved at runtime.

This example shows a typical use case of Q_DECLARE_METATYPE():

struct MyStruct
{
    int i;
    ...
};

Q_DECLARE_METATYPE(MyStruct)

If MyStruct is in a namespace, the Q_DECLARE_METATYPE() macro has to be outside the namespace:

namespace MyNamespace
{
    ...
}

Q_DECLARE_METATYPE(MyNamespace::MyStruct)

Since MyStruct is now known to QMetaType, it can be used in QVariant:

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

...

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

Some types are registered automatically and do not need this macro:

Note: This method also registers the stream and debug operators for the type if they are visible at registration time. As this is done automatically in some places, it is strongly recommended to declare the stream operators for a type directly after the type itself. Because of the argument dependent lookup rules of C++, it is also strongly recommended to declare the operators in the same namespace as the type itself.

The stream operators should have the following signatures:

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

See also qRegisterMetaType().

[since 5.0] Q_DECLARE_OPAQUE_POINTER(PointerType)

This macro enables pointers to forward-declared types (PointerType) to be registered with QMetaType using either Q_DECLARE_METATYPE() or qRegisterMetaType().

This macro was introduced in Qt 5.0.

See also Q_DECLARE_METATYPE() and qRegisterMetaType().

Q_DECLARE_SEQUENTIAL_CONTAINER_METATYPE(Container)

This macro makes the container Container known to QMetaType as a sequential container. This makes it possible to put an instance of Container<T> into a QVariant, if T itself is known to QMetaType.

Note that all of the Qt sequential containers already have built-in support, and it is not necessary to use this macro with them. The std::vector and std::list containers also have built-in support.

This example shows a typical use of Q_DECLARE_SEQUENTIAL_CONTAINER_METATYPE():

#include <deque>

Q_DECLARE_SEQUENTIAL_CONTAINER_METATYPE(std::deque)

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

Q_DECLARE_SMART_POINTER_METATYPE(SmartPointer)

This macro makes the smart pointer SmartPointer known to QMetaType as a smart pointer. This makes it possible to put an instance of SmartPointer<T> into a QVariant, if T is a type which inherits QObject.

Note that the QWeakPointer, QSharedPointer and QPointer already have built-in support, and it is not necessary to use this macro with them.

This example shows a typical use of Q_DECLARE_SMART_POINTER_METATYPE():

#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'.
    }
}

© 2022 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.