QQmlEngine Class

Dokumentation zu den Mitgliedsfunktionen

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

Erstelle eine neue QQmlEngine mit der angegebenen „ parent “.

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

Löscht den „ QQmlEngine “.

Alle auf dieser Engine erstellten „ QQmlContext “ werden ungültig gemacht, jedoch nicht zerstört (es sei denn, sie sind dem Objekt „ QQmlEngine “ untergeordnet).

Weitere Informationen zum Bereinigen der JS-Engine finden Sie unter ~QJSEngine().

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

Legt den provider fest, der für Bilder verwendet werden soll, die über das URL-Schema „image:“ mit dem Host „ providerId “ angefordert werden. Der QQmlEngine übernimmt die Verantwortung für „ provider “.

Bildanbieter ermöglichen die Unterstützung von Pixmap- und Threaded-Image-Anfragen. Weitere Informationen zur Implementierung und Verwendung von Bildanbietern finden Sie in der Dokumentation zu „ 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 Verzeichnis hinzu, in dem die Engine in einer URL-basierten Verzeichnisstruktur nach installierten Modulen sucht. Qt geht davon aus, dass alle Dateien und Ordner unter „ path “ aus einer vertrauenswürdigen Quelle stammen.

„ path “ kann ein Verzeichnis im lokalen Dateisystem, ein Qt-Ressourcenpfad (:/imports), eine Qt-Ressourcen- URL (qrc:/imports) oder eine URL sein.

Der „ path “ wird in die kanonische Form umgewandelt, bevor er zur Importpfadliste hinzugefügt wird.

Der neu hinzugefügte „ path “ steht an erster Stelle in der Liste „ importPathList()“.

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 sucht (auf die in der Datei „ qmldir “ verwiesen wird). Qt geht davon aus, dass alle Dateien und Ordner unter „ path “ aus einer vertrauenswürdigen Quelle stammen.

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

Die neu hinzugefügte „ path “ steht an erster Stelle in der „ pluginPathList “ ().

Siehe auch ` setPluginPathList()`.

void QQmlEngine::addUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)

Fügt einen „ urlInterceptor “ hinzu, der beim Auflösen 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, da dies zu Inkonsistenzen bei der URL-Auswahl führen kann. Werden mehrere URL-Interceptoren angegeben, werden diese für jede URL in der Reihenfolge aufgerufen, in der sie hinzugefügt wurden.

QQmlEngine Übernimmt keine 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 zum Auflösen von Komponenten verwendet, wenn eine relative URL an den Konstruktor ` QQmlComponent ` übergeben wird.

Wenn keine Basis-URL 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.

Diese Funktion bewirkt, dass die Metadaten der meisten zuvor von der Engine geladenen Komponenten gelöscht werden. Dazu werden nicht mehr referenzierte Komponenten aus dem Komponenten-Cache der Engine entfernt. Komponenten, auf die noch verwiesen wird, werden nicht entfernt, da dies mit hoher Wahrscheinlichkeit später zu Abstürzen führen würde.

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

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

Als allgemeine Faustregel gilt: Stellen Sie sicher, dass keine aus QML-Komponenten erstellten Objekte mehr aktiv sind, wenn Sie den Komponenten-Cache leeren.

Siehe auch trimComponentCache() und clearSingletons().

void QQmlEngine::clearSingletons()

Löscht alle Singleton-Instanzen, die der Engine gehören.

Diese Funktion entfernt alle Singleton-Instanzen und löscht dabei alle QObjects, die der Engine gehören. Dies ist nützlich, um sicherzustellen, dass vor dem Aufruf von ` clearComponentCache()` keine von QML erstellten Objekte übrig bleiben.

QML-Eigenschaften, die auf ` QObject` basierende Singleton-Instanzen enthalten, werden auf null gesetzt, wenn die Engine Eigentümer des Singletons ist, oder behalten ihren Wert bei, wenn die Engine nicht Eigentümer ist. Die Singletons werden nicht automatisch neu erstellt, wenn auf bereits vorhandene, von QML erstellte Objekte zugegriffen wird. Erst 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“, falls kein Kontext festgelegt wurde.

