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 existing 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 task. The task may be defined for that element by the host language, or by author-defined variables, or both. The default task 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 is 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 is be to send the values of the form elements to an author-defined IRI by the author-defined HTTP method. See Activation triggers and behavior for more details.

activation trigger

An event which is defined to initiate an activation behavior. Refer to Activation triggers and behavior for more details.

author

In the context of this specification, an author, content author, or script author is a person who writes script or other executable content that uses the interfaces, events, and event flow defined in this specification. See Content authors and content conformance category for more details.

bubbling phase

The process by which an event can be handled by one of the target ancestors after being handled by the proximal event target. See the description of the bubble phase in the context of event flow for more details.

capture phase

The process by which an event can be handled by one of the target ancestors before being handled by the proximal event target. See the description of the capture phase in the context of event flow for more details.

character value

In the context of key values, a character value is a string representing one or more Unicode characters, such as a letter or symbol, or a set of letters. Note: in source code, some key values, such as non-graphic characters, may be represented using the character escape syntax of the programming language in use.

dead key

A dead key is a key or combination of keys which 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 an optional supplementary behavior that an implementation must perform in combination with the dispatch of the event object. Each event type definition, and each specification, defines the default action for that event type, if it has one. An instance of an event may have more than one default action under some circumstances, such as when associated with an activation trigger. 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 document's browsing context's Window Proxy object as defined in HTML5.

delta

