/*
 * Copyright (c) 2007 World Wide Web Consortium,
 *
 * (Massachusetts Institute of Technology, European Research Consortium for
 * Informatics and Mathematics, Keio University). All Rights Reserved. This
 * work is distributed under the W3C(r) Software License [1] in the hope that
 * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 *
 * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
 *
 * Difference to the original copy of this file:
 *   1) REMOVE public boolean canDispatch(String namespaceURI,
 *                             String type);
 */

package org.w3c.dom.events;

import org.w3c.dom.DOMException;

/**
 *  The <code>DocumentEvent</code> interface provides a mechanism by which the
 * user can create an <code>Event</code> object of a type supported by the
 * implementation. If the feature "Events" is supported by the
 * <code>Document</code> object, the <code>DocumentEvent</code> interface
 * must be implemented on the same object. If the feature "+Events" is
 * supported by the <code>Document</code> object, an object that supports
 * the <code>DocumentEvent</code> interface must be returned by invoking the
 * method <code>Node.getFeature("+Events", "3.0")</code> on the
 * <code>Document</code> object.
 * <p>See also the <a href='http://www.w3.org/TR/2007/WD-DOM-Level-3-Events-20071207'>
   Document Object Model (DOM) Level 3 Events Specification
  </a>.
 * @since DOM Level 2
 */
public interface DocumentEvent {
    /**
     *  Creates an event object of the type specified.
     * @param eventType  The <code>eventType</code> parameter specifies the
     *   name of the DOM Events interface to be supported by the created
     *   event object, e.g. <code>"Event"</code>, <code>"MouseEvent"</code>,
     *   <code>"MutationEvent"</code> and so on. If the <code>Event</code>
     *   is to be dispatched via the <code>EventTarget.dispatchEvent()</code>
     *    method the appropriate event initialization method must be called
     *   after creation in order to initialize the <code>Event</code>'s
     *   values.  As an example, a user wishing to synthesize some kind of
     *   <code>UIEvent</code> would invoke
     *   <code>DocumentEvent.createEvent("UIEvent")</code>. The
     *   <code>UIEvent.initUIEventNS()</code> method could then be called on
     *   the newly created <code>UIEvent</code> object to set the specific
     *   type of user interface event to be dispatched, DOMActivate for
     *   example, and set its context information, e.g.
     *   <code>UIEvent.detail</code> in this example.  For backward
     *   compatibility reason, "UIEvents", "MouseEvents", "MutationEvents",
     *   and "HTMLEvents" feature names are valid values for the parameter
     *   <code>eventType</code> and represent respectively the interfaces
     *   "UIEvent", "MouseEvent", "MutationEvent", and "Event", and the
     *   characters 'a'..'z' are considered equivalent to the characters
     *   'A'..'Z'.
     * @return  The newly created event object.
     * @exception DOMException
     *    NOT_SUPPORTED_ERR: Raised if the implementation does not support the
     *   <code>Event</code> interface requested.
     */
    public Event createEvent(String eventType)
                             throws DOMException;

}