PIXI.EventBoundary

class EventBoundary

Event boundaries are "barriers" where events coming from an upstream scene are modified before downstream propagation.

Root event boundary

The rootBoundary handles events coming from the <canvas />. PIXI.EventSystem handles the normalization from native Events into FederatedEvents. The rootBoundary then does the hit-testing and event dispatch for the upstream normalized event.

Additional event boundaries

An additional event boundary may be desired within an application's scene graph. For example, if a portion of the scene is is flat with many children at one level - a spatial hash maybe needed to accelerate hit testing. In this scenario, the container can be detached from the scene and glued using a custom event boundary.

import { Container } from '@pixi/display';
import { EventBoundary } from '@pixi/events';
import { SpatialHash } from 'pixi-spatial-hash';

class HashedHitTestingEventBoundary
{
    private spatialHash: SpatialHash;

    constructor(scene: Container, spatialHash: SpatialHash)
    {
        super(scene);
        this.spatialHash = spatialHash;
    }

    hitTestRecursive(...)
    {
        // TODO: If target === this.rootTarget, then use spatial hash to get a
        // list of possible children that match the given (x,y) coordinates.
    }
}

class VastScene extends DisplayObject
{
    protected eventBoundary: EventBoundary;
    protected scene: Container;
    protected spatialHash: SpatialHash;

    constructor()
    {
        this.scene = new Container();
        this.spatialHash = new SpatialHash();
        this.eventBoundary = new HashedHitTestingEventBoundary(this.scene, this.spatialHash);

        // Populate this.scene with a ton of children, while updating this.spatialHash
    }
}

Constructor

new PIXI.EventBoundary(rootTarget: PIXI.DisplayObject) → {}

Parameters:
Name	Type	Attributes	Description
rootTarget	PIXI.DisplayObject	<optional>	The holder of the event boundary.

Summary

Properties from EventBoundary

Cursor \| string	cursor The cursor preferred by the event targets underneath this boundary.
EventEmitter	dispatch Emits events after they were dispatched into the scene graph.
boolean	moveOnAll = false This flag would emit `pointermove`, `touchmove`, and `mousemove` events on all DisplayObjects.
PIXI.DisplayObject	rootTarget The root event-target residing below the event boundary.
Map<typeof PIXI.FederatedEvent, PIXI.FederatedEvent[]>	protected eventPool
Record<string, any>	protected mappingState
Record<string, PIXI.FederatedEvent<{ fn : (e: Array) => void, priority : number }>>	protected mappingTable Maps event types to forwarding handles for them.

Methods from EventBoundary