The distance an input device using the WheelEvent interface (such as a mouse wheel) has rotated around its axis. The value of a delta must be a floating point number indicating the number of pixels, lines, or pages scrolled (as indicated by the deltaMode property. The relationship between the physical direction of rotation and whether the delta is positive or negative is environment and device dependent. However, if a user agent scrolls as the default action then the sign of the delta is given by a right-hand coordinate system where positive X,Y, and Z axes are directed towards the right-most edge, bottom-most edge, and farthest depth (away from the user) of the document, respectively.

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 must be deprecated in this specification. Implementations which do not already include support for the feature may implement deprecated features for reasons of backwards compatibility with existing content, but content 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. Features marked as deprecated in this specification are expected to be dropped from future specifications.

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”.

document

An object instantiating the Document interface [DOM3 Core], representing the entire HTML or XML text document. Conceptually, it is the root of the document tree, and provides the primary access to the document's data.

DOM application

A DOM application is script or code, written by a content author or automatically generated, which takes advantage of the interfaces, methods, attributes, events, and other features described in this specification in order to make dynamic or interactive content, such as Web applications, exposed to users in a user agent.

DOM Level 0

The term “DOM Level 0” refers to a mix of HTML document functionalities, often not formally specified but traditionally supported as de facto standards, implemented originally by Netscape Navigator version 3.0 or Microsoft Internet Explorer version 3.0. In many cases, attributes or methods have been included for reasons of backward compatibility with “DOM Level 0”.

empty string

The empty string is a value of type DOMString of length 0, i.e., a string which contains no characters (neither printing nor control characters).

event

An event is the representation of some occurrence (such as a mouse click on the presentation of an element, the removal of child node from an element, or any number of other possibilities) which is associated with its proximal event target. Each event is an instantiation of one specific event type.

event order

The sequence in which events from the same event source or process occur, using the same or related event interfaces. For example, in an environment with a mouse, a track pad, and a keyboard, each of those input devices would constitute a separate event source, and each would follow its own event order; a mousedown event from the trackpad followed by a mouseup event from the mouse would not result in a click event. Note that there may be interactions between different event orders; for example, a click event might be modified by a concurrent keypress event (shift+click); however, the event orders of these different event sources would be distinct. The event order of some interfaces are device-independent; for example, a user might change focus using the 'Tab' key, or by clicking the new focused element with the mouse. The event order in such cases depends on the state of the process, not on the state of the device that initiates the state change.

event phase

See phase.

event target

The object to which an event is targeted.

event type

An event type is an event object with a particular name and which defines particular trigger conditions, properties, 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 Event.type attribute on the event object. See event types for more details. Also loosely referred to as 'event', such as the click event.

focus

Focus is a special state of receptivity and concentration on an particular element or other event target within a document. Each element has different behavior when focused, depending on its functionality, such as priming the element for activation (as for a button or hyperlink) or toggling state (as for a checkbox), receiving text input (as for a text form field), or copying selected text. For more details, see Document Focus and Focus Context.

focus ring

A focus ring is a an ordered set of focus targets within a document. A host language may define one or more ways to determine the order of targets, such as document order, a numerical index defined per focus target, explicit pointers between focus targets, or a hybrid of different models. Each document may contain multiple focus rings, or conditional focus rings. Typically, for document-order or indexed focus rings, focus “wraps around” from the last focus target to the first.

fire

A synonym for dispatch.

host language

Any language which integrates the features of another language or API specification, while normatively referencing the origin specification rather than redefining those features, and extending those features only in ways defined by the origin specification. An origin specification 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.

hysteresis

A feature of human interface design to accept input values within a certain range of location or time, in order to improve the user experience. For example, allowing for small deviation in the time it takes for a user to double-click a mouse button is temporal hysteresis, and not immediately closing a nested menu if the user mouses out from the parent window when transitioning to the child menu is locative hysteresis.

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.

key value

A key value is character value or multi-character string (such as 'Enter', 'Tab', or 'MediaNextTrack') associated with a key in a particular state. Every key has a key value, whether or not it has a character value; this includes control keys, function keys, modifier keys, dead keys, and any other key. The key value of any given key at any given time depends upon the key mapping.

key mapping

Key mapping is the process of assigning a key value to a particular key, and is the result of a combination of several factors, including the operating system and the keyboard layout (e.g., QWERTY, Dvorak, Spanish, InScript, Chinese, etc.), and after taking into account all modifier key ('Shift', 'Alt', etc.) and dead key states.

local name

See local name in [XML Namespaces 1.0].

modifier key

A modifier key changes the normal behavior of a key, such as to produce a character of a different case (as with the 'Shift' key), or to alter what functionality the key triggers (as with the 'Fn' or 'Alt' keys). Refer to the KeyboardEvent.getModifierState() method for a list of modifier keys defined in this specification. See also Modifier keys.

namespace URI

A namespace URI is a URI that identifies an XML namespace. This is called the namespace name in [XML Namespaces 1.0]. 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 defaultView (window), to the Document object, root element, and down to the event target (capture phase), at the event target itself (target phase), and back up the same chain (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 proximal event target. As the event propagates, each event target in the propagation path is in turn set as the Event.currentTarget. The propagation path is initially composed of one or more event phases as defined by the event type, but may be interrupted. Also known as an event target chain.

proximal event target

The proximal event target is the object representing the event target to which an event is targeted using the DOM event flow. The proximal event target is the value of the Event.target attribute.

QWERTY

QWERTY (pronounced "ˈkwɜrti") is a common keyboard layout, so named because the first five character keys on the top row of letter keys are Q, W, E, R, T, and Y. There are many other popular keyboard layouts (including the Dvorak and Colemak layouts), most designed for localization or ergonomics.

root element

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

rotation

An indication of incremental change on an input device using the WheelEvent interface. On some devices this may be a literal rotation of a wheel, while on others, it may be movement along a flat surface, or pressure on a particular button.

text composition system

A software component that 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.

target phase

The process by which an event can be handled by the proximal event target. See the description of the target phase in the context of event flow for more details.

topmost event target

The topmost event target must be the element highest in the rendering order which is capable of being an event target. In this case, 'top' must 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. For specific details regarding hit testing and stacking order, refer to the host language.

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.

Unicode code point

A Unicode code point is a unique hexadecimal number signifying a character by its index in the Unicode codespace (or library of characters). In the context of key values, a Unicode code point is expressed as a string in the format “\u” followed by a hexadecimal character index in the range 0000 to 10FFFF, using at least four digits. See also character value.

user agent

A program, such as a browser or content authoring tool, normally running on a client machine, which acts on a user's behalf in retrieving, interpreting, executing, presenting, or creating content. Users may act on the content using different user agents at different times, for different purposes. See the Web browsers and other dynamic or interactive user agents and Authoring tools for details on the requirements for a conforming user agent.

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 1: graphical representation of an event dispatched in a DOM tree using the DOM event flow

Event objects are always dispatched to the proximal event target. At the beginning of the dispatch, implementations must first determine the event object's propagation path.

The propagation path must be an ordered list of event targets through which the event object must pass. For tree-based DOM implementations, the propagation path must be reflect the hierarchical tree structure of the document. The last item in the list must be the proximal 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; for tree-based DOM implementations, this applies 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 proximal event target in the document while the event object is being dispatched; such changes do not affect the propagation path. Additionally, exceptions inside event listeners do not stop the propagation of the event or 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 must 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 will 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 object's proximal event 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 must handle the event after it has reached its target.

Implementations must 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 must be the next pending event target in the partial propagation path, starting with the first. From the perspective of an event listener this must be the event target the listener has been registered on.

Next, the implementation must determine the current target's candidate event listeners. This must be the list of all event listeners that have been registered on the current target in their order of registration. [HTML5] defines the ordering of listeners registered through event handler attributes. 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 must 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 object's 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.

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 must 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 must 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 must be defined individually for each event type. An alternate application of this model can be found in [DOM3 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 one or more 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 [HTML5] form element. When the user submits the form (e.g., by pressing on a submit button), the HTML event submit will be dispatched to the element and the default action for this event type will 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 must 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 with 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 might scroll a document view by a certain amount as default action of a mouse wheel event, while another implementation might instead zoom the document as its default action for a mouse wheel event.

3.3 Synchronous and asynchronous events

Events may be either synchronously or asynchronously .

Events which are synchronous ("sync events") must be treated as if they are in a virtual queue in a first-in-first-out model, ordered by sequence of temporal occurrence, with respect to other events, to changes in the DOM, and to user interaction. Each event in this virtual queue must be delayed until the previous event has completed its propagation behavior, or been canceled. Some sync events are driven by a specific device or process, such as mouse button events; these events are governed by the event order algorithms defined for that set of events, and a user agent must dispatch these events in the defined order.

Example: A user double-clicks a passage of text to select a word, then presses the 'delete' key to erase the word, triggering the following synchronous sequence of events: mousedown, mouseup, click, mousedown, mouseup, click, dblclick, select, keydown, DOMCharacterDataModified. Each of these events are fired in the sequence initiated by the user's actions.

Events which are asynchronous ("async events") may be dispatched as the results of the action are completed, with no relation to other events, to other changes in the DOM, nor to user interaction.

Example: During loading of a document, an inline script element is parsed and executed. The load event is queued to be fired asynchronously at the script element. However, because it is an async event, its order with relation to other synchronous events fired during load (such as the DOMContentLoaded event from HTML5).

3.3.1 Event order and event loops

Most events take place in a sequential context. [HTML5] defines its event operations in terms of an event loop mechanism, in which events of all types are fed into different task queues. This specification does not define events in terms of this event loop mechanism, but it is compatible with this mechanism. Instead, this specification defines several operation-specific event orders.

Using the terminology of HTML5, each independent device, such as a mouse or keyboard, should be treated as a task source which feeds into the appropriate task queue, in the order defined by the event order associated with that device; each operation, such as a focus change or composition input, also acts as a task source for the appropriate task queue. The resolution of these event loops is handled in a manner conforming to the host language, such as HTML [HTML5].

Warning! Certain events, such as “hotkeys” or controls keys pressed in a certain sequence, may be “swallowed” by the operating system or the application, interrupting the expected event order. Content authors should make appropriate checks for such occurrences.

3.4 Trusted events

Events that are generated by the user agent, either as a result of user interaction, or as a direct result of changes to the DOM, are trusted by the user agent with privileges that are not afforded to events generated by script through the DocumentEvent.createEvent("Event") method, modified using the Event.initEvent() method, or dispatched via the EventTarget.dispatchEvent() method. The isTrusted attribute of trusted events has a value of true, while untrusted events have a isTrusted attribute value of false.

Most untrusted events should not trigger default actions, with the exception of click or DOMActivate events which have been synthesized and are managed by the user agents event as the default action of an activation trigger (see Activation triggers and behaviors for more details); these user-agent-managed synthesized events have an isTrusted attribute value of false, but still initiate any default actions. All other untrusted events must behave as if the Event.preventDefault() method had been called on that event.

For security reasons, a host language should not define events which are not cancelable (see Default actions and cancelable events), but also have default actions, since these default actions may be initiated by untrusted events.

3.5 Activation triggers and behavior

Certain proximal event targets (such as a link or button element) may have associated activation behavior (such a following a link) that implementations perform in response to an activation trigger (such as clicking a link).

A host language should indicate which, if any, elements have activation behavior, describe appropriate activation triggers, and define the result of that activation behavior. An implementation which supports a host language should initiate these activation behavior when the associated activation trigger occurs.

Example: Both HTML and SVG have an a element which indicates a link. Relevant activation triggers for an a element are a click event on the text or image content of the a element, or a keydown event with a key attribute value of 'Enter' key when the a element has focus. The activation behavior for an a element is normally to change the content of the window to the content of the new document, in the case of external links, or to reposition the current document relative to the new anchor, in the case of internal links.

An activation trigger is a user action or an event which indicates to the implementation that an activation behavior should be initiated. User-initiated activation triggers include clicking a mouse button on an activatable element, pressing the 'Enter' key when an activatable element has focus, or pressing a key that is somehow linked to an activatable element (a “hotkey” or “access key”) even when that element does not have focus. Event-based activation triggers may include timer-based events that activate an element at a certain clock time or after a certain time period has elapsed, progress events after a certain action has been completed, or many other condition-based or state-based events.

In some cases, a host language may define attributes or even attribute values which add to or change the native activation trigger or activation behavior of an element. For example, ARIA [ARIA] defines values for the role attribute that add semantics to the element to which it is applied, for purposes of enhanced accessibility. In such cases, if the host language does not explicitly define the activation trigger or activation behavior, the content author must provide the mechanics of the activation trigger (via an event listener) or activation behavior (such as calling an ECMAScript function) for that element when applying that attribute or attribute value.

3.5.1 Activation event synthesis

If the instance of the activation trigger is not an event of event type click (that is, when it does not result from a user's activation of a button or link using a mouse or equivalent pointing device), the implementation must synthesize and dispatch an event of event type click as one of the default actions of that activation trigger; the value of the Event.target must be set to the proximal event target (normally, the currently focused element), and the event must simulate a left click (i.e., the MouseEvent.button attribute value must be 0, and the MouseEvent.buttons attribute value must be 1). Other context information of such a simulated click event is implementation dependent, but for historical purposes, the interface for the click event must be the MouseEvent interface, regardless of the actual device used to activate the element. Preventing the default action of the activation trigger, such as with the Event.preventDefault(), must stop the initiation of the activation behavior.

Example: When a user activates a hyperlink using a keyboard, such as by focusing the hyperlink element and pressing the 'Enter' or 'Space' key, a click event would be dispatched as the default action of the respective keydown event.

Implementations must dispatch the synthesized click event as described above even if they do not normally 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.

Implementations which support the DOMActivate event type should also dispatch a DOMActivate event as a default action of a click event which is associated with an activation trigger. However, such implementations should only initiate the associated activation behavior once for any given occurrence of an activation trigger.

Example: The DOMActivate event type is required to be supported for XForms [XFORMS], which is intended for implementation within a host language. In a scenario where a plugin or script-based implementation of XForms is intended for installation in a native implementation of this specification which does not support the DOMActivate event type, the XForms user agent has to synthesize and dispatch its own DOMActivate events based on the appropriate activation triggers. Thus, when a click event is dispatched by the DOM Level 3 Events user agent, the XForms user agent has to determine whether to synthesize a DOMActivate event with the same relevant properties as a default action of that click event; appropriate cues might be whether the click event is trusted, or whether its proximal event target has a DOMActivate event listener registered.

Note: Content authors should not rely upon the interoperable support of DOMActivate in many user agents. Thus, content authors may use the DOMActivate event type whenever they wish to make or react to an activation trigger, but should use the click event type for more accessible behavior instead, due to wider implementation.

Warning! The DOMActivate event type is deprecated in this specification.

3.5.1 Activation Event Order

Activation triggers and behavior can be defined in part by the events which are dispatched in a set order relative to one another. The following is the typical sequence of events for an element activated by a pointing device (with only pertinent events listed):

1. click
2. DOMActivate (default action, if supported by the user agent; synthesized; trusted="false")
3. All other default actions, including the activation behavior

The following is the typical sequence of events when a focused element is activated by a key event (with only pertinent events listed):

1. keydown (must be a key which can activate the element, such as the 'Enter' or 'Space' key, or the element is not activated)
2. click (default action; synthesized; trusted="false")
3. DOMActivate (default action, if supported by the user agent; synthesized; trusted="false")
4. All other default actions, including the activation behavior

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 must 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 2: 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 must 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:
  void                               stopImmediatePropagation();
  readonly attribute boolean         defaultPrevented;
  readonly attribute boolean         isTrusted;
};
                

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 proximal 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 must be true, otherwise the value must 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 must be true, otherwise the value must 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 proximal event target 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.

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

Used to indicate whether this event was generated by the user agent (trusted) or by script (untrusted). See trusted events for more details.

eventPhase of type unsigned short, readonly

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

target of type EventTarget, readonly

Used to indicate the event target. This attribute contains the proximal event target 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.

type of type DOMString, readonly

The name of the event type. The name must be a DOMString. Specifications that define events, content authors, and authoring tools must use case-sensitive event type names.

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.

Warning! For security reasons, events modified using Event.initEvent() must have a isTrusted attribute value of false. See trusted events for more details.

Parameters

eventTypeArg of type DOMString

Specifies Event.type, the 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

preventDefault

When this method is invoked, the event must be canceled, meaning any default actions normally taken by the implementation as a result of the event must not occur (see also Default actions and cancelable events). Default actions which occur prior to the event's dispatch (see Default actions and cancelable events) are reverted. Calling this method for a non-cancelable event must have no effect. If an event has more than one default action, each cancelable default action must be canceled.

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 must 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 must 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 use a prefix string on the event type name 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 any             detail;
  void                               initCustomEvent(in DOMString typeArg, 
                                                     in boolean   canBubbleArg, 
                                                     in boolean   cancelableArg, 
                                                     in any       detailArg);
};
                

Attributes

detail of type any, 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 any

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 must 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.

Note: Though an event listener can be registered for any event target node, the user agent only dispatches UA-generated (trusted) events on node types that are defined as proximal event target types for that specific event type (see the List of DOM3 Event Types); for example, a mouseover event type registered on a text node will never be fired by the user agent, though a content author could dispatch an event of that type on the text node via script.

When used with the DOM event flow, this interface must be implemented by all proximal event targets 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 repeatedly on the same EventTarget with the same values for the parameters 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.

Note: In addition to the EventTarget.addEventListener method, some host languages may allow a content author to register event listeners by the use of attributes, e.g., onclick="handleClick()". Because the details of this are often language-specific, this type of event listener registration is not defined in this specification, but in general, any event type may be used as an attribute in this way by adding the prefix on- to the event type name, and events so dispatched should behave consistently with the event registration and propagation defined in this specification, with the same interfaces, properties, and methods.

IDL Definition

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

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.

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 must be an object which implements the EventListener interface, such as a reference to a .

The listener parameter must be either an object that implements the EventListener interface, or a function. If listener is a function then it must be used as the callback for the event; otherwise, if listener implements EventTarget, then its handleEvent method must be used as the callback.

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

Note: The listener may be a reference to a function object or an inline function object literal.

useCapture of type boolean

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

This parameter may be optional, on an implementation-specific basis. If not provided, the EventTarget.addEventListener method must behave as if useCapture were specified to be false. See the non-normative Interface EventTarget WebIDL definition for a formal description.

Note: For programming languages which do not allow optional method parameters, such as Java, the implementation may provide two EventTarget.addEventListener methods, one with 2 parameters, and one with 3 parameters.

Authoring Note: The useCapture parameter was required in DOM2 Events [DOM2 Events], and omitting this parameter may cause an error in older implementations.

No Return Value

No Exceptions

removeEventListener

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

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 and target phases and once for the target and bubbling phases, each must be removed separately. Removal of an event listener registered for the capture and target phases does not affect the same event listener registered for the target and bubbling phases, and vice versa.

This parameter may be optional, on an implementation-specific basis. If not provided, the EventTarget.removeEventListener method must behave as if useCapture were specified to be false, including the removal of event listeners which had an EventTarget.addEventListener useCapture value of false. See the non-normative Interface EventTarget WebIDL definition for a formal description

Note: For programming languages which do not allow optional method parameters, such as Java, the implementation may provide two EventTarget.removeEventListener methods, one with 2 parameters, and one with 3 parameters.

Authoring Note: The useCapture parameter was required in DOM2 Events [DOM2 Events], and omitting this parameter may cause an error in older implementations.

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 must be the EventTarget object on which dispatchEvent is called.

Warning! For security reasons, events dispatched using EventTarget.dispatchEvent() must have a isTrusted attribute value of false. See trusted events for more details.

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 must be false, else it must be true.

Exceptions

EventException	UNSPECIFIED_EVENT_TYPE_ERR: Raised if the Event.type was not specified by initializing the event before dispatchEvent was called. 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 a DOMString as conforming to the restrictions in Event.type.

4.4 Interface EventListener

Interface EventListener (introduced in DOM Level 2)

The EventListener interface is the primary way to handle events. Content authors must define on object, such as a function, which the EventListener interface and register their event listener on an EventTarget. The content authors 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, must 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 must 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 {
  // EventExceptionCode
  const unsigned short      UNSPECIFIED_EVENT_TYPE_ERR     = 0;
  // Introduced in DOM Level 3:
  const unsigned short      DISPATCH_REQUEST_ERR           = 1;

  // Introduced in DOM Level 2:
  unsigned short            code;
};
                

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 [HTML5] application, the specifications of those languages may restrict the semantics and scope (in particular the possible proximal event targets) 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 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 of interpreting of this table, the event load is required to 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 defaultView, Document, or Element nodes, or if it is attached to the bubbling phase only, this event listener is required 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 and document manipulation.

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);
};
                

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

