QQmlEngine Class

Dokumentation der Mitgliedsfunktionen

[explicit] QQmlEngine::QQmlEngine(QObject *parent = nullptr)

Erstellen Sie eine neue QQmlEngine mit der angegebenen parent.

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

Zerstört das QQmlEngine.

Alle QQmlContext's, die auf dieser Engine erstellt wurden, werden ungültig gemacht, aber nicht zerstört (es sei denn, sie sind dem QQmlEngine Objekt übergeordnet).

Siehe ~QJSEngine() für Details zum Aufräumen der JS-Engine.

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

Legt die provider für Bilder fest, die über das Schema image: url mit dem Host providerId angefordert werden. QQmlEngine übernimmt den Besitz von provider.

Bildanbieter ermöglichen die Unterstützung von Pixmap- und Threaded-Image-Anforderungen. Einzelheiten zur Implementierung und Verwendung von Bildanbietern finden Sie in der Dokumentation QQuickImageProvider.

Alle erforderlichen Bildanbieter sollten der Engine hinzugefügt werden, bevor QML-Quelldateien geladen werden.

Siehe auch removeImageProvider(), QQuickImageProvider, und QQmlImageProviderBase.

void QQmlEngine::addImportPath(const QString &path)

Fügt path als ein Verzeichnis hinzu, in dem die Engine nach installierten Modulen in einer URL-basierten Verzeichnisstruktur sucht.

path kann ein lokales Dateisystemverzeichnis, ein Qt-Ressourcenpfad (:/imports), eine Qt-Ressourcenurl (qrc:/imports) oder eine URL sein.

Die path wird in eine kanonische Form umgewandelt, bevor sie der Importpfadliste hinzugefügt wird.

Die neu hinzugefügte path wird an erster Stelle in importPathList() stehen.

Siehe auch setImportPathList(), QML-Module und QML-Importpfad

void QQmlEngine::addPluginPath(const QString &path)

Fügt path als Verzeichnis hinzu, in dem die Engine nach nativen Plugins für importierte Module (auf die in der Datei qmldir verwiesen wird) sucht.

Standardmäßig enthält die Liste nur ., d. h. die Engine sucht im Verzeichnis der Datei qmldir selbst.

Das neu hinzugefügte path wird als erstes in der pluginPathList() aufgeführt.

Siehe auch setPluginPathList().

void QQmlEngine::addUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)

Fügt eine urlInterceptor hinzu, die bei der Auflösung von URLs in QML verwendet wird. Dies gilt auch für URLs, die zum Laden von Skriptdateien und QML-Typen verwendet werden. Die URL-Interceptoren sollten nicht verändert werden, während die Engine Dateien lädt, sonst kann die URL-Auswahl inkonsistent sein. Wenn mehrere URL-Abfangmechanismen angegeben werden, werden sie in der Reihenfolge aufgerufen, in der sie für jede URL hinzugefügt wurden.

QQmlEngine übernimmt nicht die Verantwortung für den Interceptor und löscht ihn nicht.

QUrl QQmlEngine::baseUrl() const

Gibt die Basis-URL für diese Engine zurück. Die Basis-URL wird nur verwendet, um Komponenten aufzulösen, wenn eine relative URL an den QQmlComponent -Konstruktor übergeben wird.

Wenn eine Basis-URL nicht explizit festgelegt wurde, gibt diese Methode das aktuelle Arbeitsverzeichnis der Anwendung zurück.

Siehe auch setBaseUrl().

void QQmlEngine::clearComponentCache()

Löscht den internen Komponenten-Cache der Engine.

Mit dieser Funktion werden die Eigenschaftsmetadaten der meisten Komponenten, die zuvor von der Engine geladen wurden, zerstört. Dies geschieht, indem nicht referenzierte Komponenten aus dem Komponenten-Cache der Engine entfernt werden. Komponenten, die noch referenziert sind, werden nicht gelöscht, da dies mit ziemlicher Sicherheit zu weiteren Abstürzen führen würde.

Wenn keine Komponenten referenziert sind, setzt diese Funktion die Engine in einen Zustand zurück, in dem sie keine geladenen Komponentendaten enthält. Dies kann nützlich sein, um eine kleinere Teilmenge des vorherigen Komponentensatzes neu zu laden oder um eine neue Version einer zuvor geladenen Komponente zu laden.

Sobald der Komponenten-Cache geleert wurde, müssen die Komponenten geladen werden, bevor neue Objekte erstellt werden können.

