Mouse Events
All JS3Objects can easily be told to listen for Mouse Events
Enabling Mouse Events
To optimize performance, Mouse Events are ignored by default. To tell the Stage to listen for Mouse Events set the Stage's interactive property to true.
var stage = new JS3('my-canvas');
stage.interactive = true;
All JS3Objects have two basic properties that control their interactivity.
var c = new JS3Circle();
c.enabled = false; // default
c.draggable = false; // default
To make any Object draggable, set its draggable property to true, likewise to tell any Object to ignore Mouse Events, set its enabled property to false.
Listening For Events
All JS3Objects have the following handlers that listen for Mouse Interactions.
Each handler can be set to a callback function which will be executed whenever that interaction takes place.
var c = new JS3Circle();
c.down = function(){ trace('The Mouse was pressed!'); };
c.up = function(){ trace('The Mouse was released!'); };
c.over = function(){ trace('I was moused over!'); };
c.out = function(){ trace('I was moused out!'); };
c.click = function(){ trace('I was clicked!'); };
c.dclick = function(){ trace('I was doubled clicked!'); };
c.dragStart = function(){ trace('I am starting to be dragged!'); };
c.dragChange = function(){ trace('I am being dragged!'); };
c.dragComplete = function(){ trace('I am done being dragged!'); };
The callbacks receive a JS3EventObject that describes the type of event and to whom and where it took place.
var c = new JS3Circle();
c.name = 'my-circle';
c.click = onCircleClick;
function onCircleClick(e)
{
trace(e.target.name); // traces 'my-circle';
}
Quick Tip : Assigning a callback to any drag handler automatically sets that Object's draggable property to true.
However you can always disable dragging by setting draggable or enabled to false without the need to remove the callback.
Stage Events
You can also bind the following callbacks directly to the Stage.
var stage = new JS3('my-canvas');
stage.down = function(){ trace('The Mouse was pressed'); };
stage.up = function(){ trace('The Mouse was released'); };
stage.move = function(){ trace('The Mouse moved'); };
stage.click = function(){ trace('The Stage was clicked'); };
stage.dclick = function(){ trace('The Stage was doubled clicked'); };
stage.enter = function(){ trace('The Mouse entered the Stage'); };
stage.leave = function(){ trace('The Mouse left the Stage'); };
stage.focusIn = function(){ trace('The Window gained focus'); };
stage.focusOut = function(){ trace('The Window lost focus'); };
The following example shows how to listen for Mouse clicks on the Stage.
If we set the enabled property of the Circle to true, we can capture that target even though the callback is bound to the Stage.
var stage = new JS3('my-canvas');
var c = new JS3Circle( { x:25, y:25, size:50 });
c.name = 'my-circle';
c.enabled = true;
stage.addChild(c);
stage.click = function(e)
{
alert(e.target.name + 'was clicked');
}
Click around in the Canvas below.
The JS3 Event Object
Callbacks bound to handlers receive a JS3EventObject with the following properties
event.x : Number // global mouse X position where the event occurred
event.y : Number // global mouse Y position where the event occurred
event.type : String // the type of event that occurred
event.owner : JS3Object // the JS3Object to which the callback was bound
event.target : JS3Object // the JS3Object that actually received the event
Disabling Mouse Events
You can easily enable / disable MouseEvent listeners by toggling the following properties on any JS3Object :
var c = new JS3Circle();
c.enabled : Boolean // set to false to ignore click, dclick, over & out
c.draggable : Boolean // set to false to ignore dragStart, dragChange & dragComplete
Furthermore, you can at any time disable all MouseEvent Listeners by simply setting the stage.interactive property to false.
var stage = new JS3Circle();
stage.interactive = false;