Home · All Classes · All Functions · Overviews

QML GridView Element Reference

[Inherits Flickable]

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

Properties

Attached Properties

Attached Signals

Methods

Detailed Description

The model is typically provided by a QAbstractListModel "C++ model object", but can also be created directly in QML.

The items are laid out top to bottom (vertically) or left to right (horizontally) and may be flicked to scroll.

The below example creates a very simple grid, using a QML model.

 Rectangle {
     width: 240; height: 180; color: "white"
     // ContactModel model is defined in dummydata/ContactModel.qml
     // The viewer automatically loads files in dummydata/* to assist
     // development without a real data source.

     // Define a delegate component.  A component will be
     // instantiated for each visible item in the list.
     Component {
         id: delegate
         Item {
             id: wrapper
             width: 80; height: 78
             Column {
                 Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter }
                 Text { text: name; anchors.horizontalCenter: parent.horizontalCenter }
             }
         }
     }
     // Define a highlight component.  Just one of these will be instantiated
     // by each ListView and placed behind the current item.
     Component {
         id: highlight
         Rectangle {
             color: "lightsteelblue"
             radius: 5
         }
     }
     // The actual grid
     GridView {
         width: parent.width; height: parent.height
         model: ContactModel; delegate: delegate
         cellWidth: 80; cellHeight: 80
         highlight: highlight
         focus: true
     }
 }

The model is defined as a ListModel using QML:

 import Qt 4.6

 ListModel {
     id: contactModel
     ListElement {
         name: "Bill Smith"
         number: "555 3264"
         portrait: "pics/portrait.png"
     }
     ListElement {
         name: "Jim Williams"
         number: "555 5673"
         portrait: "pics/portrait.png"
     }
     ListElement {
         name: "John Brown"
         number: "555 8426"
         portrait: "pics/portrait.png"
     }
     ListElement {
         name: "Sam Wise"
         number: "555 0473"
         portrait: "pics/portrait.png"
     }
 }

In this case ListModel is a handy way for us to test our UI. In practice the model would be implemented in C++, or perhaps via a SQL data source.


Property Documentation

cacheBuffer : int

This property holds the number of off-screen pixels to cache.

This property determines the number of pixels above the top of the view and below the bottom of the view to cache. Setting this value can make scrolling the view smoother at the expense of additional memory usage.


cellWidth : int
cellHeight : int

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

The default cell size is 100x100.


count : int

This property holds the number of items in the view.


currentIndex : int
currentItem : Item

currentIndex holds the index of the current item. currentItem is the current item. Note that the position of the current item may only be approximate until it becomes visible in the view.


delegate : component

The delegate provides a template defining each item instantiated by the view. The index is exposed as an accessible index property. Properties of the model are also available depending upon the type of Data Model.

Note that the GridView will layout the items based on the size of the root item in the delegate.

Here is an example delegate:

     Component {
         id: delegate
         Item {
             id: wrapper
             width: 80; height: 78
             Column {
                 Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter }
                 Text { text: name; anchors.horizontalCenter: parent.horizontalCenter }
             }
         }
     }

flow : enumeration

This property holds the flow of the grid.

Possible values are LeftToRight (default) and TopToBottom.

If flow is LeftToRight, the view will scroll vertically. If flow is TopToBottom, the view will scroll horizontally.


highlight : component

This property holds the component to use as the highlight.

An instance of the highlight component will be created for each view. The geometry of the resultant component instance will be managed by the view so as to stay with the current item, unless the highlightFollowsCurrentItem property is false.

The below example demonstrates how to make a simple highlight:

     Component {
         id: highlight
         Rectangle {
             color: "lightsteelblue"
             radius: 5
         }
     }

See also highlightItem and highlightFollowsCurrentItem.


highlightFollowsCurrentItem : bool

This property sets whether the highlight is managed by the view.

If highlightFollowsCurrentItem is true, the highlight will be moved smoothly to follow the current item. If highlightFollowsCurrentItem is false, the highlight will not be moved by the view, and must be implemented by the highlight component, for example:

 Component {
     id: myHighlight
     Rectangle {
         id: wrapper; color: "lightsteelblue"; radius: 4; width: 320; height: 60
         y: SpringFollow { source: Wrapper.GridView.view.currentItem.y; spring: 3; damping: 0.2 }
         x: SpringFollow { source: Wrapper.GridView.view.currentItem.x; spring: 3; damping: 0.2 }
     }
 }

highlightItem : Item

highlightItem holds the highlight item, which was created from the highlight component.

The highlightItem is managed by the view unless highlightFollowsCurrentItem is set to false.

See also highlight and highlightFollowsCurrentItem.


keyNavigationWraps : bool

This property holds whether the grid wraps key navigation

If this property is true then key presses to move off of one end of the grid will cause the selection to jump to the other side.


model : model

This property holds the model providing data for the grid.

The model provides a set of data that is used to create the items for the view. For large or dynamic datasets the model is usually provided by a C++ model object. The C++ model object must be a QAbstractItemModel subclass, a VisualModel, or a simple list.

See also Data Models.


Attached Property Documentation

GridView.delayRemove : bool

This attached property holds whether the delegate may be destroyed.

It is attached to each instance of the delegate.

It is sometimes necessary to delay the destruction of an item until an animation completes.

The example below ensures that the animation completes before the item is removed from the grid.

 Component {
     id: myDelegate
     Item {
         id: wrapper
         GridView.onRemove: SequentialAnimation {
             PropertyAction { target: wrapper.GridView; property: "delayRemove"; value: true }
             NumberAnimation { target: wrapper; property: "scale"; to: 0; duration: 250; easing: "easeInOutQuad" }
             PropertyAction { target: wrapper.GridView; property: "delayRemove"; value: false }
         }
     }
 }

GridView.isCurrentItem : bool

This attched property is true if this delegate is the current item; otherwise false.

It is attached to each instance of the delegate.


GridView.view : GridView

This attached property holds the view that manages this delegate instance.

It is attached to each instance of the delegate.


Attached Signal Documentation

GridView::onAdd ()

This attached handler is called immediately after an item is added to the view.


GridView::onRemove ()

This attached handler is called immediately before an item is removed from the view.


Method Documentation

GridView::moveCurrentIndexDown ()

Move the currentIndex down one item in the view. The current index will wrap if keyNavigationWraps is true and it is currently at the end.


GridView::moveCurrentIndexLeft ()

Move the currentIndex left one item in the view. The current index will wrap if keyNavigationWraps is true and it is currently at the end.


GridView::moveCurrentIndexRight ()

Move the currentIndex right one item in the view. The current index will wrap if keyNavigationWraps is true and it is currently at the end.


GridView::moveCurrentIndexUp ()

Move the currentIndex up one item in the view. The current index will wrap if keyNavigationWraps is true and it is currently at the end.



Copyright © 2010 Nokia Corporation and/or its subsidiary(-ies) Trademarks
Qt 4.7.0