<?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>QScriptEngineAgent 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="../pyqt4ref.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">QScriptEngineAgent Class Reference<br /><sup><sup>[<a href="qtscript.html">QtScript</a> module]</sup></sup></h1><p>The QScriptEngineAgent class provides an interface to report events pertaining to <a href="qscriptengine.html">QScriptEngine</a> execution. <a href="#details">More...</a></p>
<h3>Types</h3><ul><li><div class="fn" />enum <b><a href="qscriptengineagent.html#Extension-enum">Extension</a></b> { DebuggerInvocationRequest }</li></ul><h3>Methods</h3><ul><li><div class="fn" /><b><a href="qscriptengineagent.html#QScriptEngineAgent">__init__</a></b> (<i>self</i>, QScriptEngine)</li><li><div class="fn" /><b><a href="qscriptengineagent.html#contextPop">contextPop</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qscriptengineagent.html#contextPush">contextPush</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptEngine <b><a href="qscriptengineagent.html#engine">engine</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qscriptengineagent.html#exceptionCatch">exceptionCatch</a></b> (<i>self</i>, int, QScriptValue)</li><li><div class="fn" /><b><a href="qscriptengineagent.html#exceptionThrow">exceptionThrow</a></b> (<i>self</i>, int, QScriptValue, bool)</li><li><div class="fn" />QVariant <b><a href="qscriptengineagent.html#extension">extension</a></b> (<i>self</i>, Extension, QVariant <i>argument</i> = QVariant())</li><li><div class="fn" /><b><a href="qscriptengineagent.html#functionEntry">functionEntry</a></b> (<i>self</i>, int)</li><li><div class="fn" /><b><a href="qscriptengineagent.html#functionExit">functionExit</a></b> (<i>self</i>, int, QScriptValue)</li><li><div class="fn" /><b><a href="qscriptengineagent.html#positionChange">positionChange</a></b> (<i>self</i>, int, int, int)</li><li><div class="fn" /><b><a href="qscriptengineagent.html#scriptLoad">scriptLoad</a></b> (<i>self</i>, int, QString, QString, int)</li><li><div class="fn" /><b><a href="qscriptengineagent.html#scriptUnload">scriptUnload</a></b> (<i>self</i>, int)</li><li><div class="fn" />bool <b><a href="qscriptengineagent.html#supportsExtension">supportsExtension</a></b> (<i>self</i>, Extension)</li></ul><a name="details" /><hr /><h2>Detailed Description</h2><p>The QScriptEngineAgent class provides an interface to report events pertaining to <a href="qscriptengine.html">QScriptEngine</a> execution.</p>
<p>The QScriptEngineAgent class is the basis of tools that monitor and/or control the execution of a <a href="qscriptengine.html">QScriptEngine</a>, such as debuggers and profilers.</p>
<p>To process script loading and unloading events, reimplement the <a href="qscriptengineagent.html#scriptLoad">scriptLoad</a>() and <a href="qscriptengineagent.html#scriptUnload">scriptUnload</a>() functions. <a href="qscriptengineagent.html#scriptLoad">scriptLoad</a>() is called after the input to <a href="qscriptengine.html#evaluate">QScriptEngine.evaluate</a>() has been parsed, right before the given script is executed. The engine assigns each script an ID, which is available as one of the arguments to <a href="qscriptengineagent.html#scriptLoad">scriptLoad</a>(); subsequently, other event handlers can use the ID to identify a particular script. One common usage of <a href="qscriptengineagent.html#scriptLoad">scriptLoad</a>() is to retain the script text, filename and base line number (the original input to <a href="qscriptengine.html#evaluate">QScriptEngine.evaluate</a>()), so that other event handlers can e.g. map a line number to the corresponding line of text.</p>
<p><a href="qscriptengineagent.html#scriptUnload">scriptUnload</a>() is called when the <a href="qscriptengine.html">QScriptEngine</a> has no further use for a script; the QScriptEngineAgent may at this point safely discard any resources associated with the script (such as the script text). Note that after <a href="qscriptengineagent.html#scriptUnload">scriptUnload</a>() has been called, the <a href="qscriptengine.html">QScriptEngine</a> may reuse the relevant script ID for new scripts (i.e. as argument to a subsequent call to <a href="qscriptengineagent.html#scriptLoad">scriptLoad</a>()).</p>
<p>Evaluating the following script will result in <a href="qscriptengineagent.html#scriptUnload">scriptUnload</a>() being called immediately after evaluation has completed:</p>
<pre> var a = Math.random() + 2;</pre>
<p>Evaluating the following script will \b{not} result in a call to <a href="qscriptengineagent.html#scriptUnload">scriptUnload</a>() when evaluation has completed:</p>
<pre> function cube(a) {
return a * a * a;
}
var a = cube(3);</pre>
<p>The script isn't unloaded because it defines a function (<tt>cube</tt>) that remains in the script environment after evaluation has completed. If a subsequent script removed the <tt>cube</tt> function (e.g. by setting it to <tt>null</tt>), <a href="qscriptengineagent.html#scriptUnload">scriptUnload</a>() would be called when the function is garbage collected. In general terms, a script isn't unloaded until the engine has determined that none of its contents is referenced.</p>
<p>To process script function calls and returns, reimplement the <a href="qscriptengineagent.html#functionEntry">functionEntry</a>() and <a href="qscriptengineagent.html#functionExit">functionExit</a>() functions. <a href="qscriptengineagent.html#functionEntry">functionEntry</a>() is called when a script function is about to be executed; <a href="qscriptengineagent.html#functionExit">functionExit</a>() is called when a script function is about to return, either normally or due to an exception.</p>
<p>To process individual script statements, reimplement <a href="qscriptengineagent.html#positionChange">positionChange</a>(). <a href="qscriptengineagent.html#positionChange">positionChange</a>() is called each time the engine is about to execute a new statement of a script, and thus offers the finest level of script monitoring.</p>
<p>To process exceptions, reimplement <a href="qscriptengineagent.html#exceptionThrow">exceptionThrow</a>() and <a href="qscriptengineagent.html#exceptionCatch">exceptionCatch</a>(). <a href="qscriptengineagent.html#exceptionThrow">exceptionThrow</a>() is called when a script exception is thrown, before it has been handled. <a href="qscriptengineagent.html#exceptionCatch">exceptionCatch</a>() is called when an exception handler is present, and execution is about to be resumed at the handler code.</p>
<p>See also <a href="qscriptengine.html#setAgent">QScriptEngine.setAgent</a>() and <a href="qscriptcontextinfo.html">QScriptContextInfo</a>.</p>
<hr /><h2>Type Documentation</h2><h3 class="fn"><a name="Extension-enum" />QScriptEngineAgent.Extension</h3><p>This enum specifies the possible extensions to a <a href="qscriptengineagent.html">QScriptEngineAgent</a>.</p>
<p><table border="1" cellpadding="2" cellspacing="1" class="valuelist" width="100%">
<tr><th width="25%">Constant</th><th width="15%">Value</th><th width="60%">Description</th></tr>
<tr><td valign="top"><tt>QScriptEngineAgent.DebuggerInvocationRequest</tt></td><td align="center" valign="top"><tt>0</tt></td><td valign="top">The agent handles <tt>debugger</tt> script statements.</td></tr>
</table></p>
<p>See also <a href="qscriptengineagent.html#extension">extension</a>().</p>
<hr /><h2>Method Documentation</h2><h3 class="fn"><a name="QScriptEngineAgent" />QScriptEngineAgent.__init__ (<i>self</i>, <a href="qscriptengine.html">QScriptEngine</a>)</h3><p>Constructs a <a href="qscriptengineagent.html">QScriptEngineAgent</a> object for the given <i>engine</i>.</p>
<p>The engine takes ownership of the agent.</p>
<p>Call <a href="qscriptengine.html#setAgent">QScriptEngine.setAgent</a>() to make this agent the active agent.</p>
<a name="//apple_ref/cpp/instm/QScriptEngineAgent/~QScriptEngineAgent" />
<h3 class="fn"><a name="contextPop" />QScriptEngineAgent.contextPop (<i>self</i>)</h3><p>This function is called when the current script context is about to be popped.</p>
<p>The default implementation does nothing.</p>
<p>See also <a href="qscriptengineagent.html#contextPush">contextPush</a>() and <a href="qscriptengineagent.html#functionExit">functionExit</a>().</p>
<a name="//apple_ref/cpp/instm/QScriptEngineAgent/contextPush" />
<h3 class="fn"><a name="contextPush" />QScriptEngineAgent.contextPush (<i>self</i>)</h3><p>This function is called when a new script context has been pushed.</p>
<p>The default implementation does nothing.</p>
<p>See also <a href="qscriptengineagent.html#contextPop">contextPop</a>() and <a href="qscriptengineagent.html#functionEntry">functionEntry</a>().</p>
<a name="//apple_ref/cpp/instm/QScriptEngineAgent/engine" />
<h3 class="fn"><a name="engine" /><a href="qscriptengine.html">QScriptEngine</a> QScriptEngineAgent.engine (<i>self</i>)</h3><p>Returns the <a href="qscriptengine.html">QScriptEngine</a> that this agent is associated with.</p>
<a name="//apple_ref/cpp/instm/QScriptEngineAgent/exceptionCatch" />
<h3 class="fn"><a name="exceptionCatch" />QScriptEngineAgent.exceptionCatch (<i>self</i>, int, <a href="qscriptvalue.html">QScriptValue</a>)</h3><p>This function is called when the given <i>exception</i> is about to be caught, in the script identified by <i>scriptId</i>.</p>
<p>Reimplement this function if you want to handle this event.</p>
<p>The default implementation does nothing.</p>
<p>See also <a href="qscriptengineagent.html#exceptionThrow">exceptionThrow</a>().</p>
<a name="//apple_ref/cpp/instm/QScriptEngineAgent/exceptionThrow" />
<h3 class="fn"><a name="exceptionThrow" />QScriptEngineAgent.exceptionThrow (<i>self</i>, int, <a href="qscriptvalue.html">QScriptValue</a>, bool)</h3><p>This function is called when the given <i>exception</i> has occurred in the engine, in the script identified by <i>scriptId</i>. If the exception was thrown by a native Qt Script function, <i>scriptId</i> is -1.</p>
<p>If <i>hasHandler</i> is true, there is a <tt>catch</tt> or <tt>finally</tt> block that will handle the exception. If <i>hasHandler</i> is false, there is no handler for the exception.</p>
<p>Reimplement this function if you want to handle this event. For example, a debugger can notify the user when an uncaught exception occurs (i.e. <i>hasHandler</i> is false).</p>
<p>The default implementation does nothing.</p>
<p>See also <a href="qscriptengineagent.html#exceptionCatch">exceptionCatch</a>().</p>
<a name="//apple_ref/cpp/instm/QScriptEngineAgent/extension" />
<h3 class="fn"><a name="extension" />QVariant QScriptEngineAgent.extension (<i>self</i>, <a href="qscriptengineagent.html#Extension-enum">Extension</a>, QVariant <i>argument</i> = QVariant())</h3><p>This virtual function can be reimplemented in a <a href="qscriptengineagent.html">QScriptEngineAgent</a> subclass to provide support for extensions. The optional <i>argument</i> can be provided as input to the <i>extension</i>; the result must be returned in the form of a <a href="qvariant.html">QVariant</a>. You can call <a href="qscriptengineagent.html#supportsExtension">supportsExtension</a>() to check if an extension is supported by the <a href="qscriptengineagent.html">QScriptEngineAgent</a>. By default, no extensions are supported, and this function returns an invalid <a href="qvariant.html">QVariant</a>.</p>
<p>If you implement the <a href="qscriptengineagent.html#Extension-enum">DebuggerInvocationRequest</a> extension, Qt Script will call this function when a <tt>debugger</tt> statement is encountered in a script. The <i>argument</i> is a <a href="qvariant.html#QVariantList-typedef">QVariantList</a> containing three items: The first item is the scriptId (a long), the second item is the line number (an int), and the third item is the column number (an int).</p>
<p>See also <a href="qscriptengineagent.html#supportsExtension">supportsExtension</a>().</p>
<a name="//apple_ref/cpp/instm/QScriptEngineAgent/functionEntry" />
<h3 class="fn"><a name="functionEntry" />QScriptEngineAgent.functionEntry (<i>self</i>, int)</h3><p>This function is called when a script function is called in the engine. If the script function is not a native Qt Script function, it resides in the script identified by <i>scriptId</i>; otherwise, <i>scriptId</i> is -1.</p>
<p>This function is called just before execution of the script function begins. You can obtain the <a href="qscriptcontext.html">QScriptContext</a> associated with the function call with <a href="qscriptengine.html#currentContext">QScriptEngine.currentContext</a>(). The arguments passed to the function are available.</p>
<p>Reimplement this function to handle this event. For example, a debugger implementation could reimplement this function (and <a href="qscriptengineagent.html#functionExit">functionExit</a>()) to keep track of the call stack and provide step-over functionality.</p>
<p>The default implementation does nothing.</p>
<p>See also <a href="qscriptengineagent.html#functionExit">functionExit</a>(), <a href="qscriptengineagent.html#positionChange">positionChange</a>(), and <a href="qscriptengine.html#currentContext">QScriptEngine.currentContext</a>().</p>
<a name="//apple_ref/cpp/instm/QScriptEngineAgent/functionExit" />
<h3 class="fn"><a name="functionExit" />QScriptEngineAgent.functionExit (<i>self</i>, int, <a href="qscriptvalue.html">QScriptValue</a>)</h3><p>This function is called when the currently executing script function is about to return. If the script function is not a native Qt Script function, it resides in the script identified by <i>scriptId</i>; otherwise, <i>scriptId</i> is -1. The <i>returnValue</i> is the value that the script function will return.</p>
<p>This function is called just before the script function returns. You can still access the <a href="qscriptcontext.html">QScriptContext</a> associated with the script function call with <a href="qscriptengine.html#currentContext">QScriptEngine.currentContext</a>().</p>
<p>If the engine's <a href="qscriptengine.html#hasUncaughtException">hasUncaughtException</a>() function returns true, the script function is exiting due to an exception; otherwise, the script function is returning normally.</p>
<p>Reimplement this function to handle this event; typically you will then also want to reimplement <a href="qscriptengineagent.html#functionEntry">functionEntry</a>().</p>
<p>The default implementation does nothing.</p>
<p>See also <a href="qscriptengineagent.html#functionEntry">functionEntry</a>() and <a href="qscriptengine.html#hasUncaughtException">QScriptEngine.hasUncaughtException</a>().</p>
<a name="//apple_ref/cpp/instm/QScriptEngineAgent/positionChange" />
<h3 class="fn"><a name="positionChange" />QScriptEngineAgent.positionChange (<i>self</i>, int, int, int)</h3><p>This function is called when the engine is about to execute a new statement in the script identified by <i>scriptId</i>. The statement begins on the line and column specified by <i>lineNumber</i> and <i>columnNumber</i>. This event is not generated for native Qt Script functions.</p>
<p>Reimplement this function to handle this event. For example, a debugger implementation could reimplement this function to provide line-by-line stepping, and a profiler implementation could use it to count the number of times each statement is executed.</p>
<p>The default implementation does nothing.</p>
<p>See also <a href="qscriptengineagent.html#scriptLoad">scriptLoad</a>() and <a href="qscriptengineagent.html#functionEntry">functionEntry</a>().</p>
<a name="//apple_ref/cpp/instm/QScriptEngineAgent/scriptLoad" />
<h3 class="fn"><a name="scriptLoad" />QScriptEngineAgent.scriptLoad (<i>self</i>, int, QString, QString, int)</h3><p>This function is called when the engine has parsed a script and has associated it with the given <i>id</i>. The id can be used to identify this particular script in subsequent event notifications.</p>
<p><i>program</i>, <i>fileName</i> and <i>baseLineNumber</i> are the original arguments to the <a href="qscriptengine.html#evaluate">QScriptEngine.evaluate</a>() call that triggered this event.</p>
<p>This function is called just before the script is about to be evaluated.</p>
<p>You can reimplement this function to record information about the script; for example, by retaining the script text, you can obtain the line of text corresponding to a line number in a subsequent call to <a href="qscriptengineagent.html#positionChange">positionChange</a>().</p>
<p>The default implementation does nothing.</p>
<p>See also <a href="qscriptengineagent.html#scriptUnload">scriptUnload</a>().</p>
<a name="//apple_ref/cpp/instm/QScriptEngineAgent/scriptUnload" />
<h3 class="fn"><a name="scriptUnload" />QScriptEngineAgent.scriptUnload (<i>self</i>, int)</h3><p>This function is called when the engine has discarded the script identified by the given <i>id</i>.</p>
<p>You can reimplement this function to clean up any resources you have associated with the script.</p>
<p>The default implementation does nothing.</p>
<p>See also <a href="qscriptengineagent.html#scriptLoad">scriptLoad</a>().</p>
<a name="//apple_ref/cpp/instm/QScriptEngineAgent/supportsExtension" />
<h3 class="fn"><a name="supportsExtension" />bool QScriptEngineAgent.supportsExtension (<i>self</i>, <a href="qscriptengineagent.html#Extension-enum">Extension</a>)</h3><p>Returns true if the <a href="qscriptengineagent.html">QScriptEngineAgent</a> supports the given <i>extension</i>; otherwise, false is returned. By default, no extensions are supported.</p>
<p>See also <a href="qscriptengineagent.html#extension">extension</a>().</p>
<p /><address><hr /><div align="center"><table border="0" cellspacing="0" width="100%"><tr class="address"><td align="left" width="25%">PyQt 4.7.4 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> 2010</td><td align="right" width="25%">Qt 4.6.3</td></tr></table></div></address></body></html>
