pencil.js / scene / Scene

Class: Scene<O>

Defined in: scene.ts:28

Root of every drawing, linked to a canvas displayed on screen and handling user interactions

Extends

• OffScreenCanvas<O>

Type Parameters

Type Parameter	Default type
O extends SceneOptions	SceneOptions

Constructors

Constructor

new Scene<O>(container?, options?): Scene<O>;

Defined in: scene.ts:68

Scene constructor

Parameters

Parameter	Type	Default value	Description
container?	HTMLElement	window.document.body	Container of the renderer (or a canvas to use)
options?	Partial<O>	undefined	Specific options

Returns

Scene<O>

Overrides

OffScreenCanvas.constructor

Properties

Property	Type	Description	Inherited from	Defined in
children	Container<ContainerOptions>[]	List of children	OffScreenCanvas.children	container.ts:134
ctx	CanvasRenderingContext2D	Drawing context	OffScreenCanvas.ctx	offscreen-canvas.ts:25
cursorPosition	Position	Last known pointer position	-	scene.ts:43
eventListeners	Record<string, EventListener[]>	Set of event listeners of this component	OffScreenCanvas.eventListeners	event-emitter.ts:33
fps	number	Number of frame per seconds (only when looped)	-	scene.ts:52
frameCount	number	Number of time this container has been rendered	OffScreenCanvas.frameCount	container.ts:140
isClicked	boolean	Is the scene clicked	-	scene.ts:49
isLooped	boolean	Is the scene rendered every frame	-	scene.ts:46
lastTick	number | null	Timestamp of the last render	-	scene.ts:55
options	O	Set of options	OffScreenCanvas.options	container.ts:131
parent	| Container<ContainerOptions> | null	Parent container (null when not attached)	OffScreenCanvas.parent	container.ts:137
position	Position	Position in its container	OffScreenCanvas.position	container.ts:128

Accessors

center

Get Signature

get center(): Position;

Defined in: offscreen-canvas.ts:114

Return this canvas center point

Returns

Position

Inherited from

OffScreenCanvas.center

---

height

Get Signature

get height(): number;

Defined in: offscreen-canvas.ts:96

Height of the canvas

Returns

number

Set Signature

set height(height): void;

Defined in: offscreen-canvas.ts:100

Parameters

Parameter	Type
height	number

Returns

void

Inherited from

OffScreenCanvas.height

---

isScene

Get Signature

get isScene(): boolean;

Defined in: scene.ts:33

Is this the root scene

Returns

boolean

Overrides

OffScreenCanvas.isScene

---

size

Get Signature

get size(): Position;

Defined in: offscreen-canvas.ts:107

Return the whole canvas size

Returns

Position

Inherited from

OffScreenCanvas.size

---

width

Get Signature

get width(): number;

Defined in: offscreen-canvas.ts:85

Width of the canvas

Returns

number

Set Signature

set width(width): void;

Defined in: offscreen-canvas.ts:89

Parameters

Parameter	Type
width	number

Returns

void

Inherited from

OffScreenCanvas.width

---

className

Get Signature

get static className(): string;

Defined in: scene.ts:29

Name used when serializing (survive minification)

Returns

string

Overrides

OffScreenCanvas.className

---

defaultOptions

Get Signature

get static defaultOptions(): SceneOptions;

Defined in: scene.ts:364

Default options for this class

Returns

SceneOptions

Overrides

OffScreenCanvas.defaultOptions

---

events

Get Signature

get static events(): Record<string, string>;

Defined in: scene.ts:374

Set of events for easy access

Returns

Record<string, string>

Overrides

OffScreenCanvas.events

Methods

add()

add(...children): this;

Defined in: container.ts:206

Add other containers as children

Parameters

Parameter	Type	Description
...children	Container<ContainerOptions>[]	Other containers

Returns

this

Itself

Inherited from

OffScreenCanvas.add

---

applyRotationAndScale()

protected applyRotationAndScale(ctx): this;

Defined in: container.ts:467

Apply rotation and scaling to the context

Parameters

Parameter	Type	Description
ctx	CanvasRenderingContext2D	Drawing context

Returns

this

Itself

Inherited from

OffScreenCanvas.applyRotationAndScale

---

