001 
002 /*
003  *  JScripter Standard 1.0 - To Script In Java
004  *  Copyright (C) 2008-2011  J.J.Liu<jianjunliu@126.com> <http://www.jscripter.org>
005  *  
006  *  This program is free software: you can redistribute it and/or modify
007  *  it under the terms of the GNU Affero General Public License as published by
008  *  the Free Software Foundation, either version 3 of the License, or
009  *  (at your option) any later version.
010  *  
011  *  This program is distributed in the hope that it will be useful,
012  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
013  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014  *  GNU Affero General Public License for more details.
015  *  
016  *  You should have received a copy of the GNU Affero General Public License
017  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
018  */
019 
020 package js.dom;
021 
022 import js.core.*;
023 import js.user.*;
024 
025 /**
026  * <p>An <b>opaque</b> interface from <tt>EventTarget</tt> interface of DOM Level2 Event.</p>
027  *
028  * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.jscripter.org" target="_blank">http://www.jscripter.org</a>
029  *
030  * @javascript <b>Opaque</b> types can be resolved but no class objects for them can be
031  * generated into the target codes. Re-compilers must exit with error on the operations of
032  * accessing that kind of class objects.
033  * The <tt>checkcast</tt> operation to the class literal of this interface must be ignored
034  * and <tt>instanceof</tt> to it always <tt>true</tt>.
035  */
036 public interface EventTarget
037 {
038     /**
039      * <p>Adds an event handler function to the set of event handlers for this element. 
040      * This is a DOM-standard method supported by all modern browsers except IE.</p>
041      * <p>This method adds the specified event <tt>listener</tt> function to the set of 
042      * listeners registered on this node to handle events of the specified <tt>type</tt>. 
043      * If <tt>useCapture</tt> is <tt>true</tt>, the <tt>listener</tt> is registered as 
044      * a capturing event listener. If <tt>useCapture</tt> is <tt>false</tt>, it is 
045      * registered as a normal event listener.</p>
046      * <p>This method may be called multiple times to register multiple event handlers 
047      * for the same type of event on the same node. Note, however, that the DOM 
048      * Specification makes no guarantees about the order in which multiple event handlers 
049      * are invoked.</p>
050      * <p>If the same event listener function is registered twice on the same node with 
051      * the same <tt>type</tt> and <tt>useCapture</tt> arguments, the second registration 
052      * is simply ignored. If a new event listener is registered on this node while an 
053      * event is being handled at this node, the new event listener is not invoked for 
054      * that event.</p>
055      * <p>When a node is duplicated with {@link JsNode#cloneNode(Boolean)} or {@link JsDocument#importNode(JsNode, Boolean)}, 
056      * the event listeners registered for the original node are not copied.</p>
057      * <p>The same method is also defined by, and works analogously on, the {@link JsDocument} 
058      * and {@link JsWindow} objects.</p>
059      * @param type The type of event for which the event listener is to be invoked.
060      * @param listener The event listener function that is invoked when an event of the 
061      * specified type is dispatched to this node. When invoked, the listener function 
062      * is passed an {@link JsEvent} object and is invoked as a method of the node on 
063      * which it is registered.
064      * @param useCapture If <tt>true</tt>, the specified <tt>listener</tt> is to be 
065      * invoked only during the capturing phase of event propagation. The more common 
066      * value of <tt>false</tt> means that the <tt>listener</tt> is not invoked during 
067      * the capturing phase but instead is invoked when this node is the actual event 
068      * target or when the event bubbles up to this node from its original target.
069      * @since 1.0
070      * @see #attachEvent(String, JsFunction)
071      * @see #removeEventListener(String, JsFunction, Boolean)
072      * @see JsDocument#addEventListener(String, JsFunction, Boolean)
073      * @see JsWindow#addEventListener(String, JsFunction, Boolean)
074      * @javascript Re-compilers must convert the interface invocation of this method directly
075      * into a JavaScript invocation on its current object instance without changing the 
076      * method name, but expanding variable arguments, if any, into comma-separated values. 
077      */
078     public void addEventListener(String type, JsFunction<?> listener, Boolean useCapture);
079     /**
080      * <p>Removes an event handler function from the set of handlers for this element. 
081      * This is a standard DOM method implemented by all modern browsers except IE.</p>
082      * <p>This method removes the specified event <tt>listener</tt> function. The <tt>type</tt> 
083      * and <tt>useCapture</tt> arguments must be the same as they are in the 
084      * corresponding call to {@link #addEventListener(String, JsFunction, Boolean)}. If 
085      * no event listener is found that matches the specified arguments, this method does 
086      * nothing.</p>
087      * <p>Once an event <tt>listener</tt> function has been removed by this method, it 
088      * will no longer be invoked for the specified <tt>type</tt> of event on this node. 
089      * This is true even if the event <tt>listener</tt> is removed by another event 
090      * listener registered for the same type of event on the same node.</p>
091      * <p>The same method is also defined by, and works analogously on, the {@link JsDocument} 
092      * and {@link JsWindow} objects</p>
093      * @param type The type of event for which the event listener is to be deleted.
094      * @param listener The event listener function that is to be removed.
095      * @param useCapture <tt>true</tt> if a capturing event listener is to be removed; 
096      * <tt>false</tt> if a normal event listener is to be removed.
097      * @since 1.0
098      * @see #detachEvent(String, JsFunction)
099      * @see #addEventListener(String, JsFunction, Boolean)
100      * @see JsDocument#removeEventListener(String, JsFunction, Boolean)
101      * @see JsWindow#removeEventListener(String, JsFunction, Boolean)
102      * @javascript Re-compilers must convert the interface invocation of this method directly
103      * into a JavaScript invocation on its current object instance without changing the 
104      * method name, but expanding variable arguments, if any, into comma-separated values. 
105      */
106     public void removeEventListener(String type, JsFunction<?> listener, Boolean useCapture);
107     /**
108      * <p>Adds an event handler function to the set of handlers for this element. 
109      * This is the IE-specific alternative to {@link #addEventListener(String, JsFunction, Boolean)}.</p>
110      * <p>This method is an IE-specific event registration method. It serves the same 
111      * purpose as the standard {@link #addEventListener(String, JsFunction, Boolean)} 
112      * method, which IE does not support, but is different from that function in several 
113      * important ways:
114      * <ul>
115      * <li>Since the IE event model does not support event capturing, this method and 
116      * {@link #detachEvent(String, JsFunction)} expect only two arguments: the event 
117      * type and the handler function.</li>
118      * <li>The event handler names passed to the IE methods should include the "on" 
119      * prefix.</li>
120      * <li>Functions registered with this method are invoked with no {@link JsEvent} 
121      * {@link JsWindow#event} property of 
122      * {@link JsWindow#window} object.</li>
123      * <li>Functions registered with this method are invoked as global functions, rather 
124      * than as methods of the node on which the event occurred. That is, when an event 
125      * handler registered with this method executes, the <tt>this</tt> keyword refers to 
126      * {@link JsWindow#window} object, not to the event's target node.</li>
127      * <li>This method allows the same event handler function to be registered more than 
128      * once. When an event of the specified type occurs, the registered function is 
129      * invoked as many times as it is registered.</li>
130      * </ul>
131      * </p>
132      * <p>The same method is also defined by, and works analogously on, the {@link JsDocument} 
133      * and {@link JsWindow} objects</p>
134      * @param type The type of event for which the event listener is to be invoked, with 
135      * a leading "on" prefix.
136      * @param listener The event listener function that is invoked when an event of the 
137      * specified type is dispatched to this node. This function is not passed any 
138      * {@link JsWindow#event} 
139      * property of the {@link JsWindow} object.
140      * @since 1.0
141      * @see #addEventListener(String, JsFunction, Boolean)
142      * @see #detachEvent(String, JsFunction)
143      * @see JsDocument#attachEvent(String, JsFunction)
144      * @see JsWindow#attachEvent(String, JsFunction)
145      * @javascript Re-compilers must convert the interface invocation of this method directly
146      * into a JavaScript invocation on its current object instance without changing the 
147      * method name, but expanding variable arguments, if any, into comma-separated values. 
148      */
149     public void attachEvent(String type, JsFunction<?> listener);
150     /**
151      * <p>Removes an event handler function from this element. This is the IE-specific 
152      * alternative to the standard {@link #removeEventListener(String, JsFunction, Boolean)} 
153      * method.</p>
154      * <p>This method undoes the event handler function registration performed by the 
155      * {@link #attachEvent(String, JsFunction)} method. It is the IE-specific analog to 
156      * the standard {@link #removeEventListener(String, JsFunction, Boolean)}. To remove 
157      * an event handler function for a node, simply invoke this method with the same 
158      * arguments you originally passed to {@link #attachEvent(String, JsFunction)}.</p>
159      * <p>The same method is also defined by, and works analogously on, the {@link JsDocument} 
160      * and {@link JsWindow} objects</p>
161      * @param type The type of event for which the event listener is to be invoked, with 
162      * a leading "on" prefix.
163      * @param listener The event listener function that is to be removed.
164      * @since 1.0
165      * @see #removeEventListener(String, JsFunction, Boolean)
166      * @see #attachEvent(String, JsFunction)
167      * @see JsDocument#detachEvent(String, JsFunction)
168      * @see JsWindow#detachEvent(String, JsFunction)
169      * @javascript Re-compilers must convert the interface invocation of this method directly
170      * into a JavaScript invocation on its current object instance without changing the 
171      * method name, but expanding variable arguments, if any, into comma-separated values. 
172      */
173     public void detachEvent(String type, JsFunction<?> listener);
174 }