Als allgemeine Faustregel gilt: Stellen Sie sicher, dass keine Objekte, die aus QML-Komponenten erstellt wurden, lebendig sind, wenn Sie den Komponenten-Cache leeren.

Siehe auch trimComponentCache() und clearSingletons().

void QQmlEngine::clearSingletons()

Löscht alle Singletons, die die Engine besitzt.

Diese Funktion entfernt alle Singleton-Instanzen und löscht alle QObjects, die der Engine gehören. Dies ist nützlich, um sicherzustellen, dass keine QML-erstellten Objekte übrig sind, bevor clearComponentCache() aufgerufen wird.

QML-Eigenschaften, die QObject-basierte Singleton-Instanzen enthalten, werden null, wenn die Engine das Singleton besitzt oder behalten ihren Wert, wenn die Engine es nicht besitzt. Die Singletons werden nicht automatisch neu erstellt, wenn auf bestehende, mit QML erstellte Objekte zugegriffen wird. Nur wenn neue Komponenten instanziiert werden, werden die Singletons neu erstellt.

Siehe auch clearComponentCache().

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

Gibt den QQmlContext für den object zurück, oder nullptr, wenn kein Kontext gesetzt wurde.

Wenn QQmlEngine eine QObject instanziiert, wird ihr automatisch ein interner Kontext zugewiesen. Solche internen Kontexte sind schreibgeschützt. Sie können keine Kontexteigenschaften für sie festlegen.

Siehe auch setContextForObject(), qmlContext(), qmlEngine(), und QQmlContext::setContextProperty().

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

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

[signal] void QQmlEngine::exit(int retCode)

Dieses Signal wird ausgegeben, wenn die von der Engine geladene QML die Ereignisschleife mit dem angegebenen Returncode retCode verlassen möchte.

Siehe auch quit().

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

Gibt den für providerId eingestellten Bildanbieter zurück, wenn er gefunden wurde; andernfalls wird nullptr zurückgegeben.

Siehe auch QQuickImageProvider.

QStringList QQmlEngine::importPathList() const

Gibt die Liste der Verzeichnisse zurück, in denen die Engine nach installierten Modulen in einer URL-basierten Verzeichnisstruktur sucht.

Befindet sich beispielsweise /opt/MyApp/lib/imports im Pfad, dann veranlasst QML, das com.mycompany.Feature importiert, QQmlEngine, in /opt/MyApp/lib/imports/com/mycompany/Feature/ nach den von diesem Modul bereitgestellten Komponenten zu suchen. Eine Datei qmldir ist erforderlich, um die Typversionszuordnung und möglicherweise QML-Erweiterungsplugins zu definieren.

Standardmäßig enthält diese Liste die unter QML-Importpfad genannten Pfade.

Siehe auch addImportPath() und setImportPathList().

QQmlIncubationController *QQmlEngine::incubationController() const

Gibt den aktuell eingestellten Inkubationsregler zurück, oder 0, wenn kein Regler eingestellt wurde.

Siehe auch setIncubationController().

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

Führt die aktuellen URL-Interceptoren auf dem angegebenen url der angegebenen type aus und gibt das Ergebnis zurück.

[since 6.6] void QQmlEngine::markCurrentFunctionAsTranslationBinding()

Wenn diese Methode innerhalb einer Funktion aufgerufen wird, die Teil einer Bindung in QML ist, wird die Bindung als Übersetzungsbindung behandelt.

class I18nAwareClass : public QObject {

  //...

   QString text() const
   {
        if (auto engine = qmlEngine(this))
            engine->markCurrentFunctionAsTranslationBinding();
        return tr("Hello, world!");
   }
};

Diese Funktion wurde in Qt 6.6 eingeführt.

Siehe auch QQmlEngine::retranslate.

QNetworkAccessManager *QQmlEngine::networkAccessManager() const

Gibt einen gemeinsamen QNetworkAccessManager zurück, der von jedem von dieser Engine instanziierten QML-Typ verwendet werden kann.

Wenn ein QQmlNetworkAccessManagerFactory gesetzt wurde und ein QNetworkAccessManager noch nicht erstellt wurde, wird das QQmlNetworkAccessManagerFactory verwendet, um das QNetworkAccessManager zu erstellen; andernfalls hat das zurückgegebene QNetworkAccessManager keinen Proxy oder Cache gesetzt.

Siehe auch setNetworkAccessManagerFactory().

QQmlNetworkAccessManagerFactory *QQmlEngine::networkAccessManagerFactory() const

Gibt die aktuelle QQmlNetworkAccessManagerFactory zurück.

