<?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>