applyTransform()

applyTransform(ctx): this;

Defined in: container.ts:450

Apply position, clipping, rotation and scaling to the context

Parameters

Parameter	Type	Description
ctx	CanvasRenderingContext2D	Drawing context

Returns

this

Itself

Inherited from

OffScreenCanvas.applyTransform

---

clear()

clear(): this;

Defined in: offscreen-canvas.ts:52

Erase the canvas

Returns

this

Itself

Inherited from

OffScreenCanvas.clear

---

climbAncestry()

climbAncestry(callback, until?): void;

Defined in: container.ts:744

Execute an action on itself and every ancestor

Parameters

Parameter	Type	Description
callback	(ancestor) => void	Function to execute on each ancestor
until?	| Container<ContainerOptions> | null	Define a ancestor where to stop the climbing (excluded)

Returns

void

Inherited from

OffScreenCanvas.climbAncestry

---

clone()

clone(): this;

Defined in: container.ts:788

Create a deep copy of this container (and its children)

Returns

this

Inherited from

OffScreenCanvas.clone

---

delete()

delete(): this;

Defined in: container.ts:259

Remove itself from its parent

Returns

this

Itself

Inherited from

OffScreenCanvas.delete

---

destroy()

destroy(): this;

Defined in: scene.ts:189

Stop rendering, remove every listener and remove the canvas from the page (when created by the scene)

Returns

this

Itself

---

empty()

empty(): this;

Defined in: container.ts:251

Remove all its children

Returns

this

Itself

Inherited from

OffScreenCanvas.empty

---

fire()

fire(event): this;

Defined in: container.ts:374

Fire an event and bubble it to its parent

Parameters

Parameter	Type	Description
event	BaseEvent	Event to fire

Returns

this

Itself

Inherited from

OffScreenCanvas.fire

---

getAbsoluteMatrix()

getAbsoluteMatrix(): DOMMatrix;

Defined in: container.ts:330

Get the cumulated matrix of transformation from the root to this container

Returns

DOMMatrix

Inherited from

OffScreenCanvas.getAbsoluteMatrix

---

getAbsolutePosition()

getAbsolutePosition(): Position;

Defined in: container.ts:338

Get this container's absolute position (up to it's utmost parent), taking into account every transformation

Returns

Position

Inherited from

OffScreenCanvas.getAbsolutePosition

---

getEventPosition()

getEventPosition(event): Position;

Defined in: scene.ts:203

Convert a DOM event coordinates into the scene space

Parameters

Parameter	Type	Description
event	{ clientX: number; clientY: number; }	Any DOM mouse/pointer event
event.clientX	number	-
event.clientY	number	-

Returns

Position

---

getImageData()

getImageData(vectorDefinition?): ImageData;

Defined in: offscreen-canvas.ts:129

Render and return the canvas content as data

Parameters

Parameter	Type	Description
vectorDefinition?	VectorDefinition	Box of data to extract

Returns

ImageData

Inherited from

OffScreenCanvas.getImageData

---

getMatrix()

getMatrix(): DOMMatrix;

Defined in: container.ts:310

Get the matrix of transformation applied by this container on its children (including its position)

Returns

DOMMatrix

Inherited from

OffScreenCanvas.getMatrix

---

getRandomPosition()

getRandomPosition(): Position;

Defined in: offscreen-canvas.ts:121

Return a random position within the canvas

Returns

Position

Inherited from

OffScreenCanvas.getRandomPosition

---

getRoot()

getRoot(): Container;

Defined in: container.ts:299

Return its highest parent

Returns

Container

Inherited from

OffScreenCanvas.getRoot

---

getScene()

getScene(): Promise<Scene<SceneOptions>>;

Defined in: container.ts:267

Return a promise for the associated scene (resolved once attached to a scene)

Returns

Promise<Scene<SceneOptions>>

Inherited from

OffScreenCanvas.getScene

---

getTarget()

getTarget(position, ctx): 
  | Container<ContainerOptions>
  | null;

Defined in: container.ts:401

Find the target at a position

Parameters

Parameter	Type	Description
position	Position	Any position
ctx	CanvasRenderingContext2D	Drawing context to apply paths

Returns

| Container<ContainerOptions> | null

