EventManager Mechanism
- version: since cocos2d-html5 v3.0 alpha0
Introduction
Cocos2d-html5 3.0 introduces a new mechanism for responding to user events. This document explains how it works.
The basics:
- Event listeners encapsulate your event processing code.
- Event Manager manage listeners of user events.
- Event objects contain information about the event.
To respond to events, you must first create an cc.EventListener. There are five different kinds of EventListeners:
-
cc.EventListenerTouch- responds to touch events -
cc.EventListenerKeyboard- responds to keyboard events -
cc.EventListenerAcceleration- reponds to accelerometer events -
cc.EventListenMouse- responds to mouse events -
cc.EventListenerCustom- responds to custom events
Then, attach your event processing code to the appropriate callback on the event listener (e.g., onTouchBegan for EventListenerTouch listeners, or onKeyPressed for keyboard event listeners).
Next, register your EventListener with the cc.eventManager.
When events occur (for example, the user touches the screen, or types on the keyboard), the cc.eventManager distributes Event objects (e.g. EventTouch, EventKeyboard) to the appropriate EventListeners by calling your callbacks. Each Event object contains information about the event (for example, the coordinates where the touch occurred).
Example
In the following example, we will add three overlapping buttons to a scene. Each will respond to touch events.
Create three sprites with images for the buttons
var sprite1 = cc.Sprite.create("Images/CyanSquare.png");
sprite1.x = size.width/2 - 80;
sprite1.y = size.height/2 + 80;
this.addChild(sprite1, 10);
var sprite2 = cc.Sprite.create("Images/MagentaSquare.png");
sprite2.x = size.width/2;
sprite2.y = size.height/2;
this.addChild(sprite2, 20);
var sprite3 = cc.Sprite.create("Images/YellowSquare.png");
sprite3.x = 0;
sprite3.y = 0;
sprite2.addChild(sprite3, 1);
Create a single touch event listener and write the callback code
//Create a "one by one" touch event listener (processes one touch at a time)
var listener1 = cc.EventListener.create({
event: cc.EventListener.TOUCH_ONE_BY_ONE,
// When "swallow touches" is true, then returning 'true' from the onTouchBegan method will "swallow" the touch event, preventing other listeners from using it.
swallowTouches: true,
//onTouchBegan event callback function
onTouchBegan: function (touch, event) {
// event.getCurrentTarget() returns the *listener's* sceneGraphPriority node.
var target = event.getCurrentTarget();
//Get the position of the current point relative to the button
var locationInNode = target.convertToNodeSpace(touch.getLocation());
var s = target.getContentSize();
var rect = cc.rect(0, 0, s.width, s.height);
//Check the click area
if (cc.rectContainsPoint(rect, locationInNode)) {
cc.log("sprite began... x = " + locationInNode.x + ", y = " + locationInNode.y);
target.opacity = 180;
return true;
}
return false;
},
//Trigger when moving touch
onTouchMoved: function (touch, event) {
//Move the position of current button sprite
var target = event.getCurrentTarget();
var delta = touch.getDelta();
target.x += delta.x;
target.y += delta.y;
},
//Process the touch end event
onTouchEnded: function (touch, event) {
var target = event.getCurrentTarget();
cc.log("sprite onTouchesEnded.. ");
target.setOpacity(255);
//Reset zOrder and the display sequence will change
if (target == sprite2) {
sprite1.setLocalZOrder(100);
} else if (target == sprite1) {
sprite1.setLocalZOrder(0);
}
}
});
cc.EventListener.create is a creator of all type of event listeners, parameter ‘event’ can be used to set event listener’s type. for example ‘cc.EventListener.TOUCH_ONE_BY_ONE’ and cc.EventListenerTouchOneByOne .
Add event listener to event dispatcher
// add listeners to cc.eventManager
cc.eventManager.addListener(listener1, sprite1);
cc.eventManager.addListener(listener1.clone(), sprite2);
cc.eventManager.addListener(listener1.clone(), sprite3);
cc.eventManager is a singleton object in Cocos2d-html5. You can use it to manage the dispatching state of all events. You can add listener to cc.eventManager through addListener, addListener supports two parameters: listener and nodeOrPriority, if nodeOrPriority is a cc.Node or cc.Node’s subclass object, it will add listener as SceneGraphPriority, and if nodeOrPriority is number value, it will add listener as FixedPriority.
Note: In the example above, we use the clone() method in the second and third calls to addListener. This is because each event listener can be added only once. The methods addListener set a registration flag on the event listener, and won’t add the event listener again if the flag is already set.
One more thing to keep in mind: if you add a fixed priority listener to a node, you need to remove the listener manually when the node is removed. However, in the case of a scene graph priority listener, the listener is bound to the node: when the node’s destructor is called, the listener will be removed automatically.
A faster way to add listener to cc.eventManager
cc.eventManager.addListener({
event: cc.EventListener.TOUCH_ALL_AT_ONCE,
onTouchesMoved: function (touches, event) {
var touch = touches[0];
var delta = touch.getDelta();
var node = event.getCurrentTarget().getChildByTag(TAG_TILE_MAP);
var diff = cc.pAdd(delta, node.getPosition());
node.setPosition(diff);
}
}, this);
cc.eventManager的 addListener's first parameter listener supports two types: cc.EventListener object and json object. if listener is a json object, it will create a cc.EventListener object by json object.
touchable_sprite.png (44.2 KB)
