events.addListener(target,

eventName,handler,listenMode)

This function adds an event listener to the target object. The first argument is the target. The second argument is the name of the event (such as "click"). The third argument is the function that will handle the event. The fourth argument is optional, that specifies how the the handler should listen. The following are the acceptables types of listening:

• events.AFTER - The handler will be fired after previously registered handlers. This is the default listening mode.
  
  
• events.BEFORE - The handler will be fired before previously registered handlers
  
  

This function returns the handler function. If the target object is DOM element, you may omit the "on" prefix. For example:

            var myElement = byId("myId");
            


            events.addListener(byElement,"click",
            


            	function() { debug(this._id + " was clicked") });
          

Note, that the "this" scope is preserved with the event handler. With DOM events, the event is "fixed", so that you can access the target field of the event from both IE and standards compliant browsers. You can also access the standard preventDefault and stopPropagation functions with IE as well.

Also, this function may be used on any JavaScript object that has a function member, not just on DOM objects. This creates a form of aspect oriented programming. For example if you have the following object:

            var myObj = {initialize : function() { this.index=0; this.text=""; }};
          

We could add a listener to the initialize function on the myObj object by doing this:

            events.addListener(myObj,"initialize",
            


            	function() { debug(this + " has been initialized"});
            


          

As you can see, this event listener has much more capabilities than simply a DOM listener.

events.removeListener(target,

eventName,handler)

The first argument is the target, the second is name of the event to remove the listener from, and the third the handler to remove. This function simply removes the providing listening handler from the list of handlers, so that it will not be listening anymore.