NAME

DOM.Events - Event registration abstraction layer

SYNOPSIS

JSAN.use("DOM.Events");

function handleClick(e) {
    e.currentTarget.style.backgroundColor = "#68b";
}

DOM.Events.addListener(window, "load", function () {
    alert("The page is loaded.");
});

DOM.Events.addListener(window, "load", function () {
    // this listener won't interfere with the first one
    var divs = document.getElementsByTagName("div");
    for(var i=0; i<divs.length; i++) {
        DOM.Events.addListener(divs[i], "click", handleClick);
    }
});

DESCRIPTION

This library lets you use a single interface to listen for and handle all DOM events to reduce browser-specific code branching. It also helps in dealing with Internet Explorer's memory leak problem by automatically unsetting all event listeners when the page is unloaded (for IE only).

Functions

All functions are kept inside the namespace DOM.Events and aren't exported automatically.

addListener( HTMLElement element, string eventType, Function handler [, boolean makeCompatible = true] )

Registers an event listener/handler on an element. The eventType string should not be prefixed with "on" (e.g. "mouseover" not "onmouseover"). If makeCompatible is true (the default), the handler is put inside a wrapper that lets you handle the events using parts of the DOM Level 2 Events model, even in Internet Explorer (and behave-alikes). Specifically:

• The event object is passed as the first argument to the event handler, so you don't have to access it through window.event.

• The event object has the properties target, currentTarget, and relatedTarget and the methods preventDefault() and stopPropagation() that behave as described in the DOM Level 2 Events specification (for the most part).

• If possible, the event object for mouse events will have the properties pageX and pageY that contain the mouse's position relative to the document at the time the event occurred.

• If you attempt to set a duplicate event handler on an element, the duplicate will still be added (this is different from the DOM2 Events model, where duplicates are discarded).

If makeCompatible is false, the arguments are simply passed to the browser's native event registering facilities, which means you'll have to deal with event incompatibilities yourself. However, if you don't need to access the event information, doing it this way can be slightly faster and it gives you the option of unsetting the handler with a different syntax (see below).

The return value is a positive integer identifier for the listener that can be used to unregister it later on in your script.

removeListener( integer identifier )

Unregisters the event listener associated with the given identifier so that it will no longer be called when the event fires.

var listener = DOM.Events.addListener(myElement, "mousedown", myHandler);
// later on ...
DOM.Events.removeListener(listener);

removeListener( HTMLElement element, string eventType, Function handler )

This alternative syntax can be also be used to unset an event listener, but it can only be used if makeCompatible was false when it was set.

SEE ALSO

DOM Level 2 Events Specification, http://www.w3.org/TR/DOM-Level-2-Events/

Understanding and Solving Internet Explorer Leak Patterns, http://msdn.microsoft.com/library/default.asp?url=/library/en-us/IETechCol/dnwebgen/ie_leak_patterns.asp

AUTHOR

Justin Constantino, <goflyapig@gmail.com>.

COPYRIGHT

Copyright (c) 2005 Justin Constantino.  All rights reserved.
This module is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public Licence.