QMetaType Class

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

List of all members, including inherited members

Public Types

Public Functions

Static Public Members

Detailed Description

QMetaType describes a C++ type at run time: its name, size, how to construct, copy, compare and destroy a value, and how to stream it. QVariant, queued connections and the property system are built on it.

Obtain one for a type with fromType(), or from an id or a name:

QMetaType t = QMetaType::fromType<QString>();
void *s = t.create();      // a new, empty QString
t.destroy(s);

QMetaType u = QMetaType::fromName("QString");
Q_ASSERT(t == u && t.id() == QMetaType::QString);

The built-in types have the same ids as in Qt. Any other type gets an id the first time it is registered, with qRegisterMetaType(), Q_DECLARE_METATYPE() or by asking for its id(); ids of types registered at run time are at least QMetaType::User.

Debug streaming (QDebug) and data streaming (QDataStream) of a type are available when its operator<< and operator>> exist and the stream classes are declared where the type is first used. Equality and ordering are detected the same way.

See also QVariant and QMetaTypeId.

Differences from Qt

Member Type Documentation

typedef QMetaType::ConverterFunction

The type of a function that converts a value. It reads the source value at its first argument and stores the result in the already constructed target at its second argument. It returns false if the conversion fails.

enum QMetaType::Type

The identifiers of the types that are built in. A type registered at run time gets an id from User upward.

enum QMetaType::TypeFlag

These flags describe a type.

typedef QMetaType::TypeFlags

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

Member Function Documentation

QMetaType::QMetaType(int typeId = UnknownType)

Constructs a QMetaType for the built-in or registered type with the id typeId. The result is invalid if typeId is unknown.

See also isValid().

[explicit] QMetaType::QMetaType(const QMetaTypeInterface *d)

Constructs a QMetaType from the interface d. This is meant for code that Nt generates.

qsizetype QMetaType::alignOf() const

Returns the alignment in bytes of a value of the type, or 0 if this object is not valid.

See also sizeOf().

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

Returns true if a value of the type fromType can be converted to toType with convert(). Whether a particular value converts can still depend on its contents.

See also convert().

bool QMetaType::compare(const void *lhs, const void *rhs, int &result) const

Compares the values at lhs and rhs. If the type is ordered, stores a negative number, 0 or a positive number in result when lhs is less than, equal to or greater than rhs, and returns true. Otherwise returns false.

See also isOrdered() and equals().

QPartialOrdering QMetaType::compare(const void *lhs, const void *rhs) const

This is an overloaded function.

Compares the values at lhs and rhs and returns the result as an ordering: QPartialOrdering::Less, Equivalent or Greater for a type that is ordered, and QPartialOrdering::Unordered for a type that has no operator<, for an invalid type and if lhs or rhs is nullptr. Two floating-point values are unordered if one of them is not a number.

This function was introduced in 6.0.

See also isOrdered(), equals() and QVariant::compare().

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

Constructs a value of the type in the memory at where, as a copy of the value at copy or, if copy is nullptr, with the default constructor. Returns where, or nullptr if the type cannot be constructed that way.

See also create() and destruct().

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

This is an overloaded function.

Constructs a value of the type with the id type at where, as a copy of copy or default-constructed.

[static] bool QMetaType::convert(QMetaType fromType, const void *from, QMetaType toType, void *to)

Converts the value at from of the type fromType to the type toType, storing the result in the constructed value at to. Returns true on success.

A converter registered with registerConverter() takes precedence. Otherwise the built-in conversions apply:

• Numbers, bool and QChar convert to each other. A floating-point number converts to an integer by rounding, and fails if it is not finite or does not fit.

• QString and QByteArray convert to numbers (an integer, or a number with a fraction that is rounded) and to bool (false for an empty string, "0" and "false").

• Numbers, bool, QChar, QDate, QTime, QDateTime, QUrl, QUuid, QVersionNumber and a QStringList of one element convert to QString; so does a QByteArray, as UTF-8.

• QString converts to QByteArray (as UTF-8), QDate, QTime, QDateTime (ISO 8601), QUrl, QUuid, QVersionNumber and QStringList (one element).

• QDateTime converts to QDate and QTime, and QDate to QDateTime.

• QStringList, QByteArrayList and QVariantList convert to each other when each element converts; QVariantMap and QVariantHash convert to each other.

• QPoint, QSize, QRect and QLine convert to and from their floating-point variants.

• QModelIndex and QPersistentModelIndex convert to each other.

• A QJsonValue converts to bool, a number, QString, QStringList, QVariantList, QVariantMap, QVariantHash, QJsonObject, QJsonArray and QJsonDocument when it holds a value of that kind, and all of these, and nullptr, convert to a QJsonValue. A QJsonObject converts to and from QVariantMap and QVariantHash, a QJsonArray to and from QVariantList and QStringList, and a QJsonDocument to and from the object or array it holds.

• An enumeration converts to and from integers; with Q_ENUM() it also converts to and from its key name as a QString.

• A sequential or associative container converts to QVariantList, QVariantMap or QVariantHash when its elements convert.

• A pointer to a QObject-derived class converts to another one if the cast succeeds.

See also canConvert(), registerConverter() and QVariant::convert().

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

Creates a value of the type on the heap, as a copy of the value at copy or, if copy is nullptr, with the default constructor. Returns nullptr if the type cannot be constructed that way. Free the value with destroy().

See also construct() and destroy().

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

