C

PathView QML Type

Lays out items in a model on a path. More...

Import Statement:	`import QtQuick`
Since:	Qt Quick Ultralite 2.12
Inherits:	Item

List of all members, including inherited members

Properties

count : int
currentIndex : int
delegate : Component
model : model
path : Path
pathItemCount : int
preferredHighlightBegin : real
preferredHighlightEnd : real

Attached Properties

isCurrentItem : bool

Methods

decrementCurrentIndex()
incrementCurrentIndex()

Detailed Description

A PathView displays data from models created from built-in QML types like ListModel , or custom model classes defined in C++ that inherit from Qul::ListModel.

The view has a model property, defining the data to be displayed, and a delegate property, defining how to display the data. The delegate is instantiated for each item in the PathView.

Note: Unlike mainstream Qt, Qt Quick Ultralite does not support moving items along the path using flick or swipe gestures. Use a button to change the currentIndex property of the PathView.

For example, if there is a simple list model defined in a file ContactModel.qml like this:

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

This data can be represented as a PathView, like this:

Rectangle {
    PathView {
        model: model1
        // Note, pathItemCount should be set to a value larger than 0
        pathItemCount: 3
        path: Path {
            startX: 120; startY: 100
            PathQuad { x: 120; y: 25; controlX: 260; controlY: 75 }
            PathQuad { x: 120; y: 100; controlX: -20; controlY: 75 }
        }
        delegate: Item {
            id: wrapper
            height: 100
            width: 100
            required property string icon
            required property string name
            required property int index
            readonly property bool isCurrent: PathView.isCurrentItem

            opacity: isCurrent ? 1 : 0.5
            // Note: to keep the current item on top of the others change the z value
            z: isCurrent ? 1 : 0

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }

            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
                anchors.bottom: parent.bottom
            }
        }
    }
}

PathView does not automatically handle keyboard navigation, because the navigation keys depend upon the shape of the path. Use buttons instead for navigating through the items in a PathView, by changing the current index with either decrementCurrentIndex or incrementCurrentIndex.

PathView {
    // ...
    Button {
        text: "Previous"
        onClicked: pathView.decrementCurrentIndex()
    }
    Button {
        text: "Next"
        onClicked: pathView.incrementCurrentIndex()
    }
    // the Keys.* with the focus property is not supported in \QUL
    // focus: true
    // Keys.onLeftPressed: decrementCurrentIndex()
    // Keys.onRightPressed: incrementCurrentIndex()
}

You should not store state information in a delegate as Qt Quick Ultralite instantiates and destroys the delegates at any time.

Qt Quick Ultralite statically allocates a fixed size for the delegates, and you can define the size using the pathItemCount property. The size should be a value larger than 0, which represents the maximum number of items that could be visible on the path at any time. If the model has less no. of items than the pathItemCount, PathView adjusts the delegate count accordingly.

PathView attaches the PathView.isCurrentItem property to the root item of the delegate. In the following example, the root delegate item can access the attached property directly as PathView.isCurrentItem, while the child nameText object needs an additional qualifier to access the property

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 + (wrapper.PathView.isCurrentItem ? " (current)" : "")
            font.pointSize: 16
        }
    }
}

Important considerations

Use PathView.isCurrentItem to highlight current items as Qt Quick Ultralite doesn't yet support highlightItem.
PathView doesn't enable clip automatically. If the view is not clipped by another item or the screen, set clip: true to clip items that are outside the viewport.

Property Documentation

preferredHighlightBegin : real

preferredHighlightEnd : real

These properties set the preferred range of the highlight (current item) within the view. The preferred values must be in the range from 0 to 1.

Note: Animations and touch gestures are not supported yet, so the default PathView.StrictlyEnforceRange is always used. This means, currentItem is at the start of the range.

Define a highlight range to control where the current item ends up when the view moves. For example, if you want the currently selected item to be in the middle of the path, set the highlight range to be 0.5,0.5.

Note: A valid range requires preferredHighlightEnd to be greater than or equal to preferredHighlightBegin.

count : int

This property holds the number of items in the model.

currentIndex : int

This property holds the index of the current item.

delegate : Component

The delegate provides a template defining each item instantiated by the view. The index is exposed as an accessible index property. Properties of the model are also available depending upon the type of ListModel.

Note: PathView will lay out the items based on the size of the root.

Here is an example delegate:

        delegate: Item {
            id: wrapper
            height: 100
            width: 100
            required property string icon
            required property string name
            required property int index
            readonly property bool isCurrent: PathView.isCurrentItem

            opacity: isCurrent ? 1 : 0.5
            // Note: to keep the current item on top of the others change the z value
            z: isCurrent ? 1 : 0

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }

            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
                anchors.bottom: parent.bottom
            }
        }
    }

model : model

This property holds the model providing data for the view.

The model provides a set of data that is used to create the items for the view. Use C++ models for large or dynamic datasets, and QML models based on the ListModel type for simple datasets.

Note: changing the model will reset the offset and currentIndex to 0.

See also ListModel.

path : Path

This property holds the path used to lay out the items.

See also Path.

pathItemCount : int

This property holds the number of items visible on the path at any time.

Qt Quick Ultralite uses it to also allocate the delegates statically. It uses the required number of delegate instances only, if the model has less number of items than pathItemCount.

Attached Property Documentation

PathView.isCurrentItem : bool [read-only]

This attached property is true if the delegate is the current item; otherwise false. It is attached to each instance of the delegate.

A current item is the delegate item with the same index as the currentIndex property of the PathView.

This property may be used to adjust the appearance of the current item.

        delegate: Item {
            id: wrapper
            height: 100
            width: 100
            required property string icon
            required property string name
            required property int index
            readonly property bool isCurrent: PathView.isCurrentItem

            opacity: isCurrent ? 1 : 0.5
            // Note: to keep the current item on top of the others change the z value
            z: isCurrent ? 1 : 0

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }

            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
                anchors.bottom: parent.bottom
            }
        }
    }

Method Documentation

decrementCurrentIndex()

Decrements the current index.

Note: Call this method only after the Component has completed.

incrementCurrentIndex()

Increments the current index.

Note: Call this method only after the Component has completed.

Available under certain Qt licenses.
Find out more.