source: branches/HeuristicLab.Problems.GrammaticalOptimization/SharpVectorCore/Events/IEventTarget.cs @ 12762

using System;

namespace SharpVectors.Dom.Events
{
  /// <summary>
  /// The <see cref="IEventTarget">IEventTarget</see> interface is
  /// implemented by all the objects which could be
  /// <see href="http://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/glossary.html#dt-event-target">event targets</see>
  /// in an implementation which supports the
  /// <see href="http://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/events.html#Events-flows">Event flows</see>.
  /// </summary>
  /// <remarks>
  /// <para>
  /// The interface allows registration, removal or query of event
  /// listeners, and dispatch of events to an event target.
  /// </para>
  /// <para>
  /// When used with
  /// <see href="http://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/events.html#Events-flow">DOM event flow</see>,
  /// this interface is implemented by all
  /// <see href="http://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/glossary.html#dt-target-node">target nodes</see>
  /// and target ancestors, i.e. all DOM <see cref="INode">INode</see>s of
  /// the tree support this interface when the implementation conforms to
  /// DOM Level 3 Events and, therefore, this interface can be obtained by
  /// using binding-specific casting methods on an instance of the
  /// <see cref="INode">Node</see> interface.
  /// </para>
  /// <para>
  /// Invoking multiple times
  /// <see cref="AddEventListener">AddEventListener</see> or
  /// <see cref="AddEventListenerNs">AddEventListenerNs</see> on the same
  /// <see cref="IEventTarget">IEventTarget</see> with the same parameters
  /// (<c>namespaceUri</c>, <c>type</c>, <c>listener</c>, and
  /// <c>useCapture</c>) is considered to be a no-op and thus independently
  /// of the event group. They do not cause the
  /// <see cref="EventListener">EventListener</see> to be called more
  /// than once and do not cause a change in the triggering order. In order
  /// to guarantee that an event listener will be added to the event target
  /// for the specified event group, one needs to invoke
  /// <see cref="RemoveEventListener">RemoveEventListener</see> or
  /// <see cref="RemoveEventListenerNs">RemoveEventListenerNs</see> first.
  /// </para>
  /// </remarks>
  public interface IEventTarget
  {
    #region Methods
    
    #region DOM Level 2
    
    /// <summary>
    /// This method allows the registration of an event listener in the
    /// default group and, depending on the <c>useCapture</c> parameter,
    /// on the capture phase of the DOM event flow or its target and
    /// bubbling phases. <see cref=" http://www.w3.org/TR/SVG/interact.html#SVGEvents"/>
    /// </summary>
    /// <param name="type">
    /// Specifies the <see cref="IEvent.Type">IEvent.Type</see> associated
    /// with the event for which the user is registering. 
    /// </param>
    /// <param name="listener">
    /// The listener parameter takes an object implemented by the user
    /// which implements the
    /// <see cref="EventListener">EventListener</see> interface and
    /// contains the method to be called when the event occurs.
    /// </param>
    /// <param name="useCapture">
    /// If <c>true</c>, <c>useCapture</c> indicates that the user wishes
    /// to add the event listener for the
    /// <see href="http://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/glossary.html#dt-capture-phase">capture phase</see>
    /// only, i.e. this event listener will not be triggered during the
    /// <see href="http://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/glossary.html#dt-target-phase">target</see>
    /// and
    /// <see href="http://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/glossary.html#dt-bubbling-phase">bubbling phases</see>.
    /// If <c>false</c>, the event listener will only be triggered during the target and bubbling phases.
    /// </param>
    void AddEventListener(
      string type,
      EventListener listener,
      bool useCapture);
    
