Table of contents

Appendices

1.6 Basic interfaces

The interfaces described in this section are fundamental to DOM Level 3 Events and must always be supported by the implementation.

The Event interface is used to provide contextual information about an event to the listener processing the event. An object which implements the Event interface is passed as the parameter to an EventListener. More specific context information is passed to event listeners by deriving additional interfaces from Event which contain information directly relating to the type of event they represent. These derived interfaces are also implemented by the object passed to the event listener.

An integer indicating which phase of the event flow is being processed as defined in [DOM event flow].

The current event phase is the capture phase.

The current event is in the target phase, i.e. it is being evaluated at the event target.

The current event phase is the bubbling phase.

The name must be an NCName as defined in [Namespaces] and is case-sensitive. The character ":" (colon) should not be used in this attribute.

If the attribute Event.namespaceURI is different from null, this attribute represents a local name.

Used to indicate the event target. This attribute contain the target node when used with the [DOM event flow].

Used to indicate the EventTarget whose EventListeners are currently being processed. This is particularly useful during the capture and bubbling phases. This attribute could contain the target node or a target ancestor when used with the [DOM event flow].

Used to indicate which phase of event flow is currently being accomplished.

Used to indicate whether or not an event is a bubbling event. If the event can bubble the value is true, otherwise the value is false.

Used to indicate whether or not an event can have its default action prevented (see also [Default actions and cancelable events]). If the default action can be prevented the value is true, otherwise the value is false.

Used to specify the time (in milliseconds relative to the epoch) at which the event was created. Due to the fact that some systems may not provide this information the value of timeStamp may be not available for all events. When not available, a value of 0 will be returned. Examples of epoch time are the time of the system start or 0:0:0 UTC 1st January 1970.

This method is used to prevent event listeners of the same group to be triggered but its effect is differed until all event listeners attached on the currentTarget have been triggered (see [Event propagation and event groups]). Once it has been called, further calls to that method have no additional effect.

NOTE: 

This method does not prevent the default action from being invoked; use preventDefault for that effect.

If an event is cancelable, the preventDefault method is used to signify that the event is to be canceled, meaning any default action normally taken by the implementation as a result of the event will not occur (see also [Default actions and cancelable events]), and thus independently of event groups. Calling this method for a non-cancelable event has no effect.

NOTE: 

This method does not stop the event propagation; use stopPropagation or stopImmediatePropagation for that effect.

The initEvent method is used to initialize the value of an Event created through the DocumentEvent.createEvent method. This method may only be called before the Event has been dispatched via the EventTarget.dispatchEvent method. If the method is called several times before invoking EventTarget.dispatchEvent, only the final invocation takes precedence. If called from a subclass of Event interface only the values specified in this method are modified, all other attributes are left unchanged.

This method sets the Event.type attribute to eventTypeArg, and Event.localName and Event.namespaceURI to null. To initialize an event with a local name and namespace URI, use the initEventNS method.

Specifies the event type.

Specifies whether or not the event can bubble. This parameter overrides the intrinsic bubbling behavior of the event.

Specifies whether or not the event's default action can be prevented. This parameter overrides the intrinsic cancelable behavior of the event.

The namespace URI associated with this event at creation time, or null if it is unspecified.

For events initialized with a DOM Level 2 Events method, such as initEvent, this is always null.

This method will always return false, unless the event implements the CustomEvent interface.

true if preventDefault() has been called for this event.

This method is used to prevent event listeners of the same group to be triggered and, unlike stopPropagation its effect is immediate (see [Event propagation and event groups]). Once it has been called, further calls to that method have no additional effect.

NOTE: 

This method does not prevent the default action from being invoked; use preventDefault for that effect.

This method will return true if the method preventDefault() has been called for this event, false otherwise.

true if preventDefault() has been called for this event.

This method will return true if the method stopPropagation() has been called for this event in the current group, false in any other cases.

true if the event propagation has been stopped in the current group.

The initEventNS method is used to initialize the value of an Event created through the DocumentEvent interface. This method may only be called before the Event has been dispatched via the dispatchEvent method, though it may be called multiple times the event has been dispatched. If called multiple times the final invocation takes precedence. If a call to initEventNS is made after one of the Event derived interfaces' init methods has been called, only the values specified in the initEventNS method are modified, all other attributes are left unchanged.

This method sets the Event.type attribute to eventTypeArg, and Event.namespaceURI to namespaceURIArg.

Specifies the namespace URI associated with this event, or null if no namespace.

Specifies the local name of the event type (see also the description of Event.type).

Specifies whether or not the event can bubble.

Specifies whether or not the event's default action can be prevented.

The EventTarget interface is implemented by all the objects which could be event targets in an implementation which supports the [Event flows]. The interface allows registration, removal or query of event listeners, and dispatch of events to an event target.

