Creating QtScript ExtensionsQtScript extensions can make additional functionality available to scripts evaluated by a QScriptEngine. Extensions are imported by calling the QScriptEngine::importExtension() function. There are three ways to create an extension:
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 __init__.js (usually located in [application plugin path]/script/foo/) 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 "foo.bar.baz", the engine will look for __init__.js in foo/bar/baz. Additionally, before importing "foo.bar.baz", the engine will ensure that the extensions "foo" and "foo.bar" are imported, locating and evaluating the corresponding __init__.js in the same manner (in folders foo and foo/bar, respectively). The contents of __init__.js are evaluated in a new QScriptContext, as if it were the body of a function. The engine's Global Object acts as the this object. The following local variables are initially available to the script:
An example of a simple __init__.js: print("importing " + __extension__); __setupPackage__("cool.stuff"); cool.stuff.add = function(a, b) { return a + b; } cool.stuff.subtract = function(a, b) { return a - b; } 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 after the relevant __init__.js (if any) has been evaluated. Continuining with the example of our imaginary extension "foo.bar.baz", the following steps will be performed by QScriptEngine::importExtension():
Static ExtensionsWhen an extension is compiled and linked into your application as a static plugin, Qt Script will look for the optional __init__.js script in a resource, prefixed by :/qtscriptextension. For example, if the extension key is "foo.bar", Qt Script will evaluate the contents of the file :/qtscriptextension/foo/bar/__init__.js, if it exists. Note that if the resource is built into the plugin, you may need to use the Q_INIT_RESOURCE() macro to initialize the resource before importing the extension. |