tb-harmony-modern-ts/README.md

tb-harmony-modern-ts

This repository is a project template that allows you to code in modern TypeScript for ToonBoom Harmony.

Example script

function* recursiveIterNodes(n: string): Generator<string> {
  yield n;
  if (node.isGroup(n)) {
    for (let i = 0; i < node.numberOfSubNodes(n); i++) {
      yield* recursiveIterNodes(node.subNode(n, i));
    }
  }
}

function main() {
  const nodes = Array.from(recursiveIterNodes(node.root()));

  for (const node of nodes) {
    console.log(node);
  }
}

main();

Why

You can script in two ways for ToonBoom Harmony: either with Python or QtScript (JavaScript).

QtScript (scripting engine part of the Qt framework) is an old JavaScript dialect that is based on the ECMAScript 3.0 standard, therefore it lacks features like modules, modern syntax, arrow functions, etc...

Today we have TypeScript which is a superset of JavaScript with syntax for types, ES modules, async/await and more but how can we use those?

How

TypeScript and type definitions

We can code in TypeScript but in order to use Harmony's QtScript API, we need type definitions (.d.ts files describing the types).

Luckily for us, Bryan Fordney made scripts to generate them: tba-types (Typescript definitions for Toon Boom Harmony and Storyboard Pro)

Modules and imports

In Harmony's QtScript you can import code from another file in two ways:

include

include("module.js");

Which include the whole script into the current one, therefore polluting the current namespace.

exports

// function.js
exports.test = function test() {
  MessageLog.trace("test");
};

// main.js
var module = require("./function.js");
module.test();

Which is a CommonJS "like" custom implementation from ToonBoom without the same semantics. It's also used to define ToonBoom packages by exporting a configure function from a configure.js file.

-> In today's modern JavaScript, the official standard package format is ECMAScript modules (or ESM/ES6 modules) with import/export.