QQmlEngine Class

Documentation des fonctions membres

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

Créer un nouveau QQmlEngine avec l'adresse parent.

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

Détruit l'objet QQmlEngine.

Tous les QQmlContext créés sur ce moteur seront invalidés, mais pas détruits (sauf s'ils sont liés à l'objet QQmlEngine ).

Voir ~QJSEngine() pour plus de détails sur le nettoyage du moteur JS.

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

Définit l'adresse provider à utiliser pour les images demandées via le schéma image: url, avec l'hôte providerId. L'adresse QQmlEngine est propriétaire de l'adresse provider.

Les fournisseurs d'images permettent de prendre en charge les demandes d'images pixmap et threadées. Voir la documentation de QQuickImageProvider pour plus de détails sur la mise en œuvre et l'utilisation des fournisseurs d'images.

Tous les fournisseurs d'images nécessaires doivent être ajoutés au moteur avant que les fichiers sources QML ne soient chargés.

Voir aussi removeImageProvider(), QQuickImageProvider, et QQmlImageProviderBase.

void QQmlEngine::addImportPath(const QString &path)

Ajoute path comme répertoire dans lequel le moteur recherche les modules installés dans une structure de répertoire basée sur l'URL.

path peut être un répertoire du système de fichiers local, un chemin de ressources Qt (:/imports), une url de ressources Qt (qrc:/imports) ou une URL.

Le path sera converti en forme canonique avant d'être ajouté à la liste des chemins d'importation.

L'adresse path nouvellement ajoutée sera la première dans la liste des adresses importPathList().

Voir aussi setImportPathList(), Modules QML et Chemin d'importation QML.

void QQmlEngine::addPluginPath(const QString &path)

Ajoute path comme répertoire dans lequel le moteur recherche des plugins natifs pour les modules importés (référencés dans le fichier qmldir ).

Par défaut, la liste ne contient que ., c'est-à-dire que le moteur recherche dans le répertoire du fichier qmldir lui-même.

Le fichier path nouvellement ajouté sera le premier dans la liste pluginPathList().

Voir également setPluginPathList().

void QQmlEngine::addUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)

Ajoute une adresse urlInterceptor à utiliser lors de la résolution d'URL en QML. Cela s'applique également aux URL utilisées pour le chargement des fichiers de script et des types QML. Les intercepteurs d'URL ne doivent pas être modifiés pendant que le moteur charge des fichiers, sinon la sélection des URL risque d'être incohérente. Les intercepteurs d'URL multiples, lorsqu'ils sont donnés, seront appelés dans l'ordre dans lequel ils ont été ajoutés pour chaque URL.

QQmlEngine ne prend pas possession de l'intercepteur et ne le supprime pas.

QUrl QQmlEngine::baseUrl() const

Renvoie l'URL de base de ce moteur. L'URL de base n'est utilisée pour résoudre les composants que lorsqu'une URL relative est transmise au constructeur de QQmlComponent.

Si aucune URL de base n'a été explicitement définie, cette méthode renvoie le répertoire de travail actuel de l'application.

Voir aussi setBaseUrl().

void QQmlEngine::clearComponentCache()

Efface le cache interne des composants du moteur.

Cette fonction entraîne la destruction des métadonnées des propriétés de la plupart des composants précédemment chargés par le moteur. Pour ce faire, elle supprime les composants non référencés du cache des composants du moteur. Elle ne supprime pas les composants qui sont encore référencés, car cela conduirait presque certainement à des plantages ultérieurs.

Si aucun composant n'est référencé, cette fonction ramène le moteur à un état où il ne contient aucune donnée de composant chargé. Cela peut être utile pour recharger un sous-ensemble plus petit du jeu de composants précédent, ou pour charger une nouvelle version d'un composant précédemment chargé.

Une fois que le cache des composants a été vidé, les composants doivent être chargés avant que de nouveaux objets puissent être créés.

En règle générale, assurez-vous qu'aucun objet créé à partir de composants QML n'est vivant lorsque vous videz le cache des composants.

Voir également trimComponentCache() et clearSingletons().

void QQmlEngine::clearSingletons()

Efface tous les singletons que le moteur possède.

Cette fonction supprime toutes les instances de singleton, en supprimant tous les QObjects appartenant au moteur parmi eux. Ceci est utile pour s'assurer qu'il ne reste aucun objet créé par QML avant d'appeler clearComponentCache().

Les propriétés QML contenant des instances de singleton basées sur QObject deviennent nulles si le moteur possède le singleton ou conservent leur valeur si le moteur ne le possède pas. Les singletons ne sont pas automatiquement recréés lors de l'accès à des objets QML existants. Les singletons ne sont recréés que lorsque de nouveaux composants sont instanciés.

Voir aussi clearComponentCache().

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

Renvoie le QQmlContext pour le object, ou nullptr si aucun contexte n'a été défini.

Lorsque QQmlEngine instancie un QObject, un contexte interne lui est automatiquement attribué. Ces contextes internes sont en lecture seule. Il n'est pas possible de leur attribuer des propriétés de contexte.

