Skip to content

Commit db4d614

Browse files
CSourcesCSources
committed
Added Marker Creator Script, Script Types Documentation, Various Corrections
- Added a Marker Creator script package and source. - Added Script Types section with documentation on different script types. - Corrected various errors in documentation. - Added additional information to various sections.
1 parent 3317e79 commit db4d614

30 files changed

Lines changed: 1301 additions & 105 deletions

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
| Section | Description |
1414
|---|---|
1515
| [Package Structure](docs/package_structure/package_structure.md) | Required files, metainfo.xml, classfactory.xml |
16-
| [Script Interface](docs/script_interface.md) | Task lifecycle, factory functions, include_file |
16+
| [Script Types](script_types/script_interfaces.md) | Category reference and registration patterns |
1717
| [Host API](docs/host/host_overview.md) | Host namespace — Classes, Engine, GUI, IO, Signals, etc. |
1818
| [SDK Files](docs/sdk/sdk_files.md) | CCL.JS, Engine.JS, Devices.JS, HostUtils, etc. |
1919
| [Context Object](docs/context/context_object.md) | editor, functions, iterator, parameters, track list |

‎docs/api_index.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,15 @@
1010
| [Resources](package_structure/resources.md) | Runtime resource access via `package://` |
1111
| [Installation](package_structure/installation.md) | Scripts folder locations and hot-reloading |
1212
| [Creating a .package File](package_structure/package_creation.md) | Zip-based packaging for distribution |
13-
| [Script Interface](script_interface.md) | Task lifecycle, execution phases, factory functions |
13+
14+
## Script Types
15+
16+
| Page | Description |
17+
|---|---|
18+
| [Script Interfaces](script_types/script_interfaces.md) | Category reference |
19+
| [EditTask](script_types/edittask.md) | Command/action scripts with optional dialog |
20+
| [EditAddIn](script_types/editaddin.md) | Persistent add-in panels |
21+
| [WindowClass](script_types/windowclass.md) | Non-blocking workspace windows via FrameworkService |
1422

1523
## Host API
1624

‎docs/host/gui.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ sidebar_position: 4
2626
| `Host.GUI.openUrl(url)` | — | `url` — `Host.Url` path | Open a local file or URL in the host |
2727
| `Host.GUI.runDialog(theme, formName, controller)` | — | `theme` — theme object, `formName` — form name, `controller` — controller object | Open a skin.xml dialog (blocking) |
2828
| `Host.GUI.runDialogWithParameters(params, title)` | — | `params` — param list, `title` — dialog title | Open a parameter dialog with a param list |
29-
| `Host.GUI.showFile(url)` | — | `url` — `Host.Url` path | Reveal a file in the host |
29+
| `Host.GUI.showFile(url)` | `number` | `url` — `Host.Url` path | Reveal a file or folder in the system file manager. Returns `0` on success |
3030

3131
## Clipboard
3232

@@ -205,7 +205,7 @@ var result = Host.GUI.runDialogWithParameters(params, "Dialog Title");
205205

206206
## showFile
207207

208-
`Host.GUI.showFile()` reveals a file in the host or system file browser. Accepts a `Host.Url` object.
208+
`Host.GUI.showFile()` reveals a file or folder in the system file manager. Accepts a `Host.Url` object. For a file, it reveals the parent folder with the file selected. For a directory, it opens the folder. Returns `0` on success.
209209

210210
```javascript
211211
var path = Host.Url("local://$USERCONTENT/folder/");

‎docs/overview.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ This is not a complete reference. There is plenty of missing, improperly structu
1111
| Section | Description |
1212
|---|---|
1313
| [Package Structure](package_structure/package_structure.md) | Required files, metainfo.xml, classfactory.xml |
14-
| [Script Interface](script_interface.md) | Task lifecycle, factory functions, include_file |
14+
| [Script Types](script_types/script_interfaces.md) | Category reference and registration patterns |
1515
| [Host API](host/host_overview.md) | Host namespace — Classes, Engine, GUI, IO, Signals, etc. |
1616
| [SDK Files](sdk/sdk_files.md) | CCL.JS, Engine.JS, Devices.JS, HostUtils, etc. |
1717
| [Context Object](context/context_object.md) | editor, functions, iterator, parameters, track list |

‎docs/package_structure/classfactory.md‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ Script registration, entry points, and attributes.
7373
| `"FrameworkService"` | Host-managed service surface, not shown in menus |
7474
| `"Gadget"` | - |
7575

76-
See [docs/script_interface.md](../script_interface.md) for the interface and lifecycle associated with each category.
76+
See [Script Interfaces](../script_types/script_interfaces.md) for the minimal interface and lifecycle associated with documented categories.
7777

7878
## subCategory values
7979

@@ -128,7 +128,7 @@ See [docs/script_interface.md](../script_interface.md) for the interface and lif
128128

129129
**Icon binding (toolbar buttons and menu items):**
130130

131-
For `EditAddIn` toolbar buttons, the script class uses `subCategory="Engine"` with `groupName` for panel location. For `EditTask` menu items, use `menuGroup` for menu categorization.
131+
For `EditAddIn` toolbar buttons, the script class uses an addin specific `subCategory` (`"Engine"`, `"Project"`, `"Show"`) with `groupName` for panel location. For `EditTask` menu items, use `menuGroup` for menu categorization.
132132

133133
The image is declared in `skin.xml` as an `<Image>` and referenced from `classfactory.xml` with `theme://$package/...`.
134134

