GridView QML Type

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

import QtQuick 2.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"
    }
}

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 (containing Image and Text items) for its delegate.

import QtQuick 2.0

GridView {
    width: 300; height: 200

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

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 Keyboard Focus in Qt Quick 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
}

The layout of the items in a GridView can be controlled by these properties:

• flow - controls whether items flow from left to right (as a series of rows) or from top to bottom (as a series of columns). This value can be either GridView.FlowLeftToRight or GridView.FlowTopToBottom.

• layoutDirection - controls the horizontal layout direction: that is, whether items are laid out from the left side of the view to the right, or vice-versa. This value can be either Qt.LeftToRight or Qt.RightToLeft.

• verticalLayoutDirection - controls the vertical layout direction: that is, whether items are laid out from the top of the view down towards the bottom of the view, or vice-versa. This value can be either GridView.TopToBottom or GridView.BottomToTop.

By default, a GridView flows from left to right, and items are laid out from left to right horizontally, and from top to bottom vertically.

These properties can be combined to produce a variety of layouts, as shown in the table below. The GridViews in the first row all have a flow value of GridView.FlowLeftToRight, but use different combinations of horizontal and vertical layout directions (specified by layoutDirection and verticalLayoutDirection respectively). Similarly, the GridViews in the second row below all have a flow value of GridView.FlowTopToBottom, but use different combinations of horizontal and vertical layout directions to lay out their items in different ways.

GridViews with GridView.FlowLeftToRight flow
(H) Left to right (V) Top to bottom	(H) Right to left (V) Top to bottom	(H) Left to right (V) Bottom to top	(H) Right to left (V) Bottom to top

GridViews with GridView.FlowTopToBottom flow
(H) Left to right (V) Top to bottom	(H) Right to left (V) Top to bottom	(H) Left to right (V) Bottom to top	(H) Right to left (V) Bottom to top

See also QML Data Models, ListView, PathView, Qt Quick Examples - Views

currentItem : Item

The currentIndex property holds the index of the current item, and currentItem holds the current item. Setting the currentIndex to -1 will clear the highlight and set currentItem to null.

If highlightFollowsCurrentItem is true, setting either of these properties will smoothly scroll the GridView so that the current item becomes visible.

Note that the position of the current item may only be approximate until it becomes visible in the view.

preferredHighlightBegin : real

preferredHighlightEnd : real

These properties define the preferred range of the highlight (for the current item) within the view. The preferredHighlightBegin value must be less than the preferredHighlightEnd value.

These properties affect the position of the current item when the view is scrolled. For example, if the currently selected item should stay in the middle of the view when it is scrolled, set the preferredHighlightBegin and preferredHighlightEnd values to the top and bottom coordinates of where the middle item would be. If the currentItem is changed programmatically, the view will automatically scroll so that the current item is in the middle of the view. Furthermore, the behavior of the current item index will occur whether or not a highlight exists.

Valid values for highlightRangeMode are:

• GridView.ApplyRange - the view attempts to maintain the highlight within the range. However, the highlight can move outside of the range at the ends of the view or due to mouse interaction.

• GridView.StrictlyEnforceRange - the highlight never moves outside of the range. The current item changes if a keyboard or mouse action would cause the highlight to move outside of the range.

• GridView.NoHighlightRange - this is the default value.

[since QtQuick 2.3] displayMarginEnd : int

This property allows delegates to be displayed outside of the view geometry.

If this value is non-zero, the view will create extra delegates before the start of the view, or after the end. The view will create as many delegates as it can fit into the pixel size specified.

For example, if in a vertical view the delegate is 20 pixels high, there are 3 columns, and displayMarginBeginning and displayMarginEnd are both set to 40, then 6 delegates above and 6 delegates below will be created and shown.

The default value is 0.

This property is meant for allowing certain UI configurations, and not as a performance optimization. If you wish to create delegates outside of the view geometry for performance reasons, you probably want to use the cacheBuffer property instead.

This QML property was introduced in QtQuick 2.3.

cellWidth : real

These properties holds the width and height of each cell in the grid.

The default cell size is 100x100.

This property holds the transition to apply to items that are added to the view.

For example, here is a view that specifies such a transition:

GridView {
    ...
    add: Transition {
        NumberAnimation { properties: "x,y"; from: 100; duration: 1000 }
    }
}

Whenever an item is added to the above view, the item will be animated from the position (100,100) to its final x,y position within the view, over one second. The transition only applies to the new items that are added to the view; it does not apply to the items below that are displaced by the addition of the new items. To animate the displaced items, set the displaced or addDisplaced properties.

For more details and examples on how to use view transitions, see the ViewTransition documentation.

See Also▲

This property holds the transition to apply to items within the view that are displaced by the addition of other items to the view.

For example, here is a view that specifies such a transition:

GridView {
    ...
    addDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Whenever an item is added to the above view, all items beneath the new item are displaced, causing them to move down (or sideways, if horizontally orientated) within the view. As this displacement occurs, the items' movement to their new x,y positions within the view will be animated by a NumberAnimation over one second, as specified. This transition is not applied to the new item that has been added to the view; to animate the added items, set the add property.

If an item is displaced by multiple types of operations at the same time, it is not defined as to whether the addDisplaced, moveDisplaced or removeDisplaced transition will be applied. Additionally, if it is not necessary to specify different transitions depending on whether an item is displaced by an add, move or remove operation, consider setting the displaced property instead.

For more details and examples on how to use view transitions, see the ViewTransition documentation.

See Also▲

This property determines whether delegates are retained outside the visible area of the view.

If this value is greater than zero, the view may keep as many delegates instantiated as will fit within the buffer specified. For example, if in a vertical view the delegate is 20 pixels high, there are 3 columns and cacheBuffer is set to 40, then up to 6 delegates above and 6 delegates below the visible area may be created/retained. The buffered delegates are created asynchronously, allowing creation to occur across multiple frames and reducing the likelihood of skipping frames. In order to improve painting performance delegates outside the visible area are not painted.

The default value of this property is platform dependent, but will usually be a value greater than zero. Negative values are ignored.

Note that cacheBuffer is not a pixel buffer - it only maintains additional instantiated delegates.

The cacheBuffer operates outside of any display margins specified by displayMarginBeginning or