QQmlEngine Class

The QQmlEngine class provides an environment for instantiating QML components. More...

Header: #include <QQmlEngine>
CMake: find_package(Qt6 COMPONENTS Qml REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Qml)
qmake: QT += qml
Since: Qt 5.0
Inherits: QJSEngine
Inherited By:

QQmlApplicationEngine

Properties

Public Functions

QQmlEngine(QObject *parent = nullptr)
virtual ~QQmlEngine() override
void addImageProvider(const QString &providerId, QQmlImageProviderBase *provider)
void addImportPath(const QString &path)
void addPluginPath(const QString &path)
void addUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)
QUrl baseUrl() const
void clearComponentCache()
QQmlImageProviderBase *imageProvider(const QString &providerId) const
QStringList importPathList() const
bool importPlugin(const QString &filePath, const QString &uri, QList<QQmlError> *errors)
QQmlIncubationController *incubationController() const
QUrl interceptUrl(const QUrl &url, QQmlAbstractUrlInterceptor::DataType type) const
QNetworkAccessManager *networkAccessManager() const
QQmlNetworkAccessManagerFactory *networkAccessManagerFactory() const
QString offlineStorageDatabaseFilePath(const QString &databaseName) const
QString offlineStoragePath() const
bool outputWarningsToStandardError() const
QStringList pluginPathList() const
void removeImageProvider(const QString &providerId)
void removeUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)
QQmlContext *rootContext() const
void setBaseUrl(const QUrl &url)
void setImportPathList(const QStringList &paths)
void setIncubationController(QQmlIncubationController *controller)
void setNetworkAccessManagerFactory(QQmlNetworkAccessManagerFactory *factory)
void setOfflineStoragePath(const QString &dir)
void setOutputWarningsToStandardError(bool enabled)
void setPluginPathList(const QStringList &paths)
T singletonInstance(int qmlTypeId)
void trimComponentCache()
QList<QQmlAbstractUrlInterceptor *> urlInterceptors() const

Public Slots

void retranslate()

Signals

void exit(int retCode)
void quit()
void warnings(const QList<QQmlError> &warnings)

Static Public Members

QQmlContext *contextForObject(const QObject *object)
void setContextForObject(QObject *object, QQmlContext *context)

Reimplemented Protected Functions

