using System;
namespace SharpVectors.Dom.Events{
/// <summary>
/// The <see cref="IDocumentEvent">IDocumentEvent</see> interface provides
/// a mechanism by which the user can create an
/// <see cref="IEvent">IEvent</see> object of a type supported by the
/// implementation. It is expected that the
/// <see cref="IDocumentEvent">IDocumentEvent</see> interface will be
/// implemented on the same object which implements the
/// <see cref="IDocument">IDocument</see> interface in an implementation
/// which supports the <see cref="IEvent">IEvent</see> model.
/// </summary>
public interface IDocumentEvent
{
#region Methods
#region DOM Level 2
/// <summary>
/// The <see cref="CreateEvent">CreateEvent</see> method is used in
/// creating <see cref="IEvent">IEvent</see>s when it is either
/// inconvenient or unnecessary for the user to create an
/// <see cref="IEvent">IEvent</see> themselves.
/// </summary>
/// <remarks>
/// <para>
/// In cases where the implementation provided
/// <see cref="IEvent">IEvent</see> is insufficient, users may supply
/// their own <see cref="IEvent">IEvent</see> implementations for use
/// with the
/// <see cref="IEventTarget.DispatchEvent">IEventTarget.DispatchEvent</see>
/// method. However, the DOM implementation needs access to the
/// attributes
/// <see cref="IEvent.CurrentTarget">IEvent.CurrentTarget</see> and
/// <see cref="IEvent.EventPhase">IEvent.EventPhase</see> to propagate
/// appropriately the event in the DOM tree. Therefore users'
/// <see cref="IEvent">IEvent</see> implementations might need to
/// support the <see cref="ICustomEvent">ICustomEvent</see> interface
/// for that effect.
/// </para>
/// <para>
/// Note: For backward compatibility reason, <c>"UIEvents"</c>,
/// <c>"MouseEvents"</c>, <c>"MutationEvents"</c>, and
/// <c>"HTMLEvents"</c> feature names are valid values for the
/// parameter <c>eventType</c> and represent respectively the
/// interfaces <c>"UIEvent"</c>, <c>"MouseEvent"</c>,
/// <c>"MutationEvent"</c>, and <c>"Event"</c>.
/// </para>
/// </remarks>
/// <param name="eventType">
/// The <c>eventType</c> parameter specifies the name of the DOM
/// Events interface to be supported by the created event object, e.g.
/// <c>"Event"</c>, <c>"MouseEvent"</c>, <c>"MutationEvent"</c> ...
/// If the <see cref="IEvent">IEvent</see> is to be dispatched via the
/// <see cref="IEventTarget.DispatchEvent">IEventTarget.DispatchEvent</see>
/// method the appropriate event init method must be called after
/// creation in order to initialize the <see cref="IEvent">IEvent</see>'s
/// values. As an example, a user wishing to synthesize some kind of
/// <see cref="IUiEvent">IUiEvent</see> would call
/// <see cref="IDocumentEvent.CreateEvent">IDocumentEvent.CreateEvent</see>
/// with the parameter <c>"UIEvent"</c>. The
/// <see cref="IUiEvent.InitUiEventNs">IUiEvent.InitUiEventNs</see>
/// method could then be called on the newly created
/// <see cref="IUiEvent">IUiEvent</see> object to set the specific
/// type of user interface event to be dispatched,
/// {<c>"http://www.w3.org/2001/xml-events"</c>,
/// <c>"DOMActivate"</c>} for example, and set its context
/// information, e.g.
/// <see cref="IUiEvent.Detail">IUiEvent.Detail</see> in this example.
/// </param>
/// <returns>
/// The newly created event object.
/// </returns>
/// <exception cref="DomException">
/// NOT_SUPPORTED_ERR: Raised if the implementation does not support
/// the <see cref="IEvent">Event</see> interface requested.
/// </exception>
IEvent CreateEvent(
string eventType);
#endregion
#region DOM Level 3 Experimental
/// <summary>
/// Test if the implementation can generate events of a specified type.
/// </summary>
/// <param name="namespaceUri">
/// Specifies the
/// <see cref="IEvent.NamespaceUri">IEvent.NamespaceUri</see> of the
/// event.
/// </param>
/// <param name="type">
/// Specifies the <see cref="IEvent.Type">IEvent.Type</see> of the
/// event.
/// </param>
/// <returns>
/// <c>true</c> if the implementation can generate and dispatch this
/// event type, <c>false</c> otherwise.
/// </returns>
bool CanDispatch(
string namespaceUri,
string type);
#endregion
#endregion
}
}
|