Component QML Type

Encapsule une définition de composant QML. En savoir plus…

• Liste de tous les membres, y compris les membres hérités

Propriétés

• progress : real
• status : enumeration
• url : url

Signaux associés

• completed()
• destruction()

Méthodes

• QtObject createObject(QtObject parent, var properties)
• string errorString()
• var incubateObject(QtObject parent, var properties, enumeration mode)

Description détaillée

Les composants sont des types QML réutilisables et encapsulés, dotés d'interfaces bien définies.

Les composants sont souvent définis par des fichiers de composants, c'est-à-dire des fichiers « .qml ». Le type Component permet essentiellement de définir des composants QML en ligne, au sein d’un document QML, plutôt que dans un fichier QML distinct. Cela peut s’avérer utile pour réutiliser un petit composant au sein d’un fichier QML, ou pour définir un composant qui appartient logiquement à d’autres composants QML au sein d’un même fichier.

Par exemple, voici un composant utilisé par plusieurs objets ` Loader `. Il contient un seul élément, un ` Rectangle` :

import QtQuick

Item {
    width: 100; height: 100

    Component {
        id: redSquare

        Rectangle {
            color: "red"
            width: 10
            height: 10
        }
    }

    Loader { sourceComponent: redSquare }
    Loader { sourceComponent: redSquare; x: 20 }
}

Notez que, alors qu’un objet ` Rectangle ` serait automatiquement rendu et affiché s’il était isolé, ce n’est pas le cas du rectangle ci-dessus, car il est défini à l’intérieur d’un ` Component`. Le composant encapsule les types QML qu’il contient, comme s’ils étaient définis dans un fichier QML distinct, et n’est chargé qu’à la demande (dans ce cas, par les deux objets ` Loader `). Comme la classe `Component` n’est pas dérivée de la classe `Item`, il n’est pas possible d’y ancrer quoi que ce soit.

La définition d’un « Component » s’apparente à celle d’un document QML. Un document QML comporte un seul élément de niveau supérieur qui définit le comportement et les propriétés de ce composant, et ne peut définir ni propriétés ni comportement en dehors de cet élément de niveau supérieur. De la même manière, une définition de « Component » contient un seul élément de niveau supérieur (qui, dans l’exemple ci-dessus, est un « Rectangle ») et ne peut définir aucune donnée en dehors de cet élément, à l’exception d’un identifiant (qui, dans l’exemple ci-dessus, est « redSquare »).

Le type « Component » est couramment utilisé pour fournir des composants graphiques aux vues. Par exemple, la propriété « ListView::delegate » nécessite un « Component » pour spécifier la manière dont chaque élément de la liste doit être affiché.

Component Les objets peuvent également être créés dynamiquement à l’aide de ` Qt.createComponent()`.

ComponentLes s sont utiles pour déclarer un type lorsque vous n’avez besoin que d’une instance de ce type sans avoir à ajouter un tout nouveau fichier. Cependant, vous ne pouvez pas nommer ce type et, par conséquent, vous ne pouvez pas l’utiliser pour déclarer une propriété ni l’utiliser dans une annotation de type. Si vous en avez besoin, privilégiez l’utilisation de composants en ligne.

Contexte de création

Le contexte de création d’un composant correspond au contexte dans lequel le composant a été déclaré. Ce contexte sert de contexte parent (créant une hiérarchie de contextes) lorsque le composant est instancié par un objet tel qu’un ` ListView ` ou un `Loader`.

Dans l’exemple suivant, comp1 est créé dans le contexte racine de MyItem.qml, et tous les objets instanciés à partir de ce composant auront accès aux identifiants et aux propriétés de ce contexte, tels que internalSettings.color. Lorsque ` comp1 ` est utilisé comme délégué ` ListView ` dans un autre contexte (comme dans `main.qml` ci-dessous), il continuera d’avoir accès aux propriétés de son contexte de création (qui seraient autrement privées pour les utilisateurs externes).

Item {
    property Component mycomponent: comp1

    QtObject {
        id: internalSettings
        property color color: "green"
    }

    Component {
        id: comp1
        Rectangle { color: internalSettings.color; width: 400; height: 50 }
    }
}

ListView {
    width: 400; height: 400
    model: 5
    delegate: myItem.mycomponent    //will create green Rectangles

    MyItem { id: myItem }
}

Il est important que la durée de vie du contexte de création soit plus longue que celle de tous les objets créés. Voir Gestion des objets créés dynamiquement pour plus de détails.

Documentation sur les propriétés

progress : real [read-only]

