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

• elem Object
  The element whose events you want to capture. See the description below for more details.
• eventType String|Array
  The name or names of the event(s) that you want to listen for. Takes the form "click" rather than "onclick"
• callback Function
  The callback function; see the description below for details of the function parameters
• ctx Object (optional)
  The calling context (i.e. "this") for the callback. Allows you to pass in unbound object method pointers as the callback.

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.

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

• elem Object
  The element whose events you no longer want to capture.
• eventType String|Array
  The name or names of the event(s) that no you longer want to listen for. Takes the form "click" rather than "onclick"
• callback Function
  The callback function that was previously registered
• ctx Object (optional)
  The calling context (i.e. "this") for the callback

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

• elem Object
  The element whose event handlers you want to remove.

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

• eventType String
  The name of the "event" that you want dispatched
• eventTarget Object
  The element or Object that you want the event purportedly to come from
• eventProperties Object
  Data to be associated with the event.

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();