001    /*
002     * Copyright (c) 2000 World Wide Web Consortium,
003     * (Massachusetts Institute of Technology, Institut National de
004     * Recherche en Informatique et en Automatique, Keio University). All
005     * Rights Reserved. This program is distributed under the W3C's Software
006     * Intellectual Property License. This program is distributed in the
007     * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
008     * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
009     * PURPOSE.
010     * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
011     */
012    
013    package org.w3c.dom.events;
014    
015    /**
016     *  The <code>EventTarget</code> interface is implemented by all
017     * <code>Nodes</code> in an implementation which supports the DOM Event
018     * Model. Therefore, this interface can be obtained by using
019     * binding-specific casting methods on an instance of the <code>Node</code>
020     * interface. The interface allows registration and removal of
021     * <code>EventListeners</code> on an <code>EventTarget</code> and dispatch
022     * of events to that <code>EventTarget</code>.
023     * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113'>Document Object Model (DOM) Level 2 Events Specification</a>.
024     * @since DOM Level 2
025     */
026    public interface EventTarget {
027        /**
028         * This method allows the registration of event listeners on the event
029         * target. If an <code>EventListener</code> is added to an
030         * <code>EventTarget</code> while it is processing an event, it will not
031         * be triggered by the current actions but may be triggered during a
032         * later stage of event flow, such as the bubbling phase.
033         * <br> If multiple identical <code>EventListener</code>s are registered
034         * on the same <code>EventTarget</code> with the same parameters the
035         * duplicate instances are discarded. They do not cause the
036         * <code>EventListener</code> to be called twice and since they are
037         * discarded they do not need to be removed with the
038         * <code>removeEventListener</code> method.
039         * @param type The event type for which the user is registering
040         * @param listener The <code>listener</code> parameter takes an interface
041         *   implemented by the user which contains the methods to be called
042         *   when the event occurs.
043         * @param useCapture If true, <code>useCapture</code> indicates that the
044         *   user wishes to initiate capture. After initiating capture, all
045         *   events of the specified type will be dispatched to the registered
046         *   <code>EventListener</code> before being dispatched to any
047         *   <code>EventTargets</code> beneath them in the tree. Events which
048         *   are bubbling upward through the tree will not trigger an
049         *   <code>EventListener</code> designated to use capture.
050         */
051        public void addEventListener(String type,
052                                     EventListener listener,
053                                     boolean useCapture);
054    
055        /**
056         * This method allows the removal of event listeners from the event
057         * target. If an <code>EventListener</code> is removed from an
058         * <code>EventTarget</code> while it is processing an event, it will not
059         * be triggered by the current actions. <code>EventListener</code>s can
060         * never be invoked after being removed.
061         * <br>Calling <code>removeEventListener</code> with arguments which do
062         * not identify any currently registered <code>EventListener</code> on
063         * the <code>EventTarget</code> has no effect.
064         * @param type Specifies the event type of the <code>EventListener</code>
065         *   being removed.
066         * @param listener The <code>EventListener</code> parameter indicates the
067         *   <code>EventListener </code> to be removed.
068         * @param useCapture Specifies whether the <code>EventListener</code>
069         *   being removed was registered as a capturing listener or not. If a
070         *   listener was registered twice, one with capture and one without,
071         *   each must be removed separately. Removal of a capturing listener
072         *   does not affect a non-capturing version of the same listener, and
073         *   vice versa.
074         */
075        public void removeEventListener(String type,
076                                        EventListener listener,
077                                        boolean useCapture);
078    
079        /**
080         * This method allows the dispatch of events into the implementations
081         * event model. Events dispatched in this manner will have the same
082         * capturing and bubbling behavior as events dispatched directly by the
083         * implementation. The target of the event is the
084         * <code> EventTarget</code> on which <code>dispatchEvent</code> is
085         * called.
086         * @param evt Specifies the event type, behavior, and contextual
087         *   information to be used in processing the event.
088         * @return The return value of <code>dispatchEvent</code> indicates
089         *   whether any of the listeners which handled the event called
090         *   <code>preventDefault</code>. If <code>preventDefault</code> was
091         *   called the value is false, else the value is true.
092         * @exception EventException
093         *   UNSPECIFIED_EVENT_TYPE_ERR: Raised if the <code>Event</code>'s type
094         *   was not specified by initializing the event before
095         *   <code>dispatchEvent</code> was called. Specification of the
096         *   <code>Event</code>'s type as <code>null</code> or an empty string
097         *   will also trigger this exception.
098         */
099        public boolean dispatchEvent(Event evt)
100                                     throws EventException;
101    
102    }