Back to Qt.io
Contact Us Blog Download Qt

QQmlApplicationEngine Class

QQmlApplicationEngine bietet eine bequeme Möglichkeit zum Laden einer Anwendung aus einer einzelnen QML-Datei. Mehr...

Kopfzeile: #include <QQmlApplicationEngine>
CMake: find_package(Qt6 REQUIRED COMPONENTS Qml)
target_link_libraries(mytarget PRIVATE Qt6::Qml)
qmake: QT += qml
Vererbungen: QQmlEngine

Öffentliche Funktionen

QQmlApplicationEngine(QObject *parent = nullptr)
QQmlApplicationEngine(const QString &filePath, QObject *parent = nullptr)
QQmlApplicationEngine(const QUrl &url, QObject *parent = nullptr)
(since 6.5) QQmlApplicationEngine(QAnyStringView uri, QAnyStringView typeName, QObject *parent = nullptr)
virtual ~QQmlApplicationEngine() override
QList<QObject *> rootObjects() const

Öffentliche Slots

void load(const QString &filePath)
void load(const QUrl &url)
void loadData(const QByteArray &data, const QUrl &url = QUrl())
(since 6.5) void loadFromModule(QAnyStringView uri, QAnyStringView typeName)
(since 6.0) void setExtraFileSelectors(const QStringList &extraFileSelectors)
void setInitialProperties(const QVariantMap &initialProperties)

Signale

void objectCreated(QObject *object, const QUrl &url)
(since 6.4) void objectCreationFailed(const QUrl &url)

Detaillierte Beschreibung

Diese Klasse kombiniert QQmlEngine und QQmlComponent, um einen bequemen Weg zum Laden einer einzelnen QML-Datei zu bieten. Sie stellt auch einige zentrale Anwendungsfunktionen für QML zur Verfügung, die eine hybride C++/QML-Anwendung normalerweise von C++ aus steuern würde.

Es kann wie folgt verwendet werden:

#include <QGuiApplication>
#include <QQmlApplicationEngine>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);
    QQmlApplicationEngine engine("main.qml");
    return app.exec();
}

Im Gegensatz zu QQuickView erstellt die QQmlApplicationEngine nicht automatisch ein Stammfenster. Wenn Sie visuelle Elemente von Qt Quick verwenden, müssen Sie diese innerhalb eines Window platzieren.

Sie können auch QCoreApplication mit QQmlApplicationEngine verwenden, wenn Sie keine QML-Module verwenden, die ein QGuiApplication erfordern (wie QtQuick).

Liste der Konfigurationsänderungen gegenüber einem Standard QQmlEngine:

  • Verbindung von Qt.quit() zu QCoreApplication::quit()
  • Lädt automatisch Übersetzungsdateien aus einem i18n-Verzeichnis neben der Haupt-QML-Datei.
    • Übersetzungsdateien müssen den Präfix "qml_" haben, z.B. qml_ja_JP.qm.
  • Die Übersetzungen werden neu geladen, wenn die Eigenschaft QJSEngine::uiLanguage / Qt.uiLanguage geändert wird.
  • Setzt automatisch einen Inkubationsregler, wenn die Szene einen QQuickWindow enthält.
  • Setzt automatisch einen QQmlFileSelector als Url-Interceptor und wendet Dateiselektoren auf alle QML-Dateien und Assets an.

Das Verhalten der Engine kann durch die Verwendung der geerbten Methoden von QQmlEngine weiter angepasst werden.

Dokumentation der Mitgliedsfunktionen

QQmlApplicationEngine::QQmlApplicationEngine(QObject *parent = nullptr)

Erstellen Sie eine neue QQmlApplicationEngine mit der angegebenen parent. Sie werden später load() aufrufen müssen, um eine QML-Datei zu laden.

QQmlApplicationEngine::QQmlApplicationEngine(const QString &filePath, QObject *parent = nullptr)

Erstellt eine neue QQmlApplicationEngine und lädt die QML-Datei unter der angegebenen Adresse filePath, die eine lokale Datei oder ein qrc-Pfad sein muss. Wenn ein relativer Pfad angegeben wird, wird dieser als relativ zum Arbeitsverzeichnis der Anwendung interpretiert.

Dies dient der Bequemlichkeit und ist dasselbe wie die Verwendung des leeren Konstruktors und der anschließende Aufruf von load.

QQmlApplicationEngine::QQmlApplicationEngine(const QUrl &url, QObject *parent = nullptr)

Erstellt eine neue QQmlApplicationEngine und lädt die QML-Datei unter der angegebenen Adresse url. Dies dient der Bequemlichkeit und ist dasselbe wie die Verwendung des leeren Konstruktors und der anschließende Aufruf von load.

[explicit, since 6.5] QQmlApplicationEngine::QQmlApplicationEngine(QAnyStringView uri, QAnyStringView typeName, QObject *parent = nullptr)

Erzeugt eine neue QQmlApplicationEngine und lädt den QML-Typ, der durch uri und typeName angegeben ist. Diese Funktion dient der Bequemlichkeit und ist dasselbe wie die Verwendung des leeren Konstruktors und der anschließende Aufruf von loadFromModule.

Diese Funktion wurde in Qt 6.5 eingeführt.

[override virtual noexcept] QQmlApplicationEngine::~QQmlApplicationEngine()

Zerstört die QQmlApplicationEngine und alle von ihr geladenen QML-Objekte.

[slot] void QQmlApplicationEngine::load(const QString &filePath)

Lädt die QML-Stammdatei, die sich unter filePath befindet. filePath muss ein Pfad zu einer lokalen Datei oder zu einer Datei im Ressourcendateisystem sein. Wenn filePath ein relativer Pfad ist, wird er als relativ zum Arbeitsverzeichnis der Anwendung betrachtet. Der durch die Datei definierte Objektbaum wird sofort instanziiert.

