About Caph event system

This document provides useful information about the Caph event system.

Contents

Overview

Caph event system manages all DOM3 bubbling events which occur from the application such as "select", "focusin", "focusout", "click", "dblclick", "mousedown", "mouseup", "mousemove", "mouseover", "mouseout", "mousewheel", "wheel", "beforeinput", "input", "keydown" and "keyup". Exceptionally, Caph event system manages a capturing event "resize". 

When a managed event occurs from the application, Caph event system receives it first and then sends the message which is normalized from the event to the corresponding observers which consist of the corresponding event handlers sequentially if the message propagation is not stopped. 

As noted above, Caph event system propagates the message from the child to the parent or from the parent to the child. It is similar to DOM event propagation. But Caph event system provides the broadcasting instead of the capturing. Because Caph event system only manages the capturing event "resize". So if Caph event system receives a broadcasting message, sends the message to the corresponding observer's all children. 
Caph event system also provides the way to send a message between observers or all observers.

To use the Caph event system, define a new event observer and append it to the event manager. When an event occurs, event manager will normalize the event to a message and send it to all of its observers. If the event observer has parent or children, the message will propagate in either of the directions depending on the propagation type (bubbling or broadcasting).

Defining a new observer

To use Caph event system, define a new event observer. The event observer should mix-in caph.module.mixins.event.Observer object. Sample code is below:

1
2
3
4

var MyObserver = $class({
    $mixins : [caph.module.mixins.event.Observer],
    // your own class definition is here.
});

The MyObserver class is now an event observer class. You can use this class to handle messages from event manager. However, it does not handle any messages yet.

Attaching handlers to observer

After creating a new observer, you should attach an event handler to it to handle messages from the event manager. The event handler name always starts with on prefix and consists of lowercase name of event type. The event type name can be a string of which first letter is capitalized. Other cases are not permitted.

All event handlers have a caph.event.Message parameter object. caph.event.Message provides methods to get the event type, source, detail information and so on. Refer to the API reference for the details. The code below illustrates how to attach the event handlers:  

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

var MyObserver = $class({
    $mixins : [caph.module.mixins.event.Observer],

    onclick : function(message) { // handles DOM click event.
        console.log(message.detail.offsetX);
        console.log(message.detail.offsetY);
    },

    onkeydown : function(message) { // handles DOM keydown event.
        console.log(message.key().code);
    },

    onpress : function(message) { // handles custom press event.
        console.log(message.detail.type);
    }
});

This example shows how to attach the event handler. The click, keydown and press event handlers are attached to this observer. The click and keydown events are standard DOM event type. The press event is a custom defined event type. In Caph event system, both types of events are handled in the same way.

Sending message

If you want to communicate with other observers, you can send a message through event manager using the send and sendTo methods. There should be only one instance of eventManager in the whole application, so any attempt to create a new instance will throw an exception. Instead, always refer to eventManager by using the getInstance method. Refer to the API reference for more details. Sample source code can be found below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

var eventManager = caph.module.event.Manager.getInstance();
var MyObserver = $class({
    $mixins : [caph.module.mixins.event.Observer],

    onclick : function(message) { // handles DOM click event.
        eventManager.sendTo(this, {
            type :"press",
            detail : {
                type : "click",
                message : "mouse click!"
            }
        });
        message.stopPropatation();
    },

    onkeydown : function(message) { // handles DOM keydown event.
        if (message.key().enter) {
            eventManager.sendTo(this, {
                type : "press",
                detail : {
                    type :"keydown",
                    message : "key down!"
                }
            });
            message.stopPropatation();
        }
    },

    onpress : function(message) {
        var detail = message.detail;
        console.log(detail.type);
        console.log(detail.message);
    }
});

This example shows how to send a message. If you click or press any key, despite default action it will also trigger the custom event press, because click and keydown event handlers send press message to this observer. If you want to stop the propagation, use caph.event.Message.stopPropagation() method.

Adding to event manager

After creating the observer and setting up defined callbacks, the next step is to add the observer to event manager. The code below shown an example how to do that:

1
2
3
4
5
6
7
8
9
10
11

var eventManager = caph.module.event.Manager.getInstance();
var observer = new MyObserver();

eventManager.addObserver(observer);
eventManager.send({
    type :"press"
    detail : {
        type : "broadcast",
        message : "send message!"
    }
});

To attach the observer use the addObserver method. If you send a message to all event observers, use event handler’s send method.