ListView QML Type▲
-
Import Statement: import QtQuick 2.13
-
Inherits: Flickable
-
Group: ListView is part of qtquick-views
Detailed Description▲
A ListView displays data from models created from built-in QML types like ListModel and XmlListModel, or custom model classes defined in C++ that inherit from QAbstractItemModel or QAbstractListModel.
A ListView has a model, which defines the data to be displayed, and a delegate, which defines how the data should be displayed. Items in a ListView are laid out horizontally or vertically. List views are inherently flickable because ListView 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 2.0
ListModel
{
ListElement
{
name
:
"Bill Smith"
number
:
"555 3264"
}
ListElement
{
name
:
"John Brown"
number
:
"555 8426"
}
ListElement
{
name
:
"Sam Wise"
number
:
"555 0473"
}
}
Another component can display this model data in a ListView, like this:
import
QtQuick 2.0
ListView
{
width
:
180
; height
:
200
model
:
ContactModel {}
delegate
:
Text
{
text
:
name
+
": "
+
number
}
}

Here, the ListView creates a ContactModel component for its model, and a Text item for its delegate. The view will create a new Text component for each item in the model. Notice the delegate is able to access the model's name and number data directly.
An improved list view is shown below. The delegate is visually improved and is moved into a separate contactDelegate component.
Rectangle
{
width
:
180
; height
:
200
Component
{
id
:
contactDelegate
Item
{
width
:
180
; height
:
40
Column
{
Text
{
text
:
'<b>Name:</b> '
+
name
}
Text
{
text
:
'<b>Number:</b> '
+
number }
}
}
}
ListView
{
anchors.fill
:
parent
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 list view. The list 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. They are parented to ListView's contentItem, not to the view itself. State should never be stored in a delegate.
ListView attaches a number of properties to the root item of the delegate, for example ListView.isCurrentItem. In the following example, the root delegate item can access this attached property directly as ListView.isCurrentItem, while the child contactInfo object must refer to this property as wrapper.ListView.isCurrentItem.
ListView
{
width
:
180
; height
:
200
Component
{
id
:
contactsDelegate
Rectangle
{
id
:
wrapper
width
:
180
height
:
contactInfo.height
color
:
ListView.isCurrentItem ? "black"
:
"red"
Text
{
id
:
contactInfo
text
:
name
+
": "
+
number
color
:
wrapper.ListView.isCurrentItem ? "red"
:
"black"
}
}
}
model
:
ContactModel {}
delegate
:
contactsDelegate
focus
:
true
}
Views do not enable clip automatically. If the view is not clipped by another item or the screen, it will be necessary to set clip: true in order to have the out of view items clipped nicely.
ListView Layouts▲
The layout of the items in a ListView can be controlled by these properties:
-
orientation - controls whether items flow horizontally or vertically. This value can be either Qt.Horizontal or Qt.Vertical.
-
layoutDirection - controls the horizontal layout direction for a horizontally-oriented view: 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 for a vertically-oriented view: 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 ListView.TopToBottom or ListView.BottomToTop.
By default, a ListView has a vertical orientation, and items are laid out from top to bottom. The table below shows the different layouts that a ListView can have, depending on the values of the properties listed above.
ListViews with Qt.Vertical orientation |
|
---|---|
Top to bottom ![]() |
Bottom to top ![]() |
ListViews with Qt.Horizontal orientation |
|
---|---|
Left to right ![]() |
Right to left ![]() |
Flickable Direction▲
By default, a vertical ListView sets flickableDirection to Flickable.Vertical, and a horizontal ListView sets it to Flickable.Horizontal. Furthermore, a vertical ListView only calculates (estimates) the contentHeight, and a horizontal ListView only calculates the contentWidth. The other dimension is set to -1.
Since Qt 5.9 (Qt Quick 2.9), it is possible to make a ListView that can be flicked to both directions. In order to do this, the flickableDirection can be set to Flickable.AutoFlickDirection or Flickable.AutoFlickIfNeeded, and the desired contentWidth or contentHeight must be provided.
ListView
{
width
:
180
; height
:
200
contentWidth
:
320
flickableDirection
:
Flickable.AutoFlickDirection
model
:
ContactModel {}
delegate
:
Row
{
Text
{
text
:
'<b>Name:</b> '
+
name
; width
: