diff options
author | Bea Lam <bea.lam@nokia.com> | 2010-03-02 02:07:40 (GMT) |
---|---|---|
committer | Bea Lam <bea.lam@nokia.com> | 2010-03-02 02:07:40 (GMT) |
commit | 8da93faace82eb2bc86e76c0ad0a0c5c95e3b8bf (patch) | |
tree | 1559fc7e2fb0b983979d5e2d9abc53c16cede957 /src | |
parent | 5bfe57bbd1e6055e9b2d70d0b4c28052fefce430 (diff) | |
download | Qt-8da93faace82eb2bc86e76c0ad0a0c5c95e3b8bf.zip Qt-8da93faace82eb2bc86e76c0ad0a0c5c95e3b8bf.tar.gz Qt-8da93faace82eb2bc86e76c0ad0a0c5c95e3b8bf.tar.bz2 |
Add docs and tests for WorkerListModel.
Task-number: QT-2807
Diffstat (limited to 'src')
-rw-r--r-- | src/declarative/qml/qdeclarativeworkerscript.cpp | 137 | ||||
-rw-r--r-- | src/declarative/qml/qdeclarativeworkerscript_p.h | 9 |
2 files changed, 143 insertions, 3 deletions
diff --git a/src/declarative/qml/qdeclarativeworkerscript.cpp b/src/declarative/qml/qdeclarativeworkerscript.cpp index 03151e4..c1d090e 100644 --- a/src/declarative/qml/qdeclarativeworkerscript.cpp +++ b/src/declarative/qml/qdeclarativeworkerscript.cpp @@ -841,6 +841,41 @@ bool QDeclarativeWorkerListModelAgent::event(QEvent *e) return QObject::event(e); } +/*! + \qmlclass WorkerListModel QDeclarativeWorkerListModel + \brief The WorkerListModel element provides a threaded list model. + + Use WorkerListModel together with WorkerScript to define a list model + that is controlled by a separate thread. This is useful if list modification + operations are synchronous and take some time: using WorkerListModel + moves these operations to a different thread and avoids blocking of the + main GUI thread. + + The thread that creates the WorkerListModel can modify the model for any + initial set-up requirements. However, once the model has been modified by + the associated WorkerScript, the model can only be modified by that worker + script and becomes read-only to all other threads. + + Here is an example application that uses WorkerScript to append the + current time to a WorkerListModel: + + \snippet examples/declarative/workerlistmodel/timedisplay.qml 0 + + The included file, \tt dataloader.js, looks like this: + + \snippet examples/declarative/workerlistmodel/dataloader.js 0 + + The application's \tt Timer object periodically sends a message to the + worker script by calling \tt WorkerScript::sendMessage(). When this message + is received, \tt WorkerScript.onMessage() is invoked in + \tt dataloader.js, which appends the current time to the worker list + model. + + Note that unlike ListModel, WorkerListModel does not have \tt move() and + \tt setProperty() methods. + + \sa WorkerScript, ListModel +*/ QDeclarativeWorkerListModel::QDeclarativeWorkerListModel(QObject *parent) : QListModelInterface(parent), m_agent(0) { @@ -854,6 +889,14 @@ QDeclarativeWorkerListModel::~QDeclarativeWorkerListModel() } } +/*! + \qmlmethod WorkerListModel::clear() + + Deletes all content from the model. The properties are cleared such that + different properties may be set on subsequent additions. + + \sa append() remove() +*/ void QDeclarativeWorkerListModel::clear() { if (m_agent) { @@ -869,6 +912,13 @@ void QDeclarativeWorkerListModel::clear() } } +/*! + \qmlmethod WorkerListModel::remove(int index) + + Deletes the content at \a index from the model. + + \sa clear() +*/ void QDeclarativeWorkerListModel::remove(int index) { if (m_agent) { @@ -884,6 +934,18 @@ void QDeclarativeWorkerListModel::remove(int index) emit countChanged(); } +/*! + \qmlmethod WorkerListModel::append(jsobject dict) + + Adds a new item to the end of the list model, with the + values in \a dict. + + \code + FruitModel.append({"cost": 5.95, "name":"Pizza"}) + \endcode + + \sa set() remove() +*/ void QDeclarativeWorkerListModel::append(const QScriptValue &value) { if (m_agent) { @@ -914,6 +976,21 @@ void QDeclarativeWorkerListModel::append(const QScriptValue &value) emit countChanged(); } +/*! + \qmlmethod WorkerListModel::insert(int index, jsobject dict) + + Adds a new item to the list model at position \a index, with the + values in \a dict. + + \code + FruitModel.insert(2, {"cost": 5.95, "name":"Pizza"}) + \endcode + + The \a index must be to an existing item in the list, or one past + the end of the list (equivalent to append). + + \sa set() append() +*/ void QDeclarativeWorkerListModel::insert(int index, const QScriptValue &value) { if (m_agent) { @@ -946,6 +1023,30 @@ void QDeclarativeWorkerListModel::insert(int index, const QScriptValue &value) emit countChanged(); } +/*! + \qmlmethod object ListModel::get(int index) + + Returns the item at \a index in the list model. + + \code + FruitModel.append({"cost": 5.95, "name":"Jackfruit"}) + FruitModel.get(0).cost + \endcode + + The \a index must be an element in the list. + + Note that properties of the returned object that are themselves objects + will also be models, and this get() method is used to access elements: + + \code + FruitModel.append(..., "attributes": + [{"name":"spikes","value":"7mm"}, + {"name":"color","value":"green"}]); + FruitModel.get(0).attributes.get(1).value; // == "green" + \endcode + + \sa append() +*/ QScriptValue QDeclarativeWorkerListModel::get(int index) const { QDeclarativeEngine *engine = qmlEngine(this); @@ -962,6 +1063,21 @@ QScriptValue QDeclarativeWorkerListModel::get(int index) const return rv; } +/*! + \qmlmethod WorkerListModel::set(int index, jsobject dict) + + Changes the item at \a index in the list model with the + values in \a dict. Properties not appearing in \a valuemap + are left unchanged. + + \code + FruitModel.set(3, {"cost": 5.95, "name":"Pizza"}) + \endcode + + The \a index must be an element in the list. + + \sa append() +*/ void QDeclarativeWorkerListModel::set(int index, const QScriptValue &value) { if (m_agent) { @@ -995,6 +1111,22 @@ void QDeclarativeWorkerListModel::set(int index, const QScriptValue &value) } } +/*! + \qmlmethod WorkerListModel::sync() + + Writes any unsaved changes to the list model. This must be called after + changes have been made to the list model in the worker script. + + Note that this method can only be called from the associated worker script. +*/ +void QDeclarativeWorkerListModel::sync() +{ + // This is really a dummy method to make it look like sync() exists in + // WorkerListModel (and not QDeclarativeWorkerListModelAgent) and to let + // us document sync(). + qmlInfo(this) << "sync() can only be called from a WorkerScript"; +} + QDeclarativeWorkerListModelAgent *QDeclarativeWorkerListModel::agent() { if (!m_agent) @@ -1013,6 +1145,10 @@ QString QDeclarativeWorkerListModel::toString(int role) const return m_roles.value(role); } +/*! + \qmlproperty int ListModel::count + The number of data entries in the model. +*/ int QDeclarativeWorkerListModel::count() const { return m_values.count(); @@ -1038,4 +1174,3 @@ QT_END_NAMESPACE #include "qdeclarativeworkerscript.moc" - diff --git a/src/declarative/qml/qdeclarativeworkerscript_p.h b/src/declarative/qml/qdeclarativeworkerscript_p.h index 8ebd2c1..01cc72a 100644 --- a/src/declarative/qml/qdeclarativeworkerscript_p.h +++ b/src/declarative/qml/qdeclarativeworkerscript_p.h @@ -61,6 +61,8 @@ #include <QtScript/qscriptvalue.h> #include <QtCore/qurl.h> +QT_BEGIN_HEADER + QT_BEGIN_NAMESPACE class QDeclarativeWorkerScript; @@ -84,7 +86,7 @@ private: QDeclarativeWorkerScriptEnginePrivate *d; }; -class QDeclarativeWorkerScript : public QObject, public QDeclarativeParserStatus +class Q_DECLARATIVE_EXPORT QDeclarativeWorkerScript : public QObject, public QDeclarativeParserStatus { Q_OBJECT Q_PROPERTY(QUrl source READ source WRITE setSource NOTIFY sourceChanged) @@ -115,7 +117,7 @@ private: }; class QDeclarativeWorkerListModelAgent; -class QDeclarativeWorkerListModel : public QListModelInterface +class Q_DECLARATIVE_EXPORT QDeclarativeWorkerListModel : public QListModelInterface { Q_OBJECT Q_PROPERTY(int count READ count NOTIFY countChanged) @@ -130,6 +132,7 @@ public: Q_INVOKABLE void insert(int index, const QScriptValue&); Q_INVOKABLE QScriptValue get(int index) const; Q_INVOKABLE void set(int index, const QScriptValue &); + Q_INVOKABLE void sync(); QDeclarativeWorkerListModelAgent *agent(); @@ -157,4 +160,6 @@ QT_END_NAMESPACE QML_DECLARE_TYPE(QDeclarativeWorkerScript); QML_DECLARE_TYPE(QDeclarativeWorkerListModel); +QT_END_HEADER + #endif // QDECLARATIVEWORKERSCRIPT_P_H |