The User Interface event types are listed below. Some of these events use the UIEvent interface if generated from a user interface, but the Event interface otherwise, as detailed in each event.

5.2.5 Text Event 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 values 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 {

  // InputMethodCode
  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   inputMethod;  
  readonly attribute DOMString       locale;
  void                               initTextEvent(in DOMString typeArg, 
                                                   in boolean canBubbleArg, 
                                                   in boolean cancelableArg, 
                                                   in views::AbstractView viewArg, 
                                                   in DOMString dataArg, 
                                                   in unsigned long inputMethod, 
                                                   in DOMString localeArg);
};
                

Definition group InputMethodCode

This set of constants must be used to indicate the origin of the text input. In case a DOM implementation wishes to provide a new origin 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.

inputMethod of type unsigned long, readonly

The inputMethod attribute contains an indication of the origin of the text input, as described in InputMethodCode.

locale of type DOMString, readonly

The locale attribute contains a BCP-47 tag [BCP-47] indicating the locale for which the origin of the event (whether keyboard, IME, handwriting recognition software, or other input mode) is configured, e.g. "en-US". May be the empty string when inapplicable or unknown, e.g. for pasted text, or when this information is not exposed by the underlying platform.

Note: locale does not necessarily indicate the locale of the data or the context in which it is being entered. For example, a French user often might not switch to an English keyboard setting when typing English, in which case the locale will still indicate French, even though the data is actually English.

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.

