src/bind/java/org/w3c/dom/events/CustomEvent.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>CustomEvent</code> interface gives access to the attributes
  17  * <code>Event.currentTarget</code> and <code>Event.eventPhase</code>. It is
  18  * intended to be used by the DOM Events implementation to access the
  19  * underlying current target and event phase while dispatching a custom
  20  * <code>Event</code> in the tree; it is also intended to be implemented,
  21  * and <em>not used</em>, by DOM applications.
  22  * <p> The methods contained in this interface are not intended to be used by
  23  * a DOM application, especially during the dispatch on the
  24  * <code>Event</code> object. Changing the current target or the current
  25  * phase may result in unpredictable results of the event flow. The DOM
  26  * Events implementation should ensure that both methods return the
  27  * appropriate current target and phase before invoking each event listener
  28  * on the current target to protect DOM applications from malicious event
  29  * listeners.
  30  * <p ><b>Note:</b>  If this interface is supported by the event object,
  31  * <code>Event.isCustom()</code> must return <code>true</code>.
  32  * <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>.
  33  * @since DOM Level 3
  34  */
  35 public interface CustomEvent extends Event {
  36     /**
  37      *  The <code>setDispatchState</code> method is used by the DOM Events
  38      * implementation to set the values of <code>Event.currentTarget</code>
  39      * and <code>Event.eventPhase</code>. It also reset the states of
  40      * <code>isPropagationStopped</code> and
  41      * <code>isImmediatePropagationStopped</code>.
  42      * @param target  Specifies the new value for the
  43      *   <code>Event.currentTarget</code> attribute.
  44      * @param phase  Specifies the new value for the
  45      *   <code>Event.eventPhase</code> attribute.
  46      */
  47     public void setDispatchState(EventTarget target,
  48                                  short phase);
  49
  50     /**
  51      *  This method will return <code>true</code> if the method
  52      * <code>stopPropagation()</code> has been called for this event,
  53      * <code>false</code> in any other cases.
  54      * @return  <code>true</code> if the event propagation has been stopped
  55      *   in the current group.
  56      */
  57     public boolean isPropagationStopped();
  58
  59     /**
  60      *  The <code>isImmediatePropagationStopped</code> method is used by the
  61      * DOM Events implementation to know if the method
  62      * <code>stopImmediatePropagation()</code> has been called for this
  63      * event. It returns <code>true</code> if the method has been called,
  64      * <code>false</code> otherwise.
  65      * @return  <code>true</code> if the event propagation has been stopped
  66      *   immediately in the current group.
  67      */
  68     public boolean isImmediatePropagationStopped();
  69
  70 }