Usage of nsIDOMEventListener Interface

 Meant to be a script-only mechanism for setting an upload progress event
 listener.
 This attribute should not be used from native code!!
 This event listener may be called multiple times during the upload..

 After the initial response, all event listeners will be cleared.
 // XXXbz what does that mean, exactly?

 This event listener must be set BEFORE calling open().

 Mozilla only.

attribute nsIDOMEventListener onuploadprogress

 Meant to be a script-only mechanism for setting a callback function.
 The attribute is expected to be JavaScript function object. When the
 readyState changes, the callback function will be called.
 This attribute should not be used from native code!!

 After the initial response, all event listeners will be cleared.
 // XXXbz what does that mean, exactly?   

 Call open() before setting an onreadystatechange listener.

attribute nsIDOMEventListener onreadystatechange

 The nsIDOMEventTarget interface is the interface implemented by all
 event targets in the Document Object Model.

 For more information on this interface please see 
 http://www.w3.org/TR/DOM-Level-2-Events/

 @status FROZEN


 This method allows the registration of event listeners on the event target.
 If an EventListener is added to an EventTarget while it is processing an
 event, it will not be triggered by the current actions but may be 
 triggered during a later stage of event flow, such as the bubbling phase.
 
 If multiple identical EventListeners are registered on the same 
 EventTarget with the same parameters the duplicate instances are 
 discarded. They do not cause the EventListener to be called twice 
 and since they are discarded they do not need to be removed with the 
 removeEventListener method.

 @param   type The event type for which the user is registering
 @param   listener The listener parameter takes an interface 
                   implemented by the user which contains the methods 
                   to be called when the event occurs.
 @param   useCapture If true, useCapture indicates that the user 
                     wishes to initiate capture. After initiating 
                     capture, all events of the specified type will be 
                     dispatched to the registered EventListener before 
                     being dispatched to any EventTargets beneath them 
                     in the tree. Events which are bubbling upward 
                     through the tree will not trigger an 
                     EventListener designated to use capture.

void addEventListener(in DOMString type, in nsIDOMEventListener listener, in boolean useCapture)

 This method allows the removal of event listeners from the event 
 target. If an EventListener is removed from an EventTarget while it 
 is processing an event, it will not be triggered by the current actions. 
 EventListeners can never be invoked after being removed.
 Calling removeEventListener with arguments which do not identify any 
 currently registered EventListener on the EventTarget has no effect.

 @param   type Specifies the event type of the EventListener being 
               removed.
 @param   listener The EventListener parameter indicates the 
                   EventListener to be removed.
 @param   useCapture Specifies whether the EventListener being 
                     removed was registered as a capturing listener or 
                     not. If a listener was registered twice, one with 
                     capture and one without, each must be removed 
                     separately. Removal of a capturing listener does 
                     not affect a non-capturing version of the same 
                     listener, and vice versa.

void removeEventListener(in DOMString type, in nsIDOMEventListener listener, in boolean useCapture)

 This method is the same as the addEventListener() method defined
 in nsIDOMEventTarget, but it takes one additional argument which
 lets callers control whether or not they want to receive
 untrusted events (synthetic events generated by untrusted code)

 @param   type See the type argument to the same method in
               nsIDOMEventTarget.
 @param   listener See the listener argument to the same method in
                   nsIDOMEventTarget.
 @param   useCapture See the listener argument to the same method in
                     nsIDOMEventTarget.
 @param   wantsUntrusted If false, the listener will not receive any
                         untrusted events (see above), if true, the
                         listener will receive events whether or not
                         they're trusted

void addEventListener(in DOMString type, in nsIDOMEventListener listener, in boolean useCapture, in boolean wantsUntrusted)