initializing-qml-runtime.qdoc

Go to the documentation of this file.

// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
\page qtqml-initializing-qml-runtime.html
\title Initializing the QML Runtime
\brief Provides information on how to initialize the QML runtime in applications.
 
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 \c qml tool, which loads
\c {.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:
 
\list
    \li Create a Qt C++ application.
 
        The application should load the QQmlEngine in one of the following ways:
        \list
            \li Loading the QML file through a QQuickView instance.
            \li Creating a QQmlEngine instance and loading QML files with
                QQmlComponent.
        \endlist
    \li Create a Qt Bridges application.
 
        For details, see Qt Bridges documentation:
        \list
            \li \l{Qt Bridges for C#}
            \li \l{Qt Bridges for Rust}
        \endlist
    \li Use the \c 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
        \l{Prototyping with the QML Runtime Tool}.
\endlist
 
\section1 Initializing the QML Runtime in C++ Applications
 
\section2 Initializing with QQuickView
 
\l QQuickView is a QWindow-based class that can load QML files. For example, if
there is a QML file, \c application.qml, it will look like this:
 
\qml
    import QtQuick
 
    Rectangle { width: 100; height: 100; color: "red" }
\endqml
 
It can be loaded in a Qt application's \c main.cpp file like this:
 
\code
    #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();
    }
\endcode
 
This creates a QWindow-based view that displays the contents of
\c {application.qml}.
 
\section3 Build files
 
\if defined(onlinedocs)
  \tab {build-qt-app}{tab-cmake}{CMake}{checked}
  \tab {build-qt-app}{tab-qmake}{qmake}{}
  \tabcontent {tab-cmake}
\else
  \section4 Using CMake
\endif
  \include {module-use.qdocinc} {building with cmake} {Quick}
\if defined(onlinedocs)
  \endtabcontent
  \tabcontent {tab-qmake}
\else
  \section4 Using qmake
\endif
  \include {module-use.qdocinc} {building_with_qmake} {quick}
  For more information, see \l{Creating Project Files}.
\if defined(onlinedocs)
  \endtabcontent
\endif
 
\section2 Creating a QQmlEngine directly
 
If \c application.qml doesn't have any graphical components, or if it's
preferred to avoid \l QQuickView for other reasons, the \l QQmlEngine can be
constructed directly instead. In this case, \c application.qml is loaded as a
\l QQmlComponent instance rather than placed into a view:
 
\code
    #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();
    }
\endcode
 
If you're not using any graphical items from Qt Quick, you can replace
\l QGuiApplication with a \l QCoreApplication in the code above. This way, you
can use QML as a language without any dependencies to the \l{Qt GUI} module.
 
*/