PathView QML Type

Coloca los elementos proporcionados por el modelo en una ruta. Más...

• Lista de todos los miembros, incluidos los heredados

Propiedades

• cacheItemCount : int
• count : int
• currentIndex : int
• currentItem : Item
• delegate : Component
• dragMargin : real
• dragging : bool
• flickDeceleration : real
• flicking : bool
• highlight : Component
• highlightItem : Item
• highlightMoveDuration : int
• highlightRangeMode : enumeration
• interactive : bool
• maximumFlickVelocity : real
• model : model
• movementDirection : enumeration
• moving : bool
• offset : real
• path : Path
• pathItemCount : int
• preferredHighlightBegin : real
• preferredHighlightEnd : real
• snapMode : enumeration

Propiedades anexas

• isCurrentItem : bool
• onPath : bool
• view : PathView

Señales

• dragEnded()
• dragStarted()
• flickEnded()
• flickStarted()
• movementEnded()
• movementStarted()

Métodos

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

Descripción detallada

Un PathView muestra datos de modelos creados a partir de tipos QML incorporados como ListModel y XmlListModel, o clases de modelo personalizadas definidas en C++ que heredan de QAbstractListModel.

La vista tiene un model, que define los datos que deben mostrarse, y un delegate, que define cómo deben mostrarse los datos. El delegate se instanciará para cada elemento del path. Los elementos pueden desplazarse por el recorrido.

Por ejemplo, si hay un modelo de lista simple definido en un archivo ContactModel.qml como éste:

import QtQuick

ListModel {
    ListElement {
        name: "Bill Jones"
        icon: "pics/qtlogo.png"
    }
    ListElement {
        name: "Jane Doe"
        icon: "pics/qtlogo.png"
    }
    ListElement {
        name: "John Smith"
        icon: "pics/qtlogo.png"
    }
}

Estos datos pueden ser representados como un PathView, así:

import QtQuick

Rectangle {
    width: 240; height: 200

    Component {
        id: delegate
        Column {
            id: wrapper

            required property url icon
            required property string name

            opacity: PathView.isCurrentItem ? 1 : 0.5

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }
            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
            }
        }
    }

    PathView {
        anchors.fill: parent
        model: ContactModel {}
        delegate: delegate
        path: Path {
            startX: 120; startY: 100
            PathQuad { x: 120; y: 25; controlX: 260; controlY: 75 }
            PathQuad { x: 120; y: 100; controlX: -20; controlY: 75 }
        }
    }
}

(Observe que el ejemplo anterior utiliza PathAttribute para escalar y modificar la opacidad de los elementos a medida que giran. Este código adicional puede verse en la documentación de PathAttribute ).

PathView no maneja automáticamente la navegación por teclado. Esto se debe a que las teclas a utilizar para la navegación dependerán de la forma de la ruta. La navegación se puede añadir de forma sencilla estableciendo focus en true y llamando a decrementCurrentIndex() o incrementCurrentIndex(), por ejemplo para navegar utilizando las teclas de flecha izquierda y derecha:

PathView {
    // ...
    focus: true
    Keys.onLeftPressed: decrementCurrentIndex()
    Keys.onRightPressed: incrementCurrentIndex()
}

La propia vista de la ruta es un ámbito de enfoque (véase Enfoque del teclado en Qt Quick para más detalles).

Los delegados se instancian según sea necesario y pueden destruirse en cualquier momento. El estado nunca debe almacenarse en un delegado.

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

    Component {
        id: delegate
        Column {
            id: wrapper

            required property url icon
            required property string name

            opacity: PathView.isCurrentItem ? 1 : 0.5

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }
            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
            }
        }
    }

Tenga en cuenta que las vistas no se recortan automáticamente. Si la vista no está recortada por otro elemento o por la pantalla, será necesario establecer clip: true para que los elementos fuera de la vista queden bien recortados.

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

Documentación de propiedades

cacheItemCount : int

Esta propiedad contiene el número máximo de elementos que se almacenarán en caché fuera de la ruta.

