EventTarget interface is implemented by all the objects
* which could be event targets in an implementation which supports an event
* flow. The interface allows registration and removal of event listeners,
* and dispatch of events to an event target.
* When used with the DOM event flow, this interface is implemented by all
* target nodes and target ancestors, i.e. all DOM Nodes of the
* tree support this interface when the implementation conforms to DOM Level
* 3 Events and, therefore, this interface can be obtained by using
* binding-specific casting methods on an instance of the Node
* interface.
*
Invoking addEventListener or
* addEventListenerNS repeatedly on the same
* EventTarget with the same values for the parameters
* namespaceURI, type, listener, and
* useCapture has no effect. Doing so does not cause the
* EventListener to be called more than once and does not cause
* a change in the triggering order.
*
See also the
Document Object Model (DOM) Level 3 Events Specification
.
* @since DOM Level 2
*/
public interface EventTarget {
/**
* Registers an event listener, depending on the useCapture
* parameter, on the capture phase of the DOM event flow or its target
* and bubbling phases. Invoking this method is equivalent to invoking
* addEventListenerNS with the same values for the
* parameters type, listener, and
* useCapture, and the value null for the
* parameter namespaceURI.
* @param type Specifies the Event.type associated with the
* event for which the user is registering.
* @param listener The listener parameter takes an object
* implemented by the user which implements the
* EventListener interface and contains the method to be
* called when the event occurs.
* @param useCapture If true, useCapture indicates that the
* user wishes to add the event listener for the capture phase only,
* i.e. this event listener will not be triggered during the target
* and bubbling phases. If false, the event listener will
* only be triggered during the target and bubbling phases.
*/
public void addEventListener(String type,
EventListener listener,
boolean useCapture);
/**
* Removes an event listener. Calling removeEventListener
* with arguments which do not identify any currently registered
* EventListener on the EventTarget has no
* effect. The Event.namespaceURI for which the user
* registered the event listener is implied and is null.
* @param type Specifies the Event.type for which the user
* registered the event listener.
* @param listener The EventListener to be removed.
* @param useCapture Specifies whether the EventListener
* being removed was registered for the capture phase or not. If a
* listener was registered twice, once for the capture phase and once
* for the target and bubbling phases, each must be removed
* separately. Removal of an event listener registered for the capture
* phase does not affect the same event listener registered for the
* target and bubbling phases, and vice versa.
*/
public void removeEventListener(String type,
EventListener listener,
boolean useCapture);
/**
* Dispatches an event into the implementation's event model. The event
* target of the event is the EventTarget object on which
* dispatchEvent is called.
* @param evt The event to be dispatched.
* @return Indicates whether any of the listeners which handled the
* event called Event.preventDefault(). If
* Event.preventDefault() was called the returned value
* is false, else it is true.
* @exception EventException
* UNSPECIFIED_EVENT_TYPE_ERR: Raised if the Event.type
* was not specified by initializing the event before
* dispatchEvent was called. Specification of the
* Event.type as null or an empty string
* will also trigger this exception.
*
DISPATCH_REQUEST_ERR: Raised if the Event object is
* already being dispatched.
* @exception DOMException
* NOT_SUPPORTED_ERR: Raised if the Event object has not
* been created using DocumentEvent.createEvent().
*
INVALID_CHARACTER_ERR: Raised if Event.type is not
* an NCName as defined in [XML Namespaces 1.1]
* .
* @version DOM Level 3
*/
public boolean dispatchEvent(Event evt)
throws EventException;
}