74 lines
2.6 KiB
Markdown
74 lines
2.6 KiB
Markdown
# tb-harmony-modern-ts
|
|
|
|
This repository is a project template that allows you to code in modern TypeScript for ToonBoom Harmony.
|
|
|
|
## Example script
|
|
|
|
```ts
|
|
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](https://docs.toonboom.com/help/harmony-24/scripting/pythonmodule/index.html) or [QtScript](https://docs.toonboom.com/help/harmony-24/scripting/script/index.html) (JavaScript).
|
|
|
|
[QtScript](https://doc.qt.io/archives/qt-5.15/qtscript-index.html) (scripting engine part of the Qt framework) is an old JavaScript dialect that is based on the [ECMAScript 3.0 standard](https://www-archive.mozilla.org/js/language/e262-3.pdf), therefore it lacks features like modules, modern syntax, arrow functions, etc...
|
|
|
|
Today we have [TypeScript](https://www.typescriptlang.org/) 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](https://github.com/bryab/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`
|
|
|
|
```js
|
|
include("module.js");
|
|
```
|
|
|
|
Which include the whole script into the current one, therefore polluting the current namespace.
|
|
|
|
#### `exports`
|
|
|
|
```js
|
|
// function.js
|
|
exports.test = function test() {
|
|
MessageLog.trace("test");
|
|
};
|
|
```
|
|
|
|
```js
|
|
// main.js
|
|
var module = require("./function.js");
|
|
module.test();
|
|
```
|
|
|
|
Which is a [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules) "like" custom implementation from ToonBoom without the same semantics. It's also used to define [ToonBoom packages](https://docs.toonboom.com/help/harmony-24/scripting/extended/index.html#create_package) by exporting a `configure` function from a `configure.js` file.
|
|
|
|
-> In today's modern JavaScript, the official standard package format is [ECMAScript modules](https://nodejs.org/api/esm.html#modules-ecmascript-modules) (or ESM/ES6 modules) with `import`/`export`.
|