Por ejemplo, un PathView con un modelo que contiene 20 elementos, un pathItemCount de 10, y un cacheItemCount de 4 creará hasta 14 elementos, con 10 visibles en la ruta y 4 invisibles en caché.

Los delegados en caché se crean de forma asíncrona, lo que permite que la creación se produzca en varios fotogramas y reduce la probabilidad de saltarse fotogramas.

Véase también pathItemCount.

count : int [read-only]

Esta propiedad contiene el número de elementos del modelo.

currentIndex : int

Esta propiedad contiene el índice del elemento actual.

currentItem : Item [read-only]

Esta propiedad contiene el elemento actual 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 desplazamiento de la vista cuando se especifica pathItemCount. 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.

Tenga en cuenta que PathView distribuirá los elementos en función del tamaño del elemento raíz del delegado.

He aquí un ejemplo de delegación:

    Component {
        id: delegate
        Column {
            id: wrapper

            required property url icon
            required property string name

            opacity: PathView.isCurrentItem ? 1 : 0.5

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }
            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
            }
        }
    }

dragMargin : real

Esta propiedad contiene la distancia máxima de la trayectoria que inicia el arrastre del ratón.

Por defecto, la ruta sólo puede arrastrarse haciendo clic sobre un elemento. Si dragMargin es mayor que cero, se puede iniciar un arrastre haciendo clic dentro de los píxeles dragMargin de la ruta.

dragging : bool [read-only]

Esta propiedad indica si la vista se está moviendo debido a que el usuario la está arrastrando.

flickDeceleration : real

Esta propiedad contiene la velocidad a la que se desacelerará un movimiento.

El valor predeterminado es 100.

flicking : bool [read-only]

Esta propiedad indica si la vista se está moviendo debido a que el usuario la está desplazando.

highlight : Component

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

Se creará una instancia del componente de resaltado para cada vista. La geometría de la instancia del componente resultante será gestionada por la vista para permanecer con el elemento actual.

El siguiente ejemplo muestra cómo crear un resalte sencillo. Observe el uso de la propiedad adjunta PathView.onPath para garantizar que el resalte se oculta cuando se desplaza fuera de la ruta.

Component {
    Rectangle {
        visible: PathView.onPath
        // ...
    }
}

Véase también highlightItem y highlightRangeMode.

highlightItem : Item [read-only]

highlightItem contiene el elemento destacado, creado a partir del componente highlight.

Véase también highlight.

highlightMoveDuration : int

Esta propiedad contiene la duración de la animación de movimiento del delegado de resaltado.

Si highlightRangeMode es StrictlyEnforceRange entonces esta propiedad determina la velocidad a la que los elementos se mueven a lo largo del recorrido.

El valor por defecto para la duración es 300ms.

Estas propiedades establecen el rango preferido del resaltado (elemento actual) dentro de la vista. Los valores preferidos deben estar en el rango de 0 a 1.

Los valores válidos para highlightRangeMode son:

El valor por defecto es PathView.StrictlyEnforceRange.

Definir un rango de resaltado es la forma correcta de influir en dónde termina el elemento actual cuando la vista se mueve. Por ejemplo, si desea que el elemento seleccionado actualmente se encuentre en el centro del recorrido, defina el rango de resaltado como 0.5,0.5 y highlightRangeMode a PathView.StrictlyEnforceRange. Entonces, cuando la ruta se desplace, el elemento actualmente seleccionado será el elemento en esa posición. Esto también se aplica a cuando el elemento actualmente seleccionado cambia - se desplazará dentro del rango de resaltado preferido. Además, el comportamiento del índice del elemento actual se producirá tanto si existe un resalte como si no.

interactive : bool

Un usuario no puede arrastrar o desplazar un PathView que no sea interactivo.

Esta propiedad es útil para desactivar temporalmente el desplazamiento. Esto permite una interacción especial con los hijos de PathView.

maximumFlickVelocity : real

Esta propiedad contiene la velocidad máxima aproximada a la que el usuario puede desplazar la vista en píxeles/segundo.

El valor por defecto depende de la plataforma.

model : model

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

