1
<?xml version="1.0" encoding="iso-8859-1"?>
2
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
3
<html><head><title>QScriptContext Class Reference</title><style>h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm }
4
a:link { color: #004faf; text-decoration: none }
5
a:visited { color: #672967; text-decoration: none }
6
td.postheader { font-family: sans-serif }
7
tr.address { font-family: sans-serif }
8
body { background: #ffffff; color: black; }
9
</style></head><body><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr /><td align="left" valign="top" width="32"><img align="left" border="0" height="32" src="images/rb-logo.png" width="32" /></td><td width="1">  </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="modules.html"><font color="#004faf">Modules</font></a></td></table><h1 align="center">QScriptContext Class Reference<br /><sup><sup>[<a href="qtscript.html">QtScript</a> module]</sup></sup></h1><p>The QScriptContext class represents a Qt Script function
10
invocation. <a href="#details">More...</a></p>
12
<h3>Types</h3><ul><li><div class="fn" />enum <b><a href="qscriptcontext.html#Error-enum">Error</a></b> { UnknownError, ReferenceError, SyntaxError, TypeError, RangeError, URIError }</li><li><div class="fn" />enum <b><a href="qscriptcontext.html#ExecutionState-enum">ExecutionState</a></b> { NormalState, ExceptionState }</li></ul><h3>Methods</h3><ul><li><div class="fn" />QScriptValue <b><a href="qscriptcontext.html#activationObject">activationObject</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptcontext.html#argument">argument</a></b> (<i>self</i>, int <i>index</i>)</li><li><div class="fn" />int <b><a href="qscriptcontext.html#argumentCount">argumentCount</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptcontext.html#argumentsObject">argumentsObject</a></b> (<i>self</i>)</li><li><div class="fn" />QStringList <b><a href="qscriptcontext.html#backtrace">backtrace</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptcontext.html#callee">callee</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptEngine <b><a href="qscriptcontext.html#engine">engine</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qscriptcontext.html#isCalledAsConstructor">isCalledAsConstructor</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptContext <b><a href="qscriptcontext.html#parentContext">parentContext</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qscriptcontext.html#setActivationObject">setActivationObject</a></b> (<i>self</i>, QScriptValue <i>activation</i>)</li><li><div class="fn" /><b><a href="qscriptcontext.html#setThisObject">setThisObject</a></b> (<i>self</i>, QScriptValue <i>thisObject</i>)</li><li><div class="fn" />ExecutionState <b><a href="qscriptcontext.html#state">state</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptcontext.html#thisObject">thisObject</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptcontext.html#throwError">throwError</a></b> (<i>self</i>, Error <i>error</i>, QString <i>text</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptcontext.html#throwError-2">throwError</a></b> (<i>self</i>, QString <i>text</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptcontext.html#throwValue">throwValue</a></b> (<i>self</i>, QScriptValue <i>value</i>)</li><li><div class="fn" />QString <b><a href="qscriptcontext.html#toString">toString</a></b> (<i>self</i>)</li></ul><a name="details" /><hr /><h2>Detailed Description</h2><p>The QScriptContext class represents a Qt Script function
14
<p>A QScriptContext provides access to the `this' object and
15
arguments passed to a script function. You typically want to access
16
this information when you're writing a native (C++) function (see
17
<a href="qscriptengine.html#newFunction">QScriptEngine.newFunction</a>())
18
that will be called from script code. For example, when the script
21
foo(<span class="number">20.5</span><span class="operator">,</span> <span class="string">"hello"</span><span class="operator">,</span> <span class="keyword">new</span> Object())
23
<p>is evaluated, a QScriptContext will be created, and the context
24
will carry the arguments as QScriptValues; in this particular case,
25
the arguments will be one <a href="qscriptvalue.html">QScriptValue</a> containing the number 20.5, a
26
second <a href="qscriptvalue.html">QScriptValue</a> containing the
27
string <tt>"hello"</tt>, and a third <a href="qscriptvalue.html">QScriptValue</a> containing a Qt Script
29
<p>Use <a href="qscriptcontext.html#argumentCount">argumentCount</a>() to get the
30
number of arguments passed to the function, and <a href="qscriptcontext.html#argument">argument</a>() to get an argument at
31
a certain index. The <a href="qscriptcontext.html#argumentsObject">argumentsObject</a>()
32
function returns a Qt Script array object containing all the
33
arguments; you can use the <a href="qscriptvalueiterator.html">QScriptValueIterator</a> to iterate
34
over its elements, or pass the array on as arguments to another
35
script function using <a href="qscriptvalue.html#call">QScriptValue.call</a>().</p>
36
<p>Use <a href="qscriptcontext.html#thisObject">thisObject</a>() to
37
get the `this' object associated with the function call, and
38
<a href="qscriptcontext.html#setThisObject">setThisObject</a>() to
39
set the `this' object. If you are implementing a native "instance
40
method", you typically fetch the <a href="qscriptcontext.html#thisObject">thisObject</a>() and access one or
41
more of its properties:</p>
43
<span class="type"><a href="qscriptvalue.html">QScriptValue</a></span> Person_prototype_fullName(<span class="type">QScriptContext</span> <span class="operator">*</span>context<span class="operator">,</span> <span class="type"><a href="qscriptengine.html">QScriptEngine</a></span> <span class="operator">*</span>engine)
45
<span class="type"><a href="qscriptvalue.html">QScriptValue</a></span> self <span class="operator">=</span> context<span class="operator">-</span><span class="operator">></span>thisObject();
46
<span class="type"><a href="qstring.html">QString</a></span> result;
47
result <span class="operator">+</span><span class="operator">=</span> self<span class="operator">.</span>property(<span class="string">"firstName"</span>)<span class="operator">.</span>toString();
48
result <span class="operator">+</span><span class="operator">=</span> QLatin1String(<span class="string">" "</span>);
49
result <span class="operator">+</span><span class="operator">=</span> self<span class="operator">.</span>property(<span class="string">"lastName"</span>)<span class="operator">.</span>toString();
50
<span class="keyword">return</span> result;
53
<p>Use <a href="qscriptcontext.html#isCalledAsConstructor">isCalledAsConstructor</a>()
54
to determine if the function was called as a constructor (e.g.
55
<tt>"new foo()"</tt> (as constructor) or just <tt>"foo()"</tt>).
56
When a function is called as a constructor, the <a href="qscriptcontext.html#thisObject">thisObject</a>() contains the
57
newly constructed object that the function is expected to
59
<p>Use <a href="qscriptcontext.html#throwValue">throwValue</a>() or
60
<a href="qscriptcontext.html#throwError">throwError</a>() to throw
62
<p>Use <a href="qscriptcontext.html#callee">callee</a>() to obtain
63
the <a href="qscriptvalue.html">QScriptValue</a> that represents
64
the function being called. This can for example be used to call the
65
function recursively.</p>
66
<p>Use <a href="qscriptcontext.html#parentContext">parentContext</a>() to get a
67
pointer to the context that precedes this context in the activation
68
stack. This is mostly useful for debugging purposes (e.g. when
69
constructing some form of backtrace).</p>
70
<p>The <a href="qscriptcontext.html#activationObject">activationObject</a>()
71
function returns the object that is used to hold the local
72
variables associated with this function call. You can replace the
73
activation object by calling <a href="qscriptcontext.html#setActivationObject">setActivationObject</a>().
74
A typical usage of these functions is when you want script code to
75
be evaluated in the context of the parent context, e.g. to
76
implement an include() function:</p>
78
<span class="type"><a href="qscriptvalue.html">QScriptValue</a></span> myInclude(<span class="type">QScriptContext</span> <span class="operator">*</span>ctx<span class="operator">,</span> <span class="type"><a href="qscriptengine.html">QScriptEngine</a></span> <span class="operator">*</span>eng)
80
<span class="type"><a href="qstring.html">QString</a></span> fileName <span class="operator">=</span> ctx<span class="operator">-</span><span class="operator">></span>argument(<span class="number">0</span>)<span class="operator">.</span>toString();
81
<span class="type"><a href="qstring.html">QString</a></span> contents <span class="operator">=</span> readTheFile(fileName);
82
ctx<span class="operator">-</span><span class="operator">></span>setActivationObject(ctx<span class="operator">-</span><span class="operator">></span>parentContext()<span class="operator">-</span><span class="operator">></span>activationObject());
83
ctx<span class="operator">-</span><span class="operator">></span>setThisObject(ctx<span class="operator">-</span><span class="operator">></span>parentContext()<span class="operator">-</span><span class="operator">></span>thisObject());
84
<span class="keyword">return</span> eng<span class="operator">-</span><span class="operator">></span>evaluate(contents<span class="operator">,</span> fileName);
87
<p>Use <a href="qscriptcontext.html#backtrace">backtrace</a>() to
88
get a human-readable backtrace associated with this context. This
89
can be useful for debugging purposes when implementing native
90
functions. The <a href="qscriptcontext.html#toString">toString</a>() function provides a
91
string representation of the context. (<a href="qscriptcontextinfo.html">QScriptContextInfo</a> provides more
92
detailed debugging-related information about the
94
<p>Use <a href="qscriptcontext.html#engine">engine</a>() to obtain
95
a pointer to the <a href="qscriptengine.html">QScriptEngine</a>
96
that this context resides in.</p>
97
<hr /><h2>Type Documentation</h2><h3 class="fn"><a name="Error-enum" />QScriptContext.Error</h3><p>This enum specifies types of error.</p>
98
<table class="valuelist">
99
<tr class="odd" valign="top">
100
<th class="tblConst">Constant</th>
101
<th class="tblval">Value</th>
102
<th class="tbldscr">Description</th>
105
<td class="topAlign"><tt>QScriptContext.ReferenceError</tt></td>
106
<td class="topAlign"><tt>1</tt></td>
107
<td class="topAlign">A reference error.</td>
110
<td class="topAlign"><tt>QScriptContext.SyntaxError</tt></td>
111
<td class="topAlign"><tt>2</tt></td>
112
<td class="topAlign">A syntax error.</td>
115
<td class="topAlign"><tt>QScriptContext.TypeError</tt></td>
116
<td class="topAlign"><tt>3</tt></td>
117
<td class="topAlign">A type error.</td>
120
<td class="topAlign"><tt>QScriptContext.RangeError</tt></td>
121
<td class="topAlign"><tt>4</tt></td>
122
<td class="topAlign">A range error.</td>
125
<td class="topAlign"><tt>QScriptContext.URIError</tt></td>
126
<td class="topAlign"><tt>5</tt></td>
127
<td class="topAlign">A URI error.</td>
130
<td class="topAlign"><tt>QScriptContext.UnknownError</tt></td>
131
<td class="topAlign"><tt>0</tt></td>
132
<td class="topAlign">An unknown error.</td>
137
<h3 class="fn"><a name="ExecutionState-enum" />QScriptContext.ExecutionState</h3><p>This enum specifies the frameution state of the context.</p>
138
<table class="valuelist">
139
<tr class="odd" valign="top">
140
<th class="tblConst">Constant</th>
141
<th class="tblval">Value</th>
142
<th class="tbldscr">Description</th>
145
<td class="topAlign"><tt>QScriptContext.NormalState</tt></td>
146
<td class="topAlign"><tt>0</tt></td>
147
<td class="topAlign">The context is in a normal state.</td>
150
<td class="topAlign"><tt>QScriptContext.ExceptionState</tt></td>
151
<td class="topAlign"><tt>1</tt></td>
152
<td class="topAlign">The context is in an exceptional state.</td>
155
<hr /><h2>Method Documentation</h2><h3 class="fn"><a name="activationObject" /><a href="qscriptvalue.html">QScriptValue</a> QScriptContext.activationObject (<i>self</i>)</h3><p>Returns the activation object of this <a href="qscriptcontext.html">QScriptContext</a>. The activation object
156
provides access to the local variables associated with this
158
<p><b>Note:</b> The activation object might not be available if
159
there is no active <a href="qscriptengineagent.html">QScriptEngineAgent</a>, as it might be
161
<p><b>See also</b> <a href="qscriptcontext.html#setActivationObject">setActivationObject</a>(),
162
<a href="qscriptcontext.html#argument">argument</a>(), and <a href="qscriptcontext.html#argumentsObject">argumentsObject</a>().</p>
165
<h3 class="fn"><a name="argument" /><a href="qscriptvalue.html">QScriptValue</a> QScriptContext.argument (<i>self</i>, int <i>index</i>)</h3><p>Returns the function argument at the given <i>index</i>.</p>
166
<p>If <i>index</i> >= <a href="qscriptcontext.html#argumentCount">argumentCount</a>(), a <a href="qscriptvalue.html">QScriptValue</a> of the primitive type
167
Undefined is returned.</p>
168
<p><b>See also</b> <a href="qscriptcontext.html#argumentCount">argumentCount</a>().</p>
171
<h3 class="fn"><a name="argumentCount" />int QScriptContext.argumentCount (<i>self</i>)</h3><p>Returns the number of arguments passed to the function in this
173
<p>Note that the argument count can be different from the formal
174
number of arguments (the <tt>length</tt> property of <a href="qscriptcontext.html#callee">callee</a>()).</p>
175
<p><b>See also</b> <a href="qscriptcontext.html#argument">argument</a>().</p>
178
<h3 class="fn"><a name="argumentsObject" /><a href="qscriptvalue.html">QScriptValue</a> QScriptContext.argumentsObject (<i>self</i>)</h3><p>Returns the arguments object of this <a href="qscriptcontext.html">QScriptContext</a>.</p>
179
<p>The arguments object has properties <tt>callee</tt> (equal to
180
<a href="qscriptcontext.html#callee">callee</a>()) and
181
<tt>length</tt> (equal to <a href="qscriptcontext.html#argumentCount">argumentCount</a>()), and
182
properties <tt>0</tt>, <tt>1</tt>, ..., <a href="qscriptcontext.html#argumentCount">argumentCount</a>() - 1 that
183
provide access to the argument values. Initially, property
184
<tt>P</tt> (0 <= <tt>P</tt> < <a href="qscriptcontext.html#argumentCount">argumentCount</a>()) has the
185
same value as argument(<tt>P</tt>). In the case when <tt>P</tt> is
186
less than the number of formal parameters of the function,
187
<tt>P</tt> shares its value with the corresponding property of the
188
activation object (<a href="qscriptcontext.html#activationObject">activationObject</a>()).
189
This means that changing this property changes the corresponding
190
property of the activation object and vice versa.</p>
191
<p><b>See also</b> <a href="qscriptcontext.html#argument">argument</a>() and <a href="qscriptcontext.html#activationObject">activationObject</a>().</p>
194
<h3 class="fn"><a name="backtrace" />QStringList QScriptContext.backtrace (<i>self</i>)</h3><p>Returns a human-readable backtrace of this <a href="qscriptcontext.html">QScriptContext</a>.</p>
195
<p>Each line is of the form
196
<tt><function-name>(<arguments>)@<file-name>:<line-number></tt>.</p>
197
<p>To access individual pieces of debugging-related information
198
(for example, to construct your own backtrace representation), use
199
<a href="qscriptcontextinfo.html">QScriptContextInfo</a>.</p>
200
<p><b>See also</b> <a href="qscriptengine.html#uncaughtExceptionBacktrace">QScriptEngine.uncaughtExceptionBacktrace</a>(),
201
<a href="qscriptcontextinfo.html">QScriptContextInfo</a>, and
202
<a href="qscriptcontext.html#toString">toString</a>().</p>
205
<h3 class="fn"><a name="callee" /><a href="qscriptvalue.html">QScriptValue</a> QScriptContext.callee (<i>self</i>)</h3><p>Returns the callee. The callee is the function object that this
206
<a href="qscriptcontext.html">QScriptContext</a> represents an
210
<h3 class="fn"><a name="engine" /><a href="qscriptengine.html">QScriptEngine</a> QScriptContext.engine (<i>self</i>)</h3><p>Returns the <a href="qscriptengine.html">QScriptEngine</a> that
211
this <a href="qscriptcontext.html">QScriptContext</a> belongs
215
<h3 class="fn"><a name="isCalledAsConstructor" />bool QScriptContext.isCalledAsConstructor (<i>self</i>)</h3><p>Returns true if the function was called as a constructor (e.g.
216
<tt>"new foo()"</tt>); otherwise returns false.</p>
217
<p>When a function is called as constructor, the <a href="qscriptcontext.html#thisObject">thisObject</a>() contains the
218
newly constructed object to be initialized.</p>
219
<p><b>Note:</b> This function is only guaranteed to work for a
220
context corresponding to native functions.</p>
223
<h3 class="fn"><a name="parentContext" /><a href="qscriptcontext.html">QScriptContext</a> QScriptContext.parentContext (<i>self</i>)</h3><p>Returns the parent context of this <a href="qscriptcontext.html">QScriptContext</a>.</p>
226
<h3 class="fn"><a name="setActivationObject" />QScriptContext.setActivationObject (<i>self</i>, <a href="qscriptvalue.html">QScriptValue</a> <i>activation</i>)</h3><p>Sets the activation object of this <a href="qscriptcontext.html">QScriptContext</a> to be the given
227
<i>activation</i>.</p>
228
<p>If <i>activation</i> is not an object, this function does
230
<p><b>Note:</b> For a context corresponding to a JavaScript
231
function, this is only guaranteed to work if there was an <a href="qscriptengineagent.html">QScriptEngineAgent</a> active on the
232
engine while the function was evaluated.</p>
233
<p><b>See also</b> <a href="qscriptcontext.html#activationObject">activationObject</a>().</p>
236
<h3 class="fn"><a name="setThisObject" />QScriptContext.setThisObject (<i>self</i>, <a href="qscriptvalue.html">QScriptValue</a> <i>thisObject</i>)</h3><p>Sets the `this' object associated with this <a href="qscriptcontext.html">QScriptContext</a> to be
237
<i>thisObject</i>.</p>
238
<p>If <i>thisObject</i> is not an object, this function does
240
<p><b>See also</b> <a href="qscriptcontext.html#thisObject">thisObject</a>().</p>
243
<h3 class="fn"><a name="state" /><a href="qscriptcontext.html#ExecutionState-enum">ExecutionState</a> QScriptContext.state (<i>self</i>)</h3><p>Returns the frameution state of this <a href="qscriptcontext.html">QScriptContext</a>.</p>
246
<h3 class="fn"><a name="thisObject" /><a href="qscriptvalue.html">QScriptValue</a> QScriptContext.thisObject (<i>self</i>)</h3><p>Returns the `this' object associated with this <a href="qscriptcontext.html">QScriptContext</a>.</p>
247
<p><b>See also</b> <a href="qscriptcontext.html#setThisObject">setThisObject</a>().</p>
250
<h3 class="fn"><a name="throwError" /><a href="qscriptvalue.html">QScriptValue</a> QScriptContext.throwError (<i>self</i>, <a href="qscriptcontext.html#Error-enum">Error</a> <i>error</i>, QString <i>text</i>)</h3><p>Throws an <i>error</i> with the given <i>text</i>. Returns the
251
created error object.</p>
252
<p>The <i>text</i> will be stored in the <tt>message</tt> property
253
of the error object.</p>
254
<p>The error object will be initialized to contain information
255
about the location where the error occurred; specifically, it will
256
have properties <tt>lineNumber</tt>, <tt>fileName</tt> and
257
<tt>stack</tt>. These properties are described in <a href="scripting.html#qtscript-extensions-to-ecmascript">QtScript
258
Extensions to ECMAScript</a>.</p>
259
<p><b>See also</b> <a href="qscriptcontext.html#throwValue">throwValue</a>() and <a href="qscriptcontext.html#state">state</a>().</p>
262
<h3 class="fn"><a name="throwError-2" /><a href="qscriptvalue.html">QScriptValue</a> QScriptContext.throwError (<i>self</i>, QString <i>text</i>)</h3><p>This is an overloaded function.</p>
263
<p>Throws an error with the given <i>text</i>. Returns the created
265
<p><b>See also</b> <a href="qscriptcontext.html#throwValue">throwValue</a>() and <a href="qscriptcontext.html#state">state</a>().</p>
268
<h3 class="fn"><a name="throwValue" /><a href="qscriptvalue.html">QScriptValue</a> QScriptContext.throwValue (<i>self</i>, <a href="qscriptvalue.html">QScriptValue</a> <i>value</i>)</h3><p>Throws an exception with the given <i>value</i>. Returns the
269
value thrown (the same as the argument).</p>
270
<p><b>See also</b> <a href="qscriptcontext.html#throwError">throwError</a>() and <a href="qscriptcontext.html#state">state</a>().</p>
273
<h3 class="fn"><a name="toString" />QString QScriptContext.toString (<i>self</i>)</h3><p>Returns a string representation of this context. This is useful
275
<p>This function was introduced in Qt 4.4.</p>
276
<p><b>See also</b> <a href="qscriptcontext.html#backtrace">backtrace</a>().</p>
277
<address><hr /><div align="center"><table border="0" cellspacing="0" width="100%"><tr class="address"><td align="left" width="25%">PyQt 4.10.3 for X11</td><td align="center" width="50%">Copyright © <a href="http://www.riverbankcomputing.com">Riverbank Computing Ltd</a> and <a href="http://www.qtsoftware.com">Nokia</a> 2012</td><td align="right" width="25%">Qt 4.8.5</td></tr></table></div></address></body></html>
b'\\ No newline at end of file'