Wenn der „ QQmlEngine “ einen „ QObject “ instanziiert, wird ihm 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)

Implementiert: ` QObject::event(QEvent *e)`.

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

Dieses Signal wird ausgelöst, wenn das von der Engine geladene QML die Ereignisschleife mit dem angegebenen Rückgabecode „ retCode “ verlassen möchte.

Siehe auch quit().

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

Gibt den für „ providerId “ festgelegten Bildanbieter zurück, sofern dieser gefunden wird; andernfalls wird „ nullptr “ zurückgegeben.

Siehe auch QQuickImageProvider.

QStringList QQmlEngine::importPathList() const

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

Befindet sich beispielsweise /opt/MyApp/lib/imports im Pfad, führt ein QML-Code, der com.mycompany.Feature importiert, dazu, dass die „ QQmlEngine “ in /opt/MyApp/lib/imports/com/mycompany/Feature/ nach den von diesem Modul bereitgestellten Komponenten sucht. Eine „ qmldir “-Datei ist erforderlich, um die Zuordnung von Typen und Versionen sowie gegebenenfalls QML-Erweiterungs-Plugins 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ühre die aktuellen URL-Interceptoren für die angegebene URL „ url “ der angegebenen URL „ type “ aus und gib das Ergebnis zurück.

[since 6.6] void QQmlEngine::markCurrentFunctionAsTranslationBinding()

Wird diese Methode innerhalb einer Funktion aufgerufen, 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 ein allgemeines „ QNetworkAccessManager “ zurück, das von jedem durch diese Engine instanziierten QML-Typ verwendet werden kann.

Wenn ein „ QQmlNetworkAccessManagerFactory “ festgelegt wurde und noch kein „ QNetworkAccessManager “ erstellt wurde, wird der „ QQmlNetworkAccessManagerFactory “ zum Erstellen des „ QNetworkAccessManager “ verwendet; andernfalls sind für den zurückgegebenen „ QNetworkAccessManager “ weder ein Proxy noch ein Cache festgelegt.

Siehe auch setNetworkAccessManagerFactory().

QQmlNetworkAccessManagerFactory *QQmlEngine::networkAccessManagerFactory() const

Gibt den aktuellen QQmlNetworkAccessManagerFactory zurück.

Siehe auch setNetworkAccessManagerFactory().

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

Gibt den Dateipfad zurück, unter dem sich eine „ Local Storage “-Datenbank mit der Kennung „ databaseName “ befindet (bzw. befinden würde).

Siehe auch „ LocalStorage.openDatabaseSync() “.

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

Dieses Signal wird ausgelöst, 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 über das Signal „ warnings()“ auch an „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 sucht (die in der Datei „ qmldir “ referenziert sind).

Standardmäßig enthält die Liste nur ` .`, d. h., die Engine durchsucht das Verzeichnis der Datei ` qmldir ` selbst.

Siehe auch ` addPluginPath()` und ` setPluginPathList()`.

[signal] void QQmlEngine::quit()

Dieses Signal wird ausgelöst, wenn das von der Engine geladene QML beendet werden möchte.

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 einen „ urlInterceptor “, der zuvor mit „ addUrlInterceptor “ hinzugefügt wurde. Die URL-Interceptoren sollten nicht geändert werden, während die Engine Dateien lädt, da dies zu Inkonsistenzen bei der URL-Auswahl führen kann.

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

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

QQmlContext *QQmlEngine::rootContext() const

Gibt den Root-Kontext der Engine zurück.

Der Stammkontext wird automatisch von „ QQmlEngine “ erstellt. Daten, die allen von der Engine instanziierten QML-Komponenteninstanzen zur Verfügung stehen sollen, sollten im Stammkontext abgelegt werden.

