Creating Qt Script Extensions

Qt Script 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:

• Subclass QScriptExtensionPlugin and implement the desired functionality.
• Implement the functionality in a script file.
• Use a hybrid approach, where part of the functionality is implemented in a QScriptExtensionPlugin, and part is implemented in a script file.

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:

• __extension__: The name of the extension (e.g. "foo.bar.baz").
• __setupPackage__: A convenience function for setting up a "namespace" in the script environment. A typical application is to call __setupPackage__() with __extension__ as argument; e.g. __setupPackage__("foo.bar.baz") would ensure that the object chain represented by the expression foo.bar.baz exists in the script environment. (This function is semantically equivalent to QScriptExtensionPlugin::setupPackage().)
• __postInit__: By default, this variable is undefined. If you assign a function to it, that function will be called after 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.

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():

• If it exists, foo/__init__.js is evaluated.
• If a plugin with "foo" in its list of keys is found, its initialize() function is called with "foo" as key.
• If it exists, foo/bar/__init__.js is evaluated.
• If a plugin with "foo.bar" in its list of keys is found, its initialize() function is called with "foo.bar" as key.
• If it exists, foo/bar/baz/__init__.js is evaluated.
• If a plugin with "foo.bar.baz" in its list of keys is found, its initialize() function is called with "foo.bar.baz" as key.

Static Extensions

When 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.