QQmlEngine Class

Related Non-Members

template <typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = true)

The form of this template function is:

template<typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = true)

This returns the attached object instance that has been attached to the specified attachee by the attaching type T.

If create is true and type T is a valid attaching type, this creates and returns a new attached object instance.

Returns 0 if type T is not a valid attaching type, or if create is false and no attachment object instance has previously been created for attachee.

See also QML_ATTACHED() and Providing Attached Properties.

void qmlClearTypeRegistrations()

Clears all stored type registrations, such as those produced with qmlRegisterType().

Do not call this function while a QQmlEngine exists or behavior will be undefined. Any existing QQmlEngines must be deleted before calling this function. This function only affects the application global cache. Delete the QQmlEngine to clear all cached data relating to that engine.

QQmlContext *qmlContext(const QObject *object)

Returns the QQmlContext associated with object, if any. This is equivalent to QQmlEngine::contextForObject(object).

Note: Add #include <QtQml> to use this function.

See also contextForObject() and qmlEngine().

[since 5.9] QQmlInfo qmlDebug(const QObject *object)

Prints debug messages that include the file and line number for the specified QML object.

When QML types produce logging messages, it improves traceability if they include the QML file and line number on which the particular instance was instantiated.

To include the file and line number, an object must be passed. If the file and line number is not available for that instance (either it was not instantiated by the QML engine or location information is disabled), "unknown location" will be used instead. For example,

qmlDebug(object) << "Internal state: 42";

prints

QML MyCustomType (unknown location): Internal state: 42

This function was introduced in Qt 5.9.

See also qmlInfo and qmlWarning.

QQmlEngine *qmlEngine(const QObject *object)

Returns the QQmlEngine associated with object, if any. This is equivalent to QQmlEngine::contextForObject(object)->engine(), but more efficient.

Note: Add #include <QtQml> to use this function.

See also contextForObject() and qmlContext().

QQmlInfo qmlInfo(const QObject *object)

Prints informational messages that include the file and line number for the specified QML object.

When QML types produce logging messages, it improves traceability if they include the QML file and line number on which the particular instance was instantiated.

To include the file and line number, an object must be passed. If the file and line number is not available for that instance (either it was not instantiated by the QML engine or location information is disabled), "unknown location" will be used instead.

For example,

qmlInfo(object) << tr("component property is a write-once property");

prints

QML MyCustomType (unknown location): component property is a write-once property

Note: In versions prior to Qt 5.9, qmlInfo reported messages using a warning QtMsgType. For Qt 5.9 and above, qmlInfo uses an info QtMsgType. To send warnings, use qmlWarning.

See also qmlDebug and qmlWarning.

bool qmlProtectModule(const char *uri, int majVersion)

This function protects a module from having types registered into it. This can be used to prevent other plugins from injecting types into your module. It can also be a performance improvement, as it allows the engine to skip checking for the possibility of new types or plugins when this import is reached.

The performance benefit is primarily seen when registering application specific types from within the application instead of through a plugin. Using qmlProtectModule allows the engine to skip checking for a plugin when that uri is imported, which can be noticeable with slow file systems.

After this function is called, any attempt to register C++ types into this uri, major version combination will lead to a runtime error. Call this after you have registered all of your types with the engine.

Returns true if the module with uri as a module identifier and majVersion as a major version number was found and locked, otherwise returns false. The module must contain exported types in order to be found.

[since 5.14] template <typename T> int qmlRegisterAnonymousType(const char *uri, int versionMajor)

This template function registers the C++ type in the QML system as an anonymous type. The resulting QML type does not have a name. Therefore, instances of this type cannot be created from the QML system. You can, however, access instances of the type when they are exposed as properties of other types.

Use this function when the type will not be referenced by name, specifically for C++ types that are used on the left-hand side of a property binding. To indicate to which module the type belongs use uri and versionMajor.

For example, consider the following two classes:

class Bar : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QString baz READ baz WRITE setBaz NOTIFY bazChanged)

public:
    Bar() {}

    QString baz() const { return mBaz; }

    void setBaz(const QString &baz)
    {
        if (baz == mBaz)
            return;

        mBaz = baz;
        emit bazChanged();
    }

signals:
    void bazChanged();

private:
    QString mBaz;
};

class Foo : public QObject
{
    Q_OBJECT
    Q_PROPERTY(Bar *bar READ bar CONSTANT FINAL)

public:
    Foo() {}

    Bar *bar() { return &mBar; }

private:
    Bar mBar;
};

In QML, we assign a string to the baz property of bar:

Foo {
    bar.baz: "abc"
    Component.onCompleted: print(bar.baz)
}

For the QML engine to know that the Bar type has a baz property, we have to make Bar known:

qmlRegisterType<Foo>("App", 1, 0, "Foo");
qmlRegisterAnonymousType<Bar>("App", 1);

As the Foo type is instantiated in QML, it must be registered with the version of qmlRegisterType() that takes an element name.

Returns the QML type id.

This function was introduced in Qt 5.14.

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

template <typename T, typename E> int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

This template function registers the C++ type and its extension object in the QML system with the name qmlName in the library imported from uri having version number composed from versionMajor and versionMinor. Properties not available in the main type will be searched for in the extension object.

Returns the QML type id.

See also QML_EXTENDED(), qmlRegisterType(), and Registering Extension Objects.

template <typename T, typename E> int qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)

This template function registers the C++ type and its extension in the QML system with the name qmlName in the library imported from uri having version number composed from versionMajor and versionMinor.

While the type has a name and a type, it cannot be created. An error message with the given reason is printed if the user attempts to create an instance of this type.

This is useful where the type is only intended for providing attached properties, enum values or an abstract base class with its extension.

Returns the QML type id.

See also QML_EXTENDED(), QML_UNCREATABLE(), and qmlRegisterUncreatableType().

[since 5.9] void qmlRegisterModule(const char *uri, int versionMajor, int versionMinor)

This function registers a module in a particular uri with a version specified in versionMajor and versionMinor.

This can be used to make a certain module version available, even if no types are registered for that version. This is particularly useful for keeping the versions of related modules in sync.

This function was introduced in Qt 5.9.

template <typename T, int metaObjectRevision> int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)

This template function registers the specified revision of a C++ type in the QML system with the library imported from uri having the version number composed from versionMajor and versionMinor.

Returns the QML type id.

template<typename T, int metaObjectRevision>
int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor);

This function is typically used to register the revision of a base class to use for the specified version of the type (see Type Revisions and Versions).

[since 5.14] int qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *cppObject)

This function is used to register a singleton object cppObject, with a particular uri and typeName. Its version is a combination of versionMajor and versionMinor.

Installing a singleton type into a URI allows you to provide arbitrary functionality (methods and properties) to QML code without requiring individual instances of the type to be instantiated by the client.

Use this function to register an object of the given type T as a singleton type.

A QObject singleton type may be referenced via the type name with which it was registered; in turn this type name may be used as the target in a Connections type, or like any other type ID. However, there's one exception: a QObject singleton type property can't be aliased because the singleton type name does not identify an object within the same component as any other item.

Note: cppObject must outlive the QML engine in which it is used. Moreover, cppObject must have the same thread affinity as the engine. If you want separate singleton instances for multiple engines, you need to use qmlRegisterSingletonType. See Threads and QObjects for more information about thread safety.

Usage:

// First, define your QObject which provides the functionality.
class SingletonTypeExample : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)

public:
    explicit SingletonTypeExample(QObject* parent = nullptr) : QObject(parent) {}

    Q_INVOKABLE int doSomething()
    {
        setSomeProperty(5);
        return m_someProperty;
    }

    int someProperty() const { return m_someProperty; }
    void setSomeProperty(int val) {
        if (m_someProperty != val) {
            m_someProperty = val;
            emit somePropertyChanged(val);
        }
    }

signals:
    void somePropertyChanged(int newValue);

private:
    int m_someProperty = 0;
};

// Second, create an instance of the object

// allocate example before the engine to ensure that it outlives it
QScopedPointer<SingletonTypeExample> example(new SingletonTypeExample);
QQmlEngine engine;

// Third, register the singleton type provider with QML by calling this
// function in an initialization function.
qmlRegisterSingletonInstance("Qt.example.qobjectSingleton", 1, 0, "MyApi", example.get());

In order to use the registered singleton type in QML, you must import the URI with the corresponding version.

import QtQuick 2.0
import Qt.example.qobjectSingleton 1.0
Item {
    id: root
    property int someValue: MyApi.someProperty

    Component.onCompleted: {
        console.log(MyApi.doSomething())
    }
}

This function was introduced in Qt 5.14.

See also QML_SINGLETON and qmlRegisterSingletonType.

int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, QJSValue (*)(QQmlEngine *, QJSEngine *) callback)

This function may be used to register a singleton type provider callback in a particular uri and typeName with a version specified in versionMajor and versionMinor.

Installing a singleton type allows developers to provide arbitrary functionality (methods and properties) to a client without requiring individual instances of the type to be instantiated by the client.

A singleton type may be either a QObject or a QJSValue. This function should be used to register a singleton type provider function which returns a QJSValue as a singleton type.

NOTE: QJSValue singleton type properties will not trigger binding re-evaluation if changed.

Usage:

// First, define the singleton type provider function (callback).
static QJSValue example_qjsvalue_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
{
    Q_UNUSED(engine)

    static int seedValue = 5;
    QJSValue example = scriptEngine->newObject();
    example.setProperty("someProperty", seedValue++);
    return example;
}

// Second, register the singleton type provider with QML by calling this function in an initialization function.
qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", example_qjsvalue_singletontype_provider);

Alternatively, you can use a C++11 lambda:

qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QJSValue {
    Q_UNUSED(engine)

    static int seedValue = 5;
    QJSValue example = scriptEngine->newObject();
    example.setProperty("someProperty", seedValue++);
    return example;
});

In order to use the registered singleton type in QML, you must import the singleton type.

import QtQuick 2.0
import Qt.example.qjsvalueApi 1.0 as ExampleApi
Item {
    id: root
    property int someValue: ExampleApi.MyApi.someProperty
}

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

template <typename T> int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *(*)(QQmlEngine *, QJSEngine *) callback)

This function may be used to register a singleton type provider callback in a particular uri and typeName with a version specified in versionMajor and versionMinor.

Installing a singleton type into a uri allows developers to provide arbitrary functionality (methods and properties) to clients without requiring individual instances ot the type to be instantiated by the client.

A singleton type may be either a QObject or a QJSValue. This function should be used to register a singleton type provider function which returns a QObject of the given type T as a singleton type.

A QObject singleton type may be referenced via the type name with which it was registered, and this typename may be used as the target in a Connections type or otherwise used as any other type id would. One exception to this is that a QObject singleton type property may not be aliased.

NOTE: A QObject singleton type instance returned from a singleton type provider is owned by the QML engine unless the object has explicit QQmlEngine::CppOwnership flag set.

Usage:

// First, define your QObject which provides the functionality.
class SingletonTypeExample : public QObject
{
    Q_OBJECT
    Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)

public:
    SingletonTypeExample(QObject* parent = 0)
        : QObject(parent), m_someProperty(0)
    {
    }

    ~SingletonTypeExample() {}

    Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; }

    int someProperty() const { return m_someProperty; }
    void setSomeProperty(int val) { m_someProperty = val; emit somePropertyChanged(val); }

signals:
    void somePropertyChanged(int newValue);

private:
    int m_someProperty;
};

// Second, define the singleton type provider function (callback).
static QObject *example_qobject_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
{
    Q_UNUSED(engine)
    Q_UNUSED(scriptEngine)

    SingletonTypeExample *example = new SingletonTypeExample();
    return example;
}

// Third, register the singleton type provider with QML by calling this function in an initialization function.
qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", example_qobject_singletontype_provider);

Alternatively, you can use a C++11 lambda:

qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QObject * {
    Q_UNUSED(engine)
    Q_UNUSED(scriptEngine)

    SingletonTypeExample *example = new SingletonTypeExample();
    return example;
});

In order to use the registered singleton type in QML, you must import the singleton type.

import QtQuick 2.0
import Qt.example.qobjectSingleton 1.0
Item {
    id: root
    property int someValue: MyApi.someProperty

    Component.onCompleted: {
        someValue = MyApi.doSomething()
    }
}

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

[since 5.14] template <typename T> int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QObject *(QQmlEngine *, QJSEngine *)> callback)

This function overloads qmlRegisterSingletonType.

This function was introduced in Qt 5.14.

int qmlRegisterSingletonType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)

This function may be used to register a singleton type with the name qmlName, in the library imported from uri having the version number composed from versionMajor and versionMinor. The type is defined by the QML file located at url. The url must be an absolute URL, i.e. url.isRelative() == false.

In addition the type's QML file must have pragma Singleton statement among its import statements.

A singleton type may be referenced via the type name with which it was registered, and this typename may be used as the target in a Connections type or otherwise used as any other type id would. One exception to this is that a singleton type property may not be aliased (because the singleton type name does not identify an object within the same component as any other item).

Usage:

// First, define your QML singleton type which provides the functionality.
pragma Singleton
import QtQuick 2.0
Item {
    property int testProp1: 125
}

// Second, register the QML singleton type by calling this function in an initialization function.
qmlRegisterSingletonType(QUrl("file:///absolute/path/SingletonType.qml"), "Qt.example.qobjectSingleton", 1, 0, "RegisteredSingleton");

In order to use the registered singleton type in QML, you must import the singleton type.

import QtQuick 2.0
import Qt.example.qobjectSingleton 1.0
Item {
    id: root
    property int someValue: RegisteredSingleton.testProp1
}

It is also possible to have QML singleton types registered without using the qmlRegisterSingletonType function. That can be done by adding a pragma Singleton statement among the imports of the type's QML file. In addition the type must be defined in a qmldir file with a singleton keyword and the qmldir must be imported by the QML files using the singleton.

