Skip to content

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.

NameKindWhat it is
RIPPLE_SCENE_MARKERSswitchInsert and delete frames move the scene markers.
EXTEND_DRAWING_EXPOSUREswitchThe Timeline's Extend drawing exposure setting.
TIMELINE_CREATE_KEY_EXPOSUREswitchThe Timeline's Create key exposure setting.
TIMELINE_SHOW_SOUNDswitchSound is shown in the Timeline.
CreateSymbolUnderElementswitchLayers made by Distribute to Layers go under the current one.
DRAWING_LIGHTTABLE_ENABLE_SHADEswitchThe light table is shaded.
PLAY_ENABLE_SCRUBBINGswitchSound plays as you scrub.
DRAWING_LIGHTTABLE_OPACITYnumberThe light table's opacity.
DRAWING_LIGHTTABLE_WASHnumberThe light table's wash.
DRAWING_VIEW_THUMBNAILS_LOCATIONwhole numberThe location of the Drawing view's thumbnails.
TIMELINE_LAST_NOTE_COLOURcolourThe 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.

  • perform runs the command once while it is enabled. performForEach answers 1 when it ran and 0 when not.
  • validate gives { isValid, enabled, checked }.
  • getActionList gives the slots, and getResponderList the responder names.
  • A name that matches nothing does nothing and gives false or 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).

  • shortcut is a key sequence of up to 40 letters, or empty for none. A key another command already has is not taken.
  • menu is the menu's title. It defaults to Scripts, and a menu with that title is made before Help if there is none.
  • toolbar: true also 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.