void	addEventMapping(type: string, fn: (e: PIXI.FederatedEvent) => void) Adds an event mapping for the event `type` handled by `fn`.
void	all(e: PIXI.FederatedEvent, type: string, target: PIXI.FederatedEventTarget) Emits the event e to all display objects. The event is propagated in the bubbling phase always.
void	dispatchEvent(e: PIXI.FederatedEvent, type: string)
PIXI.DisplayObject	hitTest(x: number, y: number) Finds the DisplayObject that is the target of a event at the given coordinates.
void	mapEvent(e: PIXI.FederatedEvent)
void	propagate(e: PIXI.FederatedEvent, type: string)
PIXI.FederatedEventTarget[]	propagationPath(target: PIXI.FederatedEventTarget)
T	protected allocateEvent(constructor: { new (boundary: PIXI.EventBoundary): T }) Allocate a specific type of event from this.eventPool.
PIXI.FederatedPointerEvent	protected clonePointerEvent(from: PIXI.FederatedPointerEvent, type: string) Clones the event `from`, with an optional `type` override.
void	protected copyData(from: PIXI.FederatedEvent, to: PIXI.FederatedEvent) Copies base PIXI.FederatedEvent data from `from` into `to`.
void	protected copyMouseData(from: PIXI.FederatedEvent, to: PIXI.FederatedEvent) Copies mouse PIXI.FederatedMouseEvent data from `from` to `to`.
void	protected copyPointerData(from: PIXI.FederatedEvent, to: PIXI.FederatedEvent) Copies pointer PIXI.FederatedPointerEvent data from `from` into `to`.
void	protected copyWheelData(from: PIXI.FederatedWheelEvent, to: PIXI.FederatedWheelEvent) Copies wheel PIXI.FederatedWheelEvent data from `from` into `to`.
PIXI.FederatedPointerEvent	protected createPointerEvent(from: PIXI.FederatedPointerEvent, type: string, target: PIXI.FederatedEventTarget) Creates an event whose `originalEvent` is `from`, with an optional `type` and `target` override.
PIXI.FederatedWheelEvent	protected createWheelEvent(from: PIXI.FederatedWheelEvent) Creates a wheel event whose `originalEvent` is `from`.
PIXI.FederatedEventTarget	protected findMountedTarget(propagationPath: PIXI.FederatedEventTarget[]) Finds the most specific event-target in the given propagation path that is still mounted in the scene graph.
void	protected freeEvent(event: T) Frees the event and puts it back into the event pool.
boolean	protected hitPruneFn(displayObject: PIXI.DisplayObject, location: PIXI.Point) Checks whether the display object or any of its children cannot pass the hit test at all.
boolean	protected hitTestFn(displayObject: PIXI.DisplayObject, location: PIXI.Point)
PIXI.DisplayObject[]	protected hitTestRecursive(currentTarget: PIXI.DisplayObject, interactive: boolean, location: PIXI.Point, testFn: (object: PIXI.DisplayObject, pt: PIXI.Point) => boolean, pruneFn: (object: PIXI.DisplayObject, pt: PIXI.Point) => boolean)
void	protected mapPointerDown(from: PIXI.FederatedEvent) Maps the upstream `pointerdown` events to a downstream `pointerdown` event.
void	protected mapPointerMove(from: PIXI.FederatedEvent) Maps the upstream `pointermove` to downstream `pointerout`, `pointerover`, and `pointermove` events, in that order.
void	protected mapPointerOut(from: PIXI.FederatedEvent) Maps the upstream `pointerout` to downstream `pointerout`, `pointerleave` events, in that order.
void	protected mapPointerOver(from: PIXI.FederatedEvent) Maps the upstream `pointerover` to downstream `pointerover` and `pointerenter` events, in that order.
void	protected mapPointerUp(from: PIXI.FederatedEvent)
void	protected mapPointerUpOutside(from: PIXI.FederatedEvent)
void	protected mapWheel(from: PIXI.FederatedEvent)
void	protected notifyTarget(e: PIXI.FederatedEvent, type: string)
TrackingData	protected trackingData(id: number)

Public Properties

cursor EventBoundary.ts:139

cursor: Cursor | string

The cursor preferred by the event targets underneath this boundary.

dispatch EventBoundary.ts:128

dispatch: EventEmitter

Emits events after they were dispatched into the scene graph.

This can be used for global events listening, regardless of the scene graph being used. It should not be used by interactive libraries for normal use.

Special events that do not bubble all the way to the root target are not emitted from here, e.g. pointerenter, pointerleave, click.

moveOnAll EventBoundary.ts:142

moveOnAll: boolean = false

This flag would emit pointermove, touchmove, and mousemove events on all DisplayObjects.

The moveOnAll semantics mirror those of earlier versions of PixiJS. This was disabled in favor of the Pointer Event API's approach.

rootTarget EventBoundary.ts:121

rootTarget: PIXI.DisplayObject

The root event-target residing below the event boundary.

All events are dispatched trickling down and bubbling up to this rootTarget.

Protected Properties

eventPool EventBoundary.ts:170

protected eventPool: Map<typeof PIXI.FederatedEvent, PIXI.FederatedEvent[]>

The event pool maps event constructors to an free pool of instances of those specific events.

See:

mappingState EventBoundary.ts:162

protected mappingState: Record<string, any>

State object for mapping methods.

See: PIXI.EventBoundary#trackingData

mappingTable EventBoundary.ts:150

protected mappingTable: Record<string, PIXI.FederatedEvent<{ fn : (e: Array) => void, priority : number }>>

Maps event types to forwarding handles for them.

EventBoundary provides mapping for "pointerdown", "pointermove", "pointerout", "pointerleave", "pointerover", "pointerup", and "pointerupoutside" by default.

See: PIXI.EventBoundary#addEventMapping

Public Methods

addEventMapping EventBoundary.ts:205

addEventMapping(type: string, fn: (e: PIXI.FederatedEvent) => void) → {void}

Adds an event mapping for the event type handled by fn.

Event mappings can be used to implement additional or custom events. They take an event coming from the upstream scene (or directly from the PIXI.EventSystem) and dispatch new downstream events generally trickling down and bubbling up to this.rootTarget.

To modify the semantics of existing events, the built-in mapping methods of EventBoundary should be overridden instead.

Parameters:
Name	Type	Description
type	string	The type of upstream event to map.
fn	(e: PIXI.FederatedEvent) => void	The mapping method. The context of this function must be bound manually, if desired.

