ListView Class Reference

The ListView item provides a list view of items provided by a model. More...

Inheritance diagram for ListView:

Detailed Description

The ListView item provides a list view of items provided by a model.

Since

4.7

A ListView displays data from models created from built-in QML elements like ListModel and XmlListModel, or custom model classes defined in C++ that inherit from QAbstractListModel.

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 .

Example Usage

The following example shows the definition of a simple list model defined in a file called ContactModel.qml:

import QtQuick 1.0

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

Another component can display this model data in a ListView, like this:

import QtQuick 1.0

ListView {
    width: 180; height: 200

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

Here, the ListView creates a ContactModel component for its model, and a Text element for its delegate. The view will create 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.

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

Rectangle {
    width: 180; height: 200

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

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

The currently selected item is highlighted with a blue Rectangle using the highlight property, and focus is set to true to enable keyboard navigation for the list view. The list view itself is a focus scope (see the focus documentation page for more details).

Delegates are instantiated as needed and may be destroyed at any time. State should never be stored in a delegate.

ListView attaches a number of properties to the root item of the delegate, for example {ListView.isCurrentItem}. In the following example, the root delegate item can access this attached property directly as ListView.isCurrentItem, while the child contactInfo object must refer to this property as 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
}

Note

Views do not enable clip automatically. If the view is not clipped by another item or the screen, it will be necessary to set {clip: true} in order to have the out of view items clipped nicely.

See also

{QML Data Models}, GridView, {Models and Views: ListView Examples}{ListView examples}

---

The documentation for this class was generated from the following file:

• /src/declarative/graphicsitems/qdeclarativelistview.cpp