The upcoming version of CreateJS is going to include some substantial updates to the event model. These changes will impact all of the libraries, and should provide a more powerful, consistent way to work with events.

onEvent Handlers

In the last version of CreateJS, we deprecated all of the onEvent handlers (ex. onClick) in favour of addEventListener(). In this version we are removing those handlers completely. This allows us to support a single event model, and makes adding new capabilities (like bubbling) much easier.

on(“event”)

The addEventListener() model provides a robust, unified event model that is compatible with DOM Level 2 events. However, it tends to be verbose, and isn’t particularly feature rich.

To address this, we added a shortcut on() method (inspired by libraries like jQuery) that makes it easy to add robust listeners with the same amount of code as onEvent handlers. Additionally, listeners added with on() are scoped to the dispatching object by default, the same as onEvent handlers were.

The first two lines below are functionally almost identical, though the second is actually using addEventListener() under the hood:

obj.onTick = myHandler; // deprecated & removed
obj.on("tick", myHandler); // short, same scope
obj.addEventListener("tick", myHandler); // longer, ambiguous scope

The on() method also provides a ton of additional capability, such as specifying a scope, indicating that the listener should only be triggered once, and including arbitrary data with the callback.

// .on(type,    listener,    scope, once, data)
btn.on("click", handleClick, myObj, true, "hello!");

In the above example, when btn is clicked it calls handleClick in the scope of myObj. This event listener is removed automatically after it fires (true). Two parameters are passed to handleClick – the event object and the associated data (“hello!”).

The on() method works by creating a wrapper function and passing it to addEventListener(). It returns this wrapper so that you can remove it later with removeEventListener() or off().

clickListener = btn.on("click", handleClick);
// ... later:
btn.off("click", clickListener);

Event Class

We’ve added a base Event class that should be used for all events. For simple events without extra data, you can still pass a string to dispatchEvent() and an Event object will be created automatically if there are any listeners. The latter is recommended when possible because it avoids instantiation and reduces garbage collection.

var evt = new Event("myevent");
evt.myEventData = "foo";
this.dispatchEvent(evt);

// or, if no custom data:
this.dispatchEvent("myevent");

Event.remove()

To make it really easy to clean up your listeners, you can call remove() on an Event object to remove the current listener.

function eventHandler(evt) {
  // remove the listener if count > 3:
  if (this.count++ > 3) { evt.remove(); }
}

Removing “wrapped” event listeners can be tricky, and this will hopefully make it easier.

Inheritance

Extending EventDispatcher now works correctly, and most classes now extend it instead of mixing it in. Notable exceptions are Ticker (which uses a static interface), and MouseEvent (which mixes it in for the deprecated mouseup/mousemove functionality).

This isn’t a huge change, but it does clean up the code slightly, and means that you can use instanceof EventDispatcher.

Event Bubbling

CreateJS now supports the DOM Level 2 event bubbling model, so events will propagate through the EaselJS display hierarchy. This includes support for all the expected capabilities like stopPropagation(), stopImmediatePropagation(), preventDefault(), eventPhase, cancelable, currentTarget, useCapture, etc.

While this was added with EaselJS’s display list in mind, it should work with any EventDispatcher that exposes a parent property.

New EaselJS Events

We’ve added a few new events to EaselJS display objects including: rollover / rollout, and pressmove / pressup. The latter two events fire when the mouse (or touch) moves or is released after being pressed down on the target. This is a replacement for the current MouseEvent mousemove & mouseup events that have now been deprecated.

There are also some new events for Stage: mouseleave / mouseenter, tickstart / tickend, and drawstart / drawend.

Summary

A lot of changes, but I hope they will make working with events much easier. I’m happy with where the event model is now, and there shouldn’t be any more major changes to the event model moving forward. We’re always happy to hear feedback about these changes, and how we can make things even better.