<?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="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">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 <i>engine</i>)</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 <i>scriptId</i>, QScriptValue <i>exception</i>)</li><li><div class="fn" /><b><a href="qscriptengineagent.html#exceptionThrow">exceptionThrow</a></b> (<i>self</i>, int <i>scriptId</i>, QScriptValue <i>exception</i>, bool <i>hasHandler</i>)</li><li><div class="fn" />QVariant <b><a href="qscriptengineagent.html#extension">extension</a></b> (<i>self</i>, Extension <i>extension</i>, QVariant <i>argument</i> = QVariant())</li><li><div class="fn" /><b><a href="qscriptengineagent.html#functionEntry">functionEntry</a></b> (<i>self</i>, int <i>scriptId</i>)</li><li><div class="fn" /><b><a href="qscriptengineagent.html#functionExit">functionExit</a></b> (<i>self</i>, int <i>scriptId</i>, QScriptValue <i>returnValue</i>)</li><li><div class="fn" /><b><a href="qscriptengineagent.html#positionChange">positionChange</a></b> (<i>self</i>, int <i>scriptId</i>, int <i>lineNumber</i>, int <i>columnNumber</i>)</li><li><div class="fn" /><b><a href="qscriptengineagent.html#scriptLoad">scriptLoad</a></b> (<i>self</i>, int <i>id</i>, QString <i>program</i>, QString <i>fileName</i>, int <i>baseLineNumber</i>)</li><li><div class="fn" /><b><a href="qscriptengineagent.html#scriptUnload">scriptUnload</a></b> (<i>self</i>, int <i>id</i>)</li><li><div class="fn" />bool <b><a href="qscriptengineagent.html#supportsExtension">supportsExtension</a></b> (<i>self</i>, Extension <i>extension</i>)</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 class="cpp">
var a <span class="operator">=</span> Math<span class="operator">.</span>random() <span class="operator">+</span> <span class="number">2</span>;
</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 class="cpp">
function cube(a) {
<span class="keyword">return</span> a <span class="operator">*</span> a <span class="operator">*</span> a;
}
var a <span class="operator">=</span> cube(<span class="number">3</span>);
</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>
<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>
<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>QScriptEngineAgent.DebuggerInvocationRequest</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">The agent handles <tt>debugger</tt> script
statements.</td>
</tr>
</table>
<p><b>See also</b> <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> <i>engine</i>)</h3><p>The <i>engine</i> argument, if not None, causes <i>self</i> to be owned by Qt instead of PyQt.</p><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>
<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><b>See also</b> <a href="qscriptengineagent.html#contextPush">contextPush</a>() and
<a href="qscriptengineagent.html#functionExit">functionExit</a>().</p>
<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><b>See also</b> <a href="qscriptengineagent.html#contextPop">contextPop</a>() and <a href="qscriptengineagent.html#functionEntry">functionEntry</a>().</p>
<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>
<h3 class="fn"><a name="exceptionCatch" />QScriptEngineAgent.exceptionCatch (<i>self</i>, int <i>scriptId</i>, <a href="qscriptvalue.html">QScriptValue</a> <i>exception</i>)</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><b>See also</b> <a href="qscriptengineagent.html#exceptionThrow">exceptionThrow</a>().</p>
<h3 class="fn"><a name="exceptionThrow" />QScriptEngineAgent.exceptionThrow (<i>self</i>, int <i>scriptId</i>, <a href="qscriptvalue.html">QScriptValue</a> <i>exception</i>, bool <i>hasHandler</i>)</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><b>See also</b> <a href="qscriptengineagent.html#exceptionCatch">exceptionCatch</a>().</p>
<h3 class="fn"><a name="extension" />QVariant QScriptEngineAgent.extension (<i>self</i>, <a href="qscriptengineagent.html#Extension-enum">Extension</a> <i>extension</i>, 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><b>See also</b> <a href="qscriptengineagent.html#supportsExtension">supportsExtension</a>().</p>
<h3 class="fn"><a name="functionEntry" />QScriptEngineAgent.functionEntry (<i>self</i>, int <i>scriptId</i>)</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><b>See also</b> <a href="qscriptengineagent.html#functionExit">functionExit</a>(), <a href="qscriptengineagent.html#positionChange">positionChange</a>(), and
<a href="qscriptengine.html#currentContext">QScriptEngine.currentContext</a>().</p>
<h3 class="fn"><a name="functionExit" />QScriptEngineAgent.functionExit (<i>self</i>, int <i>scriptId</i>, <a href="qscriptvalue.html">QScriptValue</a> <i>returnValue</i>)</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><b>See also</b> <a href="qscriptengineagent.html#functionEntry">functionEntry</a>() and
<a href="qscriptengine.html#hasUncaughtException">QScriptEngine.hasUncaughtException</a>().</p>
<h3 class="fn"><a name="positionChange" />QScriptEngineAgent.positionChange (<i>self</i>, int <i>scriptId</i>, int <i>lineNumber</i>, int <i>columnNumber</i>)</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> 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><b>Note:</b> <i>columnNumber</i> is undefined</p>
<p><b>See also</b> <a href="qscriptengineagent.html#scriptLoad">scriptLoad</a>() and <a href="qscriptengineagent.html#functionEntry">functionEntry</a>().</p>
<h3 class="fn"><a name="scriptLoad" />QScriptEngineAgent.scriptLoad (<i>self</i>, int <i>id</i>, QString <i>program</i>, QString <i>fileName</i>, int <i>baseLineNumber</i>)</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><b>See also</b> <a href="qscriptengineagent.html#scriptUnload">scriptUnload</a>().</p>
<h3 class="fn"><a name="scriptUnload" />QScriptEngineAgent.scriptUnload (<i>self</i>, int <i>id</i>)</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><b>See also</b> <a href="qscriptengineagent.html#scriptLoad">scriptLoad</a>().</p>
<h3 class="fn"><a name="supportsExtension" />bool QScriptEngineAgent.supportsExtension (<i>self</i>, <a href="qscriptengineagent.html#Extension-enum">Extension</a> <i>extension</i>)</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><b>See also</b> <a href="qscriptengineagent.html#extension">extension</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>
