Component QML Type

Encapsule une définition de composant QML. Plus d'informations...

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

Propriétés

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

Signaux attachés

• completed()
• destruction()

Méthodes

• QtObject createObject(QtObject parent, object properties)
• string errorString()
• object incubateObject(QtObject parent, object 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 Composant 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 être utile pour réutiliser un petit composant dans un fichier QML, ou pour définir un composant qui appartient logiquement à d'autres composants QML dans un 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 }
}

Remarquez que si un Rectangle est automatiquement rendu et affiché, 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 ). Le composant n'étant pas dérivé de l'élément, il n'est pas possible d'y ancrer quoi que ce soit.

La définition d'un site Component est similaire à celle d'un document QML. Un document QML possède un seul élément de premier niveau qui définit le comportement et les propriétés de ce composant, et ne peut pas définir de propriétés ou de comportement en dehors de cet élément de premier niveau. De la même manière, une définition Component contient un seul élément de premier niveau (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 comment chaque élément de la liste doit être affiché.

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

ComponentLes objets de type s sont utiles pour déclarer un type dont vous n'avez besoin que d'une instance sans avoir à ajouter un nouveau fichier entier. Cependant, vous ne pouvez pas nommer ce type et par conséquent vous ne pouvez pas l'utiliser pour déclarer une propriété ou l'utiliser dans une annotation de type. Si vous avez besoin de cela, préférez l'utilisation de composants inline.

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 est utilisé comme contexte parent (créant une hiérarchie de contexte) lorsque le composant est instancié par un objet tel que ListView ou 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é de ListView dans un autre contexte (comme dans main.qml ci-dessous), il continue à 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 supérieure à celle des objets créés. Pour plus de détails, voir Gestion des objets créés dynamiquement.

Documentation sur les propriétés

progress : real [read-only]

La progression du chargement du composant, de 0.0 (rien chargé) à 1.0 (terminé).

status : enumeration [read-only]

Cette propriété indique l'état de chargement du composant. L'état peut être l'un des suivants

url : url [read-only]

L'URL du composant. Il s'agit de l'URL utilisée pour construire le composant.

Documentation sur les signaux attachés

completed()

Émise après l'instanciation de l'objet. Il peut être utilisé pour exécuter un code de script au démarrage, une fois que l'environnement QML complet a été établi.

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!")
    }
}

destruction()

Emis lorsque l'objet commence à être détruit. Ce signal peut être utilisé pour annuler le travail effectué en réponse au signal completed(), ou tout autre code impératif dans 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, object properties)

Crée et renvoie une instance d'objet de ce composant qui aura les valeurs données parent et properties. L'argument properties est facultatif. Retourne 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, indiquez null pour la valeur parent. Notez que si l'objet retourné doit être affiché, vous devez fournir une valeur parent valide ou définir la propriété parent de l'objet retourné, sinon l'objet ne sera pas visible.

Si une valeur parent n'est pas fournie à createObject(), une référence à l'objet retourné doit être conservée afin qu'il ne soit pas détruit par le ramasse-miettes. Cela est vrai même si Item::parent est défini par la suite, car le fait de définir le parent de l'élément 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 méthode est plus efficace que la définition des valeurs de propriété après la création de l'objet, en particulier lorsque de grands ensembles de valeurs de propriété sont définis, et elle permet également de définir les liaisons de propriété (à 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 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(). Voir Création dynamique d'objets QML à partir de JavaScript pour plus d'informations.

Voir également incubateObject().

string errorString()

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

La chaîne comprend le fichier, l'emplacement et la description de chaque erreur. Si plusieurs erreurs sont présentes, elles sont séparées par un caractère de retour à la ligne.

Si aucune erreur n'est présente, une chaîne vide est renvoyée.

object incubateObject(QtObject parent, object 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 et n'entraînent pas de gel de l'interface utilisateur.

L'argument parent spécifie le parent de l'instance créée. L'omission du paramètre ou la transmission de null créera un objet sans parent. 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é comme une carte d'éléments propriété-valeur qui seront définis sur l'objet créé pendant sa construction. mode peut être Qt.Synchronous ou Qt.Asynchronous, et contrôle 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éé. L'instance de l'objet créé ne sera disponible que lorsque l'incubateur sera dans l'état Prêt.
• onStatusChanged - Spécifie une fonction de rappel à invoquer lorsque le statut change. Le statut est transmis en tant que paramètre à la fonction de rappel.
• forceCompletion() - Appel pour 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(). Voir Création dynamique d'objets QML à partir de JavaScript pour plus d'informations.

Voir aussi createObject().