UsefulJS.Event

The Event module provides a simple, cross-browser event registration mechanism. It also provides a facility for dispatching custom events to interested parties.

Static methods

register

Registers interest in an event

Syntax
register(elem, eventType, callback[, ctx])
Parameters

Returns Boolean: true if any callback function was successfully registered, false if the same callback and context had already been used to register interest in the same events (will also return false if the parameters are garbage).

Description

The callback function takes has the following form:

callback(event, eventType, eventSource, registeredElement)

Note that event will already have been resolved so there is no need to do that annoying event = event || window.event dance. In addition, the document tree will already have been walked to trace back from the source of an event to the document element that you registered an interest in in the first place. The event type is also resolved so you don't have to go peeking inside the event object to get at it.

The callback function can return an explicit Boolean false to stop event propagation (assuming the event is cancelable in the first place). Either way, no further callbacks registered using register will be called for this event.

For convenience, you may pass a String value as the elem parameter. Otherwise you may pass in an Element object, the document object or the window object. You may also pass in nothing, in which case window is assumed. If an Element object is passed in and it doesn't have an id attribute, a random ID will be assigned to it. This is required to match events in elements to the registered callbacks.

Uncaught exceptions during event handling go somewhere and are handled in some way by the browser. UsefulJS.Event traps exceptions thrown by your callback, removes your callback from its callback list and rethrows the exception to be handled by the browser. This is not something you want happening, so trap exceptions in your callback and handle them explicitly!
Usage
// Force characters entered into a text input to uppercase
var ucOnly = function(evt, evtType, evtSrc, eReg) {
    // Can't modify keypress events directly in most browsers
    var fn = function() {
        eReg.value = eReg.value.toLocaleUpperCase();
    };
    setTimeout(fn, 20);
};
UsefulJS.Event.register("myInput", "keypress", ucOnly, null);

deregister

Deregisters a previously registered event handler.

Syntax
deregister(elem, eventType, callback[, ctx])
Parameters

Returns Boolean: true if any listener was successfully deregistered, false if all listeners were no longer registered or were never registered in the first place.

Description

The parameters are identical to the register method. The context is required together with the callback since the combination of callback and context identifies the event handler. See the description of register for information about the elem parameter.

Usage
// Allow normal text entry
UsefulJS.Event.deregister("myInput", "keypress", ucOnly, null);

clear

Clears all event handlers for an element that were set using register.

Syntax
clear(elem)
Parameters
Description

If you remove an element from the document tree and later reuse the same ID for a different element, event handling won't work properly because the registered event handlers will be for the old element. Calling clear will clear the internal tables for the element ID.

fire

Sends a custom event through the UsefulJS.Event dispatcher

Syntax
fire(eventType, eventTarget, eventProperties)
Parameters
Description

Events don't have to be limited to DOM events. The fire method allows pretty much anything to be sent as an event and picked up by registered listeners. If the system supports CustomEvent objects the event object received by the listener functions will be a bona-fide custom event dispatched from the eventTarget. Otherwise it will be an object that looks and behaves for all intents and purposes like a CustomEvent object. The eventProperties parameter will be available as the detail property of the event object. As with the other UsefulJS.Event methods, eventTarget can be an Element object, the ID of an element, the document object or the window object and defaults to the window object.

Usage
// Dispatch Christmas greetings
UsefulJS.Event.register(null, "specialday", function(evt) {
    if (evt.detail.day === "Christmas") {
        alert(evt.detail.greeting);
    }
});
var christmasGreetings = UsefulJS.Event.fire.bind(null, "specialday", window, 
    { day : "Christmas", greeting : "Merry Christmas, everybody!" });
var f = function() {
    var now = new Date();
    if (now.getMonth() === 11 && now.getDate() === 25) {
        christmasGreetings();
    }
    setTimeout(f, 86400000);
};
f();