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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
|
<?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> = None)</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> = None)</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.12.1 for X11</td><td align="center" width="50%">Copyright © <a href="http://www.riverbankcomputing.com">Riverbank Computing Ltd</a> and <a href="http://www.qt.io">The Qt Company</a> 2015</td><td align="right" width="25%">Qt 4.8.7</td></tr></table></div></address></body></html>
|
