Contents

• Public Types
• Static Public Members
• Related Non-Members
• Macros
• Detailed Description

Detailed Description

TheQMetaType class manages named types in the meta-object system.

The class is used as a helper to marshall types inQVariant 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 withQ_DECLARE_METATYPE() to make them available toQVariant and other template-based functions. CallqRegisterMetaType() to make type 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 ofMyClass:

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

If we want the stream operatorsoperator<<() andoperator>>() to work onQVariant objects that store custom types, the custom type must provideoperator<<() andoperator>>() operators.

Member Type Documentation

enum QMetaType::Type

These are the built-in types supported byQMetaType:

Additional types can be registered usingQ_DECLARE_METATYPE().

See alsotype() andtypeName().

Member Function Documentation

[static]void * QMetaType::construct(int type, constvoid * copy = 0)

Returns a copy ofcopy, assuming it is of typetype. Ifcopy is zero, creates a default type.

See alsodestroy(),isRegistered(), andType.

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

Destroys thedata, assuming it is of thetype given.

See alsoconstruct(),isRegistered(), andType.

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

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

See alsotype(),typeName(), andType.

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

Reads the object of the specifiedtype from the givenstream intodata. Returns true if the object is loaded successfully; otherwise returns false.

The type must have been registered withqRegisterMetaType() andqRegisterMetaTypeStreamOperators() beforehand.

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

See alsosave() andqRegisterMetaTypeStreamOperators().

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

Writes the object pointed to bydata with the IDtype to the givenstream. Returns true if the object is saved successfully; otherwise returns false.

The type must have been registered withqRegisterMetaType() andqRegisterMetaTypeStreamOperators() beforehand.

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

See alsoload() andqRegisterMetaTypeStreamOperators().

[static]int QMetaType::type(constchar * typeName)

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

See alsoisRegistered(),typeName(), andType.

[static]constchar * QMetaType::typeName(int type)

Returns the type name associated with the giventype, or 0 if no matching type was found. The returned pointer must not be deleted.

See alsotype(),isRegistered(), andType.

[static]void QMetaType::unregisterType(constchar * typeName)

Unregisters a user type, withtypeName.

This function was introduced in Qt 4.4.

See alsotype() andtypeName().

Related Non-Members

intqMetaTypeId()

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

Typical usage:

int id= qMetaTypeId<QString>();// id is now QMetaType::QStringid= 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.

Note: This function isthread-safe.

This function was introduced in Qt 4.1.

See alsoQ_DECLARE_METATYPE() andQMetaType::type().

intqRegisterMetaType(constchar * typeName)

Registers the type nametypeName for the typeT. Returns the internal ID used byQMetaType. Any class or struct that has a public default constructor, a public copy constructor and a public destructor can be registered.

After a type has been registered, you can create and destroy objects of that type dynamically at run-time.

This example registers the classMyClass:

qRegisterMetaType<MyClass>("MyClass");

This function is useful to register typedefs so they can be used byQMetaProperty, or in QueuedConnections

typedefQString CustomString;qRegisterMetaType<CustomString>("CustomString");

Note: This function isthread-safe.

See alsoqRegisterMetaTypeStreamOperators(),QMetaType::isRegistered(), andQ_DECLARE_METATYPE().

intqRegisterMetaType()

Call this function to register the typeT.T must be declared withQ_DECLARE_METATYPE(). Returns the meta type Id.

Example:

int id=qRegisterMetaType<MyStruct>();

To use the typeT inQVariant, usingQ_DECLARE_METATYPE() is sufficient. To use the typeT in queued signal and slot connections,qRegisterMetaType<T>() must be called before the first connection is established.

Also, to use typeT with theQObject::property() API,qRegisterMetaType<T>() must be called before it is used, typically in the constructor of the class that usesT, or in themain() function.

Note: This function isthread-safe.

This function was introduced in Qt 4.2.

See alsoQ_DECLARE_METATYPE().

voidqRegisterMetaTypeStreamOperators(constchar * typeName)

Registers the stream operators for the typeT calledtypeName.

Afterward, the type can be streamed usingQMetaType::load() andQMetaType::save(). These functions are used when streaming aQVariant.

qRegisterMetaTypeStreamOperators<MyClass>("MyClass");

The stream operators should have the following signatures:

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

Note: This function isthread-safe.

See alsoqRegisterMetaType(),QMetaType::isRegistered(), andQ_DECLARE_METATYPE().

Macro Documentation

Q_DECLARE_METATYPE( Type)

This macro makes the typeType known toQMetaType as long as it provides a public default constructor, a public copy constructor and a public destructor. It is needed to use the typeType as a custom type inQVariant.

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

Adding a Q_DECLARE_METATYPE() makes the type known to all template based functions, includingQVariant. Note that if you intend to use the type inqueued signal and slot connections or inQObject's property system, you also have to callqRegisterMetaType() 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)

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

namespace MyNamespace{...}Q_DECLARE_METATYPE(MyNamespace::MyStruct)

SinceMyStruct is now known toQMetaType, it can be used inQVariant:

MyStruct s;QVariant var;var.setValue(s);// copy s into the variant...// retrieve the valueMyStruct s2= var.value<MyStruct>();

See alsoqRegisterMetaType().