QQmlEngine Class

Documentation des fonctions membres

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

Créer un nouvel objet QQmlEngine avec l'parent fournie.

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

Supprime l'QQmlEngine.

Toutes les instances d'QQmlContext créées sur ce moteur seront invalidées, mais pas détruites (à moins qu'elles ne soient rattachées à 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'provider à utiliser pour les images demandées via le schéma d'URL « image: », avec l'hôte providerId. L'QQmlEngine prend en charge provider.

Les fournisseurs d’images permettent la prise en charge des requêtes d’images pixmap et en thread. Consultez la documentation d’ QQuickImageProvider pour plus de détails sur l’implémentation et l’utilisation des fournisseurs d’images.

Tous les fournisseurs d’images requis doivent être ajoutés au moteur avant le chargement de tout fichier source QML.

Voir également removeImageProvider(), QQuickImageProvider et QQmlImageProviderBase.

void QQmlEngine::addImportPath(const QString &path)

Ajoute path en tant que répertoire dans lequel le moteur recherche les modules installés au sein d'une structure de répertoires basée sur des URL. Qt part du principe que tous les fichiers et dossiers situés sous path proviennent d'une source fiable.

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

L’ path sera convertie en forme canonique avant d’être ajoutée à la liste des chemins d’importation.

L'path nouvellement ajouté figurera en première position dans la fonction importPathList().

Voir également ` setImportPathList()`, Modules QML et Chemin d'importation QML

void QQmlEngine::addPluginPath(const QString &path)

Ajoute path comme répertoire dans lequel le moteur recherche les plugins natifs pour les modules importés (référencés dans le fichier qmldir ). Qt part du principe que tous les fichiers et dossiers situés sous path proviennent d'une source fiable.

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

Le fichier « path » nouvellement ajouté figurera en première position dans la liste pluginPathList().

Voir également setPluginPathList().

void QQmlEngine::addUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)

Ajoute un intercepteur d'URL ( urlInterceptor ) à utiliser lors de la résolution des URL dans QML. Cela s'applique également aux URL utilisées pour charger des fichiers de script et des types QML. Les intercepteurs d'URL ne doivent pas être modifiés pendant que le moteur charge les fichiers, sous peine de rendre la sélection des URL incohérente. Si plusieurs intercepteurs d'URL sont définis, ils 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 sert uniquement à résoudre les composants lorsqu'une URL relative est transmise au constructeur 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()

Vide le cache des composants internes du moteur.

Cette fonction entraîne la destruction des métadonnées de propriété 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 de composants du moteur. Elle ne supprime pas les composants qui sont encore référencés, car cela entraînerait presque certainement des plantages par la suite.

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ée. Cela peut s’avérer utile pour recharger un sous-ensemble plus restreint de l’ensemble de composants précédent, ou pour charger une nouvelle version d’un composant précédemment chargé.

Une fois le cache des composants 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 ne soit encore actif lorsque vous videz le cache des composants.

Voir également trimComponentCache() et clearSingletons().

void QQmlEngine::clearSingletons()

Supprime tous les singletons gérés par le moteur.

Cette fonction supprime toutes les instances de singleton, en effaçant notamment tous les QObjects détenus par le moteur. Cela permet de s'assurer qu'aucun objet créé par QML ne subsiste avant d'appeler clearComponentCache().

Les propriétés QML contenant des instances de singleton basées sur ` QObject` prennent la valeur `null` si le moteur possède le singleton, ou conservent leur valeur si ce n’est pas le cas. Les singletons ne sont pas automatiquement recréés lors de l’accès à des objets existants créés par QML. Ce n’est que lorsque de nouveaux composants sont instanciés que les singletons sont recréés.

Voir également clearComponentCache().

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

Renvoie l'QQmlContext correspondant à l'object, ou nullptr si aucun contexte n'a été défini.

Lorsque l'QQmlEngine instancie un QObject, un contexte interne lui est automatiquement attribué. Ces contextes internes sont en lecture seule. Vous ne pouvez pas leur définir de propriétés de contexte.

Voir également 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 sortir de 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 existe ; sinon, renvoie nullptr.

Voir également QQuickImageProvider.

QStringList QQmlEngine::importPathList() const

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

