<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html><head><title>QScriptContext Class Reference</title><style>h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
td.postheader { font-family: sans-serif }
tr.address { font-family: sans-serif }
body { background: #ffffff; color: black; }
</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
invocation. <a href="#details">More...</a></p>
<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
invocation.</p>
<p>A QScriptContext provides access to the `this' object and
arguments passed to a script function. You typically want to access
this information when you're writing a native (C++) function (see
<a href="qscriptengine.html#newFunction">QScriptEngine.newFunction</a>())
that will be called from script code. For example, when the script
code</p>
<pre class="cpp">
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())
</pre>
<p>is evaluated, a QScriptContext will be created, and the context
will carry the arguments as QScriptValues; in this particular case,
the arguments will be one <a href="qscriptvalue.html">QScriptValue</a> containing the number 20.5, a
second <a href="qscriptvalue.html">QScriptValue</a> containing the
string <tt>"hello"</tt>, and a third <a href="qscriptvalue.html">QScriptValue</a> containing a Qt Script
object.</p>
<p>Use <a href="qscriptcontext.html#argumentCount">argumentCount</a>() to get the
number of arguments passed to the function, and <a href="qscriptcontext.html#argument">argument</a>() to get an argument at
a certain index. The <a href="qscriptcontext.html#argumentsObject">argumentsObject</a>()
function returns a Qt Script array object containing all the
arguments; you can use the <a href="qscriptvalueiterator.html">QScriptValueIterator</a> to iterate
over its elements, or pass the array on as arguments to another
script function using <a href="qscriptvalue.html#call">QScriptValue.call</a>().</p>
<p>Use <a href="qscriptcontext.html#thisObject">thisObject</a>() to
get the `this' object associated with the function call, and
<a href="qscriptcontext.html#setThisObject">setThisObject</a>() to
set the `this' object. If you are implementing a native "instance
method", you typically fetch the <a href="qscriptcontext.html#thisObject">thisObject</a>() and access one or
more of its properties:</p>
<pre class="cpp">
<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)
{
<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();
<span class="type"><a href="qstring.html">QString</a></span> result;
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();
result <span class="operator">+</span><span class="operator">=</span> QLatin1String(<span class="string">" "</span>);
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();
<span class="keyword">return</span> result;
}
</pre>
<p>Use <a href="qscriptcontext.html#isCalledAsConstructor">isCalledAsConstructor</a>()
to determine if the function was called as a constructor (e.g.
<tt>"new foo()"</tt> (as constructor) or just <tt>"foo()"</tt>).
When a function is called as a constructor, the <a href="qscriptcontext.html#thisObject">thisObject</a>() contains the
newly constructed object that the function is expected to
initialize.</p>
<p>Use <a href="qscriptcontext.html#throwValue">throwValue</a>() or
<a href="qscriptcontext.html#throwError">throwError</a>() to throw
an exception.</p>
<p>Use <a href="qscriptcontext.html#callee">callee</a>() to obtain
the <a href="qscriptvalue.html">QScriptValue</a> that represents
the function being called. This can for example be used to call the
function recursively.</p>
<p>Use <a href="qscriptcontext.html#parentContext">parentContext</a>() to get a
pointer to the context that precedes this context in the activation
stack. This is mostly useful for debugging purposes (e.g. when
constructing some form of backtrace).</p>
<p>The <a href="qscriptcontext.html#activationObject">activationObject</a>()
function returns the object that is used to hold the local
variables associated with this function call. You can replace the
activation object by calling <a href="qscriptcontext.html#setActivationObject">setActivationObject</a>().
A typical usage of these functions is when you want script code to
be evaluated in the context of the parent context, e.g. to
implement an include() function:</p>
<pre class="cpp">
<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)
{
<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();
<span class="type"><a href="qstring.html">QString</a></span> contents <span class="operator">=</span> readTheFile(fileName);
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());
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());
<span class="keyword">return</span> eng<span class="operator">-</span><span class="operator">></span>evaluate(contents<span class="operator">,</span> fileName);
}
</pre>
<p>Use <a href="qscriptcontext.html#backtrace">backtrace</a>() to
get a human-readable backtrace associated with this context. This
can be useful for debugging purposes when implementing native
functions. The <a href="qscriptcontext.html#toString">toString</a>() function provides a
string representation of the context. (<a href="qscriptcontextinfo.html">QScriptContextInfo</a> provides more
detailed debugging-related information about the
QScriptContext.)</p>
<p>Use <a href="qscriptcontext.html#engine">engine</a>() to obtain
a pointer to the <a href="qscriptengine.html">QScriptEngine</a>
that this context resides in.</p>
<hr /><h2>Type Documentation</h2><h3 class="fn"><a name="Error-enum" />QScriptContext.Error</h3><p>This enum specifies types of error.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QScriptContext.ReferenceError</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign">A reference error.</td>
</tr>
<tr>
<td class="topAlign"><tt>QScriptContext.SyntaxError</tt></td>
<td class="topAlign"><tt>2</tt></td>
<td class="topAlign">A syntax error.</td>
</tr>
<tr>
<td class="topAlign"><tt>QScriptContext.TypeError</tt></td>
<td class="topAlign"><tt>3</tt></td>
<td class="topAlign">A type error.</td>
</tr>
<tr>
<td class="topAlign"><tt>QScriptContext.RangeError</tt></td>
<td class="topAlign"><tt>4</tt></td>
<td class="topAlign">A range error.</td>
</tr>
<tr>
<td class="topAlign"><tt>QScriptContext.URIError</tt></td>
<td class="topAlign"><tt>5</tt></td>
<td class="topAlign">A URI error.</td>
</tr>
<tr>
<td class="topAlign"><tt>QScriptContext.UnknownError</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">An unknown error.</td>
</tr>
</table>
<h3 class="fn"><a name="ExecutionState-enum" />QScriptContext.ExecutionState</h3><p>This enum specifies the frameution state of the context.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QScriptContext.NormalState</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">The context is in a normal state.</td>
</tr>
<tr>
<td class="topAlign"><tt>QScriptContext.ExceptionState</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign">The context is in an exceptional state.</td>
</tr>
</table>
<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
provides access to the local variables associated with this
context.</p>
<p><b>Note:</b> The activation object might not be available if
there is no active <a href="qscriptengineagent.html">QScriptEngineAgent</a>, as it might be
optimized.</p>
<p><b>See also</b> <a href="qscriptcontext.html#setActivationObject">setActivationObject</a>(),
<a href="qscriptcontext.html#argument">argument</a>(), and <a href="qscriptcontext.html#argumentsObject">argumentsObject</a>().</p>
<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>
<p>If <i>index</i> >= <a href="qscriptcontext.html#argumentCount">argumentCount</a>(), a <a href="qscriptvalue.html">QScriptValue</a> of the primitive type
Undefined is returned.</p>
<p><b>See also</b> <a href="qscriptcontext.html#argumentCount">argumentCount</a>().</p>
<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
invocation.</p>
<p>Note that the argument count can be different from the formal
number of arguments (the <tt>length</tt> property of <a href="qscriptcontext.html#callee">callee</a>()).</p>
<p><b>See also</b> <a href="qscriptcontext.html#argument">argument</a>().</p>
<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>
<p>The arguments object has properties <tt>callee</tt> (equal to
<a href="qscriptcontext.html#callee">callee</a>()) and
<tt>length</tt> (equal to <a href="qscriptcontext.html#argumentCount">argumentCount</a>()), and
properties <tt>0</tt>, <tt>1</tt>, ..., <a href="qscriptcontext.html#argumentCount">argumentCount</a>() - 1 that
provide access to the argument values. Initially, property
<tt>P</tt> (0 <= <tt>P</tt> < <a href="qscriptcontext.html#argumentCount">argumentCount</a>()) has the
same value as argument(<tt>P</tt>). In the case when <tt>P</tt> is
less than the number of formal parameters of the function,
<tt>P</tt> shares its value with the corresponding property of the
activation object (<a href="qscriptcontext.html#activationObject">activationObject</a>()).
This means that changing this property changes the corresponding
property of the activation object and vice versa.</p>
<p><b>See also</b> <a href="qscriptcontext.html#argument">argument</a>() and <a href="qscriptcontext.html#activationObject">activationObject</a>().</p>
<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>
<p>Each line is of the form
<tt><function-name>(<arguments>)@<file-name>:<line-number></tt>.</p>
<p>To access individual pieces of debugging-related information
(for example, to construct your own backtrace representation), use
<a href="qscriptcontextinfo.html">QScriptContextInfo</a>.</p>
<p><b>See also</b> <a href="qscriptengine.html#uncaughtExceptionBacktrace">QScriptEngine.uncaughtExceptionBacktrace</a>(),
<a href="qscriptcontextinfo.html">QScriptContextInfo</a>, and
<a href="qscriptcontext.html#toString">toString</a>().</p>
<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
<a href="qscriptcontext.html">QScriptContext</a> represents an
invocation of.</p>
<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
this <a href="qscriptcontext.html">QScriptContext</a> belongs
to.</p>
<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.
<tt>"new foo()"</tt>); otherwise returns false.</p>
<p>When a function is called as constructor, the <a href="qscriptcontext.html#thisObject">thisObject</a>() contains the
newly constructed object to be initialized.</p>
<p><b>Note:</b> This function is only guaranteed to work for a
context corresponding to native functions.</p>
<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>
<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
<i>activation</i>.</p>
<p>If <i>activation</i> is not an object, this function does
nothing.</p>
<p><b>Note:</b> For a context corresponding to a JavaScript
function, this is only guaranteed to work if there was an <a href="qscriptengineagent.html">QScriptEngineAgent</a> active on the
engine while the function was evaluated.</p>
<p><b>See also</b> <a href="qscriptcontext.html#activationObject">activationObject</a>().</p>
<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
<i>thisObject</i>.</p>
<p>If <i>thisObject</i> is not an object, this function does
nothing.</p>
<p><b>See also</b> <a href="qscriptcontext.html#thisObject">thisObject</a>().</p>
<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>
<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>
<p><b>See also</b> <a href="qscriptcontext.html#setThisObject">setThisObject</a>().</p>
<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
created error object.</p>
<p>The <i>text</i> will be stored in the <tt>message</tt> property
of the error object.</p>
<p>The error object will be initialized to contain information
about the location where the error occurred; specifically, it will
have properties <tt>lineNumber</tt>, <tt>fileName</tt> and
<tt>stack</tt>. These properties are described in <a href="scripting.html#qtscript-extensions-to-ecmascript">QtScript
Extensions to ECMAScript</a>.</p>
<p><b>See also</b> <a href="qscriptcontext.html#throwValue">throwValue</a>() and <a href="qscriptcontext.html#state">state</a>().</p>
<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>
<p>Throws an error with the given <i>text</i>. Returns the created
error object.</p>
<p><b>See also</b> <a href="qscriptcontext.html#throwValue">throwValue</a>() and <a href="qscriptcontext.html#state">state</a>().</p>
<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
value thrown (the same as the argument).</p>
<p><b>See also</b> <a href="qscriptcontext.html#throwError">throwError</a>() and <a href="qscriptcontext.html#state">state</a>().</p>
<h3 class="fn"><a name="toString" />QString QScriptContext.toString (<i>self</i>)</h3><p>Returns a string representation of this context. This is useful
for debugging.</p>
<p>This function was introduced in Qt 4.4.</p>
<p><b>See also</b> <a href="qscriptcontext.html#backtrace">backtrace</a>().</p>
<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>
