QQmlEngine Class

 QQmlEngine engine;
 QQmlComponent component(&engine);
 component.setData("import QtQuick 2.0\nText { text: \"Hello world!\" }", QUrl());
 QQuickItem *item = qobject_cast<QQuickItem *>(component.create());

 //add item to view, etc
 ...

Macro Documentation

QML_ADDED_IN_MINOR_VERSION(VERSION)

Declares that the enclosing type or namespace was added in the specified minor VERSION, relative to the module major version. The minor version is assumed to be in line with any revisions given by Q_REVISION() macros on methods, slots, or signals, and any REVISION tags on properties declared with Q_PROPERTY().

QML_ADDED_IN_MINOR_VERSION() only takes effect if the type or namespace is available in QML, by having a QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, or QML_INTERFACE macro.

If the QML module the type belongs to is imported with a lower version than the one determined this way, the QML type is invisible.

See also QML_ELEMENT and QML_NAMED_ELEMENT().

QML_ANONYMOUS

Declares the enclosing type to be available, but anonymous in QML. The type cannot be created or used as property type, but when passed from C++, it is recognized.

See also QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), and QML_INTERFACE.

QML_ATTACHED(ATTACHED_TYPE)

Declares that the enclosing type attaches ATTACHED_TYPE as an attached property to other types. This takes effect if the type is exposed to QML using a QML_ELEMENT or QML_NAMED_ELEMENT() macro.

See also QML_ELEMENT, QML_NAMED_ELEMENT(), qmlAttachedPropertiesObject(), and Providing Attached Properties.

QML_DECLARE_TYPE

Equivalent to Q_DECLARE_METATYPE(TYPE *) and Q_DECLARE_METATYPE(QQmlListProperty<TYPE>)

QML_DECLARE_TYPEINFO(Type, Flags)

Declares additional properties of the given Type as described by the specified Flags.

Current the only supported type info is QML_HAS_ATTACHED_PROPERTIES which declares that the Type supports attached properties. QML_DECLARE_TYPEINFO() is not necessary if Type contains the QML_ATTACHED macro.

QML_ELEMENT

Declares the enclosing type or namespace to be available in QML, using its class or namespace name as the QML element name.

For example, this makes the C++ class Slider available as a QML type named Slider.

 class Slider : public QObject
 {
     Q_OBJECT
     QML_ELEMENT
     ...
 }

You can use the build system to register the type in the type namespace com.mycompany.qmlcomponents with major version 1 by specifying the following in your project file:

 CONFIG += qmltypes
 QML_IMPORT_NAME = com.mycompany.qmlcomponents
 QML_IMPORT_MAJOR_VERSION = 1

Once registered, the type can be used in QML by importing the same type namespace and version number:

 import com.mycompany.qmlcomponents 1.0

 Slider {
     // ...
 }

You can also make namespaces tagged with Q_NAMESPACE available this way, in order to expose any enums tagged with Q_ENUM_NS they contain.

See also Choosing the Correct Integration Method Between C++ and QML, QML_NAMED_ELEMENT(), Q_REVISION(), and QML_ADDED_IN_MINOR_VERSION().

QML_EXTENDED(EXTENDED_TYPE)

Declares that the enclosing type uses EXTENDED_TYPE as an extension to provide further properties and methods in QML. This takes effect if the type is exposed to QML using a QML_ELEMENT or QML_NAMED_ELEMENT() macro.

See also QML_ELEMENT, QML_NAMED_ELEMENT(), and Registering Extension Objects.

QML_FOREIGN(FOREIGN_TYPE)

Declares that any QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, QML_INTERFACE, QML_UNCREATABLE(), QML_SINGLETON, QML_ADDED_IN_MINOR_VERSION(), QML_REMOVED_IN_MINOR_VERSION(), QML_ATTACHED(), or QML_EXTENDED() macros in the enclosing C++ type do not apply to the enclosing type but instead to FOREIGN_TYPE. The enclosing type still needs to be registered with the meta object system using a Q_GADGET or Q_OBJECT macro.

This is useful for registering types that cannot be amended to add the macros, for example because they belong to 3rdparty libraries.

NOTE: You may want to use QML_NAMED_ELEMENT() instead of QML_ELEMENT due to the fact that the element will be named like the struct it is contained in, not the foreign type. See Extending QML - Extension Objects Example for an example.