virtual bool event(QEvent *e) override
QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = true)
void qmlClearTypeRegistrations()
QQmlContext *qmlContext(const QObject *object)
QQmlInfo qmlDebug(const QObject *object)
QQmlEngine *qmlEngine(const QObject *object)
QQmlInfo qmlInfo(const QObject *object)
bool qmlProtectModule(const char *uri, int majVersion)
int qmlRegisterAnonymousType(const char *uri, int versionMajor)
int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
int qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)
void qmlRegisterModule(const char *uri, int versionMajor, int versionMinor)
int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)
int qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *cppObject)
int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, QJSValue (*)(QQmlEngine *, QJSEngine *) callback)
int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *(*)(QQmlEngine *, QJSEngine *) callback)
int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QObject *(QQmlEngine *, QJSEngine *)> callback)
int qmlRegisterSingletonType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)
int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
int qmlRegisterType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)
int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)
int qmlRegisterUncreatableMetaObject(const QMetaObject &staticMetaObject, const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)
int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)
int qmlTypeId(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
QQmlInfo qmlWarning(const QObject *object)

Macros

Detailed Description

Each QML component is instantiated in a QQmlContext. QQmlContext's are essential for passing data to QML components. In QML, contexts are arranged hierarchically and this hierarchy is managed by the QQmlEngine.

Prior to creating any QML components, an application must have created a QQmlEngine to gain access to a QML context. The following example shows how to create a simple Text item.

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

In this case, the Text item will be created in the engine's root context.

See also QQmlComponent, QQmlContext, and QML Global Object.

Property Documentation

offlineStoragePath : QString

This property holds the directory for storing offline user data

Returns the directory where SQL and other offline storage is placed.

The SQL databases created with openDatabaseSync() are stored here.

The default is QML/OfflineStorage in the platform-standard user application data directory.

Note that the path may not currently exist on the filesystem, so callers wanting to create new files at this location should create it first - see QDir::mkpath().

Access functions:

QString offlineStoragePath() const
void setOfflineStoragePath(const QString &dir)

See also l{Qt Quick Local Storage QML Types}.

Member Function Documentation

QQmlEngine::QQmlEngine(QObject *parent = nullptr)

Create a new QQmlEngine with the given parent.

[signal, since 5.8] void QQmlEngine::exit(int retCode)

This signal is emitted when the QML loaded by the engine would like to exit from the event loop with the specified return code retCode.

This function was introduced in Qt 5.8.

See also quit().

[signal] void QQmlEngine::quit()

This signal is emitted when the QML loaded by the engine would like to quit.

See also exit().

[slot, since 5.10] void QQmlEngine::retranslate()

Refreshes all binding expressions that use strings marked for translation.

Call this function after you have installed a new translator with QCoreApplication::installTranslator, to ensure that your user-interface shows up-to-date translations.

This function was introduced in Qt 5.10.

[signal] void QQmlEngine::warnings(const QList<QQmlError> &warnings)

This signal is emitted when warnings messages are generated by QML.

[override virtual] QQmlEngine::~QQmlEngine()

Destroys the QQmlEngine.

Any QQmlContext's created on this engine will be invalidated, but not destroyed (unless they are parented to the QQmlEngine object).

See QJSEngine docs for details on cleaning up the JS engine.

void QQmlEngine::addImageProvider(const QString &providerId, QQmlImageProviderBase *provider)

Sets the provider to use for images requested via the image: url scheme, with host providerId. The QQmlEngine takes ownership of provider.

Image providers enable support for pixmap and threaded image requests. See the QQuickImageProvider documentation for details on implementing and using image providers.

All required image providers should be added to the engine before any QML sources files are loaded.

See also removeImageProvider(), QQuickImageProvider, and QQmlImageProviderBase.

void QQmlEngine::addImportPath(const QString &path)

Adds path as a directory where the engine searches for installed modules in a URL-based directory structure.

The path may be a local filesystem directory, a Qt Resource path (:/imports), a Qt Resource url (qrc:/imports) or a URL.

The path will be converted into canonical form before it is added to the import path list.

The newly added path will be first in the importPathList().

See also setImportPathList() and QML Modules.

void QQmlEngine::addPluginPath(const QString &path)

Adds path as a directory where the engine searches for native plugins for imported modules (referenced in the qmldir file).

By default, the list contains only ., i.e. the engine searches in the directory of the qmldir file itself.

The newly added path will be first in the pluginPathList().

See also setPluginPathList().

void QQmlEngine::addUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)

Adds a urlInterceptor to be used when resolving URLs in QML. This also applies to URLs used for loading script files and QML types. The URL interceptors should not be modifed while the engine is loading files, or URL selection may be inconsistent. Multiple URL interceptors, when given, will be called in the order they were added for each URL.

QQmlEngine does not take ownership of the interceptor and won't delete it.

QUrl QQmlEngine::baseUrl() const

Return the base URL for this engine. The base URL is only used to resolve components when a relative URL is passed to the QQmlComponent constructor.

If a base URL has not been explicitly set, this method returns the application's current working directory.

See also setBaseUrl().

void QQmlEngine::clearComponentCache()

Clears the engine's internal component cache.

This function causes the property metadata of all components previously loaded by the engine to be destroyed. All previously loaded components and the property bindings for all extant objects created from those components will cease to function.

This function returns the engine to a state where it does not contain any loaded component data. This may be useful in order to reload a smaller subset of the previous component set, or to load a new version of a previously loaded component.