Returns:
Type	Description
void

all EventBoundary.ts:343

all(e: PIXI.FederatedEvent, type: string, target: PIXI.FederatedEventTarget) → {void}

Emits the event e to all display objects. The event is propagated in the bubbling phase always.

This is used in the pointermove legacy mode.

Parameters:
Name	Type	Attributes	Description
e	PIXI.FederatedEvent		The emitted event.
type	string	<optional>	The listeners to notify.
target	PIXI.FederatedEventTarget

Returns:
Type	Description
void

dispatchEvent EventBoundary.ts:231

dispatchEvent(e: PIXI.FederatedEvent, type: string) → {void}

Dispatches the given event

Parameters:
Name	Type	Attributes	Description
e	PIXI.FederatedEvent
type	string	<optional>

Returns:
Type	Description
void

hitTest EventBoundary.ts:271

hitTest(x: number, y: number) → {PIXI.DisplayObject}

Finds the DisplayObject that is the target of a event at the given coordinates.

The passed (x,y) coordinates are in the world space above this event boundary.

Parameters:
Name	Type	Description
x	number
y	number

Returns:
Type	Description
PIXI.DisplayObject

mapEvent EventBoundary.ts:245

mapEvent(e: PIXI.FederatedEvent) → {void}

Maps the given upstream event through the event boundary and propagates it downstream.

Parameters:
Name	Type	Description
e	PIXI.FederatedEvent

Returns:
Type	Description
void

propagate EventBoundary.ts:294

propagate(e: PIXI.FederatedEvent, type: string) → {void}

Propagate the passed event from from this.rootTarget to its target e.target.

Parameters:
Name	Type	Attributes	Description
e	PIXI.FederatedEvent		The event to propagate.
type	string	<optional>

Returns:
Type	Description
void

propagationPath EventBoundary.ts:369

propagationPath(target: PIXI.FederatedEventTarget) → {PIXI.FederatedEventTarget[]}

Finds the propagation path from rootTarget to the passed target. The last element in the path is target.

Parameters:
Name	Type	Description
target	PIXI.FederatedEventTarget

Returns:
Type	Description
PIXI.FederatedEventTarget[]

Protected Methods

allocateEvent EventBoundary.ts:1248

protected allocateEvent(constructor: { new (boundary: PIXI.EventBoundary): T }) → {T}

Allocate a specific type of event from this.eventPool.

This allocation is constructor-agnostic, as long as it only takes one argument - this event boundary.

Parameters:
Name	Type	Description
constructor	{ new (boundary: PIXI.EventBoundary): T }	The event's constructor.

Returns:
Type	Description
T

clonePointerEvent EventBoundary.ts:1091

protected clonePointerEvent(from: PIXI.FederatedPointerEvent, type: string) → {PIXI.FederatedPointerEvent}

Clones the event from, with an optional type override.

The event is allocated using this.allocateEvent.

Parameters:
Name	Type	Attributes	Default	Description
from	PIXI.FederatedPointerEvent			The event to clone.
type	string	<optional>	from.type	The type of the returned event.

Returns:
Type	Description
PIXI.FederatedPointerEvent

copyData EventBoundary.ts:1205

protected copyData(from: PIXI.FederatedEvent, to: PIXI.FederatedEvent) → {void}

Copies base PIXI.FederatedEvent data from from into to.

The following properties are copied:

isTrusted
srcElement
timeStamp
type

Parameters:
Name	Type	Description
from	PIXI.FederatedEvent	The event to copy data from.
to	PIXI.FederatedEvent	The event to copy data into.

Returns:
Type	Description
void

copyMouseData EventBoundary.ts:1168

protected copyMouseData(from: PIXI.FederatedEvent, to: PIXI.FederatedEvent) → {void}

Copies mouse PIXI.FederatedMouseEvent data from from to to.

The following properties are copied:

altKey
button
buttons
clientX
clientY
metaKey
movementX
movementY
pageX
pageY
x
y
screen
global

Parameters:
Name	Type	Description
from	PIXI.FederatedEvent
to	PIXI.FederatedEvent

Returns:
Type	Description
void

copyPointerData EventBoundary.ts:1136

protected copyPointerData(from: PIXI.FederatedEvent, to: PIXI.FederatedEvent) → {void}

Copies pointer PIXI.FederatedPointerEvent data from from into to.

The following properties are copied:

pointerId
width
height
isPrimary
pointerType
pressure
tangentialPressure
tiltX
tiltY