Zusätzliche Daten, die nur für eine Teilmenge von Komponenteninstanzen verfügbar sein sollen, sollten in Unterkontexten abgelegt werden, die dem Stammkontext untergeordnet sind.

void QQmlEngine::setBaseUrl(const QUrl &url)

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

Siehe auch baseUrl().

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

Setzt den „ QQmlContext “ für den „ object “ auf „ context “. Wenn der „ object “ bereits über einen Kontext verfügt, wird eine Warnung ausgegeben, der Kontext wird jedoch nicht geändert.

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

Siehe auch contextForObject().

[since 6.12] bool QQmlEngine::setExternalSingletonInstance(QAnyStringView moduleName, QAnyStringView typeName, QObject *instance)

Legen Sie die Singleton-Instanz fest, die für den angegebenen Typ in der QML-Engine verwendet werden soll.

Mit dieser Funktion können Sie manuell eine von ` QObject` abgeleitete Instanz festlegen, die in QML für diese Engine als Singleton verwendet werden soll. Auf diese Weise können Sie die Erstellung der Instanz steuern. Dies kann in verschiedenen Szenarien nützlich sein, unter anderem in Fällen, in denen Ihr Singleton mit Backend-Komponenten kommunizieren muss.

Diese Funktion benötigt die Parameter ` moduleName ` und ` typeName `, um den Singleton-Typ anzugeben, den Sie festlegen möchten, sowie den einzustellenden ` instance `. Der Typ muss bereits als QML-Singleton-Typ registriert sein, idealerweise mithilfe von ` QML_ELEMENT ` und `QML_SINGLETON`. Falls das Modul noch nicht geladen wurde, wird es nun geladen.

Die Funktion gibt bei Erfolg „true“ und bei einem Fehler „false“ zurück. Tritt ein Fehler auf, wird eine Warnung ausgegeben, die den Fehler detailliert beschreibt.

Beispielsweise benötigt das Singleton möglicherweise einen Backend-Dienst, um zu funktionieren, und könnte dann wie folgt deklariert werden:

class CppSingleton: public QObject {
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
    QML_UNCREATABLE("Provided via QQmlEngine::setExternalSingletonInstance")
    // Q_PROPERTY(...)
public:
    explicit CppSingleton(BackendService *service); // constructor taking a reference to something MySingleton needs
    // members, Q_INVOKABLE functions, etc.
};

Bei der Initialisierung der Anwendung können Sie dann Folgendes tun:

    // create and setup the backend service
    BackendService service;

    // create your singleton instance
    CppSingleton singleton(&service);
    QQmlApplicationEngine engine;
    engine.setExternalSingletonInstance("com.company.myApp", "MySingleton", &singleton);
    engine.loadFromModule("com.company.myApp", "Main");

Beachten Sie, dass anstelle eines Standardkonstruktors oder einer statischen `create`-Funktion das Makro ` QML_UNCREATABLE()` verwendet wurde, um anzugeben, dass dieses Element nicht von der QML-Engine erstellt werden kann.

Singleton-Instanzen können pro Typ und Engine nur einmal festgelegt werden und müssen vor jeglicher Verwendung festgelegt werden. Sobald eine Singleton-Instanz erstellt oder festgelegt wurde, ist es nicht mehr möglich, sie mit dieser Funktion festzulegen; daher sollten Sie die Instanzen festlegen, bevor sie zum ersten Mal aus QML heraus verwendet werden.

Die Engine übernimmt nicht die Verantwortung für die von Ihnen übergebene Instanz, es sei denn, Sie weisen die Engine explizit dazu an, indem Sie ` QJSEngine::setObjectOwnership()` verwenden.

Diese Funktion wurde in Qt 6.12 eingeführt.

void QQmlEngine::setImportPathList(const QStringList &paths)

Legt „ paths “ als Liste der Verzeichnisse fest, in denen die Engine in einer URL-basierten Verzeichnisstruktur nach installierten Modulen sucht. Qt geht davon aus, dass alle Dateien und Ordner unter „ paths “ aus einer vertrauenswürdigen Quelle stammen.

