1 /* 2 * Copyright (c) 2007 World Wide Web Consortium, 3 * 4 * (Massachusetts Institute of Technology, European Research Consortium for 5 * Informatics and Mathematics, Keio University). All Rights Reserved. This 6 * work is distributed under the W3C(r) Software License [1] in the hope that 7 * it will be useful, but WITHOUT ANY WARRANTY; without even the implied 8 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 9 * 10 * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 11 * 12 * Difference to the original copy of this file: 13 * 1) REMOVE DOMException thrown by dispatchEvent(Event evt); 14 * 2) REMOVE public void addEventListenerNS(String namespaceURI, 15 * String type, 16 * EventListener listener, 17 * boolean useCapture); 18 * 3) REMOVE public void removeEventListenerNS(String namespaceURI, 19 * String type, 20 * EventListener listener, 21 * boolean useCapture); 22 */ 23 24 package org.w3c.dom.events; 25 26 /** 27 * The <code>EventTarget</code> interface is implemented by all the objects 28 * which could be event targets in an implementation which supports an event 29 * flow. The interface allows registration and removal of event listeners, 30 * and dispatch of events to an event target. 31 * <p> When used with the DOM event flow, this interface is implemented by all 32 * target nodes and target ancestors, i.e. all DOM <code>Nodes</code> of the 33 * tree support this interface when the implementation conforms to DOM Level 34 * 3 Events and, therefore, this interface can be obtained by using 35 * binding-specific casting methods on an instance of the <code>Node</code> 36 * interface. 37 * <p> Invoking <code>addEventListener</code> or 38 * <code>addEventListenerNS</code> repeatedly on the same 39 * <code>EventTarget</code> with the same values for the parameters 40 * <code>namespaceURI</code>, <code>type</code>, <code>listener</code>, and 41 * <code>useCapture</code> has no effect. Doing so does not cause the 42 * <code>EventListener</code> to be called more than once and does not cause 43 * a change in the triggering order. 44 * <p>See also the <a href='http://www.w3.org/TR/2007/WD-DOM-Level-3-Events-20071207'> 45 Document Object Model (DOM) Level 3 Events Specification 46 </a>. 47 * @since DOM Level 2 48 */ 49 public interface EventTarget { 50 /** 51 * Registers an event listener, depending on the <code>useCapture</code> 52 * parameter, on the capture phase of the DOM event flow or its target 53 * and bubbling phases. Invoking this method is equivalent to invoking 54 * <code>addEventListenerNS</code> with the same values for the 55 * parameters <code>type</code>, <code>listener</code>, and 56 * <code>useCapture</code>, and the value <code>null</code> for the 57 * parameter <code>namespaceURI</code>. 58 * @param type Specifies the <code>Event.type</code> associated with the 59 * event for which the user is registering. 60 * @param listener The <code>listener</code> parameter takes an object 61 * implemented by the user which implements the 62 * <code>EventListener</code> interface and contains the method to be 63 * called when the event occurs. 64 * @param useCapture If true, <code>useCapture</code> indicates that the 65 * user wishes to add the event listener for the capture phase only, 66 * i.e. this event listener will not be triggered during the target 67 * and bubbling phases. If <code>false</code>, the event listener will 68 * only be triggered during the target and bubbling phases. 69 */ addEventListener(String type, EventListener listener, boolean useCapture)70 public void addEventListener(String type, 71 EventListener listener, 72 boolean useCapture); 73 74 /** 75 * Removes an event listener. Calling <code>removeEventListener</code> 76 * with arguments which do not identify any currently registered 77 * <code>EventListener</code> on the <code>EventTarget</code> has no 78 * effect. The <code>Event.namespaceURI</code> for which the user 79 * registered the event listener is implied and is <code>null</code>. 80 * @param type Specifies the <code>Event.type</code> for which the user 81 * registered the event listener. 82 * @param listener The <code>EventListener</code> to be removed. 83 * @param useCapture Specifies whether the <code>EventListener</code> 84 * being removed was registered for the capture phase or not. If a 85 * listener was registered twice, once for the capture phase and once 86 * for the target and bubbling phases, each must be removed 87 * separately. Removal of an event listener registered for the capture 88 * phase does not affect the same event listener registered for the 89 * target and bubbling phases, and vice versa. 90 */ removeEventListener(String type, EventListener listener, boolean useCapture)91 public void removeEventListener(String type, 92 EventListener listener, 93 boolean useCapture); 94 95 /** 96 * Dispatches an event into the implementation's event model. The event 97 * target of the event is the <code>EventTarget</code> object on which 98 * <code>dispatchEvent</code> is called. 99 * @param evt The event to be dispatched. 100 * @return Indicates whether any of the listeners which handled the 101 * event called <code>Event.preventDefault()</code>. If 102 * <code>Event.preventDefault()</code> was called the returned value 103 * is <code>false</code>, else it is <code>true</code>. 104 * @exception EventException 105 * UNSPECIFIED_EVENT_TYPE_ERR: Raised if the <code>Event.type</code> 106 * was not specified by initializing the event before 107 * <code>dispatchEvent</code> was called. Specification of the 108 * <code>Event.type</code> as <code>null</code> or an empty string 109 * will also trigger this exception. 110 * <br> DISPATCH_REQUEST_ERR: Raised if the <code>Event</code> object is 111 * already being dispatched. 112 * @exception DOMException 113 * NOT_SUPPORTED_ERR: Raised if the <code>Event</code> object has not 114 * been created using <code>DocumentEvent.createEvent()</code>. 115 * <br> INVALID_CHARACTER_ERR: Raised if <code>Event.type</code> is not 116 * an <a href='http://www.w3.org/TR/2004/REC-xml-names11-20040204/#NT-NCName'>NCName</a> as defined in [<a href='http://www.w3.org/TR/2006/REC-xml-names11-20060816'>XML Namespaces 1.1</a>] 117 * . 118 * @version DOM Level 3 119 */ dispatchEvent(Event evt)120 public boolean dispatchEvent(Event evt) 121 throws EventException; 122 123 } 124