EventTarget interface is implemented by all the objects
* which could be event targets in an implementation which supports the .
* The interface allows registration and removal of event listeners, and
* dispatch of events to an event target.
* When used with , 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. In order to register a listener for a
* different event group () the previously registered listener has to be
* removed first.
*
See also the
Document Object Model (DOM) Level 3 Events Specification
.
* @since DOM Level 2
*/
public interface EventTarget {
/**
* This method allows the registration of an event listener in the
* default group and, 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
* parameters namespaceURI and evtGroup.
* @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);
/**
* This method allows the removal of event listeners from the default
* group. 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.
*
Note: Event listeners registered for other event groups
* than the default group cannot be removed using this method; see
* EventTarget.removeEventListenerNS() for that effect.
* @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);
/**
* This method allows the dispatch of events 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, DOMException;
/**
* This method allows the registration of an event listener in a
* specified group or the default group and, depending on the
* useCapture parameter, on the capture phase of the DOM
* event flow or its target and bubbling phases.
* @param namespaceURI Specifies the Event.namespaceURI
* associated with the event for which the user is registering.
* @param type Refer to the EventTarget.addEventListener()
* method for a description of this parameter.
* @param listener Refer to the
* EventTarget.addEventListener() method for a
* description of this parameter.
* @param useCapture Refer to the
* EventTarget.addEventListener() method for a
* description of this parameter.
* @param evtGroup The object that represents the event group to
* associate with the EventListener (see also ). Use
* null to attach the event listener to the default
* group.
* @since DOM Level 3
*/
public void addEventListenerNS(String namespaceURI,
String type,
EventListener listener,
boolean useCapture,
Object evtGroup);
/**
* This method allows the removal of an event listener, independently of
* the associated event group. Calling removeEventListenerNS
* with arguments which do not identify any currently registered
* EventListener on the EventTarget has no
* effect.
* @param namespaceURI Specifies the Event.namespaceURI
* associated with the event for which the user registered the event
* listener.
* @param type Refer to the
* EventTarget.removeEventListener() method for a
* description of this parameter.
* @param listener Refer to the
* EventTarget.removeEventListener() method for a
* description of this parameter.
* @param useCapture Refer to the
* EventTarget.removeEventListener() method for a
* description of this parameter.
* @since DOM Level 3
*/
public void removeEventListenerNS(String namespaceURI,
String type,
EventListener listener,
boolean useCapture);
}