# Handling events

Event handling in the WRTKit is based on the "observer pattern", meaning that events are reported from the event source to observers that are said to be "listening" to event notifications. An event listener is simply a JavaScript function that takes a single argument: the event message. In fact even that single argument is optional and if the function is not interested in the event message then it can simply ignore it.

All views and controls inherit from a common base class called "UIElement" that defines the mechanics for event observation and notification. From the point of view of event listeners, the most important methods are addEventListener() and removeEventListener(). These two methods are used to register and unregister listener functions from a view or control.

There are different types of events though, and event listeners are typically not interested in receiving notifications of all events. For example an event listener that wants to know when a button has been pressed doesn't usually care if the pointer is currently hovering above the button or not. Filtering of event notifications works based on event type names. E.g. in this case the event listener would have been added so that it should be called only for events of the "ActionPerformed" type. The event type is given to the addEventListener() function when a listener is registered. If a listener function really wants to be notified of all event types then null can be specified as the event type. Note that the event type must also be specified when an event listener is unregistered.

The code below shows a typical event listener function:

    // Callback for event notifications.
    function handleEvent(event) {
        // handle event here
    }

The event message is passed to the first argument (called event in this case) of the event handler function. The event message is a JavaScript object with three properties: type, source and value. The type property specifies the event type name and is useful if a listener function is listening to several types of events. The source argument is a reference to the source view or control that sent out the event notification. If a listener function is listening to events from many different controls then this is useful to figure out in which of the controls the event occurred. Here the unique identifier of views and controls can come in handy to identify the source without needing to retain references to all the source controls. Finally the value property is a event-type specific property that contains some information about the event. For example if the event type is "TextChanged" from a text entry control then the value would be the new text value that the user has typed into the control.

The code below demonstrates how to add and remove an event listener to/from a control. The example assumes that the control has already been created and that the ctrl variable refers to it.

    // add listener to ctrl
    // function to add is handleEvent() for event type "ActionPerformed"
    ctrl.addEventListener("ActionPerformed", handleEvent);

    // remove listener from ctrl
    // function to remove is handleEvent() for event type "ActionPerformed"
    ctrl.removeEventListener("ActionPerformed", handleEvent);

Parent topic: Common WRTKit tasks