ListModel QML Type

Define una fuente de datos de lista de forma libre. Más...

• Lista de todos los miembros, incluidos los heredados

Propiedades

• count : int
• dynamicRoles : bool

Métodos

• 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()

Descripción detallada

El ListModel es un simple contenedor de definiciones ListElement, cada una de las cuales contiene roles de datos. El contenido puede definirse dinámicamente o explícitamente en QML.

El número de elementos del modelo puede obtenerse a partir de su propiedad count. También se proporcionan varios métodos familiares para manipular el contenido del modelo, como append(), insert(), move(), remove() y set(). Estos métodos aceptan diccionarios como argumentos, que el modelo convierte en objetos ListElement.

Los elementos pueden manipularse a través del modelo mediante el método setProperty(), que permite establecer y modificar los roles del elemento especificado.

ListModel hereda de QAbstractListModel y proporciona sus métodos Q_INVOKABLE. Se puede, por ejemplo, utilizar QAbstractItemModel::index para recuperar un QModelIndex para una fila y una columna.

Ejemplo de uso

El siguiente ejemplo muestra un ListModel que contiene tres elementos, con los roles "nombre" y "coste".

import QtQuick

ListModel {
    id: fruitModel

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

Los roles (propiedades) de cada elemento deben empezar por una letra minúscula y deben ser comunes a todos los elementos de un modelo. La documentación de ListElement proporciona más directrices sobre cómo deben definirse los elementos.

Dado que el modelo de ejemplo contiene una propiedad id, puede ser referenciada por vistas, como la ListView de este ejemplo:

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
    }
}

Es posible que los roles contengan datos de lista. En el siguiente ejemplo creamos una lista de atributos de fruta:

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" }
        ]
    }
}

El delegado muestra todos los atributos de la fruta:

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 }
            }
        }
    }
}

Modificación de modelos de lista

El contenido de un ListModel puede crearse y modificarse mediante los métodos clear(), append(), set(), insert() y setProperty(). Por ejemplo:

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

Tenga en cuenta que cuando se crea contenido de forma dinámica, el conjunto de propiedades disponibles no se puede cambiar una vez establecido. Las propiedades que se añadan primero al modelo serán las únicas permitidas en el modelo.

Utilización de modelos de lista enhebrados con WorkerScript

ListModel puede utilizarse junto con WorkerScript para acceder a un modelo de lista desde varios subprocesos. Esto es útil si las modificaciones de la lista son síncronas y llevan algún tiempo: las operaciones de la lista se pueden mover a un subproceso diferente para evitar el bloqueo del subproceso principal de la interfaz gráfica de usuario.

He aquí un ejemplo que utiliza WorkerScript para añadir periódicamente la hora actual a un modelo de lista:

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

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

El archivo incluido, dataloader.mjs, tiene este aspecto:

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
    }
}

El temporizador del ejemplo principal envía mensajes al script trabajador llamando a WorkerScript::sendMessage(). Cuando se recibe este mensaje, WorkerScript.onMessage() es invocado en dataloader.mjs, que añade la hora actual al modelo de lista.

Observe la llamada a sync() desde el hilo externo. Debe llamar a sync() o de lo contrario los cambios realizados en la lista desde ese hilo no se reflejarán en el modelo de lista en el hilo principal.

Véase también Modelos de datos y Qt Qml.

Documentación de propiedades

count : int [read-only]

El número de entradas de datos en el modelo.

dynamicRoles : bool

Por defecto, el tipo de un rol se fija la primera vez que se utiliza el rol. Por ejemplo, si creas un rol llamado "datos" y le asignas un número, ya no podrás asignar una cadena al rol "datos". Sin embargo, cuando la propiedad dynamicRoles está activada, el tipo de un rol dado no es fijo y puede ser diferente entre elementos.

La propiedad dynamicRoles debe establecerse antes de añadir ningún dato a ListModel, y debe establecerse desde el hilo principal.

Un ListModel que tenga datos definidos estáticamente (mediante la sintaxis QML de ListElement ) no puede tener activada la propiedad dynamicRoles.

El uso de ListModel con roles dinámicos habilitados tiene un coste de rendimiento significativo. El coste varía de una plataforma a otra, pero suele ser entre 4 y 6 veces más lento que el uso de tipos de rol estáticos.

Debido al coste de rendimiento del uso de roles dinámicos, están desactivados por defecto.

Documentación del método

void append(jsobject dict)

Añade un nuevo elemento al final del modelo de lista, con los valores de dict.

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

Véase también set() y remove().

void clear()

Elimina todo el contenido del modelo. En particular, esto invalida todos los objetos que puedas haber recuperado utilizando get().

Véase también append(), remove() y get().

object get(int index)

Devuelve el elemento en index en el modelo de lista. Esto permite acceder a los datos del elemento o modificarlos desde JavaScript:

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

El index debe ser un elemento de la lista.

Tenga en cuenta que las propiedades del objeto devuelto que sean a su vez objetos también serán modelos, y que este método get() se utiliza para acceder a los elementos:

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

Véase también append() y clear().

void insert(int index, jsobject dict)

Añade un nuevo elemento al modelo de lista en la posición index, con los valores de dict.

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

El index debe ser a un elemento existente en la lista, o uno pasado el final de la lista (equivalente a append).

Véase también set() y append().

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

Mueve n elementos from una posición to otra.

Los rangos desde y hasta deben existir; por ejemplo, para mover los 3 primeros elementos al final de la lista:

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

Véase también append().

void remove(int index, int count = 1)

Elimina count número de elementos en index del modelo.

Véase también clear().

void set(int index, jsobject dict)

Cambia el elemento en index en el modelo de lista con los valores en dict. Las propiedades que no aparecen en dict no se modifican.

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

Si index es igual a count() entonces se añade un nuevo elemento a la lista. En caso contrario, index debe ser un elemento de la lista.

Véase también append().

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

Cambia el property del elemento en index en el modelo de lista a value.

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

El index debe ser un elemento de la lista.

Véase también append().

void sync()

Escribe cualquier cambio no guardado en el modelo de lista después de que haya sido modificado desde un script de trabajador.