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/IETechC
    ol/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.

</html>