ListView QML Type

Proporciona una vista de lista de los elementos proporcionados por un modelo. Más...

• Lista de todos los miembros, incluidos los heredados

Propiedades

• add : Transition
• addDisplaced : Transition
• cacheBuffer : int
• count : int
• currentIndex : int
• currentItem : Item
• currentSection : string
• delegate : Component
• delegateModelAccess : enumeration (since 6.10)
• displaced : Transition
• displayMarginBeginning : int (since QtQuick 2.3)
• displayMarginEnd : int (since QtQuick 2.3)
• effectiveLayoutDirection : enumeration
• footer : Component
• footerItem : Item
• footerPositioning : enumeration (since Qt 5.4)
• header : Component
• headerItem : Item
• headerPositioning : enumeration (since Qt 5.4)
• highlight : Component
• highlightFollowsCurrentItem : bool
• highlightItem : Item
• highlightMoveDuration : int
• highlightMoveVelocity : real
• highlightRangeMode : enumeration
• highlightResizeDuration : int
• highlightResizeVelocity : real
• keyNavigationEnabled : bool
• keyNavigationWraps : bool
• layoutDirection : enumeration
• model : model
• move : Transition
• moveDisplaced : Transition
• orientation : enumeration
• populate : Transition
• preferredHighlightBegin : real
• preferredHighlightEnd : real
• remove : Transition
• removeDisplaced : Transition
• reuseItems : bool
• section
  • section.criteria : enumeration
  • section.delegate : Component
  • section.labelPositioning : enumeration
  • section.property : string
• snapMode : enumeration
• spacing : real
• verticalLayoutDirection : enumeration

Propiedades anexas

• delayRemove : bool
• isCurrentItem : bool
• nextSection : string
• previousSection : string
• section : string
• view : ListView

Señales adjuntas

• add()
• pooled()
• remove()
• reused()

Métodos

• void decrementCurrentIndex()
• void forceLayout()
• void incrementCurrentIndex()
• int indexAt(real x, real y)
• Item itemAt(real x, real y)
• Item itemAtIndex(int index)
• void positionViewAtBeginning()
• void positionViewAtEnd()
• void positionViewAtIndex(int index, PositionMode mode)

Descripción detallada

Un ListView muestra datos de modelos creados a partir de tipos QML incorporados como ListModel y XmlListModel, o clases de modelos personalizados definidos en C++ que heredan de QAbstractItemModel o QAbstractListModel.

Un ListView tiene un model, que define los datos que deben mostrarse, y un delegate, que define cómo deben mostrarse los datos. Los elementos de un ListView se disponen horizontal o verticalmente. Las vistas de lista son inherentemente parpadeables porque ListView hereda de Flickable.

Ejemplo de uso

El siguiente ejemplo muestra la definición de un modelo de lista simple definido en un archivo llamado ContactModel.qml:

import QtQuick

ListModel {
    ListElement {
        name: "Bill Smith"
        number: "555 3264"
    }
    ListElement {
        name: "John Brown"
        number: "555 8426"
    }
    ListElement {
        name: "Sam Wise"
        number: "555 0473"
    }
}

Otro componente puede mostrar los datos de este modelo en un ListView, como éste:

import QtQuick

ListView {
    width: 180; height: 200

    model: ContactModel {}
    delegate: Text {
        required property string name
        required property string number
        text: name + ": " + number
    }
}

Aquí, el ListView crea un componente ContactModel para su modelo, y un elemento Text para su delegado. La vista creará un nuevo componente Text para cada elemento del modelo. Observe que el delegado puede acceder directamente a los datos name y number del modelo.

A continuación se muestra una vista de lista mejorada. El delegado se ha mejorado visualmente y se ha trasladado a un componente contactDelegate independiente.

Rectangle {
    width: 180; height: 200

    Component {
        id: contactDelegate
        Item {
            id: myItem
            required property string name
            required property string number
            width: 180; height: 40
            Column {
                Text { text: '<b>Name:</b> ' + myItem.name }
                Text { text: '<b>Number:</b> ' + myItem.number }
            }
        }
    }

    ListView {
        anchors.fill: parent
        model: ContactModel {}
        delegate: contactDelegate
        highlight: Rectangle { color: "lightsteelblue"; radius: 5 }
        focus: true
    }
}

El elemento actualmente seleccionado se resalta con un Rectangle azul utilizando la propiedad highlight, y focus se establece en true para permitir la navegación por teclado para la vista de lista. La propia vista de lista es un ámbito de enfoque (para más información, consulte Enfoque de teclado en Qt Quick ).

Los delegados se instancian según sea necesario y pueden destruirse en cualquier momento. Por lo tanto, state should never be stored in a delegate. Los delegados suelen tener como padre al ListView contentItem, pero normalmente, dependiendo de si es visible en la vista o no, el padre puede cambiar, y a veces ser null. Por ello, no se recomienda enlazar a las propiedades del padre desde el delegado. Si desea que el delegado llene el ancho del ListView, considere utilizar uno de los siguientes enfoques en su lugar:

ListView {
    id: listView
    // ...

    delegate: Item {
        // Incorrect.
        width: parent.width

        // Correct.
        width: listView.width
        width: ListView.view.width
        // ...
    }
}

ListView adjunta una serie de propiedades al elemento raíz del delegado, por ejemplo ListView.isCurrentItem. En el siguiente ejemplo, el elemento raíz del delegado puede acceder directamente a esta propiedad adjunta como ListView.isCurrentItem, mientras que el objeto hijo contactInfo debe hacer referencia a esta propiedad como wrapper.ListView.isCurrentItem.

ListView {
    width: 180; height: 200

    Component {
        id: contactsDelegate
        Rectangle {
            id: wrapper
            width: 180
            height: contactInfo.height
            color: ListView.isCurrentItem ? "black" : "red"
            Text {
                id: contactInfo
                text: name + ": " + number
                color: wrapper.ListView.isCurrentItem ? "red" : "black"
            }
        }
    }

    model: ContactModel {}
    delegate: contactsDelegate
    focus: true
}