Inherited from

OffScreenCanvas.getTarget

---

hide()

hide(): this;

Defined in: scene.ts:175

Hide it

Returns

this

Itself

Overrides

OffScreenCanvas.hide

---

isAncestorOf()

isAncestorOf(container?): boolean;

Defined in: container.ts:728

Define if this is an ancestor of another container

Parameters

Parameter	Type	Description
container?	| Container<ContainerOptions> | null	Any container

Returns

boolean

Inherited from

OffScreenCanvas.isAncestorOf

---

isHover()

isHover(): boolean;

Defined in: scene.ts:145

A scene is always hovered when shown

Returns

boolean

Overrides

OffScreenCanvas.isHover

---

isInClip()

protected isInClip(position, ctx): boolean;

Defined in: container.ts:437

Tell if a position is inside the clipping region

Parameters

Parameter	Type	Description
position	Position	Any position (in the drawing context space)
ctx	CanvasRenderingContext2D	Drawing context with this container's transformations applied

Returns

boolean

Inherited from

OffScreenCanvas.isInClip

---

makePath()

makePath(_ctx): this;

Defined in: container.ts:700

Do nothing on Container, override it to add behavior

Parameters

Parameter	Type	Description
_ctx	CanvasRenderingContext2D	Drawing context

Returns

this

Itself

Inherited from

OffScreenCanvas.makePath

---

on()

on(
   eventName, 
   callback, 
   isTargeted?
): this;

Defined in: event-emitter.ts:51

Listen to an event or multiple events

Parameters

Parameter	Type	Default value	Description
eventName	string | string[]	undefined	Name of event (or a list of event names) to listen to. The event name can be followed by a modifier (separated by a ".")
callback	EventCallback	undefined	Function to call when event fire
isTargeted?	boolean	false	Should only listen to event targeting itself

Returns

this

Itself

Example

component.on("event.modifier", () => console.log("Event fired with modifier"));

Inherited from

OffScreenCanvas.on

---

once()

once(
   eventName, 
   callback, 
   isTargeted?
): this;

Defined in: event-emitter.ts:71

Listen to an event only once

Parameters

Parameter	Type	Default value	Description
eventName	string | string[]	undefined	Name of event (or a list of event names) to listen to.
callback	EventCallback	undefined	Function to call when event fire
isTargeted?	boolean	false	Should only listen to event targeting itself

Returns

this

Itself

Inherited from

OffScreenCanvas.once

---

remove()

remove(...children): this;

Defined in: container.ts:234

Remove children from the list

Parameters

Parameter	Type	Description
...children	Container<ContainerOptions>[]	Children to remove

Returns

this

Itself

Inherited from

OffScreenCanvas.remove

---

removeAllListener()

removeAllListener(): this;

Defined in: event-emitter.ts:127

Remove all event listeners

Returns

this

Itself

Inherited from

OffScreenCanvas.removeAllListener

---

removeListener()

removeListener(eventName, callback?): this;

Defined in: event-emitter.ts:105

Remove an event or multiple events

Parameters

Parameter	Type	Description
eventName	string | string[]	Name of event (or a list of event names) to remove
callback?	EventCallback<any>	Specify the callback to remove, if not defined remove all listeners

Returns

this

Itself

Inherited from

OffScreenCanvas.removeListener

---

render()

render(): this;

Defined in: scene.ts:116

Draw the whole scene

Returns

this

Itself

Overrides

OffScreenCanvas.render

---

setContext()

setContext(_ctx): this;

Defined in: container.ts:503

Set variables of the context according to specified options (override it to add behavior)

Parameters

Parameter	Type	Description
_ctx	CanvasRenderingContext2D	Drawing context

Returns

this

Itself

Inherited from

OffScreenCanvas.setContext

---

setCursor()

setCursor(cursor?): this;

Defined in: scene.ts:107

Change the cursor displayed over the canvas

Parameters

Parameter	Type	Default value	Description
cursor?	string | null	Component.cursors.default	Cursor string

Returns

this

Itself

---

setImageData()

setImageData(imageData, positionDefinition?): this;

Defined in: offscreen-canvas.ts:144

Put data into the canvas

Parameters

