Appearance
DisplayController
The DisplayController combines properties and functions from a given Display and its corresponding Stage Instance to make an easy to use object for controlling and monitor the status and content of a Stage Instance from JavaScript.
After a Snippet has initialized, a DisplayController for each Display can be found under the global Plinthos object.
Properties
.instanceKey
: string readonlyinstanceKey
The Instance Key of the Display and the Stage (a Display will always share its Instance Key with its respective Stage instance).
.stageKey
: string readonlystageKey
The Stage Key of the Stage Instance connected to this Display.
.stageName
: string readonlystageName
The name of the Stage connected to this Display.
.isOffscreen
: boolean readonlyisOffscreen
True if the connected Stage Instance is in a Web Worker; false if it is not (on the main thread).
NOTE
Whether or not a Stage Instance is built in a Web Worker is dependent on whether or not the "Worker Key" field is populated during Snippet configuration.
isRunning
: boolean readonlyisRunning
True if the connected Stage Instance is running; false if it is not.
.isStopping
: boolean readonlyisStopping
True if the connected Stage Instance is in the process of stopping; false if it is not.
NOTE
isStopping being false could indicate either that the Stage Instance is running with no immediate intention of stopping OR it is fully stopped. Use isRunning to determine the actual current running state of the Stage Instance.
shotKey
: string readonlyshotKey
The key of the Shot currently being displayed by the connected Stage Instance.
NOTE
shotKey is different from contentKey in two ways: shotKey will always return the key of a Shot, event if the current piece of content is a Sequence (i.e., it will return the key of the currently displayed Shot within the Sequence) whereas contentKey will return the key of the Sequence if a Sequence is the current piece of Content.
contentKey
: stringcontentKey
The key of the current piece of Content. Unlike shotKey, this value can be set resulting in a Content transition.
bindings
: Object readonlybindings
An object consisting of keyed number values that certain Content is able to respond to. Usage of this object will vary between Kits.
Important
All values in the bindings object must be of type number. Non-number members will be discarded.
userData
: Object readonlyuserData
An object that contains arbitrary data that is used by the Stage Instance to compose or display some Stage Content. Usage of this object will vary between Kits.
.shotData
: Object readonlyshotData
An object that serves as a set of Instance-wide default Shot Parameters. Changing these values between Shot changes will change the default values for subsequent Shots.
.debug
: booleandebug
A boolean flag to enable or disable debug mode. Turning on debug mode will cause various system messages to be logged to the console.
.pixelRatio
: numberpixelRatio
The pixel ratio for the connected Stage Instance. Lowering this value will result in blurring or pixelation but will improve performance in some cases.
NOTE
This value reflects the pixel ratio as a co-efficient of the device pixel ratio meaning that a value of 1 is full utilization of all device pixels regardless of device PPI.
skipFrames
: numberskipFrames
The number of frames that should be skipped between between each rendered frame. Although this is generally set to 0 (meaning that every frame is rendered), lowering framerate dynamically can sometimes be a useful performance tweaking tool.
pointerEventSurrogate
: HTMLElement | nullpointerEventSurrogate
An HTML element that will relay its mouse events to the Canvas of the Stage Instance. This is useful if you want to be able to click or drag on the Canvas but the Canvas element is underneath too many other elements to make this practical.
.canvas
: HTMLCanvasElementcanvas
The Canvas of the Stage Instance.
.isIntersecting
: boolean readonlyisIntersecting
Returns true if the canvas is intersecting with the viewport and false if not.
attribution
: Attribution[] readonlyattribution
An array of Attribution objects. This array contains all the Attribution objects for all assets in the Stage.
.activeAttribution
: Attribution[] readonlyactiveAttribution
An array of Attribution objects. This array contains only the Attribution objects for currently visible assets in the Stage.
Methods
.start
(): voidstart
Start the Stage Instance connected to the Display.
.stop
(options?: StopOptions): voidstop
Stop the Stage Instance connected to the Display. An optional StopOptions object can be passed in as a parameter to tweak how the stop is handled.
.show
(key: string, data?: Object): Promise<boolean>show
A more controlled way of transitioning Content (rather than setting contentKey), also allowing for the passing of Parameters to the Stage Instance.
smash
(key: string, data?: Object): Promise<boolean>smash
Same as show except that the Content changes with the smash cut instead of a smooth transition.
.run
(methodName: string, ...methodArgs): Promise<void>Allows for the calling of a Reaction method.
.benchmark
(): Promise<BenchmarkResults>benchmark
Debugging tool for measuring stage performance.
Important
This should never be used in production or even written into code files; calling it from the browser console is the only recommended use case.
addEventListener
(type: string, listener: EventListener, options?: AddEventListenerOptions): voidaddEventListener
Allows the adding of custom event listeners to the Display. All events from the Stage Instance propagate up through the Display so adding event listeners that this level captures all events emitted from the connected Stage Instance.
.removeEventListener
(type: string, listener: EventListener, options?: AddEventListenerOptions): voidremoveEventListener
Removes a custom event listener. This works using the same standard rules as regular Javascript event listeners.