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

delegate : Component
model : model
orientation : enumeration
spacing : real

Methods

var itemAtIndex(int index)

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

delegate : Component

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

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

Available under certain Qt licenses.
Find out more.