@theatre/studio


import studio from '@theatre/studio'

studio.initializefn

Initializes the studio. Call it once in your index.js/index.ts module. It silently ignores subsequent calls.

studio.transactionfn

Runs an undo-able transaction. Creates a single undo level for all the operations inside the transaction.

Will roll back if an error is thrown.


studio.transaction(({ set, unset }) => {
set(obj.props.x, 10) // set the value of obj.props.x to 10
unset(obj.props.y) // unset the override at obj.props.y
})

api.setfn

Set the value of a prop by its pointer. If the prop is sequenced, the value will be a keyframe at the current sequence position.


const obj = sheet.object('box', { x: 0, y: 0 })
studio.transaction(({ set }) => {
// set a specific prop's value
set(obj.props.x, 10) // New value is {x: 10, y: 0}
// values are set partially
set(obj.props, { y: 11 }) // New value is {x: 10, y: 11}
// this throw an error, as there is no such prop as 'z'
set(obj.props.z, 10)
})

api.unsetfn

Unsets the value of a prop by its pointer.


const obj = sheet.object('box', { x: 0, y: 0 })
studio.transaction(({ set }) => {
// set props.x to its default value
unset(obj.props.x)
// set all props to their default value
set(obj.props)
})

studio.scrubfn

Creates a scrub, which is just like a transaction, except you can run it multiple times without creating extra undo levels.


const scrub = studio.scrub()
scrub.capture(({ set }) => {
set(obj.props.x, 10) // set the value of obj.props.x to 10
})
// half a second later...
scrub.capture(({ set }) => {
set(obj.props.y, 11) // set the value of obj.props.y to 11
// note that since we're not setting obj.props.x, its value reverts back to its old value (ie. not 10)
})
// then either:
scrub.commit() // commits the scrub and creates a single undo level
// or:
scrub.reset() // clears all the ops in the scrub so we can run scrub.capture() again
// or:
scrub.discard() // clears the ops and destroys it (ie. can't call scrub.capture() anymore)

studio.extendfn

Registers an extension. Extensions enable you to extend the Studio's UI and/or extend the functionality of Studio. Read more about working with extensions in the "Authoring extensions" manual.


import { extension } from './myExtension'
studio.extend(extension)

studio.createContentOfSaveFilefn

Creates a JSON object that contains the state of the project. You can use this to programmatically save the state of your projects to the storage system of your choice, rather than manually clicking on the "Export" button in the UI.


const projectId = 'project'
const json = studio.createContentOfSaveFile(projectId)
const string = JSON.stringify(json)
fetch(`/projects/${projectId}/state`, { method: 'POST', body: string }).then(() => {
console.log('Saved')
})

studio.createPanefn

Creates a new pane. Takes a string as its argument specifying a pane class previously registered by an extension.


studio.createPane('snapshot')

studio.getStudioProjectfn

Returns the Theatre.js project that contains the studio's sheets and objects.

It is useful if you'd like to have sheets/objects that are present only when the studio is present.

studio.selection

The current selection, consisting of sheets and sheet objects.


console.log(studio.selection) // [ISheetObject, ISheet]

studio.onSelectionChangefn

Let's you subscribe to selection changes. Calls the provided callback with the current selection every time the selection changes.


return studio.onSelectionChange((newSelection) => {
console.log(newSelection) // [ISheetObject, ISheet]
})

studio.setSelectionfn

Sets the current selection.


studio.setSelection([someSheet, someObject])

studio.ui

Exposes utilities to manipulate the Studio UI.

studio.ui.hidefn

Hides the Studio.


studio.ui.hide()

studio.ui.restorefn

Shows the Studio.


studio.ui.restore()

studio.ui.isHidden

true if Studio is hidden currently.


if (studio.ui.isHidden) {
// Do something
}

studio.ui.renderToolsetfn

Let's you render a toolset previously defined by an extension into a dom node of your choice.


studio.ui.renderToolset('my-toolbar', toolbarContainerNode)


Was this article helpful to you?

Last edited on September 29, 2022.
Edit this page

Theatre.js
Theatre.js is a design tool in the making. We aim to blur the line between designer/developer, author/consumer, and artist/scientist.
© 2022 Theatre.js Oy – Helsinki.