Options
All
  • Public
  • Public/Protected
  • All
Menu

Class EventDispatcher<TEvent>

Base class that adds the ability to dispatch events and attach handlers that should be called when such events are triggered.

This EventDispatcher also supports event capturing and bubbling phases, heavily inspired by existing event dispatching systems like the functionality described in the DOM Event W3 spec

Type parameters

  • TEvent: AbstractEvent

    The type of the events that this EventDispatcher is expected to dispatch. To allow for multiple event classes, use a union type here. If you don't specify an event type, any event that extends AbstractEvent can be dispatched, but you won't get automatic typing for event handlers.

Hierarchy

  • Disposable
    • EventDispatcher

Implements

  • IDisposable

Index

Constructors

Properties

Methods

Constructors

constructor

  • Creates an EventDispatcher instance.

    example

    You can use the target parameter to proxy the EventDispatcher instead of extending it directly.

    class Foo {
  public dispatcher:EventDispatcher<FooEvent>;

  constructor() {
    this.dispatcher = new EventDispatcher<FooEvent>(null, this);
  }

  ...
};

    Parameters

    • Default value parent: EventDispatcher | null = null

      If set, registers the given EventDispatcher instance as parent. This child-parent relationship is used in the event chain during the capture phase of events and the bubbling phase of bubbling events. For more information on event bubbling and capturing, see dispatchEvent

    • Optional target: EventDispatcher

      If set, will set the target attribute of all events dispatched by this EventDispatcher to the given object. If not set, will use this instance as a target for dispatched events.

    Returns EventDispatcher

Properties

Protected listeners

listeners: EventListenerMap<TEvent>

An object containing all event listeners by event type. Each value on this object is an Array of EventListenerData objects for each event listener added with that type.

parent

parent: EventDispatcher | null

The parent EventDispatcher instance. If this instance has no parent, this value will be set to null. The parent is used in the bubbling and capturing phases of events.

see

dispatchEvent for more information on the bubbling and capturing chain

Protected target

target: EventDispatcher

The value that will be set as target on events that are dispatched by this EventDispatcher instance. Set to the value passed to the constructor

Methods

addEventListener

  • Adds a new event listener. The given handler function will be called in the following cases:

    • An event with a type that is equal to the given eventType is dispatched on this EventDispatcher instance.
    • An event with a type that is equal to the given eventType is dispatched on a child EventDispatcher, and the useCapture parameter is set to true
    • An event with bubbles set to true and a type that is equal to the given eventType is dispatched on a child EventDispatcher, and the useCapture parameter is set to false
    see

    dispatchEvent for more info on the which event listeners are called during capturing and bubbling

    Type parameters

    Parameters

    • eventType: TType

      The eventType to listen for

    • handler: EventHandlerForEvent<ExtractEventOfType<TEvent, TType>>

      The handler function that will be called when a matching event is dispatched. This function will retrieve the dispatched event as a parameter

    • Default value useCapture: boolean = false

      Indicates if this handler should be called during the capturing phase of an event chain. If and only if this is set to false will this handler be called during the bubbling phase of an event chain.

    • Default value priority: number = 0

      A number that indicates the priority of this event listener relative to other event listeners of the same type on this EventDispatcher instance. A higher number indicates that this listener will be called earlier.

    Returns EventListenerData<TEvent>

    An object describing the listener that has a dispose() method to remove the listener.

dispatchEvent

  • dispatchEvent(event: TEvent): boolean

  • Dispatches the given event. The dispatch consists of three phases:

    1. The capture phase. We walk through all ancestors of this EventDispatcher, with the top-most instance first and the direct parent of this EventDispatcher last. On each ancestor, we call all event handlers that are added with the useCapture argument set to true and the eventType set to the same type as the given event. If this EventDispatcher has no parent, this phase will be skipped.
    2. The target phase. In this phase we call all event handlers on this EventDispatcher instance that listen for the same type as the given event.
    3. The bubbling phase. This phase will only be executed if the given event has the bubbles property set to true. If so, we will again walk through all ancestors of this EventDispatcher, but in the reverse order: the direct parent of this instance first and the top-most parent last. On every ancestor, we will call all event handlers that are added with the useCapture argument set to false and the eventType set to the same type as the given event.

    If any of the event handlers call stopPropagation(), we will skip all event handlers that occur on a target later in the event chain. If an event handler calls stopImmediatePropagation(), we will also skip any event handlers on the same target in the event chain.

    Parameters

    • event: TEvent

      The event to dispatch

    Returns boolean

    If one of the handlers that have been called during this dispatch called event.preventDefault(), this method will return false. If no handlers have been called or none of the handlers have called event.preventDefault(), this method will return true.

    Please note: preventDefault() can only be called on events that have their cancelable property set to true

dispose

  • dispose(): void

  • Cleans up this EventListener instance. No event handlers on this EventDispatcher will be called and future calls to dispatchEvent() will be ignored.

    Returns void

hasEventListener

  • Checks if an event listener matching the given parameters exists on this EventDispatcher instance.

    Type parameters

    Parameters

    • eventType: TType

      Will only look for event listeners with this eventType

    • Optional handler: EventHandlerForEvent<ExtractEventOfType<TEvent, TType>>

      If set, will only match event listeners that have the same handler function

    • Optional useCapture: undefined | false | true

      If set, will only match event listeners that have the same useCapture argument.

      Please note: if no useCapture argument was provided to addEventListener, it is set to false by default

    Returns boolean

    True if one or more event listeners exist

isDisposed

  • isDisposed(): boolean

  • After dispose has been called, this method returns true. Use this method to determine whether dispose() should be run again.

    Returns boolean

Protected listenerSorter

  • Method that is used to sort arrays of event listeners based on their priority property. Higher priority will be sorted before lower priority values.

    Parameters

    Returns number

    A number that indicates the sorting according to the JS sort() method.

removeAllEventListeners

  • removeAllEventListeners(eventType?: TypesForEvent<TEvent>): void

  • Removes all event listeners that have a type of the given eventType from this EventDispatcher instance, regardless of their handler or useCapture property.

    Please note: if you remove an event listener during the dispatch of an event it will not be called anymore, even if it was supposed to be called in the same event chain

    Parameters

    • Optional eventType: TypesForEvent<TEvent>

      The type of event to remove. If not provided, all event listeners will be removed regardless of their type.

    Returns void

removeEventListener

  • removeEventListener<TType>(eventType: TType, handler: EventHandlerForEvent<any>, useCapture?: boolean): void

  • Removes all event listeners that match the given parameters from this EventDispatcher instance.

    Please note: if you remove an event listener during the dispatch of an event it will not be called anymore, even if it was supposed to be called in the same event chain

    Type parameters

    Parameters

    • eventType: TType

      Only event listeners of that have this eventType are removed

    • handler: EventHandlerForEvent<any>

      Only event listeners that have this handler function will be removed

    • Default value useCapture: boolean = false

      Only event listeners that have been added with the same useCapture parameter will be removed. Please note: if no useCapture argument is provided, only event listeners that have useCapture set to false will be removed.

    Returns void

willTrigger

  • Checks if an event listener with a type of the given eventType exists on this EventDispatcher or any ancestor EventDispatcher instance.

    Parameters

    Returns boolean

    true if a matching listener is found

Generated using TypeDoc