QMetaType Class

Member Function Documentation

[explicit] QMetaType::QMetaType(int typeId)

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

[constexpr, since 6.0] QMetaType::QMetaType()

Constructs a default, invalid, QMetaType object.

This function was introduced in Qt 6.0.

[constexpr, 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:

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.

This function was introduced in Qt 6.0.

See also equals() and isOrdered().

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

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

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.

See also QMetaType::destroy().

bool QMetaType::debugStream(QDebug &dbg, const void *rhs)

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

void QMetaType::destroy(void *data) const

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

See also QMetaType::create().

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.

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

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

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 constexpr] template <typename T> QMetaType QMetaType::fromType()

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

[static] 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

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

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

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

int QMetaType::id() const

Returns id type held by this QMetatype instance.

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

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

See also qRegisterMetaType() and isValid().

bool QMetaType::isValid() const

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

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

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

See also QMetaType::flags().

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

See also typeName().

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

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

[static] 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);

[static] 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);

[static] 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. Since Qt 6.5, the function can also return an instance of std::optional<To> to be able to indicate failed conversions.

QMetaType::registerConverter<CustomStringType, QString>([](const CustomStringType &str) {
    return QString::fromUtf8(str.data());
});
QMetaType::registerConverter<QJsonValue, QPointF>(
          [](const QJsonValue &value) -> std::optional<QPointF> {
    const auto object = value.toObject();
    if (!object.contains("x") || !object.contains("y"))
        return std::nullopt;  // The conversion fails if the required properties are missing
    return QPointF{object["x"].toDouble(), object["y"].toDouble()};
});

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

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

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.