GridView Class Reference

The GridView item provides a grid view of items provided by a model. More...

Inheritance diagram for GridView:

Detailed Description

The GridView item provides a grid view of items provided by a model.

Since

4.7

A GridView 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 GridView has a model , which defines the data to be displayed, and a delegate , which defines how the data should be displayed. Items in a GridView are laid out horizontally or vertically. Grid views are inherently flickable as GridView 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: "Jim Williams"
        portrait: "pics/portrait.png"
    }
    ListElement {
        name: "John Brown"
        portrait: "pics/portrait.png"
    }
    ListElement {
        name: "Bill Smyth"
        portrait: "pics/portrait.png"
    }
    ListElement {
        name: "Sam Wise"
        portrait: "pics/portrait.png"
    }
}

{class="float-right"}

This model can be referenced as ContactModel in other QML files. See QML Modules for more information about creating reusable components like this.

Another component can display this model data in a GridView, as in the following example, which creates a ContactModel component for its model, and a Column element (containing Image and Text elements) for its delegate.

import QtQuick 1.0

GridView {
    width: 300; height: 200

    model: ContactModel {}
    delegate: Column {
        Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter }
        Text { text: name; anchors.horizontalCenter: parent.horizontalCenter }
    }
}

{class="float-right"}

The view will create a new delegate for each item in the model. Note that the delegate is able to access the model's name and portrait data directly.

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

Rectangle {
    width: 300; height: 200

    Component {
        id: contactDelegate
        Item {
            width: grid.cellWidth; height: grid.cellHeight
            Column {
                anchors.fill: parent
                Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter }
                Text { text: name; anchors.horizontalCenter: parent.horizontalCenter }
            }
        }
    }

    GridView {
        id: grid
        anchors.fill: parent
        cellWidth: 80; cellHeight: 80

        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 grid view. The grid 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.

GridView attaches a number of properties to the root item of the delegate, for example {GridView.isCurrentItem}. In the following example, the root delegate item can access this attached property directly as GridView.isCurrentItem, while the child contactInfo object must refer to this property as wrapper.GridView.isCurrentItem.

GridView {
    width: 300; height: 200
    cellWidth: 80; cellHeight: 80

    Component {
        id: contactsDelegate
        Rectangle {
            id: wrapper
            width: 80
            height: 80
            color: GridView.isCurrentItem ? "black" : "red"
            Text {
                id: contactInfo
                text: name + ": " + number
                color: wrapper.GridView.isCurrentItem ? "red" : "black"
            }
        }
    }

    model: ContactModel {}
    delegate: contactsDelegate
    focus: true
}

Note

Views do not set the Item::clip property automatically. If the view is not clipped by another item or the screen, it will be necessary to set this property to true in order to clip the items that are partially or fully outside the view.

See also

{declarative/modelviews/gridview}{GridView example}

---

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

• /src/declarative/graphicsitems/qdeclarativegridview.cpp