Siehe auch setNetworkAccessManagerFactory().

QString QQmlEngine::offlineStorageDatabaseFilePath(const QString &databaseName) const

Gibt den Dateipfad zurück, in dem sich eine Datenbank Local Storage mit dem Bezeichner databaseName befindet (oder befinden würde).

Siehe auch LocalStorage.openDatabaseSync().

[signal, since 6.5] void QQmlEngine::offlineStoragePathChanged()

Dieses Signal wird ausgesendet, wenn sich offlineStoragePath ändert.

Diese Funktion wurde in Qt 6.5 eingeführt.

bool QQmlEngine::outputWarningsToStandardError() const

Gibt true zurück, wenn Warnmeldungen zusätzlich zur Ausgabe durch das Signal warnings() auf stderr ausgegeben werden, andernfalls false.

Der Standardwert ist true.

Siehe auch setOutputWarningsToStandardError().

QStringList QQmlEngine::pluginPathList() const

Gibt die Liste der Verzeichnisse zurück, in denen die Engine nach nativen Plugins für importierte Module (auf die in der Datei qmldir verwiesen wird) sucht.

Standardmäßig enthält die Liste nur ., d. h. die Maschine sucht im Verzeichnis der Datei qmldir selbst.

Siehe auch addPluginPath() und setPluginPathList().

[signal] void QQmlEngine::quit()

Dieses Signal wird ausgegeben, wenn die von der Engine geladene QML beendet werden soll.

Siehe auch exit().

void QQmlEngine::removeImageProvider(const QString &providerId)

Entfernt den Bildanbieter für providerId.

Siehe auch addImageProvider() und QQuickImageProvider.

void QQmlEngine::removeUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)

Entfernen Sie eine urlInterceptor, die zuvor mit addUrlInterceptor hinzugefügt wurde. Die URL-Abfangvorrichtungen sollten nicht geändert werden, während die Engine Dateien lädt, da sonst die URL-Auswahl inkonsistent sein könnte.

Dadurch wird der Interceptor nicht gelöscht, sondern lediglich aus der Engine entfernt. Sie können ihn anschließend in derselben oder einer anderen Engine wiederverwenden.

[slot] void QQmlEngine::retranslate()

Aktualisiert alle Bindungsausdrücke, die zur Übersetzung markierte Zeichenketten verwenden.

Rufen Sie diese Funktion auf, nachdem Sie einen neuen Übersetzer mit QCoreApplication::installTranslator installiert haben, um sicherzustellen, dass Ihre Benutzerschnittstelle aktuelle Übersetzungen anzeigt.

QQmlContext *QQmlEngine::rootContext() const

Gibt den Wurzelkontext der Engine zurück.

Der Wurzelkontext wird automatisch von QQmlEngine erstellt. Daten, die allen von der Engine instanziierten QML-Komponenteninstanzen zur Verfügung stehen sollen, sollten in den Wurzelkontext gestellt werden.

Zusätzliche Daten, die nur einer Teilmenge von Komponenteninstanzen zur Verfügung stehen sollen, sollten in Subkontexten abgelegt werden, die dem Wurzelkontext übergeordnet sind.

void QQmlEngine::setBaseUrl(const QUrl &url)

Setzen Sie die Basis-URL für diese Engine auf url.

Siehe auch baseUrl().

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

Setzt den QQmlContext für den object auf context. Wenn der object bereits einen Kontext hat, wird eine Warnung ausgegeben, aber der Kontext wird nicht geändert.

Wenn die QQmlEngine eine QObject instanziiert, wird der Kontext automatisch gesetzt.

Siehe auch contextForObject().

void QQmlEngine::setImportPathList(const QStringList &paths)

Legt paths als die Liste der Verzeichnisse fest, in denen die Engine nach installierten Modulen in einer URL-basierten Verzeichnisstruktur sucht.

Standardmäßig enthält diese Liste die unter QML-Importpfad genannten Pfade.

Siehe auch importPathList() und addImportPath().

void QQmlEngine::setIncubationController(QQmlIncubationController *controller)

Legt die Inkubationszeit des Motors fest controller. Die Engine kann nur ein aktives Steuergerät haben und übernimmt nicht die Verantwortung für dieses.

Siehe auch incubationController().

void QQmlEngine::setNetworkAccessManagerFactory(QQmlNetworkAccessManagerFactory *factory)

Legt die factory für die Erstellung von QNetworkAccessManager(s) fest.

