<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html><head><title>QScriptClass Class Reference</title><style>h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
td.postheader { font-family: sans-serif }
tr.address { font-family: sans-serif }
body { background: #ffffff; color: black; }
</style></head><body><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr /><td align="left" valign="top" width="32"><img align="left" border="0" height="32" src="images/rb-logo.png" width="32" /></td><td width="1">  </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="modules.html"><font color="#004faf">Modules</font></a></td></table><h1 align="center">QScriptClass Class Reference<br /><sup><sup>[<a href="qtscript.html">QtScript</a> module]</sup></sup></h1><p>The QScriptClass class provides an interface for defining custom
behavior of (a class of) Qt Script objects. <a href="#details">More...</a></p>
<h3>Types</h3><ul><li><div class="fn" />enum <b><a href="qscriptclass.html#Extension-enum">Extension</a></b> { Callable, HasInstance }</li><li><div class="fn" />enum <b><a href="qscriptclass.html#QueryFlag-enum">QueryFlag</a></b> { HandlesReadAccess, HandlesWriteAccess }</li><li><div class="fn" />class <b><a href="qscriptclass-queryflags.html">QueryFlags</a></b></li></ul><h3>Methods</h3><ul><li><div class="fn" /><b><a href="qscriptclass.html#QScriptClass">__init__</a></b> (<i>self</i>, QScriptEngine <i>engine</i>)</li><li><div class="fn" />QScriptEngine <b><a href="qscriptclass.html#engine">engine</a></b> (<i>self</i>)</li><li><div class="fn" />QVariant <b><a href="qscriptclass.html#extension">extension</a></b> (<i>self</i>, Extension <i>extension</i>, QVariant <i>argument</i> = QVariant())</li><li><div class="fn" />QString <b><a href="qscriptclass.html#name">name</a></b> (<i>self</i>)</li><li><div class="fn" />QScriptClassPropertyIterator <b><a href="qscriptclass.html#newIterator">newIterator</a></b> (<i>self</i>, QScriptValue <i>object</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptclass.html#property">property</a></b> (<i>self</i>, QScriptValue <i>object</i>, QScriptString <i>name</i>, int <i>id</i>)</li><li><div class="fn" />QScriptValue.PropertyFlags <b><a href="qscriptclass.html#propertyFlags">propertyFlags</a></b> (<i>self</i>, QScriptValue <i>object</i>, QScriptString <i>name</i>, int <i>id</i>)</li><li><div class="fn" />QScriptValue <b><a href="qscriptclass.html#prototype">prototype</a></b> (<i>self</i>)</li><li><div class="fn" />(QueryFlags, int <i>id</i>) <b><a href="qscriptclass.html#queryProperty">queryProperty</a></b> (<i>self</i>, QScriptValue <i>object</i>, QScriptString <i>name</i>, QueryFlags <i>flags</i>)</li><li><div class="fn" /><b><a href="qscriptclass.html#setProperty">setProperty</a></b> (<i>self</i>, QScriptValue <i>object</i>, QScriptString <i>name</i>, int <i>id</i>, QScriptValue <i>value</i>)</li><li><div class="fn" />bool <b><a href="qscriptclass.html#supportsExtension">supportsExtension</a></b> (<i>self</i>, Extension <i>extension</i>)</li></ul><a name="details" /><hr /><h2>Detailed Description</h2><p>The QScriptClass class provides an interface for defining custom
behavior of (a class of) Qt Script objects.</p>
<p>The QScriptClass class defines an interface for handling various
aspects of interaction with the Qt Script objects associated with
the class. Such objects are created by calling <a href="qscriptengine.html#newObject">QScriptEngine.newObject</a>(),
passing a pointer to the QScriptClass as argument.</p>
<p>By subclassing QScriptClass, you can define precisely how access
to properties of the objects that use your class is handled. This
enables a fully dynamic handling of properties, e.g. it's more
powerful than <a href="qscriptengine.html#newQObject">QScriptEngine.newQObject</a>().
For example, you can use QScriptClass to implement array-type
objects (i.e. objects that handle the <tt>length</tt> property, and
properties whose names are valid array indexes, in a special way),
or to implement a "live" (runtime-defined) proxy to an underlying
object.</p>
<p>If you just need to handle access to a set of properties that
are known at the time an object is created (i.e.
"semi-statically"), you might consider using <a href="qscriptvalue.html#setProperty">QScriptValue.setProperty</a>() to
define getter/setter functions for the relevant properties, rather
than subclassing QScriptClass.</p>
<p>Reimplement <a href="qscriptclass.html#queryProperty">queryProperty</a>() to specify
which properties are handled in a custom way by your script class
(i.e. should be <b>delegated</b> to the QScriptClass), and which
properties should be handled just like normal Qt Script object
properties.</p>
<p>Reimplement <a href="qscriptclass.html#property">property</a>()
and <a href="qscriptclass.html#setProperty">setProperty</a>() to
perform the actual access (read or write) to the properties that
your class handles. Additionally, you can reimplement <a href="qscriptclass.html#propertyFlags">propertyFlags</a>() to specify
custom flags for your properties.</p>
<p>Reimplement <a href="qscriptclass.html#newIterator">newIterator</a>() to provide an
iterator for objects of your custom class. This is only necessary
if objects of your class can have custom properties that you want
to be reported when an object is used together with the <a href="qscriptvalueiterator.html">QScriptValueIterator</a> class, or when
an object is used in a for-in enumeration statement in a
script.</p>
<p>When implementing custom classes of objects, you typically use
<a href="qscriptvalue.html#setData">QScriptValue.setData</a>() to
store instance-specific data as part of object initialization; the
data won't be accessible from scripts directly, but you can access
it in e.g. your reimplementations of <a href="qscriptclass.html#property">property</a>() and <a href="qscriptclass.html#setProperty">setProperty</a>() (by calling
<a href="qscriptvalue.html#data">QScriptValue.data</a>()) to
perform custom processing.</p>
<p>Reimplement <a href="qscriptclass.html#prototype">prototype</a>() to provide a custom
prototype object for your script class.</p>
<p>Reimplement <a href="qscriptclass.html#supportsExtension">supportsExtension</a>() and
<a href="qscriptclass.html#extension">extension</a>() if your
custom script class supports one or more of the extensions
specified by the Extension enum.</p>
<hr /><h2>Type Documentation</h2><h3 class="fn"><a name="Extension-enum" />QScriptClass.Extension</h3><p>This enum specifies the possible extensions to a <a href="qscriptclass.html">QScriptClass</a>.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QScriptClass.Callable</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">Instances of this class can be called as
functions.</td>
</tr>
<tr>
<td class="topAlign"><tt>QScriptClass.HasInstance</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign">Instances of this class implement
[[HasInstance]].</td>
</tr>
</table>
<p><b>See also</b> <a href="qscriptclass.html#extension">extension</a>().</p>
<h3 class="fn"><a name="QueryFlag-enum" />QScriptClass.QueryFlag</h3><p>This enum describes flags that are used to query a <a href="qscriptclass.html">QScriptClass</a> regarding how access to a
property should be handled.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QScriptClass.HandlesReadAccess</tt></td>
<td class="topAlign"><tt>0x01</tt></td>
<td class="topAlign">The <a href="qscriptclass.html">QScriptClass</a> handles read access to this
property.</td>
</tr>
<tr>
<td class="topAlign"><tt>QScriptClass.HandlesWriteAccess</tt></td>
<td class="topAlign"><tt>0x02</tt></td>
<td class="topAlign">The <a href="qscriptclass.html">QScriptClass</a> handles write access to this
property.</td>
</tr>
</table>
<p>The QueryFlags type is a typedef for <a href="qflags.html">QFlags</a><QueryFlag>. It stores an OR
combination of QueryFlag values.</p>
<p><b>See also</b> <a href="qscriptclass.html#queryProperty">queryProperty</a>().</p>
<hr /><h2>Method Documentation</h2><h3 class="fn"><a name="QScriptClass" />QScriptClass.__init__ (<i>self</i>, <a href="qscriptengine.html">QScriptEngine</a> <i>engine</i>)</h3><p>Constructs a <a href="qscriptclass.html">QScriptClass</a> object
to be used in the given <i>engine</i>.</p>
<p>The engine does not take ownership of the <a href="qscriptclass.html">QScriptClass</a> object.</p>
<h3 class="fn"><a name="engine" /><a href="qscriptengine.html">QScriptEngine</a> QScriptClass.engine (<i>self</i>)</h3><p>Returns the engine that this <a href="qscriptclass.html">QScriptClass</a> is associated with.</p>
<h3 class="fn"><a name="extension" />QVariant QScriptClass.extension (<i>self</i>, <a href="qscriptclass.html#Extension-enum">Extension</a> <i>extension</i>, QVariant <i>argument</i> = QVariant())</h3><p>This virtual function can be reimplemented in a <a href="qscriptclass.html">QScriptClass</a> subclass to provide support
for extensions. The optional <i>argument</i> can be provided as
input to the <i>extension</i>; the result must be returned in the
form of a <a href="qvariant.html">QVariant</a>. You can call
<a href="qscriptclass.html#supportsExtension">supportsExtension</a>() to
check if an extension is supported by the <a href="qscriptclass.html">QScriptClass</a>. By default, no extensions are
supported, and this function returns an invalid <a href="qvariant.html">QVariant</a>.</p>
<p>If you implement the Callable extension, Qt Script will call
this function when an instance of your class is called as a
function (e.g. from a script or using <a href="qscriptvalue.html#call">QScriptValue.call</a>()). The
<i>argument</i> will contain a pointer to the <a href="qscriptcontext.html">QScriptContext</a> that represents the
function call, and you should return a <a href="qvariant.html">QVariant</a> that holds the result of the function
call. In the following example the sum of the arguments to the
script function are added up and returned:</p>
<pre class="cpp">
<span class="keyword">if</span> (extension <span class="operator">=</span><span class="operator">=</span> Callable) {
<span class="type"><a href="qscriptcontext.html">QScriptContext</a></span> <span class="operator">*</span>context <span class="operator">=</span> qvariant_cast<span class="operator"><</span><span class="type"><a href="qscriptcontext.html">QScriptContext</a></span><span class="operator">*</span><span class="operator">></span>(argument);
<span class="type"><a href="qscriptengine.html">QScriptEngine</a></span> <span class="operator">*</span>engine <span class="operator">=</span> context<span class="operator">-</span><span class="operator">></span>engine();
<span class="type">double</span> sum <span class="operator">=</span> <span class="number">0</span>;
<span class="keyword">for</span> (<span class="type">int</span> i <span class="operator">=</span> <span class="number">0</span>; i <span class="operator"><</span> context<span class="operator">-</span><span class="operator">></span>argumentCount(); <span class="operator">+</span><span class="operator">+</span>i)
sum <span class="operator">+</span><span class="operator">=</span> context<span class="operator">-</span><span class="operator">></span>argument(i)<span class="operator">.</span>toNumber();
<span class="keyword">return</span> sum;
}
</pre>
<p>If you implement the <a href="qscriptclass.html#Extension-enum">HasInstance</a> extension, Qt
Script will call this function as part of evaluating the
<tt>instanceof</tt> operator, as described in ECMA-262 Section
11.8.6. The <i>argument</i> is a QScriptValueList containing two
items: The first item is the object that <a href="qscriptclass.html#Extension-enum">HasInstance</a> is being applied
to (an instance of your class), and the second item can be any
value. extension() should return true if the value delegates
behavior to the object, false otherwise.</p>
<p><b>See also</b> <a href="qscriptclass.html#supportsExtension">supportsExtension</a>().</p>
<h3 class="fn"><a name="name" />QString QScriptClass.name (<i>self</i>)</h3><p>Returns the name of the script class.</p>
<p>Qt Script uses this name to generate a default string
representation of objects in case you do not provide a toString
function.</p>
<p>The default implementation returns a null string.</p>
<h3 class="fn"><a name="newIterator" /><a href="qscriptclasspropertyiterator.html">QScriptClassPropertyIterator</a> QScriptClass.newIterator (<i>self</i>, <a href="qscriptvalue.html">QScriptValue</a> <i>object</i>)</h3><p>Returns an iterator for traversing custom properties of the
given <i>object</i>.</p>
<p>The default implementation returns 0, meaning that there are no
custom properties to traverse.</p>
<p>Reimplement this function if objects of your script class can
have one or more custom properties (e.g. those reported to be
handled by <a href="qscriptclass.html#queryProperty">queryProperty</a>()) that you
want to appear when an object's properties are enumerated (e.g. by
a for-in statement in a script).</p>
<p>Qt Script takes ownership of the new iterator object.</p>
<p><b>See also</b> <a href="qscriptvalueiterator.html">QScriptValueIterator</a>.</p>
<h3 class="fn"><a name="property" /><a href="qscriptvalue.html">QScriptValue</a> QScriptClass.property (<i>self</i>, <a href="qscriptvalue.html">QScriptValue</a> <i>object</i>, <a href="qscriptstring.html">QScriptString</a> <i>name</i>, int <i>id</i>)</h3><p>Returns the value of the property with the given <i>name</i> of
the given <i>object</i>.</p>
<p>The <i>id</i> argument is only useful if you assigned a value to
it in <a href="qscriptclass.html#queryProperty">queryProperty</a>().</p>
<p>The default implementation does nothing and returns an invalid
<a href="qscriptvalue.html">QScriptValue</a>.</p>
<p><b>See also</b> <a href="qscriptclass.html#setProperty">setProperty</a>() and <a href="qscriptclass.html#propertyFlags">propertyFlags</a>().</p>
<h3 class="fn"><a name="propertyFlags" /><a href="qscriptvalue-propertyflags.html">QScriptValue.PropertyFlags</a> QScriptClass.propertyFlags (<i>self</i>, <a href="qscriptvalue.html">QScriptValue</a> <i>object</i>, <a href="qscriptstring.html">QScriptString</a> <i>name</i>, int <i>id</i>)</h3><p>Returns the flags of the property with the given <i>name</i> of
the given <i>object</i>.</p>
<p>The <i>id</i> argument is only useful if you assigned a value to
it in <a href="qscriptclass.html#queryProperty">queryProperty</a>().</p>
<p>The default implementation returns 0.</p>
<p><b>See also</b> <a href="qscriptclass.html#property">property</a>().</p>
<h3 class="fn"><a name="prototype" /><a href="qscriptvalue.html">QScriptValue</a> QScriptClass.prototype (<i>self</i>)</h3><p>Returns the object to be used as the prototype of new instances
of this class (created with <a href="qscriptengine.html#newObject">QScriptEngine.newObject</a>()).</p>
<p>The default implementation returns an invalid <a href="qscriptvalue.html">QScriptValue</a>, meaning that the standard
Object prototype will be used. Reimplement this function to provide
your own custom prototype.</p>
<p>Typically you initialize your prototype object in the
constructor of your class, then return it in this function.</p>
<p>See the "Making Use of Prototype-Based Inheritance" section in
the <a href="qtscript.html">QtScript</a> documentation for more
information on how prototypes are used.</p>
<h3 class="fn"><a name="queryProperty" />(<a href="qscriptclass-queryflags.html">QueryFlags</a>, int <i>id</i>) QScriptClass.queryProperty (<i>self</i>, <a href="qscriptvalue.html">QScriptValue</a> <i>object</i>, <a href="qscriptstring.html">QScriptString</a> <i>name</i>, <a href="qscriptclass-queryflags.html">QueryFlags</a> <i>flags</i>)</h3><p>Queries this script class for how access to the property with
the given <i>name</i> of the given <i>object</i> should be handled.
The given <i>flags</i> specify the aspects of interest. This
function should return a subset of <i>flags</i> to indicate which
aspects of property access should be further handled by the script
class.</p>
<p>For example, if the <i>flags</i> contain <a href="qscriptclass.html#QueryFlag-enum">HandlesReadAccess</a>, and you
would like your class to handle the reading of the property
(through the <a href="qscriptclass.html#property">property</a>()
function), the returned flags should include <a href="qscriptclass.html#QueryFlag-enum">HandlesReadAccess</a>. If the
returned flags do not contain <a href="qscriptclass.html#QueryFlag-enum">HandlesReadAccess</a>, the
property will be handled as a normal script object property.</p>
<p>You can optionally use the <i>id</i> argument to store a value
that will subsequently be passed on to functions such as <a href="qscriptclass.html#property">property</a>() and <a href="qscriptclass.html#setProperty">setProperty</a>().</p>
<p>The default implementation of this function returns 0.</p>
<p>Note: This function is only called if the given property isn't
already a normal property of the object. For example, say you
advertise that you want to handle read access to property
<tt>foo</tt>, but not write access; if <tt>foo</tt> is then
assigned a value, it will become a normal script object property,
and subsequently you will no longer be queried regarding read
access to <tt>foo</tt>.</p>
<p><b>See also</b> <a href="qscriptclass.html#property">property</a>().</p>
<h3 class="fn"><a name="setProperty" />QScriptClass.setProperty (<i>self</i>, <a href="qscriptvalue.html">QScriptValue</a> <i>object</i>, <a href="qscriptstring.html">QScriptString</a> <i>name</i>, int <i>id</i>, <a href="qscriptvalue.html">QScriptValue</a> <i>value</i>)</h3><p>Sets the property with the given <i>name</i> of the given
<i>object</i> to the given <i>value</i>.</p>
<p>The <i>id</i> argument is only useful if you assigned a value to
it in <a href="qscriptclass.html#queryProperty">queryProperty</a>().</p>
<p>The default implementation does nothing.</p>
<p>An invalid <i>value</i> represents a request to remove the
property.</p>
<p><b>See also</b> <a href="qscriptclass.html#property">property</a>().</p>
<h3 class="fn"><a name="supportsExtension" />bool QScriptClass.supportsExtension (<i>self</i>, <a href="qscriptclass.html#Extension-enum">Extension</a> <i>extension</i>)</h3><p>Returns true if the <a href="qscriptclass.html">QScriptClass</a>
supports the given <i>extension</i>; otherwise, false is returned.
By default, no extensions are supported.</p>
<p>Reimplement this function to indicate which extensions your
custom class supports.</p>
<p><b>See also</b> <a href="qscriptclass.html#extension">extension</a>().</p>
<address><hr /><div align="center"><table border="0" cellspacing="0" width="100%"><tr class="address"><td align="left" width="25%">PyQt 4.10.3 for X11</td><td align="center" width="50%">Copyright © <a href="http://www.riverbankcomputing.com">Riverbank Computing Ltd</a> and <a href="http://www.qtsoftware.com">Nokia</a> 2012</td><td align="right" width="25%">Qt 4.8.5</td></tr></table></div></address></body></html>
