Pixi’VNClass: EventBoundary
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:66
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
}
}
Advanced
Constructors
Constructor
> new EventBoundary(rootTarget?): EventBoundary
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:124
Parameters
rootTarget?
The holder of the event boundary.
Returns
EventBoundary
Properties
cursor
> cursor: Cursor | string & object
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:83
The cursor preferred by the event targets underneath this boundary.
dispatch
> dispatch: EventEmitter
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:81
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
> enableGlobalMoveEvents: boolean
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:92
Enables the global move events. globalpointermove, globaltouchmove, and globalmousemove
eventPool
> protected eventPool: Map<typeof FederatedEvent, FederatedEvent<UIEvent | PixiTouch>[]>
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:114
The event pool maps event constructors to an free pool of instances of those specific events.
See
- EventBoundary#allocateEvent
- EventBoundary#freeEvent
mappingState
> protected mappingState: Record<string, any>
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:108
State object for mapping methods.
See
EventBoundary#trackingData
mappingTable
> protected mappingTable: Record<string, object[]>
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:100
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
moveOnAll
> moveOnAll: boolean
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:90
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.
rootTarget
> rootTarget: Container
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:71
The root event-target residing below the event boundary.
All events are dispatched trickling down and bubbling up to this rootTarget.
Methods
addEventMapping()
> addEventMapping(type, fn): void
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:137
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.
Parameters
type
string
The type of upstream event to map.
fn
(e) => void
The mapping method. The context of this function must be bound manually, if desired.
Returns
void
all()
> all(e, type?, targets?): void
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:172
Emits the event e to all interactive containers. The event is propagated in the bubbling phase always.
This is used in the globalpointermove event.
Parameters
e
The emitted event.
type?
string | string[]
The listeners to notify.
targets?
The targets to notify.
Returns
void
allocateEvent()
> protected allocateEvent<T>(constructor): T
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:390
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.
Type Parameters
T
T extends FederatedEvent<UIEvent | PixiTouch>
Parameters
constructor
(boundary) => T
The event's constructor.
Returns
T
An event of the given type.
clonePointerEvent()
> protected clonePointerEvent(from, type?): FederatedPointerEvent
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:311
Clones the event from, with an optional type override.
The event is allocated using this.allocateEvent.
Parameters
from
The event to clone.
type?
string
The type of the returned event.
Returns
copyData()
> protected copyData(from, to): void
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:375
Copies base FederatedEvent data from from into to.
The following properties are copied:
- isTrusted
- srcElement
- timeStamp
- type
Parameters
from
The event to copy data from.
to
The event to copy data into.
Returns
void
copyMouseData()
> protected copyMouseData(from, to): void
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:363
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
Parameters
from
The event to copy data from.
to
The event to copy data into.
Returns
void
copyPointerData()
> protected copyPointerData(from, to): void
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:340
Copies pointer FederatedPointerEvent data from from into to.
The following properties are copied:
- pointerId
- width
- height
- isPrimary
- pointerType
- pressure
- tangentialPressure
- tiltX
- tiltY
Parameters
from
The event to copy data from.
to
The event to copy data into.
Returns
void
copyWheelData()
> protected copyWheelData(from, to): void
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:323
Copies wheel FederatedWheelEvent data from from into to.
The following properties are copied:
- deltaMode
- deltaX
- deltaY
- deltaZ
Parameters
from
The event to copy data from.
to
The event to copy data into.
Returns
void
createPointerEvent()
> protected createPointerEvent(from, type?, target?): FederatedPointerEvent
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:296
Creates an event whose originalEvent is from, with an optional type and target override.
The event is allocated using this.allocateEvent.
Parameters
from
The originalEvent for the returned event.
type?
string
The type of the returned event.
target?
The target of the returned event.
Returns
createWheelEvent()
> protected createWheelEvent(from): FederatedWheelEvent
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:303
Creates a wheel event whose originalEvent is from.
The event is allocated using this.allocateEvent.
Parameters
from
The upstream wheel event.
Returns
dispatchEvent()
> dispatchEvent(e, type?): void
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:143
Dispatches the given event
Parameters
e
The event to dispatch.
type?
string
The type of event to dispatch. Defaults to e.type.
Returns
void
findMountedTarget()
> protected findMountedTarget(propagationPath): Container
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:287
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
propagationPath
The propagation path was valid in the past.
Returns
- The most specific event-target still mounted at the same location in the scene graph.
freeEvent()
> protected freeEvent<T>(event): void
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:404
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.
Type Parameters
T
T extends FederatedEvent<UIEvent | PixiTouch>
Parameters
event
T
The event to be freed.
Returns
void
Throws
Error if the event is managed by another event boundary.
hitPruneFn()
> protected hitPruneFn(container, location): boolean
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:205
Checks whether the container or any of its children cannot pass the hit test at all.
EventBoundary's implementation uses the hitArea and Container._maskEffect for pruning.
Parameters
container
The container to prune.
location
The location to test for overlap.
Returns
boolean
hitTest()
> hitTest(x, y): Container
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:156
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.
Parameters
x
number
The x coordinate of the event.
y
number
The y coordinate of the event.
Returns
hitTestFn()
> protected hitTestFn(container, location): boolean
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:212
Checks whether the container passes hit testing for the given location.
Parameters
container
The container to test.
location
The location to test for overlap.
Returns
boolean
- Whether
containerpasses hit testing forlocation.
hitTestMoveRecursive()
> protected hitTestMoveRecursive(currentTarget, eventMode, location, testFn, pruneFn, ignore?): Container<ContainerChild>[]
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:179
Parameters
currentTarget
eventMode
location
testFn
(object, pt) => boolean
pruneFn
(object, pt) => boolean
ignore?
boolean
Returns
hitTestRecursive()
> protected hitTestRecursive(currentTarget, eventMode, location, testFn, pruneFn): Container<ContainerChild>[]
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:194
Recursive implementation for hitTest.
Parameters
currentTarget
The Container that is to be hit tested.
eventMode
The event mode for the currentTarget or one of its parents.
location
The location that is being tested for overlap.
testFn
(object, pt) => boolean
Callback that determines whether the target passes hit testing. This callback
can assume that pruneFn failed to prune the container.
pruneFn
(object, pt) => 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
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.
mapEvent()
> mapEvent(e): void
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:148
Maps the given upstream event through the event boundary and propagates it downstream.
Parameters
e
The event to map.
Returns
void
mapPointerDown()
> protected mapPointerDown(from): void
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:228
Maps the upstream pointerdown events to a downstream pointerdown event.
touchstart, rightdown, mousedown events are also dispatched for specific pointer types.
Parameters
from
The upstream pointerdown event.
Returns
void
mapPointerMove()
> protected mapPointerMove(from): void
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:236
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
from
The upstream pointermove event.
Returns
void
mapPointerOut()
> protected mapPointerOut(from): void
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:250
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
from
The upstream pointerout event.
Returns
void
mapPointerOver()
> protected mapPointerOver(from): void
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:243
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
from
The upstream pointerover event.
Returns
void
mapPointerUp()
> protected mapPointerUp(from): void
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:261
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.
Parameters
from
The upstream pointerup event.
Returns
void
mapPointerUpOutside()
> protected mapPointerUpOutside(from): void
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:273
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
{@link 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
from
The upstream pointerupoutside event.
Returns
void
mapWheel()
> protected mapWheel(from): void
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:278
Maps the upstream wheel event to a downstream wheel event.
Parameters
from
The upstream wheel event.
Returns
void
notifyTarget()
> protected notifyTarget(e, type?): void
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:221
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.
Parameters
e
The event passed to the target.
type?
string
The type of event to notify. Defaults to e.type.
Returns
void
propagate()
> propagate(e, type?): void
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:163
Propagate the passed event from from this.rootTarget to its
target e.target.
Parameters
e
The event to propagate.
type?
string
The type of event to propagate. Defaults to e.type.
Returns
void
propagationPath()
> propagationPath(target): Container<ContainerChild>[]
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:178
Finds the propagation path from rootTarget to the passed
target. The last element in the path is target.
Parameters
target
The target to find the propagation path to.
Returns
trackingData()
> protected trackingData(id): TrackingData
Defined in: node_modules/pixi.js/lib/events/EventBoundary.d.ts:381
Parameters
id
number
The pointer ID.
Returns
The tracking data stored for the given pointer. If no data exists, a blank state will be created.