Home · All Classes · All Functions · Overviews

QML ListView Element Reference

[Inherits Flickable]

The ListView item provides a list 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 vertically or horizontally and may be flicked to scroll.

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

The user interface defines a delegate to display an item, a highlight, and the ListView which uses the above.

 Rectangle {
     width: 180; height: 200; 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: 180; height: 40
             Column {
                 x: 5; y: 5
                 Text { text: '<b>Name:</b> ' + name }
                 Text { text: '<b>Number:</b> ' + number }
             }
         }
     }
     // 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 list
     ListView {
         width: parent.width; height: parent.height
         model: ContactModel
         delegate: delegate
         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"
     }
     ListElement {
         name: "John Brown"
         number: "555 8426"
     }
     ListElement {
         name: "Sam Wise"
         number: "555 0473"
     }
 }

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 list and below the bottom of the list to cache. Setting this value can make scrolling the list smoother at the expense of additional memory usage.


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.


currentSection : string

This property holds the section that is currently at the beginning of 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 ListView 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: 180; height: 40
             Column {
                 x: 5; y: 5
                 Text { text: '<b>Name:</b> ' + name }
                 Text { text: '<b>Number:</b> ' + number }
             }
         }
     }

highlight : component

This property holds the component to use as the highlight.

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

The below example demonstrates how to make a simple highlight for a vertical list.

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

See also highlightItem and highlightFollowsCurrentItem.


highlightFollowsCurrentItem : bool

This property holds 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. The following example creates a highlight with its motion defined by the spring SpringFollow:

     Component {
         id: highlight
         Rectangle {
             width: 180; height: 40
             color: "lightsteelblue"; radius: 5
             y: SpringFollow {
                 source: list.currentItem.y
                 spring: 3
                 damping: 0.2
             }
         }
     }
     ListView {
         id: list
         width: parent.height; height: parent.height
         model: ContactModel; delegate: delegate
         highlight: highlight
         highlightFollowsCurrentItem: false
         focus: true
     }

Note that the highlight animation also affects the way that the view is scrolled. This is because the view moves to maintain the highlight within the preferred highlight range (or visible viewport).

See also highlight and highlightMoveSpeed.


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.


highlightMoveSpeed : real
highlightResizeSpeed : real

These properties hold the move and resize animation speed of the highlight delegate.

highlightFollowsCurrentItem must be true for these properties to have effect.

The default value for these properties is 400 pixels/second.

See also highlightFollowsCurrentItem.


keyNavigationWraps : bool

This property holds whether the list wraps key navigation

If this property is true then key presses to move off of one end of the list will cause the current item to jump to the other end.


model : model

This property holds the model providing data for the list.

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 or a simple list.

Models can also be created directly in QML, using a ListModel, XmlListModel or VisualItemModel.

See also Data Models.


orientation : enumeration

This property holds the orientation of the list.

Possible values are Vertical (default) and Horizontal.

Vertical Example:

Horizontal Example:


preferredHighlightBegin : real
preferredHighlightEnd : real
highlightRangeMode : enumeration

These properties set the preferred range of the highlight (current item) within the view.

Note that this is the correct way to influence where the current item ends up when the list scrolls. For example, if you want the currently selected item to be in the middle of the list, then set the highlight range to be where the middle item would go. Then, when the list scrolls, the currently selected item will be the item at that spot. This also applies to when the currently selected item changes - it will scroll to within the preferred highlight range. Furthermore, the behaviour of the current item index will occur whether or not a highlight exists.

If highlightRangeMode is set to ApplyRange the view will attempt to maintain the highlight within the range, however the highlight can move outside of the range at the ends of the list or due to a mouse interaction.

If highlightRangeMode is set to StrictlyEnforceRange the highlight will never move outside of the range. This means that the current item will change if a keyboard or mouse action would cause the highlight to move outside of the range.

The default value is NoHighlightRange.

Note that a valid range requires preferredHighlightEnd to be greater than or equal to preferredHighlightBegin.


section.property : string
section.criteria : enumeration

These properties hold the expression to be evaluated for the section attached property.

section.property hold the name of the property to use to determine the section the item is in.

section.criteria holds the criteria to use to get the section. It can be either:

Each item in the list has attached properties named ListView.section and ListView.prevSection. These may be used to place a section header for related items. The example below assumes that the model is sorted by size of pet. The section expression is the size property. If ListView.section and ListView.prevSection differ, the item will display a section header.

 Rectangle {
     width: 200
     height: 240
     color: "white"
     // MyPets model is defined in dummydata/MyPetsModel.qml
     // The viewer automatically loads files in dummydata/* to assist
     // development without a real data source.
     // This one contains my pets.

     // Define a delegate component that includes a separator for sections.
     Component {
         id: petDelegate
         Item {
             id: wrapper
             width: 200
             // My height is the combined height of the description and the section separator
             height: desc.height
             Item {
                 id: desc
                 x: 5
                 height: layout.height + 4
                 Column {
                     id: layout
                     y: 2
                     Text { text: 'Name: ' + name }
                     Text { text: 'Type: ' + type }
                     Text { text: 'Age: ' + age }
                 }
             }
         }
     }
     // Define a highlight component.  Just one of these will be instantiated
     // by each ListView and placed behind the current item.
     Component {
         id: petHighlight
         Rectangle {
             color: "#FFFF88"
         }
     }
     // The list
     ListView {
         id: myList
         width: 200
         height: parent.height
         model: MyPetsModel
         delegate: petDelegate
         highlight: petHighlight
         // The sectionExpression is simply the size of the pet.
         // We use this to determine which section we are in above.
         section.property: "size"
         section.criteria: ViewSection.FullString
         section.delegate: Rectangle {
             color: "lightsteelblue"
             width: 200
             height: 20
             Text {
                 text: section; font.bold: true
                 x: 2; height: parent.height; verticalAlignment: 'AlignVCenter'
             }
         }
         focus: true
     }
 }


snapMode : enumeration

This property determines where the view will settle following a drag or flick. The allowed values are:


spacing : real

This property holds the spacing to leave between items.


Attached Property Documentation

ListView.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 list.

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

ListView.isCurrentItem : bool

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

It is attached to each instance of the delegate.

This property may be used to adjust the appearance of the current item, for example:

     Component {
         id: delegate
         Item {
             id: wrapper
             width: 180; height: 40
             Column {
                 x: 5; y: 5
                 Text { text: '<b>Name:</b> ' + name }
                 Text { text: '<b>Number:</b> ' + number }
             }
             // Use the ListView.isCurrentItem attached property to
             // indent the item if it is the current item.
             states: [
                 State {
                     name: "Current"
                     when: wrapper.ListView.isCurrentItem
                     PropertyChanges { target: wrapper; x: 10 }
                 }
             ]
             transitions: [
                 Transition { NumberAnimation { matchProperties: "x"; duration: 200 } }
             ]
         }
     }

ListView.prevSection : string

This attached property holds the section of the previous element.

It is attached to each instance of the delegate.

The section is evaluated using the section properties.


ListView.section : string

This attached property holds the section of this element.

It is attached to each instance of the delegate.

The section is evaluated using the section properties.


ListView.view : ListView

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

It is attached to each instance of the delegate.


Attached Signal Documentation

ListView::onAdd ()

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


ListView::onRemove ()

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


Method Documentation

ListView::decrementCurrentIndex ()

Decrements the current index. The current index will wrap if keyNavigationWraps is true and it is currently at the beginning.


ListView::incrementCurrentIndex ()

Increments the current index. The current index will wrap if keyNavigationWraps is true and it is currently at the end.


ListView::positionViewAtIndex ( int index )

Positions the view such that the index is at the top (or left for horizontal orientation) of the view. If positioning the view at the index would cause empty space to be displayed at the end of the view, the view will be positioned at the end.



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