Once the component cache has been cleared, components must be loaded before any new objects can be created.

Note: Any existing objects created from QML components retain their types, even if you clear the component cache. This includes singleton objects. If you create more objects from the same QML code after clearing the cache, the new objects will be of different types than the old ones. Assigning such a new object to a property of its declared type belonging to an object created before clearing the cache won't work.

As a general rule of thumb, make sure that no objects created from QML components are alive when you clear the component cache.

See also trimComponentCache().

[static] QQmlContext *QQmlEngine::contextForObject(const QObject *object)

Returns the QQmlContext for the object, or 0 if no context has been set.

When the QQmlEngine instantiates a QObject, the context is set automatically.

See also setContextForObject(), qmlContext(), and qmlEngine().

[override virtual protected] bool QQmlEngine::event(QEvent *e)

Reimplements: QObject::event(QEvent *e).

QQmlImageProviderBase *QQmlEngine::imageProvider(const QString &providerId) const

Returns the image provider set for providerId if found; otherwise returns nullptr.

See also QQuickImageProvider.

QStringList QQmlEngine::importPathList() const

Returns the list of directories where the engine searches for installed modules in a URL-based directory structure.

For example, if /opt/MyApp/lib/imports is in the path, then QML that imports com.mycompany.Feature will cause the QQmlEngine to look in /opt/MyApp/lib/imports/com/mycompany/Feature/ for the components provided by that module. A qmldir file is required for defining the type version mapping and possibly QML extensions plugins.

By default, the list contains the directory of the application executable, paths specified in the QML_IMPORT_PATH environment variable, and the builtin QmlImportsPath from QLibraryInfo.

See also addImportPath() and setImportPathList().

bool QQmlEngine::importPlugin(const QString &filePath, const QString &uri, QList<QQmlError> *errors)

Imports the plugin named filePath with the uri provided. Returns true if the plugin was successfully imported; otherwise returns false.

On failure and if non-null, the errors list will have any errors which occurred prepended to it.

The plugin has to be a Qt plugin which implements the QQmlEngineExtensionPlugin interface.

QQmlIncubationController *QQmlEngine::incubationController() const

Returns the currently set incubation controller, or 0 if no controller has been set.

See also setIncubationController().

QUrl QQmlEngine::interceptUrl(const QUrl &url, QQmlAbstractUrlInterceptor::DataType type) const

Run the current URL interceptors on the given url of the given type and return the result.

QNetworkAccessManager *QQmlEngine::networkAccessManager() const

Returns a common QNetworkAccessManager which can be used by any QML type instantiated by this engine.

If a QQmlNetworkAccessManagerFactory has been set and a QNetworkAccessManager has not yet been created, the QQmlNetworkAccessManagerFactory will be used to create the QNetworkAccessManager; otherwise the returned QNetworkAccessManager will have no proxy or cache set.

See also setNetworkAccessManagerFactory().

QQmlNetworkAccessManagerFactory *QQmlEngine::networkAccessManagerFactory() const

Returns the current QQmlNetworkAccessManagerFactory.

See also setNetworkAccessManagerFactory().

[since 5.9] QString QQmlEngine::offlineStorageDatabaseFilePath(const QString &databaseName) const

Returns the file path where a Local Storage database with the identifier databaseName is (or would be) located.

This function was introduced in Qt 5.9.

See also LocalStorage.openDatabaseSync().

bool QQmlEngine::outputWarningsToStandardError() const

Returns true if warning messages will be output to stderr in addition to being emitted by the warnings() signal, otherwise false.

The default value is true.

See also setOutputWarningsToStandardError().

QStringList QQmlEngine::pluginPathList() const

Returns the list of directories where the engine searches for native plugins for imported modules (referenced in the qmldir file).

By default, the list contains only ., i.e. the engine searches in the directory of the qmldir file itself.

See also addPluginPath() and setPluginPathList().

