# EaselJS Mouse Interaction

Synopsis: Learn about mouse events on display objects and the stage.
Topics: MouseEvent, addEventListener, on, click, dblclick, mouseover, mouseout, mousemove, mousedown, enableMouseOver, drag and drop, mouseMoveOutside
Target: EaselJS v0.8.1

This tutorial is part of the EaselJS GitHub repository.
Check out the repository for more tutorials and a handful of helpful samples.

## The Basics

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`, `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.

Note that there is no `mouseup` event. Instead use `click` (when the mouse is pressed and released on the same target, or `pressup` if you need to know when the mouse is pressed on a target, but released anywhere.

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);

## MouseEvent

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

## Bubbling

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.

## mouseChildren & mouseEnabled

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.on("click", function() { alert("Clicked!"); }); circle.mouseEnabled = false;

## hitArea

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.

## Stage mouse events

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.on("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.on("stagemousemove", 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.

## Drag and drop

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.

circle.on("pressmove", function(evt) { evt.target.x = evt.stageX; evt.target.y = evt.stageY; }); circle.on("pressup", function(evt) { console.log("up"); })

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 useful APIs

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.

Check out the API documentation and the HitTest tutorial for more information.