6
6
td.postheader { font-family: sans-serif }
7
7
tr.address { font-family: sans-serif }
8
8
body { background: #ffffff; color: black; }
9
</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">QScriptEngine Class Reference<br /><sup><sup>[<a href="qtscript.html">QtScript</a> module]</sup></sup></h1><p>The QScriptEngine class provides an environment for evaluating Qt Script code. <a href="#details">More...</a></p>
10
<p>Inherits <a href="qobject.html">QObject</a>.</p><h3>Types</h3><ul><li><div class="fn" />enum <b><a href="qscriptengine.html#QObjectWrapOption-enum">QObjectWrapOption</a></b> { ExcludeChildObjects, ExcludeSuperClassMethods, ExcludeSuperClassProperties, AutoCreateDynamicProperties, ..., ExcludeDeleteLater }</li><li><div class="fn" />class <b><a href="qscriptengine-qobjectwrapoptions.html">QObjectWrapOptions</a></b></li><li><div class="fn" />enum <b><a href="qscriptengine.html#ValueOwnership-enum">ValueOwnership</a></b> { QtOwnership, ScriptOwnership, AutoOwnership }</li></ul><h3>Methods</h3><ul><li><div class="fn" /><b><a href="qscriptengine.html#QScriptEngine">__init__</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qscriptengine.html#QScriptEngine-2">__init__</a></b> (<i>self</i>, QObject)</li><li><div class="fn" /><b><a href="qscriptengine.html#abortEvaluation">abortEvaluation</a></b> (<i>self</i>, QScriptValue <i>result</i> = QScriptValue())</li><li><div class="fn" />QScriptEngineAgent <b><a href="qscriptengine.html#agent">agent</a></b> (<i>self</i>)</li><li><div class="fn" />QStringList <b><a href="qscriptengine.html#availableExtensions">availableExtensions</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qscriptengine.html#canEvaluate">canEvaluate</a></b> (<i>self</i>, QString)</li><li><div class="fn" /><b><a href="qscriptengine.html#clearExceptions">clearExceptions</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qscriptengine.html#collectGarbage">collectGarbage</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptContext <b><a href="qscriptengine.html#currentContext">currentContext</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#defaultPrototype">defaultPrototype</a></b> (<i>self</i>, int)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#evaluate">evaluate</a></b> (<i>self</i>, QString, QString <i>fileName</i> = QString(), int <i>lineNumber</i> = 1)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#globalObject">globalObject</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qscriptengine.html#hasUncaughtException">hasUncaughtException</a></b> (<i>self</i>)</li><li><div class="fn" />QStringList <b><a href="qscriptengine.html#importedExtensions">importedExtensions</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#importExtension">importExtension</a></b> (<i>self</i>, QString)</li><li><div class="fn" /><b><a href="qscriptengine.html#installTranslatorFunctions">installTranslatorFunctions</a></b> (<i>self</i>, QScriptValue <i>object</i> = QScriptValue())</li><li><div class="fn" />bool <b><a href="qscriptengine.html#isEvaluating">isEvaluating</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newArray">newArray</a></b> (<i>self</i>, int <i>length</i> = 0)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newDate">newDate</a></b> (<i>self</i>, float)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newDate-2">newDate</a></b> (<i>self</i>, QDateTime)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newFunction">newFunction</a></b> (<i>self</i>, callable, int <i>length</i> = 0)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newFunction-2">newFunction</a></b> (<i>self</i>, callable, QScriptValue, int <i>length</i> = 0)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newObject">newObject</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newObject-2">newObject</a></b> (<i>self</i>, QScriptClass, QScriptValue <i>data</i> = QScriptValue())</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newQMetaObject">newQMetaObject</a></b> (<i>self</i>, QMetaObject, QScriptValue <i>ctor</i> = QScriptValue())</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newQObject">newQObject</a></b> (<i>self</i>, QObject, ValueOwnership <i>ownership</i> = QScriptEngine.QtOwnership, QObjectWrapOptions <i>options</i> = 0)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newQObject-2">newQObject</a></b> (<i>self</i>, QScriptValue, QObject, ValueOwnership <i>ownership</i> = QScriptEngine.QtOwnership, QObjectWrapOptions <i>options</i> = 0)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newRegExp">newRegExp</a></b> (<i>self</i>, QRegExp)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newRegExp-2">newRegExp</a></b> (<i>self</i>, QString, QString)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newVariant">newVariant</a></b> (<i>self</i>, QVariant)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newVariant-2">newVariant</a></b> (<i>self</i>, QScriptValue, QVariant)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#nullValue">nullValue</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qscriptengine.html#popContext">popContext</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qscriptengine.html#processEventsInterval">processEventsInterval</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptContext <b><a href="qscriptengine.html#pushContext">pushContext</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qscriptengine.html#setAgent">setAgent</a></b> (<i>self</i>, QScriptEngineAgent)</li><li><div class="fn" /><b><a href="qscriptengine.html#setDefaultPrototype">setDefaultPrototype</a></b> (<i>self</i>, int, QScriptValue)</li><li><div class="fn" /><b><a href="qscriptengine.html#setGlobalObject">setGlobalObject</a></b> (<i>self</i>, QScriptValue)</li><li><div class="fn" /><b><a href="qscriptengine.html#setProcessEventsInterval">setProcessEventsInterval</a></b> (<i>self</i>, int)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#toObject">toObject</a></b> (<i>self</i>, QScriptValue)</li><li><div class="fn" />QScriptString <b><a href="qscriptengine.html#toStringHandle">toStringHandle</a></b> (<i>self</i>, QString)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#uncaughtException">uncaughtException</a></b> (<i>self</i>)</li><li><div class="fn" />QStringList <b><a href="qscriptengine.html#uncaughtExceptionBacktrace">uncaughtExceptionBacktrace</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qscriptengine.html#uncaughtExceptionLineNumber">uncaughtExceptionLineNumber</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#undefinedValue">undefinedValue</a></b> (<i>self</i>)</li></ul><h3>Static Methods</h3><ul><li><div class="fn" />QScriptSyntaxCheckResult <b><a href="qscriptengine.html#checkSyntax">checkSyntax</a></b> (QString)</li></ul><h3>Qt Signals</h3><ul><li><div class="fn" />void <b><a href="qscriptengine.html#signalHandlerException">signalHandlerException</a></b> (const QScriptValue&)</li></ul><a name="details" /><hr /><h2>Detailed Description</h2><p>The QScriptEngine class provides an environment for evaluating Qt Script code.</p>
11
<p>See the <a href="qtscript.html">QtScript</a> documentation for information about the Qt Script language, and how to get started with scripting your C++ application.</p>
12
<a name="evaluating-scripts" />
9
</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">QScriptEngine Class Reference<br /><sup><sup>[<a href="qtscript.html">QtScript</a> module]</sup></sup></h1><p>The QScriptEngine class provides an environment for evaluating
10
Qt Script code. <a href="#details">More...</a></p>
12
<p>Inherits <a href="qobject.html">QObject</a>.</p><h3>Types</h3><ul><li><div class="fn" />enum <b><a href="qscriptengine.html#QObjectWrapOption-enum">QObjectWrapOption</a></b> { ExcludeChildObjects, ExcludeSuperClassMethods, ExcludeSuperClassProperties, AutoCreateDynamicProperties, ..., ExcludeSlots }</li><li><div class="fn" />class <b><a href="qscriptengine-qobjectwrapoptions.html">QObjectWrapOptions</a></b></li><li><div class="fn" />enum <b><a href="qscriptengine.html#ValueOwnership-enum">ValueOwnership</a></b> { QtOwnership, ScriptOwnership, AutoOwnership }</li></ul><h3>Methods</h3><ul><li><div class="fn" /><b><a href="qscriptengine.html#QScriptEngine">__init__</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qscriptengine.html#QScriptEngine-2">__init__</a></b> (<i>self</i>, QObject)</li><li><div class="fn" /><b><a href="qscriptengine.html#abortEvaluation">abortEvaluation</a></b> (<i>self</i>, QScriptValue <i>result</i> = QScriptValue())</li><li><div class="fn" />QScriptEngineAgent <b><a href="qscriptengine.html#agent">agent</a></b> (<i>self</i>)</li><li><div class="fn" />QStringList <b><a href="qscriptengine.html#availableExtensions">availableExtensions</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qscriptengine.html#canEvaluate">canEvaluate</a></b> (<i>self</i>, QString)</li><li><div class="fn" /><b><a href="qscriptengine.html#clearExceptions">clearExceptions</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qscriptengine.html#collectGarbage">collectGarbage</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptContext <b><a href="qscriptengine.html#currentContext">currentContext</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#defaultPrototype">defaultPrototype</a></b> (<i>self</i>, int)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#evaluate">evaluate</a></b> (<i>self</i>, QString, QString <i>fileName</i> = QString(), int <i>lineNumber</i> = 1)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#globalObject">globalObject</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qscriptengine.html#hasUncaughtException">hasUncaughtException</a></b> (<i>self</i>)</li><li><div class="fn" />QStringList <b><a href="qscriptengine.html#importedExtensions">importedExtensions</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#importExtension">importExtension</a></b> (<i>self</i>, QString)</li><li><div class="fn" /><b><a href="qscriptengine.html#installTranslatorFunctions">installTranslatorFunctions</a></b> (<i>self</i>, QScriptValue <i>object</i> = QScriptValue())</li><li><div class="fn" />bool <b><a href="qscriptengine.html#isEvaluating">isEvaluating</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newArray">newArray</a></b> (<i>self</i>, int <i>length</i> = 0)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newDate">newDate</a></b> (<i>self</i>, float)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newDate-2">newDate</a></b> (<i>self</i>, QDateTime)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newFunction">newFunction</a></b> (<i>self</i>, callable, int <i>length</i> = 0)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newFunction-2">newFunction</a></b> (<i>self</i>, callable, QScriptValue, int <i>length</i> = 0)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newObject">newObject</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newObject-2">newObject</a></b> (<i>self</i>, QScriptClass, QScriptValue <i>data</i> = QScriptValue())</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newQMetaObject">newQMetaObject</a></b> (<i>self</i>, QMetaObject, QScriptValue <i>ctor</i> = QScriptValue())</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newQObject">newQObject</a></b> (<i>self</i>, QObject, ValueOwnership <i>ownership</i> = QScriptEngine.QtOwnership, QObjectWrapOptions <i>options</i> = 0)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newQObject-2">newQObject</a></b> (<i>self</i>, QScriptValue, QObject, ValueOwnership <i>ownership</i> = QScriptEngine.QtOwnership, QObjectWrapOptions <i>options</i> = 0)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newRegExp">newRegExp</a></b> (<i>self</i>, QRegExp)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newRegExp-2">newRegExp</a></b> (<i>self</i>, QString, QString)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newVariant">newVariant</a></b> (<i>self</i>, QVariant)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#newVariant-2">newVariant</a></b> (<i>self</i>, QScriptValue, QVariant)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#nullValue">nullValue</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qscriptengine.html#popContext">popContext</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qscriptengine.html#processEventsInterval">processEventsInterval</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptContext <b><a href="qscriptengine.html#pushContext">pushContext</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qscriptengine.html#reportAdditionalMemoryCost">reportAdditionalMemoryCost</a></b> (<i>self</i>, int <i>size</i>)</li><li><div class="fn" /><b><a href="qscriptengine.html#setAgent">setAgent</a></b> (<i>self</i>, QScriptEngineAgent)</li><li><div class="fn" /><b><a href="qscriptengine.html#setDefaultPrototype">setDefaultPrototype</a></b> (<i>self</i>, int, QScriptValue)</li><li><div class="fn" /><b><a href="qscriptengine.html#setGlobalObject">setGlobalObject</a></b> (<i>self</i>, QScriptValue)</li><li><div class="fn" /><b><a href="qscriptengine.html#setProcessEventsInterval">setProcessEventsInterval</a></b> (<i>self</i>, int)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#toObject">toObject</a></b> (<i>self</i>, QScriptValue)</li><li><div class="fn" />QScriptString <b><a href="qscriptengine.html#toStringHandle">toStringHandle</a></b> (<i>self</i>, QString)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#uncaughtException">uncaughtException</a></b> (<i>self</i>)</li><li><div class="fn" />QStringList <b><a href="qscriptengine.html#uncaughtExceptionBacktrace">uncaughtExceptionBacktrace</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qscriptengine.html#uncaughtExceptionLineNumber">uncaughtExceptionLineNumber</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptengine.html#undefinedValue">undefinedValue</a></b> (<i>self</i>)</li></ul><h3>Static Methods</h3><ul><li><div class="fn" />QScriptSyntaxCheckResult <b><a href="qscriptengine.html#checkSyntax">checkSyntax</a></b> (QString)</li></ul><h3>Qt Signals</h3><ul><li><div class="fn" />void <b><a href="qscriptengine.html#signalHandlerException">signalHandlerException</a></b> (const QScriptValue&)</li></ul><a name="details" /><hr /><h2>Detailed Description</h2><p>The QScriptEngine class provides an environment for evaluating
14
<p>See the <a href="qtscript.html">QtScript</a> documentation for
15
information about the Qt Script language, and how to get started
16
with scripting your C++ application.</p>
17
<a id="evaluating-scripts" name="evaluating-scripts" />
13
18
<h3>Evaluating Scripts</h3>
14
<p>Use <a href="qscriptengine.html#evaluate">evaluate</a>() to evaluate script code; this is the C++ equivalent of the built-in script function <tt>eval()</tt>.</p>
15
<pre> QScriptEngine myEngine;
16
QScriptValue three = myEngine.evaluate("1 + 2");</pre>
17
<p><a href="qscriptengine.html#evaluate">evaluate</a>() returns a <a href="qscriptvalue.html">QScriptValue</a> that holds the result of the evaluation. The <a href="qscriptvalue.html">QScriptValue</a> class provides functions for converting the result to various C++ types (e.g. <a href="qscriptvalue.html#toString">QScriptValue.toString</a>() and <a href="qscriptvalue.html#toNumber">QScriptValue.toNumber</a>()).</p>
18
<p>The following code snippet shows how a script function can be defined and then invoked from C++ using <a href="qscriptvalue.html#call">QScriptValue.call</a>():</p>
19
<pre> QScriptValue fun = myEngine.evaluate("(function(a, b) { return a + b; })");
19
<p>Use <a href="qscriptengine.html#evaluate">evaluate</a>() to
20
evaluate script code; this is the C++ equivalent of the built-in
21
script function <tt>eval()</tt>.</p>
22
<pre class="highlightedCode brush: cpp">
23
QScriptEngine myEngine;
24
QScriptValue three = myEngine.evaluate("1 + 2");
26
<p><a href="qscriptengine.html#evaluate">evaluate</a>() returns a
27
<a href="qscriptvalue.html">QScriptValue</a> that holds the result
28
of the evaluation. The <a href="qscriptvalue.html">QScriptValue</a>
29
class provides functions for converting the result to various C++
30
types (e.g. <a href="qscriptvalue.html#toString">QScriptValue.toString</a>() and
31
<a href="qscriptvalue.html#toNumber">QScriptValue.toNumber</a>()).</p>
32
<p>The following code snippet shows how a script function can be
33
defined and then invoked from C++ using <a href="qscriptvalue.html#call">QScriptValue.call</a>():</p>
34
<pre class="highlightedCode brush: cpp">
35
QScriptValue fun = myEngine.evaluate("(function(a, b) { return a + b; })");
20
36
QScriptValueList args;
21
37
args << 1 << 2;
22
QScriptValue threeAgain = fun.call(QScriptValue(), args);</pre>
23
<p>As can be seen from the above snippets, a script is provided to the engine in the form of a string. One common way of loading scripts is by reading the contents of a file and passing it to <a href="qscriptengine.html#evaluate">evaluate</a>():</p>
24
<pre> QString fileName = "helloworld.qs";
38
QScriptValue threeAgain = fun.call(QScriptValue(), args);
40
<p>As can be seen from the above snippets, a script is provided to
41
the engine in the form of a string. One common way of loading
42
scripts is by reading the contents of a file and passing it to
43
<a href="qscriptengine.html#evaluate">evaluate</a>():</p>
44
<pre class="highlightedCode brush: cpp">
45
QString fileName = "helloworld.qs";
25
46
QFile scriptFile(fileName);
26
47
if (!scriptFile.open(QIODevice.ReadOnly))
27
48
<span class="comment">// handle error</span>
28
49
QTextStream stream(&scriptFile);
29
50
QString contents = stream.readAll();
30
51
scriptFile.close();
31
myEngine.evaluate(contents, fileName);</pre>
32
<p>Here we pass the name of the file as the second argument to <a href="qscriptengine.html#evaluate">evaluate</a>(). This does not affect evaluation in any way; the second argument is a general-purpose string that is used to identify the script for debugging purposes (for example, our filename will now show up in any <a href="qscriptengine.html#uncaughtExceptionBacktrace">uncaughtExceptionBacktrace</a>() involving the script).</p>
33
<a name="engine-configuration" />
52
myEngine.evaluate(contents, fileName);
54
<p>Here we pass the name of the file as the second argument to
55
<a href="qscriptengine.html#evaluate">evaluate</a>(). This does not
56
affect evaluation in any way; the second argument is a
57
general-purpose string that is used to identify the script for
58
debugging purposes (for example, our filename will now show up in
59
any <a href="qscriptengine.html#uncaughtExceptionBacktrace">uncaughtExceptionBacktrace</a>()
60
involving the script).</p>
61
<a id="engine-configuration" name="engine-configuration" />
34
62
<h3>Engine Configuration</h3>
35
<p>The <a href="qscriptengine.html#globalObject">globalObject</a>() function returns the <b>Global Object</b> associated with the script engine. Properties of the Global Object are accessible from any script code (i.e. they are global variables). Typically, before evaluating "user" scripts, you will want to configure a script engine by adding one or more properties to the Global Object:</p>
36
<pre> myEngine.globalObject().setProperty("myNumber", 123);
63
<p>The <a href="qscriptengine.html#globalObject">globalObject</a>()
64
function returns the <b>Global Object</b> associated with the
65
script engine. Properties of the Global Object are accessible from
66
any script code (i.e. they are global variables). Typically, before
67
evaluating "user" scripts, you will want to configure a script
68
engine by adding one or more properties to the Global Object:</p>
69
<pre class="highlightedCode brush: cpp">
70
myEngine.globalObject().setProperty("myNumber", 123);
38
QScriptValue myNumberPlusOne = myEngine.evaluate("myNumber + 1");</pre>
39
<p>Adding custom properties to the scripting environment is one of the standard means of providing a scripting API that is specific to your application. Usually these custom properties are objects created by the <a href="qscriptengine.html#newQObject">newQObject</a>() or <a href="qscriptengine.html#newObject">newObject</a>() functions, or constructor functions created by <a href="qscriptengine.html#newFunction">newFunction</a>().</p>
40
<a name="script-exceptions" />
72
QScriptValue myNumberPlusOne = myEngine.evaluate("myNumber + 1");
74
<p>Adding custom properties to the scripting environment is one of
75
the standard means of providing a scripting API that is specific to
76
your application. Usually these custom properties are objects
77
created by the <a href="qscriptengine.html#newQObject">newQObject</a>() or <a href="qscriptengine.html#newObject">newObject</a>() functions, or
78
constructor functions created by <a href="qscriptengine.html#newFunction">newFunction</a>().</p>
79
<a id="script-exceptions" name="script-exceptions" />
41
80
<h3>Script Exceptions</h3>
42
<p><a href="qscriptengine.html#evaluate">evaluate</a>() can throw a script exception (e.g. due to a syntax error); in that case, the return value is the value that was thrown (typically an <tt>Error</tt> object). You can check whether the evaluation caused an exception by calling <a href="qscriptengine.html#hasUncaughtException">hasUncaughtException</a>(). In that case, you can call toString() on the error object to obtain an error message. The current uncaught exception is also available through <a href="qscriptengine.html#uncaughtException">uncaughtException</a>(). You can obtain a human-readable backtrace of the exception with <a href="qscriptengine.html#uncaughtExceptionBacktrace">uncaughtExceptionBacktrace</a>(). Calling <a href="qscriptengine.html#clearExceptions">clearExceptions</a>() will cause any uncaught exceptions to be cleared.</p>
43
<pre> QScriptValue result = myEngine.evaluate(...);
81
<p><a href="qscriptengine.html#evaluate">evaluate</a>() can throw a
82
script exception (e.g. due to a syntax error); in that case, the
83
return value is the value that was thrown (typically an
84
<tt>Error</tt> object). You can check whether the evaluation caused
85
an exception by calling <a href="qscriptengine.html#hasUncaughtException">hasUncaughtException</a>().
86
In that case, you can call toString() on the error object to obtain
87
an error message. The current uncaught exception is also available
88
through <a href="qscriptengine.html#uncaughtException">uncaughtException</a>(). You
89
can obtain a human-readable backtrace of the exception with
90
<a href="qscriptengine.html#uncaughtExceptionBacktrace">uncaughtExceptionBacktrace</a>().
91
Calling <a href="qscriptengine.html#clearExceptions">clearExceptions</a>() will
92
cause any uncaught exceptions to be cleared.</p>
93
<pre class="highlightedCode brush: cpp">
94
QScriptValue result = myEngine.evaluate(...);
44
95
if (myEngine.hasUncaughtException()) {
45
96
int line = myEngine.uncaughtExceptionLineNumber();
46
97
qDebug() << "uncaught exception at line" << line << ":" << result.toString();
48
<p>The <a href="qscriptengine.html#checkSyntax">checkSyntax</a>() function can be used to determine whether code can be usefully passed to <a href="qscriptengine.html#evaluate">evaluate</a>().</p>
49
<a name="script-object-creation" />
100
<p>The <a href="qscriptengine.html#checkSyntax">checkSyntax</a>()
101
function can be used to determine whether code can be usefully
102
passed to <a href="qscriptengine.html#evaluate">evaluate</a>().</p>
103
<a id="script-object-creation" name="script-object-creation" />
50
104
<h3>Script Object Creation</h3>
51
<p>Use <a href="qscriptengine.html#newObject">newObject</a>() to create a standard Qt Script object; this is the C++ equivalent of the script statement <tt>new Object()</tt>. You can use the object-specific functionality in <a href="qscriptvalue.html">QScriptValue</a> to manipulate the script object (e.g. <a href="qscriptvalue.html#setProperty">QScriptValue.setProperty</a>()). Similarly, use <a href="qscriptengine.html#newArray">newArray</a>() to create a Qt Script array object. Use <a href="qscriptengine.html#newDate">newDate</a>() to create a <tt>Date</tt> object, and <a href="qscriptengine.html#newRegExp">newRegExp</a>() to create a <tt>RegExp</tt> object.</p>
52
<a name="qobject-integration" />
105
<p>Use <a href="qscriptengine.html#newObject">newObject</a>() to
106
create a standard Qt Script object; this is the C++ equivalent of
107
the script statement <tt>new Object()</tt>. You can use the
108
object-specific functionality in <a href="qscriptvalue.html">QScriptValue</a> to manipulate the script
109
object (e.g. <a href="qscriptvalue.html#setProperty">QScriptValue.setProperty</a>()).
110
Similarly, use <a href="qscriptengine.html#newArray">newArray</a>()
111
to create a Qt Script array object. Use <a href="qscriptengine.html#newDate">newDate</a>() to create a
112
<tt>Date</tt> object, and <a href="qscriptengine.html#newRegExp">newRegExp</a>() to create a
113
<tt>RegExp</tt> object.</p>
114
<a id="qobject-integration" name="qobject-integration" />
53
115
<h3>QObject Integration</h3>
54
<p>Use <a href="qscriptengine.html#newQObject">newQObject</a>() to wrap a <a href="qobject.html">QObject</a> (or subclass) pointer. <a href="qscriptengine.html#newQObject">newQObject</a>() returns a proxy script object; properties, children, and signals and slots of the <a href="qobject.html">QObject</a> are available as properties of the proxy object. No binding code is needed because it is done dynamically using the Qt meta object system.</p>
55
<pre> QPushButton button;
116
<p>Use <a href="qscriptengine.html#newQObject">newQObject</a>() to
117
wrap a <a href="qobject.html">QObject</a> (or subclass) pointer.
118
<a href="qscriptengine.html#newQObject">newQObject</a>() returns a
119
proxy script object; properties, children, and signals and slots of
120
the <a href="qobject.html">QObject</a> are available as properties
121
of the proxy object. No binding code is needed because it is done
122
dynamically using the Qt meta object system.</p>
123
<pre class="highlightedCode brush: cpp">
56
125
QScriptValue scriptButton = myEngine.newQObject(&button);
57
126
myEngine.globalObject().setProperty("button", scriptButton);
59
128
myEngine.evaluate("button.checkable = true");
61
130
qDebug() << scriptButton.property("checkable").toBoolean();
62
scriptButton.property("show").call(); <span class="comment">// call the show() slot</span></pre>
63
<p>Use <a href="qscriptengine.html#qScriptConnect">qScriptConnect</a>() to connect a C++ signal to a script function; this is the Qt Script equivalent of <a href="qobject.html#connect">QObject.connect</a>(). When a script function is invoked in response to a C++ signal, it can cause a script exception; you can connect to the <a href="qscriptengine.html#signalHandlerException">signalHandlerException</a>() signal to catch such an exception.</p>
64
<p>Use <a href="qscriptengine.html#newQMetaObject">newQMetaObject</a>() to wrap a <a href="qmetaobject.html">QMetaObject</a>; this gives you a "script representation" of a <a href="qobject.html">QObject</a>-based class. <a href="qscriptengine.html#newQMetaObject">newQMetaObject</a>() returns a proxy script object; enum values of the class are available as properties of the proxy object. You can also specify a function that will be used to construct objects of the class (e.g. when the constructor is invoked from a script). For classes that have a "standard" Qt constructor, Qt Script can provide a default script constructor for you; see <a href="qscriptengine.html#scriptValueFromQMetaObject">scriptValueFromQMetaObject</a>().</p>
65
<p>See the <a href="qtscript.html">QtScript</a> documentation for more information on the <a href="qobject.html">QObject</a> integration.</p>
66
<a name="support-for-custom-c-types" />
131
scriptButton.property("show").call(); <span class="comment">// call the show() slot</span>
133
<p>Use <a href="qscriptengine.html#qScriptConnect">qScriptConnect</a>() to connect
134
a C++ signal to a script function; this is the Qt Script equivalent
135
of <a href="qobject.html#connect">QObject.connect</a>(). When a
136
script function is invoked in response to a C++ signal, it can
137
cause a script exception; you can connect to the <a href="qscriptengine.html#signalHandlerException">signalHandlerException</a>()
138
signal to catch such an exception.</p>
139
<p>Use <a href="qscriptengine.html#newQMetaObject">newQMetaObject</a>() to wrap a
140
<a href="qmetaobject.html">QMetaObject</a>; this gives you a
141
"script representation" of a <a href="qobject.html">QObject</a>-based class. <a href="qscriptengine.html#newQMetaObject">newQMetaObject</a>() returns a
142
proxy script object; enum values of the class are available as
143
properties of the proxy object. You can also specify a function
144
that will be used to construct objects of the class (e.g. when the
145
constructor is invoked from a script). For classes that have a
146
"standard" Qt constructor, Qt Script can provide a default script
147
constructor for you; see <a href="qscriptengine.html#scriptValueFromQMetaObject">scriptValueFromQMetaObject</a>().</p>
148
<p>See the <a href="qtscript.html">QtScript</a> documentation for
149
more information on the <a href="qobject.html">QObject</a>
151
<a id="support-for-custom-c-types" name="support-for-custom-c-types" />
67
152
<h3>Support for Custom C++ Types</h3>
68
<p>Use <a href="qscriptengine.html#newVariant">newVariant</a>() to wrap a <a href="qvariant.html">QVariant</a>. This can be used to store values of custom (non-<a href="qobject.html">QObject</a>) C++ types that have been registered with the Qt meta-type system. To make such types scriptable, you typically associate a prototype (delegate) object with the C++ type by calling <a href="qscriptengine.html#setDefaultPrototype">setDefaultPrototype</a>(); the prototype object defines the scripting API for the C++ type. Unlike the <a href="qobject.html">QObject</a> integration, there is no automatic binding possible here; i.e. you have to create the scripting API yourself, for example by using the <a href="qscriptable.html">QScriptable</a> class.</p>
69
<p>Use <a href="qscriptengine.html#fromScriptValue">fromScriptValue</a>() to cast from a <a href="qscriptvalue.html">QScriptValue</a> to another type, and <a href="qscriptengine.html#toScriptValue">toScriptValue</a>() to create a <a href="qscriptvalue.html">QScriptValue</a> from another value. You can specify how the conversion of C++ types is to be performed with <a href="qscriptengine.html#qScriptRegisterMetaType">qScriptRegisterMetaType</a>() and <a href="qscriptengine.html#qScriptRegisterSequenceMetaType">qScriptRegisterSequenceMetaType</a>(). By default, Qt Script will use <a href="qvariant.html">QVariant</a> to store values of custom types.</p>
70
<a name="importing-extensions" />
153
<p>Use <a href="qscriptengine.html#newVariant">newVariant</a>() to
154
wrap a <a href="qvariant.html">QVariant</a>. This can be used to
155
store values of custom (non-<a href="qobject.html">QObject</a>) C++
156
types that have been registered with the Qt meta-type system. To
157
make such types scriptable, you typically associate a prototype
158
(delegate) object with the C++ type by calling <a href="qscriptengine.html#setDefaultPrototype">setDefaultPrototype</a>();
159
the prototype object defines the scripting API for the C++ type.
160
Unlike the <a href="qobject.html">QObject</a> integration, there is
161
no automatic binding possible here; i.e. you have to create the
162
scripting API yourself, for example by using the <a href="qscriptable.html">QScriptable</a> class.</p>
163
<p>Use <a href="qscriptengine.html#fromScriptValue">fromScriptValue</a>() to cast
164
from a <a href="qscriptvalue.html">QScriptValue</a> to another
165
type, and <a href="qscriptengine.html#toScriptValue">toScriptValue</a>() to create a
166
<a href="qscriptvalue.html">QScriptValue</a> from another value.
167
You can specify how the conversion of C++ types is to be performed
168
with <a href="qscriptengine.html#qScriptRegisterMetaType">qScriptRegisterMetaType</a>()
169
and <a href="qscriptengine.html#qScriptRegisterSequenceMetaType">qScriptRegisterSequenceMetaType</a>().
170
By default, Qt Script will use <a href="qvariant.html">QVariant</a>
171
to store values of custom types.</p>
172
<a id="importing-extensions" name="importing-extensions" />
71
173
<h3>Importing Extensions</h3>
72
<p>Use <a href="qscriptengine.html#importExtension">importExtension</a>() to import plugin-based extensions into the engine. Call <a href="qscriptengine.html#availableExtensions">availableExtensions</a>() to obtain a list naming all the available extensions, and <a href="qscriptengine.html#importedExtensions">importedExtensions</a>() to obtain a list naming only those extensions that have been imported.</p>
73
<p>Call <a href="qscriptengine.html#pushContext">pushContext</a>() to open up a new variable scope, and <a href="qscriptengine.html#popContext">popContext</a>() to close the current scope. This is useful if you are implementing an extension that evaluates script code containing temporary variable definitions (e.g. <tt>var foo = 123;</tt>) that are safe to discard when evaluation has completed.</p>
74
<a name="native-functions" />
174
<p>Use <a href="qscriptengine.html#importExtension">importExtension</a>() to
175
import plugin-based extensions into the engine. Call <a href="qscriptengine.html#availableExtensions">availableExtensions</a>()
176
to obtain a list naming all the available extensions, and <a href="qscriptengine.html#importedExtensions">importedExtensions</a>() to
177
obtain a list naming only those extensions that have been
179
<p>Call <a href="qscriptengine.html#pushContext">pushContext</a>()
180
to open up a new variable scope, and <a href="qscriptengine.html#popContext">popContext</a>() to close the
181
current scope. This is useful if you are implementing an extension
182
that evaluates script code containing temporary variable
183
definitions (e.g. <tt>var foo = 123;</tt>) that are safe to discard
184
when evaluation has completed.</p>
185
<a id="native-functions" name="native-functions" />
75
186
<h3>Native Functions</h3>
76
<p>Use <a href="qscriptengine.html#newFunction">newFunction</a>() to wrap native (C++) functions, including constructors for your own custom types, so that these can be invoked from script code. Such functions must have the signature <a href="qscriptengine.html#FunctionSignature-typedef">QScriptEngine.FunctionSignature</a>. You may then pass the function as argument to <a href="qscriptengine.html#newFunction">newFunction</a>(). Here is an example of a function that returns the sum of its first two arguments:</p>
77
<pre> QScriptValue myAdd(QScriptContext *context, QScriptEngine *engine)
187
<p>Use <a href="qscriptengine.html#newFunction">newFunction</a>()
188
to wrap native (C++) functions, including constructors for your own
189
custom types, so that these can be invoked from script code. Such
190
functions must have the signature <a href="qscriptengine.html#FunctionSignature-typedef">QScriptEngine.FunctionSignature</a>.
191
You may then pass the function as argument to <a href="qscriptengine.html#newFunction">newFunction</a>(). Here is an
192
example of a function that returns the sum of its first two
194
<pre class="highlightedCode brush: cpp">
195
QScriptValue myAdd(QScriptContext *context, QScriptEngine *engine)
79
197
QScriptValue a = context->argument(0);
80
198
QScriptValue b = context->argument(1);
81
199
return a.toNumber() + b.toNumber();
83
<p>To expose this function to script code, you can set it as a property of the Global Object:</p>
84
<pre> QScriptValue fun = myEngine.newFunction(myAdd);
85
myEngine.globalObject().setProperty("myAdd", fun);</pre>
86
<p>Once this is done, script code can call your function in the exact same manner as a "normal" script function:</p>
87
<pre> QScriptValue result = myEngine.evaluate("myAdd(myNumber, 1)");</pre>
88
<a name="long-running-scripts" />
202
<p>To expose this function to script code, you can set it as a
203
property of the Global Object:</p>
204
<pre class="highlightedCode brush: cpp">
205
QScriptValue fun = myEngine.newFunction(myAdd);
206
myEngine.globalObject().setProperty("myAdd", fun);
208
<p>Once this is done, script code can call your function in the
209
exact same manner as a "normal" script function:</p>
210
<pre class="highlightedCode brush: cpp">
211
QScriptValue result = myEngine.evaluate("myAdd(myNumber, 1)");
213
<a id="long-running-scripts" name="long-running-scripts" />
89
214
<h3>Long-running Scripts</h3>
90
<p>If you need to evaluate possibly long-running scripts from the main (GUI) thread, you should first call <a href="qscriptengine.html#setProcessEventsInterval">setProcessEventsInterval</a>() to make sure that the GUI stays responsive. You can abort a currently running script by calling <a href="qscriptengine.html#abortEvaluation">abortEvaluation</a>(). You can determine whether an engine is currently running a script by calling <a href="qscriptengine.html#isEvaluating">isEvaluating</a>().</p>
91
<a name="core-debugging-tracing-facilities" />
215
<p>If you need to evaluate possibly long-running scripts from the
216
main (GUI) thread, you should first call <a href="qscriptengine.html#setProcessEventsInterval">setProcessEventsInterval</a>()
217
to make sure that the GUI stays responsive. You can abort a
218
currently running script by calling <a href="qscriptengine.html#abortEvaluation">abortEvaluation</a>(). You can
219
determine whether an engine is currently running a script by
220
calling <a href="qscriptengine.html#isEvaluating">isEvaluating</a>().</p>
221
<a id="garbage-collection" name="garbage-collection" />
222
<h3>Garbage Collection</h3>
223
<p>Qt Script objects may be garbage collected when they are no
224
longer referenced. There is no guarantee as to when automatic
225
garbage collection will take place.</p>
226
<p>The <a href="qscriptengine.html#collectGarbage">collectGarbage</a>() function
227
can be called to explicitly request garbage collection.</p>
228
<p>The <a href="qscriptengine.html#reportAdditionalMemoryCost">reportAdditionalMemoryCost</a>()
229
function can be called to indicate that a Qt Script object occupies
230
memory that isn't managed by the scripting environment. Reporting
231
the additional cost makes it more likely that the garbage collector
232
will be triggered. This can be useful, for example, when many
233
custom, native Qt Script objects are allocated.</p>
234
<a id="core-debugging-tracing-facilities" name="core-debugging-tracing-facilities" />
92
235
<h3>Core Debugging/Tracing Facilities</h3>
93
<p>Since Qt 4.4, you can be notified of events pertaining to script execution (e.g. script function calls and statement execution) through the <a href="qscriptengineagent.html">QScriptEngineAgent</a> interface; see the <a href="qscriptengine.html#setAgent">setAgent</a>() function. This can be used to implement debugging and profiling of a QScriptEngine.</p>
94
<p>See also <a href="qscriptvalue.html">QScriptValue</a>, <a href="qscriptcontext.html">QScriptContext</a>, and <a href="qscriptengineagent.html">QScriptEngineAgent</a>.</p>
236
<p>Since Qt 4.4, you can be notified of events pertaining to script
237
execution (e.g. script function calls and statement execution)
238
through the <a href="qscriptengineagent.html">QScriptEngineAgent</a> interface; see the
239
<a href="qscriptengine.html#setAgent">setAgent</a>() function. This
240
can be used to implement debugging and profiling of a
95
242
<hr /><h2>Type Documentation</h2><h3 class="fn"><a name="QObjectWrapOption-enum" />QScriptEngine.QObjectWrapOption</h3><p>These flags specify options when wrapping a <a href="qobject.html">QObject</a> pointer with <a href="qscriptengine.html#newQObject">newQObject</a>().</p>
96
<p><table border="1" cellpadding="2" cellspacing="1" class="valuelist" width="100%">
97
<tr><th width="25%">Constant</th><th width="15%">Value</th><th width="60%">Description</th></tr>
98
<tr><td valign="top"><tt>QScriptEngine.ExcludeChildObjects</tt></td><td align="center" valign="top"><tt>0x0001</tt></td><td valign="top">The script object will not expose child objects as properties.</td></tr>
99
<tr><td valign="top"><tt>QScriptEngine.ExcludeSuperClassMethods</tt></td><td align="center" valign="top"><tt>0x0002</tt></td><td valign="top">The script object will not expose signals and slots inherited from the superclass.</td></tr>
100
<tr><td valign="top"><tt>QScriptEngine.ExcludeSuperClassProperties</tt></td><td align="center" valign="top"><tt>0x0004</tt></td><td valign="top">The script object will not expose properties inherited from the superclass.</td></tr>
101
<tr><td valign="top"><tt>QScriptEngine.ExcludeSuperClassContents</tt></td><td align="center" valign="top"><tt>0x0006</tt></td><td valign="top">Shorthand form for ExcludeSuperClassMethods | ExcludeSuperClassProperties</td></tr>
102
<tr><td valign="top"><tt>QScriptEngine.ExcludeDeleteLater</tt></td><td align="center" valign="top"><tt>0x0010</tt></td><td valign="top">The script object will not expose the <a href="qobject.html#deleteLater">QObject.deleteLater</a>() slot.</td></tr>
103
<tr><td valign="top"><tt>QScriptEngine.AutoCreateDynamicProperties</tt></td><td align="center" valign="top"><tt>0x0100</tt></td><td valign="top">Properties that don't already exist in the <a href="qobject.html">QObject</a> will be created as dynamic properties of that object, rather than as properties of the script object.</td></tr>
104
<tr><td valign="top"><tt>QScriptEngine.PreferExistingWrapperObject</tt></td><td align="center" valign="top"><tt>0x0200</tt></td><td valign="top">If a wrapper object with the requested configuration already exists, return that object.</td></tr>
105
<tr><td valign="top"><tt>QScriptEngine.SkipMethodsInEnumeration</tt></td><td align="center" valign="top"><tt>0x0008</tt></td><td valign="top">Don't include methods (signals and slots) when enumerating the object's properties.</td></tr>
107
<p>The QObjectWrapOptions type is a typedef for <a href="qflags.html">QFlags</a><QObjectWrapOption>. It stores an OR combination of QObjectWrapOption values.</p>
108
<a name="//apple_ref/cpp/tag/QScriptEngine/ValueOwnership" />
109
<a name="//apple_ref/cpp/econst/QScriptEngine/QtOwnership" />
110
<a name="//apple_ref/cpp/econst/QScriptEngine/ScriptOwnership" />
111
<a name="//apple_ref/cpp/econst/QScriptEngine/AutoOwnership" />
112
<h3 class="fn"><a name="ValueOwnership-enum" />QScriptEngine.ValueOwnership</h3><p>This enum specifies the ownership when wrapping a C++ value, e.g. by using <a href="qscriptengine.html#newQObject">newQObject</a>().</p>
113
<p><table border="1" cellpadding="2" cellspacing="1" class="valuelist" width="100%">
114
<tr><th width="25%">Constant</th><th width="15%">Value</th><th width="60%">Description</th></tr>
115
<tr><td valign="top"><tt>QScriptEngine.QtOwnership</tt></td><td align="center" valign="top"><tt>0</tt></td><td valign="top">The standard Qt ownership rules apply, i.e. the associated object will never be explicitly deleted by the script engine. This is the default. (<a href="qobject.html">QObject</a> ownership is explained in <a href="objecttrees.html">Object Trees and Object Ownership</a>.)</td></tr>
116
<tr><td valign="top"><tt>QScriptEngine.ScriptOwnership</tt></td><td align="center" valign="top"><tt>1</tt></td><td valign="top">The value is owned by the script environment. The associated data will be deleted when appropriate (i.e. after the garbage collector has discovered that there are no more live references to the value).</td></tr>
117
<tr><td valign="top"><tt>QScriptEngine.AutoOwnership</tt></td><td align="center" valign="top"><tt>2</tt></td><td valign="top">If the associated object has a parent, the Qt ownership rules apply (QtOwnership); otherwise, the object is owned by the script environment (ScriptOwnership).</td></tr>
119
<hr /><h2>Method Documentation</h2><h3 class="fn"><a name="QScriptEngine" />QScriptEngine.__init__ (<i>self</i>)</h3><p>Constructs a <a href="qscriptengine.html">QScriptEngine</a> object.</p>
120
<p>The <a href="qscriptengine.html#globalObject">globalObject</a>() is initialized to have properties as described in <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">ECMA-262</a>, Section 15.1.</p>
121
<h3 class="fn"><a name="QScriptEngine-2" />QScriptEngine.__init__ (<i>self</i>, <a href="qobject.html">QObject</a>)</h3><p>The <i>QObject</i> argument, if not None, causes <i>self</i> to be owned by Qt instead of PyQt.</p><p>Constructs a <a href="qscriptengine.html">QScriptEngine</a> object with the given <i>parent</i>.</p>
122
<p>The <a href="qscriptengine.html#globalObject">globalObject</a>() is initialized to have properties as described in <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">ECMA-262</a>, Section 15.1.</p>
123
<a name="//apple_ref/cpp/instm/QScriptEngine/~QScriptEngine" />
124
<h3 class="fn"><a name="abortEvaluation" />QScriptEngine.abortEvaluation (<i>self</i>, <a href="qscriptvalue.html">QScriptValue</a> <i>result</i> = QScriptValue())</h3><p>Aborts any script evaluation currently taking place in this engine. The given <i>result</i> is passed back as the result of the evaluation (i.e. it is returned from the call to <a href="qscriptengine.html#evaluate">evaluate</a>() being aborted).</p>
125
<p>If the engine isn't evaluating a script (i.e. <a href="qscriptengine.html#isEvaluating">isEvaluating</a>() returns false), this function does nothing.</p>
126
<p>Call this function if you need to abort a running script for some reason, e.g. when you have detected that the script has been running for several seconds without completing.</p>
243
<table class="valuelist">
248
<th class="tblConst">Constant</th>
249
<th class="tblval">Value</th>
250
<th class="tbldscr">Description</th>
253
<td class="topAlign">
254
<tt>QScriptEngine.ExcludeChildObjects</tt></td>
255
<td class=" topAlign"><tt>0x0001</tt></td>
256
<td class="topAlign">The script object will not expose child
257
objects as properties.</td>
260
<td class="topAlign">
261
<tt>QScriptEngine.ExcludeSuperClassMethods</tt></td>
262
<td class=" topAlign"><tt>0x0002</tt></td>
263
<td class="topAlign">The script object will not expose signals and
264
slots inherited from the superclass.</td>
267
<td class="topAlign">
268
<tt>QScriptEngine.ExcludeSuperClassProperties</tt></td>
269
<td class=" topAlign"><tt>0x0004</tt></td>
270
<td class="topAlign">The script object will not expose properties
271
inherited from the superclass.</td>
274
<td class="topAlign">
275
<tt>QScriptEngine.ExcludeSuperClassContents</tt></td>
276
<td class=" topAlign"><tt>0x0006</tt></td>
277
<td class="topAlign">Shorthand form for ExcludeSuperClassMethods |
278
ExcludeSuperClassProperties</td>
281
<td class="topAlign">
282
<tt>QScriptEngine.ExcludeDeleteLater</tt></td>
283
<td class=" topAlign"><tt>0x0010</tt></td>
284
<td class="topAlign">The script object will not expose the <a href="qobject.html#deleteLater">QObject.deleteLater</a>() slot.</td>
287
<td class="topAlign"><tt>QScriptEngine.ExcludeSlots</tt></td>
288
<td class=" topAlign"><tt>0x0020</tt></td>
289
<td class="topAlign">The script object will not expose the <a href="qobject.html">QObject</a>'s slots.</td>
292
<td class="topAlign">
293
<tt>QScriptEngine.AutoCreateDynamicProperties</tt></td>
294
<td class=" topAlign"><tt>0x0100</tt></td>
295
<td class="topAlign">Properties that don't already exist in the
296
<a href="qobject.html">QObject</a> will be created as dynamic
297
properties of that object, rather than as properties of the script
301
<td class="topAlign">
302
<tt>QScriptEngine.PreferExistingWrapperObject</tt></td>
303
<td class=" topAlign"><tt>0x0200</tt></td>
304
<td class="topAlign">If a wrapper object with the requested
305
configuration already exists, return that object.</td>
308
<td class="topAlign">
309
<tt>QScriptEngine.SkipMethodsInEnumeration</tt></td>
310
<td class=" topAlign"><tt>0x0008</tt></td>
311
<td class="topAlign">Don't include methods (signals and slots) when
312
enumerating the object's properties.</td>
315
<p>The QObjectWrapOptions type is a typedef for <a href="qflags.html">QFlags</a><QObjectWrapOption>. It stores an OR
316
combination of QObjectWrapOption values.</p>
319
<h3 class="fn"><a name="ValueOwnership-enum" />QScriptEngine.ValueOwnership</h3><p>This enum specifies the ownership when wrapping a C++ value,
320
e.g. by using <a href="qscriptengine.html#newQObject">newQObject</a>().</p>
321
<table class="valuelist">
326
<th class="tblConst">Constant</th>
327
<th class="tblval">Value</th>
328
<th class="tbldscr">Description</th>
331
<td class="topAlign"><tt>QScriptEngine.QtOwnership</tt></td>
332
<td class=" topAlign"><tt>0</tt></td>
333
<td class="topAlign">The standard Qt ownership rules apply, i.e.
334
the associated object will never be explicitly deleted by the
335
script engine. This is the default. (<a href="qobject.html">QObject</a> ownership is explained in <a href="objecttrees.html">Object Trees & Ownership</a>.)</td>
338
<td class="topAlign"><tt>QScriptEngine.ScriptOwnership</tt></td>
339
<td class=" topAlign"><tt>1</tt></td>
340
<td class="topAlign">The value is owned by the script environment.
341
The associated data will be deleted when appropriate (i.e. after
342
the garbage collector has discovered that there are no more live
343
references to the value).</td>
346
<td class="topAlign"><tt>QScriptEngine.AutoOwnership</tt></td>
347
<td class=" topAlign"><tt>2</tt></td>
348
<td class="topAlign">If the associated object has a parent, the Qt
349
ownership rules apply (QtOwnership); otherwise, the object is owned
350
by the script environment (ScriptOwnership).</td>
353
<hr /><h2>Method Documentation</h2><h3 class="fn"><a name="QScriptEngine" />QScriptEngine.__init__ (<i>self</i>)</h3><p>Constructs a <a href="qscriptengine.html">QScriptEngine</a>
355
<p>The <a href="qscriptengine.html#globalObject">globalObject</a>()
356
is initialized to have properties as described in <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">
357
ECMA-262</a>, Section 15.1.</p>
360
<h3 class="fn"><a name="QScriptEngine-2" />QScriptEngine.__init__ (<i>self</i>, <a href="qobject.html">QObject</a>)</h3><p>The <i>QObject</i> argument, if not None, causes <i>self</i> to be owned by Qt instead of PyQt.</p><p>Constructs a <a href="qscriptengine.html">QScriptEngine</a>
361
object with the given <i>parent</i>.</p>
362
<p>The <a href="qscriptengine.html#globalObject">globalObject</a>()
363
is initialized to have properties as described in <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">
364
ECMA-262</a>, Section 15.1.</p>
367
<h3 class="fn"><a name="abortEvaluation" />QScriptEngine.abortEvaluation (<i>self</i>, <a href="qscriptvalue.html">QScriptValue</a> <i>result</i> = QScriptValue())</h3><p>Aborts any script evaluation currently taking place in this
368
engine. The given <i>result</i> is passed back as the result of the
369
evaluation (i.e. it is returned from the call to <a href="qscriptengine.html#evaluate">evaluate</a>() being aborted).</p>
370
<p>If the engine isn't evaluating a script (i.e. <a href="qscriptengine.html#isEvaluating">isEvaluating</a>() returns
371
false), this function does nothing.</p>
372
<p>Call this function if you need to abort a running script for
373
some reason, e.g. when you have detected that the script has been
374
running for several seconds without completing.</p>
127
375
<p>This function was introduced in Qt 4.4.</p>
128
<p>See also <a href="qscriptengine.html#evaluate">evaluate</a>(), <a href="qscriptengine.html#isEvaluating">isEvaluating</a>(), and <a href="qscriptengine.html#setProcessEventsInterval">setProcessEventsInterval</a>().</p>
129
<a name="//apple_ref/cpp/instm/QScriptEngine/agent" />
130
<h3 class="fn"><a name="agent" /><a href="qscriptengineagent.html">QScriptEngineAgent</a> QScriptEngine.agent (<i>self</i>)</h3><p>Returns the agent currently installed on this engine, or 0 if no agent is installed.</p>
376
<p>See also <a href="qscriptengine.html#evaluate">evaluate</a>(),
377
<a href="qscriptengine.html#isEvaluating">isEvaluating</a>(), and
378
<a href="qscriptengine.html#setProcessEventsInterval">setProcessEventsInterval</a>().</p>
381
<h3 class="fn"><a name="agent" /><a href="qscriptengineagent.html">QScriptEngineAgent</a> QScriptEngine.agent (<i>self</i>)</h3><p>Returns the agent currently installed on this engine, or 0 if no
382
agent is installed.</p>
131
383
<p>This function was introduced in Qt 4.4.</p>
132
384
<p>See also <a href="qscriptengine.html#setAgent">setAgent</a>().</p>
133
<a name="//apple_ref/cpp/instm/QScriptEngine/availableExtensions" />
134
<h3 class="fn"><a name="availableExtensions" />QStringList QScriptEngine.availableExtensions (<i>self</i>)</h3><p>Returns a list naming the available extensions that can be imported using the <a href="qscriptengine.html#importExtension">importExtension</a>() function. This list includes extensions that have been imported.</p>
387
<h3 class="fn"><a name="availableExtensions" />QStringList QScriptEngine.availableExtensions (<i>self</i>)</h3><p>Returns a list naming the available extensions that can be
388
imported using the <a href="qscriptengine.html#importExtension">importExtension</a>()
389
function. This list includes extensions that have been
135
391
<p>This function was introduced in Qt 4.4.</p>
136
<p>See also <a href="qscriptengine.html#importExtension">importExtension</a>() and <a href="qscriptengine.html#importedExtensions">importedExtensions</a>().</p>
137
<a name="//apple_ref/cpp/clm/QScriptEngine/checkSyntax" />
138
<h3 class="fn"><a name="canEvaluate" />bool QScriptEngine.canEvaluate (<i>self</i>, QString)</h3><h3 class="fn"><a name="checkSyntax" /><a href="qscriptsyntaxcheckresult.html">QScriptSyntaxCheckResult</a> QScriptEngine.checkSyntax (QString)</h3><p>Checks the syntax of the given <i>program</i>. Returns a <a href="qscriptsyntaxcheckresult.html">QScriptSyntaxCheckResult</a> object that contains the result of the check.</p>
392
<p>See also <a href="qscriptengine.html#importExtension">importExtension</a>() and
393
<a href="qscriptengine.html#importedExtensions">importedExtensions</a>().</p>
396
<h3 class="fn"><a name="canEvaluate" />bool QScriptEngine.canEvaluate (<i>self</i>, QString)</h3><h3 class="fn"><a name="checkSyntax" /><a href="qscriptsyntaxcheckresult.html">QScriptSyntaxCheckResult</a> QScriptEngine.checkSyntax (QString)</h3><p>Checks the syntax of the given <i>program</i>. Returns a
397
<a href="qscriptsyntaxcheckresult.html">QScriptSyntaxCheckResult</a>
398
object that contains the result of the check.</p>
139
399
<p>This function was introduced in Qt 4.5.</p>
140
<a name="//apple_ref/cpp/instm/QScriptEngine/clearExceptions" />
141
402
<h3 class="fn"><a name="clearExceptions" />QScriptEngine.clearExceptions (<i>self</i>)</h3><p>Clears any uncaught exceptions in this engine.</p>
142
403
<p>This function was introduced in Qt 4.4.</p>
143
404
<p>See also <a href="qscriptengine.html#hasUncaughtException">hasUncaughtException</a>().</p>
144
<a name="//apple_ref/cpp/instm/QScriptEngine/collectGarbage" />
145
407
<h3 class="fn"><a name="collectGarbage" />QScriptEngine.collectGarbage (<i>self</i>)</h3><p>Runs the garbage collector.</p>
146
<p>The garbage collector will attempt to reclaim memory by locating and disposing of objects that are no longer reachable in the script environment.</p>
147
<p>Normally you don't need to call this function; the garbage collector will automatically be invoked when the <a href="qscriptengine.html">QScriptEngine</a> decides that it's wise to do so (i.e. when a certain number of new objects have been created). However, you can call this function to explicitly request that garbage collection should be performed as soon as possible.</p>
148
<a name="//apple_ref/cpp/instm/QScriptEngine/currentContext" />
408
<p>The garbage collector will attempt to reclaim memory by locating
409
and disposing of objects that are no longer reachable in the script
411
<p>Normally you don't need to call this function; the garbage
412
collector will automatically be invoked when the <a href="qscriptengine.html">QScriptEngine</a> decides that it's wise to do
413
so (i.e. when a certain number of new objects have been created).
414
However, you can call this function to explicitly request that
415
garbage collection should be performed as soon as possible.</p>
416
<p>See also <a href="qscriptengine.html#reportAdditionalMemoryCost">reportAdditionalMemoryCost</a>().</p>
149
419
<h3 class="fn"><a name="currentContext" /><a href="qscriptcontext.html">QScriptContext</a> QScriptEngine.currentContext (<i>self</i>)</h3><p>Returns the current context.</p>
150
<p>The current context is typically accessed to retrieve the arguments and `this' object in native functions; for convenience, it is available as the first argument in <a href="qscriptengine.html#FunctionSignature-typedef">QScriptEngine.FunctionSignature</a>.</p>
151
<a name="//apple_ref/cpp/instm/QScriptEngine/defaultPrototype" />
152
<h3 class="fn"><a name="defaultPrototype" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.defaultPrototype (<i>self</i>, int)</h3><p>Returns the default prototype associated with the given <i>metaTypeId</i>, or an invalid <a href="qscriptvalue.html">QScriptValue</a> if no default prototype has been set.</p>
420
<p>The current context is typically accessed to retrieve the
421
arguments and `this' object in native functions; for convenience,
422
it is available as the first argument in <a href="qscriptengine.html#FunctionSignature-typedef">QScriptEngine.FunctionSignature</a>.</p>
425
<h3 class="fn"><a name="defaultPrototype" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.defaultPrototype (<i>self</i>, int)</h3><p>Returns the default prototype associated with the given
426
<i>metaTypeId</i>, or an invalid <a href="qscriptvalue.html">QScriptValue</a> if no default prototype has
153
428
<p>See also <a href="qscriptengine.html#setDefaultPrototype">setDefaultPrototype</a>().</p>
154
<a name="//apple_ref/cpp/instm/QScriptEngine/evaluate" />
155
<h3 class="fn"><a name="evaluate" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.evaluate (<i>self</i>, QString, QString <i>fileName</i> = QString(), int <i>lineNumber</i> = 1)</h3><p>Evaluates <i>program</i>, using <i>lineNumber</i> as the base line number, and returns the result of the evaluation.</p>
431
<h3 class="fn"><a name="evaluate" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.evaluate (<i>self</i>, QString, QString <i>fileName</i> = QString(), int <i>lineNumber</i> = 1)</h3><p>Evaluates <i>program</i>, using <i>lineNumber</i> as the base
432
line number, and returns the result of the evaluation.</p>
156
433
<p>The script code will be evaluated in the current context.</p>
157
<p>The evaluation of <i>program</i> can cause an exception in the engine; in this case the return value will be the exception that was thrown (typically an <tt>Error</tt> object). You can call <a href="qscriptengine.html#hasUncaughtException">hasUncaughtException</a>() to determine if an exception occurred in the last call to evaluate().</p>
158
<p><i>lineNumber</i> is used to specify a starting line number for <i>program</i>; line number information reported by the engine that pertain to this evaluation (e.g. <a href="qscriptengine.html#uncaughtExceptionLineNumber">uncaughtExceptionLineNumber</a>()) will be based on this argument. For example, if <i>program</i> consists of two lines of code, and the statement on the second line causes a script exception, <a href="qscriptengine.html#uncaughtExceptionLineNumber">uncaughtExceptionLineNumber</a>() would return the given <i>lineNumber</i> plus one. When no starting line number is specified, line numbers will be 1-based.</p>
159
<p><i>fileName</i> is used for error reporting. For example in error objects the file name is accessible through the "fileName" property if it's provided with this function.</p>
160
<p>See also <a class="obsolete" href="qscriptengine-obsolete.html#canEvaluate">canEvaluate</a>(), <a href="qscriptengine.html#hasUncaughtException">hasUncaughtException</a>(), <a href="qscriptengine.html#isEvaluating">isEvaluating</a>(), and <a href="qscriptengine.html#abortEvaluation">abortEvaluation</a>().</p>
161
<a name="//apple_ref/cpp/instm/QScriptEngine/fromScriptValue" />
434
<p>The evaluation of <i>program</i> can cause an exception in the
435
engine; in this case the return value will be the exception that
436
was thrown (typically an <tt>Error</tt> object). You can call
437
<a href="qscriptengine.html#hasUncaughtException">hasUncaughtException</a>()
438
to determine if an exception occurred in the last call to
440
<p><i>lineNumber</i> is used to specify a starting line number for
441
<i>program</i>; line number information reported by the engine that
442
pertain to this evaluation (e.g. <a href="qscriptengine.html#uncaughtExceptionLineNumber">uncaughtExceptionLineNumber</a>())
443
will be based on this argument. For example, if <i>program</i>
444
consists of two lines of code, and the statement on the second line
445
causes a script exception, <a href="qscriptengine.html#uncaughtExceptionLineNumber">uncaughtExceptionLineNumber</a>()
446
would return the given <i>lineNumber</i> plus one. When no starting
447
line number is specified, line numbers will be 1-based.</p>
448
<p><i>fileName</i> is used for error reporting. For example in
449
error objects the file name is accessible through the "fileName"
450
property if it's provided with this function.</p>
451
<p>See also <a class="obsolete" href="qscriptengine.html#canEvaluate">canEvaluate</a>(), <a href="qscriptengine.html#hasUncaughtException">hasUncaughtException</a>(),
452
<a href="qscriptengine.html#isEvaluating">isEvaluating</a>(), and
453
<a href="qscriptengine.html#abortEvaluation">abortEvaluation</a>().</p>
162
456
<h3 class="fn"><a name="globalObject" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.globalObject (<i>self</i>)</h3><p>Returns this engine's Global Object.</p>
163
<p>By default, the Global Object contains the built-in objects that are part of <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">ECMA-262</a>, such as Math, Date and String. Additionally, you can set properties of the Global Object to make your own extensions available to all script code. Non-local variables in script code will be created as properties of the Global Object, as well as local variables in global code.</p>
457
<p>By default, the Global Object contains the built-in objects that
458
are part of <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">
459
ECMA-262</a>, such as Math, Date and String. Additionally, you can
460
set properties of the Global Object to make your own extensions
461
available to all script code. Non-local variables in script code
462
will be created as properties of the Global Object, as well as
463
local variables in global code.</p>
164
464
<p>See also <a href="qscriptengine.html#setGlobalObject">setGlobalObject</a>().</p>
165
<a name="//apple_ref/cpp/instm/QScriptEngine/hasUncaughtException" />
166
<h3 class="fn"><a name="hasUncaughtException" />bool QScriptEngine.hasUncaughtException (<i>self</i>)</h3><p>Returns true if the last script evaluation resulted in an uncaught exception; otherwise returns false.</p>
467
<h3 class="fn"><a name="hasUncaughtException" />bool QScriptEngine.hasUncaughtException (<i>self</i>)</h3><p>Returns true if the last script evaluation resulted in an
468
uncaught exception; otherwise returns false.</p>
167
469
<p>The exception state is cleared when <a href="qscriptengine.html#evaluate">evaluate</a>() is called.</p>
168
<p>See also <a href="qscriptengine.html#uncaughtException">uncaughtException</a>(), <a href="qscriptengine.html#uncaughtExceptionLineNumber">uncaughtExceptionLineNumber</a>(), and <a href="qscriptengine.html#uncaughtExceptionBacktrace">uncaughtExceptionBacktrace</a>().</p>
169
<a name="//apple_ref/cpp/instm/QScriptEngine/importExtension" />
170
<h3 class="fn"><a name="importedExtensions" />QStringList QScriptEngine.importedExtensions (<i>self</i>)</h3><p>Returns a list naming the extensions that have been imported using the <a href="qscriptengine.html#importExtension">importExtension</a>() function.</p>
470
<p>See also <a href="qscriptengine.html#uncaughtException">uncaughtException</a>(),
471
<a href="qscriptengine.html#uncaughtExceptionLineNumber">uncaughtExceptionLineNumber</a>(),
472
and <a href="qscriptengine.html#uncaughtExceptionBacktrace">uncaughtExceptionBacktrace</a>().</p>
475
<h3 class="fn"><a name="importedExtensions" />QStringList QScriptEngine.importedExtensions (<i>self</i>)</h3><p>Returns a list naming the extensions that have been imported
476
using the <a href="qscriptengine.html#importExtension">importExtension</a>()
171
478
<p>This function was introduced in Qt 4.4.</p>
172
479
<p>See also <a href="qscriptengine.html#availableExtensions">availableExtensions</a>().</p>
173
<a name="//apple_ref/cpp/instm/QScriptEngine/installTranslatorFunctions" />
174
<h3 class="fn"><a name="importExtension" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.importExtension (<i>self</i>, QString)</h3><p>Imports the given <i>extension</i> into this <a href="qscriptengine.html">QScriptEngine</a>. Returns <a href="qscriptengine.html#undefinedValue">undefinedValue</a>() if the extension was successfully imported. You can call <a href="qscriptengine.html#hasUncaughtException">hasUncaughtException</a>() to check if an error occurred; in that case, the return value is the value that was thrown by the exception (usually an <tt>Error</tt> object).</p>
175
<p><a href="qscriptengine.html">QScriptEngine</a> ensures that a particular extension is only imported once; subsequent calls to importExtension() with the same extension name will do nothing and return <a href="qscriptengine.html#undefinedValue">undefinedValue</a>().</p>
176
<p>See also <a href="qscriptengine.html#availableExtensions">availableExtensions</a>(), <a href="qscriptextensionplugin.html">QScriptExtensionPlugin</a>, and <a href="qtscriptextensions.html">Creating QtScript Extensions</a>.</p>
177
<a name="//apple_ref/cpp/instm/QScriptEngine/importedExtensions" />
178
<h3 class="fn"><a name="installTranslatorFunctions" />QScriptEngine.installTranslatorFunctions (<i>self</i>, <a href="qscriptvalue.html">QScriptValue</a> <i>object</i> = QScriptValue())</h3><p>Installs translator functions on the given <i>object</i>, or on the Global Object if no object is specified.</p>
179
<p>The relation between Qt Script translator functions and C++ translator functions is described in the following table:</p>
180
<p><table align="center" border="0" cellpadding="2" cellspacing="1" class="generic">
181
<thead><tr class="qt-style" valign="top"><th>Script Function</th><th>Corresponding C++ Function</th></tr></thead>
182
<tr class="odd" valign="top"><td>qsTr()</td><td><a href="qobject.html#tr">QObject.tr</a>()</td></tr>
183
<tr class="even" valign="top"><td><a href="qtcore.html#QT_TR_NOOP">QT_TR_NOOP</a>()</td><td><a href="qtcore.html#QT_TR_NOOP">QT_TR_NOOP</a>()</td></tr>
184
<tr class="odd" valign="top"><td>qsTranslate()</td><td><a href="qcoreapplication.html#translate">QCoreApplication.translate</a>()</td></tr>
185
<tr class="even" valign="top"><td><a href="qtcore.html#QT_TRANSLATE_NOOP">QT_TRANSLATE_NOOP</a>()</td><td><a href="qtcore.html#QT_TRANSLATE_NOOP">QT_TRANSLATE_NOOP</a>()</td></tr>
482
<h3 class="fn"><a name="importExtension" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.importExtension (<i>self</i>, QString)</h3><p>Imports the given <i>extension</i> into this <a href="qscriptengine.html">QScriptEngine</a>. Returns <a href="qscriptengine.html#undefinedValue">undefinedValue</a>() if the
483
extension was successfully imported. You can call <a href="qscriptengine.html#hasUncaughtException">hasUncaughtException</a>()
484
to check if an error occurred; in that case, the return value is
485
the value that was thrown by the exception (usually an
486
<tt>Error</tt> object).</p>
487
<p><a href="qscriptengine.html">QScriptEngine</a> ensures that a
488
particular extension is only imported once; subsequent calls to
489
importExtension() with the same extension name will do nothing and
490
return <a href="qscriptengine.html#undefinedValue">undefinedValue</a>().</p>
491
<p>See also <a href="qscriptengine.html#availableExtensions">availableExtensions</a>(),
492
<a href="qscriptextensionplugin.html">QScriptExtensionPlugin</a>,
493
and <a href="qtscriptextensions.html">Creating QtScript
497
<h3 class="fn"><a name="installTranslatorFunctions" />QScriptEngine.installTranslatorFunctions (<i>self</i>, <a href="qscriptvalue.html">QScriptValue</a> <i>object</i> = QScriptValue())</h3><p>Installs translator functions on the given <i>object</i>, or on
498
the Global Object if no object is specified.</p>
499
<p>The relation between Qt Script translator functions and C++
500
translator functions is described in the following table:</p>
501
<table class="generic">
503
<tr class="qt-style topAlign">
504
<th>Script Function</th>
505
<th>Corresponding C++ Function</th>
508
<tr class="odd topAlign">
513
<p><a href="qobject.html#tr">QObject.tr</a>()</p>
516
<tr class="even topAlign">
518
<p><a href="qtcore.html#QT_TR_NOOP">QT_TR_NOOP</a>()</p>
521
<p><a href="qtcore.html#QT_TR_NOOP">QT_TR_NOOP</a>()</p>
524
<tr class="odd topAlign">
529
<p><a href="qcoreapplication.html#translate">QCoreApplication.translate</a>()</p>
532
<tr class="even topAlign">
534
<p><a href="qtcore.html#QT_TRANSLATE_NOOP">QT_TRANSLATE_NOOP</a>()</p>
537
<p><a href="qtcore.html#QT_TRANSLATE_NOOP">QT_TRANSLATE_NOOP</a>()</p>
187
541
<p>This function was introduced in Qt 4.5.</p>
188
542
<p>See also <a href="internationalization.html">Internationalization with Qt</a>.</p>
189
<a name="//apple_ref/cpp/instm/QScriptEngine/isEvaluating" />
190
<h3 class="fn"><a name="isEvaluating" />bool QScriptEngine.isEvaluating (<i>self</i>)</h3><p>Returns true if this engine is currently evaluating a script, otherwise returns false.</p>
545
<h3 class="fn"><a name="isEvaluating" />bool QScriptEngine.isEvaluating (<i>self</i>)</h3><p>Returns true if this engine is currently evaluating a script,
546
otherwise returns false.</p>
191
547
<p>This function was introduced in Qt 4.4.</p>
192
<p>See also <a href="qscriptengine.html#evaluate">evaluate</a>() and <a href="qscriptengine.html#abortEvaluation">abortEvaluation</a>().</p>
193
<a name="//apple_ref/cpp/instm/QScriptEngine/newArray" />
194
<h3 class="fn"><a name="newArray" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.newArray (<i>self</i>, int <i>length</i> = 0)</h3><p>Creates a <a href="qtscript.html">QtScript</a> object of class Array with the given <i>length</i>.</p>
548
<p>See also <a href="qscriptengine.html#evaluate">evaluate</a>()
549
and <a href="qscriptengine.html#abortEvaluation">abortEvaluation</a>().</p>
552
<h3 class="fn"><a name="newArray" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.newArray (<i>self</i>, int <i>length</i> = 0)</h3><p>Creates a <a href="qtscript.html">QtScript</a> object of class
553
Array with the given <i>length</i>.</p>
195
554
<p>See also <a href="qscriptengine.html#newObject">newObject</a>().</p>
196
<a name="//apple_ref/cpp/instm/QScriptEngine/newDate" />
197
<h3 class="fn"><a name="newDate" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.newDate (<i>self</i>, float)</h3><p>Creates a <a href="qtscript.html">QtScript</a> object of class Date with the given <i>value</i> (the number of milliseconds since 01 January 1970, UTC).</p>
198
<h3 class="fn"><a name="newDate-2" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.newDate (<i>self</i>, <a href="qdatetime.html">QDateTime</a>)</h3><p>Creates a <a href="qtscript.html">QtScript</a> object of class Date from the given <i>value</i>.</p>
557
<h3 class="fn"><a name="newDate" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.newDate (<i>self</i>, float)</h3><p>Creates a <a href="qtscript.html">QtScript</a> object of class
558
Date with the given <i>value</i> (the number of milliseconds since
559
01 January 1970, UTC).</p>
562
<h3 class="fn"><a name="newDate-2" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.newDate (<i>self</i>, <a href="qdatetime.html">QDateTime</a>)</h3><p>Creates a <a href="qtscript.html">QtScript</a> object of class
563
Date from the given <i>value</i>.</p>
199
564
<p>See also <a href="qscriptvalue.html#toDateTime">QScriptValue.toDateTime</a>().</p>
200
<a name="//apple_ref/cpp/instm/QScriptEngine/newFunction" />
201
<h3 class="fn"><a name="newFunction" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.newFunction (<i>self</i>, callable, int <i>length</i> = 0)</h3><p>Creates a <a href="qscriptvalue.html">QScriptValue</a> that wraps a native (C++) function. <i>fun</i> must be a C++ function with signature <a href="qscriptengine.html#FunctionSignature-typedef">QScriptEngine.FunctionSignature</a>. <i>length</i> is the number of arguments that <i>fun</i> expects; this becomes the <tt>length</tt> property of the created <a href="qscriptvalue.html">QScriptValue</a>.</p>
202
<p>Note that <i>length</i> only gives an indication of the number of arguments that the function expects; an actual invocation of a function can include any number of arguments. You can check the <a href="qscriptcontext.html#argumentCount">argumentCount()</a> of the <a href="qscriptcontext.html">QScriptContext</a> associated with the invocation to determine the actual number of arguments passed.</p>
203
<p>A <tt>prototype</tt> property is automatically created for the resulting function object, to provide for the possibility that the function will be used as a constructor.</p>
204
<p>By combining newFunction() and the property flags <a href="qscriptvalue.html#PropertyFlag-enum">QScriptValue.PropertyGetter</a> and <a href="qscriptvalue.html#PropertyFlag-enum">QScriptValue.PropertySetter</a>, you can create script object properties that behave like normal properties in script code, but are in fact accessed through functions (analogous to how properties work in <a href="properties.html">Qt's Property System</a>). Example:</p>
205
<pre> static QScriptValue getSetFoo(QScriptContext *context, QScriptEngine *engine)
567
<h3 class="fn"><a name="newFunction" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.newFunction (<i>self</i>, callable, int <i>length</i> = 0)</h3><p>Creates a <a href="qscriptvalue.html">QScriptValue</a> that
568
wraps a native (C++) function. <i>fun</i> must be a C++ function
569
with signature <a href="qscriptengine.html#FunctionSignature-typedef">QScriptEngine.FunctionSignature</a>.
570
<i>length</i> is the number of arguments that <i>fun</i> expects;
571
this becomes the <tt>length</tt> property of the created <a href="qscriptvalue.html">QScriptValue</a>.</p>
572
<p>Note that <i>length</i> only gives an indication of the number
573
of arguments that the function expects; an actual invocation of a
574
function can include any number of arguments. You can check the
575
<a href="qscriptcontext.html#argumentCount">argumentCount()</a> of
576
the <a href="qscriptcontext.html">QScriptContext</a> associated
577
with the invocation to determine the actual number of arguments
579
<p>A <tt>prototype</tt> property is automatically created for the
580
resulting function object, to provide for the possibility that the
581
function will be used as a constructor.</p>
582
<p>By combining newFunction() and the property flags <a href="qscriptvalue.html#PropertyFlag-enum">QScriptValue.PropertyGetter</a>
583
and <a href="qscriptvalue.html#PropertyFlag-enum">QScriptValue.PropertySetter</a>,
584
you can create script object properties that behave like normal
585
properties in script code, but are in fact accessed through
586
functions (analogous to how properties work in <a href="properties.html#qt-s-property-system">Qt's Property System</a>).
588
<pre class="highlightedCode brush: cpp">
589
static QScriptValue getSetFoo(QScriptContext *context, QScriptEngine *engine)
207
591
QScriptValue callee = context->callee();
208
592
if (context->argumentCount() == 1) <span class="comment">// writing?</span>
302
739
QScriptValue metaObject = engine.newQMetaObject(&QObject.staticMetaObject, ctor);
303
740
engine.globalObject().setProperty("QObject", metaObject);
305
QScriptValue result = engine.evaluate("new QObject()");</pre>
742
QScriptValue result = engine.evaluate("new QObject()");
306
744
<p>See also <a href="qscriptengine.html#newQObject">newQObject</a>() and <a href="qscriptengine.html#scriptValueFromQMetaObject">scriptValueFromQMetaObject</a>().</p>
307
<a name="//apple_ref/cpp/instm/QScriptEngine/newQObject" />
308
<h3 class="fn"><a name="newQObject" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.newQObject (<i>self</i>, <a href="qobject.html">QObject</a>, <a href="qscriptengine.html#ValueOwnership-enum">ValueOwnership</a> <i>ownership</i> = QScriptEngine.QtOwnership, <a href="qscriptengine-qobjectwrapoptions.html">QObjectWrapOptions</a> <i>options</i> = 0)</h3><p>Creates a <a href="qtscript.html">QtScript</a> object that wraps the given <a href="qobject.html">QObject</a> <i>object</i>, using the given <i>ownership</i>. The given <i>options</i> control various aspects of the interaction with the resulting script object.</p>
309
<p>Signals and slots, properties and children of <i>object</i> are available as properties of the created <a href="qscriptvalue.html">QScriptValue</a>. For more information, see the <a href="qtscript.html">QtScript</a> documentation.</p>
310
<p>If <i>object</i> is a null pointer, this function returns <a href="qscriptengine.html#nullValue">nullValue</a>().</p>
311
<p>If a default prototype has been registered for the <i>object</i>'s class (or its superclass, recursively), the prototype of the new script object will be set to be that default prototype.</p>
312
<p>If the given <i>object</i> is deleted outside of <a href="qtscript.html">QtScript</a>'s control, any attempt to access the deleted <a href="qobject.html">QObject</a>'s members through the <a href="qtscript.html">QtScript</a> wrapper object (either by script code or C++) will result in a script exception.</p>
313
<p>See also <a href="qscriptvalue.html#toQObject">QScriptValue.toQObject</a>().</p>
747
<h3 class="fn"><a name="newQObject" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.newQObject (<i>self</i>, <a href="qobject.html">QObject</a>, <a href="qscriptengine.html#ValueOwnership-enum">ValueOwnership</a> <i>ownership</i> = QScriptEngine.QtOwnership, <a href="qscriptengine-qobjectwrapoptions.html">QObjectWrapOptions</a> <i>options</i> = 0)</h3><p>Creates a <a href="qtscript.html">QtScript</a> object that wraps
748
the given <a href="qobject.html">QObject</a> <i>object</i>, using
749
the given <i>ownership</i>. The given <i>options</i> control
750
various aspects of the interaction with the resulting script
752
<p>Signals and slots, properties and children of <i>object</i> are
753
available as properties of the created <a href="qscriptvalue.html">QScriptValue</a>. For more information, see the
754
<a href="qtscript.html">QtScript</a> documentation.</p>
755
<p>If <i>object</i> is a null pointer, this function returns
756
<a href="qscriptengine.html#nullValue">nullValue</a>().</p>
757
<p>If a default prototype has been registered for the
758
<i>object</i>'s class (or its superclass, recursively), the
759
prototype of the new script object will be set to be that default
761
<p>If the given <i>object</i> is deleted outside of <a href="qtscript.html">QtScript</a>'s control, any attempt to access the
762
deleted <a href="qobject.html">QObject</a>'s members through the
763
<a href="qtscript.html">QtScript</a> wrapper object (either by
764
script code or C++) will result in a script exception.</p>
765
<p>See also <a href="qscriptvalue.html#toQObject">QScriptValue.toQObject</a>() and
766
<a href="qscriptengine.html#reportAdditionalMemoryCost">reportAdditionalMemoryCost</a>().</p>
314
769
<h3 class="fn"><a name="newQObject-2" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.newQObject (<i>self</i>, <a href="qscriptvalue.html">QScriptValue</a>, <a href="qobject.html">QObject</a>, <a href="qscriptengine.html#ValueOwnership-enum">ValueOwnership</a> <i>ownership</i> = QScriptEngine.QtOwnership, <a href="qscriptengine-qobjectwrapoptions.html">QObjectWrapOptions</a> <i>options</i> = 0)</h3><p>This is an overloaded function.</p>
315
<p>Initializes the given <i>scriptObject</i> to hold the given <i>qtObject</i>, and returns the <i>scriptObject</i>.</p>
316
<p>This function enables you to "promote" a plain Qt Script object (created by the <a href="qscriptengine.html#newObject">newObject</a>() function) to a <a href="qobject.html">QObject</a> proxy, or to replace the <a href="qobject.html">QObject</a> contained inside an object previously created by the <a href="qscriptengine.html#newQObject">newQObject</a>() function.</p>
317
<p>The prototype() of the <i>scriptObject</i> will remain unchanged.</p>
318
<p>If <i>scriptObject</i> is not an object, this function behaves like the normal <a href="qscriptengine.html#newQObject">newQObject</a>(), i.e. it creates a new script object and returns it.</p>
319
<p>This function is useful when you want to provide a script constructor for a <a href="qobject.html">QObject</a>-based class. If your constructor is invoked in a <tt>new</tt> expression (<a href="qscriptcontext.html#isCalledAsConstructor">QScriptContext.isCalledAsConstructor</a>() returns true), you can pass <a href="qscriptcontext.html#thisObject">QScriptContext.thisObject</a>() (the default constructed script object) to this function to initialize the new object.</p>
770
<p>Initializes the given <i>scriptObject</i> to hold the given
771
<i>qtObject</i>, and returns the <i>scriptObject</i>.</p>
772
<p>This function enables you to "promote" a plain Qt Script object
773
(created by the <a href="qscriptengine.html#newObject">newObject</a>() function) to a
774
<a href="qobject.html">QObject</a> proxy, or to replace the
775
<a href="qobject.html">QObject</a> contained inside an object
776
previously created by the <a href="qscriptengine.html#newQObject">newQObject</a>() function.</p>
777
<p>The prototype() of the <i>scriptObject</i> will remain
779
<p>If <i>scriptObject</i> is not an object, this function behaves
780
like the normal <a href="qscriptengine.html#newQObject">newQObject</a>(), i.e. it creates a
781
new script object and returns it.</p>
782
<p>This function is useful when you want to provide a script
783
constructor for a <a href="qobject.html">QObject</a>-based class.
784
If your constructor is invoked in a <tt>new</tt> expression
785
(<a href="qscriptcontext.html#isCalledAsConstructor">QScriptContext.isCalledAsConstructor</a>()
786
returns true), you can pass <a href="qscriptcontext.html#thisObject">QScriptContext.thisObject</a>()
787
(the default constructed script object) to this function to
788
initialize the new object.</p>
320
789
<p>This function was introduced in Qt 4.4.</p>
321
<a name="//apple_ref/cpp/instm/QScriptEngine/newRegExp" />
322
<h3 class="fn"><a name="newRegExp" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.newRegExp (<i>self</i>, <a href="qregexp.html">QRegExp</a>)</h3><p>Creates a <a href="qtscript.html">QtScript</a> object of class RegExp with the given <i>regexp</i>.</p>
790
<p>See also <a href="qscriptengine.html#reportAdditionalMemoryCost">reportAdditionalMemoryCost</a>().</p>
793
<h3 class="fn"><a name="newRegExp" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.newRegExp (<i>self</i>, <a href="qregexp.html">QRegExp</a>)</h3><p>Creates a <a href="qtscript.html">QtScript</a> object of class
794
RegExp with the given <i>regexp</i>.</p>
323
795
<p>See also <a href="qscriptvalue.html#toRegExp">QScriptValue.toRegExp</a>().</p>
324
<h3 class="fn"><a name="newRegExp-2" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.newRegExp (<i>self</i>, QString, QString)</h3><p>Creates a <a href="qtscript.html">QtScript</a> object of class RegExp with the given <i>pattern</i> and <i>flags</i>.</p>
325
<p>The legal flags are 'g' (global), 'i' (ignore case), and 'm' (multiline).</p>
326
<a name="//apple_ref/cpp/instm/QScriptEngine/newVariant" />
327
<h3 class="fn"><a name="newVariant" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.newVariant (<i>self</i>, QVariant)</h3><p>Creates a <a href="qtscript.html">QtScript</a> object holding the given variant <i>value</i>.</p>
328
<p>If a default prototype has been registered with the meta type id of <i>value</i>, then the prototype of the created object will be that prototype; otherwise, the prototype will be the Object prototype object.</p>
329
<p>See also <a href="qscriptengine.html#setDefaultPrototype">setDefaultPrototype</a>() and <a href="qscriptvalue.html#toVariant">QScriptValue.toVariant</a>().</p>
798
<h3 class="fn"><a name="newRegExp-2" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.newRegExp (<i>self</i>, QString, QString)</h3><p>Creates a <a href="qtscript.html">QtScript</a> object of class
799
RegExp with the given <i>pattern</i> and <i>flags</i>.</p>
800
<p>The legal flags are 'g' (global), 'i' (ignore case), and 'm'
804
<h3 class="fn"><a name="newVariant" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.newVariant (<i>self</i>, QVariant)</h3><p>Creates a <a href="qtscript.html">QtScript</a> object holding
805
the given variant <i>value</i>.</p>
806
<p>If a default prototype has been registered with the meta type id
807
of <i>value</i>, then the prototype of the created object will be
808
that prototype; otherwise, the prototype will be the Object
809
prototype object.</p>
810
<p>See also <a href="qscriptengine.html#setDefaultPrototype">setDefaultPrototype</a>(),
811
<a href="qscriptvalue.html#toVariant">QScriptValue.toVariant</a>(), and
812
<a href="qscriptengine.html#reportAdditionalMemoryCost">reportAdditionalMemoryCost</a>().</p>
330
815
<h3 class="fn"><a name="newVariant-2" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.newVariant (<i>self</i>, <a href="qscriptvalue.html">QScriptValue</a>, QVariant)</h3><p>This is an overloaded function.</p>
331
<p>Initializes the given Qt Script <i>object</i> to hold the given variant <i>value</i>, and returns the <i>object</i>.</p>
332
<p>This function enables you to "promote" a plain Qt Script object (created by the <a href="qscriptengine.html#newObject">newObject</a>() function) to a variant, or to replace the variant contained inside an object previously created by the <a href="qscriptengine.html#newVariant">newVariant</a>() function.</p>
816
<p>Initializes the given Qt Script <i>object</i> to hold the given
817
variant <i>value</i>, and returns the <i>object</i>.</p>
818
<p>This function enables you to "promote" a plain Qt Script object
819
(created by the <a href="qscriptengine.html#newObject">newObject</a>() function) to a
820
variant, or to replace the variant contained inside an object
821
previously created by the <a href="qscriptengine.html#newVariant">newVariant</a>() function.</p>
333
822
<p>The prototype() of the <i>object</i> will remain unchanged.</p>
334
<p>If <i>object</i> is not an object, this function behaves like the normal <a href="qscriptengine.html#newVariant">newVariant</a>(), i.e. it creates a new script object and returns it.</p>
335
<p>This function is useful when you want to provide a script constructor for a C++ type. If your constructor is invoked in a <tt>new</tt> expression (<a href="qscriptcontext.html#isCalledAsConstructor">QScriptContext.isCalledAsConstructor</a>() returns true), you can pass <a href="qscriptcontext.html#thisObject">QScriptContext.thisObject</a>() (the default constructed script object) to this function to initialize the new object.</p>
823
<p>If <i>object</i> is not an object, this function behaves like
824
the normal <a href="qscriptengine.html#newVariant">newVariant</a>(), i.e. it creates a
825
new script object and returns it.</p>
826
<p>This function is useful when you want to provide a script
827
constructor for a C++ type. If your constructor is invoked in a
828
<tt>new</tt> expression (<a href="qscriptcontext.html#isCalledAsConstructor">QScriptContext.isCalledAsConstructor</a>()
829
returns true), you can pass <a href="qscriptcontext.html#thisObject">QScriptContext.thisObject</a>()
830
(the default constructed script object) to this function to
831
initialize the new object.</p>
336
832
<p>This function was introduced in Qt 4.4.</p>
337
<a name="//apple_ref/cpp/instm/QScriptEngine/nullValue" />
338
<h3 class="fn"><a name="nullValue" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.nullValue (<i>self</i>)</h3><p>Returns a <a href="qscriptvalue.html">QScriptValue</a> of the primitive type Null.</p>
833
<p>See also <a href="qscriptengine.html#reportAdditionalMemoryCost">reportAdditionalMemoryCost</a>().</p>
836
<h3 class="fn"><a name="nullValue" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.nullValue (<i>self</i>)</h3><p>Returns a <a href="qscriptvalue.html">QScriptValue</a> of the
837
primitive type Null.</p>
339
838
<p>See also <a href="qscriptengine.html#undefinedValue">undefinedValue</a>().</p>
340
<a name="//apple_ref/cpp/instm/QScriptEngine/popContext" />
341
<h3 class="fn"><a name="popContext" />QScriptEngine.popContext (<i>self</i>)</h3><p>Pops the current execution context and restores the previous one. This function must be used in conjunction with <a href="qscriptengine.html#pushContext">pushContext</a>().</p>
841
<h3 class="fn"><a name="popContext" />QScriptEngine.popContext (<i>self</i>)</h3><p>Pops the current execution context and restores the previous
842
one. This function must be used in conjunction with <a href="qscriptengine.html#pushContext">pushContext</a>().</p>
342
843
<p>See also <a href="qscriptengine.html#pushContext">pushContext</a>().</p>
343
<a name="//apple_ref/cpp/instm/QScriptEngine/processEventsInterval" />
344
<h3 class="fn"><a name="processEventsInterval" />int QScriptEngine.processEventsInterval (<i>self</i>)</h3><p>Returns the interval in milliseconds between calls to <a href="qcoreapplication.html#processEvents">QCoreApplication.processEvents</a>() while the interpreter is running.</p>
846
<h3 class="fn"><a name="processEventsInterval" />int QScriptEngine.processEventsInterval (<i>self</i>)</h3><p>Returns the interval in milliseconds between calls to <a href="qcoreapplication.html#processEvents">QCoreApplication.processEvents</a>()
847
while the interpreter is running.</p>
345
848
<p>See also <a href="qscriptengine.html#setProcessEventsInterval">setProcessEventsInterval</a>().</p>
346
<a name="//apple_ref/cpp/instm/QScriptEngine/pushContext" />
347
<h3 class="fn"><a name="pushContext" /><a href="qscriptcontext.html">QScriptContext</a> QScriptEngine.pushContext (<i>self</i>)</h3><p>Enters a new execution context and returns the associated <a href="qscriptcontext.html">QScriptContext</a> object.</p>
348
<p>Once you are done with the context, you should call <a href="qscriptengine.html#popContext">popContext</a>() to restore the old context.</p>
349
<p>By default, the `this' object of the new context is the Global Object. The context's <a href="qscriptcontext.html#callee">callee</a>() will be invalid.</p>
350
<p>This function is useful when you want to evaluate script code as if it were the body of a function. You can use the context's <a href="qscriptcontext.html#activationObject">activationObject</a>() to initialize local variables that will be available to scripts. Example:</p>
351
<pre> QScriptEngine engine;
851
<h3 class="fn"><a name="pushContext" /><a href="qscriptcontext.html">QScriptContext</a> QScriptEngine.pushContext (<i>self</i>)</h3><p>Enters a new execution context and returns the associated
852
<a href="qscriptcontext.html">QScriptContext</a> object.</p>
853
<p>Once you are done with the context, you should call <a href="qscriptengine.html#popContext">popContext</a>() to restore the old
855
<p>By default, the `this' object of the new context is the Global
856
Object. The context's <a href="qscriptcontext.html#callee">callee</a>() will be invalid.</p>
857
<p>This function is useful when you want to evaluate script code as
858
if it were the body of a function. You can use the context's
859
<a href="qscriptcontext.html#activationObject">activationObject</a>() to
860
initialize local variables that will be available to scripts.
862
<pre class="highlightedCode brush: cpp">
863
QScriptEngine engine;
352
864
QScriptContext *context = engine.pushContext();
353
865
context->activationObject().setProperty("myArg", 123);
354
866
engine.evaluate("var tmp = myArg + 42");
356
engine.popContext();</pre>
357
<p>In the above example, the new variable "tmp" defined in the script will be local to the context; in other words, the script doesn't have any effect on the global environment.</p>
870
<p>In the above example, the new variable "tmp" defined in the
871
script will be local to the context; in other words, the script
872
doesn't have any effect on the global environment.</p>
358
873
<p>Returns 0 in case of stack overflow</p>
359
874
<p>See also <a href="qscriptengine.html#popContext">popContext</a>().</p>
360
<a name="//apple_ref/cpp/instm/QScriptEngine/scriptValueFromQMetaObject" />
361
<h3 class="fn"><a name="setAgent" />QScriptEngine.setAgent (<i>self</i>, <a href="qscriptengineagent.html">QScriptEngineAgent</a>)</h3><p>Installs the given <i>agent</i> on this engine. The agent will be notified of various events pertaining to script execution. This is useful when you want to find out exactly what the engine is doing, e.g. when <a href="qscriptengine.html#evaluate">evaluate</a>() is called. The agent interface is the basis of tools like debuggers and profilers.</p>
877
<h3 class="fn"><a name="reportAdditionalMemoryCost" />QScriptEngine.reportAdditionalMemoryCost (<i>self</i>, int <i>size</i>)</h3><p>Reports an additional memory cost of the given <i>size</i>,
878
measured in bytes, to the garbage collector.</p>
879
<p>This function can be called to indicate that a Qt Script object
880
has memory associated with it that isn't managed by Qt Script
881
itself. Reporting the additional cost makes it more likely that the
882
garbage collector will be triggered.</p>
883
<p>Note that if the additional memory is shared with objects
884
outside the scripting environment, the cost should not be reported,
885
since collecting the Qt Script object would not cause the memory to
887
<p>Negative <i>size</i> values are ignored, i.e. this function
888
can't be used to report that the additional memory has been
890
<p>This function was introduced in Qt 4.7.</p>
891
<p>See also <a href="qscriptengine.html#collectGarbage">collectGarbage</a>().</p>
894
<h3 class="fn"><a name="setAgent" />QScriptEngine.setAgent (<i>self</i>, <a href="qscriptengineagent.html">QScriptEngineAgent</a>)</h3><p>Installs the given <i>agent</i> on this engine. The agent will
895
be notified of various events pertaining to script execution. This
896
is useful when you want to find out exactly what the engine is
897
doing, e.g. when <a href="qscriptengine.html#evaluate">evaluate</a>() is called. The agent
898
interface is the basis of tools like debuggers and profilers.</p>
362
899
<p>The engine maintains ownership of the <i>agent</i>.</p>
363
<p>Calling this function will replace the existing agent, if any.</p>
900
<p>Calling this function will replace the existing agent, if
364
902
<p>This function was introduced in Qt 4.4.</p>
365
903
<p>See also <a href="qscriptengine.html#agent">agent</a>().</p>
366
<a name="//apple_ref/cpp/instm/QScriptEngine/setDefaultPrototype" />
367
<h3 class="fn"><a name="setDefaultPrototype" />QScriptEngine.setDefaultPrototype (<i>self</i>, int, <a href="qscriptvalue.html">QScriptValue</a>)</h3><p>Sets the default prototype of the C++ type identified by the given <i>metaTypeId</i> to <i>prototype</i>.</p>
368
<p>The default prototype provides a script interface for values of type <i>metaTypeId</i> when a value of that type is accessed from script code. Whenever the script engine (implicitly or explicitly) creates a <a href="qscriptvalue.html">QScriptValue</a> from a value of type <i>metaTypeId</i>, the default prototype will be set as the <a href="qscriptvalue.html">QScriptValue</a>'s prototype.</p>
369
<p>The <i>prototype</i> object itself may be constructed using one of two principal techniques; the simplest is to subclass <a href="qscriptable.html">QScriptable</a>, which enables you to define the scripting API of the type through <a href="qobject.html">QObject</a> properties and slots. Another possibility is to create a script object by calling <a href="qscriptengine.html#newObject">newObject</a>(), and populate the object with the desired properties (e.g. native functions wrapped with <a href="qscriptengine.html#newFunction">newFunction</a>()).</p>
370
<p>See also <a href="qscriptengine.html#defaultPrototype">defaultPrototype</a>(), <a href="qscriptengine.html#qScriptRegisterMetaType">qScriptRegisterMetaType</a>(), <a href="qscriptable.html">QScriptable</a>, and <a href="script-defaultprototypes.html">Default Prototypes Example</a>.</p>
371
<a name="//apple_ref/cpp/instm/QScriptEngine/setGlobalObject" />
372
<h3 class="fn"><a name="setGlobalObject" />QScriptEngine.setGlobalObject (<i>self</i>, <a href="qscriptvalue.html">QScriptValue</a>)</h3><p>Sets this engine's Global Object to be the given <i>object</i>. If <i>object</i> is not a valid script object, this function does nothing.</p>
373
<p>When setting a custom global object, you may want to use <a href="qscriptvalueiterator.html">QScriptValueIterator</a> to copy the properties of the standard Global Object; alternatively, you can set the internal prototype of your custom object to be the original Global Object.</p>
906
<h3 class="fn"><a name="setDefaultPrototype" />QScriptEngine.setDefaultPrototype (<i>self</i>, int, <a href="qscriptvalue.html">QScriptValue</a>)</h3><p>Sets the default prototype of the C++ type identified by the
907
given <i>metaTypeId</i> to <i>prototype</i>.</p>
908
<p>The default prototype provides a script interface for values of
909
type <i>metaTypeId</i> when a value of that type is accessed from
910
script code. Whenever the script engine (implicitly or explicitly)
911
creates a <a href="qscriptvalue.html">QScriptValue</a> from a value
912
of type <i>metaTypeId</i>, the default prototype will be set as the
913
<a href="qscriptvalue.html">QScriptValue</a>'s prototype.</p>
914
<p>The <i>prototype</i> object itself may be constructed using one
915
of two principal techniques; the simplest is to subclass <a href="qscriptable.html">QScriptable</a>, which enables you to define the
916
scripting API of the type through <a href="qobject.html">QObject</a> properties and slots. Another
917
possibility is to create a script object by calling <a href="qscriptengine.html#newObject">newObject</a>(), and populate the
918
object with the desired properties (e.g. native functions wrapped
919
with <a href="qscriptengine.html#newFunction">newFunction</a>()).</p>
920
<p>See also <a href="qscriptengine.html#defaultPrototype">defaultPrototype</a>(),
921
<a href="qscriptengine.html#qScriptRegisterMetaType">qScriptRegisterMetaType</a>(),
922
<a href="qscriptable.html">QScriptable</a>, and <a href="script-defaultprototypes.html">Default Prototypes Example</a>.</p>
925
<h3 class="fn"><a name="setGlobalObject" />QScriptEngine.setGlobalObject (<i>self</i>, <a href="qscriptvalue.html">QScriptValue</a>)</h3><p>Sets this engine's Global Object to be the given <i>object</i>.
926
If <i>object</i> is not a valid script object, this function does
928
<p>When setting a custom global object, you may want to use
929
<a href="qscriptvalueiterator.html">QScriptValueIterator</a> to
930
copy the properties of the standard Global Object; alternatively,
931
you can set the internal prototype of your custom object to be the
932
original Global Object.</p>
374
933
<p>This function was introduced in Qt 4.5.</p>
375
934
<p>See also <a href="qscriptengine.html#globalObject">globalObject</a>().</p>
376
<a name="//apple_ref/cpp/instm/QScriptEngine/setProcessEventsInterval" />
377
<h3 class="fn"><a name="setProcessEventsInterval" />QScriptEngine.setProcessEventsInterval (<i>self</i>, int)</h3><p>Sets the interval between calls to QCoreApplication.processEvents to <i>interval</i> milliseconds.</p>
378
<p>While the interpreter is running, all event processing is by default blocked. This means for instance that the gui will not be updated and timers will not be fired. To allow event processing during interpreter execution one can specify the processing interval to be a positive value, indicating the number of milliseconds between each time <a href="qcoreapplication.html#processEvents">QCoreApplication.processEvents</a>() is called.</p>
379
<p>The default value is -1, which disables event processing during interpreter execution.</p>
380
<p>You can use <a href="qcoreapplication.html#postEvent">QCoreApplication.postEvent</a>() to post an event that performs custom processing at the next interval. For example, you could keep track of the total running time of the script and call <a href="qscriptengine.html#abortEvaluation">abortEvaluation</a>() when you detect that the script has been running for a long time without completing.</p>
937
<h3 class="fn"><a name="setProcessEventsInterval" />QScriptEngine.setProcessEventsInterval (<i>self</i>, int)</h3><p>Sets the interval between calls to
938
QCoreApplication.processEvents to <i>interval</i>
940
<p>While the interpreter is running, all event processing is by
941
default blocked. This means for instance that the gui will not be
942
updated and timers will not be fired. To allow event processing
943
during interpreter execution one can specify the processing
944
interval to be a positive value, indicating the number of
945
milliseconds between each time <a href="qcoreapplication.html#processEvents">QCoreApplication.processEvents</a>()
947
<p>The default value is -1, which disables event processing during
948
interpreter execution.</p>
949
<p>You can use <a href="qcoreapplication.html#postEvent">QCoreApplication.postEvent</a>()
950
to post an event that performs custom processing at the next
951
interval. For example, you could keep track of the total running
952
time of the script and call <a href="qscriptengine.html#abortEvaluation">abortEvaluation</a>() when you
953
detect that the script has been running for a long time without
381
955
<p>See also <a href="qscriptengine.html#processEventsInterval">processEventsInterval</a>().</p>
382
<a name="//apple_ref/cpp/instm/QScriptEngine/signalHandlerException" />
383
<h3 class="fn"><a name="toObject" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.toObject (<i>self</i>, <a href="qscriptvalue.html">QScriptValue</a>)</h3><p>Converts the given <i>value</i> to an object, if such a conversion is possible; otherwise returns an invalid <a href="qscriptvalue.html">QScriptValue</a>. The conversion is performed according to the following table:</p>
384
<p><table align="center" border="0" cellpadding="2" cellspacing="1" class="generic">
385
<thead><tr class="qt-style" valign="top"><th>Input Type</th><th>Result</th></tr></thead>
386
<tr class="odd" valign="top"><td>Undefined</td><td>An invalid <a href="qscriptvalue.html">QScriptValue</a>.</td></tr>
387
<tr class="even" valign="top"><td>Null</td><td>An invalid <a href="qscriptvalue.html">QScriptValue</a>.</td></tr>
388
<tr class="odd" valign="top"><td>Boolean</td><td>A new Boolean object whose internal value is set to the value of the boolean.</td></tr>
389
<tr class="even" valign="top"><td>Number</td><td>A new Number object whose internal value is set to the value of the number.</td></tr>
390
<tr class="odd" valign="top"><td>String</td><td>A new String object whose internal value is set to the value of the string.</td></tr>
391
<tr class="even" valign="top"><td>Object</td><td>The result is the object itself (no conversion).</td></tr>
958
<h3 class="fn"><a name="toObject" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.toObject (<i>self</i>, <a href="qscriptvalue.html">QScriptValue</a>)</h3><p>Converts the given <i>value</i> to an object, if such a
959
conversion is possible; otherwise returns an invalid <a href="qscriptvalue.html">QScriptValue</a>. The conversion is performed
960
according to the following table:</p>
961
<table class="generic">
963
<tr class="qt-style topAlign">
968
<tr class="odd topAlign">
973
<p>An invalid <a href="qscriptvalue.html">QScriptValue</a>.</p>
976
<tr class="even topAlign">
981
<p>An invalid <a href="qscriptvalue.html">QScriptValue</a>.</p>
984
<tr class="odd topAlign">
989
<p>A new Boolean object whose internal value is set to the value of
993
<tr class="even topAlign">
998
<p>A new Number object whose internal value is set to the value of
1002
<tr class="odd topAlign">
1007
<p>A new String object whose internal value is set to the value of
1011
<tr class="even topAlign">
1016
<p>The result is the object itself (no conversion).</p>
393
1020
<p>This function was introduced in Qt 4.5.</p>
394
1021
<p>See also <a href="qscriptengine.html#newObject">newObject</a>().</p>
395
<a name="//apple_ref/cpp/instm/QScriptEngine/toScriptValue" />
396
<h3 class="fn"><a name="toStringHandle" /><a href="qscriptstring.html">QScriptString</a> QScriptEngine.toStringHandle (<i>self</i>, QString)</h3><p>Returns a handle that represents the given string, <i>str</i>.</p>
397
<p><a href="qscriptstring.html">QScriptString</a> can be used to quickly look up properties, and compare property names, of script objects.</p>
1024
<h3 class="fn"><a name="toStringHandle" /><a href="qscriptstring.html">QScriptString</a> QScriptEngine.toStringHandle (<i>self</i>, QString)</h3><p>Returns a handle that represents the given string,
1026
<p><a href="qscriptstring.html">QScriptString</a> can be used to
1027
quickly look up properties, and compare property names, of script
398
1029
<p>This function was introduced in Qt 4.4.</p>
399
1030
<p>See also <a href="qscriptvalue.html#property">QScriptValue.property</a>().</p>
400
<a name="//apple_ref/cpp/instm/QScriptEngine/uncaughtException" />
401
<h3 class="fn"><a name="uncaughtException" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.uncaughtException (<i>self</i>)</h3><p>Returns the current uncaught exception, or an invalid <a href="qscriptvalue.html">QScriptValue</a> if there is no uncaught exception.</p>
402
<p>The exception value is typically an <tt>Error</tt> object; in that case, you can call toString() on the return value to obtain an error message.</p>
403
<p>See also <a href="qscriptengine.html#hasUncaughtException">hasUncaughtException</a>(), <a href="qscriptengine.html#uncaughtExceptionLineNumber">uncaughtExceptionLineNumber</a>(), and <a href="qscriptengine.html#uncaughtExceptionBacktrace">uncaughtExceptionBacktrace</a>().</p>
404
<a name="//apple_ref/cpp/instm/QScriptEngine/uncaughtExceptionBacktrace" />
405
<h3 class="fn"><a name="uncaughtExceptionBacktrace" />QStringList QScriptEngine.uncaughtExceptionBacktrace (<i>self</i>)</h3><p>Returns a human-readable backtrace of the last uncaught exception.</p>
406
<p>Each line is of the form <tt><function-name>(<arguments>)@<file-name>:<line-number></tt>.</p>
1033
<h3 class="fn"><a name="uncaughtException" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.uncaughtException (<i>self</i>)</h3><p>Returns the current uncaught exception, or an invalid <a href="qscriptvalue.html">QScriptValue</a> if there is no uncaught
1035
<p>The exception value is typically an <tt>Error</tt> object; in
1036
that case, you can call toString() on the return value to obtain an
1038
<p>See also <a href="qscriptengine.html#hasUncaughtException">hasUncaughtException</a>(),
1039
<a href="qscriptengine.html#uncaughtExceptionLineNumber">uncaughtExceptionLineNumber</a>(),
1040
and <a href="qscriptengine.html#uncaughtExceptionBacktrace">uncaughtExceptionBacktrace</a>().</p>
1043
<h3 class="fn"><a name="uncaughtExceptionBacktrace" />QStringList QScriptEngine.uncaughtExceptionBacktrace (<i>self</i>)</h3><p>Returns a human-readable backtrace of the last uncaught
1045
<p>Each line is of the form
1046
<tt><function-name>(<arguments>)@<file-name>:<line-number></tt>.</p>
407
1047
<p>See also <a href="qscriptengine.html#uncaughtException">uncaughtException</a>().</p>
408
<a name="//apple_ref/cpp/instm/QScriptEngine/uncaughtExceptionLineNumber" />
409
<h3 class="fn"><a name="uncaughtExceptionLineNumber" />int QScriptEngine.uncaughtExceptionLineNumber (<i>self</i>)</h3><p>Returns the line number where the last uncaught exception occurred.</p>
410
<p>Line numbers are 1-based, unless a different base was specified as the second argument to <a href="qscriptengine.html#evaluate">evaluate</a>().</p>
411
<p>See also <a href="qscriptengine.html#hasUncaughtException">hasUncaughtException</a>() and <a href="qscriptengine.html#uncaughtExceptionBacktrace">uncaughtExceptionBacktrace</a>().</p>
412
<a name="//apple_ref/cpp/instm/QScriptEngine/undefinedValue" />
413
<h3 class="fn"><a name="undefinedValue" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.undefinedValue (<i>self</i>)</h3><p>Returns a <a href="qscriptvalue.html">QScriptValue</a> of the primitive type Undefined.</p>
1050
<h3 class="fn"><a name="uncaughtExceptionLineNumber" />int QScriptEngine.uncaughtExceptionLineNumber (<i>self</i>)</h3><p>Returns the line number where the last uncaught exception
1052
<p>Line numbers are 1-based, unless a different base was specified
1053
as the second argument to <a href="qscriptengine.html#evaluate">evaluate</a>().</p>
1054
<p>See also <a href="qscriptengine.html#hasUncaughtException">hasUncaughtException</a>()
1055
and <a href="qscriptengine.html#uncaughtExceptionBacktrace">uncaughtExceptionBacktrace</a>().</p>
1058
<h3 class="fn"><a name="undefinedValue" /><a href="qscriptvalue.html">QScriptValue</a> QScriptEngine.undefinedValue (<i>self</i>)</h3><p>Returns a <a href="qscriptvalue.html">QScriptValue</a> of the
1059
primitive type Undefined.</p>
414
1060
<p>See also <a href="qscriptengine.html#nullValue">nullValue</a>().</p>
415
<hr /><h2>Qt Signal Documentation</h2><h3 class="fn"><a name="signalHandlerException" />void signalHandlerException (const QScriptValue&)</h3><p>This is the default overload of this signal.</p><p>This signal is emitted when a script function connected to a signal causes an <i>exception</i>.</p>
1061
<hr /><h2>Qt Signal Documentation</h2><h3 class="fn"><a name="signalHandlerException" />void signalHandlerException (const QScriptValue&)</h3><p>This is the default overload of this signal.</p><p>This signal is emitted when a script function connected to a
1062
signal causes an <i>exception</i>.</p>
416
1063
<p>This function was introduced in Qt 4.4.</p>
417
1064
<p>See also <a href="qscriptengine.html#qScriptConnect">qScriptConnect</a>().</p>
418
<a name="//apple_ref/cpp/instm/QScriptEngine/toObject" />
419
<address><hr /><div align="center"><table border="0" cellspacing="0" width="100%"><tr class="address"><td align="left" width="25%">PyQt 4.7.7 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>
b'\\ No newline at end of file'
1067
<address><hr /><div align="center"><table border="0" cellspacing="0" width="100%"><tr class="address"><td align="left" width="25%">PyQt 4.8.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.qtsoftware.com">Nokia</a> 2010</td><td align="right" width="25%">Qt 4.7.0</td></tr></table></div></address></body></html>
b'\\ No newline at end of file'
added
removed
doc/html/qscriptengine.html