Diseños ListView

El diseño de los ítems en un ListView puede ser controlado por estas propiedades:

• orientation - controla si los ítems fluyen horizontal o verticalmente. Este valor puede ser Qt.Horizontal o Qt.Vertical.
• layoutDirection - controla la dirección de la disposición horizontal para una vista orientada horizontalmente: es decir, si los elementos se disponen desde el lado izquierdo de la vista hacia la derecha, o viceversa. Este valor puede ser Qt.LeftToRight o Qt.RightToLeft.
• verticalLayoutDirection - controla la dirección de la disposición vertical para una vista orientada verticalmente: es decir, si los elementos se disponen desde la parte superior de la vista hacia la parte inferior de la vista, o viceversa. Este valor puede ser ListView.TopToBottom o ListView.BottomToTop.

Por defecto, un ListView tiene una orientación vertical, y los elementos se disponen de arriba a abajo. La siguiente tabla muestra los diferentes diseños que puede tener un ListView, dependiendo de los valores de las propiedades listadas anteriormente.

Dirección Flickable

Por defecto, un ListView vertical establece flickableDirection a Flickable.Vertical, y un ListView horizontal lo establece a Flickable.Horizontal. Además, un ListView vertical sólo calcula (estima) el contentHeight, y un ListView horizontal sólo calcula el contentWidth. La otra dimensión se establece en -1.

Desde Qt 5.9 (Qt Quick 2.9), es posible hacer un ListView que pueda ser flickeado en ambas direcciones. Para ello, el flickableDirection se puede establecer a Flickable.AutoFlickDirection o Flickable.AutoFlickIfNeeded, y se debe proporcionar el contentWidth o contentHeight deseado.

ListView {
    width: 180; height: 200

    contentWidth: 320
    flickableDirection: Flickable.AutoFlickDirection

    model: ContactModel {}
    delegate: Row {
        Text { text: '<b>Name:</b> ' + name; width: 160 }
        Text { text: '<b>Number:</b> ' + number; width: 160 }
    }
}

Orden de apilamiento en ListView

La dirección Z value de los elementos determina si se muestran por encima o por debajo de otros elementos. ListView utiliza diferentes valores Z por defecto, dependiendo del tipo de elemento que se esté creando:

Estos valores predeterminados se establecen si el valor Z del elemento es 0, por lo que establecer el valor Z de estos elementos en 0 no tiene ningún efecto. Tenga en cuenta que el valor Z es del tipo real, por lo que es posible establecer valores fraccionarios como 0.1.

Reutilización de elementos

Desde la versión 5.15, ListView puede configurarse para reciclar elementos en lugar de instanciarlos desde delegate cada vez que se muestran nuevas filas. Este enfoque mejora el rendimiento, dependiendo de la complejidad del delegado. La reutilización de elementos está desactivada por defecto (por razones de compatibilidad con versiones anteriores), pero puede activarse estableciendo la propiedad reuseItems en true.

Cuando un elemento se retira, pasa a la reserva de reutilización, que es una caché interna de elementos no utilizados. Cuando esto ocurre, se emite la señal ListView::pooled para informar al elemento de ello. Del mismo modo, cuando el elemento se vuelve a mover desde la reserva, se emite la señal ListView::reused.

Cualquier propiedad del elemento que provenga del modelo se actualiza cuando se reutiliza el elemento. Esto incluye index y row, pero también cualquier rol del modelo.

Si un elemento tiene temporizadores o animaciones, considera ponerlos en pausa al recibir la señal ListView::pooled. De esta forma evitarás utilizar los recursos de la CPU para elementos que no son visibles. Del mismo modo, si un elemento tiene recursos que no se pueden reutilizar, se podrían liberar.

El siguiente ejemplo muestra un delegado que anima un rectángulo giratorio. Cuando se agrupa, la animación se detiene temporalmente:

Component {
    id: listViewDelegate
    Rectangle {
        width: 100
        height: 50

        ListView.onPooled: rotationAnimation.pause()
        ListView.onReused: rotationAnimation.resume()

        Rectangle {
            id: rect
            anchors.centerIn: parent
            width: 40
            height: 5
            color: "green"

            RotationAnimation {
                id: rotationAnimation
                target: rect
                duration: (Math.random() * 2000) + 200
                from: 0
                to: 359
                running: true
                loops: Animation.Infinite
            }
        }
    }
}

Tamaño variable del delegado y etiquetas de sección

Los tamaños variables de los delegados pueden provocar el cambio de tamaño y la omisión de cualquier ScrollBar adjunto. Esto se debe a que ListView estima el tamaño de su contenido a partir de los elementos asignados (normalmente sólo los elementos visibles, el resto se asume que tienen un tamaño similar), y los tamaños de delegado variables impiden una estimación precisa. Para reducir este efecto, cacheBuffer puede ajustarse a valores más altos, creando así más elementos y mejorando la estimación del tamaño de los elementos no asignados, a expensas de un uso adicional de memoria. Sections tiene el mismo efecto porque adjunta y alarga la etiqueta de sección al primer elemento dentro de la sección.

Evite Almacenar Estado en los Delegados

Los delegados de ListView se instancian cuando es necesario y pueden ser destruidos cuando están fuera de vista. Para ilustrar esto, ejecute el siguiente ejemplo:

ListView {
    anchors.fill: parent
    model: 3
    delegate: CheckDelegate {
        text: qsTr("Channel %1").arg(index + 1)

        required property int index
        property bool channelActivated

        onClicked: channelActivated = checked
    }
}

