event-emit.md

Event Listening and Emitting

Cocos Creator provides the EventTarget class to suport the listening and emitting of custom event. Before using it, it needs to be imported from the 'cc' module and an EventTarget object needs to be instantiated.

import { EventTarget } from 'cc';
const eventTarget = new EventTarget();

Note: although the Node object also implements some EventTarget interfaces, it is no longer recommended to continue using the Node object to listen to and emit custom events. Because this is not efficient enough, and we also hope that Node object only listens to events related to Node.

Event Listening

Listen to events can be registered by the interface this.node.on(). The methods are as follows:

// This event listener is triggered every time and needs to be unregistered manually.
eventTarget.on(type, func, target?);

The type is the event registration string. func is the callback to listen to when the event is executed. And target is the event receive object. If target is not set, then this in the callback refers to the object that is currently executing the callback.

The event listener interface on can pass to the third parameter target to bind the caller of the response function. Calling the following two methods would have the same effect:

// Using Function Binding
eventTarget.on(Node.EventType.MOUSE_DOWN, function ( event ) {
  this.enabled = false;
}.bind(this));

// Using the third parameter
eventTarget.on(Node.EventType.MOUSE_DOWN, (event) => {
  this.enabled = false;
}, this);

Besides listening with on, the once interface can also be used. The once listener will shut the event being listened to after the listener function responds.

Canceling listeners

We can shut the corresponding event listener using off when we don't care about a certain event anymore.

The off method can be used in two ways

// Cancel all registered events of this type on the object.
eventTarget.off(type);
// Cancels events on objects with this type of callback designation target.
eventTarget.off(type, func, target);

One thing to note is that the parameter of off must be in one-to-one correspondence with the parameter of on in order to cancel it.

Example:

import { _decorator, Component, EventTarget } from 'cc';
const { ccclass } = _decorator;
const eventTarget = new EventTarget();

@ccclass("Example")
export class Example extends Component {
    onEnable () {
        eventTarget.on('foobar', this._sayHello, this);
    }

    onDisable () {
        eventTarget.off('foobar', this._sayHello, this);
    }

    _sayHello () {
        console.log('Hello World');
    }
}

Event Emitting

Events are emitted through the eventTarget.emit() interface, as follows:

// At most 5 args could be emit.
eventTarget.emit(type, ...args);

Explanation for event parameters

When emitting events, we can pass our event parameters starting with the second argument of the emit function. Also, the corresponding event parameters can be fetched in the callback registered in on.

import { _decorator, Component, EventTarget } from 'cc';
const { ccclass } = _decorator;
const eventTarget = new EventTarget();

@ccclass("Example")
export class Example extends Component {
    onLoad () {
        eventTarget.on('foo', (arg1, arg2, arg3) => {
            console.log(arg1, arg2, arg3);  // print 1, 2, 3
        });
    }

    start () {
        let arg1 = 1, arg2 = 2, arg3 = 3;
        // At most 5 args could be emit.
        eventTarget.emit('foo', arg1, arg2, arg3);
    }
}

Note: only up to 5 event parameters can be passed here for the performance of the underlying event distribution. Therefore, care should be taken to control the number of parameters passed when passing a parameter.

System built-in events

Above are the general rules for listening to and emitting events. Cocos Creator has some built-in system events. Please refer to the following documents:

• Input Event System

• Node Event System