La progression du chargement du composant, de 0,0 (rien n'est chargé) à 1,0 (chargement terminé).

status : enumeration [read-only]

Cette propriété indique l'état de chargement du composant. L'état peut prendre l'une des valeurs suivantes :

url : url [read-only]

L'URL du composant. Il s'agit de l'URL qui a été utilisée pour créer le composant.

Documentation relative aux signaux associés

[attached] completed()

Émis une fois l’objet instancié. Cela permet d’exécuter du code de script au démarrage, une fois que l’environnement QML complet a été mis en place.

Le gestionnaire de signal ` onCompleted ` peut être déclaré sur n'importe quel objet. L'ordre d'exécution des gestionnaires n'est pas défini.

Rectangle {
    Component.onCompleted: console.log("Completed Running!")
    Rectangle {
        Component.onCompleted: console.log("Nested Completed Running!")
    }
}

[attached] destruction()

Émis lorsque l'objet commence à être détruit. Cela peut être utilisé pour annuler les opérations effectuées en réponse au signal ` completed()` ou à tout autre code impératif de votre application.

Le gestionnaire de signal onDestruction peut être déclaré sur n'importe quel objet. L'ordre d'exécution des gestionnaires n'est pas défini.

Rectangle {
    Component.onDestruction: console.log("Destruction Beginning!")
    Rectangle {
        Component.onDestruction: console.log("Nested Destruction Beginning!")
    }
}

Voir aussi Qt Qml.

Documentation des méthodes

QtObject createObject(QtObject parent, var properties)

Crée et renvoie une instance d'objet de ce composant qui possédera les propriétés ` parent ` et ` properties` spécifiées. L'argument ` properties ` est facultatif. Renvoie `null` si la création de l'objet échoue.

L'objet sera créé dans le même contexte que celui dans lequel le composant a été créé. Cette fonction renvoie toujours `null` lorsqu'elle est appelée sur des composants qui n'ont pas été créés en QML.

Si vous souhaitez créer un objet sans définir de parent, spécifiez ` null ` comme valeur de ` parent `. Notez que si l'objet renvoyé doit être affiché, vous devez fournir une valeur valide pour ` parent ` ou définir la propriété ` parent ` de l'objet renvoyé, sinon l'objet ne sera pas visible.

Si aucun parent n’est fourni à createObject(), une référence à l’objet renvoyé doit être conservée afin qu’il ne soit pas détruit par le ramasse-miettes. Cela vaut quel que soit le fait que Item::parent soit défini par la suite, car la définition du parent Item ne modifie pas la propriété de l’objet. Seul le parent graphique est modifié.

Cette méthode accepte un argument facultatif ` properties ` qui spécifie une carte des valeurs initiales des propriétés de l’objet créé. Ces valeurs sont appliquées avant que la création de l’objet ne soit finalisée. Cette approche est plus efficace que de définir les valeurs des propriétés après la création de l’objet, en particulier lorsque de grands ensembles de valeurs de propriétés sont définis, et permet également de configurer des liaisons de propriétés (à l’aide de ` Qt.binding`) avant la création de l’objet.

L’argument ` properties ` est spécifié sous la forme d’une carte d’éléments propriété-valeur. Par exemple, le code ci-dessous crée un objet dont les valeurs initiales de ` x ` et ` y ` sont respectivement 100 et 100 :

const component = Qt.createComponent("Button.qml");
if (component.status === Component.Ready) {
    component.createObject(parent, { x: 100, y: 100 });
}

Les instances créées dynamiquement peuvent être supprimées à l’aide de la méthode ` destroy() `. Pour plus d’informations, consultez la section Création dynamique d’objets QML à partir de JavaScript.

Voir également incubateObject().

string errorString()

Renvoie une description lisible par l'utilisateur de toute erreur.

La chaîne de caractères comprend le nom du fichier, son emplacement et la description de chaque erreur. S'il y a plusieurs erreurs, elles sont séparées par un caractère de nouvelle ligne.

S'il n'y a pas d'erreurs, une chaîne vide est renvoyée.

var incubateObject(QtObject parent, var properties, enumeration mode)

Crée un incubateur pour une instance de ce composant. Les incubateurs permettent d'instancier de nouvelles instances de composants de manière asynchrone, sans provoquer de blocage de l'interface utilisateur.

L'argument ` parent ` spécifie le parent de l'instance créée. Si ce paramètre est omis ou si la valeur `null` est transmise, un objet sans parent sera créé. Dans ce cas, une référence à l'objet créé doit être conservée afin qu'il ne soit pas détruit par le ramasse-miettes.

L’argument ` properties ` est spécifié sous la forme d’une carte d’éléments propriété-valeur qui seront attribués à l’objet créé lors de sa construction. ` mode ` peut prendre la valeur `Qt.Synchronous` ou `Qt.Asynchronous` et détermine si l’instance est créée de manière synchrone ou asynchrone. La valeur par défaut est « asynchrone ». Dans certaines circonstances, même si Qt.Synchronous est spécifié, l’incubateur peut créer l’objet de manière asynchrone. Cela se produit si le composant appelant incubateObject() est lui-même créé de manière asynchrone.

Les trois arguments sont facultatifs.

En cas de succès, la méthode renvoie un incubateur, sinon elle renvoie null. L’incubateur possède les propriétés suivantes :

• status - L'état de l'incubateur. Les valeurs valides sont Component.Ready, Component.Loading et Component.Error.
• object - L’instance de l’objet créé. Elle ne sera disponible que lorsque l’incubateur aura atteint l’état Ready.
• onStatusChanged - Spécifie une fonction de rappel à invoquer lorsque l'état change. L'état est transmis en tant que paramètre à la fonction de rappel.
• forceCompletion() - Appel permettant de terminer l'incubation de manière synchrone.

L'exemple suivant montre comment utiliser un incubateur :

const component = Qt.createComponent("Button.qml");

const incubator = component.incubateObject(parent, { x: 10, y: 10 });
if (incubator.status !== Component.Ready) {
    incubator.onStatusChanged = function(status) {
        if (status === Component.Ready) {
            print("Object", incubator.object, "is now ready!");
        }
    };
} else {
    print("Object", incubator.object, "is ready immediately!");
}

Les instances créées dynamiquement peuvent être supprimées à l'aide de la méthode ` destroy() `. Pour plus d'informations, consultez la section Création dynamique d'objets QML à partir de JavaScript.

Voir également createObject().