Add WorkerScript docs and tests.

Task-number: QT-2807

6 files changed, 308 insertions, 1 deletions

diff --git a/src/declarative/qml/qdeclarativeworkerscript.cpp b/src/declarative/qml/qdeclarativeworkerscript.cpp
index c1d090e..784353a 100644
--- a/src/declarative/qml/qdeclarativeworkerscript.cpp
+++ b/src/declarative/qml/qdeclarativeworkerscript.cpp
@@ -365,6 +365,8 @@ void QDeclarativeWorkerScriptEnginePrivate::processLoad(int id, const QUrl &url)
         workerEngine->evaluate(script);
 
         workerEngine->popContext();
+    } else {
+        qWarning().nospace() << "WorkerScript: Cannot find source file " << url.toString();
     }
 }
 
@@ -382,7 +384,7 @@ QVariant QDeclarativeWorkerScriptEnginePrivate::scriptValueToVariant(const QScri
         quint32 length = (quint32)value.property(QLatin1String("length")).toNumber();
 
         for (quint32 ii = 0; ii < length; ++ii) {
-            QVariant v = scriptValueToVariant(ii);
+            QVariant v = scriptValueToVariant(value.property(ii));
             list << v;
         }
 
@@ -561,6 +563,65 @@ void QDeclarativeWorkerScriptEngine::run()
     delete d->workerEngine; d->workerEngine = 0;
 }
 
+
+/*!
+    \qmlclass WorkerScript QDeclarativeWorkerScript
+    \brief The WorkerScript element enables the use of threads in QML.
+
+    Use WorkerScript to run operations in a new thread.
+    This is useful for running operations in the background so
+    that the main GUI thread is not blocked.
+
+    Messages can be passed between the new thread and the parent thread
+    using sendMessage() and the onMessage() handler.
+    
+    Here is an example:
+
+    \qml
+    import Qt 4.6
+
+    Rectangle {
+        width: 300
+        height: 300
+
+        Text {
+            id: myText
+            text: 'Click anywhere'
+        }
+
+        WorkerScript {
+            id: myWorker
+            source: "script.js"
+
+            onMessage: {
+                myText.text = messageObject.reply
+            }
+        }
+
+        MouseArea { 
+            anchors.fill: parent
+            onClicked: myWorker.sendMessage( {'x': mouse.x, 'y': mouse.y} );
+        }
+    }
+    \endqml
+
+    The above worker script specifies a javascript file, "script.js", that handles
+    the operations to be performed in the new thread:
+
+    \qml
+    WorkerScript.onMessage = function(message) {
+        // ... long-running operations and calculations are done here
+        WorkerScript.sendMessage( {'reply': 'Mouse is at ' + message.x + ',' + message.y} );
+    }
+    \endqml
+    
+    When the user clicks anywhere within the rectangle, \c sendMessage() is
+    called, triggering the \tt WorkerScript.onMessage() handler in
+    \tt source.js. This in turn sends a reply message that is then received
+    by the \tt onMessage() handler of \tt myWorker.
+
+    \sa WorkerListModel
+*/
 QDeclarativeWorkerScript::QDeclarativeWorkerScript(QObject *parent)
 : QObject(parent), m_engine(0), m_scriptId(-1)
 {
@@ -571,6 +632,12 @@ QDeclarativeWorkerScript::~QDeclarativeWorkerScript()
     if (m_scriptId != -1) m_engine->removeWorkerScript(m_scriptId);
 }
 
+/*!
+    \qmlproperty url WorkerScript::source
+
+    This holds the url of the javascript file that implements the
+    \tt WorkerScript.onMessage() handler for threaded operations.
+*/
 QUrl QDeclarativeWorkerScript::source() const
 {
     return m_source;
@@ -589,6 +656,13 @@ void QDeclarativeWorkerScript::setSource(const QUrl &source)
     emit sourceChanged();
 }
 
+/*
+    \qmlmethod WorkerScript::sendMessage(jsobject message)
+
+    Sends the given \a message to a worker script handler in another
+    thread. The other worker script handler can receive this message
+    through the onMessage() handler.
+*/
 void QDeclarativeWorkerScript::sendMessage(const QScriptValue &message)
 {
     if (!m_engine) {
@@ -616,6 +690,13 @@ void QDeclarativeWorkerScript::componentComplete()
     }
 }
 