    /// <summary>
    /// This method allows the removal of event listeners from the default
    /// group.
    /// </summary>
    /// <remarks>
    /// Calling <see cref="RemoveEventListener">RemoveEventListener</see>
    /// with arguments which do not identify any currently registered
    /// <see cref="EventListener">EventListener</see> on the
    /// <see cref="IEventTarget">IEventTarget</see> has no effect. 
    /// </remarks>
    /// <param name="type">
    /// Specifies the <see cref="IEvent.Type">IEvent.Type</see> for which
    /// the user registered the event listener.
    /// </param>
    /// <param name="listener">
    /// The <see cref="EventListener">EventListener</see> to be removed.
    /// </param>
    /// <param name="useCapture">
    /// Specifies whether the
    /// <see cref="EventListener">EventListener</see> being removed was
    /// registered for the capture phase or not. If a listener was
    /// registered twice, once for the capture phase and once for the
    /// target and bubbling phases, each must be removed separately.
    /// Removal of an event listener registered for the capture phase does
    /// not affect the same event listener registered for the target and
    /// bubbling phases, and vice versa.
    /// </param>
    void RemoveEventListener(
      string type,
      EventListener listener,
      bool useCapture);
    
    /// <summary>
    /// This method allows the dispatch of events into the
    /// implementation's event model.
    /// </summary>
    /// <remarks>
    /// The
    /// <see href="http://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/glossary.html#dt-event-target">event target</see>
    /// of the event is the <see cref="IEventTarget">IEventTarget</see>
    /// object on which <see cref="DispatchEvent">DispatchEvent</see>
    /// is called.
    /// </remarks>
    /// <param name="evt">
    /// The event to be dispatched.
    /// </param>
    /// <returns>
    /// Indicates whether any of the listeners which handled the event
    /// called
    /// <see cref="IEvent.PreventDefault">IEvent.PreventDefault</see>.
    /// If <see cref="IEvent.PreventDefault">IEvent.PreventDefault</see>
    /// was called the returned value is <c>false</c>, else it is
    /// <c>true</c>.
    /// </returns>
    /// <exception cref="EventException">
    /// <para>
    /// UNSPECIFIED_EVENT_TYPE_ERR: Raised if the Event.type was not
    /// specified by initializing the event before dispatchEvent was
    /// called. Specification of the Event.type as null or an empty
    /// string will also trigger this exception.
    /// </para>
    /// <para>
    /// DISPATCH_REQUEST_ERR: Raised if the Event object is already being
    /// dispatched in the tree.
    /// </para>
    /// <para>
    /// NOT_SUPPORTED_ERR: Raised if the Event object has not been
    /// created using DocumentEvent.createEvent or does not support the
    /// interface CustomEvent.
    /// </para>
    /// </exception>
    bool DispatchEvent(
      IEvent evt);
    
    #endregion
    
    #region DOM Level 3 Experimental
    
    /// <summary>
    /// This method allows the registration of an event listener in a
    /// specified group or the default group and, depending on the
    /// <c>useCapture</c> parameter, on the capture phase of the DOM
    /// event flow or its target and bubbling phases.
    /// </summary>
    /// <param name="namespaceUri">
    /// Specifies the
    /// <see cref="IEvent.NamespaceUri">IEvent.NamespaceUri</see>
    /// associated with the event for which the user is registering.
    /// </param>
    /// <param name="type">
    /// Specifies the <see cref="IEvent.Type">IEvent.Type</see>
    /// associated with the event for which the user is registering.
    /// </param>
    /// <param name="listener">
    /// The <c>listener</c> parameter takes an object implemented by
    /// the user which implements the
    /// <see cref="EventListener">EventListener</see> interface and
    /// contains the method to be called when the event occurs.
    /// </param>
    /// <param name="useCapture">
    /// If <c>true</c>, <c>useCapture</c> indicates that the user wishes
    /// to add the event listener for the
    /// <see href="http://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/glossary.html#dt-capture-phase">capture phase only</see>,
    /// i.e. this event listener will not be triggered during the
    /// <see href="http://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/glossary.html#dt-target-phase">target</see>
    /// and
    /// <see href="http://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/glossary.html#dt-bubbling-phase">bubbling phases</see>.
    /// If <c>false</c>, the event listener will only be triggered
    /// during the target and bubbling phases.
    /// </param>
    /// <param name="evtGroup">
    /// The object that represents the event group to associate with the
    /// <see cref="EventListener">EventListener</see>. Use <c>null</c> to
    /// attach the event listener to the default group.
    /// </param>
    /// <seealso href="http://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/events.html#Events-propagation-and-groups">
    /// Event propagation and event groups
    /// </seealso>
    void AddEventListenerNs(
      string namespaceUri,
      string type,
      EventListener listener,
      bool useCapture,
      object evtGroup);
    
