1.1 Introduction

DOM Events is designed with two main goals. The first goal is the design of an event system which allows registration of event listeners and describes event flow through a tree structure. Additionally, the specification will provide standard modules of events for user interface control and document mutation notifications, including defined contextual information for each of these event modules.

The second goal of DOM Events is to provide a common subset of the current event systems used in DOM Level 0 browsers. This is intended to foster interoperability of existing scripts and content. It is not expected that this goal will be met with full backwards compatibility. However, the specification attempts to achieve this when possible.

2. Glossary

Some of the following term definitions have been borrowed or modified from similar definitions in other W3C or standards documents. See the links within the definitions for more information.

activation behavior

The action taken when an event, typically initiated by users through an input device, causes an element to fulfill a defined role. The role may be defined for that element by the host language, or by author-defined variables, or both. The role for any given element may be a generic action, or may be unique to that element. For example, the activation behavior of an HTML or SVG <a> element shall be to cause the user agent to traverse the link specified in the href attribute, with the further optional parameter of specifying the browsing context for the traversal (such as the current window or tab, a named window, or a new window); the activation behavior of an HTML <input> element with the type attribute value submit shall be to send the values of the form elements to an author-defined IRI by the author-defined HTTP method.

bubbling phase

The process by which an event can be handled by one of the target ancestors after being handled by the target node.

capture phase

The process by which an event can be handled by one of the target ancestors before being handled by the target node.

dead key

A dead key is a key or combination of key that produces no character by itself, but which in combination or sequence with another key produces a modified character, such as a character with diacritical marks (e.g. ö, é, â).

default action

A default action is a supplementary behavior that an implementation must perform in combination with the dispatch of the event object. Each event, and each specification, defines the default action for that event. A default action may be cancelled through the invocation of the Event.preventDefault() method. For more details, see Default actions and cancelable events.

defaultView

The defaultView is the AbstractView interface of the Document's DocumentView interface, which serves as a reference to the containing frame or window. This interface may also be accessed as the Window interface in many implementations.

deprecated

Features marked as deprecated are included in the specification as reference to older implementations or specifications, but are optional and discouraged. Only features which have existing or in-progress replacements shall be deprecated in this specification. Implementations which do not already include support for the feature should not implement deprecated features, and authors creating content should not use deprecated features, unless there is no other way to solve a use case. Other specifications which reference this specification should not use deprecated features, but should point instead to the replacements of which the feature is deprecated in favor.

dispatch

To create an event with attributes and methods appropriate to its type and context, and propagate it through the DOM tree in the specified manner. Interchangeable with the term "fire", e.g. "fire a 'click' event" or "dispatch a 'load' event".

DOM Level 0

The term "DOM Level 0" refers to a mix (not formally specified) of HTML document functionalities offered by Netscape Navigator version 3.0 and Microsoft Internet Explorer version 3.0. In some cases, attributes or methods have been included for reasons of backward compatibility with "DOM Level 0".

event

An event is the representation of some asynchronous occurrence (such as a mouse click on the presentation of the element, or the removal of child node from an element, or any of unthinkably many other possibilities) that gets associated with an event target.

event phase

See phase.

event target

The object to which an event is targeted.

event type

An event object which defines particular trigger conditions, properties, interfaces, and other characteristics which distinguish it from other event types. For example, the click event type has different characteristics than the mouseover or load event types. The event type is exposed as the type attribute on the event object. See event types for more details. Also loosely referred to as 'event', such as the click event.

host language

Any language which integrates the features of another language, while normatively referencing the origin language rather than redefining those features, and extending those features only in ways defined by the origin language. An origin language typically is only intended to be implemented in the context of one or more host languages, not as a standalone language. For example, XHTML, HTML, and SVG are host languages for DOM 3 Events, and they integrate and extend the objects and models defined in this specification.

IME

input method editor

An input method editor (IME), also known as a front end processor, is an application that performs the conversion between keystrokes and ideographs or other characters, usually by user-guided dictionary lookup, often used in East Asian languages (e.g. Chinese, Japanese, Korean). An IME may also be used for dictionary-based word completion, such as on mobile devices. See Input Method Editors for treatment of IMEs in this specification. See also text composition system.

local name

See local name in [XML Namespaces 1.1].

namespace URI

A namespace URI is a URI that identifies an XML namespace. This is called the namespace name in [XML Namespaces 1.1]. See also sections 1.3.2 "DOM URIs" and 1.3.3 "XML Namespaces" regarding URIs and namespace URIs handling and comparison in the DOM APIs.

phase

In the context of events, a phase is set of logical traversals from node to node along the DOM tree, from the root element down to the event target (capture phase), at the event target itself (target phase), and back up to the root element (bubbling phase).

propagation path

The ordered set of event targets though which an event object will pass sequentially on the way to and back from the ultimate event target. The propagation path is initially comprised of one or more event phases as defined by the event type, but may be interrupted. Also known as an event target chain.

target node

The target node is the node representing the event target to which an event is targeted using the DOM event flow.

text composition system

A software component which interprets some form of alternate input, such as a input method editor, a speech processor, or a handwriting recognition system, and converts it to text.

root element

The first element node of a document, of which all other elements are children; the document element.

target phase

The process by which an event can be handled by the event target.

topmost event target

The topmost event target shall be the element highest in the rendering order which is capable of being an event target. In this case, 'top' shall refer not to the position on the screen, but the logical order of the element in relation to other elements in drawing or stacking order on the z-axis (where the x-axis is the screen width and the y-axis is the screen height). In HTML and CSS, or in SVG, this is controlled by the document order, as modified in HTML and CSS by the 'z-index' property. In some cases, such as when using some values of the SVG 'pointer-events' property, the topmost element may not receive pointer events, in which case, the next element in z-index order which can receive pointer-events is the topmost event target. Note that visibility of the element does not necessarily affect its ability to be the topmost event target, since an element which is hidden by use of the CSS 'visibility' property can still receive pointer events (though not one with a 'display' property of 'none'), and the topmost event target may be completely obscured by another element which cannot receive pointer events. Unless otherwise noted, there is only one topmost event target in any event.

tree

A data structure that represents a document as a hierarchical set of nodes with child-parent-sibling relationships, i.e. each node having one or more possible ancestors (nodes higher in the hierarchy in a direct lineage), one or more possible descendants (nodes lower in the hierarchy in a direct lineage), and one or more possible peers (nodes of the same level in the hierarchy, with the same immediate ancestor).

Unicode character categories

The Unicode character categories, a subset of the complete Unicode general categories, comprise the categories Ll, Lm, Lo, Lt, Lu, Nd, Nl, No, Pc, Pd, Pe, Pf, Pi, Po, Ps, Sc, Sk, Sm, and So.

3.1 Event dispatch and DOM event flow

This section defines the event dispatch mechanism of the event model defined in this specification. Applications may dispatch event objects using the EventTarget.dispatchEvent() method, and implementations must dispatch event objects as if through this method. The behavior of this method depends on the event flow associated with the underlying object. An event flow describes how event objects propagate through a data structure. As an example, when an event object is dispatched to an element in an XML document, the object propagates through parts of the document, as determined by the DOM event flow which is defined at the end of this section.

Figure: graphical representation of an event dispatched in a DOM tree using the DOM event flow

Event objects are always dispatched to a node called the event target. At the beginning of the dispatch, implementations must first determine the event object's propagation path. The propagation path shall be an ordered list of event targets through which the object must pass. The last item in the list shall be the event target; the preceding items in the list are referred to as the target's ancestors, and the immediately preceding item as the target's parent. Once determined, the propagation path must not be changed, even if an element in the propagation path is moved within the DOM or removed from the DOM. As an example, in the DOM event flow event listeners might change the position of the target node in the document while the event object is being dispatched; such changes do not affect the propagation path.

As the next step, the event object must complete one or more event phases. This specification defines three event phases: capture phase; target phase; and bubble phase. Event objects complete these phases in the specified order using the partial propagation paths as defined below. A phase shall be skipped if it is not supported, or if the event object's propagation has been stopped. For example, if the Event.bubbles attribute is set to false, the bubble phase shall be skipped, and if Event.stopPropagation() has been called prior to the dispatch, all phases must be skipped.