When used with [DOM event flow], this interface is implemented by all target nodes and target ancestors, i.e. all DOM Nodes 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 Node interface.

When using addEventListener or addEventListenerNS, if multiple identical EventListeners are registered on the same EventTarget with the same parameters the duplicate instances are discarded. They do not cause the EventListener to be called twice and since they are discarded they do not need to be removed.

This method allows the registration of an event listener in the default group and, depending on the useCapture parameter, on the capture phase of the DOM event flow or its target and bubbling phases.

Specifies the Event.type associated with the event for which the user is registering.

The listener parameter takes an object implemented by the user which implements the EventListener interface and contains the method to be called when the event occurs.

If true, useCapture indicates that the user wishes to add the event listener for the capture phase only, i.e. this event listener will not be triggered during the target and bubbling phases. If false, the event listener will only be triggered during the target and bubbling phases.

This method allows the removal of event listeners from the default group.

Calling removeEventListener with arguments which do not identify any currently registered EventListener on the EventTarget has no effect.

Specifies the Event.type for which the user registered the event listener.

The EventListener to be removed.

Specifies whether the EventListener 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.

This method allows the dispatch of events into the implementation's event model. The event target of the event is the EventTarget object on which dispatchEvent is called.

Issue (1):

It is necessary to have an exception that occurs if the specified event is not an event which the implementation knows how to dispatch, if it was not created by calling DocumentEvent.createEvent and Event.isCustom() is false. NOT_SUPPORTED?

The event to be dispatched.

Indicates whether any of the listeners which handled the event called preventDefault. If preventDefault was called the returned value is false, else it is true.

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.

DISPATCH_REQUEST_ERR: Raised if the Event object is already being dispatched in the tree.

This method allows the registration of an event listener in a specified group or the default group and, depending on the useCapture parameter, on the capture phase of the DOM event flow or its target and bubbling phases.

Specifies the Event.namespaceURI associated with the event for which the user is registering.

Specifies the Event.type associated with the event for which the user is registering.

The listener parameter takes an object implemented by the user which implements the EventListener interface and contains the method to be called when the event occurs.

If true, useCapture indicates that the user wishes to add the event listener for the capture phase only, i.e. this event listener will not be triggered during the target and bubbling phases. If false, the event listener will only be triggered during the target and bubbling phases.

The EventListenerGroup to associate with the EventListener (see also [Event propagation and event groups]). Use null to attach the event listener to the default group.

This method allows the removal of event listeners from a specified group or the default group.

Calling removeEventListenerNS with arguments which do not identify any currently registered EventListener on the EventTarget has no effect.

Specifies the Event.namespaceURI associated with the event for which the user registered the event listener.

Specifies the Event.type associated with the event for which the user registered the event listener.

The EventListener parameter indicates the EventListener to be removed.

Specifies whether the EventListener 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.

The EventListenerGroup associated with the EventListener. Use null to reference the default group.

This method allows the DOM application to know if an event listener, attached to this EventTarget 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.

Specifies the Event.namespaceURI associated with the event.

Specifies the Event.type associated with the event.

true if an event listener will be triggered on the EventTarget with the specified event type, false otherwise.

This method allows the DOM application to know if this EventTarget contains an event listener registered for the specified event type. 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 (see willTriggerNS).

Issue (useCapture):

do we need a useCapture parameter?

Resolution:

No use case for that.

Specifies the Event.namespaceURI associated with the event.

Specifies the Event.type associated with the event.

true if an event listener is registered on this EventTarget for the specified event type, false otherwise.

The EventListener interface is the primary way for handling events. Users implement the EventListener interface and register their event listener on an EventTarget. The users should also remove their EventListener from its EventTarget after they have completed using the listener.

Copying a Node does not copy the event listeners attached to it. Event listeners must be attached to the newly created Node afterwards if so desired. Therefore, Nodes are copied using Node.cloneNode or Range.cloneContents, the EventListeners attached to the source Nodes are not attached to their copies.

Moving a Node does not affect the event listeners attached to it. Therefore, when Nodes are moved using Document.adoptNode, Node.appendChild, or Range.extractContents, the EventListeners attached to the moved Nodes stay attached to them.

This method is called whenever an event occurs of the event type for which the EventListener interface was registered.

The Event contains contextual information about the event.

Event listeners can be registered using Event.addEventListenerNS within a group.

When a set of actions associated with event listeners is critical for an application such as refreshing the display, it is important to separate them from other event listeners who might stop the event flow. In order to prevent undesirable side effects, the application should create a group using DocumentEvent.createEventListenerGroup and use it when adding or removing event listeners.

This method checks if the supplied EventListenerGroup is the same as the EventListenerGroup upon which the method is called.

The EventListenerGroup with which to check equality.

Returns true if the EventListenerGroups are the same, else returns false.

Issue (equal):

