Chapter 5: Using List Property Types

Files:

• declarative/tutorials/extending/chapter5-listproperties/app.qml
• declarative/tutorials/extending/chapter5-listproperties/piechart.cpp
• declarative/tutorials/extending/chapter5-listproperties/piechart.h
• declarative/tutorials/extending/chapter5-listproperties/pieslice.cpp
• declarative/tutorials/extending/chapter5-listproperties/pieslice.h
• declarative/tutorials/extending/chapter5-listproperties/main.cpp
• declarative/tutorials/extending/chapter5-listproperties/chapter5-listproperties.pro

Right now, a PieChart can only have one PieSlice. Ideally a chart would have multiple slices, with different colors and sizes. To do this, we could have a slices property that accepts a list of PieSlice items:

 import Charts 1.0
 import QtQuick 1.0

 Item {
     width: 300; height: 200

     PieChart {
         anchors.centerIn: parent
         width: 100; height: 100

         slices: [
             PieSlice {
                 anchors.fill: parent
                 color: "red"
                 fromAngle: 0; angleSpan: 110
             },
             PieSlice {
                 anchors.fill: parent
                 color: "black"
                 fromAngle: 110; angleSpan: 50
             },
             PieSlice {
                 anchors.fill: parent
                 color: "blue"
                 fromAngle: 160; angleSpan: 100
             }
         ]
     }
 }

To do this, we replace the pieSlice property in PieChart with a slices property, declared as a QDeclarativeListProperty type. The QDeclarativeListProperty class enables the creation of list properties in QML extensions. We replace the pieSlice() function with a slices() function that returns a list of slices, and add an internal append_slice() function (discussed below). We also use a QList to store the internal list of slices as m_slices:

 class PieChart : public QDeclarativeItem
 {
     Q_OBJECT
     Q_PROPERTY(QDeclarativeListProperty<PieSlice> slices READ slices)
     ...
 public:
     ...
     QDeclarativeListProperty<PieSlice> slices();

 private:
     static void append_slice(QDeclarativeListProperty<PieSlice> *list, PieSlice *slice);

     QString m_name;
     QList<PieSlice *> m_slices;
 };

Although the slices property does not have an associated WRITE function, it is still modifiable because of the way QDeclarativeListProperty works. In the PieChart implementation, we implement PieChart::slices() to return a QDeclarativeListProperty value and indicate that the internal PieChart::append_slice() function is to be called whenever a request is made from QML to add items to the list:

 QDeclarativeListProperty<PieSlice> PieChart::slices()
 {
     return QDeclarativeListProperty<PieSlice>(this, 0, &PieChart::append_slice);
 }

 void PieChart::append_slice(QDeclarativeListProperty<PieSlice> *list, PieSlice *slice)
 {
     PieChart *chart = qobject_cast<PieChart *>(list->object);
     if (chart) {
         slice->setParentItem(chart);
         chart->m_slices.append(slice);
     }
 }

The append_slice() function simply sets the parent item as before, and adds the new item to the m_slices list. As you can see, the append function for a QDeclarativeListProperty is called with two arguments: the list property, and the item that is to be appended.

The PieSlice class has also been modified to include fromAngle and angleSpan properties and to draw the slice according to these values. This is a straightforward modification if you have read the previous pages in this tutorial, so the code is not shown here.

The complete code can be seen in the updated examples/tutorials/extending/chapter5-listproperties directory.