How to expose lists to QML
[toc align_right="yes" depth="2"]
English Ελληνικά
How to expose lists to QML
Which class to use?
"QDeclarativeListProperty":http://doc.qt.nokia.com/latest/qdeclarativelistproperty.html allows you to expose list like properties to QML. When implementing the function pointers in this class, memory management will be taken care of for you and the bindings will work correctly as well. Using a standard "QList ":http://doc.qt.nokia.com/latest/qlist.html instead of QDeclarativeListProperty, will not take care of memory management and can cause your application to leak. In addition QList does not provide notification signals when children change. So when simply using a QList, the bindings won't work properly either. QDeclarativeListProperty is hence the recommended class to use for lists in QML.
Which constructor to use?
QDeclarativeListProperty provides 2 constructors. The "first one":http://doc.qt.nokia.com/latest/qdeclarativelistproperty.html#QDeclarativeListProperty taking a QList is there for convenience and should only be used for prototyping since it does not clean up memory for you. It still connects up the bindings properly and is therefore recommended over using a simple QList.
The second "QDeclarativeListProperty constructor":http://doc.qt.nokia.com/latest/qdeclarativelistproperty.html#QDeclarativeListProperty-3 constructs a QDeclarativeListProperty from a set of operation functions. It works by passing functions to be called when appending, clearing, counting and getting the current position, but only the append function is necessary to implement. This is the constructor you should use in production code.
Example on how to use QDeclarativeListProperty
The following example shows how the "QDeclarativeListProperty::AppendFunction":http://doc.qt.nokia.com/latest/qdeclarativelistproperty.html#AppendFunction-typedef and "QDeclarativeListProperty::ClearFunction ":http://doc.qt.nokia.com/latest/qdeclarativelistproperty.html#ClearFunction-typedef can be implemented:
<br />#include <QtGui&gt;<br />#include <QtDeclarative&gt;
class MyObject : public QObject<br />{<br /> Q_OBJECT<br /> Q_PROPERTY(QDeclarativeListProperty&lt;MyObject&gt; getInfo READ getInfo CONSTANT)<br />public:<br /> MyObject()<br /> {}
~MyObject()<br /> {}<br /> QDeclarativeListProperty&lt;MyObject&gt; getInfo()<br /> {<br /> for (int i = 0; i < 10; +''i)<br /> {<br /> list << new MyObject();<br /> }<br /> return QDeclarativeListProperty&lt;MyObject&gt;(this, 0, &MyObject::appendObject, 0, 0, &MyObject::clearObject);<br /> }<br /> static void appendObject(QDeclarativeListProperty&lt;MyObject&gt; *l, MyObject *obj)<br /> {<br /> MyObject '''object = qobject_cast&lt;MyObject'''>(l->object);<br /> if (object)<br /> object->list << obj;<br /> }<br /> static void clearObject(QDeclarativeListProperty&lt;MyObject&gt; *l)<br /> {<br /> MyObject '''object = qobject_cast&lt;MyObject'''>(l->object);<br /> if (object) {<br /> foreach (MyObject '''o, object->list)<br /> delete o;<br /> object->list.clear();<br /> }<br /> }<br /> QList&lt;MyObject'''> list;<br />};
<br />#include "main.moc&quot;
<br />int main(int argc, char** argv)<br />{<br /> QApplication app(argc, argv);<br /> QDeclarativeView view;<br /> qmlRegisterType&lt;MyObject&gt;("QtQuick&quot;, 1, 0, "MyObject&quot;);<br /> view.setSource(QUrl::fromLocalFile&amp;#40;"test.qml&quot;&#41;);<br /> view.show();<br /> return app.exec&amp;#40;&#41;;<br />}<br />
Due to the way that QDeclarativeListProperty works it is necessary to keep the QList around while the property is valid which is why it is a member of the class here.
The following QML file shows how the class above can be used and cleared in qml.
<br />import QtQuick 1.0
<br />Rectangle {<br /> id: page<br /> width: 500; height: 200<br /> color: "red&quot;
<br /> MyObject<br /> {<br /> id: myObject<br /> Component.onCompleted: {<br /> print("completed…"'' myObject.getInfo);
for (var i=0; i&lt;100; ++i) {<br /> myObject.getInfo = [];<br /> }<br /> }<br /> }<br />}<br />
Note that in order to clear it, it is necessary to do:
myObject.getInfo = []
as Javascript doesn't know when to clear it otherwise.
The Qt documentation provides the following "example":http://doc.qt.nokia.com/latest/declarative-tutorials-extending-chapter5-listproperties.html that can be useful to have a look at as well.
Dynamic alteration of lists
Dynamic alteration of lists is not well supported right now, due to issues with bindings and lists. The current way to alter a list is to assign a new list in its place.