Cuando se hace clic en un elemento, channelActivated se establece en true. Sin embargo, como los delegados pueden ser reused y destruidos, todo el estado se pierde cuando la vista se mueve lo suficiente. Cuando el delegado vuelva a ser visible, tendrá su estado por defecto, sin modificar (o, en el caso de un elemento reutilizado, el estado antiguo de un elemento anterior).

Para evitarlo, el estado debe almacenarse en el modelo:

ListView {
    anchors.fill: parent
    model: ListModel {
        ListElement {
            channelActivated: true
        }
        // ...
    }
    delegate: CheckDelegate {
        text: qsTr("Channel %1").arg(index + 1)
        checked: model.channelActivated

        required property int index
        required property var model

        onClicked: model.channelActivated = checked
    }
}

Ocultar delegados

Al establecer la propiedad visible de un delegado en false se ocultará ese elemento, pero el espacio que ocupaba en la vista permanecerá. Es posible establecer la propiedad height del elemento a 0 (para un ListView vertical ):

ListView {
    anchors.fill: parent
    model: ListModel {
        ListElement { hidden: false }
        ListElement { hidden: false }
        ListElement { hidden: false }
        // ...
    }
    delegate: ItemDelegate {
        text: qsTr("Item %1").arg(index)
        visible: !model.hidden
        height: visible ? implicitHeight : 0

        required property int index
        required property var model

        onClicked: model.hidden = true
    }
}

Tenga en cuenta que el estado oculto se almacena en el modelo, siguiendo el consejo de la sección Avoid Storing State in Delegates.

Sin embargo, si spacing es distinto de cero, habrá espacios desiguales entre los delegados.

Una mejor opción es filtrar tu modelo para que los elementos que no deberían ser visibles no sean cargados por la vista en absoluto. Esto se puede conseguir con QSortFilterProxyModel.

Otra opción es disable el delegado en lugar de ocultarlo.

Ver también Modelos de Datos QML, GridView, PathView, y Qt Quick Ejemplos - Vistas.

Documentación de propiedades

add : Transition

Esta propiedad contiene la transición que se aplicará a los elementos que se añadan a la vista.

Por ejemplo, aquí hay una vista que especifica dicha transición:

ListView {
    ...
    add: Transition {
        NumberAnimation { properties: "x,y"; from: 100; duration: 1000 }
    }
}

Cada vez que se añada un elemento a la vista, el elemento se animará desde la posición (100,100) hasta su posición final x,y dentro de la vista, durante un segundo. La transición sólo se aplica a los nuevos elementos que se añaden a la vista; no se aplica a los elementos de abajo que son desplazados por la adición de los nuevos elementos. Para animar los elementos desplazados, defina las propiedades displaced o addDisplaced.

Para más detalles y ejemplos sobre cómo utilizar las transiciones de vista, consulte la documentación ViewTransition.

Ver también addDisplaced, populate, y ViewTransition.

addDisplaced : Transition

Esta propiedad contiene la transición que se aplicará a los elementos de la vista desplazados por la adición de otros elementos a la vista.

Por ejemplo, aquí hay una vista que especifica una transición de este tipo:

