Difference between revisions of "How To Use QML ListView"

From Qt Wiki
Jump to: navigation, search
(Add "cleanup" tag)
m (→‎Example: fix typo)
 
(3 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Cleanup | reason=Auto-imported from ExpressionEngine.}}
+
{{Cleanup | reason=Needs to be updated to QtQuick 2}}
 
+
{{LangSwitch}}
 
[[Category:HowTo]]
 
[[Category:HowTo]]
 
[toc align_right="yes" depth="3"]
 
 
= How to Use QML ListView =
 
 
 
== Introduction ==
 
== Introduction ==
  
Line 20: Line 15:
  
 
Main.qml
 
Main.qml
<code>import QtQuick 1.0
+
<code>
 +
import QtQuick 1.0
 +
 
 
Item {
 
Item {
id: rootItem
+
  id: rootItem
// create a model item instance
+
  // create a model item instance
  SampleListModel {
+
   
id: sampleModel
+
  SampleListModel {
}
+
    id: sampleModel
  ListView {
+
  }
id: smapleListView
+
   
anchors.fill: parent
+
  ListView {
// concreate model
+
    id: sampleListView
model: sampleModel
+
    anchors.fill: parent
// provide delegate component.
+
    model: sampleModel              // concrete model
delegate: ExampleDelegate { }
+
    delegate: ExampleDelegate { }  // provide delegate component.
spacing: 4
+
    spacing: 4
}
+
  }
}</code>
+
}
 +
</code>
  
 
Now let's code ExampleDelegate component.
 
Now let's code ExampleDelegate component.
Line 48: Line 46:
 
ExampleDelegate.qml
 
ExampleDelegate.qml
  
<code>import QtQuick 1.0
+
<code>
 +
import QtQuick 1.0
  
 
Rectangle {
 
Rectangle {
id: delegateItem
+
  id: delegateItem
width: parent.width; height: 100
+
  width: parent.width; height: 100
color: "blue"
+
  color: "blue"
  Image {
+
   
id: imageItem
+
  Image {
height: parent.height; width: 100
+
    id: imageItem
anchors.left: parent.left
+
    height: parent.height; width: 100
// deligate can directly ues ListElement role name
+
    anchors.left: parent.left
source: imagePath
+
    // delegate can directly use ListElement role name
}
+
    source: imagePath
  Text {
+
  }
id: itexItem
+
   
anchors.left: imageItem.right
+
  Text {
anchors.leftMargin: 20
+
    id: itexItem
anchors.verticalCenter: parent.verticalCenter
+
    anchors.left: imageItem.right
font.pixelSize: 40
+
    anchors.leftMargin: 20
// deligate can direclty use ListElement role name
+
    anchors.verticalCenter: parent.verticalCenter
text: imageName
+
    font.pixelSize: 40
}
+
    // delegate can directly use ListElement role name
}</code>
+
    text: imageName
 +
  }
 +
}
 +
</code>
  
 
As you can see above, '''imagePath''', and '''imageName''' are not properties of delegateItem, so where are they coming from? They are coming from the model of ListView. '''The magic is that delegate components can access roles of each ListElement it visualizes directly inside it'''.
 
As you can see above, '''imagePath''', and '''imageName''' are not properties of delegateItem, so where are they coming from? They are coming from the model of ListView. '''The magic is that delegate components can access roles of each ListElement it visualizes directly inside it'''.
Line 78: Line 80:
 
=== Example: Delegate Component Embedded in Main QML file ===
 
=== Example: Delegate Component Embedded in Main QML file ===
  
<code>import QtQuick 1.0
+
<code>
 +
import QtQuick 1.0
 +
 
 
Item {
 
Item {
id: rootItem
+
  id: rootItem
Component {
+
 
id: delegateComponent
+
  Component {
Item { ………. }
+
    id: delegateComponent
}
+
    Item { ... }
  ListView {
+
  }
// provide delegate component.
+
   
delegate: delegateComponent
+
  ListView {
}
+
    // provide delegate component.
}</code>
+
    delegate: delegateComponent
 +
  }
 +
}
 +
</code>
  
 
or
 
or
  
<code>import QtQuick 1.0
+
<code>
 +
import QtQuick 1.0
 +
 
 
Item {
 
Item {
id: rootItem
+
  id: rootItem
ListView {
+
  ListView {
// provide delegate component.
+
    // provide delegate component.
delegate: Item {
+
    delegate: Item {
……………
+
      ...
}
+
    }
}
+
  }
}</code>
+
}
 +