Par exemple, si /opt/MyApp/lib/imports figure dans le chemin d'accès, alors un fichier QML qui importe com.mycompany.Feature entraînera la recherche par le moteur QQmlEngine dans /opt/MyApp/lib/imports/com/mycompany/Feature/ des composants fournis par ce module. Un fichier qmldir est nécessaire pour définir le mappage des versions de types et, éventuellement, les plugins d'extensions 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 également setIncubationController().

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

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

[since 6.6] void QQmlEngine::markCurrentFunctionAsTranslationBinding()

Si cette méthode est appelée à l'intérieur d'une fonction faisant partie d'un lien dans QML, ce lien sera traité comme un lien 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 également « QQmlEngine::retranslate ».

QNetworkAccessManager *QQmlEngine::networkAccessManager() const

Renvoie une instance d'QNetworkAccessManager, qui peut être utilisée par n'importe quel type QML instancié par ce moteur.

Si une QQmlNetworkAccessManagerFactory a été définie et qu’aucun QNetworkAccessManager n’a encore été créé, l’ QQmlNetworkAccessManagerFactory sera utilisé pour créer l’ QNetworkAccessManager; sinon, l’ QNetworkAccessManager renvoyé n’aura ni proxy ni cache défini.

Voir également setNetworkAccessManagerFactory().

QQmlNetworkAccessManagerFactory *QQmlEngine::networkAccessManagerFactory() const

Renvoie l'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 » portant l'identifiant « databaseName ».

Voir également LocalStorage.openDatabaseSync().

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

Ce signal est émis lorsque la propriété offlineStoragePath change.

Cette fonction a été introduite dans Qt 6.5.

bool QQmlEngine::outputWarningsToStandardError() const

Renvoie « true » si les messages d'avertissement doivent être affichés sur stderr en plus d'être émis par le 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 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 effectue la recherche dans le répertoire du fichier qmldir lui-même.

Voir également addPluginPath() et setPluginPathList().

[signal] void QQmlEngine::quit()

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

Voir également exit().

void QQmlEngine::removeImageProvider(const QString &providerId)

Supprime le fournisseur d'images pour providerId.

Voir également addImageProvider() et QQuickImageProvider.

void QQmlEngine::removeUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)

Supprimer un « urlInterceptor » précédemment ajouté à l'aide de ` addUrlInterceptor`. Les intercepteurs d'URL ne doivent pas être modifiés pendant que le moteur charge des fichiers, sous peine de rendre la sélection des URL incohérente.

Cette opération ne supprime pas l'intercepteur, mais se contente de le retirer du moteur. Vous pourrez le réutiliser par la suite sur le même moteur ou sur un autre.

[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'aide de ` 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 la méthode ` QQmlEngine`. Les données qui doivent être accessibles à 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 à des sous-contextes rattachés au contexte racine.

void QQmlEngine::setBaseUrl(const QUrl &url)

Définissez l'URL de base de ce moteur sur url.

Voir également baseUrl().

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

Définit l'QQmlContext de l'object sur context. Si l'object dispose déjà d'un contexte, un avertissement est affiché, mais le contexte n'est pas modifié.

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

Voir également contextForObject().

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

Définit l'instance singleton à utiliser pour le type donné sur le moteur QML.

Cette fonction vous permet de définir manuellement une instance dérivée de ` QObject` à utiliser comme singleton dans QML pour ce moteur. Cela vous permet de contrôler la création de l’instance. Cela peut s’avérer utile dans plusieurs scénarios, notamment lorsque votre singleton doit communiquer avec des composants backend.

Cette fonction prend en paramètre les objets ` moduleName ` et ` typeName ` pour indiquer le type de singleton que vous essayez de définir, ainsi que l'objet ` instance ` à définir. Le type doit déjà être enregistré en tant que type de singleton QML, idéalement à l'aide de ` QML_ELEMENT ` et `QML_SINGLETON`. Si le module n'a pas encore été chargé, il le sera à ce moment-là.

La fonction renvoie `true` en cas de succès ou `false` en cas d’échec. En cas d’échec, un avertissement détaillant l’erreur est émis.

À titre d’exemple, le singleton peut nécessiter un service backend pour fonctionner, et pourrait alors être déclaré comme suit :

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.
};

