API Docs

Class: EventDispatcher

PD. EventDispatcher

Defines an event manager for publishing and subscribing to framework events.

Events provide an arms-length way that the NLB Framework can communicate with custom classes and the user interface of its host application. It prevents framework data from being directly exposed to any bi-directional reactivity that the UI may use, whilst allowing the UI itself to pick and choose which events it will respond to.

This class uses a slightly modified version of the event dispatch pattern used in THREE.js which you may be used to. The key difference is that the framework uses a dispatch(type, ...args) method that does not require a bespoke object for storing each event's properties so that it can be passed as a single argument to each listener. Rather, it passes all of the additional arguments given in the dispatch method call on to each of the event handlers. It also returns a boolean indicating whether or not there were any listeners called for that event.

This makes message passing a bit more flexible as it allows custom classes to generate their own custom events without having to create and/or register a bespoke event object. As a result, only that custom class (and any related classes) needs to know anything about the event type and what arguments to expect.

NOTE: It is important to use a unique prefix for your custom event names (other than '!pd-' which is used by the framework) in order to prevent them conflicting with custom events that may be generated by other user's classes.

Access to model events is typically via the PD.GlobalEvents instance, which is automatically created when you include src/pd/app/pd.global-events.js. However, there are also events that are specific to a particular scene viewer or editor.

new EventDispatcher()

Creates a new event dispatcher.

Author:
  • drajmarsh

Methods

addEventListener(type, listener)

Adds or replaces a listener function.

This method returns the listener function which allows a caller to use an unnamed or arrow function defined within the call and still store it for later removal.

Parameters:
Name Type Description
type string

The type of event to listen to.
listener function

The function that gets called when the event is fired.
Returns:

Returns the listener function so it can be stored for later removal.

Type
function
Example
let event_listener;

onMounted() {
    event_listener = PD.GlobalEvents.addEventListener(PD.EVENT.SITE_LOCATION, (location) => {
        this.doSomethingWithTheLocation(location);
    });
};

onUnmounted() {
    if (event_listener) {
        PD.GlobalEvents.removeEventListener(PD.EVENT.SITE_LOCATION, event_listener);
        event_listener = null;
    }
};

dispatch(type, args)

Invokes all the listeners for the given event type with the given arguments.

NOTE: This method is different to the standard dispatchEvent() method on THREE.EventDispatcher that you may be used to. The THREE.js method requires a bespoke event object with the event arguments as properties of that object. It also modifies that object by adding an additional target property prior to sending, and creates a copy of the listener array on every call.

In our case, events may be generated many times a second as the view, location and/or sun-position are changed dynamically. The listener methods are all called in a tight loop and, given the nature of framework events, they do not remove themselves when called, so changes to the listener array during iteration are unlikely enough for the risk to be tolerable. Also, the dispatching object is typically static and globally available, so there is no need to send a reference to each listener. Whilst having to create a transitory event object, modify it and then copy the array may be a relatively small overhead, it is still an unnecessary one.

As a result, this method simply passes on the given event arguments to each listener without requiring a custom object, modifying it or copying the listener array each time.

Parameters:
Name Type Argument Description
type string

The event type identifier.
args any <repeatable>

The additional arguments that correspond to the given event type.
Returns:

Returns true if at least one event listener was invoked, otherwise false.

Type
boolean

hasEventListener(type, listener)

Determines if the given listener function is associated with the given event type.

Parameters:
Name Type Description
type string

The type of event to listen to.
listener function

The function that gets called when the event is fired.
Returns:

Returns true if the listener function exists.

Type
boolean

hasEventListeners(type)

Determines if an event has any registered listeners.

Parameters:
Name Type Description
type string

The type of event to check.
Returns:

Returns true if there is more than one listener for the given event.

Type
boolean

removeEventListener(type, listener)

Removes the given listener function from the given event type.

Parameters:
Name Type Description
type string

The type of event to listen to.
listener function

The function that gets called when the event is fired.
Returns:

Returns true if the listener function was found and removed.

Type
boolean