Applications frequently need to provide and display data. Qt Quick has the notion of models, views, and delegates to display data. They modularize the visualization of data in order to give the developer or designer control over the different aspects of the data. A developer can swap a list view with a grid view with little changes to the data. Similarly, encapsulating an instance of the data in a delegate allows the developer to dictate how to present or handle the data.

• Model - contains the data and its structure. There are several ways to create models.
• View - a container that displays the data. The view might display the data in a list or a grid.
• Delegate - dictates how the data should appear in the view. The delegate takes each data in the model and encapsulates it. The data is accessible through the delegate. The delegate can also write data back into editable models.

To visualize data, bind the view's model property to a model and the delegate property to a component or another compatible type.

Displaying Data with Views

Views are containers for collections of items. They are feature-rich and can be customized to meet style or behavior requirements.

A set of standard views are provided in the basic set of Qt Quick graphical types:

• Repeater - create items for each data entry without a predetermined layout
• ListView - arranges items in a horizontal or vertical list

These types have properties and behaviors exclusive to each type. See their respective documentation for more information.

View Delegates

Views need a delegate to visually represent an item in a list. A view visualizes each item list according to the template defined by the delegate. Items in a model are accessible through the index property as well as the item's properties.

Component {
    id: petdelegate
    Text {
        id: label
        width: view.width / petlist.count
        height: view.height / petlist.count
        font.pixelSize: 24
        text: if (index == 0)
            label.text = model.type + " (default)"
        else
            text: model.type
    }
}

Models

Data is provided to the delegate via named data roles, which the delegate may bind to. Here is a ListModel with two roles, type and age, and a ListView with a delegate that binds to these roles to display their values:

import QtQuick 2.15

Rectangle {
    color: "white"

    ListModel {
        id: myModel
        ListElement {
            type: "Dog"
            age: 8
        }
        ListElement {
            type: "Cat"
            age: 5
        }
    }

    Component {
        id: myDelegate
        Text {
            width: listView.width / myModel.count
            height: listView.height / myModel.count
            text: model.type + ", " + model.age
        }
    }

    ListView {
        id: listView
        anchors.fill: parent
        model: myModel
        delegate: myDelegate
    }
}

To get control over which roles are accessible, and to make delegates more self-contained and usable outside of views, required properties can be used. If a delegate contains required properties, the named roles are not provided. Instead, the Qt Quick Ultralite engine checks if the name of a required property matches that of a model role. If so, that property is bound to the corresponding value from the model.

import QtQuick 2.15

Rectangle {
    color: "white"

    ListModel {
        id: myModel
        ListElement {
            type: "Dog"
            age: 8
            noise: "meow"
        }
        ListElement {
            type: "Cat"
            age: 5
            noise: "woof"
        }
    }

    Component {
        id: delegate
        Text {
            width: listView.width / myModel.count
            height: listView.height / myModel.count
            required property string type
            required property int age
            text: type + ", " + age
            // WRONG: text: type + ", " + noise
            // The above line would cause a compiler error
            // as there is no required property noise
        }
    }

    ListView {
        id: listView
        anchors.fill: parent
        model: myModel
        delegate: delegate
    }
}

If there is a naming clash between the model's properties and the delegate's properties, the roles can be accessed with the qualified model name instead. For example, if a Text type had type and age properties, the text in the above example would display those property values instead of the type and age values from the model. In this case, the properties could have been referenced as model.type and model.age instead to ensure that the delegate displays the property values from the model.

A special index role containing the index of the item in the model is also available to the delegate. Note that this index is set to -1 if the item is removed from the model. If you bind to the index role, ensure that the logic accounts for the possibility of index being -1, that is, that the item is no longer valid. Usually the item will shortly be destroyed, but it is possible to delay delegate destruction in some views.

Models that do not have named roles will have the data provided via the modelData role. The modelData role is also provided for models that have only one role. In this case the modelData role contains the same data as the named role.

List Model

ListModel is a simple hierarchy of types specified in QML. The available roles are specified by the ListElement properties.

ListModel {
    id: fruitModel

    ListElement {
        name: "Apple"
        cost: 245
    }
    ListElement {
        name: "Orange"
        cost: 325
    }
    ListElement {
        name: "Banana"
        cost: 195
    }
}

The above model has two roles, name and cost. These can be bound to by a ListView delegate, for example:

ListView {
    anchors.fill: parent
    model: fruitModel
    delegate: Row {
        width: parent.width / fruitModel.count
        height: parent.height / fruitModel.count
        Text { text: "Fruit: " + model.name }
        Text { text: " Cost: $" + model.cost }
    }
}

Lists of Objects

An array literal containing object literals can be used as a model. The current element of the array is available as the modelData role and can be accessed directly or as model.modelData.

ListView {
    anchors.fill: parent
    model: [
        { name: "Apple", color: "green" },
        { name: "Pear", color: "pink" }
    ]
    delegate: Row {
        width: parent.width / 2
        height: parent.height / 2
        Text { text: "Fruit: " + modelData.name }
        Text { text: " Color: " + model.modelData.color }
    }
}

Properties of Type ListModel<T>

A property of type ListModel<T> type can be used as a model, where properties of T describe the model structure.

This allows the model data to be set externally, or by PropertyChanges in a State.

// MyView.qml
Item {
    width: 120
    height: 40

    property ListModel<NameAgeType> myModel

    ListView {
        anchors.fill: parents
        model: myModel
        delegate: Text {
            width: parent.width / myModel.count
            height: parent.height / myModel.count
            text: model.name
        }
    }
}

// NameAgeType.qml
QtObject {
    property string name
    property int age
}

// User.qml
Rectangle {
    Row {
        MyView {
            myModel: [{ name: "John Smith", age: 42 }]
        }
        MyView {
            myModel: ListModel { ListElement { name: "Smith"; age: 42 } }
        }
    }
}

Integers as Models

An integer can be used as a model that contains a certain number of types. In this case, the model does not have any data roles.

The following example creates a ListView with five elements:

Rectangle {

    Component {
        id: itemDelegate
        Text {
            width: listView.width / 5
            height: listView.height / 5
            text: "I am item number: " + index
        }
    }

    ListView {
        id: listView
        anchors.fill: parent
        model: 5
        delegate: itemDelegate
    }

}

C++ Data Models

Models can be defined in C++ and then made available to QML. This mechanism is useful for exposing existing C++ data models, mutable, or otherwise complex datasets to QML.

For information, visit Qul::ListModel and Integrating C++ code with QML.