ListModel QML Type

Définit une source de données de type « liste libre ». En savoir 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()
• var 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 ListModel est un simple conteneur de définitions d'ListElement, chacune contenant des rôles de données. Le contenu peut être défini de manière dynamique ou explicitement en QML.

Le nombre d'éléments du modèle peut être obtenu à partir de sa propriété ` count `. Plusieurs méthodes courantes 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 convertis 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 une ` 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 d’ ListElement fournit davantage de recommandations sur la manière de définir les éléments.

Comme le modèle d’exemple contient une propriété « id », il peut être référencé par des vues, telles que la vue « 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 ListModel peut être créé et modifié à l’aide des méthodes clear(), append(), set(), insert() et setProperty(). Par exemple :

    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 plus être modifié une fois défini. Seules les propriétés ajoutées en premier au modèle sont autorisées dans celui-ci.

Utilisation des modèles de liste multithread avec WorkerScript

ListModel peut être utilisé conjointement avec WorkerScript pour accéder à un modèle de liste à partir de plusieurs threads. Cela s’avère utile si les modifications apportées à la liste sont synchrones et prennent un certain temps : les opérations sur la liste peuvent être déplacées vers un autre thread afin d’éviter de bloquer le 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
    }
}

Dans l’exemple principal, le minuteur envoie des messages au script de travail en appelant ` WorkerScript::sendMessage()`. Lorsque ce message est reçu, la fonction ` WorkerScript.onMessage() ` est appelée dans ` dataloader.mjs`, ce 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 depuis ce thread ne seront pas répercutées dans le modèle de liste du thread principal.

Voir également 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 défini de manière fixe dès sa première utilisation. Par exemple, si vous créez un rôle nommé « data » et que vous lui attribuez un nombre, vous ne pouvez plus attribuer de 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 figé et peut varier d’un élément à l’autre.

La propriété `dynamicRoles` doit être définie avant l’ajout de toute donnée à l’ ListModel, et doit l’être à partir du thread principal.

Un ListModel dont les données sont définies de manière statique (via la syntaxe QML ` ListElement `) ne peut pas avoir la propriété `dynamicRoles` activée.

L’utilisation d’un « ListModel » avec les rôles dynamiques activés entraîne un coût de performance important. Ce coût varie d’une plateforme à l’autre, mais il est généralement de l’ordre de 4 à 6 fois plus lent que l’utilisation de types de rôles statiques.

En raison de ce coût en termes de performances, les rôles dynamiques sont désactivés par défaut.

Documentation des méthodes

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. Cela invalide notamment tous les objets que vous avez éventuellement récupérés à l'aide de la fonction ` get()`.

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

var get(int index)

Renvoie l'élément situé à 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'index doit être un élément de la liste.

Notez que les propriétés de l’objet renvoyé 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 contenues dans dict.

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

index doit correspondre à un élément existant de la liste, ou à un élément situé au-delà de la fin de la liste (ce qui équivaut à une ajout à la fin).

Voir également set() et append().

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

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

Les plages « from » et « to » 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 nombre d'éléments à l'adresse index du modèle.

Voir également clear().

void set(int index, jsobject dict)

Modifie l'élément situé à l'adresse index dans le modèle de liste en lui attribuant les valeurs contenues dans 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)

Modifie l'property de l'élément situé à l'adresse index dans le modèle de liste pour le remplacer par value.

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

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

Voir également append().

void sync()

Enregistre toutes les modifications non sauvegardées dans le modèle de liste après qu'il a été modifié à partir d'un script de traitement.