Class: EventDispatcher

EventDispatcher()

EventDispatcher provides methods for managing queues of event listeners and dispatching events. You can either extend EventDispatcher or mix its methods into an existing prototype or instance by using the EventDispatcher core.EventDispatcher.initialize method. Together with the CreateJS Event class, EventDispatcher provides an extended event model that is based on the DOM Level 2 event model, including addEventListener, removeEventListener, and dispatchEvent. It supports bubbling / capture, preventDefault, stopPropagation, stopImmediatePropagation, and handleEvent. EventDispatcher also exposes a core.EventDispatcher#on method, which makes it easier to create scoped listeners, listeners that only run once, and listeners with associated arbitrary data. The core.EventDispatcher#off method is merely an alias to core.EventDispatcher#removeEventListener. Another addition to the DOM Level 2 model is the core.EventDispatcher#removeAllEventListeners method, which can be used to listeners for all events, or listeners for a specific event. The Event object also includes a core.Event#remove method which removes the active listener.

Constructor

new EventDispatcher()

Source:
Example
// add EventDispatcher capabilities to the "MyClass" class.
EventDispatcher.initialize(MyClass.prototype);

// Add an event.
instance.addEventListener("eventName", event => console.log(event.target + " was clicked."));

// scope ("this") can be be a challenge with events.
// using the core.EventDispatcher#on method to subscribe to events simplifies this.
instance.addEventListener("click", event => console.log(instance === this)); // false, scope is ambiguous.
instance.on("click", event => console.log(instance === this)); // true, `on` uses dispatcher scope by default.

Methods