We should clarify what "equal" means here, or better yet, substitute it with "is the same"?

Event operations may throw an EventException as specified in their method descriptions.

An integer indicating the type of error generated.

If the Event.type was not specified by initializing the event before the method was called. Specification of the Event.type as null or an empty string will also trigger this exception.

If the Event object is already dispatched in the tree.

Event creation[top]

In most cases, the events dispatched by the DOM Events implementation are also created by the implementation. It is however possible to simulate events such as mouse events by creating the Event objects and dispatch them using the DOM Events implementation.

DOM Events provides two ways for creating Event objects. An application can either create Event objects that are known to the implementation, or create its own objects and have them dispatched by the DOM Events implementation.

Creating Event objects that are known to the DOM Events implementation is done using DocumentEvent.createEvent. The application must then initialize the object by calling the appropriate initialization method before invoking EventTarget.dispatchEvent. The Event objects created must be known by the DOM Events implementation otherwise an event exception is thrown.

The DOM application might want to create its own Event objects, in order to change the default Event implementation provided by the DOM Events implementation or to generate new event types with specific contextual information. In any case, the application is responsible for creating and initializing the Event object. The application can then dispatch the event using the DOM Events implementation by using EventTarget.dispatchEvent.

However, the DOM Events implementation requires to have access to two attributes in the Event object in order to accomplish the dispatch appropriately: Event.currentTarget and Event.eventPhase. Those attributes are defined as readonly in the Event interface since event listeners must not change them and it is the responsibility of the DOM Events implementation to update them during the event flow. Therefore, implementing the Event interface when creating its own events is not enough for an application since the DOM Events implementation will not be able to update the current phase and the current node during the dispatch, unless the event object also implements the CustomEvent interface to give access to the relevant attributes.

The DocumentEvent interface provides a mechanism by which the user can create an Event object of a type supported by the implementation. It is expected that the DocumentEvent interface will be implemented on the same object which implements the Document interface in an implementation which supports the Event model.

The eventType parameter specifies the name of the DOM Events interface to be supported by the created event object, e.g. "Event", "MouseEvent", "MutationEvent" ... If the Event is to be dispatched via the EventTarget.dispatchEvent method the appropriate event init method must be called after creation in order to initialize the Event's values.

As an example, a user wishing to synthesize some kind of UIEvent would call DocumentEvent.createEvent with the parameter "UIEvent". The UIEvent.initUIEventNS method could then be called on the newly created UIEvent object to set the specific type of user interface event to be dispatched, {"http://www.w3.org/2001/xml-events", "DOMActivate"} for example, and set its context information, e.g. UIEvent.detail in this example.

The createEvent method is used in creating Events when it is either inconvenient or unnecessary for the user to create an Event themselves. In cases where the implementation provided Event is insufficient, users may supply their own Event implementations for use with the EventTarget.dispatchEvent method. However, the DOM implementation needs access to the attributes Event.currentTarget and Event.eventPhase to propagate appropriately the event in the DOM tree. Therefore users' Event implementations might need to support the CustomEvent interface for that effect.

NOTE: 

For backward compatibility reason, "UIEvents", "MouseEvents", "MutationEvents", and "HTMLEvents" feature names are valid values for the parameter eventType and represent respectively the interfaces "UIEvent", "MouseEvent", "MutationEvent", and "Event".

The newly created event object.

NOT_SUPPORTED_ERR: Raised if the implementation does not support the Event interface requested.

This method creates a new EventListenerGroup for use in the addEventListenerNS and removeEventListenerNS methods of the EventTarget interface (see also [Event propagation and event groups]).

The newly created EventListenerGroup object.

Test if the implementation can generate events of a specified type.

Specifies the Event.namespaceURI of the event.

Specifies the Event.type of the event.

true if the implementation can generate and dispatch this event type, false otherwise.

The CustomEvent interface gives access to the attributes Event.currentTarget and Event.eventPhase. It is intended to be used by the DOM Events implementation to access the underlying current target and event phase while dispatching a custom Event in the tree; it is intended to be implemented, and not used, by DOM applications.

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.

NOTE: 

If this interface is supported by the event object, Event.isCustom() must return true.

The setCurrentTarget method is used by the DOM Events implementation to change the value of Event.currentTarget.

Specifies the new value for the Event.currentTarget attribute.

The setEventPhase method is used by the DOM Events implementation to change the value of Event.eventPhase.

Specifies the new value for the Event.eventPhase attribute.

The setCurrentEventListenerGroup method is used by the DOM Events implementation to change the current event group on which the event is being processed.

The specified event group. Use null to specify the default group.

The isImmediatePropagationStopped method is used by the DOM Events implementation to know if the method stopImmediatePropagation() has been called for this event in the current group. It returns true if the method has been called, false otherwise.

true if the event propagation has been stopped immediately in the current group.