Node System Events

    Cocos Creator supports four types of system events: mouse, touch, keyboard, device motion. They are called Global Events. The usage of touch and mouse events dispatched by Node is discussed in this document.

    System events follow the general register method, developers can register event listener not only by using the enumeration type but also by using the event name directly. It is recommended to use enumeration for event registration to avoid event registration failure due to writing problems.

    Mouse events will only be triggered on desktop platforms, the event types the system provides are as follows:

    The important APIs of mouse events (Event.EventMouse) are described in the (Event standard events API excluded).

    Touch event types and event objects

    Touch events can be triggered on both mobile platforms and desktop platforms. Developers can better debug on the desktop platform, by simply listening for touch events and responding to both mobile touch events and desktop mouse events at the same time. The types of touch events provided by the system are as follows:

    The important APIs of a touch event (Event.EventTouch) are described in the ( standard event API excluded):

    Touch events support the event bubbles on the node tree, take the pictures below as an example:

    When the mouse or finger was applied in the node C region, the event will be triggered at node C first and the node C listener will receive the event. Then the node C will pass this event to its parent node, so the node B listener will receive this event. Similarly the node B will also pass the event to its parent node A. This is a basic event bubbling phase. It needs to be emphasized that there is no hit test in parent nodes in the bubbling phase, which means that the node A and B can receive touch events even though the touch location is out of their node region.

    The bubbling phase of touch events is no different than the general events. Calling event.propagationStopped = true; can force to stop the bubbling phase.

    Ownership of touch points among brother nodes

    Suppose the node B and C in the picture above are brother nodes, while C partly covers over B. Now if C receives a touch event, it is announced that the touch point belongs to C, which means that the brother node B won’t receive the touch event any more, even though the touch location is also inside its node region. The touch point belongs to the top one among brother nodes.

    At the same time, if C has a parent node, it will also pass the touch event to its parent node through the event bubble mechanism.

    Contact interception between different Canvas is determined by priority. In the scene in the figure below, Canvas 1-5 in the node tree corresponds to priority 1-5 of the image display. It can be seen that even though Canvas nodes 3, 4, and 5 are arranged in scrambled order, the order of response of the contacts is still Canvas5 -> Canvas4 -> Canvas3 -> Canvas2 -> Canvas1, according to the priority relationship on the Canvas. The sorting between Canvas is done in the order of the node tree only if the priority is the same.

    multi-canvas

    Register touch or mouse events in the capturing phase

    Sometimes, it is necessary to dispatch touch or mouse events to parent node event listeners before dispatching to any child nodes beneath it in hierarchy, like the design of ScrollView component.

    Event bubbling cannot meet all demands. When this happens, register the parent node event listeners in the capturing phase. To achieve this goal, passing in true as the useCapture parameter (a fourth parameter) when registering touch or mouse event on the node. For example:

    When the node fires the touch-start event, the event will be first dispatched to all the parent node event listeners registered in the capturing phase, then dispatched to the node itself, and finally comes the event bubbling phase.

    Normal events are dispensed as described above. However, if the node has components such as Button, Toggle or BlockInputEvents on it, it will stop event bubbling. Look at the picture below. There are two buttons, priority 1 for Canvas0 and priority 2 for Canvas1. If you click on the intersection of the two buttons, which is the blue area in the picture, it appears that button priority 2 received the contact event successfully, while button priority 1 did not. That’s because according to the event reception rules above, button priority 2 receives contact events first and intercepts them（event.propagationStopped = true) to prevent event penetration. If the node is a non-button node, events can also be intercepted by adding the BlockInputEvents component to prevent penetration.

    Example for touch events

    Using the example below, summarizing touch events is easy. There are four nodes A, B, C and D in the picture above, where A and B are brother nodes. The specific hierarchical relationship should be like this:

    example

    1. If one touch is applied in the overlapping area between A and B, now B won’t receive the touch event, so that propagating order of the touch event should be A -> C -> D.
    2. If the touch location is in node B (the visible green area), the order should be B -> C -> D.
    3. If the touch location is in node C, the order should be C -> D.

    All node built-in events can get event names from Node.EventType.

    3D Node Events

    Definition of Transformation Enumeration Values:

    Multi-touch event

    The engine has a multi-touch event blocking switch. Multi-touch events are enabled by default. For projects that do not require multi-touch, you can disable allowing multi-touch with the following code:

    Alternatively, it can be configured via Project Setting/Macro Config.

    Pause node system events