<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- /home/gvatteka/dev/qt-4.3/doc/src/qtscriptextensions.qdoc -->
<head>
<title>Creating QtScript Extensions</title>
<link href="classic.css" rel="stylesheet" type="text/css" />
</head>
<body>
<h1 align="center">Creating QtScript Extensions<br /><small></small></h1>
<p>QtScript extensions can make additional functionality available to scripts evaluated by a QScriptEngine. Extensions are imported by calling the QScriptEngine::importExtension() function.</p>
<p>There are three ways to create an extension:</p>
<ul>
<li>Subclass QScriptExtensionPlugin and implement the desired functionality.</li>
<li>Implement the functionality in a script file.</li>
<li>Use a hybrid approach, where part of the functionality is implemented in a QScriptExtensionPlugin, and part is implemented in a script file.</li>
</ul>
<p>The (dot-qualified) extension name is used to determine the path (relative to the application's plugin path) where QScriptEngine will look for the script file that will initialize the extension; if a file called <tt>__init__.js</tt> is found in the corresponding folder, its contents will be evaluated by the engine when the extension is imported. As an example, if the extension is called <tt>"foo.bar.baz"</tt>, the engine will look for <tt>__init__.js</tt> in <tt>foo/bar/baz</tt>. Additionally, before importing <tt>"foo.bar.baz"</tt>, the engine will ensure that the extensions <tt>"foo"</tt> and <tt>"foo.bar"</tt> are imported, locating and evaluating the corresponding <tt>__init__.js</tt> in the same manner (in folders <tt>foo</tt> and <tt>foo/bar</tt>, respectively).</p>
<p>The contents of <tt>__init__.js</tt> are evaluated in a new QScriptContext, as if it were the body of a function. The engine's Global Object acts as the <tt>this</tt> object. The following local variables are initially available to the script:</p>
<ul>
<li><b>__extension__</b>: The name of the extension (e.g. <tt>"foo.bar.baz"</tt>).</li>
<li><b>__setupPackage__</b>: A convenience function for setting up a "namespace" in the script environment. A typical application is to call <tt>__setupPackage__()</tt> with <tt>__extension__</tt> as argument; e.g. <tt>__setupPackage__("foo.bar.baz")</tt> would ensure that the object chain represented by the expression <tt>foo.bar.baz</tt> exists in the script environment. (This function is semantically equivalent to QScriptExtensionPlugin::setupPackage().)</li>
<li><b>__postInit__</b>: By default, this variable is undefined. If you assign a function to it, that function will be called <b>after</b> the C++ plugin's initialize() function has been called. You can use this to perform further initialization that depends on e.g. native functions that the C++ plugin registers.</li>
</ul>
<p>An example of a simple <tt>__init__.js</tt>:</p>
<pre> print("importing " + __extension__);
__setupPackage__("cool.stuff");
cool.stuff.add = function(a, b) { return a + b; }
cool.stuff.subtract = function(a, b) { return a - b; }</pre>
<p>QScriptEngine will look for a QScriptExtensionPlugin that provides the relevant extension by querying each plugin for its keys() until a match is found. The plugin's initialize() function will be called <b>after</b> the relevant <tt>__init__.js</tt> (if any) has been evaluated.</p>
<p>Continuining with the example of our imaginary extension <tt>"foo.bar.baz"</tt>, the following steps will be performed by QScriptEngine::importExtension():</p>
<ul>
<li>If it exists, <tt>foo/__init__.js</tt> is evaluated.</li>
<li>If a plugin with <tt>"foo"</tt> in its list of keys is found, its initialize() function is called with <tt>"foo"</tt> as key.</li>
<li>If it exists, <tt>foo/bar/__init__.js</tt> is evaluated.</li>
<li>If a plugin with <tt>"foo.bar"</tt> in its list of keys is found, its initialize() function is called with <tt>"foo.bar"</tt> as key.</li>
<li>If it exists, <tt>foo/bar/baz/__init__.js</tt> is evaluated.</li>
<li>If a plugin with "foo.bar.baz" in its list of keys is found, its initialize() function is called with <tt>"foo.bar.baz"</tt> as key.</li>
</ul>
<p /><address><hr /><div align="center">
<table width="100%" cellspacing="0" border="0"><tr class="address">
<td width="30%">Copyright © 2007 <a href="trolltech.html">Trolltech</a></td>
<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>
<td width="30%" align="right"><div align="right">Qt Jambi </div></td>
</tr></table></div></address></body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
a6711891ce757817bba854bf3f25205a
>
files
>
2434
