| sidebar_position | 4 |
|---|
Host.GUI provides command execution, dialog management, clipboard, theme, desktop window, and help tutorial services.
| Property | Type | Writable | Example | Description |
|---|---|---|---|---|
Clipboard |
object |
No | Host.GUI.Clipboard.setText(text) |
Text clipboard read/write |
Commands |
object |
No | Host.GUI.Commands.interpretCommand(...) |
Command execution, discovery, and management |
Constants |
object |
No | Host.GUI.Constants.kYes |
Mouse button, modifier, dialog, and alert constants |
Desktop |
object |
No | Host.GUI.Desktop.closeTopModal() |
Desktop window and modal management |
Help |
object |
No | Host.GUI.Help.showLocation("Console") |
Reference manual navigation and UI focus effects |
Themes |
object |
No | Host.GUI.Themes.getTheme(pkgID) |
Theme/skin retrieval for dialogs |
| Method | Returns | Parameters | Description |
|---|---|---|---|
Host.GUI.alert(msg) |
— | msg — any value (auto-stringified) |
Show a modal alert dialog |
Host.GUI.ask(msg) |
— | msg — question string |
Show a Yes/No dialog; compare result to Host.GUI.Constants.kYes |
Host.GUI.keyStateToString(mask) |
string |
mask — modifier key bitmask |
Format modifier keys for display (e.g. "Command+Shift") |
Host.GUI.openUrl(url) |
— | url — Host.Url path |
Open a local file or URL in the host |
Host.GUI.runDialog(theme, formName, controller) |
— | theme — theme object, formName — form name, controller — controller object |
Open a skin.xml dialog (blocking) |
Host.GUI.runDialogWithParameters(params, title) |
— | params — param list, title — dialog title |
Open a parameter dialog with a param list |
Host.GUI.showFile(url) |
— | url — Host.Url path |
Reveal a file in the host |
Host.GUI.Clipboard provides simple text clipboard access.
| Method | Returns | Parameters | Description |
|---|---|---|---|
Host.GUI.Clipboard.getText() |
string |
none | Get clipboard text |
Host.GUI.Clipboard.setText(text) |
— | text — string to copy |
Set clipboard text |
Host.GUI.Commands provides command execution, deferred execution, and command discovery helpers.
| Method | Returns | Parameters | Description |
|---|---|---|---|
Host.GUI.Commands.assignKey(command, key) |
— | command — command object, key — key string |
Assign a keyboard shortcut to a command |
Host.GUI.Commands.beginTransaction(title) |
— | title — transaction label |
Start a command transaction for batching |
Host.GUI.Commands.deferCommand(category, name) |
— | category — command category, name — command name |
Defer a host command for sequenced execution |
Host.GUI.Commands.endTransaction() |
— | none | End a command transaction |
Host.GUI.Commands.findCommand(cat, name) |
object |
cat — category, name — command name |
Find a command object (.name, .classID) |
Host.GUI.Commands.interpretCommand(category, name) |
— | category — command category, name — command name |
Execute a host command |
Host.GUI.Commands.interpretCommand(category, name, clearSelection, attrs) |
— | clearSelection — 0/1, attrs — Host.Attributes(...) object |
Execute with optional selection clear and attributes |
Host.GUI.Commands.lookupBindings(command) |
object |
command — command object |
Look up keyboard bindings for a command |
Host.GUI.Commands.lookupKeyEvent(command) |
— | command — command object |
Look up the key event for a command |
Host.GUI.Commands.newCategoryIterator() |
object |
none | Create iterator over all categories |
Host.GUI.Commands.newCommandIterator() |
object |
none | Create iterator over all commands |
Host.GUI.Commands.registerCommand(category, name, group, title, englishName) |
— | category — category, name — command name, group — group name, title — display title, englishName — English name |
Register a new command |
Host.GUI.Commands.unregisterCommand(category, name) |
— | category — command category, name — command name |
Unregister a previously registered command |
See Command Reference for full command reference.
findCommand(category, name) returns a command object with at least classID and name. The resolved classID can be passed back into interpretCommand(...).
Attribute Example:
var attrs = Host.Attributes([
"Length", "0.02",
"Type", "Linear",
"Bend", "0"
]);
Host.GUI.Commands.interpretCommand("Audio", "Create Crossfades", false, attrs);Create Crossfades accepts Length, Type, and Bend attributes.
Host.GUI.Constants provides modifier key constants and dialog result codes. Modifier key values are bitwise constants — combine with | (e.g. kShift | kCommand = 24). Compound masks produce joined names in keyStateToString (e.g. "Command+Shift").
| Constant | Value | Category |
|---|---|---|
kShift |
8 | Modifier key |
kCommand |
16 | Modifier key |
kOption |
32 | Modifier key |
kControl |
64 | Modifier key |
kCancel |
0 | Dialog result |
kOkay |
1 | Dialog result |
kClose |
2 | Dialog result |
kApply |
3 | Dialog result |
kYes |
0 | Alert result |
kNo |
1 | Alert result |
kAlertCancel |
2 | Alert result |
kOk |
3 | Alert result |
kRetry |
4 | Alert result |
Host.GUI.Desktop provides desktop window and modal management.
| Method | Returns | Parameters | Description |
|---|---|---|---|
Host.GUI.Desktop.closeModalWindows() |
— | none | Close all open modal dialogs |
Host.GUI.Desktop.closeTopModal() |
— | none | Close the topmost modal dialog |
Host.GUI.Desktop.getApplicationWindow() |
object |
none | Get the application window object |
Host.GUI.Help provides window dimming and UI control highlighting for focus effects. HelpIDs can reference both native UI elements and custom controls in third-party dialogs (via <HelpAnchor helpid="..."> or <Form helpid="..."> in skin.xml).
| Method | Returns | Parameters | Description |
|---|---|---|---|
Host.GUI.Help.dimAllWindows() |
— | none | Dim background windows |
Host.GUI.Help.discardHighlights() |
— | none | Remove all active highlights and restore dimmed windows |
Host.GUI.Help.highlightControl(helpID) |
— | helpID — control identifier string |
Highlight a UI control by its HelpID (e.g. "Console", "Arrangement", "Inspector") |
Host.GUI.Help.modifyHighlights() |
— | none | — |
Host.GUI.Help.showLocation() |
— | none | Open the Studio Pro Reference Manual |
helpID:
Controls are referenced by helpID string constants. See HelpID for the full list of recognized constants.
Custom helpID:
Custom helpID's can be defined in third-party skin.xml files via <HelpAnchor helpid="..."> wrapping a control or <Form helpid="..."> on a form for the entire dialog window. Use with highlightControl() to highlight the specified control while the display is dimmed.
Host.GUI.Themes provides theme retrieval for dialog rendering and skin resource access. The returned theme object is passed to Host.GUI.runDialog().
| Method | Returns | Parameters | Description |
|---|---|---|---|
Host.GUI.Themes.getTheme(packageID) |
object |
packageID — Package:ID from metainfo.xml |
Get a theme object for a package's skin |
Host.GUI.Themes.loadTheme(packageID) |
object |
packageID — package identifier string |
Load a theme object |
Theme object:
| Method | Returns | Parameters | Description |
|---|---|---|---|
theme.getImage(name) |
object |
name — image resource name |
Get a named image from the skin's resources |
Example:
var theme = Host.GUI.Themes.getTheme(kPackageID);
Host.GUI.runDialog(theme, "MyForm", this);Host.GUI.alert() provides a modal alert dialog.
Host.GUI.alert(msg) // Auto-stringifies any valueHost.GUI.ask() provides a Yes/No modal dialog.
var result = Host.GUI.ask(msg);
if (result === Host.GUI.Constants.kYes) { /* yes */ }Host.GUI.keyStateToString() formats modifier-key masks for display. Compound masks produce joined names (e.g. "Command+Shift"). Modifier key values are defined in Host.GUI.Constants.
// Modifier key values: kShift=8, kCommand=16, kOption=32, kControl=64
Host.GUI.keyStateToString(8) // "Shift"
Host.GUI.keyStateToString(24) // "Command+Shift"
Host.GUI.keyStateToString(255) // "Command+Shift+Option+Control"Host.GUI.openUrl() opens a local file or URL in the host. Accepts a Host.Url object.
var targetPath = Host.Url("local://$USERCONTENT/your-file.txt");
Host.GUI.openUrl(targetPath);Host.GUI.runDialog() opens a skin.xml dialog (blocking). Requires Package:SkinFile in metainfo.xml.
var theme = Host.GUI.Themes.getTheme(packageID);
var result = Host.GUI.runDialog(theme, "FormName", controller);Host.GUI.runDialogWithParameters() opens a parameter dialog with a CCL:ParamList object. Returns a dialog result constant.
var params = Host.Classes.createInstance("CCL:ParamList");
var result = Host.GUI.runDialogWithParameters(params, "Dialog Title");Host.GUI.showFile() reveals a file in the host or system file browser. Accepts a Host.Url object.
var path = Host.Url("local://$USERCONTENT/folder/");
Host.GUI.showFile(path);