See also QML_ELEMENT and QML_NAMED_ELEMENT().

QML_INTERFACE

This macro registers the enclosing C++ type in the QML system as an interface.

Types registered as an interface in QML should also declare themselves as an interface with the meta object system. For example:

 struct FooInterface
 {
     QML_INTERFACE
 public:
     virtual ~FooInterface();
     virtual void doSomething() = 0;
 };

 Q_DECLARE_INTERFACE(FooInterface, "org.foo.FooInterface")

When registered with QML in this way, they can be used as property types:

Q_PROPERTY(FooInterface *foo READ foo WRITE setFoo)

When you assign a QObject sub-class to this property, the QML engine does the interface cast to FooInterface* automatically.

Interface types are implicitly anonymous and uncreatable in QML.

See also QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), and QML_ANONYMOUS.

QML_NAMED_ELEMENT(name)

Declares the enclosing type or namespace to be available in QML, using name as the element name. Otherwise behaves the same as QML_ELEMENT.

 class SqlEventDatabase : public QObject
 {
     Q_OBJECT
     QML_NAMED_ELEMENT(EventDatabase)

     // ...
 };

See also Choosing the Correct Integration Method Between C++ and QML and QML_ELEMENT.

QML_REMOVED_IN_MINOR_VERSION(VERSION)

Declares that the enclosing type or namespace was removed in the specified minor VERSION, relative to the module major version. This is primarily useful when replacing the implementation of a QML type. If a corresponding QML_ADDED_IN_MINOR_VERSION() is present on a different type or namespace of the same QML name, then the removed type is used when importing versions of the module lower than VERSION, and the added type is used when importing versions of the module greater or equal VERSION.

QML_REMOVED_IN_MINOR_VERSION() only takes effect if type or namespace is available in QML, by having a QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, or QML_INTERFACE macro.

See also QML_ELEMENT and QML_NAMED_ELEMENT().

QML_SINGLETON

Declares the enclosing type to be a singleton in QML. This only takes effect if the type is a Q_OBJECT and is available in QML (by having a QML_ELEMENT or QML_NAMED_ELEMENT() macro). By default, each QQmlEngine will try to create a singleton instance using the type's default constructor when the type is first accessed. If there is no default constructor the singleton is initially inaccessible. This behavior can be overridden by calling qmlRegisterSingletonType() with a specific factory function or qmlRegisterSingletonInstance() with a specific instance for the same class and the same type namespace and version.

See also QML_ELEMENT, QML_NAMED_ELEMENT(), and qmlRegisterSingletonInstance().

QML_UNAVAILABLE

This macro declares the enclosing type to be unavailable in QML. It registers an internal dummy type called QQmlTypeNotAvailable as QML_FOREIGN() type, using any further QML macros you specify.

Normally, the types exported by a module should be fixed. However, if a C++ type is not available, you should at least "reserve" the QML type name, and give the user of the unavailable type a meaningful error message.

Example:

 #ifdef NO_GAMES_ALLOWED
 struct MinehuntGame
 {
     Q_GADGET
     QML_NAMED_ELEMENT(Game)
     QML_UNAVAILABLE
     QML_UNCREATABLE("Get back to work, slacker!");
 };
 #else
 class MinehuntGame : public QObject
 {
     Q_OBJECT
     QML_NAMED_ELEMENT(Game)
     // ...
 };
 #endif

This will cause any QML which attempts to use the "Game" type to produce an error message:

 fun.qml: Get back to work, slacker!
    Game {
    ^

Using this technique, you only need a Q_GADGET struct to customize the error message, not a full-blown QObject. Without QML_UNCREATABLE(), QML_UNAVAILABLE still results in a more specific error message than the usual "is not a type" for completely unknown types.

See also QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), and QML_FOREIGN().

QML_UNCREATABLE(reason)

Declares that the enclosing type shall not be creatable from QML. This takes effect if the type is available in QML, by having a QML_ELEMENT or QML_NAMED_ELEMENT() macro. The reason will be emitted as error message if an attempt to create the type from QML is detected.

Some QML types are implicitly uncreatable, in particular types exposed with QML_ANONYMOUS or namespaces exposed with QML_ELEMENT or QML_NAMED_ELEMENT(). For such types, QML_UNCREATABLE() can be used to provide a custom error message.

See also QML_ELEMENT, QML_NAMED_ELEMENT(), and QML_ANONYMOUS.