See also QML_SINGLETON.

template <typename T> int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

This template function registers the C++ type in the QML system with the name qmlName, in the library imported from uri having the version number composed from versionMajor and versionMinor.

Returns the QML type id.

There are two forms of this template function:

template<typename T>
int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);

template<typename T, int metaObjectRevision>
int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);

The former is the standard form which registers the type T as a new type. The latter allows a particular revision of a class to be registered in a specified version (see Type Revisions and Versions).

For example, this registers a C++ class MySliderItem as a QML type named Slider for version 1.0 of a type namespace called "com.mycompany.qmlcomponents":

qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents", 1, 0, "Slider");

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

import com.mycompany.qmlcomponents 1.0

Slider {
    // ...
}

Note that it's perfectly reasonable for a library to register types to older versions than the actual version of the library. Indeed, it is normal for the new library to allow QML written to previous versions to continue to work, even if more advanced versions of some of its types are available.

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

int qmlRegisterType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)

This function registers a type in the QML system with the name qmlName, in the library imported from uri having the version number composed from versionMajor and versionMinor. The type is defined by the QML file located at url. The url must be an absolute URL, i.e. url.isRelative() == false.

Normally QML files can be loaded as types directly from other QML files, or using a qmldir file. This function allows registration of files to types from C++ code, such as when the type mapping needs to be procedurally determined at startup.

Returns -1 if the registration was not successful.

int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)

This function registers a type in the QML system with the name qmlName, in the type namespace imported from uri having the version number composed from versionMajor and versionMinor, but any attempt to instantiate the type will produce the given error message.

Normally, the types exported by a plugin 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.

Returns the QML type id.

Example:

#ifdef NO_GAMES_ALLOWED
qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!");
#else
qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game");
#endif

This will cause any QML which imports the "MinehuntCore" type namespace and attempts to use the type to produce an error message:

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

Without this, a generic "Game is not a type" message would be given.

See also QML_UNAVAILABLE, qmlRegisterUncreatableType(), and Choosing the Correct Integration Method Between C++ and QML.

[since 5.8] int qmlRegisterUncreatableMetaObject(const QMetaObject &staticMetaObject, const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)

This function registers the staticMetaObject and its extension in the QML system with the name qmlName in the library imported from uri having version number composed from versionMajor and versionMinor.

An instance of the meta object cannot be created. An error message with the given reason is printed if the user attempts to create it.

This function is useful for registering Q_NAMESPACE namespaces.

Returns the QML type id.

For example:

namespace MyNamespace {
  Q_NAMESPACE
  enum MyEnum {
      Key1,
      Key2,
  };
  Q_ENUMS(MyEnum)
}

//...
qmlRegisterUncreatableMetaObject(MyNamespace::staticMetaObject, "io.qt", 1, 0, "MyNamespace", "Access to enums & flags only");

On the QML side, you can now use the registered enums:

Component.onCompleted: console.log(MyNamespace.Key2)

This function was introduced in Qt 5.8.

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

template <typename T> int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)

This template function registers the C++ type in the QML system with the name qmlName, in the library imported from uri having the version number composed from versionMajor and versionMinor.

While the type has a name and a type, it cannot be created, and the given error message will result if creation is attempted.

This is useful where the type is only intended for providing attached properties or enum values.

Returns the QML type id.

See also QML_UNCREATABLE(), qmlRegisterTypeNotAvailable(), and Choosing the Correct Integration Method Between C++ and QML.

[since 5.12] int qmlTypeId(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

Returns the QML type id of a type that was registered with the name qmlName in a particular uri and a version specified in versionMajor and versionMinor.

This function returns the same value as the QML type registration functions such as qmlRegisterType() and qmlRegisterSingletonType().

If qmlName, uri and versionMajor match a registered type, but the specified minor version in versionMinor is higher, then the id of the type with the closest minor version is returned.

Returns -1 if no matching type was found or one of the given parameters was invalid.

This function was introduced in Qt 5.12.

See also QML_ELEMENT, QML_NAMED_ELEMENT, QML_SINGLETON, qmlRegisterType(), and qmlRegisterSingletonType().

[since 5.9] QQmlInfo qmlWarning(const QObject *object)

Prints warning messages that include the file and line number for the specified QML object.

When QML types produce logging messages, it improves traceability if they include the QML file and line number on which the particular instance was instantiated.

To include the file and line number, an object must be passed. If the file and line number is not available for that instance (either it was not instantiated by the QML engine or location information is disabled), "unknown location" will be used instead.

For example,

qmlInfo(object) << tr("property cannot be set to 0");

prints

QML MyCustomType (unknown location): property cannot be set to 0

This function was introduced in Qt 5.9.

See also qmlDebug and qmlInfo.