<?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>