Standardmäßig enthält diese Liste die unter „QML-Importpfad“ angegebenen Pfade.

Siehe auch „ importPathList()“ und „ addImportPath()“.

void QQmlEngine::setIncubationController(QQmlIncubationController *controller)

Legt die Inkubations controller en der Engine fest. Die Engine kann nur einen aktiven Controller haben und übernimmt nicht die Verantwortung dafür.

Siehe auch ` incubationController()` .

void QQmlEngine::setNetworkAccessManagerFactory(QQmlNetworkAccessManagerFactory *factory)

Legt die „ factory “ fest, die zum Erstellen von „ QNetworkAccessManager “ verwendet werden soll.

QNetworkAccessManager Wird für den gesamten Netzwerkzugriff durch QML verwendet. Durch die Implementierung einer Factory ist es möglich, benutzerdefinierte „ QNetworkAccessManager “ mit spezieller Caching-, Proxy- und Cookie-Unterstützung zu erstellen.

Die Factory muss vor dem Start der Engine festgelegt werden.

Siehe auch „ networkAccessManagerFactory()“.

void QQmlEngine::setOutputWarningsToStandardError(bool enabled)

Legen Sie fest, ob Warnmeldungen an stderr ausgegeben werden sollen, indem Sie „ enabled “ setzen.

Ist „ enabled “ auf „true“ gesetzt, werden alle von QML generierten Warnmeldungen an „stderr“ ausgegeben und über das Signal „ warnings()“ ausgelöst. Ist „ enabled “ auf „false“ gesetzt, wird nur das Signal „ warnings()“ ausgelöst. Auf diese Weise können Anwendungen die Ausgabe von Warnmeldungen selbst verarbeiten.

Der Standardwert ist „true“.

Siehe auch „ outputWarningsToStandardError()“.

void QQmlEngine::setPluginPathList(const QStringList &paths)

Legt die Liste der Verzeichnisse fest, in denen die Engine nach nativen Plugins für importierte Module (auf die in der Datei „ qmldir “ verwiesen wird) sucht, und zwar unter paths. Qt geht davon aus, dass alle Dateien und Ordner unter paths aus einer vertrauenswürdigen Quelle stammen.

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 von ` QObject` abgeleiteten Typ sein und hängt davon ab, wie das Singleton registriert wurde. Wenn noch keine Instanz von T erstellt wurde, wird sie nun erstellt. Wenn ` qmlTypeId ` keinen gültigen Singleton-Typ darstellt, wird entweder ein standardkonstruiertes ` 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 Element in der Singleton-Klasse. Die Suche über ` qmlTypeId()` ist rechenintensiv.

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

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

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 nur eine einmalige Einrichtung eines Singletons erforderlich ist; falls wiederholter Zugriff auf das Singleton erforderlich ist, ermöglicht das Zwischenspeichern seiner `typeId` einen schnelleren nachfolgenden Zugriff über ` type-id based overload`.

Das Template-Argument `T` kann entweder ` QJSValue ` oder ein Zeiger auf einen von ` QObject` abgeleiteten Typ sein und hängt davon ab, wie das Singleton registriert wurde. Wenn noch keine Instanz von `T` erstellt wurde, wird sie nun erstellt. Wenn ` typeName ` keinen gültigen Singleton-Typ darstellt, wird entweder ein standardkonstruiertes ` 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()

Leert den internen Komponenten-Cache des Motors.

Diese Funktion bewirkt, dass die Metadaten aller geladenen Komponenten, die derzeit nicht verwendet werden, gelöscht werden.

Eine Komponente gilt als in Gebrauch, wenn noch Instanzen der Komponente selbst vorhanden sind, Instanzen anderer Komponenten, die diese Komponente verwenden, oder Objekte, die von einer dieser Komponenten instanziiert wurden.

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 ausgelöst, wenn von QML „ warnings “-Meldungen generiert werden.