    /// <summary>
    /// This method allows the removal of event listeners from a specified
    /// group or the default group.
    /// </summary>
    /// <remarks>
    /// Calling
    /// <see cref="RemoveEventListenerNs">RemoveEventListenerNs</see> with
    /// arguments which do not identify any currently registered
    /// <see cref="EventListener">EventListener</see> on the EventTarget
    /// has no effect.
    /// </remarks>
    /// <param name="namespaceUri">
    /// Specifies the
    /// <see cref="IEvent.NamespaceUri">IEvent.NamespaceUri</see>
    /// associated with the event for which the user registered the event
    /// listener.
    /// </param>
    /// <param name="type">
    /// Specifies the <see cref="IEvent.Type">IEvent.Type</see> associated
    /// with the event for which the user registered the event listener.
    /// </param>
    /// <param name="listener">
    /// The <see cref="EventListener">EventListener</see> parameter
    /// indicates the <see cref="EventListener">EventListener</see> to
    /// be removed.
    /// </param>
    /// <param name="useCapture">
    /// Specifies whether the
    /// <see cref="EventListener">EventListener</see> being removed was
    /// registered for the capture phase or not. If a listener was
    /// registered twice, once for the capture phase and once for the
    /// target and bubbling phases, each must be removed separately.
    /// Removal of an event listener registered for the capture phase
    /// does not affect the same event listener registered for the target
    /// and bubbling phases, and vice versa.
    /// </param>
    void RemoveEventListenerNs(
      string namespaceUri,
      string type,
      EventListener listener,
      bool useCapture);
    
    /// <summary>
    /// This method allows the DOM application to know if an event
    /// listener, attached to this
    /// <see cref="IEventTarget">IEventTarget</see> or one of its
    /// ancestors, will be triggered by the specified event type during
    /// the dispatch of the event to this event target or one of its
    /// descendants.
    /// </summary>
    /// <param name="namespaceUri">
    /// Specifies the
    /// <see cref="IEvent.NamespaceUri">IEvent.NamespaceUri</see>
    /// associated with the event.
    /// </param>
    /// <param name="type">
    /// Specifies the <see cref="IEvent.Type">IEvent.Type</see>
    /// associated with the event.
    /// </param>
    /// <returns>
    /// <c>true</c> if an event listener will be triggered on the
    /// <see cref="IEventTarget">IEventTarget</see> with the specified
    /// event type, <c>false</c> otherwise.
    /// </returns>
    bool WillTriggerNs(
      string namespaceUri,
      string type);
    
    /// <summary>
    /// This method allows the DOM application to know if this
    /// <see cref="IEventTarget">IEventTarget</see> contains an event
    /// listener registered for the specified event type.
    /// </summary>
    /// <remarks>
    /// This is useful for determining at which nodes within a hierarchy
    /// altered handling of specific event types has been introduced, but
    /// should not be used to determine whether the specified event type
    /// triggers an event listener.
    /// </remarks>
    /// <param name="namespaceUri">
    /// Specifies the
    /// <see cref="IEvent.NamespaceUri">IEvent.NamespaceUri</see>
    /// associated with the event.
    /// </param>
    /// <param name="type">
    /// Specifies the <see cref="IEvent.Type">IEvent.Type</see>
    /// associated with the event.
    /// </param>
    /// <returns>
    /// <c>true</c> if an event listener is registered on this
    /// <see cref="IEventTarget">IEventTarget</see> for the specified
    /// event type, <c>false</c> otherwise.
    /// </returns>
    /// <seealso cref="WillTriggerNs">WillTriggerNs</seealso>
    bool HasEventListenerNs(
      string namespaceUri,
      string type);
    
    #endregion
    
    #endregion
  }
}