How to expose lists to QML: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(Convert ExpressionEngine links)
(Format code with Qt Creator. Fix some closing braces. Clean up some some auto-generated quote insertion (AFAIK...))
 
(2 intermediate revisions by 2 users not shown)
Line 4: Line 4:
[[Category:Developing_with_Qt::General]]
[[Category:Developing_with_Qt::General]]
[[Category:Tutorial]]
[[Category:Tutorial]]
[toc align_right="yes" depth="2"]
 


'''English''' [[How_to_expose_lists_to_QML_Greek|Ελληνικά]]
'''English''' [[How_to_expose_lists_to_QML_Greek|Ελληνικά]]
Line 12: Line 12:
== Which class to use? ==
== Which class to use? ==


[http://doc.qt.nokia.com/latest/qdeclarativelistproperty.html QDeclarativeListProperty] 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 [http://doc.qt.nokia.com/latest/qlist.html QList ] 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.
[http://doc.qt.io/qt-5/qqmllistproperty.html QDeclarativeListProperty] 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 [http://doc.qt.io/qt-5/qlist.html QList ] 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? ==
== Which constructor to use? ==


QDeclarativeListProperty provides 2 constructors. The [http://doc.qt.nokia.com/latest/qdeclarativelistproperty.html#QDeclarativeListProperty first one] 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.
QDeclarativeListProperty provides 2 constructors. The [http://doc.qt.io/qt-5/qqmllistproperty.html first one] 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 [http://doc.qt.nokia.com/latest/qdeclarativelistproperty.html#QDeclarativeListProperty-3 QDeclarativeListProperty constructor] 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.
The second [http://doc.qt.io/qt-5/qqmllistproperty.html QDeclarativeListProperty constructor] 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 ==
== Example on how to use QDeclarativeListProperty ==


The following example shows how the [http://doc.qt.nokia.com/latest/qdeclarativelistproperty.html#AppendFunction-typedef QDeclarativeListProperty::AppendFunction] and [http://doc.qt.nokia.com/latest/qdeclarativelistproperty.html#ClearFunction-typedef QDeclarativeListProperty::ClearFunction ] can be implemented:
The following example shows how the [http://doc.qt.io/qt-5/qqmllistproperty.html#AppendFunction-typedef QDeclarativeListProperty::AppendFunction] and [http://doc.qt.io/qt-5/qqmllistproperty.html#ClearFunction-typedef QDeclarativeListProperty::ClearFunction ] can be implemented:


<code>
<code>
#include <QtGui>
#include <QtGui>
#include <QtDeclarative>
#include <QtDeclarative>
Line 30: Line 31:
class MyObject : public QObject
class MyObject : public QObject
{
{
Q_OBJECT
    Q_OBJECT
Q_PROPERTY(QDeclarativeListProperty<MyObject> getInfo READ getInfo CONSTANT)
    Q_PROPERTY(QDeclarativeListProperty<MyObject> getInfo READ getInfo CONSTANT)
public:
public:
MyObject()
    MyObject()
{}
    {}
 
   
~MyObject()
    ~MyObject()
{}
    {}
QDeclarativeListProperty<MyObject> getInfo()
    QDeclarativeListProperty<MyObject> getInfo()
{
    {
for (int i = 0; i < 10; +''i)
        for (int i = 0; i < 10; ++i)
{
        {
list << new MyObject();
            list << new MyObject();
}
        }
return QDeclarativeListProperty<MyObject>(this, 0, &amp;MyObject::appendObject, 0, 0, &amp;MyObject::clearObject);
        return QDeclarativeListProperty<MyObject>(this, 0, &MyObject::appendObject, 0, 0, &MyObject::clearObject);
}
    }
static void appendObject(QDeclarativeListProperty<MyObject> *l, MyObject *obj)
    static void appendObject(QDeclarativeListProperty<MyObject> *l, MyObject *obj)
{
    {
MyObject '''object = qobject_cast<MyObject'''>(l->object);
        MyObject object = qobject_cast<MyObject>(l->object);
if (object)
        if (object)
object->list << obj;
            object->list << obj;
}
    }
static void clearObject(QDeclarativeListProperty<MyObject> *l)
    static void clearObject(QDeclarativeListProperty<MyObject> *l)
{
    {
MyObject '''object = qobject_cast<MyObject'''>(l->object);
        MyObject object = qobject_cast<MyObject>(l->object);
if (object) {
        if (object) {
foreach (MyObject '''o, object->list)
            foreach (MyObject o, object->list) {
delete o;
                delete o;
object->list.clear();
                object->list.clear();
}
            }
}
        }
QList<MyObject'''> list;
        QList<MyObject> list;
    }
};  
};  


Line 68: Line 70:
int main(int argc, char** argv)
int main(int argc, char** argv)
{
{
QApplication app(argc, argv);
    QApplication app(argc, argv);
QDeclarativeView view;
    QDeclarativeView view;
qmlRegisterType<MyObject>("QtQuick", 1, 0, "MyObject");
    qmlRegisterType<MyObject>("QtQuick", 1, 0, "MyObject");
view.setSource(QUrl::fromLocalFile("test.qml"));
    view.setSource(QUrl::fromLocalFile("test.qml"));
view.show();
    view.show();
return app.exec();
    return app.exec();
}
}
</code>
</code>
Line 85: Line 87:


Rectangle {
Rectangle {
id: page
    id: page
width: 500; height: 200
    width: 500; height: 200
color: "red"  
    color: "red"  
 
   
MyObject
    MyObject
{
    {
id: myObject
        id: myObject
Component.onCompleted: {
        Component.onCompleted: {
print("completed…"'' myObject.getInfo);
            print("completed…", myObject.getInfo);
 
           
for (var i=0; i<100; ++i) {
            for (var i=0; i<100; ++i) {
myObject.getInfo = [];
                myObject.getInfo = [];
}
            }
}
        }
}
    }
}
}
</code>
</code>
Line 105: Line 107:
Note that in order to clear it, it is necessary to do:
Note that in order to clear it, it is necessary to do:


<code>myObject.getInfo = []<code>
<code>myObject.getInfo = []</code>


as Javascript doesn't know when to clear it otherwise.
as Javascript doesn't know when to clear it otherwise.


The Qt documentation provides the following [http://doc.qt.nokia.com/latest/declarative-tutorials-extending-chapter5-listproperties.html example] that can be useful to have a look at as well.
The Qt documentation provides the following [http://doc.qt.io/qt-5/qqmllistproperty.html example] that can be useful to have a look at as well.


== Dynamic alteration of lists ==
== 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.
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.

Latest revision as of 18:55, 9 December 2015

This article may require cleanup to meet the Qt Wiki's quality standards. Reason: Auto-imported from ExpressionEngine.
Please improve this article if you can. Remove the {{cleanup}} tag and add this page to Updated pages list after it's clean.


English Ελληνικά

How to expose lists to QML

Which class to use?

QDeclarativeListProperty 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 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 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 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 and QDeclarativeListProperty::ClearFunction can be implemented:

#include <QtGui>
#include <QtDeclarative>

class MyObject : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QDeclarativeListProperty<MyObject> getInfo READ getInfo CONSTANT)
public:
    MyObject()
    {}
    
    ~MyObject()
    {}
    QDeclarativeListProperty<MyObject> getInfo()
    {
        for (int i = 0; i < 10; ++i)
        {
            list << new MyObject();
        }
        return QDeclarativeListProperty<MyObject>(this, 0, &MyObject::appendObject, 0, 0, &MyObject::clearObject);
    }
    static void appendObject(QDeclarativeListProperty<MyObject> *l, MyObject *obj)
    {
        MyObject object = qobject_cast<MyObject>(l->object);
        if (object)
            object->list << obj;
    }
    static void clearObject(QDeclarativeListProperty<MyObject> *l)
    {
        MyObject object = qobject_cast<MyObject>(l->object);
        if (object) {
            foreach (MyObject o, object->list) {
                delete o;
                object->list.clear();
            }
        }
        QList<MyObject> list;
    }
}; 

#include "main.moc" 

int main(int argc, char** argv)
{
    QApplication app(argc, argv);
    QDeclarativeView view;
    qmlRegisterType<MyObject>("QtQuick", 1, 0, "MyObject");
    view.setSource(QUrl::fromLocalFile("test.qml"));
    view.show();
    return app.exec();
}

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.

import QtQuick 1.0 

Rectangle {
    id: page
    width: 500; height: 200
    color: "red" 
    
    MyObject
    {
        id: myObject
        Component.onCompleted: {
            print("completed…", myObject.getInfo);
            
            for (var i=0; i<100; ++i) {
                myObject.getInfo = [];
            }
        }
    }
}

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 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.