src/bind/java/org/w3c/dom/events/DocumentEvent.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 import org.w3c.dom.DOMException;
  16
  17 /**
  18  *  The <code>DocumentEvent</code> interface provides a mechanism by which the
  19  * user can create an <code>Event</code> object of a type supported by the
  20  * implementation. If the feature "Events" is supported by the
  21  * <code>Document</code> object, the <code>DocumentEvent</code> interface
  22  * must be implemented on the same object. If the feature "+Events" is
  23  * supported by the <code>Document</code> object, an object that supports
  24  * the <code>DocumentEvent</code> interface must be returned by invoking the
  25  * method <code>Node.getFeature("+Events", "3.0")</code> on the
  26  * <code>Document</code> object.
  27  * <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>.
  28  * @since DOM Level 2
  29  */
  30 public interface DocumentEvent {
  31     /**
  32      *
  33      * @param eventType  The <code>eventType</code> parameter specifies the
  34      *   name of the DOM Events interface to be supported by the created
  35      *   event object, e.g. <code>"Event"</code>, <code>"MouseEvent"</code>,
  36      *   <code>"MutationEvent"</code> and so on. If the <code>Event</code>
  37      *   is to be dispatched via the <code>EventTarget.dispatchEvent()</code>
  38      *    method the appropriate event init method must be called after
  39      *   creation in order to initialize the <code>Event</code>'s values.
  40      *   As an example, a user wishing to synthesize some kind of
  41      *   <code>UIEvent</code> would invoke
  42      *   <code>DocumentEvent.createEvent("UIEvent")</code>. The
  43      *   <code>UIEvent.initUIEventNS()</code> method could then be called on
  44      *   the newly created <code>UIEvent</code> object to set the specific
  45      *   type of user interface event to be dispatched,
  46      *   <code>{"http://www.w3.org/2001/xml-events", "DOMActivate"}</code>
  47      *   for example, and set its context information, e.g.
  48      *   <code>UIEvent.detail</code> in this example.  The
  49      *   <code>createEvent</code> method is used in creating
  50      *   <code>Event</code>s when it is either inconvenient or unnecessary
  51      *   for the user to create an <code>Event</code> themselves. In cases
  52      *   where the implementation provided <code>Event</code> is
  53      *   insufficient, users may supply their own <code>Event</code>
  54      *   implementations for use with the
  55      *   <code>EventTarget.dispatchEvent()</code> method. However, the DOM
  56      *   implementation needs access to the attributes
  57      *   <code>Event.currentTarget</code> and <code>Event.eventPhase</code>
  58      *   to appropriately propagate the event in the DOM tree. Therefore
  59      *   users' <code>Event</code> implementations might need to support the
  60      *   <code>CustomEvent</code> interface for that effect.
  61      * <p ><b>Note:</b>    For backward compatibility reason, "UIEvents",
  62      *   "MouseEvents", "MutationEvents", and "HTMLEvents" feature names are
  63      *   valid values for the parameter <code>eventType</code> and represent
  64      *   respectively the interfaces "UIEvent", "MouseEvent",
  65      *   "MutationEvent", and "Event".
  66      * @return  The newly created event object.
  67      * @exception DOMException
  68      *    NOT_SUPPORTED_ERR: Raised if the implementation does not support the
  69      *   <code>Event</code> interface requested.
  70      */
  71     public Event createEvent(String eventType)
  72                              throws DOMException;
  73
  74     /**
  75      *  Test if the implementation can generate events of a specified type.
  76      * @param namespaceURI  Specifies the <code>Event.namespaceURI</code> of
  77      *   the event.
  78      * @param type  Specifies the <code>Event.type</code> of the event.
  79      * @return  <code>true</code> if the implementation can generate and
  80      *   dispatch this event type, <code>false</code> otherwise.
  81      * @since DOM Level 3
  82      */
  83     public boolean canDispatch(String namespaceURI,
  84                                String type);
  85
  86 }