Parameters:
Name	Type	Description
from	PIXI.FederatedEvent
to	PIXI.FederatedEvent

Returns:
Type	Description
void

copyWheelData EventBoundary.ts:1117

protected copyWheelData(from: PIXI.FederatedWheelEvent, to: PIXI.FederatedWheelEvent) → {void}

Copies wheel PIXI.FederatedWheelEvent data from from into to.

The following properties are copied:

deltaMode
deltaX
deltaY
deltaZ

Parameters:
Name	Type	Description
from	PIXI.FederatedWheelEvent
to	PIXI.FederatedWheelEvent

Returns:
Type	Description
void

createPointerEvent EventBoundary.ts:1038

protected createPointerEvent(from: PIXI.FederatedPointerEvent, type: string, target: PIXI.FederatedEventTarget) → {PIXI.FederatedPointerEvent}

Creates an event whose originalEvent is from, with an optional type and target override.

The event is allocated using this.allocateEvent.

Parameters:
Name	Type	Attributes	Default	Description
from	PIXI.FederatedPointerEvent			The `originalEvent` for the returned event.
type	string	<optional>	from.type	The type of the returned event.
target	PIXI.FederatedEventTarget	<optional>		The target of the returned event.

Returns:
Type	Description
PIXI.FederatedPointerEvent

createWheelEvent EventBoundary.ts:1070

protected createWheelEvent(from: PIXI.FederatedWheelEvent) → {PIXI.FederatedWheelEvent}

Creates a wheel event whose originalEvent is from.

The event is allocated using this.allocateEvent.

Parameters:
Name	Type	Description
from	PIXI.FederatedWheelEvent	The upstream wheel event.

Returns:
Type	Description
PIXI.FederatedWheelEvent

findMountedTarget EventBoundary.ts:1004

protected findMountedTarget(propagationPath: PIXI.FederatedEventTarget[]) → {PIXI.FederatedEventTarget}

Finds the most specific event-target in the given propagation path that is still mounted in the scene graph.

This is used to find the correct pointerup and pointerout target in the case that the original pointerdown or pointerover target was unmounted from the scene graph.

Parameters:
Name	Type	Description
propagationPath	PIXI.FederatedEventTarget[]	The propagation path was valid in the past.

Returns:
Type	Description
PIXI.FederatedEventTarget	The most specific event-target still mounted at the same location in the scene graph.

freeEvent EventBoundary.ts:1275

protected freeEvent(event: T) → {void}

Frees the event and puts it back into the event pool.

It is illegal to reuse the event until it is allocated again, using this.allocateEvent.

It is also advised that events not allocated from this.allocateEvent not be freed. This is because of the possibility that the same event is freed twice, which can cause it to be allocated twice & result in overwriting.

Parameters:
Name	Type	Description
event	T	The event to be freed.

Returns:
Type	Description
void

hitPruneFn EventBoundary.ts:478

protected hitPruneFn(displayObject: PIXI.DisplayObject, location: PIXI.Point) → {boolean}

Checks whether the display object or any of its children cannot pass the hit test at all.

EventBoundary's implementation uses the hitArea and PIXI.DisplayObject._mask for pruning.

Parameters:
Name	Type	Description
displayObject	PIXI.DisplayObject
location	PIXI.Point

Returns:
Type	Description
boolean

hitTestFn EventBoundary.ts:512

protected hitTestFn(displayObject: PIXI.DisplayObject, location: PIXI.Point) → {boolean}

Checks whether the display object passes hit testing for the given location.

Parameters:
Name	Type	Description
displayObject	PIXI.DisplayObject
location	PIXI.Point

Returns:
Type	Description
boolean	Whether `displayObject` passes hit testing for `location`.

hitTestRecursive EventBoundary.ts:395

protected hitTestRecursive(currentTarget: PIXI.DisplayObject, interactive: boolean, location: PIXI.Point, testFn: (object: PIXI.DisplayObject, pt: PIXI.Point) => boolean, pruneFn: (object: PIXI.DisplayObject, pt: PIXI.Point) => boolean) → {PIXI.DisplayObject[]}

Recursive implementation for hitTest.

Parameters:
Name	Type	Attributes	Description
currentTarget	PIXI.DisplayObject		The DisplayObject that is to be hit tested.
interactive	boolean		Flags whether `currentTarget` or one of its parents are interactive.
location	PIXI.Point		The location that is being tested for overlap.
testFn	(object: PIXI.DisplayObject, pt: PIXI.Point) => boolean		Callback that determines whether the target passes hit testing. This callback can assume that `pruneFn` failed to prune the display object.
pruneFn	(object: PIXI.DisplayObject, pt: PIXI.Point) => boolean	<optional>	Callback that determiness whether the target and all of its children cannot pass the hit test. It is used as a preliminary optimization to prune entire subtrees of the scene graph.