El modelo proporciona un conjunto de datos que se utiliza para crear los elementos de la vista. En el caso de conjuntos de datos grandes o dinámicos, el modelo suele proporcionarlo un objeto modelo de C++. Los modelos también pueden crearse directamente en QML, utilizando el tipo ListModel.

Véase también Modelos de datos.

movementDirection : enumeration

Esta propiedad determina la dirección en la que se mueven los elementos al establecer el índice actual. Los valores posibles son:

Por ejemplo, supongamos que hay 5 elementos en el modelo, y currentIndex es 0. Si currentIndex se establece en 2,

• una dirección de movimiento Positive resultará en el siguiente orden: 0, 1, 2
• una dirección de movimiento Negative resultará en el siguiente orden 0, 5, 4, 3, 2
• una dirección de movimiento Shortest resultará en el mismo orden que Positive.

moving : bool [read-only]

Esta propiedad indica si la vista se está moviendo debido a que el usuario ha arrastrado o desplazado la vista.

offset : real

El desplazamiento especifica a qué distancia del camino se encuentran los elementos desde sus posiciones iniciales. Se trata de un número real que oscila entre 0 y el número de elementos del modelo.

path : Path

Esta propiedad contiene la ruta utilizada para disponer los elementos. Para más información, consulte la documentación de Path.

pathItemCount : int

Esta propiedad contiene el número de elementos visibles en la ruta en un momento dado.

Establecer pathItemCount a undefined mostrará todos los elementos de la ruta.

snapMode : enumeration

Esta propiedad determina cómo se asentarán los elementos tras un arrastre o un desplazamiento. Los valores posibles son:

snapMode no afecta a currentIndex. Para actualizar currentIndex a medida que se desplaza la vista, ajuste highlightRangeMode a PathView.StrictlyEnforceRange (por defecto PathView).

Véase también highlightRangeMode.

Documentación de propiedades adjuntas

PathView.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 para ajustar la apariencia del elemento actual.

    Component {
        id: delegate
        Column {
            id: wrapper

            required property url icon
            required property string name

            opacity: PathView.isCurrentItem ? 1 : 0.5

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }
            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
            }
        }
    }

PathView.onPath : bool [read-only]

Esta propiedad adjunta indica si el elemento se encuentra actualmente en la ruta.

Si se ha establecido pathItemCount, es posible que algunos elementos se instancien, pero no se considere que estén actualmente en el camino. Normalmente, estos elementos se establecerían como invisibles, por ejemplo:

Component {
    Rectangle {
        visible: PathView.onPath
        // ...
    }
}

Se adjunta a cada instancia del delegado.

PathView.view : PathView [read-only]

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

Se adjunta a cada instancia del delegado.

Documentación sobre señales

dragEnded()

Esta señal se emite cuando el usuario deja de arrastrar la vista.

Si la velocidad de arrastre es suficiente en el momento en que se suelta el botón táctil/del ratón, se iniciará un flick.

dragStarted()

Esta señal se emite cuando la vista comienza a ser arrastrada debido a la interacción del usuario.

flickEnded()

Esta señal se emite cuando la vista deja de moverse debido a un flick.

flickStarted()

Esta señal se emite cuando se desliza la vista. Un flick comienza en el momento en que se suelta el ratón o el toque, mientras aún está en movimiento.

movementEnded()

Esta señal se emite cuando la vista deja de moverse debido a la interacción del usuario. Si se ha generado un desplazamiento, esta señal se emitirá cuando el desplazamiento se detenga. Si no se generó un flick, esta señal se emitirá cuando el usuario deje de arrastrar, es decir, cuando suelte el ratón o la pantalla táctil.

movementStarted()

Esta señal se emite cuando la vista comienza a moverse debido a la interacción del usuario.

Documentación del método

void decrementCurrentIndex()

Disminuye el índice actual.

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

void incrementCurrentIndex()

Incrementa el índice actual.

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

int indexAt(real x, real y)

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

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

Item itemAt(real x, real y)

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

Nota: los métodos sólo deben llamarse después de 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.

void positionViewAtIndex(int index, PositionMode mode)

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

Nota: los métodos sólo deben ser llamados después de que el Componente haya finalizado. 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, PathView.End)