This is an overloaded function.

Creates a value of the type with the id type, as a copy of copy or default-constructed.

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

Writes the value at rhs to dbg and returns true, or returns false if the type has no debug stream operator.

See also hasRegisteredDebugStreamOperator().

void QMetaType::destroy(void *data) const

Destroys the value at data, which create() returned, and frees its memory.

See also create() and destruct().

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

This is an overloaded function.

Destroys the value at data of the type with the id type and frees its memory.

void QMetaType::destruct(void *data) const

Destroys the value at data without freeing its memory.

See also destroy() and construct().

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

This is an overloaded function.

Destroys the value at where of the type with the id type.

bool QMetaType::equals(const void *lhs, const void *rhs) const

Returns true if the values at lhs and rhs are equal. A type without operator== is equal only to itself, that is, when lhs and rhs are the same address.

See also isEqualityComparable() and compare().

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

This is an overloaded function.

Returns true if the values at lhs and rhs of the type with the id typeId are equal.

TypeFlags QMetaType::flags() const

Returns the flags that describe the type.

See also QMetaType::TypeFlag.

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

Returns the QMetaType of the type called typeName. The name is normalized first, so "unsigned int" and "uint" find the same type. The result is invalid if no type is registered under the name.

See also name().

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

Returns the QMetaType of T. The qualifiers of T are ignored.

bool QMetaType::hasRegisteredDataStreamOperators() const

Returns true if the type can be written to and read from a QDataStream.

See also save() and load().

bool QMetaType::hasRegisteredDebugStreamOperator() const

Returns true if the type can be written to a QDebug stream.

See also debugStream().

int QMetaType::id() const

Returns the id of the type, registering the type first if it has no id yet. Returns 0 if this object is not valid.

See also name().

const QMetaTypeInterface * QMetaType::iface() const

Returns the interface that describes the type. This is meant for code that Nt generates.

bool QMetaType::isCopyConstructible() const

Returns true if values of the type can be copy-constructed.

See also construct().

bool QMetaType::isDefaultConstructible() const

Returns true if values of the type can be default-constructed.

See also construct().

bool QMetaType::isDestructible() const

Returns true if values of the type can be destroyed.

See also destruct().

bool QMetaType::isEqualityComparable() const

Returns true if values of the type can be compared for equality with equals().

See also equals().

bool QMetaType::isMoveConstructible() const

Returns true if values of the type can be move-constructed.

See also construct().

bool QMetaType::isOrdered() const

Returns true if values of the type can be ordered with compare().

See also compare().

bool QMetaType::isRegistered() const

Returns true if the type has been registered and has an id; otherwise returns false.

See also isValid() and id().

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

Returns true if type is the id of a built-in or registered type.

See also type() and typeName().

bool QMetaType::isValid() const

Returns true if this object describes a type; otherwise returns false.

See also isRegistered().

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

Reads a value from stream into the constructed value at data and returns true, or returns false if the type cannot be streamed.

See also save().

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

This is an overloaded function.

Reads a value of the type with the id type from stream into data.

const QMetaObject * QMetaType::metaObject() const

Returns the meta-object of the type if it is a pointer to a QObject-derived class, a class with Q_GADGET, or an enumeration declared with Q_ENUM() or Q_FLAG(); otherwise returns nullptr.

See also QMetaObject.

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

This is an overloaded function.

Returns the meta-object of the type with the id type.

const char * QMetaType::name() const

Returns the name of the type, or nullptr if this object is not valid. The name of a type registered with Q_DECLARE_METATYPE() or qRegisterMetaType() is the registered name; otherwise it is the name as the compiler spells it.

See also fromName() and id().

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

Registers the implicit conversion from From to To, so that a QVariant that holds a From converts to a To. Returns true if the registration succeeded.

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

This is an overloaded function.

Registers the member function function of From as the conversion to To.

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

This is an overloaded function.

Registers the member function function of From, which reports success through its bool pointer argument, as the conversion to To.

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

This is an overloaded function.

Registers function, a callable that takes a const From & and returns a To, as the conversion.

[static] bool QMetaType::registerConverterFunction(const ConverterFunction &function, QMetaType from, QMetaType to)

Registers function as the conversion from the type from to the type to, replacing an earlier conversion. Returns true.

See also convert() and registerConverter().

[static] int QMetaType::registerNormalizedTypedef(const ::QByteArray &normalizedTypeName, QMetaType type)

Makes normalizedTypeName another name of type, registering the type if needed, and returns the id of the type. If the name already belongs to a different type, that type's id is returned and nothing changes.

See also fromName().

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

Writes the value at data to stream and returns true, or returns false if the type cannot be streamed.

See also load().

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

This is an overloaded function.

Writes the value at data of the type with the id type to stream.

qsizetype QMetaType::sizeOf() const

Returns the size in bytes of a value of the type, or 0 if this object is not valid.

See also alignOf().

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

This is an overloaded function.

Returns the size of the type with the id type.

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

Returns the id of the type called typeName, or UnknownType if there is none.

See also fromName() and typeName().

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

This is an overloaded function.

Returns the id of the type called typeName.

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

This is an overloaded function.

Returns the flags of the type with the id type.

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

Returns the name of the type with the id type, or nullptr if there is none.

See also type() and name().

[static] void QMetaType::unregisterConverterFunction(QMetaType from, QMetaType to)

Removes the conversion registered from the type from to the type to, if any.

See also registerConverterFunction().