void QQmlEngine::removeImageProvider(const QString &providerId)

Removes the image provider for providerId.

See also addImageProvider() and QQuickImageProvider.

void QQmlEngine::removeUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)

Remove a urlInterceptor that was previously added using addUrlInterceptor. The URL interceptors should not be modifed while the engine is loading files, or URL selection may be inconsistent.

This does not delete the interceptor, but merely removes it from the engine. You can re-use it on the same or a different engine afterwards.

QQmlContext *QQmlEngine::rootContext() const

Returns the engine's root context.

The root context is automatically created by the QQmlEngine. Data that should be available to all QML component instances instantiated by the engine should be put in the root context.

Additional data that should only be available to a subset of component instances should be added to sub-contexts parented to the root context.

void QQmlEngine::setBaseUrl(const QUrl &url)

Set the base URL for this engine to url.

See also baseUrl().

[static] void QQmlEngine::setContextForObject(QObject *object, QQmlContext *context)

Sets the QQmlContext for the object to context. If the object already has a context, a warning is output, but the context is not changed.

When the QQmlEngine instantiates a QObject, the context is set automatically.

See also contextForObject().

void QQmlEngine::setImportPathList(const QStringList &paths)

Sets paths as the list of directories where the engine searches for installed modules in a URL-based directory structure.

By default, the list contains the directory of the application executable, paths specified in the QML_IMPORT_PATH environment variable, and the builtin QmlImportsPath from QLibraryInfo.

See also importPathList() and addImportPath().

void QQmlEngine::setIncubationController(QQmlIncubationController *controller)

Sets the engine's incubation controller. The engine can only have one active controller and it does not take ownership of it.

See also incubationController().

void QQmlEngine::setNetworkAccessManagerFactory(QQmlNetworkAccessManagerFactory *factory)

Sets the factory to use for creating QNetworkAccessManager(s).

QNetworkAccessManager is used for all network access by QML. By implementing a factory it is possible to create custom QNetworkAccessManager with specialized caching, proxy and cookie support.

The factory must be set before executing the engine.

Note: QQmlEngine does not take ownership of the factory.

See also networkAccessManagerFactory().

void QQmlEngine::setOutputWarningsToStandardError(bool enabled)

Set whether warning messages will be output to stderr to enabled.

If enabled is true, any warning messages generated by QML will be output to stderr and emitted by the warnings() signal. If enabled is false, only the warnings() signal will be emitted. This allows applications to handle warning output themselves.

The default value is true.

See also outputWarningsToStandardError().

void QQmlEngine::setPluginPathList(const QStringList &paths)

Sets the list of directories where the engine searches for native plugins for imported modules (referenced in the qmldir file) to paths.

By default, the list contains only ., i.e. the engine searches in the directory of the qmldir file itself.

See also pluginPathList() and addPluginPath().

[since 5.12] template <typename T> T QQmlEngine::singletonInstance(int qmlTypeId)

Returns the instance of a singleton type that was registered under qmlTypeId.

The template argument T may be either QJSValue or a pointer to a QObject-derived type and depends on how the singleton was registered. If no instance of T has been created yet, it is created now. If qmlTypeId does not represent a valid singleton type, either a default constructed QJSValue or a nullptr is returned.

QObject* example:

class MySingleton : public QObject {
    Q_OBJECT

    // Register as default constructed singleton.
    QML_ELEMENT
    QML_SINGLETON

    static int typeId;
    // ...
};

    MySingleton::typeId = qmlTypeId(...);

    // Retrieve as QObject*
    QQmlEngine engine;
    MySingleton* instance = engine.singletonInstance<MySingleton*>(MySingleton::typeId);

QJSValue example:

    // Register with QJSValue callback
    int typeId = qmlRegisterSingletonType(...);

    // Retrieve as QJSValue
    QQmlEngine engine;
    QJSValue instance = engine.singletonInstance<QJSValue>(typeId);