ListView {
    ...
    addDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Cada vez que se añade un elemento a la vista anterior, todos los elementos situados debajo del nuevo elemento se desplazan, haciendo que se muevan hacia abajo (o hacia los lados, si están orientados horizontalmente) dentro de la vista. A medida que se produce este desplazamiento, el movimiento de los elementos a sus nuevas posiciones x,y dentro de la vista se animará mediante un NumberAnimation a lo largo de un segundo, según se especifique. Esta transición no se aplica al nuevo elemento que se ha añadido a la vista; para animar los elementos añadidos, establezca la propiedad add.

Si un elemento es desplazado por varios tipos de operaciones al mismo tiempo, no está definido si se aplicará la transición addDisplaced, moveDisplaced o removeDisplaced. Además, si no es necesario especificar diferentes transiciones en función de si un elemento es desplazado por una operación de añadir, mover o eliminar, considere la posibilidad de establecer la propiedad displaced en su lugar.

Para más detalles y ejemplos sobre cómo utilizar las transiciones de vista, consulte la documentación de ViewTransition.

Véase también displaced, add, populate, y ViewTransition.

cacheBuffer : int

Esta propiedad determina si los delegados se conservan fuera del área visible de la vista.

Si este valor es mayor que cero, la vista puede conservar tantos delegados instanciados como quepan dentro del búfer especificado. Por ejemplo, si en una vista vertical el delegado tiene 20 píxeles de alto y cacheBuffer está ajustado a 40, entonces se podrán crear/conservar hasta 2 delegados por encima y 2 delegados por debajo del área visible. Los delegados en búfer se crean de forma asíncrona, lo que permite que la creación se produzca a lo largo de varios fotogramas y reduce la probabilidad de que se salten fotogramas. Para mejorar el rendimiento de pintado, los delegados fuera del área visible no se pintan.

El valor por defecto de esta propiedad depende de la plataforma, pero normalmente será un valor mayor que cero. Los valores negativos se ignoran.

Tenga en cuenta que cacheBuffer no es un buffer de píxeles - sólo mantiene delegados adicionales instanciados.

El cacheBuffer opera fuera de cualquier margen de visualización especificado por displayMarginBeginning o displayMarginEnd.

count : int [read-only]

La propiedad refleja el número de elementos del modelo de ListView, independientemente de si son visibles o están instanciados como Item de un componente delegado.

La propiedad currentIndex contiene el índice del elemento actual, y currentItem contiene el elemento actual. Establecer currentIndex a -1 borrará el resalte y establecerá currentItem a null.

Si highlightFollowsCurrentItem es true, al establecer cualquiera de estas propiedades se desplazará suavemente ListView para que el elemento actual sea visible.

Tenga en cuenta que la posición del elemento actual sólo puede ser aproximada hasta que se haga visible en la vista.

Como currentItem necesita trabajar con cualquier delegado, su tipo es Item. Sin embargo, a menudo ListView se utiliza con un solo tipo de delegado. En ese caso, la conversión de currentItem al tipo del delegado puede ayudar a la creación de herramientas y dar lugar a un código más eficiente:

component Message : Item {
    required property string sender
    required property string text
}
ListView {
    id: messageView
    delegate: Message {}
    model: messageModel
}
Button {
    text: "Reply to %1".arg((messageView.currentItem) as Message).sender
}

currentSection : string [read-only]

Esta propiedad contiene la sección que se encuentra actualmente al principio de la vista.

delegate : Component

El delegado proporciona una plantilla que define cada elemento instanciado por la vista. El índice se expone como una propiedad accesible index. Las propiedades del modelo también están disponibles dependiendo del tipo de Modelo de Datos.

El número de objetos y enlaces en el delegado tiene un efecto directo en el rendimiento de la vista. Si es posible, coloque la funcionalidad que no sea necesaria para la visualización normal del delegado en un Loader que pueda cargar componentes adicionales cuando sea necesario.

ListView distribuirá los elementos en función del tamaño del elemento raíz del delegado.

Se recomienda que el tamaño del delegado sea un número entero para evitar la alineación de los elementos por debajo de los píxeles.

La dirección stacking order predeterminada para las instancias de delegado es 1.

Véase también Stacking Order in ListView.

delegateModelAccess : enumeration [since 6.10]

Esta propiedad determina cómo los delegados pueden acceder al modelo.

El valor por defecto es DelegateModel.Qt5ReadWrite.

Esta propiedad se introdujo en Qt 6.10.

Ver también Modelos y Vistas en Qt Quick#CambiandoDatos del Modelo.

displaced : Transition

Esta propiedad contiene la transición genérica que se aplicará a los elementos que hayan sido desplazados por cualquier operación del modelo que afecte a la vista.

Es conveniente para especificar la transición genérica que se aplicará a cualquier elemento desplazado por una operación de añadir, mover o eliminar, sin tener que especificar las propiedades individuales addDisplaced, moveDisplaced y removeDisplaced. Por ejemplo, aquí hay una vista que especifica una transición desplazada:

ListView {
    ...
    displaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Cuando se añade, mueve o elimina un elemento en la vista anterior, los elementos situados debajo se desplazan hacia abajo (o hacia los lados, si están orientados horizontalmente) dentro de la vista. A medida que se produce este desplazamiento, el movimiento de los elementos a sus nuevas posiciones x,y dentro de la vista se animará mediante un NumberAnimation a lo largo de un segundo, según se especifique.

Si una vista especifica esta transición genérica desplazada, así como una transición específica addDisplaced, moveDisplaced o removeDisplaced, se utilizará la transición más específica en lugar de la transición genérica desplazada cuando se produzca la operación correspondiente, siempre que la transición más específica no se haya desactivado (estableciendo enabled en false). Si se ha desactivado, se aplicará la transición genérica desplazada.

Para más detalles y ejemplos sobre cómo utilizar las transiciones de vista, consulte la documentación ViewTransition.

Véase también addDisplaced, moveDisplaced, removeDisplaced, y ViewTransition.

Esta propiedad permite que los delegados se muestren fuera de la geometría de la vista.

Si este valor es distinto de cero, la vista creará delegados adicionales antes del inicio de la vista, o después del final. La vista creará tantos delegados como quepan en el tamaño de píxel especificado.

Por ejemplo, si en una vista vertical el delegado tiene 20 píxeles de alto y displayMarginBeginning y displayMarginEnd están ambos ajustados a 40, entonces se crearán y mostrarán 2 delegados arriba y 2 delegados abajo.

El valor por defecto es 0.

Esta propiedad está pensada para permitir ciertas configuraciones de la interfaz de usuario, y no como una optimización del rendimiento. Si deseas crear delegados fuera de la geometría de la vista por razones de rendimiento, probablemente quieras utilizar la propiedad cacheBuffer en su lugar.

Estas propiedades se introdujeron en QtQuick 2.3.

effectiveLayoutDirection : enumeration [read-only]

Esta propiedad contiene la dirección efectiva del diseño de una lista orientada horizontalmente.

Cuando se utiliza la propiedad adjunta LayoutMirroring::enabled para disposiciones locales, la dirección de la disposición visual de la lista horizontal se reflejará. Sin embargo, la propiedad layoutDirection permanecerá inalterada.

Véase también ListView::layoutDirection y LayoutMirroring.

footer : Component

Esta propiedad contiene el componente que se utilizará como pie de página.

Se crea una instancia del componente pie de página para cada vista. El pie de página se coloca al final de la vista, después de cualquier elemento. La dirección stacking order por defecto es 1.

Véase también header, footerItem, y Stacking Order in ListView.

footerItem : Item [read-only]

Contiene el elemento de pie de página creado a partir del componente footer.

Se crea una instancia del componente pie de página para cada vista. El pie de página se coloca al final de la vista, después de cualquier elemento. El stacking order predeterminado del pie de página es 1.

Véase también footer, headerItem, y Stacking Order in ListView.

footerPositioning : enumeration [since Qt 5.4]

Esta propiedad determina la posición de footer item.

Esta propiedad se introdujo en Qt 5.4.

header : Component

Esta propiedad contiene el componente que se utilizará como cabecera.

Se crea una instancia del componente de cabecera para cada vista. La cabecera se coloca al principio de la vista, antes de cualquier elemento. La cabecera predeterminada stacking order es 1.

Véase también footer, headerItem, y Stacking Order in ListView.

headerItem : Item [read-only]

Contiene el elemento de cabecera creado a partir del componente header.

Se crea una instancia del componente de cabecera para cada vista. La cabecera se coloca al principio de la vista, antes de cualquier elemento. El stacking order predeterminado de la cabecera es 1.

Véase también header, footerItem, y Stacking Order in ListView.

headerPositioning : enumeration [since Qt 5.4]

Esta propiedad determina la posición de header item.

Esta propiedad se introdujo en Qt 5.4.

highlight : Component

Esta propiedad contiene el componente que se utilizará como resaltado.

Se crea una instancia del componente de resaltado para cada lista. La geometría de la instancia del componente resultante es gestionada por la lista para que permanezca con el elemento actual, a menos que la propiedad highlightFollowsCurrentItem sea false. El valor por defecto stacking order del elemento destacado es 0.

Ver también highlightItem, highlightFollowsCurrentItem, Ejemplo de resaltado de ListView, y Stacking Order in ListView.

highlightFollowsCurrentItem : bool

Esta propiedad mantiene si el resaltado es manejado por la vista.

Si esta propiedad es true (el valor por defecto), el resaltado se mueve suavemente para seguir el elemento actual. En caso contrario, la vista no moverá el cursor, y cualquier movimiento deberá ser implementado por el cursor.

Aquí se muestra un elemento destacado con su movimiento definido por un elemento SpringAnimation:

Component {
    id: highlight
    Rectangle {
        width: 180; height: 40
        color: "lightsteelblue"; radius: 5
        y: list.currentItem.y
        Behavior on y {
            SpringAnimation {
                spring: 3
                damping: 0.2
            }
        }
    }
}

ListView {
    id: list
    width: 180; height: 200
    model: ContactModel {}
    delegate: Text { text: name }

    highlight: highlight
    highlightFollowsCurrentItem: false
    focus: true
}

Tenga en cuenta que la animación del resalte también afecta a la forma en que se desplaza la vista. Esto se debe a que la vista se desplaza para mantener el resalte dentro del rango de resalte preferido (o ventana visible).

Véase también highlight y highlightMoveVelocity.

highlightItem : Item [read-only]

Contiene el elemento destacado creado a partir del componente highlight.

El highlightItem es gestionado por la vista a menos que highlightFollowsCurrentItem se establezca en false. El stacking order predeterminado del elemento destacado es 0.

Véase también highlight, highlightFollowsCurrentItem, y Stacking Order in ListView.

Estas propiedades controlan la velocidad de las animaciones de movimiento y cambio de tamaño para el delegado de resaltado.

highlightFollowsCurrentItem debe ser true para que estas propiedades tengan efecto.

El valor por defecto de las propiedades de velocidad es 400 píxeles/segundo. El valor por defecto de las propiedades de duración es -1, es decir, el resaltado tardará el tiempo necesario en moverse a la velocidad establecida.

Estas propiedades tienen las mismas características que SmoothedAnimation: si se establecen tanto la velocidad como la duración, la animación utilizará la que proporcione la duración más corta.

Las propiedades de velocidad y duración del movimiento se utilizan para controlar el movimiento debido a cambios de índice; por ejemplo, cuando se llama a incrementCurrentIndex(). Cuando el usuario mueve un ListView, la velocidad del movimiento se utiliza para controlar el movimiento.

Para establecer sólo una propiedad, la otra puede establecerse en -1. Por ejemplo, si sólo quieres animar la duración y no la velocidad, utiliza el siguiente código:

highlightMoveDuration: 1000
highlightMoveVelocity: -1

Ver también highlightFollowsCurrentItem.

Estas propiedades definen el rango preferido del resalte (para el elemento actual) dentro de la vista. El valor preferredHighlightBegin debe ser menor que el valor preferredHighlightEnd.

Estas propiedades afectan a la posición del elemento actual cuando se desplaza la lista. Por ejemplo, si el elemento seleccionado actualmente debe permanecer en el centro de la lista cuando se desplaza la vista, establezca los valores preferredHighlightBegin y preferredHighlightEnd en las coordenadas superior e inferior de donde estaría el elemento central. Si currentItem se cambia mediante programación, la lista se desplazará automáticamente para que el elemento actual se encuentre en el centro de la vista. Además, el comportamiento del índice del elemento actual se producirá tanto si existe un resaltado como si no.

Los valores válidos para highlightRangeMode son:

keyNavigationEnabled : bool

Esta propiedad mantiene si la navegación por teclado de la lista está habilitada.

Si es true, el usuario puede navegar por la vista con el teclado. Es útil para aplicaciones que necesitan habilitar o deshabilitar selectivamente la interacción con el ratón y el teclado.

Por defecto, el valor de esta propiedad está vinculado a interactive para garantizar la compatibilidad de comportamiento de las aplicaciones existentes. Cuando se establezca explícitamente, dejará de estar vinculada a la propiedad interactive.

Véase también interactive.

keyNavigationWraps : bool

Esta propiedad indica si la lista envuelve la navegación por teclas.

Si esto es cierto, la navegación por teclas que movería la selección del elemento actual más allá del final de la lista se envuelve y mueve la selección al principio de la lista, y viceversa.

Por defecto, la navegación por teclas no se envuelve.

layoutDirection : enumeration

Esta propiedad contiene la dirección de diseño de una lista orientada horizontalmente.

Valores posibles:

Establecer esta propiedad no tiene efecto si orientation es Qt.Vertical.

Ver también ListView::effectiveLayoutDirection y ListView::verticalLayoutDirection.

model : model

Esta propiedad contiene el modelo que proporciona los datos para la lista.

El modelo proporciona el conjunto de datos que se utiliza para crear los elementos de la vista. Los modelos pueden crearse directamente en QML utilizando ListModel, ObjectModel, o proporcionarse mediante clases de modelos C++. Si se utiliza una clase de modelo C++, debe ser una subclase de QAbstractItemModel o una lista simple.

Véase también Modelos de datos.

move : Transition

Esta propiedad contiene la transición que se aplicará a los elementos de la vista que se están moviendo debido a una operación de movimiento en la vista model.

Por ejemplo, a continuación se muestra una vista que especifica una transición de este tipo:

ListView {
    ...
    move: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Siempre que model realice una operación de movimiento para desplazar un determinado conjunto de índices, los elementos respectivos de la vista se animarán a sus nuevas posiciones en la vista durante un segundo. La transición sólo se aplica a los elementos que son objeto de la operación de movimiento en el modelo; no se aplica a los elementos situados por debajo de ellos que son desplazados por la operación de movimiento. Para animar los elementos desplazados, defina las propiedades displaced o moveDisplaced.

Para más detalles y ejemplos sobre cómo utilizar las transiciones de vista, consulte la documentación ViewTransition.

Véase también moveDisplaced y ViewTransition.

moveDisplaced : Transition

Esta propiedad contiene la transición que se aplicará a los elementos desplazados por una operación de movimiento en la vista model.

Por ejemplo, a continuación se muestra una vista que especifica una transición de este tipo:

ListView {
    ...
    moveDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Cada vez que model realiza una operación de movimiento para desplazar un determinado conjunto de índices, los elementos situados entre los índices de origen y destino de la operación de movimiento se desplazan, haciendo que se muevan hacia arriba o hacia abajo (o lateralmente, si están orientados horizontalmente) dentro de la vista. A medida que se produce este desplazamiento, el movimiento de los elementos a sus nuevas posiciones x,y dentro de la vista se animará mediante un NumberAnimation a lo largo de un segundo, según se especifique. Esta transición no se aplica a los elementos que son los sujetos reales de la operación de desplazamiento; para animar los elementos desplazados, establezca la propiedad move.

Si un elemento es desplazado por varios tipos de operaciones al mismo tiempo, no está definido si se aplicará la transición addDisplaced, moveDisplaced o removeDisplaced. Además, si no es necesario especificar diferentes transiciones en función de si un elemento es desplazado por una operación de añadir, mover o eliminar, considere la posibilidad de establecer la propiedad displaced en su lugar.

Para más detalles y ejemplos sobre cómo utilizar las transiciones de vista, consulte la documentación de ViewTransition.

Véase también displaced, move, y ViewTransition.

orientation : enumeration

Esta propiedad contiene la orientación de la lista.

Valores posibles:

Constante	Descripción
ListView.Horizontal	Los ítems se disponen horizontalmente
ListView.Vertical	(por defecto) Los elementos se disponen verticalmente

Véase también Flickable Direction.

populate : Transition

Esta propiedad contiene la transición a aplicar a los elementos que se crean inicialmente para una vista.

Se aplica a todos los elementos que se crean cuando:

• La vista se crea por primera vez
• El model de la vista cambia de tal forma que los delegados visibles son completamente reemplazados.
• El model de la vista es reset, si el modelo es una subclase QAbstractItemModel

Por ejemplo, aquí hay una vista que especifica una transición de este tipo:

ListView {
    ...
    populate: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Cuando la vista se inicializa, la vista creará todos los elementos necesarios para la vista, luego los animará a sus posiciones correctas dentro de la vista durante un segundo.

Sin embargo, cuando se desplaza la vista más tarde, la transición de poblar no se ejecuta, a pesar de que los delegados se instancian a medida que se hacen visibles. Cuando el modelo cambia de manera que los nuevos delegados se hacen visibles, la transición add es la que se ejecuta. Así que no debes depender de la transición populate para inicializar propiedades en el delegado, porque no se aplica a todos los delegados. Si tu animación establece el valor to de una propiedad, la propiedad debe tener inicialmente el valor to, y la animación debe establecer el valor from en caso de que sea animada:

ListView {
    ...
    delegate: Rectangle {
        opacity: 1 // not necessary because it's the default
    }
    populate: Transition {
        NumberAnimation { property: "opacity"; from: 0; to: 1; duration: 1000 }
    }
}

Para más detalles y ejemplos sobre cómo utilizar las transiciones de vista, consulta la documentación de ViewTransition.

Véase también add y ViewTransition.

remove : Transition

Esta propiedad contiene la transición que se aplicará a los elementos que se eliminen de la vista.

Por ejemplo, aquí hay una vista que especifica dicha transición:

ListView {
    ...
    remove: Transition {
        ParallelAnimation {
            NumberAnimation { property: "opacity"; to: 0; duration: 1000 }
            NumberAnimation { properties: "x,y"; to: 100; duration: 1000 }
        }
    }
}

Cada vez que se elimine un elemento de la vista anterior, el elemento se animará a la posición (100,100) durante un segundo, y paralelamente también cambiará su opacidad a 0. La transición sólo se aplica a los elementos que se eliminan de la vista; no se aplica a los elementos situados debajo de ellos que son desplazados por la eliminación de los elementos. Para animar los elementos desplazados, ajuste las propiedades displaced o removeDisplaced.

Tenga en cuenta que cuando se aplica la transición, el elemento ya se ha eliminado del modelo; cualquier referencia a los datos del modelo para el índice eliminado no será válida.

Además, si se ha establecido la propiedad adjunta delayRemove para un elemento delegado, la transición de eliminación no se aplicará hasta que delayRemove vuelva a ser falsa.

Para más detalles y ejemplos sobre cómo utilizar las transiciones de vista, consulte la documentación de ViewTransition.

Véase también removeDisplaced y ViewTransition.

removeDisplaced : Transition

Esta propiedad contiene la transición que se aplicará a los elementos de la vista desplazados por la eliminación de otros elementos de la vista.

Por ejemplo, aquí hay una vista que especifica una transición de este tipo:

ListView {
    ...
    removeDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Cada vez que se elimina un elemento de la vista anterior, todos los elementos situados debajo de él se desplazan, haciendo que se muevan hacia arriba (o hacia los lados, si están orientados horizontalmente) dentro de la vista. A medida que se produce este desplazamiento, el movimiento de los elementos a sus nuevas posiciones x,y dentro de la vista se animará mediante un NumberAnimation a lo largo de un segundo, según se especifique. Esta transición no se aplica al elemento que realmente ha sido eliminado de la vista; para animar los elementos eliminados, establezca la propiedad remove.

Si un elemento es desplazado por varios tipos de operaciones al mismo tiempo, no está definido si se aplicará la transición addDisplaced, moveDisplaced o removeDisplaced. Además, si no es necesario especificar diferentes transiciones en función de si un elemento es desplazado por una operación de añadir, mover o eliminar, considere la posibilidad de establecer la propiedad displaced en su lugar.

Para más detalles y ejemplos sobre cómo utilizar las transiciones de vista, consulte la documentación de ViewTransition.

Véase también displaced, remove, y ViewTransition.

reuseItems : bool

Esta propiedad permite reutilizar los elementos que se instancian desde delegate. Si se establece en false, se destruyen todos los elementos agrupados actualmente.

Esta propiedad es false por defecto.

Véase también Reusing items, pooled(), y reused().

section group

Estas propiedades determinan la expresión a evaluar y la apariencia de las etiquetas de las secciones.

section.property contiene el nombre de la propiedad que es la base de cada sección.

section.criteria contiene el criterio para formar cada sección basada en section.property. Este valor puede ser uno de:

Para determinar los límites de las secciones se utiliza una comparación que no distingue entre mayúsculas y minúsculas.

section.delegate contiene el componente delegado para cada sección. La dirección stacking order predeterminada de las instancias de delegado de sección es 2. Si se declara una propiedad required llamada "sección" en ella, dicha propiedad contendrá el título de la sección.

section.labelPositioning determina si las etiquetas de la sección actual y/o siguiente se pegan al inicio/fin de la vista, y si las etiquetas se muestran en línea. Este valor puede ser una combinación de:

Cada elemento de la lista tiene propiedades adjuntas denominadas ListView.section, ListView.previousSection y ListView.nextSection.

Por ejemplo, aquí hay un ListView que muestra una lista de animales, separados en secciones. Cada elemento del ListView se coloca en una sección diferente dependiendo de la propiedad "tamaño" del elemento del modelo. El componente delegado sectionHeading proporciona la barra azul claro que marca el comienzo de cada sección.

    // The delegate for each section header
    Component {
        id: sectionHeading
        Rectangle {
            width: ListView.view.width
            height: childrenRect.height
            color: "lightsteelblue"

            required property string section

            Text {
                text: parent.section
                font.bold: true
                font.pixelSize: 20
            }
        }
    }

    ListView {
        id: view
        anchors.top: parent.top
        anchors.bottom: buttonBar.top
        width: parent.width
        model: animalsModel
        delegate: Text {
            required property string name

            text: name
            font.pixelSize: 18
        }

        section.property: "size"
        section.criteria: ViewSection.FullString
        section.delegate: sectionHeading
    }

Ver también ejemplos de ListView y Stacking Order in ListView.

snapMode : enumeration

Esta propiedad determina cómo se asentará el desplazamiento de la vista tras un arrastre o un desplazamiento. Los valores posibles son:

snapMode no afecta a currentIndex. Para actualizar currentIndex cuando se mueve la lista, establezca highlightRangeMode en ListView.StrictlyEnforceRange.

Véase también highlightRangeMode.

spacing : real

Esta propiedad contiene el espaciado entre elementos.

El valor por defecto es 0.

verticalLayoutDirection : enumeration

Esta propiedad contiene la dirección de diseño de una lista orientada verticalmente.

Valores posibles:

Esta propiedad no tiene efecto si orientation es Qt.Horizontal.

Véase también ListView::layoutDirection.

Documentación de la propiedad Attached

ListView.delayRemove : bool

Esta propiedad adjunta indica si el delegado puede ser destruido. Se adjunta a cada instancia del delegado. El valor por defecto es false.

A veces es necesario retrasar la destrucción de un elemento hasta que finalice una animación. El delegado de ejemplo que se muestra a continuación garantiza que la animación finalice antes de que el elemento se elimine de la lista.

Component {
    id: delegate
    Item {
        SequentialAnimation {
            id: removeAnimation
            PropertyAction { target: wrapper; property: "ListView.delayRemove"; value: true }
            NumberAnimation { target: wrapper; property: "scale"; to: 0; duration: 250; easing.type: Easing.InOutQuad }
            PropertyAction { target: wrapper; property: "ListView.delayRemove"; value: false }
        }
        ListView.onRemove: removeAnimation.start()
    }
}

Si se ha especificado una transición remove, no se aplicará hasta que delayRemove se devuelva a false.

ListView.isCurrentItem : bool [read-only]

Esta propiedad adjunta es verdadera si este delegado es el elemento actual; en caso contrario, es falsa.

Se adjunta a cada instancia del delegado.

Esta propiedad puede utilizarse, por ejemplo, para ajustar la apariencia del elemento actual:

ListView {
    width: 180; height: 200

    Component {
        id: contactsDelegate
        Rectangle {
            id: wrapper
            width: 180
            height: contactInfo.height
            color: ListView.isCurrentItem ? "black" : "red"
            Text {
                id: contactInfo
                text: name + ": " + number
                color: wrapper.ListView.isCurrentItem ? "red" : "black"
            }
        }
    }

    model: ContactModel {}
    delegate: contactsDelegate
    focus: true
}

ListView.nextSection : string [read-only]

Esta propiedad adjunta contiene la sección del siguiente elemento.

Se adjunta a cada instancia del delegado.

La sección se evalúa utilizando las propiedades de section.

ListView.previousSection : string [read-only]

Esta propiedad adjunta contiene la sección del elemento anterior.

Se adjunta a cada instancia del delegado.

La sección se evalúa utilizando las propiedades de section.

ListView.section : string [read-only]

Esta propiedad adjunta contiene la sección de este elemento.

Se adjunta a cada instancia del delegado.

La sección se evalúa utilizando las propiedades de section.

ListView.view : ListView [read-only]

Esta propiedad adjunta contiene la vista que gestiona esta instancia de delegado.

Se adjunta a cada instancia del delegado y también a los delegados de cabecera, pie de página, sección y resaltado.

Documentación de la señal attached

add()

Esta señal adjunta se emite inmediatamente después de añadir un elemento a la vista.

Si se especifica una transición de adición, se aplica inmediatamente después de gestionar esta señal.

pooled()

Esta señal se emite después de que un elemento se haya añadido a la reserva de reutilización. Se puede utilizar para pausar temporizadores o animaciones en curso dentro del elemento, o para liberar recursos que no se pueden reutilizar.

Esta señal sólo se emite si la propiedad reuseItems es true.

Véase también Reusing items, reuseItems, y reused().

remove()

Esta señal adjunta se emite inmediatamente antes de que se elimine un elemento de la vista.

Si se ha especificado una transición de eliminación, se aplica después de gestionar esta señal, siempre que delayRemove sea false.

reused()

Esta señal se emite después de que un elemento haya sido reutilizado. En este punto, el elemento ha sido sacado del pool y colocado dentro de la vista de contenido, y las propiedades del modelo como index y row han sido actualizadas.

Otras propiedades que no son proporcionadas por el modelo no cambian cuando un elemento es reutilizado. Debes evitar almacenar cualquier estado dentro de un delegado, pero si lo haces, restablece manualmente ese estado al recibir esta señal.

Esta señal se emite cuando se reutiliza un elemento, y no la primera vez que se crea.

Esta señal sólo se emite si la propiedad reuseItems es true.

Véase también Reusing items, reuseItems, y pooled().

Documentación del método

void decrementCurrentIndex()

Disminuye el índice actual. El índice actual se envolverá si keyNavigationWraps es verdadero y está actualmente al principio. Este método no tiene efecto si count es cero.

Nota: los métodos sólo deben ser llamados después de que el Componente se haya completado.

void forceLayout()

La respuesta a los cambios en el modelo se produce normalmente una vez por fotograma. Esto significa que dentro de los bloques de script es posible que el modelo subyacente haya cambiado, pero que ListView aún no se haya puesto al día.

Este método fuerza a ListView a responder inmediatamente a cualquier cambio pendiente en el modelo.

Nota: los métodos sólo deben ser llamados después de que el Componente se haya completado.

void incrementCurrentIndex()

Incrementa el índice actual. El índice actual se envolverá si keyNavigationWraps es verdadero y se encuentra actualmente al final. Este método no tiene efecto si count es cero.

Nota: los métodos sólo deben ser llamados después de que el Componente haya finalizado.

int indexAt(real x, real y)

Devuelve el índice del elemento visible que contiene el punto x, y en coordenadas de contenido. Si no hay ningún elemento en el punto especificado, o el elemento no es visible, se devuelve -1.

Si el elemento está fuera del área visible, se devuelve -1, independientemente de que exista un elemento en ese punto cuando se desplace a la vista.

Nota: los métodos sólo deben invocarse después de que el Componente haya finalizado.

Item itemAt(real x, real y)

Devuelve el elemento visible que contiene el punto x, y en coordenadas de contenido. Si no hay ningún elemento en el punto especificado, o el elemento no es visible, se devuelve null.

Si el elemento está fuera del área visible, se devuelve null, independientemente de que exista un elemento en ese punto cuando se desplace a la vista.

Nota: los métodos sólo deben invocarse una vez que el Componente haya finalizado.

Item itemAtIndex(int index)

Devuelve el elemento para index. Si no hay ningún elemento para ese índice, por ejemplo porque aún no se ha creado, o porque se ha desplazado fuera del área visible y se ha eliminado de la caché, se devuelve null.

Nota: este método sólo debe invocarse después de que el Componente haya finalizado. El valor devuelto tampoco debe ser almacenado ya que puede convertirse en null tan pronto como el control salga del ámbito de llamada, si la vista libera ese elemento.

Posiciona la vista al principio o al final, teniendo en cuenta cualquier encabezado o pie de página.

No se recomienda utilizar contentX o contentY para posicionar la vista en un índice concreto. Esto es poco fiable ya que eliminar elementos del inicio de la lista no provoca que todos los demás elementos se reposicionen, y porque el inicio real de la vista puede variar en función del tamaño de los delegados.

Nota: los métodos sólo deben ser llamados después de que el Componente se haya completado. Para posicionar la vista al inicio, este método debe ser llamado por Component.onCompleted. Por ejemplo, para posicionar la vista al final al inicio:

Component.onCompleted: positionViewAtEnd()

void positionViewAtIndex(int index, PositionMode mode)

Posiciona la vista de forma que index se encuentre en la posición especificada por mode:

Si posicionar la vista en index provocaría que se mostrara un espacio vacío al principio o al final de la vista, la vista se posicionará en el límite.

No se recomienda utilizar contentX o contentY para posicionar la vista en un índice concreto. Esto no es fiable, ya que la eliminación de elementos del inicio de la lista no provoca el reposicionamiento de todos los demás elementos, y porque el inicio real de la vista puede variar en función del tamaño de los delegados. La forma correcta de traer un elemento a la vista es con positionViewAtIndex.

Nota: los métodos sólo deben ser llamados después de que el Componente se haya completado. Para posicionar la vista al inicio, este método debe ser llamado por Component.onCompleted. Por ejemplo, para posicionar la vista al final:

Component.onCompleted: positionViewAtIndex(count - 1, ListView.Beginning)