PixiJS

Class: EventBoundary

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 />. 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.js';
import { EventBoundary } from 'pixi.js';
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 Container
{
    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 EventBoundary (rootTarget)

ts:146
Name Type Attributes Description
rootTarget Container <optional>

The holder of the event boundary.

Members

cursor Cursor | string

The cursor preferred by the event targets underneath this boundary.

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.

enableGlobalMoveEvents boolean

Enables the global move events. globalpointermove, globaltouchmove, and globalmousemove

Default Value:
  • true

moveOnAll boolean

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

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 Container

The root event-target residing below the event boundary. All events are dispatched trickling down and bubbling up to this rootTarget.

eventPool Map<typeof FederatedEvent, FederatedEvent[]> protected

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

See:
  • EventBoundary#allocateEvent
  • EventBoundary#freeEvent

mappingState Record<string, any> protected

State object for mapping methods.

See:
  • EventBoundary#trackingData

mappingTable Record<string, 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:
  • EventBoundary#addEventMapping

Methods

addEventMapping (type, fn) void

ts:174

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 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: FederatedEvent) => void

The mapping method. The context of this function must be bound manually, if desired.

all (e, type, targets) void

ts:318

Emits the event e to all interactive containers. The event is propagated in the bubbling phase always.

This is used in the globalpointermove event.

Name Type Attributes Description
e FederatedEvent

The emitted event.
type string | string[] <optional>

The listeners to notify.
targets

The targets to notify.

dispatchEvent (e, type) void

ts:200

Dispatches the given event

Name Type Attributes Description
e FederatedEvent

The event to dispatch.
type string <optional>

The type of event to dispatch. Defaults to e.type.

hitTest (x, y) Container

ts:242

Finds the Container 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

The x coordinate of the event.
y number

The y coordinate of the event.
Returns:
Type Description
Container

mapEvent (e) void

ts:214

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

Name Type Description
e FederatedEvent

The event to map.

propagate (e, type) void

ts:269

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

Name Type Attributes Description
e FederatedEvent

The event to propagate.
type string <optional>

The type of event to propagate. Defaults to e.type.

propagationPath (target) Container[]

ts:346

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

Name Type Description
target Container

The target to find the propagation path to.
Returns:
Type Description
Container[]

allocateEvent (constructor) T protected

ts:1402

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: EventBoundary): T
}

The event's constructor.
Returns:
Type Description
T

clonePointerEvent (from, type) FederatedPointerEvent protected

ts:1244

Clones the event from, with an optional type override.

The event is allocated using this.allocateEvent.

Name Type Attributes Default Description
from FederatedPointerEvent

The event to clone.
type string <optional>
 from.type

The type of the returned event.
Returns:
Type Description
FederatedPointerEvent

copyData (from, to) void protected

ts:1359

Copies base FederatedEvent data from from into to.

The following properties are copied:

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

The event to copy data from.
to FederatedEvent

The event to copy data into.

copyMouseData (from, to) void protected

ts:1321

Copies mouse FederatedMouseEvent data from from to to.

The following properties are copied:

  • altKey
  • button
  • buttons
  • clientX
  • clientY
  • metaKey
  • movementX
  • movementY
  • pageX
  • pageY
  • x
  • y
  • screen
  • shiftKey
  • global
Name Type Description
from FederatedEvent

The event to copy data from.
to FederatedEvent

The event to copy data into.

copyPointerData (from, to) void protected

ts:1289

Copies pointer FederatedPointerEvent data from from into to.

The following properties are copied:

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

The event to copy data from.
to FederatedEvent

The event to copy data into.

copyWheelData (from, to) void protected

ts:1270

Copies wheel FederatedWheelEvent data from from into to.

The following properties are copied:

  • deltaMode
  • deltaX
  • deltaY
  • deltaZ
Name Type Description
from FederatedWheelEvent

The event to copy data from.
to FederatedWheelEvent

The event to copy data into.

createPointerEvent (from, type, target) FederatedPointerEvent protected

ts:1189

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 FederatedPointerEvent

The originalEvent for the returned event.
type string <optional>
 from.type

The type of the returned event.
target Container <optional>

The target of the returned event.
Returns:
Type Description
FederatedPointerEvent

createWheelEvent (from) FederatedWheelEvent protected

ts:1223

Creates a wheel event whose originalEvent is from.

The event is allocated using this.allocateEvent.

Name Type Description
from FederatedWheelEvent

The upstream wheel event.
Returns:
Type Description
FederatedWheelEvent

findMountedTarget (propagationPath) Container protected

ts:1155

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 Container[]

The propagation path was valid in the past.
Returns:
Type Description
Container
  • The most specific event-target still mounted at the same location in the scene graph.

freeEvent (event) void protected

ts:1430

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 (container, location) boolean protected

ts:571

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

EventBoundary's implementation uses the hitArea and {@link Container._maskEffect} for pruning.

Name Type Description
container Container

The container to prune.
location Point

The location to test for overlap.
Returns:
Type Description
boolean

hitTestFn (container, location) boolean protected

ts:612

Checks whether the container passes hit testing for the given location.

Name Type Description
container Container

The container to test.
location Point

The location to test for overlap.
Returns:
Type Description
boolean
  • Whether container passes hit testing for location.

hitTestRecursive (currentTarget, eventMode, location, testFn, pruneFn) Container[] protected

ts:458

Recursive implementation for hitTest.

Name Type Description
currentTarget Container

The Container that is to be hit tested.
eventMode EventMode

The event mode for the currentTarget or one of its parents.
location Point

The location that is being tested for overlap.
testFn (object: Container, pt: Point) => boolean

Callback that determines whether the target passes hit testing. This callback can assume that pruneFn failed to prune the container.
pruneFn (object: Container, pt: Point) => boolean

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
Container[] 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

ts:670

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 FederatedEvent

The upstream pointerdown event.

mapPointerMove (from) void protected

ts:709

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 FederatedEvent

The upstream pointermove event.

mapPointerOut (from) void protected

ts:897

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 FederatedEvent

The upstream pointerout event.

mapPointerOver (from) void protected

ts:851

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 FederatedEvent

The upstream pointerover event.

mapPointerUp (from) void protected

ts:952

Maps the upstream pointerup event to downstream pointerup, pointerupoutside, and click/rightclick/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 FederatedEvent

The upstream pointerup event.

mapPointerUpOutside (from) void protected

ts:1080

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 FederatedEvent

The upstream pointerupoutside event.

mapWheel (from) void protected

ts:1134

Maps the upstream wheel event to a downstream wheel event.

Name Type Description
from FederatedEvent

The upstream wheel event.

notifyTarget (e, type) void protected

ts:638

Notify all the listeners to the event's currentTarget.

If the currentTarget contains the property on<type>, then it is called here, simulating the behavior from version 6.x and prior.

Name Type Attributes Description
e FederatedEvent

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

The type of event to notify. Defaults to e.type.

trackingData (id) TrackingData protected

ts:1383
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.