QQmlComponent Class

Documentation des fonctions membres

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

Créez un QQmlComponent sans données et donnez-lui les valeurs spécifiées engine et parent. Définissez les données à l'aide de setData().

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

Crée un QQmlComponent à partir de l'adresse fileName et lui attribue les adresses parent et engine.

Voir aussi loadUrl().

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

Créer un QQmlComponent à partir de l'adresse url et lui donner les adresses parent et engine.

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

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

Voir aussi loadUrl().

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

Créer un QQmlComponent à partir de fileName et lui donner les adresses parent et engine. Si mode est Asynchronous, le composant sera chargé et compilé de manière asynchrone.

Voir aussi loadUrl().

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

Créer un QQmlComponent à partir de l'adresse url et lui donner les adresses parent et engine. 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() pour charger un fichier à partir du système de fichiers local.

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

Voir aussi loadUrl().

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

Créer un QQmlComponent à partir des éléments uri et typeName et lui donner les éléments parent et engine. Si possible, le composant sera chargé de manière synchrone.

Cette fonction a été introduite dans Qt 6.5.

Voir aussi loadFromModule().

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

Créer un QQmlComponent à partir des éléments uri et typeName et lui donner les éléments parent et engine. Si mode est Asynchronous, le composant sera chargé et compilé de manière asynchrone.

Cette fonction a été introduite dans Qt 6.5.

Voir aussi loadFromModule().

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

Détruire le site QQmlComponent.

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

Crée une instance d'objet à partir de ce composant, dans les limites de l'adresse context. Retourne nullptr si la création a échoué.

La construction d'une instance par QQmlComponent s'effectue en trois étapes :

1. La hiérarchie de l'objet 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, QQmlParserStatus::componentComplete() est appelé sur les objets.

QQmlComponent::beginCreate() diffère de QQmlComponent::create() en ce sens qu'il n'exécute que l'étape 1. QQmlComponent::completeCreate() doit être appelé pour compléter les étapes 2 et 3.

Ce point de rupture est parfois utile lorsque l'on utilise des propriétés attaché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 retourné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 général, les programmeurs devraient utiliser QQmlComponent::create() pour créer un composant.

Cette fonction termine la création du composant commencée avec QQmlComponent::beginCreate() et doit être appelée ensuite.

Voir aussi beginCreate().

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

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

Si context est nullptr (par défaut), l'instance sera créée dans le 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éer une instance d'objet à partir de ce composant à l'aide de l'adresse incubator. context indique le contexte dans lequel créer l'instance d'objet.

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

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

L'objet créé et son statut de création sont disponibles via incubator.

Voir également QQmlIncubator.

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

Créer une instance d'objet de ce composant, dans l'espace spécifié context, et initialiser ses propriétés de premier niveau avec initialProperties.

Si l'une des propriétés initialProperties ne peut être définie, un avertissement est émis. Si des propriétés obligatoires ne sont pas définies, la création de l'objet échoue et renvoie nullptr, auquel cas isError() renvoie true.

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

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

Voir aussi QQmlComponent::create.

QQmlContext *QQmlComponent::creationContext() const

Retourne le site QQmlContext dans lequel le composant a été créé. Ceci n'est valable que pour les composants créés directement à partir de QML.

QQmlEngine *QQmlComponent::engine() const

Renvoie l'adresse QQmlEngine 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 isError() n'est pas défini.

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

Retourne vrai si le composant a été créé dans un fichier QML qui spécifie pragma ComponentBehavior: Bound, sinon retourne faux.

Cette fonction a été introduite dans Qt 6.5.

bool QQmlComponent::isError() const

Retourne vrai si status() == QQmlComponent::Error.

bool QQmlComponent::isLoading() const

Retourne vrai si status() == QQmlComponent::Loading.

bool QQmlComponent::isNull() const

Retourne vrai si status() == QQmlComponent::Null.

bool QQmlComponent::isReady() const

Retourne vrai si status() == QQmlComponent::Ready.

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

Charger le QQmlComponent pour typeName dans le module uri. Si le type est implémenté via un fichier QML, mode est utilisé pour le charger. Les types soutenus par 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 aussi loadUrl().

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

Chargez le fichier QQmlComponent à partir de l'adresse url.

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

Les chemins relatifs seront résolus par rapport à QQmlEngine::baseUrl(), qui est le 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)

Charger le QQmlComponent à partir du url fourni. 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() pour charger un fichier à partir du système de fichiers local.

Les chemins relatifs seront résolus par rapport à QQmlEngine::baseUrl(), qui est le 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)

Emis chaque fois que la progression du chargement du composant change. progress sera la progression actuelle entre 0.0 (rien de chargé) et 1.0 (terminé).

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

Configure le QQmlComponent pour qu'il utilise le QML data donné. Si url est fourni, il est utilisé pour définir le nom du composant et pour fournir un chemin de base pour les éléments résolus par ce composant.

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

Définir le niveau supérieur properties du 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 général, les programmeurs devraient utiliser QQmlComponent::createWithInitialProperties pour créer une instance d'objet à partir d'un composant.

Utilisez cette méthode après beginCreate et avant 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 initiales imbriquées. Au lieu de cela, la définition d'une valeur initiale pour les propriétés de type valeur avec des propriétés imbriquées peut être réalisée en créant ce type de valeur, en affectant sa propriété imbriquée et en passant ensuite le type de valeur en tant que propriété initiale de l'objet à construire.

Par exemple, pour définir fond.bold, vous pouvez créer un QFont, définir son poids sur bold, puis passer la police comme propriété initiale.

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

Emis chaque fois que l'état du composant change. status sera le nouvel état.