@@ -145,6 +145,23 @@ The image is declared in `skin.xml` as an `<Image>` and referenced from `classfa
145145
</ScriptMetaClass>
146146
```
147147

148-
## Multiple commands from one JS file
148+
## Multiple Scripts from One JS File
149149

150-
See [docs/script_interface.md](../script_interface.md) for the pattern of exporting multiple factory functions from a single JS file.
150+
A single JavaScript file can export multiple factory functions, each registered as a separate `<ScriptClass>` entry in `classfactory.xml`.
151+
152+
```xml
153+
<classfactory.xml>
154+
<ScriptClass name="Remove Empty Tracks"
155+
sourceFile="code.js"
156+
functionName="removeEmpty"/>
157+
158+
<ScriptClass name="Remove Disabled Tracks"
159+
sourceFile="code.js"
160+
functionName="removeDisabled"/>
161+
```
162+
163+
```javascript
164+
// code.js
165+
function removeEmpty() { return new TrackAction("removeEmptyTracks"); }
166+
function removeDisabled() { return new TrackAction("removeDisabledTracks"); }
167+
```

‎docs/package_structure/package_structure.md‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,4 +35,15 @@ your-script.package (ZIP)
3535

3636
For multi-script packages, the package root uses the same structure. Each `<ScriptClass>` needs a unique `classID`, and `functionName` only needs to name the factory function inside that entry's `sourceFile`. Multiple entries may point at the same `sourceFile` when one JavaScript file exports several factory functions. Shared dialog definitions live in one `skin.xml`, with one `<Form>` per script when dialogs are used.
3737

38-
See [Examples - Multi-Script Demo](../scripts/multi-script-demo.md) for a working example.
38+
See [Examples - Multi-Script Demo](../scripts/multi-script-demo.md) for a working example.
39+
40+
## Including Other JS Files
41+
42+
Include helper JavaScript files from the package root or known resource paths.
43+
44+
```javascript
45+
include_file('helper.js');
46+
include_file('constants.js');
47+
```
48+
49+
See [SDK Files](sdk/sdk_files.md) for list of bundled files.

‎docs/script_interface.md‎

Lines changed: 0 additions & 87 deletions
This file was deleted.

