API Documentation for: 0.5.0
Show:

EventDispatcher Class

Defined in: EventDispatcher:39
Module: CreateJS

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 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 on method, which makes it easier to create scoped listeners, listeners that only run once, and listeners with associated arbitrary data. The off method is merely an alias to removeEventListener.

Another addition to the DOM Level 2 model is the removeAllEventListeners method, which can be used to listeners for all events, or listeners for a specific event. The Event object also includes a remove method which removes the active listener.

Example

Add EventDispatcher capabilities to the "MyClass" class.

 EventDispatcher.initialize(MyClass.prototype);

Add an event (see addEventListener).

 instance.addEventListener("eventName", handlerMethod);
 function handlerMethod(event) {
     console.log(event.target + " Was Clicked");
 }

Maintaining proper scope
Scope (ie. "this") can be be a challenge with events. Using the on method to subscribe to events simplifies this.

 instance.addEventListener("click", function(event) {
     console.log(instance == this); // false, scope is ambiguous.
 });

 instance.on("click", function(event) {
     console.log(instance == this); // true, "on" uses dispatcher scope by default.
 });

If you want to use addEventListener instead, you may want to use function.bind() or a similar proxy to manage scope.

Constructor

EventDispatcher

()

Defined in EventDispatcher:39

Methods

_dispatchEvent

(
  • eventObj
  • eventPhase
)
protected

Defined in _dispatchEvent:348

Parameters:

addEventListener

(
  • type
  • listener
  • [useCapture]
)
Function | Object

Adds the specified event listener. Note that adding multiple listeners to the same function will result in multiple callbacks getting fired.

Example

 displayObject.addEventListener("click", handleClick);
 function handleClick(event) {
    // Click happened.
 }

Parameters:

  • 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

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

Returns:

Function | Object: Returns the listener for chaining or assignment.

dispatchEvent

(
  • eventObj
  • [target]
)
Boolean

Defined in dispatchEvent:279

Dispatches the specified event to all listeners.

Example

 // Use a string event
 this.dispatchEvent("complete");

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

Parameters:

  • eventObj Object | String | Event

    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 with the specified type.

  • [target] Object optional

    The object to use as the target property of the event object. This will default to the dispatching object. This parameter is deprecated and will be removed.

Returns:

Boolean: Returns the value of eventObj.defaultPrevented.

hasEventListener

(
  • type
)
Boolean

Indicates whether there is at least one listener for the specified event type and useCapture value.

Parameters:

  • type String

    The string type of the event.

Returns:

Boolean: Returns true if there is at least one listener for the specified event.

initialize

(
  • target
)
static

Defined in initialize:94

Static initializer to mix EventDispatcher methods into a target object or prototype.

    EventDispatcher.initialize(MyClass.prototype); // add to the prototype of the class
    EventDispatcher.initialize(myObject); // add to a specific instance

Parameters:

  • target Object

    The target object to inject EventDispatcher methods into. This can be an instance or a prototype.

initialize

() protected

Defined in initialize:133

Initialization method.

off

(
  • type
  • listener
  • [useCapture]
)

Defined in off:246

A shortcut to the removeEventListener method, with the same parameters and return value. This is a companion to the .on method.

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    The listener function or object.

  • [useCapture] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

on

(
  • type
  • listener
  • [scope]
  • [once=false]
  • [data]
  • [useCapture=false]
)
Function

Defined in on:174

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 created anonymous function is returned for use with .removeEventListener (or .off).

Example

    var 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();
        }
    }

Parameters:

  • 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

    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=false] Boolean optional

    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=false] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

Returns:

Function: Returns the anonymous function that was created and assigned as the listener. This is needed to remove the listener later using .removeEventListener.

removeAllEventListeners

(
  • [type]
)

Removes all listeners for the specified type, or all listeners of all types.

Example

 // Remove all listeners
 displayObject.removeAllEvenListeners();

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

Parameters:

  • [type] String optional

    The string type of the event. If omitted, all listeners for all types will be removed.

removeEventListener

(
  • type
  • listener
  • [useCapture]
)

Removes the specified event listener.

Important Note: that 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.

Example

 displayObject.removeEventListener("click", handleClick);

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    The listener function or object.

  • [useCapture] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

toString

() String

Defined in toString:339

Returns:

String: a string representation of the instance.

Properties

_captureListeners

Object protected

_listeners

Object protected

Defined in _listeners:118