QQmlComponent Class

Documentation des fonctions membres

QQmlComponent::QQmlComponent(QQmlEngine *engine, QObject *parent = nullptr)

Créez un QQmlComponent sans données et attribuez-lui les propriétés engine et parent. Définissez les données à l'aide de la méthode setData().

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QString &fileName, QObject *parent = nullptr)

Créez un QQmlComponent à partir de l'fileName fournie et attribuez-lui les valeurs spécifiées pour parent et engine.

Voir également loadUrl().

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QUrl &url, QObject *parent = nullptr)

Créez un QQmlComponent à partir de l'url fournie et attribuez-lui les paramètres parent et engine spécifiés.

Assurez-vous que l'URL fournie est complète et correcte ; en particulier, utilisez QUrl::fromLocalFile() lorsque vous chargez un fichier à partir du système de fichiers local.

Les chemins relatifs seront résolus par rapport à QQmlEngine::baseUrl(), qui correspond au répertoire de travail actuel sauf indication contraire.

Voir également loadUrl().

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QString &fileName, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

Crée un QQmlComponent à partir de l'fileName fourni et lui attribue les valeurs spécifiées pour parent et engine. Si mode vaut Asynchronous, le composant sera chargé et compilé de manière asynchrone.

Voir également loadUrl().

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QUrl &url, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

Créez un QQmlComponent à partir de l'url fournie et attribuez-lui les paramètres parent et engine spécifiés. Si mode est Asynchronous, le composant sera chargé et compilé de manière asynchrone.

Assurez-vous que l’URL fournie est complète et correcte ; en particulier, utilisez ` QUrl::fromLocalFile()` lorsque vous chargez un fichier à partir du système de fichiers local.

Les chemins relatifs seront résolus par rapport à QQmlEngine::baseUrl(), qui correspond au répertoire de travail actuel sauf indication contraire.

Voir également loadUrl().

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

Crée un QQmlComponent à partir des paramètres uri et typeName fournis, et lui attribue les valeurs spécifiées pour parent et engine. Si possible, le composant sera chargé de manière synchrone.

Cette fonction a été introduite dans Qt 6.5.

Voir également loadFromModule().