Name Description
initialize Static initializer to mix EventDispatcher methods into a target object or prototype.
addEventListener Adds the specified event listener. Note that adding multiple listeners to the same function will result in multiple callbacks getting fired.
dispatchEvent Dispatches the specified event to all listeners.
hasEventListener Indicates whether there is at least one listener for the specified event type.
off A shortcut to the removeEventListener method, with the same parameters and return value. This is a companion to the `on` method. To remove a listener added with `on`, you must pass in the returned wrapper function as the listener. See core.EventDispatcher#on for an example.
on A shortcut method for using addEventListener that makes it easier to specify an execution scope, have a listener only run once, associate arbitrary data with the listener, and remove the listener. This method works by creating an anonymous wrapper function and subscribing it with `addEventListener`. The wrapper function is returned for use with `removeEventListener` (or `off`). To remove a listener added with `on`, you must pass in the returned wrapper function as the listener, or use core.Event#remove. Likewise, each time you call `on` a NEW wrapper function is subscribed, so multiple calls to `on` with the same params will create multiple listeners.
removeAllEventListeners Removes all listeners for the specified type, or all listeners of all types.
removeEventListener Removes the specified event listener. You must pass the exact function reference used when the event was added. If a proxy function, or function closure is used as the callback, the proxy/closure reference must be used - a new proxy or closure will not work.
toString
willTrigger Indicates whether there is at least one listener for the specified event type on this object or any of its ancestors (parent, parent's parent, etc). A return value of true indicates that if a bubbling event of the specified type is dispatched from this object, it will trigger at least one listener. This is similar to core.EventDispatcher#hasEventListener, but it searches the entire event flow for a listener, not just this object.


(static) initialize(target)

Static initializer to mix EventDispatcher methods into a target object or prototype.
Parameters:
Name Type Description
target Object The target object to inject EventDispatcher methods into.
Source:
Example
EventDispatcher.initialize(MyClass.prototype); // add to the prototype of the class
EventDispatcher.initialize(myInstance); // add to a specific instance

addEventListener(type, listener, useCaptureopt) → {function|Object}

Adds the specified event listener. Note that adding multiple listeners to the same function will result in multiple callbacks getting fired.
Parameters:
Name Type Attributes Default Description
type string The string type of the event.
listener function | Object An object with a handleEvent method, or a function that will be called when the event is dispatched.
useCapture boolean <optional>
 false For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.
Source:
Returns:
Returns the listener for chaining or assignment.
Type
function | Object
Example
displayObject.addEventListener("click", event => console.log('clicked', event));

dispatchEvent(eventObj, bubblesopt, cancelableopt) → {boolean}

Dispatches the specified event to all listeners.
Parameters:
Name Type Attributes Default Description
eventObj Object | Event | string An object with a "type" property, or a string type. While a generic object will work, it is recommended to use a CreateJS Event instance. If a string is used, dispatchEvent will construct an Event instance if necessary with the specified type. This latter approach can be used to avoid event object instantiation for non-bubbling events that may not have any listeners.
bubbles boolean <optional>
 false Specifies the `bubbles` value when a string was passed to eventObj.
cancelable boolean <optional>
 false Specifies the `cancelable` value when a string was passed to eventObj.
Source:
Returns:
Returns false if `preventDefault()` was called on a cancelable event, true otherwise.
Type
boolean
Example
// use a string event
this.dispatchEvent("complete")

// use an Event instance
const event = new createjs.Event("progress");
this.dispatchEvent(event);

hasEventListener(type) → {boolean}

Indicates whether there is at least one listener for the specified event type.
Parameters:
Name Type Description
type string The string type of the event.
Source:
Returns:
Returns true if there is at least one listener for the specified event.
Type
boolean

off(type, listener, useCaptureopt)

A shortcut to the removeEventListener method, with the same parameters and return value. This is a companion to the `on` method. To remove a listener added with `on`, you must pass in the returned wrapper function as the listener. See core.EventDispatcher#on for an example.
Parameters:
Name Type Attributes Default Description
type string The string type of the event.
listener function | Object The listener function or object.
useCapture boolean <optional>
 false For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.
Source:

on(type, listener, scopeopt, onceopt, dataopt, useCaptureopt) → {function}

A shortcut method for using addEventListener that makes it easier to specify an execution scope, have a listener only run once, associate arbitrary data with the listener, and remove the listener. This method works by creating an anonymous wrapper function and subscribing it with `addEventListener`. The wrapper function is returned for use with `removeEventListener` (or `off`). To remove a listener added with `on`, you must pass in the returned wrapper function as the listener, or use core.Event#remove. Likewise, each time you call `on` a NEW wrapper function is subscribed, so multiple calls to `on` with the same params will create multiple listeners.
Parameters:
Name Type Attributes Default Description
type string The string type of the event.
listener function | Object An object with a handleEvent method, or a function that will be called when the event is dispatched.
scope Object <optional>
 null The scope to execute the listener in. Defaults to the dispatcher/currentTarget for function listeners, and to the listener itself for object listeners (ie. using handleEvent).
once boolean <optional>
 false If true, the listener will remove itself after the first time it is triggered.
data * <optional>
 {} Arbitrary data that will be included as the second parameter when the listener is called.
useCapture boolean <optional>
 false For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.
Source:
Returns:
Returns the anonymous function that was created and assigned as the listener. This is needed to remove the listener later using .removeEventListener.
Type
function
Example
const listener = myBtn.on("click", handleClick, null, false, { count: 3 });
function handleClick (evt, data) {
  data.count -= 1;
  console.log(this == myBtn); // true - scope defaults to the dispatcher
  if (data.count == 0) {
    alert("clicked 3 times!");
    myBtn.off("click", listener);
    // alternately: evt.remove();
  }
}

removeAllEventListeners(typeopt)

Removes all listeners for the specified type, or all listeners of all types.
Parameters:
Name Type Attributes Default Description
type string <optional>
 null The string type of the event. If omitted, all listeners for all types will be removed.
Source:
Example
// remove all listeners
displayObject.removeAllEventListeners();

// remove all click listeners
displayObject.removeAllEventListeners("click");

removeEventListener(type, listener, useCaptureopt)

Removes the specified event listener. You must pass the exact function reference used when the event was added. If a proxy function, or function closure is used as the callback, the proxy/closure reference must be used - a new proxy or closure will not work.
Parameters:
Name Type Attributes Default Description
type string The string type of the event.
listener function | Object The listener function or object.
useCapture boolean <optional>
 false For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.
Source:
Example
displayObject.removeEventListener("click", handleClick);

toString() → {String}

Source:
Returns:
a string representation of the instance.
Type
String

willTrigger(type) → {boolean}

Indicates whether there is at least one listener for the specified event type on this object or any of its ancestors (parent, parent's parent, etc). A return value of true indicates that if a bubbling event of the specified type is dispatched from this object, it will trigger at least one listener. This is similar to core.EventDispatcher#hasEventListener, but it searches the entire event flow for a listener, not just this object.
Parameters:
Name Type Description
type string The string type of the event.
Source:
Returns:
Returns `true` if there is at least one listener for the specified event.
Type
boolean