Parameter	Type	Description
imageData	ImageData	Data to add to the canvas
positionDefinition?	PositionDefinition	Position of the data

Returns

this

Itself

Inherited from

OffScreenCanvas.setImageData

---

setImageSmoothing()

setImageSmoothing(enable): this;

Defined in: offscreen-canvas.ts:43

Change the behavior for upscaled images, smoothing is good for pictures but bad for pixel-art

Parameters

Parameter	Type	Description
enable	boolean	Should the smoothing be active or not

Returns

this

Itself

Inherited from

OffScreenCanvas.setImageSmoothing

---

setOptions()

setOptions(options?): this;

Defined in: container.ts:177

Define options for this container

Parameters

Parameter	Type	Description
options?	Partial<O>	Options to override

Returns

this

Itself

Inherited from

OffScreenCanvas.setOptions

---

show()

show(): this;

Defined in: scene.ts:180

Display it

Returns

this

Itself

Overrides

OffScreenCanvas.show

---

sortChildren()

protected sortChildren(): void;

Defined in: container.ts:385

Sort children according to their zIndex

Returns

void

Inherited from

OffScreenCanvas.sortChildren

---

startLoop()

startLoop(): this;

Defined in: scene.ts:153

Start to render the scene each frame

Returns

this

Itself

---

stopLoop()

stopLoop(): this;

Defined in: scene.ts:165

Stop scene from being rendered

Returns

this

Itself

---

toGlobal()

toGlobal(positionDefinition): Position;

Defined in: container.ts:360

Convert a position from this container's space into the root (scene) space

Parameters

Parameter	Type	Description
positionDefinition	PositionDefinition	Position relative to this container

Returns

Position

Inherited from

OffScreenCanvas.toGlobal

---

toImage()

toImage(vectorDefinition?, type?): HTMLImageElement;

Defined in: offscreen-canvas.ts:155

Return an image composed of its content

Parameters

Parameter	Type	Default value	Description
vectorDefinition?	VectorDefinition	undefined	Box to restrict exported data
type?	string	"image/png"	Data format. Supported format depend on the browser implementation (png or jpeg are the only safe choices)

Returns

HTMLImageElement

Inherited from

OffScreenCanvas.toImage

---

toJSON()

toJSON(): object;

Defined in: offscreen-canvas.ts:176

Return a json ready object

Returns

children?

children?: ContainerJSON[];

Children definitions

constructor

constructor: string;

Name of the class

height

height: number;

options?

options?: Record<string, any>;

Options different from the default ones

position

position: PositionDefinition;

Position in its parent

width

width: number;

Inherited from

OffScreenCanvas.toJSON

---

toLocal()

toLocal(positionDefinition): Position;

Defined in: container.ts:347

Convert a position from the root (scene) space into this container's space

Parameters

Parameter	Type	Description
positionDefinition	PositionDefinition	Position relative to the root

Returns

Position

Inherited from

OffScreenCanvas.toLocal

---

from()

static from(definition): Scene;

Defined in: scene.ts:341

Return an instance from a generic object

Parameters

Parameter	Type	Description
definition	ContainerJSON	Scene definition

Returns

Scene

Overrides

OffScreenCanvas.from

---

getClipPath()

static getClipPath(clip): Path2D;

Defined in: container.ts:489

Build the clipping path of a component, with its own transformations applied

Parameters

Parameter	Type	Description
clip	Component	Component used as clip

Returns

Path2D

Inherited from

OffScreenCanvas.getClipPath

---

getDrawingContext()

static getDrawingContext(container?, height?): CanvasRenderingContext2D;

Defined in: scene.ts:350

Build a canvas filling the given element

Parameters

Parameter	Type	Default value	Description
container?	number | HTMLElement	window.document.body	Element holding the canvas
height?	number	1	Canvas height (when the first argument is a width)

Returns

CanvasRenderingContext2D

Overrides

OffScreenCanvas.getDrawingContext

---

setOpacity()

static setOpacity(ctx, opacity): void;

Defined in: container.ts:814

Define context opacity (null means no change)

Parameters

Parameter	Type	Description
ctx	CanvasRenderingContext2D	Drawing context
opacity	number | null	Opacity value

Returns

void

Inherited from

OffScreenCanvas.setOpacity