[explicit, since 6.5] QQmlComponent::QQmlComponent(QQmlEngine *engine, QAnyStringView uri, QAnyStringView typeName, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

Crée un QQmlComponent à partir des paramètres fournis uri et typeName, et lui attribue les valeurs spécifiées parent et engine. Si mode vaut Asynchronous, le composant sera chargé et compilé de manière asynchrone.

Cette fonction a été introduite dans Qt 6.5.

Voir également loadFromModule().

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

Détruisez l'QQmlComponent.

[virtual] QObject *QQmlComponent::beginCreate(QQmlContext *context)

Crée une instance d'objet à partir de ce composant, dans l'context spécifiée. Renvoie « nullptr » si la création a échoué.

Lorsque QQmlComponent construit une instance, cela se déroule en trois étapes :

1. La hiérarchie des objets est créée et des valeurs constantes sont attribuées.
2. Les liaisons de propriétés sont évaluées pour la première fois.
3. Le cas échéant, la méthode ` QQmlParserStatus::componentComplete()` est appelée sur les objets.

La méthode `QQmlComponent::beginCreate()` diffère de ` QQmlComponent::create()` en ce qu’elle n’effectue que l’étape 1. La méthode ` QQmlComponent::completeCreate()` doit être appelée pour mener à bien les étapes 2 et 3.

Ce point de rupture est parfois utile lors de l’utilisation de propriétés associées pour communiquer des informations à un composant instancié, car il permet de configurer leurs valeurs initiales avant que les liaisons de propriétés ne prennent effet.

La propriété de l’instance d’objet renvoyée est transférée à l’appelant.

Voir également ` completeCreate()` et ` QQmlEngine::ObjectOwnership`.

[virtual] void QQmlComponent::completeCreate()

Cette méthode offre un contrôle avancé sur la création d'instances de composants. En règle générale, les programmeurs doivent utiliser la fonction QQmlComponent::create() pour créer un composant.

Cette fonction finalise la création du composant lancée par QQmlComponent::beginCreate() et doit être appelée par la suite.

Voir également beginCreate().

[virtual] QObject *QQmlComponent::create(QQmlContext *context = nullptr)

Crée une instance d'objet à partir de ce composant, dans l'context spécifiée. Renvoie « nullptr » si la création a échoué.

Si context est nullptr (valeur par défaut), l’instance sera créée dans l’ root context du moteur.

La propriété de l’instance d’objet renvoyée est transférée à l’appelant.

Si l’objet créé à partir de ce composant est un élément visuel, il doit avoir un parent visuel, qui peut être défini en appelant QQuickItem::setParentItem(). Voir Concepts - Parent visuel dans Qt Quick pour plus de détails.

Voir également QQmlEngine::ObjectOwnership.

void QQmlComponent::create(QQmlIncubator &incubator, QQmlContext *context = nullptr, QQmlContext *forContext = nullptr)

Créez une instance d'objet à partir de ce composant à l'aide de la méthode incubator fournie. context spécifie le contexte dans lequel l'instance d'objet doit être créée.

Si context est nullptr (valeur par défaut), l’instance sera créée dans l’ root context du moteur.

forContext Spécifie un contexte dont dépend la création de cet objet. Si l’ forContext est créé de manière asynchrone et que le QQmlIncubator::IncubationMode est QQmlIncubator::AsynchronousIfNested, cet objet sera également créé de manière asynchrone. Si forContext est nullptr (par défaut), le context sera utilisé pour prendre cette décision.

L'objet créé et son état de création sont accessibles via la méthode incubator.

Voir également QQmlIncubator.

QObject *QQmlComponent::createWithInitialProperties(const QVariantMap &initialProperties, QQmlContext *context = nullptr)

Créez une instance de cet objet, dans l'context spécifiée, et initialisez ses propriétés de premier niveau à l'aide de initialProperties.

Si l’une des propriétés de ` initialProperties ` ne peut pas être définie, un avertissement est émis. S’il existe des propriétés obligatoires non définies, la création de l’objet échoue et renvoie ` nullptr` ; dans ce cas, la méthode ` isError()` renverra ` true`.

Si context est défini sur nullptr (valeur par défaut), l’instance sera créée dans l’espace de noms root context du moteur.

La propriété de l’instance d’objet renvoyée est transférée à l’appelant.

Voir également QQmlComponent::create.

QQmlContext *QQmlComponent::creationContext() const

Renvoie l'QQmlContext e dans laquelle le composant a été créé. Cela ne s'applique qu'aux composants créés directement à partir de QML.

QQmlEngine *QQmlComponent::engine() const

Renvoie l'QQmlEngine ion de ce composant.

QList<QQmlError> QQmlComponent::errors() const

Renvoie la liste des erreurs survenues lors de la dernière opération de compilation ou de création. Une liste vide est renvoyée si la fonction ` isError()` n'est pas définie.

[since 6.5] bool QQmlComponent::isBound() const

Renvoie « true » si le composant a été créé dans un fichier QML spécifiant ` pragma ComponentBehavior: Bound`, sinon renvoie « false ».

Cette fonction a été introduite dans Qt 6.5.

bool QQmlComponent::isError() const

Renvoie « true » si status() == QQmlComponent::Error.

bool QQmlComponent::isLoading() const

Renvoie « true » si ` status()` == ` QQmlComponent::Loading`.

bool QQmlComponent::isNull() const

Renvoie « true » si ` status()` == ` QQmlComponent::Null`.

bool QQmlComponent::isReady() const

Renvoie « true » si ` status()` == ` QQmlComponent::Ready`.

[slot, since 6.5] void QQmlComponent::loadFromModule(QAnyStringView uri, QAnyStringView typeName, QQmlComponent::CompilationMode mode = PreferSynchronous)

Chargez l'QQmlComponent e de typeName dans le module uri. Si le type est implémenté via un fichier QML, la fonction mode est utilisée pour le charger. Les types implémentés en C++ sont toujours chargés de manière synchrone.

QQmlEngine engine;
QQmlComponent component(&engine);
component.loadFromModule("QtQuick", "Item");
// once the component is ready
std::unique_ptr<QObject> item(component.create());
Q_ASSERT(item->metaObject() == &QQuickItem::staticMetaObject);

Cette fonction a été introduite dans Qt 6.5.

Voir également loadUrl().

[slot] void QQmlComponent::loadUrl(const QUrl &url)

Chargez le fichier « QQmlComponent » à partir de l'URL fournie : url.

Assurez-vous que l'URL fournie est complète et correcte ; en particulier, utilisez QUrl::fromLocalFile() lorsque vous chargez un fichier à partir du système de fichiers local.

Les chemins relatifs seront résolus par rapport à QQmlEngine::baseUrl(), qui correspond au répertoire de travail actuel sauf indication contraire.

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        qmlComponent, qOverload(&QQmlComponent::loadUrl));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        qmlComponent, [receiver = qmlComponent](const QUrl &url) { receiver->loadUrl(url); });