It is recommended to store the QML type id, e.g. as a static member in the singleton class. The lookup via qmlTypeId() is costly.

This function was introduced in Qt 5.12.

See also QML_SINGLETON, qmlRegisterSingletonType(), and qmlTypeId().

void QQmlEngine::trimComponentCache()

Trims the engine's internal component cache.

This function causes the property metadata of any loaded components which are not currently in use to be destroyed.

A component is considered to be in use if there are any extant instances of the component itself, any instances of other components that use the component, or any objects instantiated by any of those components.

See also clearComponentCache().

QList<QQmlAbstractUrlInterceptor *> QQmlEngine::urlInterceptors() const

Returns the list of currently active URL interceptors.

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 further modification. 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.

Once qmlProtectModule has been called, a QML engine will not search for a new qmldir file to load the module anymore. It will re-use any qmldir files it has loaded before, though. Therefore, types present at this point continue to work. Mind that different QML engines may load different modules. The module protection, however, is global and affects all engines. The overhead of locating qmldir files and loading plugins may be noticeable with slow file systems. Therefore, protecting a module once you are sure you won't need to load it anymore can be a good optimization. Mind also that the module lock not only affects plugins but also any other qmldir directives, like import or prefer, as well as any composite types or scripts declared in a qmldir file.

In addition, after this function is called, any attempt to register C++ types into this uri, major version combination will lead to a runtime error.

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.

NOTE: qmlRegisterSingleton can only be used when all types of that module are registered procedurally.

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.

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 to declare properties in QML, but when passed from C++, it is recognized. In QML, you can use properties of this type if they are declared in C++.

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. For qmake, specify the following in your project file:

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

With CMake, you pass the URI and version to qt_add_qml_module

qt6_add_qml_module(myapp
  URI com.mycompany.qmlcomponents
  VERSION 1.0
)

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.

NOTE: When classes have the same name but are located in different namespaces using QML_ELEMENT on both of them will cause a conflict. Make sure to use QML_NAMED_ELEMENT() for one of them instead.

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, methods, and enumerations 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(), QML_EXTENDED_NAMESPACE(), and Registering Extension Objects.

QML_EXTENDED_NAMESPACE(EXTENDED_NAMESPACE)

Declares that the enclosing type uses EXTENDED_NAMESPACE as an extension to provide further enumerations in QML. This takes effect if the type is exposed to QML using a QML_ELEMENT or QML_NAMED_ELEMENT() macro. The enumerations need to be exposed to the metaobject system for this to work.

For example, give the following C++ code

namespace MyNamespace {
    Q_NAMESPACE
    enum MyEnum { MyEnumerator = 10 };
    Q_ENUM_NS(MyEnum)
}

class QmlType : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_EXTENDED_NAMESPACE(MyNamespace)
}

we can access the enum in QML:

QmlType {
    property int i: QmlType.MyEnumerator // i will be 10
}

Note: EXTENDED_NAMESPACE can also be a QObject or QGadget; in that case - and in contrast to QML_EXTENDED, which also exposes methods and properties - only its enumerations are exposed.

Note: EXTENDED_NAMESPACE must have a metaobject; i.e. it must either be a namespace which contains the Q_NAMESPACE macro or a QObject/QGadget.

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

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(), QML_EXTENDED(), or QML_EXTENDED_NAMESPACE() 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. To register a namespace, see QML_FOREIGN_NAMESPACE().

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, QML_NAMED_ELEMENT(), and QML_FOREIGN_NAMESPACE().

QML_FOREIGN_NAMESPACE(FOREIGN_NAMESPACE)

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

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

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

QML_IMPLEMENTS_INTERFACES(interfaces)

This macro tells Qt which QML interfaces the class implements. This macro should only be used for interfacing with classes using QML_INTERFACE, use Q_INTERFACES otherwise. It's required in order for declarative registration via QML_ELEMENT to function properly.

