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: /**
016: * The <code>Event</code> interface is used to provide contextual information
017: * about an event to the listener processing the event. An object which
018: * implements the <code>Event</code> interface is passed as the parameter to
019: * an <code>EventListener</code>. More specific context information is
020: * passed to event listeners by deriving additional interfaces from
021: * <code>Event</code> which contain information directly relating to the
022: * type of event they represent. These derived interfaces are also
023: * implemented by the object passed to the event listener.
024: * <p> To create an instance of the <code>Event</code> interface, use the
025: * <code>DocumentEvent.createEvent("Event")</code> method call.
026: * <p>See also the <a href='http://www.w3.org/TR/2006/WD-DOM-Level-3-Events-20060413'>
027: Document Object Model (DOM) Level 3 Events Specification
028: </a>.
029: * @since DOM Level 2
030: */
031: public interface Event {
032: // PhaseType
033: /**
034: * The current event phase is the capture phase.
035: */
036: public static final short CAPTURING_PHASE = 1;
037: /**
038: * The current event is in the target phase, i.e. it is being evaluated
039: * at the event target.
040: */
041: public static final short AT_TARGET = 2;
042: /**
043: * The current event phase is the bubbling phase.
044: */
045: public static final short BUBBLING_PHASE = 3;
046:
047: /**
048: * 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/2004/REC-xml-names11-20040204/'>XML Namespaces 1.1</a>]
049: * and is case-sensitive.
050: */
051: public String getType();
052:
053: /**
054: * Used to indicate the event target. This attribute contains the target
055: * node when used with the .
056: */
057: public EventTarget getTarget();
058:
059: /**
060: * Used to indicate the <code>EventTarget</code> whose
061: * <code>EventListeners</code> are currently being processed. This is
062: * particularly useful during the capture and bubbling phases. This
063: * attribute could contain the target node or a target ancestor when
064: * used with the .
065: */
066: public EventTarget getCurrentTarget();
067:
068: /**
069: * Used to indicate which phase of event flow is currently being
070: * accomplished.
071: */
072: public short getEventPhase();
073:
074: /**
075: * Used to indicate whether or not an event is a bubbling event. If the
076: * event can bubble the value is <code>true</code>, otherwise the value
077: * is <code>false</code>.
078: */
079: public boolean getBubbles();
080:
081: /**
082: * Used to indicate whether or not an event can have its default action
083: * prevented (see also ). If the default action can be prevented the
084: * value is <code>true</code>, otherwise the value is <code>false</code>
085: * .
086: */
087: public boolean getCancelable();
088:
089: /**
090: * Used to specify the time at which the event was created in
091: * milliseconds relative to 1970-01-01T00:00:00Z. Due to the fact that
092: * some systems may not provide this information the value of
093: * <code>timeStamp</code> may be not available for all events. When not
094: * available, the value is <code>0</code>.
095: */
096: public long getTimeStamp();
097:
098: /**
099: * This method is used to prevent event listeners of the same group to be
100: * triggered but its effect is deferred until all event listeners
101: * attached on the <code>Event.currentTarget</code> have been triggered
102: * (see ). Once it has been called, further calls to that method have no
103: * additional effect.
104: * <p ><b>Note:</b> This method does not prevent the default action from
105: * being invoked; use <code>Event.preventDefault()</code> for that
106: * effect.
107: */
108: public void stopPropagation();
109:
110: /**
111: * If an event is cancelable, the <code>preventDefault</code> method is
112: * used to signify that the event is to be canceled, meaning any default
113: * action normally taken by the implementation as a result of the event
114: * will not occur (see also ), and thus independently of event groups.
115: * Calling this method for a non-cancelable event has no effect.
116: * <p ><b>Note:</b> This method does not stop the event propagation; use
117: * <code>Event.stopPropagation()</code> or
118: * <code>Event.stopImmediatePropagation()</code> for that effect.
119: */
120: public void preventDefault();
121:
122: /**
123: * The <code>initEvent</code> method is used to initialize the value of
124: * an <code>Event</code> created through the
125: * <code>DocumentEvent.createEvent</code> method. This method may only
126: * be called before the <code>Event</code> has been dispatched via the
127: * <code>EventTarget.dispatchEvent()</code> method. If the method is
128: * called several times before invoking
129: * <code>EventTarget.dispatchEvent</code>, only the final invocation
130: * takes precedence. This method has no effect if called after the event
131: * has been dispatched. If called from a subclass of the
132: * <code>Event</code> interface only the values specified in this method
133: * are modified, all other attributes are left unchanged.
134: * <br> This method sets the <code>Event.type</code> attribute to
135: * <code>eventTypeArg</code>, and <code>Event.namespaceURI</code> to
136: * <code>null</code>. To initialize an event with a namespace URI, use
137: * the <code>Event.initEventNS()</code> method.
138: * @param eventTypeArg Specifies <code>Event.type</code>, the local name
139: * of the event type.
140: * @param canBubbleArg Specifies <code>Event.bubbles</code>. This
141: * parameter overrides the intrinsic bubbling behavior of the event.
142: * @param cancelableArg Specifies <code>Event.cancelable</code>. This
143: * parameter overrides the intrinsic cancelable behavior of the event.
144: *
145: */
146: public void initEvent(String eventTypeArg, boolean canBubbleArg,
147: boolean cancelableArg);
148:
149: /**
150: * The namespace URI associated with this event at creation time, or
151: * <code>null</code> if it is unspecified.
152: * <br> For events initialized with a DOM Level 2 Events method, such as
153: * <code>Event.initEvent()</code>, this is always <code>null</code>.
154: * @since DOM Level 3
155: */
156: public String getNamespaceURI();
157:
158: /**
159: * This method is used to prevent event listeners of the same group to be
160: * triggered and, unlike <code>Event.stopPropagation()</code> its effect
161: * is immediate (see ). Once it has been called, further calls to that
162: * method have no additional effect.
163: * <p ><b>Note:</b> This method does not prevent the default action from
164: * being invoked; use <code>Event.preventDefault()</code> for that
165: * effect.
166: * @since DOM Level 3
167: */
168: public void stopImmediatePropagation();
169:
170: /**
171: * Used to indicate whether <code>Event.preventDefault()</code> has been
172: * called for this event.
173: * @since DOM Level 3
174: */
175: public boolean getDefaultPrevented();
176:
177: /**
178: * The <code>initEventNS</code> method is used to initialize the value of
179: * an <code>Event</code> object and has the same behavior as
180: * <code>Event.initEvent()</code>.
181: * @param namespaceURIArg Specifies <code>Event.namespaceURI</code>, the
182: * namespace URI associated with this event, or <code>null</code> if
183: * no namespace.
184: * @param eventTypeArg Refer to the <code>Event.initEvent()</code>
185: * method for a description of this parameter.
186: * @param canBubbleArg Refer to the <code>Event.initEvent()</code>
187: * method for a description of this parameter.
188: * @param cancelableArg Refer to the <code>Event.initEvent()</code>
189: * method for a description of this parameter.
190: * @since DOM Level 3
191: */
192: public void initEventNS(String namespaceURIArg,
193: String eventTypeArg, boolean canBubbleArg,
194: boolean cancelableArg);
195:
196: }
|