Voir aussi setContextForObject(), qmlContext(), qmlEngine() et QQmlContext::setContextProperty().

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

Réimplémente : QObject::event(QEvent *e).

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

Ce signal est émis lorsque le QML chargé par le moteur souhaite quitter la boucle d'événements avec le code de retour spécifié retCode.

Voir également quit().

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

Renvoie le fournisseur d'images défini pour providerId s'il est trouvé ; sinon, il renvoie nullptr.

Voir aussi QQuickImageProvider.

QStringList QQmlEngine::importPathList() const

Renvoie la liste des répertoires dans lesquels le moteur recherche les modules installés dans une structure de répertoires basée sur l'URL.

Par exemple, si /opt/MyApp/lib/imports figure dans le chemin d'accès, QML qui importe com.mycompany.Feature amènera QQmlEngine à rechercher dans /opt/MyApp/lib/imports/com/mycompany/Feature/ les composants fournis par ce module. Un fichier qmldir est nécessaire pour définir la correspondance entre les versions des types et éventuellement les plugins d'extension QML.

Par défaut, cette liste contient les chemins mentionnés dans Chemin d'importation QML.

Voir également addImportPath() et setImportPathList().

QQmlIncubationController *QQmlEngine::incubationController() const

Renvoie le contrôleur d'incubation actuellement défini, ou 0 si aucun contrôleur n'a été défini.

Voir aussi setIncubationController().

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

Exécute les intercepteurs d'URL actuels sur l'adresse url donnée de l'adresse type donnée et renvoie le résultat.

[since 6.6] void QQmlEngine::markCurrentFunctionAsTranslationBinding()

Si cette méthode est appelée à l'intérieur d'une fonction qui fait partie d'une liaison en QML, la liaison sera traitée comme une liaison de traduction.

class I18nAwareClass : public QObject {

  //...

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

Cette fonction a été introduite dans Qt 6.6.

Voir aussi QQmlEngine::retranslate.

QNetworkAccessManager *QQmlEngine::networkAccessManager() const

Renvoie un QNetworkAccessManager commun qui peut être utilisé par n'importe quel type QML instancié par ce moteur.

Si un QQmlNetworkAccessManagerFactory a été défini et qu'un QNetworkAccessManager n'a pas encore été créé, le QQmlNetworkAccessManagerFactory sera utilisé pour créer le QNetworkAccessManager; sinon, le QNetworkAccessManager retourné n'aura pas de proxy ou de cache défini.

Voir aussi setNetworkAccessManagerFactory().

QQmlNetworkAccessManagerFactory *QQmlEngine::networkAccessManagerFactory() const

Renvoie l'adresse actuelle QQmlNetworkAccessManagerFactory.

Voir aussi setNetworkAccessManagerFactory().

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

Renvoie le chemin d'accès au fichier où se trouve (ou se trouverait) une base de données Local Storage avec l'identifiant databaseName.

Voir aussi LocalStorage.openDatabaseSync().

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

Ce signal est émis lorsque offlineStoragePath est modifié.

Cette fonction a été introduite dans Qt 6.5.

bool QQmlEngine::outputWarningsToStandardError() const

Retourne true si des messages d'avertissement seront émis sur stderr en plus du signal warnings(), sinon false.

La valeur par défaut est true.

Voir aussi setOutputWarningsToStandardError().

QStringList QQmlEngine::pluginPathList() const

Renvoie la liste des répertoires dans lesquels le moteur recherche les plugins natifs des modules importés (référencés dans le fichier qmldir ).

Par défaut, la liste ne contient que ., c'est-à-dire que le moteur recherche dans le répertoire du fichier qmldir lui-même.

Voir aussi addPluginPath() et setPluginPathList().

[signal] void QQmlEngine::quit()

Ce signal est émis lorsque le QML chargé par le moteur souhaite quitter.

Voir aussi exit().

void QQmlEngine::removeImageProvider(const QString &providerId)

Supprime le fournisseur d'images pour providerId.

Voir aussi addImageProvider() et QQuickImageProvider.

void QQmlEngine::removeUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)

Supprimez un urlInterceptor qui a été ajouté précédemment à l'aide de addUrlInterceptor. Les intercepteurs d'URL ne doivent pas être modifiés pendant que le moteur charge des fichiers, sinon la sélection des URL risque d'être incohérente.

Cette opération ne supprime pas l'intercepteur, mais le retire simplement du moteur. Vous pouvez le réutiliser sur le même moteur ou sur un moteur différent par la suite.

[slot] void QQmlEngine::retranslate()

Actualise toutes les expressions de liaison qui utilisent des chaînes de caractères marquées pour la traduction.

Appelez cette fonction après avoir installé un nouveau traducteur à l'adresse QCoreApplication::installTranslator, afin de vous assurer que votre interface utilisateur affiche des traductions à jour.

QQmlContext *QQmlEngine::rootContext() const

Renvoie le contexte racine du moteur.

