001: /*
002: * Copyright (c) 2006 World Wide Web Consortium,
003: *
004: * (Massachusetts Institute of Technology, European Research Consortium for
005: * Informatics and Mathematics, Keio University). All Rights Reserved. This
006: * work is distributed under the W3C(r) Software License [1] in the hope that
007: * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
008: * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
009: *
010: * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
011: */
012:
013: package org.w3c.dom.events;
014:
015: import org.w3c.dom.DOMException;
016:
017: /**
018: * The <code>EventTarget</code> interface is implemented by all the objects
019: * which could be event targets in an implementation which supports the .
020: * The interface allows registration and removal of event listeners, and
021: * dispatch of events to an event target.
022: * <p> When used with , this interface is implemented by all target nodes and
023: * target ancestors, i.e. all DOM <code>Nodes</code> of the tree support
024: * this interface when the implementation conforms to DOM Level 3 Events
025: * and, therefore, this interface can be obtained by using binding-specific
026: * casting methods on an instance of the <code>Node</code> interface.
027: * <p> Invoking <code>addEventListener</code> or
028: * <code>addEventListenerNS</code> repeatedly on the same
029: * <code>EventTarget</code> with the same values for the parameters
030: * <code>namespaceURI</code>, <code>type</code>, <code>listener</code>, and
031: * <code>useCapture</code> has no effect. Doing so does not cause the
032: * <code>EventListener</code> to be called more than once and does not cause
033: * a change in the triggering order. In order to register a listener for a
034: * different event group () the previously registered listener has to be
035: * removed first.
036: * <p>See also the <a href='http://www.w3.org/TR/2006/WD-DOM-Level-3-Events-20060413'>
037: Document Object Model (DOM) Level 3 Events Specification
038: </a>.
039: * @since DOM Level 2
040: */
041: public interface EventTarget {
042: /**
043: * This method allows the registration of an event listener in the
044: * default group and, depending on the <code>useCapture</code>
045: * parameter, on the capture phase of the DOM event flow or its target
046: * and bubbling phases. Invoking this method is equivalent to invoking
047: * <code>addEventListenerNS</code> with the same values for the
048: * parameters <code>type</code>, <code>listener</code>, and
049: * <code>useCapture</code>, and the value <code>null</code> for the
050: * parameters <code>namespaceURI</code> and <code>evtGroup</code>.
051: * @param type Specifies the <code>Event.type</code> associated with the
052: * event for which the user is registering.
053: * @param listener The <code>listener</code> parameter takes an object
054: * implemented by the user which implements the
055: * <code>EventListener</code> interface and contains the method to be
056: * called when the event occurs.
057: * @param useCapture If true, <code>useCapture</code> indicates that the
058: * user wishes to add the event listener for the capture phase only,
059: * i.e. this event listener will not be triggered during the target
060: * and bubbling phases. If <code>false</code>, the event listener will
061: * only be triggered during the target and bubbling phases.
062: */
063: public void addEventListener(String type, EventListener listener,
064: boolean useCapture);
065:
066: /**
067: * This method allows the removal of event listeners from the default
068: * group. Calling <code>removeEventListener</code> with arguments which
069: * do not identify any currently registered <code>EventListener</code>
070: * on the <code>EventTarget</code> has no effect. The
071: * <code>Event.namespaceURI</code> for which the user registered the
072: * event listener is implied and is <code>null</code>.
073: * <p ><b>Note:</b> Event listeners registered for other event groups
074: * than the default group cannot be removed using this method; see
075: * <code>EventTarget.removeEventListenerNS()</code> for that effect.
076: * @param type Specifies the <code>Event.type</code> for which the user
077: * registered the event listener.
078: * @param listener The <code>EventListener</code> to be removed.
079: * @param useCapture Specifies whether the <code>EventListener</code>
080: * being removed was registered for the capture phase or not. If a
081: * listener was registered twice, once for the capture phase and once
082: * for the target and bubbling phases, each must be removed
083: * separately. Removal of an event listener registered for the capture
084: * phase does not affect the same event listener registered for the
085: * target and bubbling phases, and vice versa.
086: */
087: public void removeEventListener(String type,
088: EventListener listener, boolean useCapture);
089:
090: /**
091: * This method allows the dispatch of events into the implementation's
092: * event model. The event target of the event is the
093: * <code>EventTarget</code> object on which <code>dispatchEvent</code>
094: * is called.
095: * @param evt The event to be dispatched.
096: * @return Indicates whether any of the listeners which handled the
097: * event called <code>Event.preventDefault()</code>. If
098: * <code>Event.preventDefault()</code> was called the returned value
099: * is <code>false</code>, else it is <code>true</code>.
100: * @exception EventException
101: * UNSPECIFIED_EVENT_TYPE_ERR: Raised if the <code>Event.type</code>
102: * was not specified by initializing the event before
103: * <code>dispatchEvent</code> was called. Specification of the
104: * <code>Event.type</code> as <code>null</code> or an empty string
105: * will also trigger this exception.
106: * <br> DISPATCH_REQUEST_ERR: Raised if the <code>Event</code> object is
107: * already being dispatched.
108: * @exception DOMException
109: * NOT_SUPPORTED_ERR: Raised if the <code>Event</code> object has not
110: * been created using <code>DocumentEvent.createEvent()</code>.
111: * <br> INVALID_CHARACTER_ERR: Raised if <code>Event.type</code> is not
112: * 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/2004/REC-xml-names11-20040204/'>XML Namespaces 1.1</a>]
113: * .
114: * @version DOM Level 3
115: */
116: public boolean dispatchEvent(Event evt) throws EventException,
117: DOMException;
118:
119: /**
120: * This method allows the registration of an event listener in a
121: * specified group or the default group and, depending on the
122: * <code>useCapture</code> parameter, on the capture phase of the DOM
123: * event flow or its target and bubbling phases.
124: * @param namespaceURI Specifies the <code>Event.namespaceURI</code>
125: * associated with the event for which the user is registering.
126: * @param type Refer to the <code>EventTarget.addEventListener()</code>
127: * method for a description of this parameter.
128: * @param listener Refer to the
129: * <code>EventTarget.addEventListener()</code> method for a
130: * description of this parameter.
131: * @param useCapture Refer to the
132: * <code>EventTarget.addEventListener()</code> method for a
133: * description of this parameter.
134: * @param evtGroup The object that represents the event group to
135: * associate with the <code>EventListener</code> (see also ). Use
136: * <code>null</code> to attach the event listener to the default
137: * group.
138: * @since DOM Level 3
139: */
140: public void addEventListenerNS(String namespaceURI, String type,
141: EventListener listener, boolean useCapture, Object evtGroup);
142:
143: /**
144: * This method allows the removal of an event listener, independently of
145: * the associated event group. Calling <code>removeEventListenerNS</code>
146: * with arguments which do not identify any currently registered
147: * <code>EventListener</code> on the <code>EventTarget</code> has no
148: * effect.
149: * @param namespaceURI Specifies the <code>Event.namespaceURI</code>
150: * associated with the event for which the user registered the event
151: * listener.
152: * @param type Refer to the
153: * <code>EventTarget.removeEventListener()</code> method for a
154: * description of this parameter.
155: * @param listener Refer to the
156: * <code>EventTarget.removeEventListener()</code> method for a
157: * description of this parameter.
158: * @param useCapture Refer to the
159: * <code>EventTarget.removeEventListener()</code> method for a
160: * description of this parameter.
161: * @since DOM Level 3
162: */
163: public void removeEventListenerNS(String namespaceURI, String type,
164: EventListener listener, boolean useCapture);
165:
166: }
|