ListModel QML Type

Définit une source de données sous forme de liste libre. Plus...

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

Propriétés

• count : int
• dynamicRoles : bool

Méthodes

• void append(jsobject dict)
• void clear()
• object get(int index)
• void insert(int index, jsobject dict)
• void move(int from, int to, int n)
• void remove(int index, int count)
• void set(int index, jsobject dict)
• void setProperty(int index, string property, var value)
• void sync()

Description détaillée

Le modèle ListModel est un simple conteneur de définitions ListElement, chacune contenant des rôles de données. Le contenu peut être défini dynamiquement ou explicitement en langage QML.

Le nombre d'éléments dans le modèle peut être obtenu à partir de sa propriété count. Un certain nombre de méthodes familières sont également fournies pour manipuler le contenu du modèle, notamment append(), insert(), move(), remove() et set(). Ces méthodes acceptent des dictionnaires comme arguments ; ceux-ci sont traduits en objets ListElement par le modèle.

Les éléments peuvent être manipulés via le modèle à l'aide de la méthode setProperty(), qui permet de définir et de modifier les rôles de l'élément spécifié.

ListModel hérite de QAbstractListModel et fournit ses méthodes Q_INVOKABLE. Vous pouvez, par exemple, utiliser QAbstractItemModel::index pour récupérer QModelIndex pour une ligne et une colonne.

Exemple d'utilisation

L'exemple suivant montre un ListModel contenant trois éléments, avec les rôles "name" et "cost".

import QtQuick

ListModel {
    id: fruitModel

    ListElement {
        name: "Apple"
        cost: 2.45
    }
    ListElement {
        name: "Orange"
        cost: 3.25
    }
    ListElement {
        name: "Banana"
        cost: 1.95
    }
}

Les rôles (propriétés) de chaque élément doivent commencer par une lettre minuscule et doivent être communs à tous les éléments d'un modèle. La documentation de ListElement fournit davantage de lignes directrices sur la manière dont les éléments doivent être définis.

Comme le modèle de l'exemple contient une propriété id, celle-ci peut être référencée par des vues, telles que ListView dans cet exemple :

import QtQuick

Rectangle {
    width: 200; height: 200

    ListModel {
        id: fruitModel
        ...
    }

    Component {
        id: fruitDelegate
        Row {
            spacing: 10
            Text { text: name }
            Text { text: '$' + cost }
        }
    }

    ListView {
        anchors.fill: parent
        model: fruitModel
        delegate: fruitDelegate
    }
}

Les rôles peuvent contenir des données de type liste. Dans l'exemple suivant, nous créons une liste d'attributs de fruits :

ListModel {
    id: fruitModel

    ListElement {
        name: "Apple"
        cost: 2.45
        attributes: [
            ListElement { description: "Core" },
            ListElement { description: "Deciduous" }
        ]
    }
    ListElement {
        name: "Orange"
        cost: 3.25
        attributes: [
            ListElement { description: "Citrus" }
        ]
    }
    ListElement {
        name: "Banana"
        cost: 1.95
        attributes: [
            ListElement { description: "Tropical" },
            ListElement { description: "Seedless" }
        ]
    }
}

Le délégué affiche tous les attributs des fruits :

Component {
    id: fruitDelegate
    Item {
        width: 200; height: 50
        Text { id: nameField; text: name }
        Text { text: '$' + cost; anchors.left: nameField.right }
        Row {
            anchors.top: nameField.bottom
            spacing: 5
            Text { text: "Attributes:" }
            Repeater {
                model: attributes
                Text { text: description }
            }
        }
    }
}

Modification des modèles de liste

Le contenu d'un modèle de liste peut être créé et modifié à l'aide des méthodes clear(), append(), set(), insert() et setProperty(). Par exemple, le contenu d'un modèle de liste peut être créé et modifié à l'aide des méthodes suivantes

    Component {
        id: fruitDelegate
        Item {
            width: 200; height: 50
            Text { text: name }
            Text { text: '$' + cost; anchors.right: parent.right }

            // Double the price when clicked.
            MouseArea {
                anchors.fill: parent
                onClicked: fruitModel.setProperty(index, "cost", cost * 2)
            }
        }
    }

Notez que lors de la création dynamique de contenu, l'ensemble des propriétés disponibles ne peut pas être modifié une fois qu'il a été défini. Les propriétés ajoutées en premier au modèle sont les seules autorisées dans le modèle.

Utilisation de modèles de liste avec WorkerScript

ListModel peut être utilisé avec WorkerScript pour accéder à un modèle de liste à partir de plusieurs threads. Ceci est utile si les modifications de liste sont synchrones et prennent un certain temps : les opérations de liste peuvent être déplacées vers un autre thread pour éviter le blocage du thread principal de l'interface graphique.

