Initializing the QML Runtime

QML documents are loaded and run by the QML runtime. The QML runtime also provides access to other Qt or third-party QML modules and types.

In addition, the Qt Framework provides the qml tool, which loads .qml files. This tool is useful for developing and testing QML code without having to write a C++ application to load the QML runtime.

To run an application that uses QML, your application must invoke the QML runtime. To invoke the QML runtime:

• Create a Qt C++ application.

  The application should load the QQmlEngine in one of the following ways:

  • Loading the QML file through a QQuickView instance.
  • Creating a QQmlEngine instance and loading QML files with QQmlComponent.
• Create a Qt Bridges application.

  For details, see Qt Bridges documentation:

  • Qt Bridges for C#
  • Qt Bridges for Rust
• Use the qml tool to load and run QML files directly.

  This tool is useful for developing and testing QML code without having to write an application to load the QML runtime. For details, see Prototyping with the QML Runtime Tool.

Initializing the QML Runtime in C++ Applications

Initializing with QQuickView

QQuickView is a QWindow-based class that can load QML files. For example, if there is a QML file, application.qml, it will look like this:

import QtQuick

Rectangle { width: 100; height: 100; color: "red" }

It can be loaded in a Qt application's main.cpp file like this:

#include <QGuiApplication>
#include <QQuickView>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    QQuickView view;
    view.setSource(QUrl::fromLocalFile("application.qml"));
    view.show();

    return app.exec();
}

This creates a QWindow-based view that displays the contents of application.qml.

Build files

find_package(Qt6 REQUIRED COMPONENTS Quick)
target_link_libraries(mytarget PRIVATE Qt6::Quick)

QT += quick

Creating a QQmlEngine directly

If application.qml doesn't have any graphical components, or if it's preferred to avoid QQuickView for other reasons, the QQmlEngine can be constructed directly instead. In this case, application.qml is loaded as a QQmlComponent instance rather than placed into a view:

#include <QGuiApplication>
#include <QQmlEngine>
#include <QQmlContext>
#include <QQmlComponent>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    QQmlEngine engine;
    QQmlContext *objectContext = new QQmlContext(engine.rootContext());

    QQmlComponent component(&engine, "application.qml");
    QObject *object = component.create(objectContext);

    // ... delete object and objectContext when necessary

    return app.exec();
}

If you're not using any graphical items from Qt Quick, you can replace QGuiApplication with a QCoreApplication in the code above. This way, you can use QML as a language without any dependencies to the Qt GUI module.