This tutorial is part of the EaselJS GitHub repository.
Check out the repository for more tutorials and a handful of helpful samples.
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:
There are a number of events you can listen for on display objects:
The latter four events have some overhead associated with them, so you need to enable them with
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.
on method provides a shortcut to
addEventListener, and adds additional functionality. See the API docs for more details.
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
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
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
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.
stagemousemove are called any time a relevant mouse interaction happens anywhere on the canvas.
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
stageY properties of
MouseEvent will always return a value normalized to within your stage bounds, but you can use
rawY to get values that haven't been normalized (this can cause errors if you aren't careful).
You can monitor whether the pointer is over the canvas by using
stage.mouseInBounds and the
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
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
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.