C

ListView QML Type

Provides a list view of items provided by a model. More...

Import Statement:	import QtQuick
Since:	Qt Quick Ultralite 1.0
Inherits:	Flickable

List of all members, including inherited members

Properties

count : int
currentIndex : int
delegate : Component
highlight : Component
model : model
orientation : enumeration
spacing : real

Methods

int indexAt(real x, real y)
var itemAtIndex(int index)
positionViewAtIndex(int index, PositionMode mode)

Detailed Description

A ListView displays data from models created from built-in QML types like ListModel.

A ListView has a model, which defines the data to be displayed, and a delegate, which defines how the data should be displayed. Items in a ListView are laid out horizontally or vertically. List views are inherently flickable because ListView inherits from Flickable.

Note: In Qt Quick Ultralite all delegates must have the same size, and their size must be explicitly specified.

Example Usage

The following example shows the definition of a simple list model which is used in a ListView. Here, the ListView creates a Text item for its delegate.

Item {
    ListView {
        width: 180; height: 300

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

        delegate: Text {
            width: 180
            height: 30
            text: model.name + ": " + model.number
        }
    }
}

The view creates a new Text component for each item in the model. Notice the delegate is able to access the model's name and number data directly.

Improved example

An improved list view is shown below. The delegate is visually improved and is moved into a separate contactDelegate component.

Item {
    Rectangle {
        width: 360; height: 200

        Component {
            id: contactDelegate
            Item {
                width: 360; height: 60
                Column {
                    Text { text: 'Name: ' + model.name }
                    Text { text: 'Number: ' + model.number }
                }
            }
        }

        ListView {
            anchors.fill: parent

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

            delegate: contactDelegate
        }
    }
}

Delegates are instantiated as needed and may be destroyed at any time. They are parented to ListView's contentItem, not to the view itself. State should never be stored in a delegate.

Layout Example

The layout of the items in a ListView can be controlled using the orientation property, which controls whether items flow horizontally or vertically. This value can be either Qt.Horizontal or Qt.Vertical.

Item {
    Rectangle {
        width: 360; height: 200

        Component {
            id: contactDelegate
            Item {
                width: 120; height: 200
                Column {
                    Text { text: model.name }
                    Text { text: model.surname }
                    Text { text: "Age: " + model.age }
                }
            }
        }

        ListView {
            anchors.fill: parent
            orientation: Qt.Horizontal

            model: ListModel {
                ListElement {
                    name: "Bill"
                    surname: "Smith"
                    age: "30"
                }
                ListElement {
                    name: "John"
                    surname: "Brown"
                    age: "56"
                }
                ListElement {
                    name: "Sam"
                    surname: "Wise"
                    age: "42"
                }
            }

            delegate: contactDelegate
        }
    }
}

See also ListView QML Type and Model-View-Delegate pattern.

Property Documentation

[since Qt Quick Ultralite 2.9] count : int

This property holds the number of items in the model.

This property was introduced in Qt Quick Ultralite 2.9.

[since Qt Quick Ultralite 2.9] currentIndex : int

The currentIndex property holds the index of the current item. Setting it to -1 removes the highlight.

This property was introduced in Qt Quick Ultralite 2.9.

delegate : Component

The delegate provides a template defining each item instantiated by the list view.

[since Qt Quick Ultralite 2.9] highlight : Component

This property holds the component to use as the highlight.

Each ListView gets an instance of the highlight component, which is managed by the ListView to highlight the current item.

Note: The ListView in Qt Quick Ultralite has a different stacking order for its elements compared to Qt Quick. In Qt Quick, the delegate has a stacking order of 1, and the highlight has a stacking order of 0. However, Qt Quick Ultralite uses 0 as the stacking order value for a delegate, and -1 for the highlight. This avoids the need for additional storage, as any z value other than the default (0) needs extra storage. By maintaining a default stacking order value when possible, the ListView in Qt Quick Ultralite optimizes the use of storage.

This property was introduced in Qt Quick Ultralite 2.9.

model : model

This property holds the model, which provides data for the list.

The model provides the set of data that is used to create the items in the view.

orientation : enumeration

This property holds the orientation of the list.

Possible values:

Constant	Description
`Qt.Horizontal`	Items are laid out horizontally.
`Qt.Vertical`	Items are laid out vertically by default.

spacing : real

This property holds the spacing between items.

The default value is 0.

Method Documentation

[since Qt Quick Ultralite 2.9] int indexAt(real x, real y)

Returns the index of the visible item containing the point x, y in content coordinates. The function returns -1, if there is no item at the point specified or the item is not visible.

The function also returns -1 when item is outside the visible area, regardless of whether the item exists in the ListView.

This method was introduced in Qt Quick Ultralite 2.9.

[since Qt Quick Ultralite 1.6] var itemAtIndex(int index)

Returns the item at index. If there is no item for that index, for example because it has not been created yet, or because it has been panned out of the visible area and removed from the cache, null item is returned.

This method was introduced in Qt Quick Ultralite 1.6.

[since Qt Quick Ultralite 2.9] positionViewAtIndex(int index, PositionMode mode)

Lets you control the viewport within the ListView. It sets index based one of the following mode:

Constant	Description
`ListView.Beginning`	Position the item at the top (or left for horizontal orientation) of the view.
`ListView.Center`	Position the item in the center of the view.
`ListView.End`	Position the item at bottom (or right for horizontal orientation) of the view.
`ListView.Visible`	Position the item in the view. It has no effect, if the item is partially visible.
`ListView.Contain`	Position the entire item in the view. If the item is larger than the view, it is positioned at the top (or left for horizontal orientation) of the view.

If positioning the view at index adds empty space at the beginning or end of the view, the view is positioned at the boundary.

Note: The ListView.SnapPosition mode will have no effect as Qt Quick Ultralite doesn't yet support either highlightRangeMode or snapMode.

This method was introduced in Qt Quick Ultralite 2.9.

Available under certain Qt licenses.
Find out more.