Lors de l’initialisation de l’application, vous pouvez alors procéder ainsi :

    // 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");

Notez qu’au lieu de fournir un constructeur par défaut ou une fonction de création statique, la macro ` QML_UNCREATABLE()` a été utilisée pour indiquer que cet élément ne peut pas être créé par le moteur QML.

Les instances singleton ne peuvent être définies qu’une seule fois par type et par moteur, et doivent l’être avant toute utilisation. Une fois qu’une instance singleton est créée ou définie, il n’est plus possible de la définir à l’aide de cette fonction ; vous devez donc définir les instances avant leur première utilisation depuis QML.

Le moteur ne prendra pas possession de l’instance que vous lui transmettez, à moins que vous ne lui en donniez explicitement l’instruction à l’aide de QJSEngine::setObjectOwnership().

Cette fonction a été introduite dans Qt 6.12.

void QQmlEngine::setImportPathList(const QStringList &paths)

Définit ` paths ` comme la liste des répertoires dans lesquels le moteur recherche les modules installés au sein d’une structure de répertoires basée sur des URL. Qt part du principe que tous les fichiers et dossiers situés sous ` paths ` proviennent d’une source fiable.

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

Voir également « importPathList() » et « addImportPath() ».

void QQmlEngine::setIncubationController(QQmlIncubationController *controller)

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

Voir également incubationController().

void QQmlEngine::setNetworkAccessManagerFactory(QQmlNetworkAccessManagerFactory *factory)

Définit l'factory à utiliser pour créer une ou plusieurs instances de ` QNetworkAccessManager`.

QNetworkAccessManager Il est utilisé pour tous les accès réseau effectués par QML. En implémentant une fabrique, il est possible de créer des objets ` QNetworkAccessManager ` personnalisés avec une prise en charge spécialisée de la mise en cache, des proxys et des cookies.

La classe de fabrication doit être définie avant l'exécution du moteur.

Voir aussi networkAccessManagerFactory().

void QQmlEngine::setOutputWarningsToStandardError(bool enabled)

Définissez si les messages d'avertissement doivent être envoyés vers stderr en définissant enabled.

Si enabled est défini sur true, tous les messages d’avertissement générés par QML seront envoyés vers stderr et émis par le signal warnings(). Si enabled est défini sur false, seul le signal warnings() sera émis. Cela permet aux applications de gérer elles-mêmes l’affichage des avertissements.

La valeur par défaut est « true ».

Voir également ` outputWarningsToStandardError()`.

void QQmlEngine::setPluginPathList(const QStringList &paths)

Définit la liste des répertoires dans lesquels le moteur recherche les plugins natifs pour les modules importés (référencés dans le fichier qmldir ) sur paths. Qt part du principe que tous les fichiers et dossiers situés sous paths proviennent d'une source fiable.

Par défaut, la liste ne contient que ., c'est-à-dire que le moteur effectue ses recherches 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 enregistré sous qmlTypeId.

L'argument de modèle T peut être soit QJSValue, soit 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 à ce moment-là. Si qmlTypeId ne représente pas un type singleton valide, soit un QJSValue construit par défaut, soit un nullptr est renvoyé.

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 dans la classe singleton. La recherche via qmlTypeId() est coûteuse.

Voir également 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 » issu 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. Cela s’avère pratique lorsqu’il suffit de configurer un singleton une seule fois ; si des accès répétés au singleton sont nécessaires, la mise en cache de son `typeId` permettra des accès ultérieurs plus rapides via ` type-id based overload`.

L’argument de modèle T peut être soit QJSValue, soit un pointeur vers un type dérivé de QObject, selon la manière dont le singleton a été enregistré. Si aucune instance de T n’a encore été créée, elle est créée à ce moment-là. Si typeName ne représente pas un type de singleton valide, soit un QJSValue construit par défaut, soit un nullptr est renvoyé.

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

Cette fonction a été introduite dans Qt 6.5.

Voir également QML_SINGLETON, qmlRegisterSingletonType() et qmlTypeId().

void QQmlEngine::trimComponentCache()

Vide le cache des composants internes du moteur.

Cette fonction entraîne la destruction des métadonnées de propriété 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 existantes du composant lui-même, des instances d'autres composants qui utilisent ce 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.