Harmony Scripting Interface

Introduction

The scripting interface in Harmony uses Qt Script to provide an efficient way to program tools and macros that can, among other things, be used to manipulate scenes and automate tasks.

Scripts can be launched from a button in the Scripting toolbar, from the Script Editor, the Script Node, the Master Controller Node as well as from a command line terminal.

Qt Script is based on the ECMAScript 3.0 standard. EMCAScript can be considered an extension of JavaScript. JavaScript documentation is widely available on the internet. The first 11 chapters (Part 1) of the book Eloquent JavaScript by Marijn Haverbeke which can be read online for free at http://eloquentjavascript.net/ are a great introduction to the subject.

Note
As of Harmony 10.1:
  • The Qt UI scripting interface is included with the Harmony scripting interface, allowing the construction of complex UI objects (i.e. Dialogs with comboboxes, text edits, etc.) through scripting. The documentation for this interface can be found at http://qt-project.org/doc/qt-4.8/index.html.
  • Scripts referencing other scripts in different files must now use the JavaScript include method:
    include( "TB_orderNetworkUtils.js" )
Previous releases of Harmony were using QSA script, which was based on a hybrid of the ECMAScript 3.0 and 4.0 standards. While the languages are similar, there are a few differences. See http://qt-project.org/doc/qt-4.8/porting-qsa.html for further details.

Getting Started

Start by opening the Script Editor view. Then, select Sandbox from the scripts list. The sandbox is provided as a means to test out scripts without having to create or modify a script file. For example, try typing the following script:

// This will create a message box with the Hello World text in it.
MessageBox.information("Hello World");
// Print to the Message Log view the number of nodes at the root of the scene.
var nbNodes = node.numberOfSubNodes(node.root());
MessageLog.trace(nbNodes);

Then, click on the Run button in the Script Editor toolbar, or open the Script Editor menu from the top-left corner and select Play/Debug > Run.

Note
Refer to the Harmony documentation for instructions on how to use the Script Editor, and how to assign scripts to buttons in the toolbars.

Batch Mode

You can run a script on a Storyboard Pro project from the terminal, without opening Storyboard Pro first. This is referred to as running a script in batch mode. With the exception of the SelectionManager interface, all classes that are available in the Storyboard Pro scripting interface can be used in batch mode.

You can run a script in Harmony from a command line by using the following syntax:

  • In standalone mode:
    Harmony<Edition> /pathToProject/ProjectFile.xstage -batch -compile /pathToJavaScriptFile/javaScriptFile.js
  • In database mode:
    Harmony<Edition> -env EnvironmentName -job JobName -scene SceneName -user UserName -batch -compile /pathToJavaScriptFile/javaScriptFile.js