EaselJS: Mouse Interaction

At its core, the EaselJS mouse interaction model is very simple to use - just assign a listener to a mouse events via the addEventListener method on a display object: circle.addEventListener("click", function(event) { alert("clicked"); })

There are a number of events you can listen for on display objects: click, mousedown, mouseup, dblclick, pressmove, pressup, mouseover / mouseout, and rollover / rollout.

The latter four events have some overhead associated with them, so you need to enable them with stage.enableMouseOver(frequency). The frequency parameter indicates how many times per second EaselJS should calculate what is currently under the pointer. A higher number is more responsive, but also more computationally expensive. It defaults to 20 times per second.

The on method provides a shortcut to addEventListener, and adds additional functionality. See the API docs for more details. circle.on(type, listener, scope, once, data, useCapture);

When a mouse handler is triggered, it is called with a single parameter holding a MouseEvent instance. You can use this object to see what type of event it was, what the target was, get access to the nativeEvent object it was based on, and to check the pointer's stageX and stageY coordinates. circle.addEventListener("click", function(evt) { alert("type: "+evt.type+" target: "+evt.target+" stageX: "+evt.stageX); });

When a mouse event is triggered on a target, the event flows through three phases: the capture phase, the target phase, and the bubbling phase.

In the first phase (capture), the event is dispatched starting with the stage, and progressing through the ancestors of the target to its immediate parent. Only listeners that were added using the useCapture parameter are triggered in this phase.

In the second phase (target), the event is dispatched on the target object (ex. the element that was clicked).

In the final phase (bubbling), the event is dispatched from the immediate parent of the target through the ancestors (in the reverse order of the capture phase) to the stage.

The example below has a "button", which is a Container instance containing two children: a background shape, and a text label. All three display objects and the stage have listeners for the "click" event both with and without the useCapture param.

You can prevent the children of a Container from dispatching mouse events setting mouseChildren to false. myContainer.mouseChildren = false;

This causes the container to be treated as an aggregate element for mouse interactions. For example, in the bubbling example above setting button.mouseChildren = false; would make it so that clicking children of the button (background & label) dispatches the click event with the button as the target instead of the child that was clicked.

Similarly, you can completely disable mouse events on any display object without removing its handlers by setting mouseEnabled to false. circle.addEventListener("click", function() { alert("Clicked!"); }); circle.mouseEnabled = false;

Normally, EaselJS will calculate mouse hits on a display object based on its visible, non-transparent pixels. This usually works pretty well, but there may be cases where you want to define a hit target that is different than what is displayed on screen.

To do this, you can assign any other display object to be the hitArea for your object. It does not need to be on the display list, and will not be visible, but it will be used for the hit test instead.

Hit area display objects are used within the coordinate system (ie. concatenated transformation) of their owner, and as such you can reuse the same display object as the hitArea of multiple objects.

Notice how in this demo, as you roll over the red text, it only registers a hit when the pointer is over a non-transparent pixel, whereas the blue text uses the rectangular hitArea to calculate the hit.

For the stage, just like every other display object, you will only get events when the mouse is over a non-transparent pixel.

Stage has a few special mouse events that come in handy for responding to general mouse interactions anywhere within your canvas. stagemousedown, stagemouseup, and stagemousemove are called any time a relevant mouse interaction happens anywhere on the canvas. stage.addEventListener("stagemousedown", function(evt) { alert("the canvas was clicked at "+evt.stageX+","+evt.stageY); })

The following demo demonstrates using these events to let you finger paint on the canvas:

By default, you will stop getting stagemousemove events whenever the pointer is outside of the canvas.

If you'd like to keep getting stagemousemove events when the pointer leaves the canvas, just set mouseMoveOutside to true. The stageX & stageY properties of MouseEvent will always return a value normalized to within your stage bounds, but you can use rawX and rawY to get values that haven't been normalized (this can cause errors if you aren't careful). stage.mouseMoveOutside = true; stage.onMouseMove = function(evt) { console.log("stageX/Y: "+evt.stageX+","+evt.stageY); // always in bounds console.log("rawX/Y: "+evt.rawX+","+evt.rawY); // could be < 0, or > width/height }

You can monitor whether the pointer is over the canvas by using stage.mouseInBounds and the mouseleave / mouseenter events.

EaselJS makes drag and drop functionality very easy to implement. After the mouse is pressed over a display object, that object will generate pressmove events until the mouse is released, at which point a pressup event will be dispatched.

Check out the source for the demo below for a simple example of this in action. It's also a great place to test out the mouseMoveOutside property.

Other methods that are relevant to advanced mouse interactions are:

• Container.getObjectUnderPoint() returns the top most display object under the specified point.
• Container.getObjectsUnderPoint() returns all display objects under the specified point.
• DisplayObject.hitTest() returns true if the specified point in the display object is non-transparent.