EaselJS: Mouse Interaction

At its core, the EaselJS mouse interaction model is very simple to use - just assign a function handler for one of the mouse events on a display object: circle.onClick = function(evt) { alert("clicked"); }

There are a number of events you can listen for on display objects: onPress, onClick, onDoubleClick, onMouseOver, and onMouseOut.

The latter two 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.

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.onClick = function(evt) { alert("type: "+evt.type+" target: "+evt.target+" stageX: "+evt.stageX); }

When you assign a mouse event handler on a Container instance, it will block all mouse events to its children, even if they have their own listeners.

The example below has a "button", which is a Container instance containing two children: a background shape, and a text label. All three of these display objects have onClick handlers, but if you click the button, only its handler is called.

If you edit the code for container.html to remove the onClick handler on button, the handlers on background and label will be active.

You can also block mouse events to children without assigning a handler by setting mouseChildren to false. myContainer.mouseChildren = false;

Similarly, you can disable mouse events on any display object without removing its handlers by setting mouseEnabled to false. circle.onClick = 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.

If you assign a normal mouse event handler to the stage, it will block mouse events to all of its children. Also, 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. onMouseDown, onMouseUp and onMouseMove are called any time a relevant mouse interaction happens anywhere on the canvas. stage.onMouseDown = 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 onMouseMove events whenever the pointer is outside of the canvas. You can check of this has happened with stage.mouseInBounds.

If you'd like to keep getting onMouseMove 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 }

EaselJS makes drag and drop functionality very easy to implement. When an onPress handler is called, the MouseEvent that is passed to it has two special mouse handlers of its own, onMouseMove and onMouseUp

These handlers work exactly the same as their equivalents on Stage with one major difference - they are only active until the user releases the pointer. It sounds a little strange, but it's really simple to use.

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.