Event.java revision 8eed706474910ccb978acda03e85d3261037da6e
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 public String getNamespaceURI(); 14 * 2) REMOVE public void stopImmediatePropagation(); 15 * 3) REMOVE public boolean getDefaultPrevented(); 16 * 4) REMOVE public void initEventNS(String namespaceURIArg, 17 * String eventTypeArg, 18 * boolean canBubbleArg, 19 * boolean cancelableArg); 20 * 5) ADD public void initEvent(String eventTypeArg, 21 * boolean canBubbleArg, 22 * boolean cancelableArg, 23 * int seekTo); 24 * 25 * 6) ADD public int getSeekTo(); 26 */ 27 28package org.w3c.dom.events; 29 30/** 31 * The <code>Event</code> interface is used to provide contextual information 32 * about an event to the listener processing the event. An object which 33 * implements the <code>Event</code> interface is passed as the parameter to 34 * an <code>EventListener</code>. The object passed to the event listener 35 * may also implement derived interfaces that provide access to information 36 * directly relating to the type of event they represent. 37 * <p> To create an instance of the <code>Event</code> interface, use the 38 * <code>DocumentEvent.createEvent("Event")</code> method call. 39 * <p>See also the <a href='http://www.w3.org/TR/2007/WD-DOM-Level-3-Events-20071207'> 40 Document Object Model (DOM) Level 3 Events Specification 41 </a>. 42 * @since DOM Level 2 43 */ 44public interface Event { 45 // PhaseType 46 /** 47 * The current event phase is the capture phase. 48 */ 49 public static final short CAPTURING_PHASE = 1; 50 /** 51 * The current event is in the target phase, i.e. it is being evaluated 52 * at the event target. 53 */ 54 public static final short AT_TARGET = 2; 55 /** 56 * The current event phase is the bubbling phase. 57 */ 58 public static final short BUBBLING_PHASE = 3; 59 60 /** 61 * The local name of the event type. The name must be 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>] 62 * and is case-sensitive. 63 */ 64 public String getType(); 65 66 /** 67 * Used to indicate the event target. This attribute contains the target 68 * node when used with the . 69 */ 70 public EventTarget getTarget(); 71 72 /** 73 * Used to indicate the <code>EventTarget</code> whose 74 * <code>EventListeners</code> are currently being processed. This is 75 * particularly useful during the capture and bubbling phases. This 76 * attribute could contain the target node or a target ancestor when 77 * used with the . 78 */ 79 public EventTarget getCurrentTarget(); 80 81 /** 82 * Used to indicate which phase of event flow is currently being 83 * accomplished. 84 */ 85 public short getEventPhase(); 86 87 /** 88 * Used to indicate whether or not an event is a bubbling event. If the 89 * event can bubble the value is <code>true</code>, otherwise the value 90 * is <code>false</code>. 91 */ 92 public boolean getBubbles(); 93 94 /** 95 * Used to indicate whether or not an event can have its default action 96 * prevented (see also ). If the default action can be prevented the 97 * value is <code>true</code>, otherwise the value is <code>false</code> 98 * . 99 */ 100 public boolean getCancelable(); 101 102 /** 103 * Used to specify the time at which the event was created in 104 * milliseconds relative to 1970-01-01T00:00:00Z. Due to the fact that 105 * some systems may not provide this information the value of 106 * <code>timeStamp</code> may be not available for all events. When not 107 * available, the value is <code>0</code>. 108 */ 109 public long getTimeStamp(); 110 111 /** 112 * Prevents other event listeners from being triggered but its effect is 113 * deferred until all event listeners attached on the 114 * <code>Event.currentTarget</code> have been triggered . Once it has 115 * been called, further calls to this method have no additional effect. 116 * <p ><b>Note:</b> This method does not prevent the default action from 117 * being invoked; use <code>Event.preventDefault()</code> for that 118 * effect. 119 */ 120 public void stopPropagation(); 121 122 /** 123 * Signifies that the event is to be canceled, meaning any default action 124 * normally taken by the implementation as a result of the event will 125 * not occur (see also ). Calling this method for a non-cancelable event 126 * has no effect. 127 * <p ><b>Note:</b> This method does not stop the event propagation; use 128 * <code>Event.stopPropagation()</code> or 129 * <code>Event.stopImmediatePropagation()</code> for that effect. 130 */ 131 public void preventDefault(); 132 133 /** 134 * Initializes attributes of an <code>Event</code> created through the 135 * <code>DocumentEvent.createEvent</code> method. This method may only 136 * be called before the <code>Event</code> has been dispatched via the 137 * <code>EventTarget.dispatchEvent()</code> method. If the method is 138 * called several times before invoking 139 * <code>EventTarget.dispatchEvent</code>, only the final invocation 140 * takes precedence. This method has no effect if called after the event 141 * has been dispatched. If called from a subclass of the 142 * <code>Event</code> interface only the values specified in this method 143 * are modified, all other attributes are left unchanged. 144 * <br> This method sets the <code>Event.type</code> attribute to 145 * <code>eventTypeArg</code>, and <code>Event.namespaceURI</code> to 146 * <code>null</code>. To initialize an event with a namespace URI, use 147 * the <code>Event.initEventNS()</code> method. 148 * @param eventTypeArg Specifies <code>Event.type</code>, the local name 149 * of the event type. 150 * @param canBubbleArg Specifies <code>Event.bubbles</code>. This 151 * parameter overrides the intrinsic bubbling behavior of the event. 152 * @param cancelableArg Specifies <code>Event.cancelable</code>. This 153 * parameter overrides the intrinsic cancelable behavior of the event. 154 * 155 */ 156 public void initEvent(String eventTypeArg, 157 boolean canBubbleArg, 158 boolean cancelableArg); 159 160 /** 161 * Initializes attributes of an <code>Event</code> created through the 162 * <code>DocumentEvent.createEvent</code> method. This method may only 163 * be called before the <code>Event</code> has been dispatched via the 164 * <code>EventTarget.dispatchEvent()</code> method. If the method is 165 * called several times before invoking 166 * <code>EventTarget.dispatchEvent</code>, only the final invocation 167 * takes precedence. This method has no effect if called after the event 168 * has been dispatched. If called from a subclass of the 169 * <code>Event</code> interface only the values specified in this method 170 * are modified, all other attributes are left unchanged. 171 * <br> This method sets the <code>Event.type</code> attribute to 172 * <code>eventTypeArg</code>, and <code>Event.namespaceURI</code> to 173 * <code>null</code>. To initialize an event with a namespace URI, use 174 * the <code>Event.initEventNS()</code> method. 175 * @param eventTypeArg Specifies <code>Event.type</code>, the local name 176 * of the event type. 177 * @param canBubbleArg Specifies <code>Event.bubbles</code>. This 178 * parameter overrides the intrinsic bubbling behavior of the event. 179 * @param cancelableArg Specifies <code>Event.cancelable</code>. This 180 * parameter overrides the intrinsic cancelable behavior of the event. 181 * @param seekTo Specifies <code>Event.seekTo</code>. the int seekTo of event. 182 * 183 */ 184 public void initEvent(String eventTypeArg, 185 boolean canBubbleArg, 186 boolean cancelableArg, 187 int seekTo); 188 189 public int getSeekTo(); 190} 191