# The API

This is a reference of all the APIs available in Theatre. It's meant to complement the main guide.

# Top-level exports

Theatre is the top-level API available through import Theatre from 'theatre'. It's also a global variable if Theatre is added using a <script> tag.

# Theatre.getProject()

Returns an instance of Project:

function getProject(
  name: string, // case-sensitive. Longer than 2 characters
  config: {
    // required in core mode, optional in development mode:
    state: ProjectState
  }
): Project

Arguments:

• name: If two calls of Theatre.getProject() are given the same name, an identical Project will be returned.
• config.state is the JSON object as explained in the guide. You don't need to (but can) provide this in development mode. In core mode, this prop is mandatory.

Returns: An instance of Project

Rules of config.state:

• Assuming the name is "My project":
• If this is the first time Theatre.getProject() is called within this browser:
  • If config.state is not provided:
    • An empty state for "My project" will be created. If you then interact with the project in the UI (by creating keyframes for example), this state will be saved to the browser's storage, which currently is localStorage.
  • Else if config.state is provided:
    • The value of config.state will be saved to the browser's storage. Upon subsequent changes to the project (by editing keyframes for example), only the state in the browser's storage will change and config.state will be ignored from then on.
• Else if this is not the first time Theatre.getProject() is called within this browser:
  • The state is read from the browser's storage => config.state is ignored.

Multiple projects are allowed, identified by their names.

Learn more in the guide.

# Theatre.ui

Theatre.ui contains the UI object.

# Project

Represents a Theatre project. Returned by Theatre.getProject(). A Theatre project is analogous to a project in After Effects or Blender. The difference is that in Theatre, the project's state is persisted in the browser's storage, while in AE for example, it is saved to a file in the file system.

# project.getTimeline()

Returns an instance of Timeline.

getTimeline(timelineName: string, instanceName: string = "default"): Timeline

Arguments:

• timelineName: All timelines with the same timelineName within the project will have the same set of keyframes.
• instanceName: Timelines with the same timelineName but different instanceNames will share their keyframes, howerver, they'll have different playback states.

# project.adapters

This project's AdaptersManager, explained here.

# Timeline

A timeline. Contains Theatre objects, and a playback state.

# Timeline.getObject()

Takes a name, a native object, and optionally a TheatreObjectConfig and returns a TheatreObject:

timeline.getObject(
  name: string,
  nativeObject: unknown,
  config?: TheatreObjectConfig
): TheatreObject

Arguments:

• name of the object. If two timeline.getObject() calls have the same name, the same TheatreObject will be returned. The config of the second one will override that of the first one.
• nativeObject: Could be any value, including null. However, it is better to provide a reference to the actual native object being controlled.
• config: If an adapter can handle this native object, then config will be ignored. Otherwise, a value conforming to TheatreObjectConfig must be provided.

Returns: an instnace of TheatreObject.

Learn more at the guide.

# Timeline.time

A getter/setter for the timeline's current time in milliseconds:

// Jump to 00:00:02 (zero hours, zero minutes, two seconds)
timeline.time = 2000

// returns the current time
console.log(timeline.time)

Learn more at the guide.

# Timeline.play()

Plays the timeline. If the timeline is already playing, the playbackConfig will be overridden.

play({
  playbackConfig?: {
      // how many times to play. Defaults to 1. Can be Infinity
      iterationCount?: number
      // limit the playback to this range
      range?: {
        from: number, // in ms
        to: number // in ms
      }
      // rate of playback. Defaults to 1. If set to 1.5 for example, playback will be 1.5 times as fast
      rate?: number
      // direction of the playback, similar to that of CSS animations. Defaults to `normal`
      direction: 'normal' | 'reverse' | 'alternate' | 'alternateReverse'
    }
}): Promise<boolean>

Returns: Promise<boolean>. If the playback finishes, the boolean will be true. If it is interrupted (such as by calling timeline.pause()), then the boolean will be false.

Learn more at the guide.

# Timeline.pause()

Will pause the playback if timeline is playing.

pause(): void

Learn more at the guide.

# TheatreObjectConfig

A JS object configuring the props of a TheatreObject:

type TheatreObjectConfig = {
  props: {
    [propName: string]: PropDescriptor
  }
}

type PropDescriptor = {
  type: "number" // currently only the number type is supported. More prop types are coming.
}

This is the value required in Timeline.getObject() and Adapter.getConfig().

Learn more at the guide.

# TheatreObject

Represents a Theatre Object.

# TheatreObject.name

The name of the object, provided at timeline.getObject():

const object = timeline.getObject("My object", theDiv, config)
assert.equal(object.name, "My object")

# TheatreObject.nativeObject

A reference to the native object provided at timeline.getObject():

const theDiv = document.getElementById('the-div')
const object = timeline.getObject(objectPath, theDiv, config)
assert.equal(object.nativeObject, theDiv)

# TheatreObject.currentValues

A getter that returns an object containing the values of all the props of the object.

object.currentValues // for example: {x: 0, y: 200}

# TheatreObject.onValuesChange()

Takes a callback and calls it whenever the value of any of the props of this object have changed:

onValuesChange(callback: Callback): Unsubscribe
type Callback = (newValues: {[propKey: string]: number /* currently all props are numbers */}) => void
type Unsubscribe = () => void

newValues has the same type as TheatreObject.currentValues.

Learn more at the guide.

# AdaptersManager

Manages the adapters of the project. Detailed guide here.

# adaptersManager.add()

Takes an Adapter object and adds it to the list of recognised adapters in the project.

adapters.add(adapter: Adapter): void

# Adapter

Is a JS object that helps Theatre assign the prop types to an object and set up its onValuesChange() method. It is added to the project by calling project.adapters.add().

adapters.add(adapter: Adapter): void

type Adapter = {
  name: string,
  canHandle(nativeObject: unknown): boolean,
  getConfig(nativeObject): TheatreObjectConfig,
  start(object: TheatreObject): StopFunction,
}

type StopFunction = () => void

Learn more here.

# UI

The UI object. Only available in development mode. Available as Theatre.ui.

The state of the UI (such as the size of the panel) is persisted in the browser's storage.

# UI.show()

The UI is visible by default. If it's been hidden, this method will bring it back in:

Theatre.ui.show()

Calling Theatre.ui.show() is required in auto-reloading environment such as CodeSandbox.

# UI.hide()

Hides the UI from the screen:

Theatre.ui.hide()