Wenn ein Fehler auftritt, werden Fehlermeldungen mit qWarning ausgegeben.

[slot] void QQmlApplicationEngine::load(const QUrl &url)

Lädt die QML-Stammdatei, die sich unter url befindet. Der durch die Datei definierte Objektbaum wird für lokale Datei-URLs sofort erstellt. Entfernte URLs werden asynchron geladen, sie hören auf das Signal objectCreated, um festzustellen, wann der Objektbaum bereit ist.

Tritt ein Fehler auf, wird das Signal objectCreated mit einem Null-Zeiger als Parameter ausgegeben und Fehlermeldungen werden mit qWarning gedruckt.

[slot] void QQmlApplicationEngine::loadData(const QByteArray &data, const QUrl &url = QUrl())

Lädt die in data angegebene QML. Der durch data definierte Objektbaum wird sofort instanziiert.

Wenn eine url angegeben ist, wird sie als Basis-URL der Komponente verwendet. Dies wirkt sich auf relative Pfade innerhalb der Daten und Fehlermeldungen aus.

Wenn ein Fehler auftritt, werden Fehlermeldungen mit qWarning ausgegeben.

[slot, since 6.5] void QQmlApplicationEngine::loadFromModule(QAnyStringView uri, QAnyStringView typeName)

Lädt den QML-Typ typeName aus dem durch uri angegebenen Modul. Wenn der Typ aus einer QML-Datei stammt, die sich in einer entfernten URL befindet, wird der Typ asynchron geladen. Hören Sie auf das Signal objectCreated, um festzustellen, wann der Objektbaum bereit ist.

Wenn ein Fehler auftritt, wird das Signal objectCreated mit einem Null-Zeiger als Parameter ausgegeben und Fehlermeldungen werden mit qWarning ausgegeben.

QQmlApplicationEngine engine;
engine.loadFromModule("QtQuick", "Rectangle");

Hinweis: Das durch uri identifizierte Modul wird im Importpfad gesucht, so als ob Sie import uri innerhalb einer QML-Datei ausführen würden. Wenn das Modul dort nicht gefunden wird, schlägt diese Funktion fehl.

Diese Funktion wurde in Qt 6.5 eingeführt.

Siehe auch QQmlComponent::loadFromModule.

[signal] void QQmlApplicationEngine::objectCreated(QObject *object, const QUrl &url)

Dieses Signal wird ausgegeben, wenn das Laden eines Objekts abgeschlossen ist. Wenn das Laden erfolgreich war, enthält object einen Zeiger auf das geladene Objekt, andernfalls ist der Zeiger NULL.

Die url zu der Komponente, von der object stammt, wird ebenfalls bereitgestellt.

Hinweis: Wenn der Pfad zur Komponente als QString mit einem relativen Pfad angegeben wurde, enthält url den vollständig aufgelösten Pfad zur Datei.

[signal, since 6.4] void QQmlApplicationEngine::objectCreationFailed(const QUrl &url)

Dieses Signal wird ausgegeben, wenn das Laden aufgrund eines Fehlers beendet wurde.

Die url zu der Komponente, die nicht geladen werden konnte, wird als Argument angegeben.

QGuiApplication app(argc, argv);
QQmlApplicationEngine engine;

// exit on error
QObject::connect(&engine, &QQmlApplicationEngine::objectCreationFailed,
    &app, []() { QCoreApplication::exit(-1); }, Qt::QueuedConnection);
engine.load(QUrl());
return app.exec();

Hinweis: Wenn der Pfad zu der Komponente als QString mit einem relativen Pfad angegeben wurde, enthält url einen vollständig aufgelösten Pfad zu der Datei.

Siehe auch QQmlApplicationEngine::objectCreated, das zusätzlich zu diesem Signal ausgegeben wird (auch wenn die Erstellung fehlgeschlagen ist).

Diese Funktion wurde in Qt 6.4 eingeführt.

QList<QObject *> QQmlApplicationEngine::rootObjects() const

Gibt eine Liste aller Root-Objekte zurück, die von QQmlApplicationEngine instanziiert wurden. Diese enthält nur Objekte, die über load() oder einen Convenience-Konstruktor geladen wurden.

Hinweis: In Qt-Versionen vor 5.9 ist diese Funktion als nichtconst markiert.

[slot, since 6.0] void QQmlApplicationEngine::setExtraFileSelectors(const QStringList &extraFileSelectors)

Legt die extraFileSelectors fest, die an die interne QQmlFileSelector übergeben wird, die für die Auflösung von URLs zu lokalen Dateien verwendet wird. Die extraFileSelectors werden angewendet, wenn die erste QML-Datei geladen wird. Ein nachträgliches Setzen hat keine Auswirkung.

Diese Funktion wurde in Qt 6.0 eingeführt.

Siehe auch QQmlFileSelector und QFileSelector::setExtraSelectors.

[slot] void QQmlApplicationEngine::setInitialProperties(const QVariantMap &initialProperties)

Legt die initialProperties fest, mit der die QML-Komponente initialisiert wird, nachdem sie geladen wurde.

QQmlApplicationEngine engine;

EventDatabase eventDatabase;
EventMonitor eventMonitor;

engine.setInitialProperties({
    { "eventDatabase", QVariant::fromValue(&eventDatabase) },
    { "eventMonitor", QVariant::fromValue(&eventMonitor) }
});

Siehe auch QQmlComponent::setInitialProperties, QQmlApplicationEngine::load, und QQmlApplicationEngine::loadData.

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