using System;
namespace SharpVectors.Dom.Events{
/// <summary>
/// The <see cref="ICustomEvent">ICustomEvent</see> interface gives access
/// to the attributes
/// <see cref="IEvent.CurrentTarget">IEvent.CurrentTarget</see> and
/// <see cref="IEvent.EventPhase">IEvent.EventPhase</see>.
/// </summary>
/// <remarks>
/// <para>
/// It is intended
/// to be used by the DOM Events implementation to access the underlying
/// current target and event phase while dispatching a custom
/// <see cref="IEvent">IEvent</see> in the tree; it is also intended to be
/// implemented, and not used, by DOM applications.
/// </para>
/// <para>
/// The methods contained in this interface are not intended to be used by
/// a DOM application, especially during the dispatch on the Event object.
/// Changing the current target or the current phase may conduct into
/// unpredictable results of the event flow. The DOM Events implementation
/// should ensure that both methods return the appropriate current target
/// and phase before invoking each event listener on the current target to
/// protect DOM applications from malicious event listeners.
/// </para>
/// <para>
/// Note: If this interface is supported by the event object,
/// <see cref="IEvent.IsCustom">IEvent.IsCustom</see> must return
/// <c>true</c>.
/// </para>
/// </remarks>
public interface ICustomEvent
: IEvent
{
#region Properties
#region DOM Level 3 Experimental
/// <summary>
/// This method will return <c>true</c> if the method
/// <see cref="IEvent.StopPropagation">IEvent.StopPropagation</see> has been called
/// for this event, <c>false</c> in any other cases.
/// </summary>
/// <value>
/// <c>true</c> if the event propagation has been stopped in the
/// current group.
/// </value>
bool IsPropagationStopped
{
get;
}
/// <summary>
/// The
/// <see cref="IsImmediatePropagationStopped">IsImmediatePropagationStopped</see>
/// method is used by the DOM Events implementation to know if the
/// method
/// <see cref="IEvent.StopImmediatePropagation">IEvent.StopImmediatePropagation</see>
/// has been called for this event. It returns <c>true</c> if the
/// method has been called, <c>false</c> otherwise.
/// </summary>
bool IsImmediatePropagationStopped
{
get;
}
#endregion
#endregion
#region Methods
#region DOM Level 3 Experimental
/// <summary>
/// The <see cref="SetDispatchState">SetDispatchState</see> method is
/// used by the DOM Events implementation to set the values of
/// <see cref="IEvent.CurrentTarget">IEvent.CurrentTarget</see> and
/// <see cref="IEvent.EventPhase">IEvent.EventPhase</see>.
/// </summary>
/// <remarks>
/// It also reset the states of
/// <see cref="IsPropagationStopped">IsPropagationStopped</see> and
/// <see cref="IsImmediatePropagationStopped">IsImmediatePropagationStopped</see>.
/// </remarks>
/// <param name="target">
/// Specifies the new value for the
/// <see cref="IEvent.CurrentTarget">IEvent.CurrentTarget</see>
/// attribute.
/// </param>
/// <param name="phase">
/// Specifies the new value for the
/// <see cref="IEvent.EventPhase">IEvent.EventPhase</see> attribute.
/// </param>
void SetDispatchState(
IEventTarget target,
ushort phase);
#endregion
#endregion
}
}
|