‎docs/script_types/editaddin.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
# EditAddIn
5+
6+
An `EditAddIn` panel is a persistent, non-blocking UI strip that's auto-docked in Studio Pro's panel area, beneath the main or editor surface toolbar. Its open/closed state persists in saved files.
7+
8+
## How It Connects
9+
10+
1. **`classfactory.xml`** — declares the script as `category="EditAddIn"` with `subCategory` matching the intended context and `groupName` for panel location.
11+
2. **`skin/skin.xml`** — a `<Form>` defines the panel controls, referenced by the `formName` attribute.
12+
3. **`scriptname.js`** — implements `IComponent` with `initialize()` and `terminate()` callbacks.
13+
14+
## classfactory.xml
15+
16+
```xml
17+
<ScriptClass
18+
classID="{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}"
19+
metaClassID="{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}"
20+
category="EditAddIn"
21+
subCategory="Engine"
22+
name="My Panel"
23+
sourceFile="main.js"
24+
functionName="createInstance">
25+
<Attribute id="groupName" value="Song.AddInPanel"/>
26+
<Attribute id="formName" value="MyPanelForm"/>
27+
</ScriptClass>
28+
29+
<ScriptMetaClass classID="{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}">
30+
<ScriptClassResource id="Class:ImageResource" url="theme://$package/ToolbarIcon"/>
31+
</ScriptMetaClass>
32+
```
33+
34+
- `subCategory` specifies the Studio Pro environment context: `Engine` (Song), `Project`, `Show`.
35+
- `groupName` controls docking location. Values: `"Song.AddInPanel"`, `"Project.AddInPanel"`, `"Show.AddInPanel"`, `"MusicOnly.AddInPanel"`, `"AudioOnly.AddInPanel"`, `"SongOnly.AddInPanel"`.
36+
- `formName` references a `<Form name="MyPanelForm">` in `skin.xml`.
37+
- `metaClassID` and `ScriptMetaClass` bind an icon to the script for a toolbar button. See [classfactory.xml - ScriptMetaClass](../package_structure/classfactory.md#scriptmetaclass-icon-and-resource-binding) for icon resource details.
38+
39+
## skin.xml
40+
41+
```xml
42+
<Form name="MyPanelForm" attach="all fitsize" windowstyle="panelstyle">
43+
<!-- panel controls here -->
44+
</Form>
45+
```
46+
47+
## scriptname.js
48+
49+
```javascript
50+
function MyPanel()
51+
{
52+
this.interfaces = [
53+
Host.Interfaces.IComponent // Required for EditAddIn lifecycle
54+
]
55+
56+
this.initialize = function(context)
57+
{
58+
}
59+
60+
this.terminate = function()
61+
{
62+
}
63+
}
64+
65+
// Function name matches classfactory.xml functionName.
66+
function createInstance() {
67+
return new MyPanel()
68+
}
69+
```

‎docs/script_types/edittask.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
# EditTask
5+
6+
An `EditTask` is a command/action script that optionally collects input and performs an action. When used with `context.runDialog()` it opens a blocking dialog for collecting input before performing the action.
7+
8+
## How It Works
9+
10+
1. **`classfactory.xml`** — declares the script as `category="EditTask"` with [`subCategory`](../package_structure/classfactory.md#subcategory-values) for the target context.
11+
2. **`prepareEdit(context)`** — called first; validates state and optionally collects input. Returns `kResultOk` to proceed, or another value to cancel.
12+
3. **`performEdit(context)`** — called only if `prepareEdit` returned `kResultOk`; performs the action.
13+
14+
## classfactory.xml
15+
16+
```xml
17+
<ScriptClass
18+
classID="{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}"
19+
category="EditTask"
20+
subCategory="TrackEdit"
21+
name="My Action"
22+
sourceFile="scriptname.js"
23+
functionName="createInstance">
24+
<Attribute id="commandCategory" value="MyCategory"/>
25+
<Attribute id="menuPriority" value="0"/>
26+
</ScriptClass>
27+
```
28+
29+
## skin.xml
30+
31+
Optional for EditTask. The `<Form>` referenced by `context.runDialog()` must be defined in the package's skin:
32+
33+
```xml
34+
<Form name="MyForm" title="My Dialog" width="240" height="80">
35+
<!-- dialog controls here -->
36+
</Form>
37+
```
38+
39+
## scriptname.js
40+
41+
```javascript
42+
function MyAction()
43+
{
44+
this.interfaces = [
45+
Host.Interfaces.IEditTask // Required for EditTask lifecycle
46+
]
47+
48+
this.prepareEdit = function(context)
49+
{
50+
context.restore() // Must restore before opening dialog
51+
return context.runDialog("MyForm", "com.yourname.scriptname") // Optional — EditTask scripts can work without a dialog
52+
}
53+
54+
this.performEdit = function(context)
55+
{
56+
// Action runs here only if dialog was confirmed
57+
}
58+
}
59+
60+
// Function name matches classfactory.xml functionName
61+
function createInstance() {
62+
return new MyAction()
63+
}
64+
```
65+
66+
## Task Arguments
67+
68+
Tasks with `arguments` defined in `classfactory.xml` receive typed parameters at invocation.
69+
70+
See [context.getArguments()](../context/methods.md#get-arguments) for full reference.

‎docs/script_types/script_interfaces.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
# Script Interfaces
5+
6+
Script Interfaces define the contracts between a script and the host. Each interface (IComponent, IEditTask, etc.) corresponds to a set of lifecycle callbacks the host invokes on the script. The minimum interface required depends on the script category.
7+
8+
## Category Reference
9+
10+
The `category` attribute in `classfactory.xml` determines which interface and lifecycle the script follows.
11+
12+
| Category | Minimum Interfaces | Lifecycle Callbacks | Purpose |
13+
|---|---|---|---|
14+
| [`"EditTask"`](edittask.md) | `IEditTask` | `prepareEdit()`, `performEdit()` | Command/action script with optional dialog |
15+
| [`"EditAddIn"`](editaddin.md) | `IComponent` | `initialize()`, `terminate()` | Persistent add-in panel |
16+
| [`"FrameworkService"`](windowclass.md) | `IComponent` | `initialize()`, `terminate()` | Headless background service — auto-started at startup |
17+
18+
See [Interfaces - Callback Contracts](host/interfaces.md#callback-contracts) for the full interface and callback contract reference.

0 commit comments

Comments
 (0)