trunk/src/bind/java/org/w3c/dom/events/Event.java

   1 /*
   2  * Copyright (c) 2003 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
  13 package org.w3c.dom.events;
  14
  15 /**
  16  *  The <code>Event</code> interface is used to provide contextual information
  17  * about an event to the listener processing the event. An object which
  18  * implements the <code>Event</code> interface is passed as the parameter to
  19  * an <code>EventListener</code>. More specific context information is
  20  * passed to event listeners by deriving additional interfaces from
  21  * <code>Event</code> which contain information directly relating to the
  22  * type of event they represent. These derived interfaces are also
  23  * implemented by the object passed to the event listener.
  24  * <p> To create an instance of the <code>Event</code> interface, use the
  25  * <code>DocumentEvent.createEvent("Event")</code> method call.
  26  * <p>See also the <a href='http://www.w3.org/TR/2003/NOTE-DOM-Level-3-Events-20031107'>Document Object Model (DOM) Level 3 Events Specification</a>.
  27  * @since DOM Level 2
  28  */
  29 public interface Event {
  30     // PhaseType
  31     /**
  32      *  The current event phase is the capture phase.
  33      */
  34     public static final short CAPTURING_PHASE           = 1;
  35     /**
  36      *  The current event is in the target phase, i.e. it is being evaluated
  37      * at the event target.
  38      */
  39     public static final short AT_TARGET                 = 2;
  40     /**
  41      *  The current event phase is the bubbling phase.
  42      */
  43     public static final short BUBBLING_PHASE            = 3;
  44
  45     /**
  46      *  The name should be an <a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/#NT-NCName'>NCName</a> as defined in [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>]
  47      *  and is case-sensitive.
  48      * <br> If the attribute <code>Event.namespaceURI</code> is different from
  49      * <code>null</code>, this attribute represents a local name.
  50      */
  51     public String getType();
  52
  53     /**
  54      *  Used to indicate the event target. This attribute contains the target
  55      * node when used with the .
  56      */
  57     public EventTarget getTarget();
  58
  59     /**
  60      *  Used to indicate the <code>EventTarget</code> whose
  61      * <code>EventListeners</code> are currently being processed. This is
  62      * particularly useful during the capture and bubbling phases. This
  63      * attribute could contain the target node or a target ancestor when
  64      * used with the .
  65      */
  66     public EventTarget getCurrentTarget();
  67
  68     /**
  69      *  Used to indicate which phase of event flow is currently being
  70      * accomplished.
  71      */
  72     public short getEventPhase();
  73
  74     /**
  75      *  Used to indicate whether or not an event is a bubbling event. If the
  76      * event can bubble the value is <code>true</code>, otherwise the value
  77      * is <code>false</code>.
  78      */
  79     public boolean getBubbles();
  80
  81     /**
  82      *  Used to indicate whether or not an event can have its default action
  83      * prevented (see also ). If the default action can be prevented the
  84      * value is <code>true</code>, otherwise the value is <code>false</code>
  85      * .
  86      */
  87     public boolean getCancelable();
  88
  89     /**
  90      *  Used to specify the time (in milliseconds relative to the epoch) at
  91      * which the event was created. Due to the fact that some systems may
  92      * not provide this information the value of <code>timeStamp</code> may
  93      * be not available for all events. When not available, a value of
  94      * <code>0</code> will be returned. Examples of epoch time are the time
  95      * of the system start or 0:0:0 UTC 1st January 1970.
  96      */
  97     public long getTimeStamp();
  98
  99     /**
 100      *  This method is used to prevent event listeners of the same group to be
 101      * triggered but its effect is deferred until all event listeners
 102      * attached on the <code>currentTarget</code> have been triggered (see
 103      * ). Once it has been called, further calls to that method have no
 104      * additional effect.
 105      * <p ><b>Note:</b>  This method does not prevent the default action from
 106      * being invoked; use <code>preventDefault</code> for that 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>stopPropagation</code> or <code>stopImmediatePropagation</code>
 118      * 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(namespaceURIArg, eventTypeArg, ...)</code>
 138      *  method.
 139      * @param eventTypeArg  Specifies <code>Event.type</code>.
 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     public void initEvent(String eventTypeArg,
 146                           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 will always return <code>false</code>, unless the event
 160      * implements the <code>CustomEvent</code> interface.
 161      * @return  <code>false</code>, unless the event object implements the
 162      *   <code>CustomEvent</code> interface.
 163      * @since DOM Level 3
 164      */
 165     public boolean isCustom();
 166
 167     /**
 168      *  This method is used to prevent event listeners of the same group to be
 169      * triggered and, unlike <code>stopPropagation</code> its effect is
 170      * immediate (see ). Once it has been called, further calls to that
 171      * method have no additional effect.
 172      * <p ><b>Note:</b>  This method does not prevent the default action from
 173      * being invoked; use <code>Event.preventDefault()</code> for that
 174      * effect.
 175      * @since DOM Level 3
 176      */
 177     public void stopImmediatePropagation();
 178
 179     /**
 180      *  This method will return <code>true</code> if the method
 181      * <code>Event.preventDefault()</code> has been called for this event,
 182      * <code>false</code> otherwise.
 183      * @return  <code>true</code> if <code>Event.preventDefault()</code> has
 184      *   been called for this event.
 185      * @since DOM Level 3
 186      */
 187     public boolean isDefaultPrevented();
 188
 189     /**
 190      *  The <code>initEventNS</code> method is used to initialize the value of
 191      * an <code>Event</code> object and has the same behavior as
 192      * <code>Event.initEvent()</code>.
 193      * @param namespaceURIArg  Specifies <code>Event.namespaceuRI</code>, the
 194      *   namespace URI associated with this event, or <code>null</code> if
 195      *   no namespace.
 196      * @param eventTypeArg  Specifies <code>Event.type</code>, the local name
 197      *   of the event type.
 198      * @param canBubbleArg  Refer to the <code>Event.initEvent()</code>
 199      *   method for a description of this parameter.
 200      * @param cancelableArg  Refer to the <code>Event.initEvent()</code>
 201      *   method for a description of this parameter.
 202      * @since DOM Level 3
 203      */
 204     public void initEventNS(String namespaceURIArg,
 205                             String eventTypeArg,
 206                             boolean canBubbleArg,
 207                             boolean cancelableArg);
 208
 209 }