[slot] void QQmlComponent::loadUrl(const QUrl &url, QQmlComponent::CompilationMode mode)

Chargez le fichier « QQmlComponent » à partir de l'URL fournie : url. Si mode est Asynchronous, le composant sera chargé et compilé de manière asynchrone.

Assurez-vous que l'URL fournie est complète et correcte ; en particulier, utilisez ` QUrl::fromLocalFile()` lorsque vous chargez un fichier à partir du système de fichiers local.

Les chemins relatifs seront résolus par rapport à QQmlEngine::baseUrl(), qui correspond au répertoire de travail actuel sauf indication contraire.

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        qmlComponent, qOverload(&QQmlComponent::loadUrl));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        qmlComponent, [receiver = qmlComponent](const QUrl &url, QQmlComponent::CompilationMode mode) { receiver->loadUrl(url, mode); });

[signal] void QQmlComponent::progressChanged(qreal progress)

Émis chaque fois que la progression du chargement du composant change. progress correspond à la progression actuelle, comprise entre 0,0 (rien de chargé) et 1,0 (chargement terminé).

[slot] void QQmlComponent::setData(const QByteArray &data, const QUrl &url)

Définit l'QQmlComponent e pour qu'il utilise l'data QML spécifiée. Si l'url e est fournie, elle sert à définir le nom du composant et à fournir un chemin de base pour les éléments résolus par ce composant. Le composant sera chargé et compilé de manière synchrone.

void QQmlComponent::setInitialProperties(QObject *object, const QVariantMap &properties)

Définit l'properties de niveau supérieur de l'object, qui a été créé à partir d'un QQmlComponent.

Cette méthode offre un contrôle avancé sur la création d’instances de composants. En règle générale, les programmeurs doivent utiliser la méthode ` QQmlComponent::createWithInitialProperties ` pour créer une instance d’objet à partir d’un composant.

Utilisez cette méthode après l’appel de ` beginCreate ` et avant celui de ` completeCreate `. Si une propriété fournie n’existe pas, un avertissement est émis.

Cette méthode ne permet pas de définir directement des propriétés imbriquées initiales. Pour définir une valeur initiale pour les propriétés de type « value » comportant des propriétés imbriquées, il convient de créer ce type de valeur, d’y attribuer sa propriété imbriquée, puis de transmettre ce type de valeur en tant que propriété initiale de l’objet à construire.

Par exemple, pour définir `fond.bold`, vous pouvez créer une ` QFont`, définir son `weight` sur `bold`, puis transmettre la police en tant que propriété initiale.

[signal] void QQmlComponent::statusChanged(QQmlComponent::Status status)

Émis chaque fois que l'état du composant change. status correspondra au nouvel état.