inputMethodArg of type unsigned long

Specifies TextEvent.inputMethod.

localeArg of type DOMString

Specifies TextEvent.locale.

No Return Value

No Exceptions

The text event type is listed below.

5.2.6 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 event types when dealing with character input. Refer to Keyboard events and key values for more details, including examples on how Keyboard Events are used in combination with Composition Events. Depending on the character generation device, keyboard events may or may not be generated.

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 a value. 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(keyArg) 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       char;
  readonly attribute DOMString       key;
  readonly attribute unsigned long   location;
  readonly attribute boolean         ctrlKey;
  readonly attribute boolean         shiftKey;
  readonly attribute boolean         altKey;
  readonly attribute boolean         metaKey;
  readonly attribute boolean         repeat;
  readonly attribute DOMString       locale;
  boolean                            getModifierState(in DOMString keyArg);
  void                               initKeyboardEvent(in DOMString typeArg, 
                                                       in boolean canBubbleArg, 
                                                       in boolean cancelableArg, 
                                                       in views::AbstractView viewArg, 
                                                       in DOMString charArg, 
                                                       in DOMString keyArg, 
                                                       in unsigned long locationArg, 
                                                       in DOMString modifiersListArg,
                                                       in boolean repeat,
                                                       in DOMString localeArg); 
};
                

Definition group KeyLocationCode

This set of constants must 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_STANDARD

The key activation must 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_LEFT

The key activated originated from 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_RIGHT

The key activation originalted from 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_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_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 'Alt' (alternative) or 'Option' key modifier was active.

ctrlKey of type boolean, readonly

true if the 'Ctrl' (control) key modifier was active.

char of type DOMString, readonly

char holds the character value of the key pressed. If the key press has a printed representation, then the value must be a non-empty Unicode character string, conforming to the algorithm for determining the key value defined in this specification. For a key associated with a macro to insert multiple characters, the value of the char attribute will hold the entire sequence of characters. For a key which does not have a character representation, the value must be the empty string.

Note: the char attribute is not related to the legacy charCode attribute and does not have the same set of values.

key of type DOMString, readonly

key holds the key value of the key pressed. If the value is has a printed representation, it must match the value of the KeyboardEvent.char attribute; if the value is a control key which has no printed representation, it must be one of the key values defined in the key values set, as determined by the algorithm for determining the key value. Implementations that are unable to identify a key must use the key value 'Unidentified'.

Note: the key attribute is not related to the legacy keyCode attribute and does not have the same set of values.

location of type unsigned long, readonly

The location 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 was active.

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 was active.

repeat of type boolean, readonly

true if the key has been pressed in a sustained manner. Holding down a key must result in the repeating the events keydown, keypress (when supported by the user agent), and textinput (when the keypress results in text input) in this order, at a rate determined by the system configuration. For mobile devices which have long-key-press behavior, the first key event with a repeat attribute value of 'true' must 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.

locale of type DOMString, readonly

The locale attribute contains a BCP-47 tag [BCP-47] indicating the locale for which the keyboard originating the event is configured, e.g. "en-US". May be the empty string when inapplicable or unknown, e.g. when this information is not exposed by the underlying platform.

Note: locale does not necessarily indicate the locale of the data or the context in which it is being entered. For example, a French user often might not switch to an English keyboard setting when typing English, in which case the locale will still indicate French. Nor can it be used to definitively calculate the "physical" or "virtual" key associated with the event, or the character printed on that key.

Methods

getModifierState

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

Parameters

keyArg of type DOMString

A modifier key value. Modifier keys defined in this specification are 'Alt' 'AltGraph' 'CapsLock' 'Control' 'Fn' 'Meta' 'NumLock' 'Scroll' 'Shift' 'SymbolLock', and 'Win' User agents may support additional implementation-specific modifier keys depending on the environment.

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

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.

charArg of type DOMString

Specifies KeyboardEvent.char.

keyArg of type DOMString

Specifies KeyboardEvent.key.

locationArg of type unsigned long

Specifies KeyboardEvent.location.

modifiersListArg of type DOMString

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

repeatArg of type boolean

Specifies whether the key event is repeating; see KeyboardEvent.repeat.

localeArg of type DOMString

Specifies KeyboardEvent.locale.

No Return Value

No Exceptions

Warning! Legacy keyboard event implementations may include three additional attributes, keyCode, charCode, and which. The keyCode attribute indicates a numeric value associated with a particular key on a computer keyboard, while the charCode attribute indicates the ASCII value of the character associated with that key (which may or may not be the same as the keyCode value) and is applicable only to keys that produce a character value. In practice, keyCode and charCode are inconsistent across platforms and even the same implementation on different operating systems or using different localizations. DOM Level 3 Events does not define values for either keyCode or charCode, or behavior for charCode; content authors should use KeyboardEvent.key or KeyboardEvent.char instead, in conforming DOM Level 3 Events implementations. For more information, see the informative appendix on Legacy key attributes: keyCode, charCode, and which.

Note: For compatibility with existing content, virtual keyboards, such as software keyboards on screen-based input devices, should produce the normal range of keyboard events, even though they do not possess physical keys.

Note: In some implementations or system configurations, some key events, or their values, might be suppressed by the IME in use.

The keyboard event types are listed below.

5.2.6.1 Keyboard Event Order

The keyboard events defined in this specification occur in a set order relative to one another, for any given key:

1. keydown
2. keypress (only for keys which produce a character value)
3. If the key is depressed for a sustained period, the following events may repeat at an environment-dependent rate:
   • keydown (with repeat attribute set to true)
   • keypress (with repeat attribute set to true; only for keys which produce a character value)
4. Any default actions related to this key
5. keyup

Keys associated with a character value must, under normal circumstances, produce a textinput event as well. The order of text events relative to keyboard events is as follows:

1. keydown
2. keypress (only for keys which produce a character value)
3. If a character value is produced, textinput
4. If the key is depressed for a sustained period, the following events may repeat at an environment-dependent rate:
   • keydown (with repeat attribute set to true)
   • keypress (with repeat attribute set to true; only for keys which produce a character value)
   • If a character value is produced, textinput
5. Any default actions associated with this key
6. keyup

Note: Typically, any default actions associated with any particular key must be completed before the keyup event is dispatched, which may delay the keyup event slightly (though this is not likely to be a perceptible delay).

Warning! Because of hardware limitations, on some keyboard devices, the order between the text event and keyboard events may differ. For example, some mobile devices might dispatch the textinput event after the keyup event.

The target of a key event is the currently focused element which is processing the keyboard activity; this is often an HTML input element or a textual element which is editable, but may be an element defined by the host language to accept keyboard input for non-text purposes, such as the activation of a hotkey or trigger of some other behavior; if no suitable element is in focus, the event target will be the root element.

Note: The event target may change between different key events; for example, a keydown event on the 'Tab' key will likely have a different event target than the keyup event on the same keystroke.

5.2.7 Composition Event 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 example, Composition events might 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 values 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. While a composition session is active, keyboard events should not be dispatched to the DOM (i.e., the text composition system “swallows” the keyboard events), and only compositionupdate events may be dispatched to indicate the composition process.

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;
  readonly attribute DOMString       locale;
  void                               initCompositionEvent(in DOMString typeArg, 
                                                          in boolean canBubbleArg, 
                                                          in boolean cancelableArg, 
                                                          in views::AbstractView viewArg, 
                                                          in DOMString dataArg,
                                                          in DOMString localeArg);
};
                

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.

locale of type DOMString, readonly

The locale attribute contains a BCP-47 tag [BCP-47] indicating the locale for which the IME originating the event is configured, e.g. "ja", "zh-Hans", "ko". May be the empty string when inapplicable or unknown, e.g. when this information is not exposed by the underlying platform or application.

Note: locale does not necessarily indicate the locale of the data or the context in which it is being entered. For example, a French user often might not switch to an English keyboard setting when typing English, in which case the locale will still indicate French, even though the data is actually English. Similarly, an IME application may not distinguish between the locale of Chinese and Kanji characters.

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.

localeArg of type DOMString

Specifies CompositionEvent.locale.

No Return Value

No Exceptions

The composition event types are listed below.

5.2.7.1 Composition Event Order

The composition events defined in this specification occur in a set order relative to one another:

1. compositionstart
2. compositionupdate (multiple events)
3. compositionend

Composition events which are not canceled and which do not have the empty string as a value produce a textinput event as well. The order of text events relative to composition events is as follows:

1. compositionstart
2. compositionupdate (multiple events)
3. If a character value is produced, textinput
4. compositionend

5.2.8 Mutation Events

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

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.

Warning! 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 reference and completeness of legacy behavior, but deprecates the use of both the MutationEvent interface and the MutationNameEvent interface.

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);
};
                

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 must 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 will be the changed parent. If an event is instead dispatched to a subtree indicating a node was changed within it, the relatedNode must 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 the empty string.

newValueArg of type DOMString

Specifies MutationEvent.newValue. This value may be the empty string.

attrNameArg of type DOMString

Specifies MutationEvent.attrName. This value may be the empty string.

attrChangeArg of type unsigned short

Specifies MutationEvent.attrChange. This value may be 0.

No Return Value

No Exceptions