+/*!
+    \qmlsignal WorkerScript::onMessage(jsobject msg)
+
+    This handler is called when a message \a msg is received from a worker
+    script in another thread through a call to sendMessage().
+*/
+
 bool QDeclarativeWorkerScript::event(QEvent *event)
 {
     if (event->type() == (QEvent::Type)WorkerDataEvent::WorkerData) {
diff --git a/tests/auto/declarative/declarative.pro b/tests/auto/declarative/declarative.pro
index 38c75a8..200d831 100644
--- a/tests/auto/declarative/declarative.pro
+++ b/tests/auto/declarative/declarative.pro
@@ -55,6 +55,7 @@ SUBDIRS += \
            qdeclarativexmllistmodel \        # Cover
            qpacketprotocol \        # Cover
            qdeclarativerepeater \    # Cover
+           qdeclarativeworkerscript \    # Cover
            qdeclarativeworkerlistmodel \    # Cover
            qdeclarativevaluetypes \          # Cover
            qdeclarativexmlhttprequest \      # Cover
diff --git a/tests/auto/declarative/qdeclarativeworkerscript/data/script.js b/tests/auto/declarative/qdeclarativeworkerscript/data/script.js
new file mode 100644
index 0000000..09199de
--- /dev/null
+++ b/tests/auto/declarative/qdeclarativeworkerscript/data/script.js
@@ -0,0 +1,5 @@
+WorkerScript.onMessage = function(msg) {
+    WorkerScript.sendMessage(msg)
+}
+
+
diff --git a/tests/auto/declarative/qdeclarativeworkerscript/data/worker.qml b/tests/auto/declarative/qdeclarativeworkerscript/data/worker.qml
new file mode 100644
index 0000000..2982010
--- /dev/null
+++ b/tests/auto/declarative/qdeclarativeworkerscript/data/worker.qml
@@ -0,0 +1,27 @@
+import Qt 4.6
+
+WorkerScript {
+    id: worker
+    source: "script.js"
+
+    property bool done : false
+    property var response
+
+    function testSend(value) {
+        worker.sendMessage(value)
+    }
+
+    function testSendLiteral(value) {
+        eval('worker.sendMessage(' + value +')')
+    }
+
+    function compareLiteralResponse(expected) {
+        var e = eval('(' + expected + ')')
+        return worker.response == e
+    }
+
+    onMessage: {
+        worker.done = true
+        worker.response = messageObject
+    }
+}
diff --git a/tests/auto/declarative/qdeclarativeworkerscript/qdeclarativeworkerscript.pro b/tests/auto/declarative/qdeclarativeworkerscript/qdeclarativeworkerscript.pro
new file mode 100644
index 0000000..0543ff6
--- /dev/null
+++ b/tests/auto/declarative/qdeclarativeworkerscript/qdeclarativeworkerscript.pro
@@ -0,0 +1,9 @@
+load(qttest_p4)
+contains(QT_CONFIG,declarative): QT += declarative
+QT += script
+macx:CONFIG -= app_bundle
+
+SOURCES += tst_qdeclarativeworkerscript.cpp
+
+# Define SRCDIR equal to test's source directory
+DEFINES += SRCDIR=\\\"$$PWD\\\"
diff --git a/tests/auto/declarative/qdeclarativeworkerscript/tst_qdeclarativeworkerscript.cpp b/tests/auto/declarative/qdeclarativeworkerscript/tst_qdeclarativeworkerscript.cpp
new file mode 100644
index 0000000..841a0ee
--- /dev/null
+++ b/tests/auto/declarative/qdeclarativeworkerscript/tst_qdeclarativeworkerscript.cpp
@@ -0,0 +1,184 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the test suite of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+#include <qtest.h>
+#include <QtCore/qdebug.h>
+#include <QtScript/qscriptengine.h>
+
+#include <QtDeclarative/qdeclarativecomponent.h>
+#include <QtDeclarative/qdeclarativeengine.h>
+#include <QtDeclarative/qdeclarativeitem.h>
+
+#include <private/qdeclarativeworkerscript_p.h>
+#include "../../../shared/util.h"
+
+Q_DECLARE_METATYPE(QList<QObject*>)
+Q_DECLARE_METATYPE(QScriptValue)
+
+class tst_QDeclarativeWorkerScript : public QObject
+{
+    Q_OBJECT
+public:
+    tst_QDeclarativeWorkerScript() {}
+private slots:
+    void source();
+    void source_data();
+    void messaging();
+    void messaging_data();
+    void messaging_sendQObjectList();
+    void messaging_sendJsObject();
+
+private:
+    void waitForEchoMessage(QDeclarativeWorkerScript *worker) {
+        const QMetaObject *mo = worker->metaObject();
+        int index = mo->indexOfProperty("done");
+        QVERIFY(index >= 0);
+        QTRY_COMPARE(mo->property(index).read(worker).toBool(), true);
+        QTRY_COMPARE(mo->property(mo->indexOfProperty("done")).read(worker).toBool(), true);
+    }
+
+    QDeclarativeEngine m_engine;
+};
+
+void tst_QDeclarativeWorkerScript::source()
+{
+    QFETCH(QUrl, source);
+    QFETCH(bool, valid);
+
+    QDeclarativeComponent component(&m_engine);
+    component.setData("import Qt 4.6\nWorkerScript { source: '" + source.toString().toUtf8() + "'; }", QUrl());
+
+    if (!valid) {
+        QByteArray w = "WorkerScript: Cannot find source file \"" + source.toString().toUtf8() + "\"";
+        QTest::ignoreMessage(QtWarningMsg, w.constData());
+    }
+    QDeclarativeWorkerScript *item = qobject_cast<QDeclarativeWorkerScript*>(component.create());
+    QVERIFY(item != 0);
+
+    QCOMPARE(item->source(), source);
+
+    qApp->processEvents();
+}
+
+void tst_QDeclarativeWorkerScript::source_data()
+{
+    QTest::addColumn<QUrl>("source");
+    QTest::addColumn<bool>("valid");
+
+    QTest::newRow("valid") << QUrl::fromLocalFile(SRCDIR "/data/worker.qml") << true;
+    QTest::newRow("invalid") << QUrl("file:///asdjfk.js") << false;
+}
+
+void tst_QDeclarativeWorkerScript::messaging()
+{
+    QFETCH(QVariant, value);
+
+    QDeclarativeComponent component(&m_engine, SRCDIR "/data/worker.qml");
+    QDeclarativeWorkerScript *worker = qobject_cast<QDeclarativeWorkerScript*>(component.create());
+    QVERIFY(worker != 0);
+
+    QVERIFY(QMetaObject::invokeMethod(worker, "testSend", Q_ARG(QVariant, value)));
+    waitForEchoMessage(worker);
+
+    const QMetaObject *mo = worker->metaObject();
+    QCOMPARE(mo->property(mo->indexOfProperty("response")).read(worker).value<QVariant>(), value);
+
+    qApp->processEvents();
+}
+
+void tst_QDeclarativeWorkerScript::messaging_data()
+{
+    QTest::addColumn<QVariant>("value");
+
+    QTest::newRow("invalid") << QVariant();
+    QTest::newRow("bool") << qVariantFromValue(true);
+    QTest::newRow("int") << qVariantFromValue(1001);
+    QTest::newRow("real") << qVariantFromValue(10334.323);
+    QTest::newRow("string") << qVariantFromValue(QString("More cheeeese, Gromit!"));
+    QTest::newRow("variant list") << qVariantFromValue((QVariantList() << "a" << "b" << "c"));
+}
+
+void tst_QDeclarativeWorkerScript::messaging_sendQObjectList()
+{
+    // Not allowed to send QObjects other than QDeclarativeWorkerListModelAgent
+    // instances. If objects are sent in a list, they will be sent as 'undefined'
+    // js values.
+
+    QDeclarativeComponent component(&m_engine, SRCDIR "/data/worker.qml");
+    QDeclarativeWorkerScript *worker = qobject_cast<QDeclarativeWorkerScript*>(component.create());
+    QVERIFY(worker != 0);
+
+    QVariantList objects;
+    for (int i=0; i<3; i++)
+        objects << qVariantFromValue(new QObject(this));
+
+    QVERIFY(QMetaObject::invokeMethod(worker, "testSend", Q_ARG(QVariant, qVariantFromValue(objects))));
+    waitForEchoMessage(worker);
+
+    const QMetaObject *mo = worker->metaObject();
+    QVariantList result = mo->property(mo->indexOfProperty("response")).read(worker).value<QVariantList>();
+    QCOMPARE(result, (QVariantList() << QVariant() << QVariant() << QVariant()));
+
+    qApp->processEvents();
+}
+
+void tst_QDeclarativeWorkerScript::messaging_sendJsObject()
+{
+    QDeclarativeComponent component(&m_engine, SRCDIR "/data/worker.qml");
+    QDeclarativeWorkerScript *worker = qobject_cast<QDeclarativeWorkerScript*>(component.create());
+    QVERIFY(worker != 0);
+
+    QString jsObject = "{'spell power': 3101, 'haste': 1125}";
+
+    QVERIFY(QMetaObject::invokeMethod(worker, "testSendLiteral", Q_ARG(QVariant, jsObject)));
+    waitForEchoMessage(worker);
+
+    QVariant result = qVariantFromValue(false);
+    QVERIFY(QMetaObject::invokeMethod(worker, "compareLiteralResponse", Qt::DirectConnection, 
+            Q_RETURN_ARG(QVariant, result), Q_ARG(QVariant, jsObject)));
+    QVERIFY(result.toBool());
+
+    qApp->processEvents();
+}
+
+QTEST_MAIN(tst_QDeclarativeWorkerScript)
+
+#include "tst_qdeclarativeworkerscript.moc"
+