Le contexte racine est automatiquement créé par QQmlEngine. Les données qui doivent être disponibles pour toutes les instances de composants QML instanciées par le moteur doivent être placées dans le contexte racine.

Les données supplémentaires qui ne doivent être accessibles qu'à un sous-ensemble d'instances de composants doivent être ajoutées aux sous-contextes apparentés au contexte racine.

void QQmlEngine::setBaseUrl(const QUrl &url)

Fixe l'URL de base de ce moteur à url.

Voir aussi baseUrl().

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

Définit le QQmlContext pour le object à context. Si le object a déjà un contexte, un avertissement est émis, mais le contexte n'est pas modifié.

Lorsque QQmlEngine instancie un QObject, le contexte est défini automatiquement.

Voir aussi contextForObject().

void QQmlEngine::setImportPathList(const QStringList &paths)

Définit paths comme la liste des répertoires dans lesquels le moteur recherche les modules installés dans une structure de répertoires basée sur une URL.

Par défaut, cette liste contient les chemins mentionnés dans Chemin d'importation QML.

Voir aussi importPathList() et addImportPath().

void QQmlEngine::setIncubationController(QQmlIncubationController *controller)

Définit l'incubation du moteur controller. Le moteur ne peut avoir qu'un seul contrôleur actif et il n'en prend pas possession.

Voir aussi incubationController().

void QQmlEngine::setNetworkAccessManagerFactory(QQmlNetworkAccessManagerFactory *factory)

Définit l'adresse factory à utiliser pour créer QNetworkAccessManager(s).

QNetworkAccessManager est utilisé pour tous les accès réseau par QML. En mettant en œuvre une fabrique, il est possible de créer des QNetworkAccessManager personnalisés avec une mise en cache spécialisée, un proxy et une prise en charge des cookies.

La fabrique doit être définie avant d'exécuter le moteur.

Voir aussi networkAccessManagerFactory().

void QQmlEngine::setOutputWarningsToStandardError(bool enabled)

Indiquer si les messages d'avertissement seront émis sur stderr à enabled.

Si enabled est vrai, tous les messages d'avertissement générés par QML seront affichés sur stderr et émis par le signal warnings(). Si enabled est faux, seul le signal warnings() sera émis. Cela permet aux applications de gérer elles-mêmes les messages d'avertissement.

La valeur par défaut est true.

Voir aussi outputWarningsToStandardError().

void QQmlEngine::setPluginPathList(const QStringList &paths)

Définit la liste des répertoires dans lesquels le moteur recherche des plugins natifs pour les modules importés (référencés dans le fichier qmldir ) à paths.

Par défaut, la liste ne contient que ., c'est-à-dire que le moteur recherche dans le répertoire du fichier qmldir lui-même.

Voir également pluginPathList() et addPluginPath().

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

Renvoie l'instance d'un type singleton qui a été enregistré sous qmlTypeId.

L'argument de modèle T peut être QJSValue ou un pointeur vers un type dérivé de QObject et dépend de la manière dont le singleton a été enregistré. Si aucune instance de T n'a encore été créée, elle est créée maintenant. Si qmlTypeId ne représente pas un type singleton valide, une construction par défaut QJSValue ou une nullptr est renvoyée.

QObject* exemple :

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

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

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

Il est recommandé de stocker l'identifiant du type QML, par exemple en tant que membre statique de la classe singleton. La recherche via qmlTypeId() est coûteuse.

Voir aussi QML_SINGLETON, qmlRegisterSingletonType(), et qmlTypeId().

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

Renvoie l'instance d'un type singleton nommé typeName à partir du module spécifié par uri.

Cette méthode peut être utilisée comme alternative à l'appel de qmlTypeId suivi de la surcharge de singletonInstance basée sur l'identifiant. Cette méthode est pratique lorsqu'il s'agit de configurer un singleton une seule fois ; si un accès répété au singleton est nécessaire, la mise en cache de son typeId permettra un accès ultérieur plus rapide par l'intermédiaire de type-id based overload.

L'argument de modèle T peut être QJSValue ou un pointeur vers un type dérivé de QObject et dépend de la manière dont le singleton a été enregistré. Si aucune instance de T n'a encore été créée, elle est créée maintenant. Si typeName ne représente pas un type de singleton valide, une construction par défaut QJSValue ou nullptr est renvoyée.

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

Cette fonction a été introduite dans Qt 6.5.

Voir aussi QML_SINGLETON, qmlRegisterSingletonType(), et qmlTypeId().

void QQmlEngine::trimComponentCache()

Réduit le cache interne des composants du moteur.

Cette fonction détruit les métadonnées des propriétés de tous les composants chargés qui ne sont pas actuellement utilisés.

Un composant est considéré comme utilisé s'il existe des instances du composant lui-même, des instances d'autres composants qui utilisent le composant ou des objets instanciés par l'un de ces composants.

Voir également clearComponentCache().

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

Renvoie la liste des intercepteurs d'URL actuellement actifs.

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

Ce signal est émis lorsque des messages warnings sont générés par QML.