The editor: selection, tools, preferences and actions
What only the window holds, and the views and actions a script can add.
Some things only the editor window knows: what is selected, where the playhead is, which colour is in use, how a tool is set. A script reads and changes them as you would with the panels. None of these calls is an undo step of its own. Edits to the scene still go through buhayin.edit.
A script run from the command line has no window, so every call on this page throws NO_EDITOR there.
Selection
buhayin.selection()
await buhayin.selection()
await buhayin.selection.set({ cells: { layers, from, to } })
await buhayin.selection.set({ marks: "all" })
await buhayin.selection.clear()What is selected now: the frame, the layer, the cells, keys and marks that are picked and, in a storyboard, the labels of the panels picked or under the playhead as panels. set selects cells on the named layers between two frames, or all marks. clear selects nothing.
const selection = await buhayin.selection()
const names = selection.cells ? selection.cells.layers : []
print(names.length + " layers selected")The playhead
buhayin.playhead()
await buhayin.playhead()
await buhayin.playhead.set(frame)The frame the playhead is on, and moving it. Frames count from 1.
Colour
buhayin.palette.current()
await buhayin.palette.current()
await buhayin.palette.setColour({ name })The palette shown in the Colour view and the colour in use. setColour makes a colour of the palette shown the colour in use, by its name.
Tools
buhayin.tools
await buhayin.tools.getToolSettings(tool?)
await buhayin.tools.setToolSettings({ tool?, values })
await buhayin.tools.presets(tool?)
await buhayin.tools.applyPreset(tool, name)getToolSettings reads a tool's options and setToolSettings sets them. The whole values object is checked before any option is set. presets lists the saved tool presets, each as { tool, name }, and applyPreset applies one by name.
const presets = await buhayin.tools.presets()
for (const preset of presets) print(preset.tool, preset.name)Preferences
buhayin.preferences
await buhayin.preferences.getBool(name, fallback)
await buhayin.preferences.setBool(name, value)
await buhayin.preferences.getDouble(name, fallback)
await buhayin.preferences.setDouble(name, value)
await buhayin.preferences.getInt(name, fallback)
await buhayin.preferences.setInt(name, value)
await buhayin.preferences.getEnumValue(name, fallback)
await buhayin.preferences.setEnumValue(name, value)
await buhayin.preferences.getColor(name, fallback)
await buhayin.preferences.setColor(name, value)A script can reach eleven preferences, by name. A read of any other name gives fallback. A write to any other name throws.
| Name | Kind | What it is |
|---|---|---|
RIPPLE_SCENE_MARKERS | switch | Insert and delete frames move the scene markers. |
EXTEND_DRAWING_EXPOSURE | switch | The Timeline's Extend drawing exposure setting. |
TIMELINE_CREATE_KEY_EXPOSURE | switch | The Timeline's Create key exposure setting. |
TIMELINE_SHOW_SOUND | switch | Sound is shown in the Timeline. |
CreateSymbolUnderElement | switch | Layers made by Distribute to Layers go under the current one. |
DRAWING_LIGHTTABLE_ENABLE_SHADE | switch | The light table is shaded. |
PLAY_ENABLE_SCRUBBING | switch | Sound plays as you scrub. |
DRAWING_LIGHTTABLE_OPACITY | number | The light table's opacity. |
DRAWING_LIGHTTABLE_WASH | number | The light table's wash. |
DRAWING_VIEW_THUMBNAILS_LOCATION | whole number | The location of the Drawing view's thumbnails. |
TIMELINE_LAST_NOTE_COLOUR | colour | The last note colour. |
A switch is true or false. A colour is { r, g, b } with each from 0 to 255. Use the call that matches the kind: getBool and setBool for a switch, getDouble for a number, getInt or getEnumValue for a whole number, getColor for a colour.
const on = await buhayin.preferences.getBool("PLAY_ENABLE_SCRUBBING", false)
await buhayin.preferences.setBool("PLAY_ENABLE_SCRUBBING", !on)Editor commands
Action
await Action.perform(id, responder?, args?)
await Action.performForEach(id, responder?)
await Action.validate(id, responder?)
await Action.getActionList(responder?)
await Action.getResponderList()Run any of the editor's commands. id is the command's slot, such as onActionChooseBrushTool() (the brackets are optional), the id of a shortcuts file, or Buhayin's own name for it. responder names the view that should handle it, such as drawingView, timelineView or sceneUI, and several go in one string split by commas. With none, the first that handles it does.
performruns the command once while it is enabled.performForEachanswers 1 when it ran and 0 when not.validategives{ isValid, enabled, checked }.getActionListgives the slots, andgetResponderListthe responder names.- A name that matches nothing does nothing and gives
falseor 0.
await Action.perform("onActionChooseBrushTool()")Waiting for a command does not count against the script's time.
Views and commands a script adds
A file ending in .view.js in the scripts folder is run when the editor starts. The folder is Buhayin's application data folder or the folder beside a scene file. A file there can define a view, commands, or both.
buhayin.actions.add(definition)
await buhayin.actions.add({ id, text, entryPoint, shortcut?, menu?, toolbar? })Adds a command to a menu. entryPoint is the name of a function in the file. Running the command runs the file again and calls entryPoint(id).
shortcutis a key sequence of up to 40 letters, or empty for none. A key another command already has is not taken.menuis the menu's title. It defaults toScripts, and a menu with that title is made before Help if there is none.toolbar: truealso puts the command on the editor bar.- A file may register up to 50 commands.
await buhayin.actions.add({ id: "tidy", text: "Tidy layers", entryPoint: "tidy" })
async function tidy(id) {
print("Running " + id)
}buhayin.views.add(definition)
await buhayin.views.add({ id, title, entryPoint, controls })Adds a view of controls, shown among the editor's views. controls holds up to 50 controls of the kinds label, button, number and text. A number is kept inside its min and max. Ids, titles and control text are at most 200 letters. A file may define up to 20 views.
Pressing a button runs the file again and calls entryPoint(controlId, values). values holds each number and text control's value by its id. The last line the function prints, or its failure, is shown in a notice.