1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- qscriptengineagent.cpp -->
<head>
<title>QScriptEngineAgent Class Reference</title>
<link href="classic.css" rel="stylesheet" type="text/css" />
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top" width="32"><img src="images/qt-logo.png" align="left" width="57" height="67" border="0" /></td>
<td width="1"> </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a></td>
</tr></table><h1 class="title">QScriptEngineAgent Class Reference<br /><span class="small-subtitle">[<a href="http://qt.nokia.com/doc/4.6/qtscript.html">QtScript</a> module]</span>
</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>
<pre> #include <QScriptEngineAgent></pre><p><b>This class is not part of the Qt GUI Framework Edition.</b></p>
<p>This class was introduced in qtscriptclassic 4.4.</p>
<ul>
<li><a href="qscriptengineagent-members.html">List of all members, including inherited members</a></li>
</ul>
<hr />
<a name="public-types"></a>
<h2>Public Types</h2>
<table class="alignedsummary" border="0" cellpadding="0" cellspacing="0" width="100%">
<tr><td class="memItemLeft" align="right" valign="top">enum </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#Extension-enum">Extension</a></b> { DebuggerInvocationRequest }</td></tr>
</table>
<hr />
<a name="public-functions"></a>
<h2>Public Functions</h2>
<table class="alignedsummary" border="0" cellpadding="0" cellspacing="0" width="100%">
<tr><td class="memItemLeft" align="right" valign="top"></td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#QScriptEngineAgent">QScriptEngineAgent</a></b> ( QScriptEngine * <i>engine</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#dtor.QScriptEngineAgent">~QScriptEngineAgent</a></b> ()</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#contextPop">contextPop</a></b> ()</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#contextPush">contextPush</a></b> ()</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">QScriptEngine * </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#engine">engine</a></b> () const</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#exceptionCatch">exceptionCatch</a></b> ( qint64 <i>scriptId</i>, const QScriptValue & <i>exception</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#exceptionThrow">exceptionThrow</a></b> ( qint64 <i>scriptId</i>, const QScriptValue & <i>exception</i>, bool <i>hasHandler</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual QVariant </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#extension">extension</a></b> ( Extension <i>extension</i>, const QVariant & <i>argument</i> = QVariant() )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#functionEntry">functionEntry</a></b> ( qint64 <i>scriptId</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#functionExit">functionExit</a></b> ( qint64 <i>scriptId</i>, const QScriptValue & <i>returnValue</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#positionChange">positionChange</a></b> ( qint64 <i>scriptId</i>, int <i>lineNumber</i>, int <i>columnNumber</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#scriptLoad">scriptLoad</a></b> ( qint64 <i>id</i>, const QString & <i>program</i>, const QString & <i>fileName</i>, int <i>baseLineNumber</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#scriptUnload">scriptUnload</a></b> ( qint64 <i>id</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual bool </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#supportsExtension">supportsExtension</a></b> ( Extension <i>extension</i> ) const</td></tr>
</table>
<a name="details"></a>
<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>Member Type Documentation</h2>
<h3 class="fn"><a name="Extension-enum"></a>enum QScriptEngineAgent::Extension</h3>
<p>This enum specifies the possible extensions to a <a href="qscriptengineagent.html">QScriptEngineAgent</a>.</p>
<p><table class="valuelist" border="1" cellpadding="2" cellspacing="1" 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>Member Function Documentation</h2>
<h3 class="fn"><a name="QScriptEngineAgent"></a>QScriptEngineAgent::QScriptEngineAgent ( <a href="qscriptengine.html">QScriptEngine</a> * <i>engine</i> )</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>
<h3 class="fn"><a name="dtor.QScriptEngineAgent"></a>QScriptEngineAgent::~QScriptEngineAgent () <tt> [virtual]</tt></h3>
<p>Destroys this <a href="qscriptengineagent.html">QScriptEngineAgent</a>.</p>
<h3 class="fn"><a name="contextPop"></a>void QScriptEngineAgent::contextPop () <tt> [virtual]</tt></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>
<h3 class="fn"><a name="contextPush"></a>void QScriptEngineAgent::contextPush () <tt> [virtual]</tt></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>
<h3 class="fn"><a name="engine"></a><a href="qscriptengine.html">QScriptEngine</a> * QScriptEngineAgent::engine () const</h3>
<p>Returns the <a href="qscriptengine.html">QScriptEngine</a> that this agent is associated with.</p>
<h3 class="fn"><a name="exceptionCatch"></a>void QScriptEngineAgent::exceptionCatch ( <a href="http://qt.nokia.com/doc/4.6/qtglobal.html#qint64-typedef">qint64</a> <i>scriptId</i>, const <a href="qscriptvalue.html">QScriptValue</a> & <i>exception</i> ) <tt> [virtual]</tt></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>
<h3 class="fn"><a name="exceptionThrow"></a>void QScriptEngineAgent::exceptionThrow ( <a href="http://qt.nokia.com/doc/4.6/qtglobal.html#qint64-typedef">qint64</a> <i>scriptId</i>, const <a href="qscriptvalue.html">QScriptValue</a> & <i>exception</i>, bool <i>hasHandler</i> ) <tt> [virtual]</tt></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>
<h3 class="fn"><a name="extension"></a><a href="http://qt.nokia.com/doc/4.6/qvariant.html">QVariant</a> QScriptEngineAgent::extension ( <a href="qscriptengineagent.html#Extension-enum">Extension</a> <i>extension</i>, const <a href="http://qt.nokia.com/doc/4.6/qvariant.html">QVariant</a> & <i>argument</i> = QVariant() ) <tt> [virtual]</tt></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="http://qt.nokia.com/doc/4.6/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="http://qt.nokia.com/doc/4.6/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="http://qt.nokia.com/doc/4.6/qvariant.html#QVariantList-typedef">QVariantList</a> containing three items: The first item is the scriptId (a qint64), 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>
<h3 class="fn"><a name="functionEntry"></a>void QScriptEngineAgent::functionEntry ( <a href="http://qt.nokia.com/doc/4.6/qtglobal.html#qint64-typedef">qint64</a> <i>scriptId</i> ) <tt> [virtual]</tt></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>
<h3 class="fn"><a name="functionExit"></a>void QScriptEngineAgent::functionExit ( <a href="http://qt.nokia.com/doc/4.6/qtglobal.html#qint64-typedef">qint64</a> <i>scriptId</i>, const <a href="qscriptvalue.html">QScriptValue</a> & <i>returnValue</i> ) <tt> [virtual]</tt></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>
<h3 class="fn"><a name="positionChange"></a>void QScriptEngineAgent::positionChange ( <a href="http://qt.nokia.com/doc/4.6/qtglobal.html#qint64-typedef">qint64</a> <i>scriptId</i>, int <i>lineNumber</i>, int <i>columnNumber</i> ) <tt> [virtual]</tt></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>
<h3 class="fn"><a name="scriptLoad"></a>void QScriptEngineAgent::scriptLoad ( <a href="http://qt.nokia.com/doc/4.6/qtglobal.html#qint64-typedef">qint64</a> <i>id</i>, const <a href="http://qt.nokia.com/doc/4.6/qstring.html">QString</a> & <i>program</i>, const <a href="http://qt.nokia.com/doc/4.6/qstring.html">QString</a> & <i>fileName</i>, int <i>baseLineNumber</i> ) <tt> [virtual]</tt></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>
<h3 class="fn"><a name="scriptUnload"></a>void QScriptEngineAgent::scriptUnload ( <a href="http://qt.nokia.com/doc/4.6/qtglobal.html#qint64-typedef">qint64</a> <i>id</i> ) <tt> [virtual]</tt></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>
<h3 class="fn"><a name="supportsExtension"></a>bool QScriptEngineAgent::supportsExtension ( <a href="qscriptengineagent.html#Extension-enum">Extension</a> <i>extension</i> ) const <tt> [virtual]</tt></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 width="100%" cellspacing="0" border="0"><tr class="address">
<td width="30%" align="left">Copyright © 2010 Nokia Corporation and/or its subsidiary(-ies)</td>
<td width="40%" align="center"><a href="http://qt.nokia.com/doc/trademarks.html">Trademarks</a></td>
<td width="30%" align="right"><div align="right">Qt Solutions</div></td>
</tr></table></div></address></body>
</html>
|