Voici un exemple qui utilise WorkerScript pour ajouter périodiquement l'heure actuelle à un modèle de liste :

        Timer {
            id: timer
            interval: 2000; repeat: true
            running: true
            triggeredOnStart: true

            onTriggered: {
                var msg = {'action': 'appendCurrentTime', 'model': listModel};
                worker.sendMessage(msg);
            }
        }

Le fichier inclus, dataloader.mjs, se présente comme suit :

WorkerScript.onMessage = function(msg) {
    if (msg.action == 'appendCurrentTime') {
        var data = {'time': new Date().toTimeString()};
        msg.model.append(data);
        msg.model.sync();   // updates the changes to the list
    }
}

La minuterie de l'exemple principal envoie des messages au script de travailleur en appelant WorkerScript::sendMessage(). Lorsque ce message est reçu, WorkerScript.onMessage() est invoqué dans dataloader.mjs, qui ajoute l'heure actuelle au modèle de liste.

Notez l'appel à sync() depuis le thread externe. Vous devez appeler sync(), sinon les modifications apportées à la liste à partir de ce thread ne seront pas reflétées dans le modèle de liste du thread principal.

Voir aussi Modèles de données et Qt Qml.

Documentation sur les propriétés

count : int [read-only]

Le nombre d'entrées de données dans le modèle.

dynamicRoles : bool

Par défaut, le type d'un rôle est fixé lors de sa première utilisation. Par exemple, si vous créez un rôle appelé "data" et que vous lui attribuez un numéro, vous ne pouvez plus attribuer une chaîne de caractères au rôle "data". Toutefois, lorsque la propriété dynamicRoles est activée, le type d'un rôle donné n'est pas fixe et peut être différent d'un élément à l'autre.

La propriété dynamicRoles doit être définie avant que des données ne soient ajoutées au site ListModel et doit être définie à partir du fil d'exécution principal.

La propriété dynamicRoles ne peut pas être activée sur un site ListModel dont les données sont définies de manière statique (via la syntaxe QML ListElement ).

L'utilisation d'un site ListModel dont les rôles dynamiques sont activés a un coût important en termes de performances. Ce coût varie d'une plateforme à l'autre, mais il est généralement de 4 à 6 fois plus lent que l'utilisation de types de rôles statiques.

En raison du coût de performance lié à l'utilisation des rôles dynamiques, ceux-ci sont désactivés par défaut.

Documentation de la méthode

void append(jsobject dict)

Ajoute un nouvel élément à la fin du modèle de liste, avec les valeurs indiquées dans dict.

fruitModel.append({"cost": 5.95, "name":"Pizza"})

Voir également set() et remove().

void clear()

Supprime tout le contenu du modèle. En particulier, cela invalide tous les objets que vous avez pu récupérer en utilisant get().

Voir également append(), remove() et get().

object get(int index)

Renvoie l'élément à l'adresse index dans le modèle de liste. Cela permet d'accéder aux données de l'élément ou de les modifier à partir de JavaScript :

Component.onCompleted: {
    fruitModel.append({"cost": 5.95, "name":"Jackfruit"});
    console.log(fruitModel.get(0).cost);
    fruitModel.get(0).cost = 10.95;
}

L'adresse index doit être un élément de la liste.

Notez que les propriétés de l'objet retourné qui sont elles-mêmes des objets seront également des modèles, et que cette méthode get() est utilisée pour accéder aux éléments :

fruitModel.append(..., "attributes":
    [{"name":"spikes","value":"7mm"},
     {"name":"color","value":"green"}]);
fruitModel.get(0).attributes.get(1).value; // == "green"

Voir également append() et clear().

void insert(int index, jsobject dict)

Ajoute un nouvel élément au modèle de liste à la position index, avec les valeurs de dict.

fruitModel.insert(2, {"cost": 5.95, "name":"Pizza"})

L'adresse index doit correspondre à un élément existant de la liste ou à un élément situé après la fin de la liste (équivalent à append).

Voir également set() et append().

void move(int from, int to, int n)

Déplace les éléments n from d'une position to d'une autre.

Les plages de et à doivent exister ; par exemple, pour déplacer les 3 premiers éléments à la fin de la liste :

fruitModel.move(0, fruitModel.count - 3, 3)

Voir aussi append().

void remove(int index, int count = 1)

Supprime count le nombre d'éléments à index du modèle.

Voir aussi clear().

void set(int index, jsobject dict)

Modifie l'élément à index dans le modèle de liste avec les valeurs à dict. Les propriétés qui n'apparaissent pas dans dict restent inchangées.

fruitModel.set(3, {"cost": 5.95, "name":"Pizza"})

Si index est égal à count(), un nouvel élément est ajouté à la liste. Sinon, index doit être un élément de la liste.

Voir également append().

void setProperty(int index, string property, var value)

Change le property de l'élément situé à index dans le modèle de liste en value.

fruitModel.setProperty(3, "cost", 5.95)

Le index doit être un élément de la liste.

Voir aussi append().

void sync()

Écrit toutes les modifications non enregistrées dans le modèle de liste après qu'il a été modifié à partir d'un script de travailleur.