1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qdeclarativeworkerscript.cpp -->
<title>Qt 4.8: QML WorkerScript Element</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="content">
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
</div>
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li><a href="qdeclarativeelements.html">QML Elements</a></li>
<li>QML WorkerScript Element</li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#properties">Properties</a></li>
<li class="level1"><a href="#signal-handlers">Signal Handlers</a></li>
<li class="level1"><a href="#methods">Methods</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
<li class="level3"><a href="#restrictions">Restrictions</a></li>
</ul>
</div>
<h1 class="title">QML WorkerScript Element</h1>
<span class="subtitle"></span>
<!-- $$$WorkerScript-brief -->
<p>The WorkerScript element enables the use of threads in QML. <a href="#details">More...</a></p>
<!-- @@@WorkerScript -->
<ul>
<li><a href="qml-workerscript-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="properties"></a>
<h2>Properties</h2>
<ul>
<li class="fn"><b><b><a href="qml-workerscript.html#source-prop">source</a></b></b> : url</li>
</ul>
<a name="signal-handlers"></a>
<h2>Signal Handlers</h2>
<ul>
<li class="fn"><b><b><a href="qml-workerscript.html#onMessage-signal">onMessage</a></b></b></li>
</ul>
<a name="methods"></a>
<h2>Methods</h2>
<ul>
<li class="fn"><b><b><a href="qml-workerscript.html#sendMessage-method">sendMessage</a></b></b></li>
</ul>
<!-- $$$WorkerScript-description -->
<a name="details"></a>
<h2>Detailed Description</h2>
<p>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.</p>
<p>Messages can be passed between the new thread and the parent thread using <a href="qml-workerscript.html#sendMessage-method">sendMessage()</a> and the <a href="qml-workerscript.html#onMessage-signal">onMessage()</a> handler.</p>
<p>An example:</p>
<pre class="qml"> import QtQuick 1.0
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">width</span>: <span class="number">300</span>; <span class="name">height</span>: <span class="number">300</span>
<span class="type"><a href="qml-text.html">Text</a></span> {
<span class="name">id</span>: <span class="name">myText</span>
<span class="name">text</span>: <span class="string">'Click anywhere'</span>
}
<span class="type">WorkerScript</span> {
<span class="name">id</span>: <span class="name">myWorker</span>
<span class="name">source</span>: <span class="string">"script.js"</span>
<span class="name">onMessage</span>: <span class="name">myText</span>.<span class="name">text</span> <span class="operator">=</span> <span class="name">messageObject</span>.<span class="name">reply</span>
}
<span class="type"><a href="qml-mousearea.html">MouseArea</a></span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">onClicked</span>: <span class="name">myWorker</span>.<span class="name">sendMessage</span>({ 'x': <span class="name">mouse</span>.<span class="name">x</span>, 'y': mouse.y })
}
}</pre>
<p>The above worker script specifies a JavaScript file, "script.js", that handles the operations to be performed in the new thread. Here is <tt>script.js</tt>:</p>
<pre class="cpp"> <span class="name">WorkerScript</span>.<span class="name">onMessage</span> <span class="operator">=</span> <span class="keyword">function</span>(<span class="name">message</span>) {
<span class="comment">// ... long-running operations and calculations are done here</span>
<span class="name">WorkerScript</span>.<span class="name">sendMessage</span>({ 'reply': <span class="string">'Mouse is at '</span> <span class="operator">+</span> <span class="name">message</span>.<span class="name">x</span> <span class="operator">+</span> <span class="string">','</span> <span class="operator">+</span> <span class="name">message</span>.<span class="name">y</span> })
}</pre>
<p>When the user clicks anywhere within the rectangle, <tt>sendMessage()</tt> is called, triggering the <tt>WorkerScript.onMessage()</tt> handler in <tt>script.js</tt>. This in turn sends a reply message that is then received by the <tt>onMessage()</tt> handler of <tt>myWorker</tt>.</p>
<a name="restrictions"></a>
<h4>Restrictions</h4>
<p>Since the <tt>WorkerScript.onMessage()</tt> function is run in a separate thread, the JavaScript file is evaluated in a context separate from the main QML engine. This means that unlike an ordinary JavaScript file that is imported into QML, the <tt>script.js</tt> in the above example cannot access the properties, methods or other attributes of the QML item, nor can it access any context properties set on the QML object through <a href="qdeclarativecontext.html">QDeclarativeContext</a>.</p>
<p>Additionally, there are restrictions on the types of values that can be passed to and from the worker script. See the <a href="qml-workerscript.html#sendMessage-method">sendMessage()</a> documentation for details.</p>
<p><b>See also </b><a href="declarative-threading-workerscript.html">WorkerScript example</a> and <a href="declarative-threading-threadedlistmodel.html">Threaded ListModel example</a>.</p>
<!-- @@@WorkerScript -->
<h2>Property Documentation</h2>
<!-- $$$source -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="source-prop"></a><span class="name">source</span> : <span class="type"><a href="qml-url.html">url</a></span></p></td></tr></table></div><div class="qmldoc"><p>This holds the url of the JavaScript file that implements the <tt>WorkerScript.onMessage()</tt> handler for threaded operations.</p>
</div></div><!-- @@@source -->
<br/>
<h2>Signal Handler Documentation</h2>
<!-- $$$onMessage -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlFuncNode"><p><a name="onMessage-signal"></a>WorkerScript::<span class="name">onMessage</span> ( <span class="type">jsobject</span> <i>msg</i> )</p></td></tr></table></div><div class="qmldoc"><p>This handler is called when a message <i>msg</i> is received from a worker script in another thread through a call to <a href="qml-workerscript.html#sendMessage-method">sendMessage()</a>.</p>
</div></div><!-- @@@onMessage -->
<br/>
<h2>Method Documentation</h2>
<!-- $$$sendMessage -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlFuncNode"><p><a name="sendMessage-method"></a>WorkerScript::<span class="name">sendMessage</span> ( <span class="type">jsobject</span> <i>message</i> )</p></td></tr></table></div><div class="qmldoc"><p>Sends the given <i>message</i> to a worker script handler in another thread. The other worker script handler can receive this message through the onMessage() handler.</p>
<p>The <tt>message</tt> object may only contain values of the following types:</p>
<ul>
<li>boolean, number, string</li>
<li>JavaScript objects and arrays</li>
<li><a href="qml-listmodel.html">ListModel</a> objects (any other type of <a href="qobject.html">QObject</a>* is not allowed)</li>
</ul>
<p>All objects and arrays are copied to the <tt>message</tt>. With the exception of <a href="qml-listmodel.html">ListModel</a> objects, any modifications by the other thread to an object passed in <tt>message</tt> will not be reflected in the original object.</p>
</div></div><!-- @@@sendMessage -->
<br/>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2012 Nokia Corporation and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Nokia, Qt and their respective logos are trademarks of Nokia Corporation
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
</body>
</html>
|