1. The capture phase: the event object must propagate through the target's ancestors from the defaultView to the target's parent. This phase is also known as the capturing phase. Event listeners registered for this phase must handle the event before it reaches its target.
2. The target phase: the event object must arrive at the event's target. This phase is also known as the at-target phase. Event listeners registered for this phase must handle the event once it has reached its target. If the event type indicates that the event must not bubble, the event object must halt after completion of this phase.
3. The bubble phase: the event object propagates through the target's ancestors in reverse order, starting with the target's parent and ending with the defaultView. This phase is also known as the bubbling phase. Event listeners registered for this phase shall handle the event after it has reached its target.

Implementations let event objects accomplish an event phase by applying the following steps while there are pending event targets in the partial propagation path for this phase and the event object's propagation has not been stopped through Event.stopPropagation().

First, the implementation must determine the current target. This shall be the next pending event target in the partial propagation path, starting with the first. From the perspective of an event listener this shall be the event target the listener has been registered on.

Next, the implementation must determine the current target's candidate event listeners. This shall be the list of all event listeners that have been registered on the current target in their order of registration. Once determined, the candidate event listeners cannot be changed; adding or removing listeners does not affect the current target's candidate event listeners.

Finally, the implementation must process all candidate event listeners in order and trigger each listener if all the following conditions are met:

• The event object's immediate propagation has not been stopped.
• The listener has been registered for this event phase.
• The listener has been registered for this event type.

An implementation shall trigger a listener by invoking the EventListener.handleEvent() method or an equivalent binding-specific mechanism.

As the final step of the event dispatch, for reasons of backwards compatibility, the implementation must reset the event object's internal-propagation and default-action-prevention states. This ensures that an event object may be properly dispatched multiple times while also allowing to prevent the event objects propagation or default actions prior to the event dispatch.

In the production of the propagation path, if the defaultView implements the EventTarget interface, the event propagates from defaultView to the document object during the capture phase, and from the document object to the defaultView during the bubble phase. Note that for legacy reasons, the load event does not bubble to the defaultView in HTML implementations.

The model defined above must be applied regardless of the specific event flow associated with an event target. Each event flow must define how the propagation path shall be determined and which event phases are supported. The DOM event flow is an application of this model: the propagation path for a Node object shall be determined by its Node.parentNode chain, and if applicable, the document's containing defaultView; all events accomplish the capture and target phases; whether an event accomplishes the bubble phase shall be defined individually for each event type. An alternate application of this model can be found in [DOM Level 3 Load and Save].

Implementations of the DOM event model must be reentrant. Event listeners may perform actions that cause additional events to be dispatched. Such events are handled in a synchronous manner, the event propagation that causes the event listener to be triggered must resume only after the event dispatch of the new event is completed.

3.2 Default actions and cancelable events

Event objects may have default actions associated with them. These are actions the implementation must perform in combination with the dispatch of the event object. An example is the [HTML 4.01] form element. When the user submits the form (e.g. by pressing on a submit button), the event submit shall be dispatched to the element and the default action for this event type shall be generally to send a request to a Web server with the parameters from the form.

Default actions should be performed after the event dispatch has been completed, but in exceptional cases also immediately before the event is dispatched.

Some event objects are cancelable, meaning the default action can be prevented from occuring, or, if the default action is carried out before the dispatch, its effect may be reversed. Whether an event object is cancelable shall be indicated by the Event.cancelable attribute. Event listeners can cancel default actions of cancelable event objects by invoking the Event.preventDefault() method, and determine whether an event has been canceled through the Event.defaultPrevented attribute while the object is being dispatched, or from the return value of the EventTarget.dispatchEvent() method for event objects dispatched by the DOM application itself.

This specification does not offer features to programatically query if an event object has any default action associated with it, or to associate new default actions to an event object. Other specifications may define what default actions, if any, are associated with certain event objects. Further, implementations may associate default actions with events as necessary and appropriate for that implementation. As an example, one implementation may scroll a document view by a certain amount as default action of a mouse wheel event, while another implementation may instead zoom the document as its default action for a mouse wheel event.

3.3 Activation requests and behavior

(This section is currently being rewritten.)

Event targets may have associated activation behavior that implementations perform in response to an activation request. As an example, the typical activation behavior associated with hyperlinks is to follow the link. Activation requests are typically initiated by users through an input device.

In terms of this specification, the activation behavior of the event target shall be the default action of the event type DOMActivate. DOM applications should use this event type whenever they wish to make or react to an activation request.

Implementations must dispatch the DOMActivate event as the default action of a click event. This click event shall be either part of the activation request (e.g., a user requests activiation using a mouse), or synthesized by the implementation to accomodate legacy applications. Context information of such a click event is implementation dependent.

When implementations dispatch a synthesized click event, the expectation shall be that they do so as default action of another event type. For example, when a user activates a hyperlink using a keyboard, the click event would be dispatched as default action of the respective keyboard event.

Implementations are required to dispatch the synthesized click event as described above even if they do not dispatch such an event (e.g., when activation is requested by a voice command, since this specification does not address event types for voice input).

Note: The activation of an event target is device dependent but is also application dependent, e.g. a link in a document can be activated using a mouse click or a mouse double click.

4. Basic Event Interfaces

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

The event types defined in this specification derive from these basic interfaces, and shall inherit all of the attributes, methods, and constants of the interfaces they derive from. Event types defined in other specifications may similarly inherit from these basic interfaces or other interfaces defined in this specification, or may define their own interfaces. The following chart describes the inheritance structure of interfaces defined in this specification.

Figure: graphical representation of the DOM3 Events interface inheritance

4.1 Interface Event

Interface Event (introduced in DOM Level 2)

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 shall be passed as the parameter to an EventListener. The object passed to the event listener may also implement derived interfaces that provide access to information directly relating to the type of event they represent.

To create an instance of the Event interface, use the DocumentEvent.createEvent("Event") method call.

IDL Definition

// Introduced in DOM Level 2:
interface Event {

  // PhaseType
  const unsigned short      CAPTURING_PHASE                = 1;
  const unsigned short      AT_TARGET                      = 2;
  const unsigned short      BUBBLING_PHASE                 = 3;

  readonly attribute DOMString       type;
  readonly attribute EventTarget     target;
  readonly attribute EventTarget     currentTarget;
  readonly attribute unsigned short  eventPhase;
  readonly attribute boolean         bubbles;
  readonly attribute boolean         cancelable;
  readonly attribute DOMTimeStamp    timeStamp;
  void               stopPropagation();
  void               preventDefault();
  void               initEvent(in DOMString eventTypeArg, 
                               in boolean canBubbleArg, 
                               in boolean cancelableArg);
  // Introduced in DOM Level 3:
  readonly attribute DOMString       namespaceURI;
  // Introduced in DOM Level 3:
  void               stopImmediatePropagation();
  // Introduced in DOM Level 3:
  readonly attribute boolean         defaultPrevented;
  // Introduced in DOM Level 3:
  void               initEventNS(in DOMString namespaceURIArg, 
                                 in DOMString eventTypeArg, 
                                 in boolean canBubbleArg, 
                                 in boolean cancelableArg);
};

Definition group PhaseType

An integer indicating which phase of the event flow is being processed as defined in Event dispatch and DOM event flow.

Defined Constants

AT_TARGET

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

BUBBLING_PHASE

The current event phase is the bubbling phase.

CAPTURING_PHASE

The current event phase is the capture phase.

Attributes

bubbles of type boolean, readonly

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

cancelable of type boolean, readonly

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 shall be true, otherwise the value shall be false.

currentTarget of type EventTarget, readonly

Used to indicate the EventTarget whose EventListeners are currently being processed. This is particularly useful during the capture and bubbling phases. When used with the Event dispatch and DOM event flow, this attribute contains the target node or a target ancestor.

defaultPrevented of type boolean, readonly, introduced in DOM Level 3

Used to indicate whether Event.preventDefault() has been called for this event.

eventPhase of type unsigned short, readonly

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

namespaceURI of type DOMString, readonly, introduced in DOM Level 3

The namespace URI associated with this event at initialization time, or null if it is unspecified.
DOM Level 2 Events initialization methods, such as Event.initEvent(), set the value to null.

target of type EventTarget, readonly

Used to indicate the event target. This attribute contains the target node when used with the Event dispatch and DOM event flow.

timeStamp of type DOMTimeStamp, readonly

Used to specify the time at which the event was created in milliseconds relative to 1970-01-01T00:00:00Z. 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, the value shall be 0.

type of type DOMString, readonly

The local name of the event type. The name must be an NCName as defined in [XML Namespaces 1.1] and must be case-sensitive.

Methods

initEvent

Initializes attributes 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. This method has no effect if called after the event has been dispatched. If called from a subclass of the 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.namespaceURI to null. To initialize an event with a namespace URI, use the Event.initEventNS() method.

Parameters

eventTypeArg of type DOMString

Specifies Event.type, the local name of the event type.

canBubbleArg of type boolean

Specifies Event.bubbles. This parameter overrides the intrinsic bubbling behavior of the event.

cancelableArg of type boolean

Specifies Event.cancelable. This parameter overrides the intrinsic cancelable behavior of the event.

No Return Value

No Exceptions

initEventNS introduced in DOM Level 3

Initializes attributes of an Event object. This method has the same behavior as Event.initEvent().

Parameters

namespaceURIArg of type DOMString

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

eventTypeArg of type DOMString

Refer to the Event.initEvent() method for a description of this parameter.

canBubbleArg of type boolean

Refer to the Event.initEvent() method for a description of this parameter.

cancelableArg of type boolean

Refer to the Event.initEvent() method for a description of this parameter.

No Return Value

No Exceptions

preventDefault

Signifies that the event shall be to be canceled, meaning any default action normally taken by the implementation as a result of the event must not occur (see also Default actions and cancelable events). Calling this method for a non-cancelable event has no effect.

Note: This method does not stop the event propagation; use Event.stopPropagation() or Event.stopImmediatePropagation() for that effect.

No Parameters

No Return Value

No Exceptions

stopImmediatePropagation introduced in DOM Level 3

Prevents other event listeners from being triggered and, unlike Event.stopPropagation() its effect shall be immediate . Once it has been called, further calls to this method have no additional effect.

Note: This method does not prevent the default action from being invoked; use Event.preventDefault() for that effect.

No Parameters

No Return Value

No Exceptions

stopPropagation

Prevents other event listeners from being triggered but its effect shall be deferred until all event listeners attached on the Event.currentTarget have been triggered . Once it has been called, further calls to this method have no additional effect.

Note: This method does not prevent the default action from being invoked; use Event.preventDefault() for that effect.

No Parameters

No Return Value

No Exceptions

4.2 Interface CustomEvent

Interface CustomEvent (introduced in DOM Level 3)

The CustomEvent interface is the recommended interface for application-specific event types. Unlike the Event interface, it allows applications to provide contextual information about the event type. Application-specific event types should have an associated namespace to avoid clashes with future general-purpose event types.

To create an instance of the CustomEvent interface, use the DocumentEvent.createEvent("CustomEvent") method call.

IDL Definition

// Introduced in DOM Level 3:
interface CustomEvent : Event {
  readonly attribute DOMObject         detail;
  void               initCustomEvent(in DOMString typeArg, 
                                     in boolean canBubbleArg, 
                                     in boolean cancelableArg, 
                                     in DOMObject detailArg);
  void               initCustomEventNS(in DOMString namespaceURIArg, 
                                       in DOMString typeArg, 
                                       in boolean canBubbleArg, 
                                       in boolean cancelableArg, 
                                       in DOMObject detailArg);
};

Attributes

detail of type DOMObject, readonly

Specifies some detail information about the Event.

Methods

initCustomEvent

Initializes attributes of a CustomEvent object. This method has the same behavior as Event.initEvent().

Parameters

typeArg of type DOMString

Refer to the Event.initEvent() method for a description of this parameter.

canBubbleArg of type boolean

Refer to the Event.initEvent() method for a description of this parameter.

cancelableArg of type boolean

Refer to the Event.initEvent() method for a description of this parameter.

detailArg of type DOMObject

Specifies CustomEvent.detail. This value may be null.

No Return Value

No Exceptions

initCustomEventNS

Initializes attributes of a CustomEvent object. This method has the same behavior as Event.initEventNS().

Parameters

namespaceURIArg of type DOMString

Refer to the Event.initEventNS() method for a description of this parameter.

typeArg of type DOMString

Refer to the Event.initEventNS() method for a description of this parameter.

canBubbleArg of type boolean

Refer to the Event.initEventNS() method for a description of this parameter.

cancelableArg of type boolean

Refer to the Event.initEventNS() method for a description of this parameter.

detailArg of type DOMObject

Specifies CustomEvent.detail. This value may be null.

No Return Value

No Exceptions

4.3 Interface EventTarget

Interface EventTarget (introduced in DOM Level 2)

The EventTarget interface shall be implemented by all the objects which could be event targets in an implementation which supports an event flow. The interface allows registration and removal of event listeners, and dispatch of events to an event target.

When used with the DOM event flow, this interface must be 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.

Invoking addEventListener or addEventListenerNS repeatedly on the same EventTarget with the same values for the parameters namespaceURI, type, listener, and useCapture has no effect. Doing so does not cause the EventListener to be called more than once and does not cause a change in the triggering order.

IDL Definition

// Introduced in DOM Level 2:
interface EventTarget {
  void               addEventListener(in DOMString type, 
                                      in EventListener listener, 
                                      in boolean useCapture);
  void               removeEventListener(in DOMString type, 
                                         in EventListener listener, 
                                         in boolean useCapture);
  // Modified in DOM Level 3:
  boolean            dispatchEvent(in Event evt)
                                        raises(EventException, 
                                               DOMException);
  // Introduced in DOM Level 3:
  void               addEventListenerNS(in DOMString namespaceURI, 
                                        in DOMString type, 
                                        in EventListener listener, 
                                        in boolean useCapture);
  // Introduced in DOM Level 3:
  void               removeEventListenerNS(in DOMString namespaceURI, 
                                           in DOMString type, 
                                           in EventListener listener, 
                                           in boolean useCapture);
};

Methods

addEventListener

Registers an event listener, depending on the useCapture parameter, on the capture phase of the DOM event flow or its target and bubbling phases. Invoking this method shall be equivalent to invoking addEventListenerNS with the same values for the parameters type, listener, and useCapture, and the value null for the parameter namespaceURI. When this method is used to register an event listener, implementations may also dispatch events with the same type in other namespaces, for purposes of extensibility (e.g. this method may be used to dispatch foo event for the null namespace, or for a vendor-specific namespace); see Appendix A: Extending Events for more details.

Parameters

type of type DOMString

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

listener of type EventListener

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.

useCapture of type boolean

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 must only be triggered during the target and bubbling phases.

No Return Value

No Exceptions

addEventListenerNS introduced in DOM Level 3

Registers an event listener, depending on the useCapture parameter, on the capture phase of the DOM event flow or its target and bubbling phases.

Parameters

namespaceURI of type DOMString

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

type of type DOMString

Refer to the EventTarget.addEventListener() method for a description of this parameter.

listener of type EventListener

Refer to the EventTarget.addEventListener() method for a description of this parameter.

useCapture of type boolean

Refer to the EventTarget.addEventListener() method for a description of this parameter.

No Return Value

No Exceptions

dispatchEvent modified in DOM Level 3

Dispatches an event into the implementation's event model. The event target of the event shall be the EventTarget object on which dispatchEvent is called.

Parameters

evt of type Event

The event to be dispatched.

Return Value

boolean

Indicates whether any of the listeners which handled the event called Event.preventDefault(). If Event.preventDefault() was called the returned value shall be false, else it shall be true.

Exceptions

EventException	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 must also trigger this exception. DISPATCH_REQUEST_ERR: Raised if the Event object is already being dispatched.
DOMException	NOT_SUPPORTED_ERR: Raised if the Event object has not been created using DocumentEvent.createEvent(). INVALID_CHARACTER_ERR: Raised if Event.type is not an NCName as defined in [XML Namespaces 1.1].

removeEventListener

Removes an event listener. Calling removeEventListener with arguments which do not identify any currently registered EventListener on the EventTarget has no effect. The Event.namespaceURI for which the user registered the event listener is implied and shall be null.

Parameters

type of type DOMString

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

listener of type EventListener

The EventListener to be removed.

useCapture of type boolean

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.

No Return Value

No Exceptions

removeEventListenerNS introduced in DOM Level 3

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

Parameters

namespaceURI of type DOMString

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

type of type DOMString

Refer to the EventTarget.removeEventListener() method for a description of this parameter.

listener of type EventListener

Refer to the EventTarget.removeEventListener() method for a description of this parameter.

useCapture of type boolean

Refer to the EventTarget.removeEventListener() method for a description of this parameter.

No Return Value

No Exceptions

4.4 Interface EventListener

Interface EventListener (introduced in DOM Level 2)

The EventListener interface is the primary way for handling events. Users shall 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, with methods such as Node.cloneNode or Range.cloneContents, must not copy the event listeners attached to it. Event listeners must be attached to the newly created Node afterwards if so desired.

Moving a Node, with methods Document.adoptNode, Node.appendChild, or Range.extractContents, shall not affect the event listeners attached to it.

IDL Definition

// Introduced in DOM Level 2:
interface EventListener {
  void               handleEvent(in Event evt);
};

Methods

handleEvent

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

Parameters

evt of type Event

The Event contains contextual information about the event.

No Return Value

No Exceptions

Exception EventException introduced in DOM Level 2

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

IDL Definition

// Introduced in DOM Level 2:
exception EventException {
  unsigned short   code;
};
// EventExceptionCode
const unsigned short      UNSPECIFIED_EVENT_TYPE_ERR     = 0;
// Introduced in DOM Level 3:
const unsigned short      DISPATCH_REQUEST_ERR           = 1;

Definition group EventExceptionCode

An integer indicating the type of error generated.

Defined Constants

DISPATCH_REQUEST_ERR, introduced in DOM Level 3.

If the Event object is already dispatched in the tree.

UNSPECIFIED_EVENT_TYPE_ERR

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 must also trigger this exception.

5.1.1 List of DOM3 Event Types

Depending on the level of DOM support, or the devices used for display (e.g. screen) or interaction (e.g., mouse, keyboard, touch screen, or voice), these event types can be generated by the implementation. When used with an [XML 1.0] or [HTML 4.01] application, the specifications of those languages may restrict the semantics and scope (in particular the possible target nodes) associated with an event type. Refer to the specification defining the language used in order to find those restrictions or to find event types that are not defined in this document.

The following table provides a non-normative summary of the event types defined in this specification. All event types are in no namespace and this specification refers to them by their local name only. All events must accomplish the capture and target phases, but not all of them must accomplish the bubbling phase (see also Event dispatch and DOM event flow). Some events are not cancelable (see Default actions and cancelable events). Some events must only be dispatched to a specific set of possible targets in the DOM event flow, specified using node types. Contextual information related to the event type must be accessible using DOM interfaces.

As an example, the event load must trigger event listeners attached on Element nodes for that event and on the capture and target phases. This event cannot be cancelled. If an event listener for the load event is attached to a node other than Document or Element nodes, or if it is attached to the bubbling phase only, this event listener must not be triggered.

The event objects associated with the event types described above may contain context information. Refer to the description of the DOM interfaces for further information.

5.2.1 User Interface Event Types

This module defines the feature UIEvents 3.0 and depends on the features Events 3.0 and Views 2.0.

The User Interface event module contains basic event types associated with user interfaces.

Interface UIEvent (introduced in DOM Level 2)

The UIEvent interface provides specific contextual information associated with User Interface events.

To create an instance of the UIEvent interface, use the DocumentEvent.createEvent("UIEvent") method call.

IDL Definition

    // Introduced in DOM Level 2:
    interface UIEvent : Event {
      readonly attribute views::AbstractView view;
      readonly attribute long            detail;
      void               initUIEvent(in DOMString typeArg, 
                                     in boolean canBubbleArg, 
                                     in boolean cancelableArg, 
                                     in views::AbstractView viewArg, 
                                     in long detailArg);
      // Introduced in DOM Level 3:
      void               initUIEventNS(in DOMString namespaceURIArg, 
                                       in DOMString typeArg, 
                                       in boolean canBubbleArg, 
                                       in boolean cancelableArg, 
                                       in views::AbstractView viewArg, 
                                       in long detailArg);
    };
    

Attributes

detail of type long, readonly

Specifies some detail information about the Event, depending on the type of event.

view of type views::AbstractView, readonly

The view attribute identifies the AbstractView from which the event was generated.

Methods

initUIEvent

Initializes attributes of an UIEvent object. This method has the same behavior as Event.initEvent().

Parameters

typeArg of type DOMString

Refer to the Event.initEvent() method for a description of this parameter.

canBubbleArg of type boolean

Refer to the Event.initEvent() method for a description of this parameter.

cancelableArg of type boolean

Refer to the Event.initEvent() method for a description of this parameter.

viewArg of type views::AbstractView

Specifies UIEvent.view. This value may be null.

detailArg of type long

Specifies UIEvent.detail.

No Return Value

No Exceptions

initUIEventNS introduced in DOM Level 3

Initializes attributes of an UIEvent object. This method has the same behavior as Event.initEventNS().

Parameters

namespaceURIArg of type DOMString

Refer to the Event.initEventNS() method for a description of this parameter.

typeArg of type DOMString

Refer to the Event.initEventNS() method for a description of this parameter.

canBubbleArg of type boolean

Refer to the Event.initEventNS() method for a description of this parameter.

cancelableArg of type boolean

Refer to the Event.initEventNS() method for a description of this parameter.

viewArg of type views::AbstractView

Refer to the UIEvent.initUIEvent() method for a description of this parameter.

detailArg of type long

Refer to the UIEvent.initUIEvent() method for a description of this parameter.

No Return Value

No Exceptions

The User Interface event types are listed below.

5.2.2 Basic Event Types

This event module contains basic event types associated with document manipulation. It defines the feature BasicEvents 3.0 and depends on the feature Events 3.0. The basic event types are listed below.

5.2.6 Text Events Types

This module defines the feature TextEvents 3.0 and depends on the feature UIEvents 3.0.

The text event module originates from the [HTML 4.01] onkeypress attribute. Unlike this attribute, the event type textInput applies only to characters and is designed for use with any text input devices, not just keyboards. Refer to Keyboard events and key identifiers for examples on how text events are used in combination with keyboard events.

Interface TextEvent (introduced in DOM Level 3)

The TextEvent interface provides specific contextual information associated with Text Events.

To create an instance of the TextEvent interface, use the DocumentEvent.createEvent("TextEvent") method call.

IDL Definition

// Introduced in DOM Level 3:
interface TextEvent : UIEvent {

// InputModeCode
const unsigned long       DOM_INPUT_METHOD_UNKNOWN       = 0x00;
const unsigned long       DOM_INPUT_METHOD_KEYBOARD      = 0x01;
const unsigned long       DOM_INPUT_METHOD_PASTE         = 0x02;
const unsigned long       DOM_INPUT_METHOD_DROP          = 0x03;
const unsigned long       DOM_INPUT_METHOD_IME           = 0x04;
const unsigned long       DOM_INPUT_METHOD_OPTION        = 0x05;
const unsigned long       DOM_INPUT_METHOD_HANDWRITING   = 0x06;
const unsigned long       DOM_INPUT_METHOD_VOICE         = 0x07;
const unsigned long       DOM_INPUT_METHOD_MULTIMODAL    = 0x08;
const unsigned long       DOM_INPUT_METHOD_SCRIPT        = 0x09;

readonly attribute DOMString       data;
readonly attribute unsigned long   inputMode;
void               initTextEvent(in DOMString typeArg, 
                                 in boolean canBubbleArg, 
                                 in boolean cancelableArg, 
                                 in views::AbstractView viewArg, 
                                 in DOMString dataArg, 
                                 in unsigned long inputMode);
void               initTextEventNS(in DOMString namespaceURIArg, 
                                   in DOMString typeArg, 
                                   in boolean canBubbleArg, 
                                   in boolean cancelableArg, 
                                   in views::AbstractView viewArg, 
                                   in DOMString dataArg, 
                                   in unsigned long inputMode);
};

Definition group InputModeCode

This set of constants shall be used to indicate the origin of the text input. In case a DOM implementation wishes to provide a new location information, a value different from the following constant values must be used.

Defined Constants

DOM_INPUT_METHOD_UNKNOWN

The text string was input by an unknown means.

DOM_INPUT_METHOD_KEYBOARD

The text string was input through a keyboard. This may be associated with one or more of keypress, keydown, or keyup events.

DOM_INPUT_METHOD_PASTE

The text string was pasted in from a clipboard. This may be associated with a paste event, specified elsewhere.

DOM_INPUT_METHOD_DROP

The text string was inserted as part of a drag-and-drop operation. This may be associated with a drop event, specified elsewhere.

DOM_INPUT_METHOD_IME

The text string was entered through an Input Method Editor. This may be associated with a compositionend event.

DOM_INPUT_METHOD_OPTION

The text string was selected from a set of options presented, such as from a form. This may be associated with various other events, specified elsewhere.

DOM_INPUT_METHOD_HANDWRITING

The text string was input through a pen/tablet device and processed by handwriting recognition software. This may be associated with a specific event defined elsewhere.

DOM_INPUT_METHOD_VOICE

The text string was input by a voice device and interpreted by speech recognition software. This may be associated with a specific event defined elsewhere.

DOM_INPUT_METHOD_MULTIMODAL

The text string was inserted as part of an operation involving multiple input modalities in combination, such as pointer-enhanced speech. This may be associated with various other events, specified elsewhere.

DOM_INPUT_METHOD_SCRIPT

The text string was inserted via a script operation on the DOM. This may be associated with one or more mutation events.

Attributes

data of type DOMString, readonly

data holds the value of the characters generated by the character device. This may be a single Unicode character or a non-empty sequence of Unicode characters [Unicode]. Characters should be normalized as defined by the Unicode normalization form NFC, defined in [UAX #15]. This attribute cannot be null or contain the empty string.

inputMode of type unsigned long, readonly

The inputMode attribute contains an indication of the origin of the text input, as described in InputModeCode.

Methods

initTextEvent

Initializes attributes of a TextEvent object. This method has the same behavior as UIEvent.initUIEvent(). The value of UIEvent.detail remains undefined.

Parameters

typeArg of type DOMString

Refer to the UIEvent.initUIEvent() method for a description of this parameter.

canBubbleArg of type boolean

Refer to the UIEvent.initUIEvent() method for a description of this parameter.

cancelableArg of type boolean

Refer to the UIEvent.initUIEvent() method for a description of this parameter.

viewArg of type views::AbstractView

Refer to the UIEvent.initUIEvent() method for a description of this parameter.

dataArg of type DOMString

Specifies TextEvent.data.

inputModeArg of type unsigned long

Specifies TextEvent.inputMode.

No Return Value

No Exceptions

initTextEventNS

Initializes attributes of a TextEvent object. This method has the same behavior as UIEvent.initUIEventNS(). The value of UIEvent.detail remains undefined.

Parameters

namespaceURIArg of type DOMString

Refer to the UIEvent.initUIEventNS() method for a description of this parameter.

typeArg of type DOMString

Refer to the UIEvent.initUIEventNS() method for a description of this parameter.

canBubbleArg of type boolean

Refer to the UIEvent.initUIEventNS() method for a description of this parameter.

cancelableArg of type boolean

Refer to the UIEvent.initUIEventNS() method for a description of this parameter.

viewArg of type views::AbstractView

Refer to the UIEvent.initUIEventNS() method for a description of this parameter.

dataArg of type DOMString

Refer to the TextEvent.initTextEvent() method for a description of this parameter.

inputModeArg of type unsigned long

Specifies TextEvent.inputMode.

No Return Value

No Exceptions

The text event type is listed below.

5.2.7 Keyboard Event Types

This module defines the feature KeyboardEvents 3.0 and depends on the feature UIEvents 3.0.

Keyboard events are device dependent, i.e. they rely on the capabilities of the input devices and how they are mapped in the operating systems. It is therefore highly recommended to rely on Text events types when dealing with character input. Refer to Keyboard events and key identifiers for more details, including examples on how Keyboard Events are used in combination with Composition Events.

Interface KeyboardEvent (introduced in DOM Level 3)

The KeyboardEvent interface provides specific contextual information associated with keyboard devices. Each keyboard event references a key using an identifier. Keyboard events are commonly directed at the element that has the focus.

The KeyboardEvent interface provides convenient attributes for some common modifiers keys: KeyboardEvent.ctrlKey, KeyboardEvent.shiftKey, KeyboardEvent.altKey, KeyboardEvent.metaKey. These attributes are equivalent to using the method KeyboardEvent.getModifierState(keyIdentifierArg) with 'Control', 'Shift', 'Alt', or 'Meta' respectively.

To create an instance of the KeyboardEvent interface, use the DocumentEvent.createEvent("KeyboardEvent") method call.

IDL Definition

  // Introduced in DOM Level 3:
  interface KeyboardEvent : UIEvent {

  // KeyLocationCode
  const unsigned long       DOM_KEY_LOCATION_STANDARD      = 0x00;
  const unsigned long       DOM_KEY_LOCATION_LEFT          = 0x01;
  const unsigned long       DOM_KEY_LOCATION_RIGHT         = 0x02;
  const unsigned long       DOM_KEY_LOCATION_NUMPAD        = 0x03;
  const unsigned long       DOM_KEY_LOCATION_MOBILE        = 0x04;
  const unsigned long       DOM_KEY_LOCATION_JOYSTICK      = 0x05;

  readonly attribute DOMString       keyIdentifier;                
  readonly attribute unsigned long   keyLocation;
  readonly attribute boolean         ctrlKey;
  readonly attribute boolean         shiftKey;
  readonly attribute boolean         altKey;
  readonly attribute boolean         metaKey;
  readonly attribute boolean         repeat;
  boolean            getModifierState(in DOMString keyIdentifierArg);
  void               initKeyboardEvent(in DOMString typeArg, 
                                     in boolean canBubbleArg, 
                                     in boolean cancelableArg, 
                                     in views::AbstractView viewArg, 
                                     in DOMString keyIdentifierArg, 
                                     in unsigned long keyLocationArg, 
                                     in DOMString modifiersListArg,
                                     in boolean repeat);
  void               initKeyboardEventNS(in DOMString namespaceURIArg, 
                                       in DOMString typeArg, 
                                       in boolean canBubbleArg, 
                                       in boolean cancelableArg, 
                                       in views::AbstractView viewArg, 
                                       in DOMString keyIdentifierArg, 
                                       in unsigned long keyLocationArg, 
                                       in DOMString modifiersListArg,
                                       in boolean repeat);
  };
  

Definition group KeyLocationCode

This set of constants shall be used to indicate the location of a key on the device. In case a DOM implementation wishes to provide a new location information, a value different from the following constant values must be used.

Defined Constants

DOM_KEY_LOCATION_LEFT

The key activated shall be in the left key location (there is more than one possible location for this key). Example: the left 'Control' key on a PC 101 Key US keyboard.

DOM_KEY_LOCATION_NUMPAD

The key activation originated on the numeric keypad or with a virtual key corresponding to the numeric keypad. Example: the '1' key on a PC 101 Key US keyboard located on the numeric pad.

DOM_KEY_LOCATION_RIGHT

The key activation shall be in the right key location (there is more than one possible location for this key). Example: the right 'Shift' key on a PC 101 Key US keyboard.

DOM_KEY_LOCATION_STANDARD

The key activation shall not be distinguished as the left or right version of the key, and did not originate from the numeric keypad (or did not originate with a virtual key corresponding to the numeric keypad). Example: the 'Q' key on a PC 101 Key US keyboard.

DOM_KEY_LOCATION_MOBILE

The key activation originated on a mobile device, either on a physical keypad or a virtual keyboard. Example: the '#' key or softkey on a mobile device.

DOM_KEY_LOCATION_JOYSTICK

The key activation originated on a game controller or a joystick on a mobile device. Example: the 'DownLeft' key on a game controller.

Attributes

altKey of type boolean, readonly

true if the alternative (Alt) key modifier is activated.

Note: The Option key modifier on Macintosh systems must be represented using this key modifier.

ctrlKey of type boolean, readonly

true if the control (Ctrl) key modifier is activated.

keyIdentifier of type DOMString, readonly

keyIdentifier holds the identifier of the key. The key identifiers are defined in Key identifiers set. Implementations that are unable to identify a key must use the key identifier 'Unidentified'.

keyLocation of type unsigned long, readonly

The keyLocation attribute contains an indication of the location of the key on the device, as described in Keyboard event types.

metaKey of type boolean, readonly

true if the meta (Meta) key modifier is activated.

Note: The Command key modifier on Macintosh systems must be represented using this key modifier.

shiftKey of type boolean, readonly

true if the shift (Shift) key modifier is activated.

repeat of type boolean, readonly

true if the key has been pressed in a sustained manner. Depending on the system configuration, holding down a key results may result in multiple consecutive keydown events, keypress events, and textInput events, for appropriate keys. For mobile devices which have long-key-press behavior, the first key event with a repeat attribute value of 'true' shall serve as an indication of a long-key-press. The length of time that the key must be pressed in order to begin repeating is configuration-dependent.

Methods

getModifierState

Queries the state of a modifier using a key identifier. See also Modifier keys.

Parameters

keyIdentifierArg of type DOMString

A modifier key identifier. Common modifier keys are 'Alt', 'AltGraph', 'CapsLock', 'Control', 'Meta', 'NumLock', 'Scroll', or 'Shift'.

Note: If an application wishes to distinguish between right and left modifiers, this information could be deduced using keyboard events and KeyboardEvent.keyLocation.

Return Value

boolean

true if it is a modifier key and the modifier is activated, false otherwise.

No Exceptions

initKeyboardEvent

Initializes attributes of a KeyboardEvent object. This method has the same behavior as UIEvent.initUIEvent(). The value of UIEvent.detail remains undefined.

Parameters

typeArg of type DOMString

Refer to the UIEvent.initUIEvent() method for a description of this parameter.

canBubbleArg of type boolean

Refer to the UIEvent.initUIEvent() method for a description of this parameter.

cancelableArg of type boolean

Refer to the UIEvent.initUIEvent() method for a description of this parameter.

viewArg of type views::AbstractView

Refer to the UIEvent.initUIEvent() method for a description of this parameter.

keyIdentifierArg of type DOMString

Specifies KeyboardEvent.keyIdentifier.

keyLocationArg of type unsigned long

Specifies KeyboardEvent.keyLocation.

modifiersListArg of type DOMString

A white space separated list of modifier key identifiers to be activated on this object. As an example, "Control Alt" must mark the control and alt modifiers as activated.

No Return Value

No Exceptions

initKeyboardEventNS

Initializes attributes of a KeyboardEvent object. This method has the same behavior as UIEvent.initUIEventNS(). The value of UIEvent.detail remains undefined.

Parameters

namespaceURIArg of type DOMString

Refer to the UIEvent.initUIEventNS() method for a description of this parameter.

typeArg of type DOMString

Refer to the UIEvent.initUIEventNS() method for a description of this parameter.

canBubbleArg of type boolean

Refer to the UIEvent.initUIEventNS() method for a description of this parameter.

cancelableArg of type boolean

Refer to the UIEvent.initUIEventNS() method for a description of this parameter.

viewArg of type views::AbstractView

Refer to the UIEvent.initUIEventNS() method for a description of this parameter.

keyIdentifierArg of type DOMString

Refer to the KeyboardEvent.initKeyboardEvent() method for a description of this parameter.

keyLocationArg of type unsigned long

Refer to the KeyboardEvent.initKeyboardEvent() method for a description of this parameter.

modifiersListArg of type DOMString

Refer to the KeyboardEvent.initKeyboardEvent() method for a description of this parameter.

No Return Value

No Exceptions

Depending on the character generation device, keyboard events may or may not be generated.

The keyboard event types are listed below.

5.2.8 Composition Events Types

This module defines the feature CompositionEvents 3.0 and depends on the feature UIEvents 3.0.

Composition Events provide a means for inputing text in a supplementary or alternate manner than by Keyboard Events, in order to allow the use of characters that may not be commonly available on keyboard. For examples, Composition events may be used to add accents to characters despite their absence from standard US keyboards, to build up logograms of many Asian languages from their base components or categories, to select word choices from a combination of key presses on a mobile device keyboard, or to convert voice commands into text using a speech recognition processor. Refer to Keyboard events and key identifiers for examples on how Composition Events are used in combination with keyboard events.

Conceptually, a composition session consists of one compositionstart event, one or more compositionupdate events, and one compositionend event, with the value of the data attribute persisting between each "stage" of this event chain during each session.

Not all IME systems or devices expose the necessary data to the DOM, so the active composition string (the "Reading Window" or "candidate selection menu option") may not be available through this interface, in which case the selection may be represented by the empty string.

Interface CompositionEvent (introduced in DOM Level 3)

The CompositionEvent interface provides specific contextual information associated with Composition Events.

To create an instance of the CompositionEvent interface, use the DocumentEvent.createEvent("CompositionEvent") method call.

IDL Definition

      // Introduced in DOM Level 3:
      interface CompositionEvent : UIEvent {

      readonly attribute DOMString       data;
      void               initCompositionEvent(in DOMString typeArg, 
                                 in boolean canBubbleArg, 
                                 in boolean cancelableArg, 
                                 in views::AbstractView viewArg, 
                                 in DOMString dataArg);
      void               initCompositionEventNS(in DOMString namespaceURIArg, 
                                   in DOMString typeArg, 
                                   in boolean canBubbleArg, 
                                   in boolean cancelableArg, 
                                   in views::AbstractView viewArg, 
                                   in DOMString dataArg);
      };
      

Attributes

data of type DOMString, readonly

data holds the value of the characters generated by an input method. This may be a single Unicode character or a non-empty sequence of Unicode characters [Unicode]. Characters should be normalized as defined by the Unicode normalization form NFC, defined in [UAX #15]. This attribute may be null or contain the empty string.

Methods

initCompositionEvent

Initializes attributes of a CompositionEvent object. This method has the same behavior as UIEvent.initUIEvent(). The value of UIEvent.detail remains undefined.

Parameters

typeArg of type DOMString

Refer to the UIEvent.initUIEvent() method for a description of this parameter.

canBubbleArg of type boolean

Refer to the UIEvent.initUIEvent() method for a description of this parameter.

cancelableArg of type boolean

Refer to the UIEvent.initUIEvent() method for a description of this parameter.

viewArg of type views::AbstractView

Refer to the UIEvent.initUIEvent() method for a description of this parameter.

dataArg of type DOMString

Specifies CompositionEvent.data.

No Return Value

No Exceptions

initCompositionEventNS

Initializes attributes of a CompositionEvent object. This method has the same behavior as UIEvent.initUIEventNS(). The value of UIEvent.detail remains undefined.

Parameters

namespaceURIArg of type DOMString

Refer to the UIEvent.initUIEventNS() method for a description of this parameter.

typeArg of type DOMString

Refer to the UIEvent.initUIEventNS() method for a description of this parameter.

canBubbleArg of type boolean

Refer to the UIEvent.initUIEventNS() method for a description of this parameter.

cancelableArg of type boolean

Refer to the UIEvent.initUIEventNS() method for a description of this parameter.

viewArg of type views::AbstractView

Refer to the UIEvent.initUIEventNS() method for a description of this parameter.

dataArg of type DOMString

Refer to the CompositionEvent.initCompositionEvent() method for a description of this parameter.

No Return Value

No Exceptions

The composition event types are listed below.

5.2.9 Mutation Events

This module defines the feature MutationEvents 3.0 and depends on the feature Events 3.0.

Note: The MutationEvent interface was introduced in DOM Level 2 Events, but has not yet been completely and interoperably implemented across user agents. In addition, there have been critiques that the interface, as designed, introduces a performance and implementation challenge. A new specification is under development with the aim of addressing the use cases that mutation events solves, but in more performant manner. Thus, this specification describes mutation events for completeness, but deprecates the use of both the MutationEvent interface and the MutationNameEvent interface.

The mutation and mutation name event modules are designed to allow notification of any changes to the structure of a document, including attribute, text, or name modifications. It may be noted that none of the event types associated with the modules are designated as cancelable. This stems from the fact that it is very difficult to make use of existing DOM interfaces which cause document modifications if any change to the document might or might not take place due to cancelation of the resulting event. Although this is still a desired capability, it was decided that it would be better left until the addition of transactions into the DOM.

Many single modifications of the tree can cause multiple mutation events to be dispatched. Rather than attempt to specify the ordering of mutation events due to every possible modification of the tree, the ordering of these events is left to the implementation.

Interface MutationEvent (introduced in DOM Level 2)

The MutationEvent interface provides specific contextual information associated with Mutation events.

To create an instance of the MutationEvent interface, use the DocumentEvent.createEvent("MutationEvent") method call.

IDL Definition

    // Introduced in DOM Level 2:
    interface MutationEvent : Event {

      // attrChangeType
      const unsigned short      MODIFICATION                   = 1;
      const unsigned short      ADDITION                       = 2;
      const unsigned short      REMOVAL                        = 3;

      readonly attribute Node            relatedNode;
      readonly attribute DOMString       prevValue;
      readonly attribute DOMString       newValue;
      readonly attribute DOMString       attrName;
      readonly attribute unsigned short  attrChange;
      void               initMutationEvent(in DOMString typeArg, 
                                           in boolean canBubbleArg, 
                                           in boolean cancelableArg, 
                                           in Node relatedNodeArg, 
                                           in DOMString prevValueArg, 
                                           in DOMString newValueArg, 
                                           in DOMString attrNameArg, 
                                           in unsigned short attrChangeArg);
      // Introduced in DOM Level 3:
      void               initMutationEventNS(in DOMString namespaceURIArg, 
                                             in DOMString typeArg, 
                                             in boolean canBubbleArg, 
                                             in boolean cancelableArg, 
                                             in Node relatedNodeArg, 
                                             in DOMString prevValueArg, 
                                             in DOMString newValueArg, 
                                             in DOMString attrNameArg, 
                                             in unsigned short attrChangeArg);
    };
    

Definition group attrChangeType

An integer indicating in which way the Attr was changed.

Defined Constants

ADDITION

The Attr was just added.

MODIFICATION

The Attr was modified in place.

REMOVAL

The Attr was just removed.

Attributes

attrChange of type unsigned short, readonly

attrChange indicates the type of change which triggered the DOMAttrModified event. The values can be MODIFICATION, ADDITION, or REMOVAL.

attrName of type DOMString, readonly

attrName indicates the name of the changed Attr node in a DOMAttrModified event.

newValue of type DOMString, readonly

newValue indicates the new value of the Attr node in DOMAttrModified events, and of the CharacterData node in DOMCharacterDataModified events.

prevValue of type DOMString, readonly

prevValue indicates the previous value of the Attr node in DOMAttrModified events, and of the CharacterData node in DOMCharacterDataModified events.

relatedNode of type Node, readonly

relatedNode shall be used to identify a secondary node related to a mutation event. For example, if a mutation event is dispatched to a node indicating that its parent has changed, the relatedNode shall be the changed parent. If an event is instead dispatched to a subtree indicating a node was changed within it, the relatedNode shall be the changed node. In the case of the DOMAttrModified event it indicates the Attr node which was modified, added, or removed.

Methods

initMutationEvent

Initializes attributes of a MutationEvent object. This method has the same behavior as Event.initEvent().

Parameters

typeArg of type DOMString

Refer to the Event.initEvent() method for a description of this parameter.

canBubbleArg of type boolean

Refer to the Event.initEvent() method for a description of this parameter.

cancelableArg of type boolean

Refer to the Event.initEvent() method for a description of this parameter.

relatedNodeArg of type Node

Specifies MutationEvent.relatedNode.

prevValueArg of type DOMString

Specifies MutationEvent.prevValue. This value may be null.

newValueArg of type DOMString

Specifies MutationEvent.newValue. This value may be null.

attrNameArg of type DOMString

Specifies MutationEvent.attrName. This value may be null.

attrChangeArg of type unsigned short

Specifies MutationEvent.attrChange. This value may be null.

No Return Value

No Exceptions

initMutationEventNS introduced in DOM Level 3

Initializes attributes of a MutationEvent object. This method has the same behavior as Event.initEventNS().

Parameters

namespaceURIArg of type DOMString

Refer to the Event.initEventNS() method for a description of this parameter.

typeArg of type DOMString

Refer to the Event.initEventNS() method for a description of this parameter.

canBubbleArg of type boolean

Refer to the Event.initEventNS() method for a description of this parameter.

cancelableArg of type boolean

Refer to the Event.initEventNS() method for a description of this parameter.

relatedNodeArg of type Node

Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.

prevValueArg of type DOMString

Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.

newValueArg of type DOMString

Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.

attrNameArg of type DOMString

Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.

attrChangeArg of type unsigned short

Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.

No Return Value

No Exceptions

The mutation event types are listed below.

5.2.10 Mutation Name Event Types

This module defines the feature MutationNameEvents 3.0 and depends on the features MutationEvents 3.0 and Core 3.0.

Note: The MutationNameEvents interface, introduced in an earlier draft of this specification, derives from the MutationEvent interface, which is deprecated in this specification. Thus, this specification describes the mutation name event types for completeness, but deprecates their use.

Interface MutationNameEvent (introduced in DOM Level 3)

The MutationNameEvent interface provides specific contextual information associated with Mutation name event types.

To create an instance of the MutationNameEvent interface, use the Document.createEvent("MutationNameEvent") method call.

IDL Definition

    // Introduced in DOM Level 3:
    interface MutationNameEvent : MutationEvent {
      readonly attribute DOMString       prevNamespaceURI;
      readonly attribute DOMString       prevNodeName;
      // Introduced in DOM Level 3:
      void               initMutationNameEvent(in DOMString typeArg, 
                                               in boolean canBubbleArg, 
                                               in boolean cancelableArg, 
                                               in Node relatedNodeArg, 
                                               in DOMString prevNamespaceURIArg, 
                                               in DOMString prevNodeNameArg);
      // Introduced in DOM Level 3:
      void               initMutationNameEventNS(in DOMString namespaceURIArg, 
                                                 in DOMString typeArg, 
                                                 in boolean canBubbleArg, 
                                                 in boolean cancelableArg, 
                                                 in Node relatedNodeArg, 
                                                 in DOMString prevNamespaceURIArg, 
                                                 in DOMString prevNodeNameArg);
    };
    

Attributes

prevNamespaceURI of type DOMString, readonly

The previous value of the relatedNode's namespaceURI.

prevNodeName of type DOMString, readonly

The previous value of the relatedNode's nodeName.

Methods

initMutationNameEvent introduced in DOM Level 3

Initializes attributes of a MutationNameEvent object. This method has the same behavior as MutationEvent.initMutationEvent().

Parameters

typeArg of type DOMString

Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.

canBubbleArg of type boolean

Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.

cancelableArg of type boolean

Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.

relatedNodeArg of type Node

Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.

prevNamespaceURIArg of type DOMString

Specifies MutationNameEvent.prevNamespaceURI. This value may be null.

prevNodeNameArg of type DOMString

Specifies MutationNameEvent.prevNodeName.

No Return Value

No Exceptions

initMutationNameEventNS introduced in DOM Level 3

Initializes attributes of a MutationNameEvent object. This method has the same behavior as MutationEvent.initMutationEventNS().

Parameters

namespaceURIArg of type DOMString

Refer to the MutationEvent.initMutationEventNS() method for a description of this parameter.

typeArg of type DOMString

Refer to the MutationEvent.initMutationEventNS() method for a description of this parameter.

canBubbleArg of type boolean

Refer to the MutationEvent.initMutationEventNS() method for a description of this parameter.

cancelableArg of type boolean

Refer to the MutationEvent.initMutationEventNS() method for a description of this parameter.

relatedNodeArg of type Node

Refer to the MutationEvent.initMutationEventNS() method for a description of this parameter.

prevNamespaceURIArg of type DOMString

Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.

prevNodeNameArg of type DOMString

Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.

No Return Value

No Exceptions

The mutation name event types are listed below.

6.1 Keyboard Input

The relationship of each key to the complete keyboard has three separate aspects, each of which vary among different models and configurations of keyboards, particularly for locale-specific reasons:

• Mechanical layout: the dimensions, size, and placement of the physical keys on the keyboard
• Visual markings: the labels (or legends) that mark each key
• Functional mapping: the abstract key-identifier association of each key.

This specification only defines the functional mapping, in terms of key identifiers. The visual marking has no bearing on the digital representation of the keys, and in many configurations may be completely inaccurate.

6.1.1 Keyboard Layout

As with the key labels, the physical layout of the keys on the keyboard does not not affect the digital identifier for any given key. It is outside the scope of this specification to provide key identifiers based on keyboard layout, particularly since there are so many possible layouts for a keyboard, and since users can change the mapping of keys in their operating system, e.g. selecting a Dvorak key mapping.

However, the physical layout of the keys may be of interest to authors developing games or other applications wherein the location of the keys has an ergonomic relationship as the desired user interface controls, with little or no attention paid to the representational value of the key itself. For example, many games may use the keys 'A', 'S', 'D', and 'W' for 'left', 'down', 'right', and 'up' respectively. Authors should provide a means for the user to assign the controller keys to a custom setting appropriate to their keyboard configurations.

6.1.1.1 Desktop and Laptop Keyboards

In the case where an author wishes to rely on the mechanical layout of a desktop or laptop keyboard, this specification suggests the keyboard configuration specified in ISO/IEC 9995-3-FCD:2009A [ISO-9995-3] as a common layout appropriate to some international uses.

Note: This keyboard layout is still, in essence, a QWERTY keyboard, and will not match the keyboards or configurations of many users. Authors cannot rely upon any particular configuration, and should create content in an internationalized and localizable manner.

Figure: A graphical depiction of an ISO standard defining layouts of computer keyboards, ISO/IEC 9995-3:2009A

6.1.1.2 Mobile Keypads

In the case where an author wishes to rely on the mechanical layout of a mobile keypad, this specification suggests the keyboard configuration specified in ISO/IEC 9995-8:2006 [ISO-9995-8] as a common layout appropriate to some international uses.

Note: This keypad layout, and in particular the distribution of letters is for Western devices, and will not match the keypads or configurations of many users. Authors cannot rely upon any particular configuration, and should create content in an internationalized and localizable manner.

Figure: A graphical depiction of an ISO standard defining layouts of numeric keypads, with distribution of letters on the keys, ISO/IEC 9995-8:2006

6.2 Compositional Keyboard Input

Each keyboard event references a key using a DOMString key identifier. The set contained in this appendix is based on the sets of keycodes from:

• the interface java.awt.event.KeyEvent of the Java 2 Platform v1.4 [KeyEvent for Java];
• the enumeration System.Windows.Forms.Keys of the Microsoft .NET Framework 1.0 [Keys enumeration for .Net].

Key identifiers are strings used for uniquely addressing keyboard buttons, and intended for use in two primary scenarios: as attributes for a keyboard event; or as string values for markup attributes, such as so-called "hotkeys" (or keyboard shortcuts). As attributes on an event, the key identifier shall be a single canonical value. As author-generated content, the key identifier may be one of three equivalent string values, which all evaluate to the same key identifier; the string may be a character string (a single character, such as a letter or symbol), a key name (a multi-character string, such as enter or tab, for control or dead keys, or certain symbols), or a Unicode codepoint ("U+" followed by a hexadecimal character index). The event attribute must always be the most author-friendly of these, in the following order: character string, key name, or Unicode codepoint.

There are several use cases for keyboard events. The first use case is to retrieve the value of the key itself, in whichever mode that key currently represents (i.e. the value of a key as an upper- or lower-case letter, or a symbol or number, depending upon the current modifier keys, or as a key name); this may be used for monitoring particular input strings, or for modifier key input, or for author-generated virtual keyboards, and does not not depend upon the location of the key in the physical layout of the device, which may be mapped to different configurations based on user or system preference. The second use case is for keyboard shortcuts, where the string itself may be of secondary importance, and where they key used should default to the most appropriate key for the function, language, operating system, device, and other environmental factors (such as ctrl+c for copy operations). The final use case is completely independent of the value of the key identifier, and relies solely on the physical layout of the input device itself (such as for game controls); this is highly variable device-dependent functionality, and is not within the scope of this specification. Implementations should provide an option for users to establish their own preferential mapping for keyboard layout, and may rely upon ISO 9995-3, which defines a common layout for primary and secondary key mappings on a typical alphanumeric keyboard, or on ISO 9995-8, which defines a numeric keypad layout and secondary assignment of Unicode characters in the range U+0061..U+007A to the number keys 2 through 9.

While implementations are recommended to use the most relevant identifier for a key independently of the platform or keyboard layout mappings, DOM applications should not make assumption on the ability of keyboard devices to generate them. When using keyboard events, "consider using numbers and function keys (F4, F5, and so on) instead of letters in shortcut-key combinations" ([DWW95]) given that most keyboard layouts will provide keys for those.

'U+0000', 'U+0001', ..., 'U+10FFFF' are Unicode based key identifiers ([Unicode]). When a key cannot be mapped to Unicode, a specific identifier shall be used (see also Guidelines for defining key identifiers). In any case, no assumption should be made between the sequence of keyboard events and the text events. The following three examples illustrate the concept of keyboard layout mappings and its relation with keyboard events (following the Guidelines for defining key identifiers, the 'Q' key shall be mapped to the Latin Capital Letter Q key).

The keystroke 'U+0051' (Latin Capital Letter Q key) must produce (on a PC/AT US keyboard using a US keyboard layout mapping and without any modifier activated) the Unicode character q (Latin Small Letter Q):

1. "keydown": 'U+0051' (Latin Capital Letter Q key)
2. "textInput": 'q'
3. "keyup": 'U+0051'

If the keyboard layout mapping is switched to a french mapping, pressing the same key must produce:

1. "keydown": 'U+0041' (Latin Capital Letter A key)
2. "textInput": 'a'
3. "keyup": 'U+0041'

If the keyboard layout mapping is switched to a serbian (cyrillic) mapping, pressing the same key must produce:

1. "keydown": 'U+0409' (Cyrillic Capital Letter LJE)
2. "textInput": 'љ'
3. "keyup": 'U+0409'

Note: The order between the text event and keyboard events may differ depending on the keyboard devices.

6.3.1 Guidelines for defining key identifiers

Note: This section is normative.

The list of key identifiers contained in this appendix is not exhaustive and input devices may have to define their own key identifiers. Here is a algorithm to determine which key identifier to use:

1. Consider the primary function of the key (i.e., without modifiers), taking into consideration the keyboard layout mapping in use, to determine if a corresponding Unicode character exists from which a key identifier may be derived. If multiple Unicode characters exist which correspond to the primary function of the key, the Unicode character with the lowest codepoint must be used.
   1. If the primary function of the key is to generate a character, and that character is in one of the Unicode character categories, then the key identifier shall be a string consisting of just that character. If the primary function of the key is to generate a character in class Ll for which there exists an equivalent, single character in class Lu, the uppercase character should be used instead.
      Is this necessary? Why can't we simply allow lowercase letters as well? If a script author wishes to do a comparison, they can cast the output to upper or lower case as needed. See ISSUE-23.
   2. If the primary function of the key is to generate a character that is not in one of the above general categories, or if the primary function of the key is a function for which there exists a corresponding Unicode character that is not in one of the above general categories, then:
      1. If there exists an appropriate key identifier in the key identifiers set, and that key identifier does not have a Unicode codepoint, that key identifier must be used.
      2. If there exists an appropriate key identifier in the key identifiers set, and that key identifier has a Unicode codepoint, and that key identifier is in one of the Unicode character categories, then the character value itself for that key identifier must be used.
      3. If there is no appropriate key identifier in the key identifiers set, then the key identifier is a string beginning with "U+" and followed by the Unicode codepoint of the character in hexadecimal, using at least four digits. Leading zeroes must be omitted unless they are required to make the codepoint use at least four digits.
2. For keys with no corresponding Unicode character, a key identifier can be devised. The key identifier should be as human friendly as possible and must not contain whitespace. The identifier must be composed only of characters in the ranges U+0030..U+0039, U+0041..U+005A, or U+0061..U+007A, and must begin with a character in the range U+0041..U+005A.
   Why should we not allow names in other ranges (Chinese, for example)?

Examples:

• On a PC/AT US keyboard with a US keyboard mapping, the primary function (unmodified) of the 'Q' key is to generate the character U+0071. Since this character is in general category Ll, and there is a single corresponding character in Lu, U+0051, this character is used instead. Thus, the key identifier is "Q".
  What is the use case here? Why are uppercase letters being given priority? See ISSUE-23.
• On a PC/AT US keyboard with a two-handed Dvorak keyboard mapping, the 'Q' key maps to the '5/%' key. The primary function of this key is to generate the character U+0035. Since this character is in general category Nd, the key identifier shall be "5".
• On a French PC keyboard with a standard French mapping, the primary function of the '^' key is as a dead key for the circumflex diacritical mark. This corresponds to the combining Unicode character U+0302. Since this character is in general category Mn, the key identifier shall be "U+0302".
• On a Korean PC keyboard with a standard Korean mapping, the primary function of the 'Ha/En' key is to switch between Hangul and English input. The predefined key identifier list has an appropriate entry for this key, "HangulMode", so this shall be the key identifier.
• On some models of PDAs, the primary function of the key with a picture of a calendar on it is to launch the calendaring program. Since there is no Unicode character that corresponds to this function, and there is no appropriate entry in the predefined key identifier list, a new identifier may be devised, such as "Calendar".

Future versions of this specification may include key identifiers not included here, which have become common since the publication of this specification.