PixiJS

Class: EventBoundary

PIXI.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
    }
}

new PIXI.EventBoundary (rootTarget)

EventBoundary.ts:176
Name Type Attributes Description
rootTarget PIXI.DisplayObject <optional>

The holder of the event boundary.

Members

cursor Cursor | string

The cursor preferred by the event targets underneath this boundary.

dispatch utils.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 boolean

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.

Default Value:
  • false

rootTarget PIXI.DisplayObject

The root event-target residing below the event boundary.

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

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

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

See:

mappingState Record<string, any> protected

State object for mapping methods.

See:

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

Maps event types to forwarding handles for them.

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

See:

Methods

addEventMapping (type, fn) void

EventBoundary.ts:204

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.

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.

all (e, type, target) void

EventBoundary.ts:342

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.

Name Type Attributes Description
e PIXI.FederatedEvent

The emitted event.
type string <optional>

The listeners to notify.
target PIXI.FederatedEventTarget

dispatchEvent (e, type) void

EventBoundary.ts:230

Dispatches the given event

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

hitTest (x, y) PIXI.DisplayObject

EventBoundary.ts:270

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.

Name Type Description
x number
y number
Returns:
Type Description
PIXI.DisplayObject

mapEvent (e) void

EventBoundary.ts:244

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

Name Type Description
e PIXI.FederatedEvent

propagate (e, type) void

EventBoundary.ts:293

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

Name Type Attributes Description
e PIXI.FederatedEvent

The event to propagate.
type string <optional>

propagationPath (target) PIXI.FederatedEventTarget[]

EventBoundary.ts:368

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

Name Type Description
target PIXI.FederatedEventTarget
Returns:
Type Description
PIXI.FederatedEventTarget[]

allocateEvent (constructor) T protected

EventBoundary.ts:1247

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.

Name Type Description
constructor { new (boundary: PIXI.EventBoundary): T }

The event's constructor.
Returns:
Type Description
T

clonePointerEvent (from, type) PIXI.FederatedPointerEvent protected

EventBoundary.ts:1090

Clones the event from, with an optional type override.

The event is allocated using this.allocateEvent.

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 (from, to) void protected

EventBoundary.ts:1204

Copies base PIXI.FederatedEvent data from from into to.

The following properties are copied:

  • isTrusted
  • srcElement
  • timeStamp
  • type
Name Type Description
from PIXI.FederatedEvent

The event to copy data from.
to PIXI.FederatedEvent

The event to copy data into.

copyMouseData (from, to) void protected

EventBoundary.ts:1167

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
Name Type Description
from PIXI.FederatedEvent
to PIXI.FederatedEvent

copyPointerData (from, to) void protected

EventBoundary.ts:1135

Copies pointer PIXI.FederatedPointerEvent data from from into to.

The following properties are copied:

  • pointerId
  • width
  • height
  • isPrimary
  • pointerType
  • pressure
  • tangentialPressure
  • tiltX
  • tiltY
Name Type Description
from PIXI.FederatedEvent
to PIXI.FederatedEvent

copyWheelData (from, to) void protected

EventBoundary.ts:1116

Copies wheel PIXI.FederatedWheelEvent data from from into to.

The following properties are copied:

  • deltaMode
  • deltaX
  • deltaY
  • deltaZ
Name Type Description
from PIXI.FederatedWheelEvent
to PIXI.FederatedWheelEvent

createPointerEvent (from, type, target) PIXI.FederatedPointerEvent protected

EventBoundary.ts:1037

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

The event is allocated using this.allocateEvent.

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 (from) PIXI.FederatedWheelEvent protected

EventBoundary.ts:1069

Creates a wheel event whose originalEvent is from.

The event is allocated using this.allocateEvent.

Name Type Description
from PIXI.FederatedWheelEvent

The upstream wheel event.
Returns:
Type Description
PIXI.FederatedWheelEvent

findMountedTarget (propagationPath) PIXI.FederatedEventTarget protected

EventBoundary.ts:1003

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.

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 (event) void protected

EventBoundary.ts:1274

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.

Name Type Description
event T

The event to be freed.

hitPruneFn (displayObject, location) boolean protected

EventBoundary.ts:477

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.

Name Type Description
displayObject PIXI.DisplayObject
location PIXI.Point
Returns:
Type Description
boolean

hitTestFn (displayObject, location) boolean protected

EventBoundary.ts:511

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

Name Type Description
displayObject PIXI.DisplayObject
location PIXI.Point
Returns:
Type Description
boolean
  • Whether displayObject passes hit testing for location.

hitTestRecursive (currentTarget, interactive, location, testFn, pruneFn) PIXI.DisplayObject[] protected

EventBoundary.ts:394

Recursive implementation for hitTest.

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 (from) void protected

EventBoundary.ts:553

Maps the upstream pointerdown events to a downstream pointerdown event.

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

Name Type Description
from PIXI.FederatedEvent

mapPointerMove (from) void protected

EventBoundary.ts:590

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.

Name Type Description
from PIXI.FederatedEvent

The upstream pointermove event.

mapPointerOut (from) void protected

EventBoundary.ts:755

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

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

Name Type Description
from PIXI.FederatedEvent

The upstream pointerout event.

mapPointerOver (from) void protected

EventBoundary.ts:711

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

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

Name Type Description
from PIXI.FederatedEvent

The upstream pointerover event.

mapPointerUp (from) void protected

EventBoundary.ts:808

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.

Name Type Description
from PIXI.FederatedEvent

The upstream pointerup event.

mapPointerUpOutside (from) void protected

EventBoundary.ts:932

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.

Name Type Description
from PIXI.FederatedEvent

The upstream pointerupoutside event.

mapWheel (from) void protected

EventBoundary.ts:984

Maps the upstream wheel event to a downstream wheel event.

Name Type Description
from PIXI.FederatedEvent

The upstream wheel event.

notifyTarget (e, type) void protected

EventBoundary.ts:535

Notify all the listeners to the event's currentTarget.

Name Type Attributes Description
e PIXI.FederatedEvent

The event passed to the target.
type string <optional>

trackingData (id) TrackingData protected

EventBoundary.ts:1228
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.