See also QML_INTERFACE and Q_INTERFACES.

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.

NOTE: When inheriting from types using QML_INTERFACE, use QML_IMPLEMENTS_INTERFACES instead of Q_INTERFACES.

See also QML_IMPLEMENTS_INTERFACES(), 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 either the type's default constructor or a static factory function of the signature T *create(QQmlEngine *, QJSEngine *) when the type is first accessed. If both do exist and are accessible, the default constructor is preferred. If there is no default constructor and no factory function the singleton is inaccessible.

In order to declare a default-constructible class as singleton, all you have to do is add QML_SINGLETON:

class MySingleton : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
    // Q_PROPERTY( ... )
public:
    // members, Q_INVOKABLE functions, etc.
};

If the singleton class is not default-constructible, but you can modify it, you can add a factory function to it, in order to make it accessible:

class MySingleton : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
    // Q_PROPERTY( ... )

public:
    static MySingleton *create(QQmlEngine *qmlEngine, QJSEngine *jsEngine)
    {
        MySingleton *result = nullptr;
        // Create the object using some custom constructor or factory.
        // The QML engine will assume ownership and delete it, eventually.
        return result;
    }

    // members, Q_INVOKABLE functions, etc
};

If you cannot modify the class and it does not have a default constructor or a suitable factory function, you can provide a QML_FOREIGN wrapper to define the factory function:

struct SingletonForeign
{
    Q_GADGET
    QML_FOREIGN(MySingleton)
    QML_SINGLETON
    QML_NAMED_ELEMENT(MySingleton)
public:

    static MySingleton *create(QQmlEngine *, QJSEngine *engine)
    {
        MySingleton *result = nullptr;
        // Create the instance using some custom constructor or factory.
        // The QML engine will assume ownership and delete it, eventually.
        return result;
    }
};

Finally, if you want to provide one specific singleton object, the creation of which you cannot control, you can return that from a factory function. This is a replacement for the qmlRegisterSingletonInstance function. If you were calling

qmlRegisterSingletonInstance("MyModule", 1, 0, "MySingleton", myObject);

with myObject being of type MySingleton *, you can do the following instead:

struct SingletonForeign
{
    Q_GADGET
    QML_FOREIGN(MySingleton)
    QML_SINGLETON
    QML_NAMED_ELEMENT(MySingleton)
public:

    // Initialize this using myObject where you would previously
    // call qmlRegisterSingletonInstance().
    static MySingleton *s_singletonInstance = nullptr;

    static MySingleton *create(QQmlEngine *, QJSEngine *engine)
    {
        // The instance has to exist before it is used. We cannot replace it.
        Q_ASSERT(s_singletonInstance);

        // The engine has to have the same thread affinity as the singleton.
        Q_ASSERT(engine->thread() == s_singletonInstance->thread());

        // There can only be one engine accessing the singleton.
        if (s_engine)
            Q_ASSERT(engine == s_engine);
        else
            s_engine = engine;

        // Explicitly specify C++ ownership so that the engine doesn't delete
        // the instance.
        QJSEngine::setObjectOwnership(s_singletonInstance,
                                      QJSEngine::CppOwnership);
        return s_singletonInstance;
    }

private:
    static QJSEngine *s_engine = nullptr;
};

This way, the pre-existing class MySingleton is declared to be a QML singleton, called MySingleton. You can specify an instance for it any time before it is used by setting the s_singletonInstance member. None of this requires modification of MySingleton itself.

Note: This pattern doesn't work if either the singleton is accessed by multiple QML engines, or if the QML engine accessing it has a different thread affinity than the singleton object itself. As shown above, you can check the parameters to the create() method for identity and thread affinity of the engine in order to assert on that.

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.

Since Qt 6.0 you can use "" instead of a reason to use a standard message instead.

See also QML_ELEMENT, QML_NAMED_ELEMENT(), and QML_ANONYMOUS.

© 2021 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.