Returns:
Type	Description
PIXI.DisplayObject[]	An array holding the hit testing target and all its ancestors in order. The first element is the target itself and the last is rootTarget. This is the opposite order w.r.t. the propagation path. If no hit testing target is found, null is returned.

mapPointerDown EventBoundary.ts:554

protected mapPointerDown(from: PIXI.FederatedEvent) → {void}

Maps the upstream pointerdown events to a downstream pointerdown event.

touchstart, rightdown, mousedown events are also dispatched for specific pointer types.

Parameters:
Name	Type	Description
from	PIXI.FederatedEvent

Returns:
Type	Description
void

mapPointerMove EventBoundary.ts:591

protected mapPointerMove(from: PIXI.FederatedEvent) → {void}

Maps the upstream pointermove to downstream pointerout, pointerover, and pointermove events, in that order.

The tracking data for the specific pointer has an updated overTarget. mouseout, mouseover, mousemove, and touchmove events are fired as well for specific pointer types.

Parameters:
Name	Type	Description
from	PIXI.FederatedEvent	The upstream `pointermove` event.

Returns:
Type	Description
void

mapPointerOut EventBoundary.ts:756

protected mapPointerOut(from: PIXI.FederatedEvent) → {void}

Maps the upstream pointerout to downstream pointerout, pointerleave events, in that order.

The tracking data for the specific pointer is cleared of a overTarget.

Parameters:
Name	Type	Description
from	PIXI.FederatedEvent	The upstream `pointerout` event.

Returns:
Type	Description
void

mapPointerOver EventBoundary.ts:712

protected mapPointerOver(from: PIXI.FederatedEvent) → {void}

Maps the upstream pointerover to downstream pointerover and pointerenter events, in that order.

The tracking data for the specific pointer gets a new overTarget.

Parameters:
Name	Type	Description
from	PIXI.FederatedEvent	The upstream `pointerover` event.

Returns:
Type	Description
void

mapPointerUp EventBoundary.ts:809

protected mapPointerUp(from: PIXI.FederatedEvent) → {void}

Maps the upstream pointerup event to downstream pointerup, pointerupoutside, and click/pointertap events, in that order.

The pointerupoutside event bubbles from the original pointerdown target to the most specific ancestor of the pointerdown and pointerup targets, which is also the click event's target. touchend, rightup, mouseup, touchendoutside, rightupoutside, mouseupoutside, and tap are fired as well for specific pointer types.

Parameters:
Name	Type	Description
from	PIXI.FederatedEvent	The upstream `pointerup` event.

Returns:
Type	Description
void

mapPointerUpOutside EventBoundary.ts:933

protected mapPointerUpOutside(from: PIXI.FederatedEvent) → {void}

Maps the upstream pointerupoutside event to a downstream pointerupoutside event, bubbling from the original pointerdown target to rootTarget.

(The most specific ancestor of the pointerdown event and the pointerup event must the EventBoundary's root because the pointerup event occurred outside of the boundary.)

touchendoutside, mouseupoutside, and rightupoutside events are fired as well for specific pointer types. The tracking data for the specific pointer is cleared of a pressTarget.

Parameters:
Name	Type	Description
from	PIXI.FederatedEvent	The upstream `pointerupoutside` event.

Returns:
Type	Description
void

mapWheel EventBoundary.ts:985

protected mapWheel(from: PIXI.FederatedEvent) → {void}

Maps the upstream wheel event to a downstream wheel event.

Parameters:
Name	Type	Description
from	PIXI.FederatedEvent	The upstream `wheel` event.

Returns:
Type	Description
void

notifyTarget EventBoundary.ts:536

protected notifyTarget(e: PIXI.FederatedEvent, type: string) → {void}

Notify all the listeners to the event's currentTarget.

Parameters:
Name	Type	Attributes	Description
e	PIXI.FederatedEvent		The event passed to the target.
type	string	<optional>

Returns:
Type	Description
void

trackingData EventBoundary.ts:1229

protected trackingData(id: number) → {TrackingData}

Parameters:
Name	Type	Description
id	number	The pointer ID.

Returns:
Type	Description
TrackingData	The tracking data stored for the given pointer. If no data exists, a blank state will be created.