Creating Qt Script Extensions | Qt Script

Qt 5.9 | Qt Script | Creating Qt Script Extensions

Qt 5.9.3 Reference Documentation

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