</code>
  
 
Now, let's create SimpleListModel model where each row has roles '''imagePath''', and '''imageName'''
 
Now, let's create SimpleListModel model where each row has roles '''imagePath''', and '''imageName'''
Line 116: Line 126:
 
Example:
 
Example:
 
  SampleListModel.qml
 
  SampleListModel.qml
<code>import QtQuick 1.0
+
<code>
 +
import QtQuick 1.0
 +
 
 
ListModel {
 
ListModel {
ListElement { imagePath: "1.jpg"; imageName: "flower"}
+
  ListElement { imagePath: "1.jpg"; imageName: "flower" }
ListElement { imagePath: "2.jpg"; imageName: "house"}
+
  ListElement { imagePath: "2.jpg"; imageName: "house" }
ListElement { imagePath: "3.jpg"; imageName: "water"}
+
  ListElement { imagePath: "3.jpg"; imageName: "water" }
}</code>
+
}
 +
</code>
  
 
The above example defines a simple ListModel which can be used by a ListView. Each ListElement contains list of roles that can be directly accessed inside delegate element of ListView.
 
The above example defines a simple ListModel which can be used by a ListView. Each ListElement contains list of roles that can be directly accessed inside delegate element of ListView.
Line 129: Line 142:
  
 
Example :
 
Example :
<code>ListModel {
+
<code>
id: sampleModel
+
ListModel {
 +
  id: sampleModel
 
}
 
}
…………..
+
...
 
sampleModel.append({"name":"sonia";"age":23})
 
sampleModel.append({"name":"sonia";"age":23})
 
</code>
 
</code>
Line 139: Line 153:
  
 
Example :
 
Example :
<code>ListModel {
+
<code>
id: sampleModel
+
ListModel {
ListElement { imagePath: "image1.jpg"; imageName:"house" }
+
  id: sampleModel
 +
  ListElement { imagePath: "image1.jpg"; imageName:"house" }
 
}
 
}
…………..
+
...
 +
 
 
// insert a new row to model at index 1. Index starts from 0.
 
// insert a new row to model at index 1. Index starts from 0.
 
// This is equivalent to appending at the end as index we provide is 1.
 
// This is equivalent to appending at the end as index we provide is 1.
sampleModel.insert(1,{"name":"sonia";"age":23})
+
sampleModel.insert(1, {"name":"sonia", "age":23})
 
</code>
 
</code>
  
Line 154: Line 170:
 
Example :
 
Example :
 
<code>ListModel {
 
<code>ListModel {
id: sampleModel
+
  id: sampleModel
ListElement { imagePath: "image1.jpg"; imageName:"house" }
+
  ListElement { imagePath: "image1.jpg"; imageName:"house" }
 
}
 
}
…………..
+
...
 
// prints value of imagePath in the first row of sampleModel
 
// prints value of imagePath in the first row of sampleModel
 
console.log(sampleModel.get(0).imagePath)
 
console.log(sampleModel.get(0).imagePath)
Line 164: Line 180:
 
To Modify values of roles of a particular row, use ListModel::set(int index,jsobject dict) method
 
To Modify values of roles of a particular row, use ListModel::set(int index,jsobject dict) method
 
Example :
 
Example :
<code>ListModel {
+
<code>
id: sampleModel
+
ListModel {
ListElement { imagePath: "image1.jpg"; imageName:"house" }
+
  id: sampleModel
 +
  ListElement { imagePath: "image1.jpg"; imageName:"house" }
 
}
 
}
…………..
+
...
sampleModel.set(0,{imagePath: "image2.jpg";imageName:"water"}
+
sampleModel.set(0, {imagePath: "image2.jpg", imageName:"water"})
 
</code>
 
</code>
  
 
To set value of a particular role in a given row, use ListModel::setProperty(int index, string rolename, variant value)
 
To set value of a particular role in a given row, use ListModel::setProperty(int index, string rolename, variant value)
 
Example :
 
Example :
<code>ListModel {
+
<code>
id: sampleModel
+
ListModel {
ListElement { imagePath: "image1.jpg"; imageName:"house" }
+
  id: sampleModel
 +
  ListElement { imagePath: "image1.jpg"; imageName:"house" }
 
}
 
}
…………..
+
...
sampleModel.setProperty(0,"imagePath","image2.jpg"}
+
sampleModel.setProperty(0, "imagePath", "image2.jpg")
 
</code>
 
</code>
  

Latest revision as of 21:29, 8 July 2015

En Ar Bg De El Es Fa Fi Fr Hi Hu It Ja Kn Ko Ms Nl Pl Pt Ru Sq Th Tr Uk Zh

Introduction

ListView provides a way to visualize contents of an one-dimensional model. Data can come from QML model elements like ListModel, XmlListModel, or C++ custom model classes inherited from QAbstractListModel.

ListView has a model property which supplies data to be visualized, and has a delegate property which supplies how ( LAF ) each row in the model is visualized. ListView is provided as a part of model/view paradigm in Qt/Qt Quick.

ListView

ListView element needs to be told about the model to visualize and the delegate component to use to visualize each element of the model. This is done with model and delegate properties of ListView

Example

Main.qml import QtQuick 1.0

Item {

 id: rootItem
 // create a model item instance

 SampleListModel {
   id: sampleModel
 }

 ListView {
   id: sampleListView
   anchors.fill: parent
   model: sampleModel              // concrete model
   delegate: ExampleDelegate { }   // provide delegate component.
   spacing: 4
 }

}

Now let's code ExampleDelegate component.

Delegate

Delegate components provide a way to visualize each row of model provided in ListView. An instance of delegate component is created dynamically for each row.

Example: Separate File with Delegate Component

ExampleDelegate.qml

import QtQuick 1.0

Rectangle {

 id: delegateItem
 width: parent.width; height: 100
 color: "blue"

 Image {
   id: imageItem
   height: parent.height; width: 100
   anchors.left: parent.left
   // delegate can directly use ListElement role name
   source: imagePath
 }

 Text {
   id: itexItem
   anchors.left: imageItem.right
   anchors.leftMargin: 20
   anchors.verticalCenter: parent.verticalCenter
   font.pixelSize: 40
   // delegate can directly use ListElement role name
   text: imageName
 }

}

As you can see above, imagePath, and imageName are not properties of delegateItem, so where are they coming from? They are coming from the model of ListView. The magic is that delegate components can access roles of each ListElement it visualizes directly inside it.

Alternatively, we can place this delegate component in the same .qml file where we have ListView element.

Example: Delegate Component Embedded in Main QML file

import QtQuick 1.0

Item {

 id: rootItem
 
 Component {
   id: delegateComponent
   Item { ... }
 }

 ListView {
   // provide delegate component.
   delegate: delegateComponent
 }

}

or

import QtQuick 1.0

Item {

 id: rootItem
 ListView {
   // provide delegate component.
   delegate: Item {
     ...
   }
 }

}

Now, let's create SimpleListModel model where each row has roles imagePath, and imageName

Different ways of providing Model data

As specified earlier, data for ListView can be provided with QML Model elements like ListModel, XmlListModel or C++ custom classes inherited from QAbstractListModel.

ListModel

ListModel provides a way to specify model data to ListView. Each row in ListModel is constructed with ListElement.

Example:

SampleListModel.qml

import QtQuick 1.0

ListModel {

 ListElement { imagePath: "1.jpg"; imageName: "flower" }
 ListElement { imagePath: "2.jpg"; imageName: "house" }
 ListElement { imagePath: "3.jpg"; imageName: "water" }

}

The above example defines a simple ListModel which can be used by a ListView. Each ListElement contains list of roles that can be directly accessed inside delegate element of ListView. Note: Copy three images with names "1.jpb","2.jpg", and "3.jpg" to folder where you have qml files.

ListModel provides methods to manipulate ListModel from JavaScript. If we start with a empty ListModel, the first item inserted in to ListModel determines the roles that will be available to delegate in ListView.

Example : ListModel {

 id: sampleModel

} ... sampleModel.append({"name":"sonia";"age":23})

Now, roles name, and age will be available inside delegate of ListView. If we append more rows to above model with different roles, they will not be available to delegate.

Example : ListModel {

 id: sampleModel
 ListElement { imagePath: "image1.jpg"; imageName:"house" }

} ...

// insert a new row to model at index 1. Index starts from 0. // This is equivalent to appending at the end as index we provide is 1. sampleModel.insert(1, {"name":"sonia", "age":23})

In the above example, roles name, and age will not be available in delegate. Only roles imagePath, and imageName will be available.

To get row at a given index, use ListModel::get(index) Example : ListModel {

 id: sampleModel
 ListElement { imagePath: "image1.jpg"; imageName:"house" }

} ... // prints value of imagePath in the first row of sampleModel console.log(sampleModel.get(0).imagePath)

To Modify values of roles of a particular row, use ListModel::set(int index,jsobject dict) method Example : ListModel {

 id: sampleModel
 ListElement { imagePath: "image1.jpg"; imageName:"house" }

} ... sampleModel.set(0, {imagePath: "image2.jpg", imageName:"water"})

To set value of a particular role in a given row, use ListModel::setProperty(int index, string rolename, variant value) Example : ListModel {

 id: sampleModel
 ListElement { imagePath: "image1.jpg"; imageName:"house" }

} ... sampleModel.setProperty(0, "imagePath", "image2.jpg")

To move elements inside ListModel use ListModel::move(int from, int to,int n) Moves n items from one position to another.

To remove a row from ListModel use ListModel::remove(index) and to clear all the rows in a model call ListModel.clear()