![]() |
Home · All Classes · All Functions · Overviews |
[Inherits Flickable]
The ListView item provides a list view of items provided by a model. More...
|
|
|
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.
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 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.
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 } } } }
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.
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.
This property holds the orientation of the list.
Possible values are Vertical (default) and Horizontal.
Vertical Example:
Horizontal Example:
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 } }
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.
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.
This attached property holds the view that manages this delegate instance.
It is attached to each instance of the delegate.
This attached handler is called immediately before an item is removed from the view.
Decrements the current index. The current index will wrap if keyNavigationWraps is true and it is currently at the beginning.
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 |