QNetworkAccessManager wird für alle Netzwerkzugriffe von QML verwendet. Durch die Implementierung einer Fabrik ist es möglich, benutzerdefinierte QNetworkAccessManager mit spezieller Caching-, Proxy- und Cookie-Unterstützung zu erstellen.

Die Fabrik muss vor dem Ausführen der Engine gesetzt werden.

Siehe auch networkAccessManagerFactory().

void QQmlEngine::setOutputWarningsToStandardError(bool enabled)

Legen Sie auf enabled fest, ob Warnmeldungen auf stderr ausgegeben werden sollen.

Wenn enabled wahr ist, werden alle von QML erzeugten Warnmeldungen auf stderr ausgegeben und durch das Signal warnings() ausgegeben. Wenn enabled falsch ist, wird nur das Signal warnings() ausgegeben. Dies ermöglicht es Anwendungen, die Ausgabe von Warnungen selbst zu steuern.

Der Standardwert ist true.

Siehe auch outputWarningsToStandardError().

void QQmlEngine::setPluginPathList(const QStringList &paths)

Setzt die Liste der Verzeichnisse, in denen die Engine nach nativen Plugins für importierte Module (auf die in der Datei qmldir verwiesen wird) sucht, auf paths.

Standardmäßig enthält die Liste nur ., d.h. die Engine sucht im Verzeichnis der Datei qmldir selbst.

Siehe auch pluginPathList() und addPluginPath().

template <typename T> T QQmlEngine::singletonInstance(int qmlTypeId)

Gibt die Instanz eines Singleton-Typs zurück, der unter qmlTypeId registriert wurde.

Das Template-Argument T kann entweder QJSValue oder ein Zeiger auf einen QObject-abgeleiteten Typ sein und hängt davon ab, wie das Singleton registriert wurde. Wenn noch keine Instanz von T erzeugt wurde, wird sie jetzt erzeugt. Wenn qmlTypeId keinen gültigen Singleton-Typ darstellt, wird entweder ein standardmäßig konstruierter QJSValue oder ein nullptr zurückgegeben.

QObject* Beispiel:

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 Beispiel:

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

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

Es wird empfohlen, die QML-Typ-ID zu speichern, z.B. als statisches Mitglied in der Singleton-Klasse. Die Suche über qmlTypeId() ist aufwendig.

Siehe auch QML_SINGLETON, qmlRegisterSingletonType(), und qmlTypeId().

[since 6.5] template <typename T> T QQmlEngine::singletonInstance(QAnyStringView uri, QAnyStringView typeName)

Dies ist eine überladene Funktion.

Gibt die Instanz eines Singleton-Typs namens typeName aus dem durch uri angegebenen Modul zurück.

Diese Methode kann als Alternative zum Aufruf von qmlTypeId gefolgt von der id-basierten Überladung von singletonInstance verwendet werden. Dies ist praktisch, wenn man ein Singleton nur einmal einrichten muss; wenn ein wiederholter Zugriff auf das Singleton erforderlich ist, ermöglicht das Zwischenspeichern seiner typeId einen schnelleren späteren Zugriff über type-id based overload.

Das Template-Argument T kann entweder QJSValue oder ein Zeiger auf einen QObject-abgeleiteten Typ sein und hängt davon ab, wie das Singleton registriert wurde. Wenn noch keine Instanz von T erzeugt wurde, wird sie jetzt erzeugt. Wenn typeName keinen gültigen Singleton-Typ repräsentiert, wird entweder ein standardmäßig konstruierter QJSValue oder ein nullptr zurückgegeben.

    QQmlEngine engine;
    MySingleton *singleton = engine.singletonInstance<MySingleton *>("mymodule", "MySingleton");
/

Diese Funktion wurde in Qt 6.5 eingeführt.

Siehe auch QML_SINGLETON, qmlRegisterSingletonType(), und qmlTypeId().

void QQmlEngine::trimComponentCache()

Trimmt den internen Komponenten-Cache der Engine.

Diese Funktion bewirkt, dass die Eigenschaftsmetadaten aller geladenen Komponenten, die derzeit nicht in Gebrauch sind, zerstört werden.

Eine Komponente gilt als in Gebrauch, wenn es Instanzen der Komponente selbst, Instanzen anderer Komponenten, die die Komponente verwenden, oder Objekte, die von einer dieser Komponenten instanziiert wurden, gibt.

Siehe auch clearComponentCache().

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

Gibt die Liste der derzeit aktiven URL-Interceptoren zurück.

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

Dieses Signal wird ausgegeben, wenn warnings Nachrichten von QML erzeugt werden.