QML Data Models

QML items such as ListView, GridView and Repeater require Data Models that provide the data to be displayed. These items typically require a delegate component that creates an instance for each item in the model. Models may be static, or have items modified, inserted, removed or moved dynamically.

Data is provided to the delegate via named data roles which the delegate may bind to. Here is a ListModel with two roles, type and age, and a ListView with a delegate that binds to these roles to display their values:

 import QtQuick 1.0

 Item {
     width: 200; height: 250

     ListModel {
         id: myModel
         ListElement { type: "Dog"; age: 8 }
         ListElement { type: "Cat"; age: 5 }
     }

     Component {
         id: myDelegate
         Text { text: type + ", " + age }
     }

     ListView {
         anchors.fill: parent
         model: myModel
         delegate: myDelegate
     }
 }

If there is a naming clash between the model's properties and the delegate's properties, the roles can be accessed with the qualified model name instead. For example, if a Text element had type or age properties, the text in the above example would display those property values instead of the type and age values from the model item. In this case, the properties could have been referenced as model.type and model.age instead to ensure the delegate displays the property values from the model item.

A special index role containing the index of the item in the model is also available to the delegate. Note this index is set to -1 if the item is removed from the model. If you bind to the index role, be sure that the logic accounts for the possibility of index being -1, i.e. that the item is no longer valid. (Usually the item will shortly be destroyed, but it is possible to delay delegate destruction in some views via a delayRemove attached property.)

Models that do not have named roles (such as the QStringList model shown below) will have the data provided via the modelData role. The modelData role is also provided for models that have only one role. In this case the modelData role contains the same data as the named role.

QML provides several types of data models among the built-in set of QML elements. In addition, models can be created with C++ and then made available to QML components.

The views used to access data models are described in the Presenting Data with Views overview. The use of positioner items to arrange items from a model is covered in Using QML Positioner and Repeater Items.

 ListModel {
     id: fruitModel

     ListElement {
         name: "Apple"
         cost: 2.45
     }
     ListElement {
         name: "Orange"
         cost: 3.25
     }
     ListElement {
         name: "Banana"
         cost: 1.95
     }
 }

 ListView {
     anchors.fill: parent
     model: fruitModel
     delegate: Row {
         Text { text: "Fruit: " + name }
         Text { text: "Cost: $" + cost }
     }
 }

 ListModel { id: fruitModel }
     ...
 MouseArea {
     anchors.fill: parent
     onClicked: fruitModel.append({"cost": 5.95, "name":"Pizza"})
 }

 XmlListModel {
      id: feedModel
      source: "http://rss.news.yahoo.com/rss/oceania"
      query: "/rss/channel/item"
      XmlRole { name: "title"; query: "title/string()" }
      XmlRole { name: "link"; query: "link/string()" }
      XmlRole { name: "description"; query: "description/string()" }
 }

 VisualItemModel {
     id: itemModel
     Rectangle { height: 30; width: 80; color: "red" }
     Rectangle { height: 30; width: 80; color: "green" }
     Rectangle { height: 30; width: 80; color: "blue" }
 }

 ListView {
     anchors.fill: parent
     model: itemModel
 }

     QStringList dataList;
     dataList.append("Item 1");
     dataList.append("Item 2");
     dataList.append("Item 3");
     dataList.append("Item 4");

     QDeclarativeContext *ctxt = viewer.rootContext();
     ctxt->setContextProperty("myModel", QVariant::fromValue(dataList));

 class DataObject : public QObject
 {
     Q_OBJECT

     Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged)
     Q_PROPERTY(QString color READ color WRITE setColor NOTIFY colorChanged)
     ...
 };

 int main(int argc, char ** argv)
 {
     QApplication app(argc, argv);
     QmlApplicationViewer viewer;

     QList<QObject*> dataList;
     dataList.append(new DataObject("Item 1", "red"));
     dataList.append(new DataObject("Item 2", "green"));
     dataList.append(new DataObject("Item 3", "blue"));
     dataList.append(new DataObject("Item 4", "yellow"));

     QDeclarativeContext *ctxt = viewer.rootContext();
     ctxt->setContextProperty("myModel", QVariant::fromValue(dataList));
     ...

 class Animal
 {
 public:
     Animal(const QString &type, const QString &size);
     ...
 };

 class AnimalModel : public QAbstractListModel
 {
     Q_OBJECT
 public:
     enum AnimalRoles {
         TypeRole = Qt::UserRole + 1,
         SizeRole
     };

     AnimalModel(QObject *parent = 0);
     ...
 };

 AnimalModel::AnimalModel(QObject *parent)
     : QAbstractListModel(parent)
 {
     QHash<int, QByteArray> roles;
     roles[TypeRole] = "type";
     roles[SizeRole] = "size";
     setRoleNames(roles);
 }

 int main(int argc, char ** argv)
 {
     QApplication app(argc, argv);
     QmlApplicationViewer viewer;

     AnimalModel model;
     model.addAnimal(Animal("Wolf", "Medium"));
     model.addAnimal(Animal("Polar bear", "Large"));
     model.addAnimal(Animal("Quoll", "Small"));

     QDeclarativeContext *ctxt = viewer.rootContext();
     ctxt->setContextProperty("myModel", &model);
     ...

 class MyModelPlugin : public QDeclarativeExtensionPlugin
 {
 public:
     void registerTypes(const char *uri)
     {
         qmlRegisterType<MyModel>(uri, 1, 0,
                 "MyModel");
     }
 }

 Q_EXPORT_PLUGIN2(mymodelplugin, MyModelPlugin);

 MyModel {
     id: myModel
     ListElement { someProperty: "some value" }
 }

 ListView {
     width: 200; height: 250
     model: myModel
     delegate: Text { text: someProperty }
 }

 Item {
     width: 200; height: 250

     Component {
         id: itemDelegate
         Text { text: "I am item number: " + index }
     }

     ListView {
         anchors.fill: parent
         model: 5
         delegate: itemDelegate
     }

 }

 Rectangle {
     width: 200; height: 250

     Text {
         id: myText
         text: "Hello"
         color: "#dd44ee"
     }

     Component {
         id: myDelegate
         Text { text: model.color }
     }

     ListView {
         anchors.fill: parent
         anchors.topMargin: 30
         model: myText
         delegate: myDelegate
     }
 }

 Rectangle {
      width: 200; height: 200

     ListModel {
         id: fruitModel
         property string language: "en"
         ListElement {
             name: "Apple"
             cost: 2.45
         }
         ListElement {
             name: "Orange"
             cost: 3.25
         }
         ListElement {
             name: "Banana"
             cost: 1.95
         }
     }

     Component {
         id: fruitDelegate
         Row {
                 Text { text: " Fruit: " + name; color: ListView.view.fruit_color }
                 Text { text: " Cost: $" + cost }
                 Text { text: " Language: " + ListView.view.model.language }
         }
     }

     ListView {
         property color fruit_color: "green"
         model: fruitModel
         delegate: fruitDelegate
         anchors.fill: parent
     }
 }

         setData(int row, const QString & field_name, QVariant new_value),

         ListView.view.model.setData(index, field, value)