Workspace 6.21.5
Executing a QtScript

RunQtScript Basic Usage

There are number of Scripting operations in Workspace, these allow you to write some custom functionality in a scripting language that you may already be familiar with and add to your workflows. Currently Workspace has support for QtScript (JavaScript, ECMAScript), Python, R and MatLab.

Current script operations

RunQtScript is a particularly versatile operation, providing somewhat of a swiss army knife for handling a variety of small tasks. It accepts a script to execute via its Script input and the rest of the operation's inputs are made available to that script as variables. In addition, any number of script variables can be provided back out to the operation's outputs in addition to the result of the script (discussed below). The operation is frequently used to do things like:

  • Construct a file name or path
  • Implement switching logic to provide some result(s) based on a set of inputs
  • String handling
  • Print some information
  • Test some condition and halt execution if it fails to meet certain criteria

Configuring Named Inputs and Outputs

The names and number of the inputs and outputs are configured from the properties dialog for the operation under the "Script inputs/outputs" tab:

Configuring inputs and outputs

The inputs and outputs can also be re-ordered simply by dragging them up or down. There are some restrictions on what are considered valid names for inputs and outputs. The basic guideline is that the names must all be suitable variable names, plus a few other restrictions. The following guidelines summarize the constraints on valid names:

  • They must not contain spaces
  • They must start with a letter
  • They may only contain letters, numbers and underscores
  • The same name should not be used for both an input and an output
  • A name cannot be repeated
  • Inputs cannot have the name Dependencies or Parameters since these are already present for the operation.
  • Outputs cannot have the name Dependencies or Result since these are already present for the operation.
  • Input/output names and script variable names are case sensitive.

Scripts

The scripting language, QtScript, is an implementation of ECMAScript. Many people are familiar with Javascript and this too is based on ECMAScript. In fact, QtScript and Javascript are very similar, so if you are used to JavaScript, QtScript should be relatively easy to work with. QtScript provides some additional functionality to support Qt-specific classes and features, such as signals and slots, some specific Qt data types, etc. Generally though, most users will find that they only need the basic and familiar Javascript-like features of the language. The rest of this tutorial will use the 5th edition of the ECMAScript language when referring to specific sections of that standard. This document can be readily obtained online.

One way to learn QtScript is to simply try it out with a few examples. The following is an extremely simple sample script that could be used with the named inputs and outputs configured above:

result = Math.pow(a, b);
print(result);
Enter the script and give inputs values

The goal of this sample is not to teach you QtScript but rather to show how easy it is to add your own functionality and connect it into a workflow. Here we are reading inputs, setting an output and even writng to the Log window in only a couple of lines of code. See the Performing calculations (with QtScript) tutorial for a more complete example.

QVariant and Conversions

All of the inputs to the operation have the data type QVariant. This is Qt's generic data type used to hold a variety of different types along with some provision for automatically converting between some of those types. The Workspace framework augments Qt's type system by automatically adding each Workspace data type to Qt's meta type system where possible. Those types for which QVariant has direct support (eg bool, int, double, QString, QStringList, QRegExp and others), RunQtScript will directly convert them into their QtScript equivalents. The list of conversions more or less follows those described in the Qt documentation. As a special case, ObjectGroup subclasses are handled slightly differently. They are transformed into a property hierarchy, which can be accessed using the property names in a very convenient syntax within the script.

Advanced Usage

The QtScript language possesses some quite powerful functionality, particularly when you want to work with QObject classes, signals/slots, etc. These features are fully discussed in the Qt documentation, so the interested reader is directed there for further details.