1

UI Events

 3 years ago
source link: https://w3c.github.io/uievents/
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
neoserver,ios ssh client

5. Event Types

The DOM Event Model allows a DOM implementation to support multiple modules of events. The model has been designed to allow addition of new event modules in the future. This document does not attempt to define all possible events. For purposes of interoperability, the DOM defines a module of user interface events including lower level device dependent events and a module of document mutation events.

5.1. User Interface Events

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

5.1.1. 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 UIEvent constructor, passing an optional UIEventInit dictionary.

For newly defined events, you don’t have to inherit UIEvent interface just because they are related to user interface. Inherit only when members of UIEventInit make sense to those events.

5.1.1.1. UIEvent
[Exposed=Window]
interfaceUIEvent : Event {
  constructor(DOMString type, optionalUIEventInit eventInitDict);
  readonlyattributeWindow? view;
  readonlyattributelong detail;
};
UIEvent . view The view attribute identifies the Window from which the event was generated.

The un-initialized value of this attribute MUST be null.

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

The un-initialized value of this attribute MUST be 0.

5.1.1.2. UIEventInit
dictionaryUIEventInit : EventInit {
  Window? view = null;
  long detail = 0;
};
UIEventInit . view Should be initialized to the Window object of the global environment in which this event will be dispatched. If this event will be dispatched to an element, the view property should be set to the Window object containing the element’s ownerDocument. UIEventInit . detail This value is initialized to a number that is application-specific.

5.1.2. UI Event Types

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.1.2.1. load
Type load Interface UIEvent if generated from a user interface, Event otherwise. Sync / Async Async Bubbles No Trusted Targets Window, Document, Element Cancelable No Default action None Context
(trusted events)

A user agent MUST dispatch this event when the DOM implementation finishes loading the resource (such as the document) and any dependent resources (such as images, style sheets, or scripts). Dependent resources that fail to load MUST NOT prevent this event from firing if the resource that loaded them is still accessible via the DOM. If this event type is dispatched, implementations are REQUIRED to dispatch this event at least on the Document node.

For legacy reasons, load events for resources inside the document (e.g., images) do not include the Window in the propagation path in HTML implementations. See [HTML5] for more information.

5.1.2.2. unload
Type unload Interface UIEvent if generated from a user interface, Event otherwise. Sync / Async Sync Bubbles No Trusted Targets Window, Document, Element Cancelable No Default action None Context
(trusted events)

A user agent MUST dispatch this event when the DOM Implementation removes from the environment the resource (such as the document) or any dependent resources (such as images, style sheets, scripts). The document MUST be unloaded after the dispatch of this event type. If this event type is dispatched, implementations are REQUIRED to dispatch this event at least on the Document node.

5.1.2.3. abort
Type abort Interface UIEvent if generated from a user interface, Event otherwise. Sync / Async Sync Bubbles No Trusted Targets Window, Element Cancelable No Default action None Context
(trusted events)

A user agent MUST dispatch this event when the loading of a resource has been aborted, such as by a user canceling the load while it is still in progress.

5.1.2.4. error
Type error Interface UIEvent if generated from a user interface, Event otherwise. Sync / Async Async Bubbles No Trusted Targets Window, Element Cancelable No Default action None Context
(trusted events)

A user agent MUST dispatch this event when a resource failed to load, or has been loaded but cannot be interpreted according to its semantics, such as an invalid image, a script execution error, or non-well-formed XML.

5.1.2.5. select
Type select Interface UIEvent if generated from a user interface, Event otherwise. Sync / Async Sync Bubbles Yes Trusted Targets Element Cancelable No Default action None Context
(trusted events)

A user agent MUST dispatch this event when a user selects some text. This event is dispatched after the selection has occurred.

This specification does not provide contextual information to access the selected text. Where applicable, a host language SHOULD define rules for how a user MAY select content (with consideration for international language conventions), at what point the select event is dispatched, and how a content author MAY access the user-selected content.

In order to access to user-selected content, content authors will use native capabilities of the host languages, such as the Document.getSelection() method of the HTML Editing APIs [Editing].

The select event might not be available for all elements in all languages. For example, in [HTML5], select events can be dispatched only on form input and textarea elements. Implementations can dispatch select events in any context deemed appropriate, including text selections outside of form controls, or image or markup selections such as in SVG.

5.2. Focus Events

This interface and its associated event types and § 5.2.2 Focus Event Order were designed in accordance to the concepts and guidelines defined in User Agent Accessibility Guidelines 2.0 [UAAG20], with particular attention on the focus mechanism and the terms defined in the glossary entry for focus.

5.2.1. Interface FocusEvent

Introduced in this specification

The FocusEvent interface provides specific contextual information associated with Focus events.

To create an instance of the FocusEvent interface, use the FocusEvent constructor, passing an optional FocusEventInit dictionary.

5.2.1.1. FocusEvent
[Exposed=Window]
interfaceFocusEvent : UIEvent {
  constructor(DOMString type, optionalFocusEventInit eventInitDict);
  readonlyattributeEventTarget? relatedTarget;
};
FocusEvent . relatedTarget Used to identify a secondary EventTarget related to a Focus event, depending on the type of event.

For security reasons with nested browsing contexts, when tabbing into or out of a nested context, the relevant EventTarget SHOULD be null.

The un-initialized value of this attribute MUST be null.

5.2.1.2. FocusEventInit
dictionaryFocusEventInit : UIEventInit {
  EventTarget? relatedTarget = null;
};
FocusEventInit . relatedTarget The relatedTarget should be initialized to the element losing focus (in the case of a focus or focusin event) or the element gaining focus (in the case of a blur or focusout event).

5.2.2. Focus Event Order

The focus events defined in this specification occur in a set order relative to one another. The following is the typical sequence of events when a focus is shifted between elements (this order assumes that no element is initially focused):

Event Type Notes User shifts focus 1 focusin Sent before first target element receives focus 2 focus Sent after first target element receives focus User shifts focus 3 focusout Sent before first target element loses focus 4 focusin Sent before second target element receives focus 5 blur Sent after first target element loses focus 6 focus Sent after second target element receives focus

This specification does not define the behavior of focus events when interacting with methods such as focus() or blur(). See the relevant specifications where those methods are defined for such behavior.

5.2.3. Document Focus and Focus Context

This event module includes event types for notification of changes in document focus. There are three distinct focus contexts that are relevant to this discussion:

  • The operating system focus context which MAY be on one of many different applications currently running on the computer. One of these applications with focus can be a browser.

  • When the browser has focus, the user can switch (such as with the tab key) the application focus context among the different browser user interface fields (e.g., the Web site location bar, a search field, etc.). One of these user interface fields can be the document being shown in a tab.

  • When the document itself has focus, the document focus context can be set to any of the focusable elements in the document.

The event types defined in this specification deal exclusively with document focus, and the event target identified in the event details MUST only be part of the document or documents in the window, never a part of the browser or operating system, even when switching from one focus context to another.

Normally, a document always has a focused element (even if it is the document element itself) and a persistent focus ring. When switching between focus contexts, the document’s currently focused element and focus ring normally remain in their current state. For example, if a document has three focusable elements, with the second element focused, when a user changes operating system focus to another application and then back to the browser, the second element will still be focused within the document, and tabbing will change the focus to the third element. A host language MAY define specific elements which might receive focus, the conditions under which an element MAY receive focus, the means by which focus MAY be changed, and the order in which the focus changes. For example, in some cases an element might be given focus by moving a pointer over it, while other circumstances might require a mouse click. Some elements might not be focusable at all, and some might be focusable only by special means (clicking on the element), but not by tabbing to it. Documents MAY contain multiple focus rings. Other specifications MAY define a more complex focus model than is described in this specification, including allowing multiple elements to have the current focus.

5.2.4. Focus Event Types

The Focus event types are listed below.

5.2.4.1. blur
Type blur Interface FocusEvent Sync / Async Sync Bubbles No Trusted Targets Window, Element Cancelable No Composed Yes Default action None Context
(trusted events)

A user agent MUST dispatch this event when an event target loses focus. The focus MUST be taken from the element before the dispatch of this event type. This event type is similar to focusout, but is dispatched after focus is shifted, and does not bubble.

5.2.4.2. focus
Type focus Interface FocusEvent Sync / Async Sync Bubbles No Trusted Targets Window, Element Cancelable No Composed Yes Default action None Context
(trusted events)

A user agent MUST dispatch this event when an event target receives focus. The focus MUST be given to the element before the dispatch of this event type. This event type is similar to focusin, but is dispatched after focus is shifted, and does not bubble.

5.2.4.3. focusin
Type focusin Interface FocusEvent Sync / Async Sync Bubbles Yes Trusted Targets Window, Element Cancelable No Composed Yes Default action None Context
(trusted events)

A user agent MUST dispatch this event when an event target is about to receive focus. This event type MUST be dispatched before the element is given focus. The event target MUST be the element which is about to receive focus. This event type is similar to focus, but is dispatched before focus is shifted, and does bubble.

When using this event type, the content author can use the event’s relatedTarget attribute (or a host-language-specific method or means) to get the currently focused element before the focus shifts to the next focus event target, thus having access to both the element losing focus and the element gaining focus without the use of the blur or focusout event types.

5.2.4.4. focusout
Type focusout Interface FocusEvent Sync / Async Sync Bubbles Yes Trusted Targets Window, Element Cancelable No Composed Yes Default action None Context
(trusted events)

A user agent MUST dispatch this event when an event target is about to lose focus. This event type MUST be dispatched before the element loses focus. The event target MUST be the element which is about to lose focus. This event type is similar to blur, but is dispatched before focus is shifted, and does bubble.

5.3. Mouse Events

The mouse event module originates from the [HTML401] onclick, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, and onmouseout attributes. This event module is specifically designed for use with pointing input devices, such as a mouse or a trackball.

5.3.1. Interface MouseEvent

Introduced in DOM Level 2, modified in this specification

The MouseEvent interface provides specific contextual information associated with Mouse events.

In the case of nested elements, mouse events are always targeted at the most deeply nested element.

Ancestors of the targeted element can use event bubbling to obtain notifications of mouse events which occur within their descendent elements.

To create an instance of the MouseEvent interface, use the MouseEvent constructor, passing an optional MouseEventInit dictionary.

When initializing MouseEvent objects using initMouseEvent, implementations can use the client coordinates clientX and clientY for calculation of other coordinates (such as target coordinates exposed by DOM Level 0 implementations or other proprietary attributes, e.g., pageX).

5.3.1.1. MouseEvent
[Exposed=Window]
interfaceMouseEvent : UIEvent {
  constructor(DOMString type, optionalMouseEventInit eventInitDict);
  readonlyattributelong screenX;
  readonlyattributelong screenY;
  readonlyattributelong clientX;
  readonlyattributelong clientY;

  readonlyattributeboolean ctrlKey;
  readonlyattributeboolean shiftKey;
  readonlyattributeboolean altKey;
  readonlyattributeboolean metaKey;

  readonlyattributeshort button;
  readonlyattributeunsignedshort buttons;

  readonlyattributeEventTarget? relatedTarget;

  boolean getModifierState(DOMString keyArg);
};
screenX, of type long, readonly The horizontal coordinate at which the event occurred relative to the origin of the screen coordinate system.

The un-initialized value of this attribute MUST be 0.

screenY, of type long, readonly The vertical coordinate at which the event occurred relative to the origin of the screen coordinate system.

The un-initialized value of this attribute MUST be 0.

clientX, of type long, readonly The horizontal coordinate at which the event occurred relative to the viewport associated with the event.

The un-initialized value of this attribute MUST be 0.

clientY, of type long, readonly The vertical coordinate at which the event occurred relative to the viewport associated with the event.

The un-initialized value of this attribute MUST be 0.

ctrlKey, of type boolean, readonly Refer to the KeyboardEvent's ctrlKey attribute.

The un-initialized value of this attribute MUST be false.

shiftKey, of type boolean, readonly Refer to the KeyboardEvent's shiftKey attribute.

The un-initialized value of this attribute MUST be false.

altKey, of type boolean, readonly Refer to the KeyboardEvent's altKey attribute.

The un-initialized value of this attribute MUST be false.

metaKey, of type boolean, readonly Refer to the KeyboardEvent's metaKey attribute.

The un-initialized value of this attribute MUST be false.

button, of type short, readonly During mouse events caused by the depression or release of a mouse button, button MUST be used to indicate which pointer device button changed state.

The value of the button attribute MUST be as follows:

  • 0 MUST indicate the primary button of the device (in general, the left button or the only button on single-button devices, used to activate a user interface control or select text) or the un-initialized value.

  • 1 MUST indicate the auxiliary button (in general, the middle button, often combined with a mouse wheel).

  • 2 MUST indicate the secondary button (in general, the right button, often used to display a context menu).

  • 3 MUST indicate the X1 (back) button.

  • 4 MUST indicate the X2 (forward) button.

Some pointing devices provide or simulate more button states, and values higher than 2 or lower than 0 MAY be used to represent such buttons.

The value of button is not updated for events not caused by the depression/release of a mouse button. In these scenarios, take care not to interpret the value 0 as the left button, but rather as the un-initialized value.

Some default actions related to events such as mousedown and mouseup depend on the specific mouse button in use.

The un-initialized value of this attribute MUST be 0.

buttons, of type unsigned short, readonly During any mouse events, buttons MUST be used to indicate which combination of mouse buttons are currently being pressed, expressed as a bitmask.

Though similarly named, the values for the buttons attribute and the button attribute are very different. The value of button is assumed to be valid during mousedown / mouseup event handlers, whereas the buttons attribute reflects the state of the mouse’s buttons for any trusted MouseEvent object (while it is being dispatched), because it can represent the "no button currently active" state (0).

The value of the buttons attribute MUST be as follows:

  • 0 MUST indicate no button is currently active.

  • 1 MUST indicate the primary button of the device (in general, the left button or the only button on single-button devices, used to activate a user interface control or select text).

  • 2 MUST indicate the secondary button (in general, the right button, often used to display a context menu), if present.

  • 4 MUST indicate the auxiliary button (in general, the middle button, often combined with a mouse wheel).

Some pointing devices provide or simulate more buttons. To represent such buttons, the value MUST be doubled for each successive button (in the binary series 8, 16, 32, ... ).

Because the sum of any set of button values is a unique number, a content author can use a bitwise operation to determine how many buttons are currently being pressed and which buttons they are, for an arbitrary number of mouse buttons on a device. For example, the value 3 indicates that the left and right button are currently both pressed, while the value 5 indicates that the left and middle button are currently both pressed.

Some default actions related to events such as mousedown and mouseup depend on the specific mouse button in use.

The un-initialized value of this attribute MUST be 0.

relatedTarget, of type EventTarget, readonly, nullable Used to identify a secondary EventTarget related to a UI event, depending on the type of event.

The un-initialized value of this attribute MUST be null.

getModifierState(keyArg)

Introduced in this specification

Queries the state of a modifier using a key value.

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

DOMString keyArg Refer to the KeyboardEvent's getModifierState() method for a description of this parameter.
5.3.1.2. MouseEventInit
dictionaryMouseEventInit : EventModifierInit {
  long screenX = 0;
  long screenY = 0;
  long clientX = 0;
  long clientY = 0;

  short button = 0;
  unsignedshort buttons = 0;
  EventTarget? relatedTarget = null;
};
screenX, of type long, defaulting to 0 Initializes the screenX attribute of the MouseEvent object to the desired horizontal relative position of the mouse pointer on the user’s screen.

Initializing the event object to the given mouse position must not move the user’s mouse pointer to the initialized position.

screenY, of type long, defaulting to 0 Initializes the screenY attribute of the MouseEvent object to the desired vertical relative position of the mouse pointer on the user’s screen.

Initializing the event object to the given mouse position must not move the user’s mouse pointer to the initialized position.

clientX, of type long, defaulting to 0 Initializes the clientX attribute of the MouseEvent object to the desired horizontal position of the mouse pointer relative to the client window of the user’s browser.

Initializing the event object to the given mouse position must not move the user’s mouse pointer to the initialized position.

clientY, of type long, defaulting to 0 Initializes the clientY attribute of the MouseEvent object to the desired vertical position of the mouse pointer relative to the client window of the user’s browser.

Initializing the event object to the given mouse position must not move the user’s mouse pointer to the initialized position.

button, of type short, defaulting to 0 Initializes the button attribute of the MouseEvent object to a number representing the desired state of the button(s) of the mouse.

The value 0 is used to represent the primary mouse button, 1 is used to represent the auxiliary/middle mouse button, and 2 to represent the right mouse button. Numbers greater than 2 are also possible, but are not specified in this document.

buttons, of type unsigned short, defaulting to 0 Initializes the buttons attribute of the MouseEvent object to a number representing one or more of the button(s) of the mouse that are to be considered active.

The buttons attribute is a bit-field. If a mask value of 1 is true when applied to the value of the bit field, then the primary mouse button is down. If a mask value of 2 is true when applied to the value of the bit field, then the right mouse button is down. If a mask value of 4 is true when applied to the value of the bit field, then the auxiliary/middle button is down.

In JavaScript, to initialize the buttons attribute as if the right (2) and middle button (4) were being pressed simultaneously, the buttons value can be assigned as either:
  { buttons: 2 | 4 }
or:
  { buttons: 6 }

relatedTarget, of type EventTarget, nullable, defaulting to null The relatedTarget should be initialized to the element whose bounds the mouse pointer just left (in the case of a mouseover or mouseenter event) or the element whose bounds the mouse pointer is entering (in the case of a mouseout or mouseleave or focusout event). For other events, this value need not be assigned (and will default to null).

Implementations MUST maintain the current click count when generating mouse events. This MUST be a non-negative integer indicating the number of consecutive clicks of a pointing device button within a specific time. The delay after which the count resets is specific to the environment configuration.

5.3.2. Event Modifier Initializers

The MouseEvent and KeyboardEvent interfaces share a set of keyboard modifier attributes and support a mechanism for retrieving additional modifier states. The following dictionary enables authors to initialize keyboard modifier attributes of the MouseEvent and KeyboardEvent interfaces, as well as the additional modifier states queried via getModifierState(). The steps for constructing events using this dictionary are defined in the event constructors section.

dictionaryEventModifierInit : UIEventInit {
  boolean ctrlKey = false;
  boolean shiftKey = false;
  boolean altKey = false;
  boolean metaKey = false;

  boolean modifierAltGraph = false;
  boolean modifierCapsLock = false;
  boolean modifierFn = false;
  boolean modifierFnLock = false;
  boolean modifierHyper = false;
  boolean modifierNumLock = false;
  boolean modifierScrollLock = false;
  boolean modifierSuper = false;
  boolean modifierSymbol = false;
  boolean modifierSymbolLock = false;
};
ctrlKey, of type boolean, defaulting to false Initializes the ctrlKey attribute of the MouseEvent or KeyboardEvent objects to true if the Control key modifier is to be considered active, false otherwise.

When true, implementations must also initialize the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter Control must return true.

shiftKey, of type boolean, defaulting to false Initializes the shiftKey attribute of the MouseEvent or KeyboardEvent objects to true if the Shift key modifier is to be considered active, false otherwise.

When true, implementations must also initialize the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter Shift must return true.

altKey, of type boolean, defaulting to false Initializes the altKey attribute of the MouseEvent or KeyboardEvent objects to true if the Alt (alternative) (or Option) key modifier is to be considered active, false otherwise.

When true, implementations must also initialize the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter Alt must return true.

metaKey, of type boolean, defaulting to false Initializes the metaKey attribute of the MouseEvent or KeyboardEvent objects to true if the Meta key modifier is to be considered active, false otherwise.

When true, implementations must also initialize the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with either the parameter Meta must return true.

modifierAltGraph, of type boolean, defaulting to false Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter AltGraph must return true. modifierCapsLock, of type boolean, defaulting to false Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter CapsLock must return true. modifierFn, of type boolean, defaulting to false Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter Fn must return true. modifierFnLock, of type boolean, defaulting to false Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter FnLock must return true. modifierHyper, of type boolean, defaulting to false Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter Hyper must return true. modifierNumLock, of type boolean, defaulting to false Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter NumLock must return true. modifierScrollLock, of type boolean, defaulting to false Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter ScrollLock must return true. modifierSuper, of type boolean, defaulting to false Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter Super must return true. modifierSymbol, of type boolean, defaulting to false Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter Symbol must return true. modifierSymbolLock, of type boolean, defaulting to false Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter SymbolLock must return true.

5.3.3. Mouse Event Order

Certain mouse events defined in this specification MUST occur in a set order relative to one another. The following shows the event sequence that MUST occur when a pointing device’s cursor is moved over an element:

Event Type Element Notes 1 mousemove Pointing device is moved into element A... 2 mouseover A 3 mouseenter A 4 mousemove A Multiple mousemove events Pointing device is moved out of element A... 5 mouseout A 6 mouseleave A

When a pointing device is moved into an element A, and then into a nested element B and then back out again, the following sequence of events MUST occur:

Event Type Element Notes 1 mousemove Pointing device is moved into element A... 2 mouseover A 3 mouseenter A 4 mousemove A Multiple mousemove events Pointing device is moved into nested element B... 5 mouseout A 6 mouseover B 7 mouseenter B 8 mousemove B Multiple mousemove events Pointing device is moved from element B into A... 9 mouseout B 10 mouseleave B 11 mouseover A 12 mousemove A Multiple mousemove events Pointing device is moved out of element A... 13 mouseout A 14 mouseleave A

Sometimes elements can be visually overlapped using CSS. In the following example, three elements labeled A, B, and C all have the same dimensions and absolute position on a web page. Element C is a child of B, and B is a child of A in the DOM:

Graphical representation of three stacked elements all on top of each other. The bottom element is labeled A and the top element is C
Graphical representation of three stacked elements all on top of each other, with the pointing device moving over the stack.

When the pointing device is moved from outside the element stack to the element labeled C and then moved out again, the following series of events MUST occur:

Event Type Element Notes 1 mousemove Pointing device is moved into element C, the topmost element in the stack 2 mouseover C 3 mouseenter A 4 mouseenter B 5 mouseenter C 6 mousemove C Multiple mousemove events Pointing device is moved out of element C... 7 mouseout C 8 mouseleave C 9 mouseleave B 10 mouseleave A

The mouseover/mouseout events are only fired once, while mouseenter/mouseleave events are fired three times (once to each element).

The following is the typical sequence of events when a button associated with a pointing device (e.g., a mouse button or trackpad) is pressed and released over an element:

Event Type Notes 1 mousedown 2 mousemove OPTIONAL, multiple events, some limits 3 mouseup 4 click 5 mousemove OPTIONAL, multiple events, some limits 6 mousedown 7 mousemove OPTIONAL, multiple events, some limits 8 mouseup 9 click 10 dblclick

The lag time, degree, distance, and number of mousemove events allowed between the mousedown and mouseup events while still firing a click or dblclick event will be implementation-, device-, and platform-specific. This tolerance can aid users that have physical disabilities like unsteady hands when these users interact with a pointing device.

Each implementation will determine the appropriate hysteresis tolerance, but in general SHOULD fire click and dblclick events when the event target of the associated mousedown and mouseup events is the same element with no mouseout or mouseleave events intervening, and SHOULD fire click and dblclick events on the nearest common inclusive ancestor when the associated mousedown and mouseup event targets are different.

If a mousedown event was targeted at an HTML document’s body element, and the corresponding mouseup event was targeted at the root element, then the click event will be dispatched to the root element, since it is the nearest common inclusive ancestor.

If the event target (e.g. the target element) is removed from the DOM during the mouse events sequence, the remaining events of the sequence MUST NOT be fired on that element.

If the target element is removed from the DOM as the result of a mousedown event, no events for that element will be dispatched for mouseup, click, or dblclick, nor any default activation events. However, the mouseup event will still be dispatched on the element that is exposed to the mouse after the removal of the initial target element. Similarly, if the target element is removed from the DOM during the dispatch of a mouseup event, the click and subsequent events will not be dispatched.

5.3.4. Mouse Event Types

The Mouse event types are listed below. In the case of nested elements, mouse event types are always targeted at the most deeply nested element. Ancestors of the targeted element MAY use bubbling to obtain notification of mouse events which occur within its descendent elements.

5.3.4.1. auxclick
Type auxclick Interface PointerEvent Sync / Async Sync Bubbles Yes Trusted Targets Element Cancelable Yes Composed Yes Default action Varies Context
(trusted events)

The auxclick event type MUST be dispatched on the topmost event target indicated by the pointer, when the user presses down and releases the non-primary pointer button, or otherwise activates the pointer in a manner that simulates such an action. The actuation method of the mouse button depends upon the pointer device and the environment configuration, e.g., it MAY depend on the screen location or the delay between the press and release of the pointing device button.

The auxclick event should only be fired for the non-primary pointer buttons (i.e., when button value is not 0, buttons value is greater than 1). The primary button (like the left button on a standard mouse) MUST NOT fire auxclick events. See click for a corresponding event that is associated with the primary button.

The auxclick event MAY be preceded by the mousedown and mouseup events on the same element, disregarding changes between other node types (e.g., text nodes). Depending upon the environment configuration, the auxclick event MAY be dispatched if one or more of the event types mouseover, mousemove, and mouseout occur between the press and release of the pointing device button.

The default action of the auxclick event type varies based on the event target of the event and the value of the button or buttons attributes. Typical default actions of the auxclick event type are as follows:

Receiving and handling auxclick for the middle button.
myLink.addEventListener("auxclick", function(e) { if (e.button === 1) { // This would prevent the default behavior which is for example // opening a new tab when middle clicking on a link. e.preventDefault(); // Do something else to handle middle button click like taking // care of opening link or non-link buttons in new tabs in a way // that fits the app. Other actions like closing a tab in a tab-strip // which should be done on the click action can be done here too. } });

In the case of right button, the auxclick event is dispatched after any contextmenu event. Note that some user agents swallow all input events while a context menu is being displayed, so auxclick may not be available to applications in such scenarios. See this example for more clarification.

Receiving and handling auxlick for the right button
myDiv.addEventListener("contextmenu", function(e) { // This call makes sure no context menu is shown // to interfere with page receiving the events. e.preventDefault(); }); myDiv.addEventListener("auxclick", function(e) { if (e.button === 2) { // Do something else to handle right button click like opening a // customized context menu inside the app. } });

5.3.4.2. click
Type click Interface PointerEvent Sync / Async Sync Bubbles Yes Trusted Targets Element Cancelable Yes Composed Yes Default action Varies Context
(trusted events)

The click event type MUST be dispatched on the topmost event target indicated by the pointer, when the user presses down and releases the primary pointer button, or otherwise activates the pointer in a manner that simulates such an action. The actuation method of the mouse button depends upon the pointer device and the environment configuration, e.g., it MAY depend on the screen location or the delay between the press and release of the pointing device button.

The click event should only be fired for the primary pointer button (i.e., when button value is 0, buttons value is 1). Secondary buttons (like the middle or right button on a standard mouse) MUST NOT fire click events. See auxclick for a corresponding event that is associated with the non-primary buttons.

The click event MAY be preceded by the mousedown and mouseup events on the same element, disregarding changes between other node types (e.g., text nodes). Depending upon the environment configuration, the click event MAY be dispatched if one or more of the event types mouseover, mousemove, and mouseout occur between the press and release of the pointing device button. The click event MAY also be followed by the dblclick event.

If a user mouses down on a text node child of a <p> element which has been styled with a large line-height, shifts the mouse slightly such that it is no longer over an area containing text but is still within the containing block of that <p> element (i.e., the pointer is between lines of the same text block, but not over the text node per se), then subsequently mouses up, this will likely still trigger a click event (if it falls within the normal temporal hysteresis for a click), since the user has stayed within the scope of the same element. Note that user-agent-generated mouse events are not dispatched on text nodes.

In addition to being associated with pointer devices, the click event type MUST be dispatched as part of an element activation, as described in § 3.5 Activation triggers and behavior.

For maximum accessibility, content authors are encouraged to use the click event type when defining activation behavior for custom controls, rather than other pointing-device event types such as mousedown or mouseup, which are more device-specific. Though the click event type has its origins in pointer devices (e.g., a mouse), subsequent implementation enhancements have extended it beyond that association, and it can be considered a device-independent event type for element activation.

The default action of the click event type varies based on the event target of the event and the value of the button or buttons attributes. Typical default actions of the click event type are as follows:

5.3.4.3. dblclick
Type dblclick Interface MouseEvent Sync / Async Sync Bubbles Yes Trusted Targets Element Cancelable Yes Composed Yes Default action None Context
(trusted events)

A user agent MUST dispatch this event when the primary button of a pointing device is clicked twice over an element. The definition of a double click depends on the environment configuration, except that the event target MUST be the same between mousedown, mouseup, and dblclick. This event type MUST be dispatched after the event type click if a click and double click occur simultaneously, and after the event type mouseup otherwise.

As with the click event, the dblclick event should only be fired for the primary pointer button. Secondary buttons MUST NOT fire dblclick events.

Canceling the click event does not affect the firing of a dblclick event.

As with the click event type, the default action of the dblclick event type varies based on the event target of the event and the value of the button or buttons attributes. Normally, the typical default actions of the dblclick event type match those of the click event type, with the following additional behavior:

  • If the event target is selectable, the default action MUST be to select part or all of the selectable content. Subsequent clicks MAY select additional selectable portions of that content.

5.3.4.4. mousedown
Type mousedown Interface MouseEvent Sync / Async Sync Bubbles Yes Trusted Targets Element Cancelable Yes Composed Yes Default action Varies: Start a drag/drop operation; start a text selection; start a scroll/pan interaction (in combination with the middle mouse button, if supported) Context
(trusted events)

A user agent MUST dispatch this event when a pointing device button is pressed over an element.

Many implementations use the mousedown event to begin a variety of contextually dependent default actions. These default actions can be prevented if this event is canceled. Some of these default actions could include: beginning a drag/drop interaction with an image or link, starting text selection, etc. Additionally, some implementations provide a mouse-driven panning feature that is activated when the middle mouse button is pressed at the time the mousedown event is dispatched.

5.3.4.5. mouseenter
Type mouseenter Interface MouseEvent Sync / Async Sync Bubbles No Trusted Targets Element Cancelable No Composed No Default action None Context
(trusted events)

A user agent MUST dispatch this event when a pointing device is moved onto the boundaries of an element or one of its descendent elements. A user agent MUST also dispatch this event when the element or one of its descendants moves to be underneath the primary pointing device. This event type is similar to mouseover, but differs in that it does not bubble, and MUST NOT be dispatched when the pointer device moves from an element onto the boundaries of one of its descendent elements.

There are similarities between this event type and the CSS :hover pseudo-class [CSS2]. See also the mouseleave event type.

5.3.4.6. mouseleave
Type mouseleave Interface MouseEvent Sync / Async Sync Bubbles No Trusted Targets Element Cancelable No Composed No Default action None Context
(trusted events)

A user agent MUST dispatch this event when a pointing device is moved off of the boundaries of an element and all of its descendent elements. A user agent MUST also dispatch this event when the element or one of its descendants moves to be no longer underneath the primary pointing device. This event type is similar to mouseout, but differs in that does not bubble, and that it MUST NOT be dispatched until the pointing device has left the boundaries of the element and the boundaries of all of its children.

There are similarities between this event type and the CSS :hover pseudo-class [CSS2]. See also the mouseenter event type.

5.3.4.7. mousemove
Type mousemove Interface MouseEvent Sync / Async Sync Bubbles Yes Trusted Targets Element Cancelable Yes Composed Yes Default action None Context
(trusted events)

A user agent MUST dispatch this event when a pointing device is moved while it is over an element. The frequency rate of events while the pointing device is moved is implementation-, device-, and platform-specific, but multiple consecutive mousemove events SHOULD be fired for sustained pointer-device movement, rather than a single event for each instance of mouse movement. Implementations are encouraged to determine the optimal frequency rate to balance responsiveness with performance.

In some implementation environments, such as a browser, mousemove events can continue to fire if the user began a drag operation (e.g., a mouse button is pressed) and the pointing device has left the boundary of the user agent.

This event was formerly specified to be non-cancelable in DOM Level 2 Events [DOM-Level-2-Events], but was changed to reflect existing interoperability between user agents.

5.3.4.8. mouseout
Type mouseout Interface MouseEvent Sync / Async Sync Bubbles Yes Trusted Targets Element Cancelable Yes Composed Yes Default action None Context
(trusted events)

A user agent MUST dispatch this event when a pointing device is moved off of the boundaries of an element or when the element is moved to be no longer underneath the primary pointing device. This event type is similar to mouseleave, but differs in that does bubble, and that it MUST be dispatched when the pointer device moves from an element onto the boundaries of one of its descendent elements.

See also the mouseover event type.

5.3.4.9. mouseover
Type mouseover Interface MouseEvent Sync / Async Sync Bubbles Yes Trusted Targets Element Cancelable Yes Composed Yes Default action None Context
(trusted events)

A user agent MUST dispatch this event when a pointing device is moved onto the boundaries of an element or when the element is moved to be underneath the primary pointing device. This event type is similar to mouseenter, but differs in that it bubbles, and that it MUST be dispatched when the pointer device moves onto the boundaries of an element whose ancestor element is the event target for the same event listener instance.

See also the mouseout event type.

5.3.4.10. mouseup
Type mouseup Interface MouseEvent Sync / Async Sync Bubbles Yes Trusted Targets Element Cancelable Yes Composed Yes Default action Invoke a context menu (in combination with the right mouse button, if supported) Context
(trusted events)

A user agent MUST dispatch this event when a pointing device button is released over an element.

Many implementations will invoke a context menu as the default action of this event if the right mouse button is being released.

In some implementation environments, such as a browser, a mouseup event can be dispatched even if the pointing device has left the boundary of the user agent, e.g., if the user began a drag operation with a mouse button pressed.

5.4. Wheel Events

Wheels are devices that can be rotated in one or more spatial dimensions, and which can be associated with a pointer device. The coordinate system depends on the environment configuration.

The user’s environment might be configured to associate vertical scrolling with rotation along the y-axis, horizontal scrolling with rotation along the x-axis, and zooming with rotation along the z-axis.

The deltaX, deltaY, and deltaZ attributes of WheelEvent objects indicate a measurement along their respective axes in units of pixels, lines, or pages. The reported measurements are provided after an environment-specific algorithm translates the actual rotation/movement of the wheel device into the appropriate values and units.

A user’s environment settings can be customized to interpret actual rotation/movement of a wheel device in different ways. One movement of a common dented mouse wheel can produce a measurement of 162 pixels (162 is just an example value, actual values can depend on the current screen dimensions of the user-agent). But a user can change their default environment settings to speed-up their mouse wheel, increasing this number. Furthermore, some mouse wheel software can support acceleration (the faster the wheel is rotated/moved, the greater the delta of each measurement) or even sub-pixel rotation measurements. Because of this, authors can not assume a given rotation amount in one user agent will produce the same delta value in all user agents.

The sign (positive or negative) of the values of the deltaX, deltaY, and deltaZ attributes MUST be consistent between multiple dispatches of the wheel event while the motion of the actual wheel device is rotating/moving in the same direction. If a user agent scrolls as the default action of the wheel event then the sign of the delta SHOULD be 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.

Individual user agents can (depending on their environment and hardware configuration) interpret the same physical user interaction on the wheel differently. For example, a vertical swipe on the edge of a trackpad from top to bottom can be interpreted as a wheel action intended to either scroll the page down or to pan the page up (i.e., resulting in either a positive or negative deltaY value respectively).

5.4.1. Interface WheelEvent

Introduced in this specification

The WheelEvent interface provides specific contextual information associated with wheel events.

To create an instance of the WheelEvent interface, use the WheelEvent constructor, passing an optional WheelEventInit dictionary.

5.4.1.1. WheelEvent
[Exposed=Window]
interfaceWheelEvent : MouseEvent {
  constructor(DOMString type, optionalWheelEventInit eventInitDict);
  // DeltaModeCode
  constunsignedlong DOM_DELTA_PIXEL = 0x00;
  constunsignedlong DOM_DELTA_LINE  = 0x01;
  constunsignedlong DOM_DELTA_PAGE  = 0x02;

  readonlyattributedouble deltaX;
  readonlyattributedouble deltaY;
  readonlyattributedouble deltaZ;
  readonlyattributeunsignedlong deltaMode;
};
DOM_DELTA_PIXEL The units of measurement for the delta MUST be pixels. This is the most typical case in most operating system and implementation configurations. DOM_DELTA_LINE The units of measurement for the delta MUST be individual lines of text. This is the case for many form controls. DOM_DELTA_PAGE The units of measurement for the delta MUST be pages, either defined as a single screen or as a demarcated page. deltaX, of type double, readonly In user agents where the default action of the wheel event is to scroll, the value MUST be the measurement along the x-axis (in pixels, lines, or pages) to be scrolled in the case where the event is not cancelled. Otherwise, this is an implementation-specific measurement (in pixels, lines, or pages) of the movement of a wheel device around the x-axis.

The un-initialized value of this attribute MUST be 0.0.

deltaY, of type double, readonly In user agents where the default action of the wheel event is to scroll, the value MUST be the measurement along the y-axis (in pixels, lines, or pages) to be scrolled in the case where the event is not cancelled. Otherwise, this is an implementation-specific measurement (in pixels, lines, or pages) of the movement of a wheel device around the y-axis.

The un-initialized value of this attribute MUST be 0.0.

deltaZ, of type double, readonly In user agents where the default action of the wheel event is to scroll, the value MUST be the measurement along the z-axis (in pixels, lines, or pages) to be scrolled in the case where the event is not cancelled. Otherwise, this is an implementation-specific measurement (in pixels, lines, or pages) of the movement of a wheel device around the z-axis.

The un-initialized value of this attribute MUST be 0.0.

deltaMode, of type unsigned long, readonly The deltaMode attribute contains an indication of the units of measurement for the delta values. The default value is DOM_DELTA_PIXEL (pixels).

This attribute MUST be set to one of the DOM_DELTA constants to indicate the units of measurement for the delta values. The precise measurement is specific to device, operating system, and application configurations.

The un-initialized value of this attribute MUST be 0.

5.4.1.2. WheelEventInit
dictionaryWheelEventInit : MouseEventInit {
  double deltaX = 0.0;
  double deltaY = 0.0;
  double deltaZ = 0.0;
  unsignedlong deltaMode = 0;
};
deltaX, of type double, defaulting to 0.0 See deltaZ attribute. deltaY, of type double, defaulting to 0.0 See deltaZ attribute. deltaZ, of type double, defaulting to 0.0 Initializes the deltaZ attribute of the WheelEvent object. Relative positive values for this attribute (as well as the deltaX and deltaY attributes) are given by a right-hand coordinate system where the 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. Negative relative values are in the respective opposite directions. deltaMode, of type unsigned long, defaulting to 0 Initializes the deltaMode attribute on the WheelEvent object to the enumerated values 0, 1, or 2, which represent the amount of pixels scrolled (DOM_DELTA_PIXEL), lines scrolled (DOM_DELTA_LINE), or pages scrolled (DOM_DELTA_PAGE) if the rotation of the wheel would have resulted in scrolling.

5.4.2. Wheel Event Types

5.4.2.1. wheel
Type wheel Interface WheelEvent Sync / Async Async Bubbles Yes Trusted Targets Element Cancelable Varies Composed Yes Default action Scroll (or zoom) the document Context
(trusted events)
  • Event.target : topmost event target
  • UIEvent.view : Window
  • UIEvent.detail : 0
  • MouseEvent.screenX : if the wheel is associated with a pointing device, the value based on the pointer position on the screen, otherwise 0
  • MouseEvent.screenY : if the wheel is associated with a pointing device, the value based on the pointer position on the screen, otherwise 0
  • MouseEvent.clientX : if the wheel is associated with a pointing device, the value based on the pointer position within the viewport, otherwise 0
  • MouseEvent.clientY : if the wheel is associated with a pointing device, the value based on the pointer position within the viewport, otherwise 0
  • MouseEvent.altKey : true if Alt modifier was active, otherwise false
  • MouseEvent.ctrlKey : true if Control modifier was active, otherwise false
  • MouseEvent.shiftKey : true if Shift modifier was active, otherwise false
  • MouseEvent.metaKey : true if Meta modifier was active, otherwise false
  • MouseEvent.button : if wheel is associated with a pointing device, value based on current button pressed, otherwise 0
  • MouseEvent.buttons : if wheel is associated with a pointing device, value based on all buttons current depressed, 0 if no buttons pressed
  • MouseEvent.relatedTarget : indicates the event target the pointing device is pointing at, if any
  • WheelEvent.deltaX : expected amount that the page will scroll along the x-axis according to the deltaMode units; or an implemenation-specific value of movement of a wheel around the x-axis
  • WheelEvent.deltaY : expected amount that the page will scroll along the y-axis according to the deltaMode units; or an implemenation-specific value of movement of a wheel around the y-axis
  • WheelEvent.deltaZ : expected amount that the page will scroll along the z-axis according to the deltaMode units; or an implemenation-specific value of movement of a wheel around the z-axis
  • WheelEvent.deltaMode : unit indicator (pixels, lines, or pages) for the deltaX, deltaY, and deltaZ attributes

A user agent MUST dispatch this event when a mouse wheel has been rotated around any axis, or when an equivalent input device (such as a mouse-ball, certain tablets or touchpads, etc.) has emulated such an action. Depending on the platform and input device, diagonal wheel deltas MAY be delivered either as a single wheel event with multiple non-zero axes or as separate wheel events for each non-zero axis.

The typical default action of the wheel event type is to scroll (or in some cases, zoom) the document by the indicated amount. If this event is canceled, the implementation MUST NOT scroll or zoom the document (or perform whatever other implementation-specific default action is associated with this event type).

In some user agents, or with some input devices, the speed that the wheel has been turned can affect the delta values, with a faster speed producing a higher delta value.

5.4.2.2. cancelability of wheel events

Calling preventDefault on a wheel event can prevent or otherwise interrupt scrolling. For maximum scroll performance, a user agent may not wait for each wheel event associated with the scroll to be processed to see if it will be canceled. In such cases it is possible that only the first wheel event of a scrolling sequence is cancelable. For the rest of the wheel events the user agent should set their cancelable property to false.

5.5. Input Events

Input events are sent as notifications whenever the DOM is being updated (or about to be updated) as a direct result of a user action (e.g., keyboard input in an editable region, deleting or formatting text, ...).

5.5.1. Interface InputEvent

5.5.1.1. InputEvent

Introduced in DOM Level 3

[Exposed=Window]
interfaceInputEvent : UIEvent {
  constructor(DOMString type, optionalInputEventInit eventInitDict);
  readonlyattributeDOMString? data;
  readonlyattributeboolean isComposing;
  readonlyattributeDOMString inputType;
};
data, of type DOMString, readonly, nullable 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 [UAX15]. This attribute MAY contain the empty string.

The un-initialized value of this attribute MUST be null.

isComposing, of type boolean, readonly true if the input event occurs as part of a composition session, i.e., after a compositionstart event and before the corresponding compositionend event.

The un-initialized value of this attribute MUST be false.

inputType, of type DOMString, readonly inputType contains a string that identifies the type of input associated with the event.

For a list of valid values for this attribute, refer to the [Input-Events] specification.

The un-initialized value of this attribute MUST be the empty string "".

5.5.1.2. InputEventInit
dictionaryInputEventInit : UIEventInit {
  DOMString? data = "";
  boolean isComposing = false;
  DOMString inputType = "";
};
data, of type DOMString, nullable, defaulting to "" Initializes the data attribute of the InputEvent object. isComposing, of type boolean, defaulting to false Initializes the isComposing attribute of the InputEvent object. inputType, of type DOMString, defaulting to "" Initializes the inputType attribute of the InputEvent object.

5.5.2. Input Event Order

The input events defined in this specification MUST occur in a set order relative to one another.

Event Type Notes 1 beforeinput DOM element is updated 2 input

5.5.3. Input Event Types

5.5.3.1. beforeinput
Type beforeinput Interface InputEvent Sync / Async Sync Bubbles Yes Trusted Targets Element (specifically: control types such as HTMLInputElement, etc.) or any Element with contenteditable attribute enabled Cancelable Yes Composed Yes Default action Update the DOM element Context
(trusted events)

A user agent MUST dispatch this event when the DOM is about to be updated.

5.5.3.2. input
Type input Interface InputEvent Sync / Async Sync Bubbles Yes Trusted Targets Element (specifically: control types such as HTMLInputElement, etc.) or any Element with contenteditable attribute enabled Cancelable No Composed Yes Default action None Context
(trusted events)

A user agent MUST dispatch this event immediately after the DOM has been updated.

5.6. Keyboard Events

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. 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 might not be generated.

Keyboard events are only one modality of providing textual input. For editing scenarios, consider also using the InputEvent as an alternate to (or in addition to) keyboard events.

5.6.1. Interface KeyboardEvent

Introduced in this specification

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: ctrlKey, shiftKey, altKey, metaKey. These attributes are equivalent to using the method getModifierState() with Control, Shift, Alt, or Meta respectively.

To create an instance of the KeyboardEvent interface, use the KeyboardEvent constructor, passing an optional KeyboardEventInit dictionary.

5.6.1.1. KeyboardEvent
[Exposed=Window]
interfaceKeyboardEvent : UIEvent {
  constructor(DOMString type, optionalKeyboardEventInit eventInitDict);
  // KeyLocationCode
  constunsignedlong DOM_KEY_LOCATION_STANDARD = 0x00;
  constunsignedlong DOM_KEY_LOCATION_LEFT = 0x01;
  constunsignedlong DOM_KEY_LOCATION_RIGHT = 0x02;
  constunsignedlong DOM_KEY_LOCATION_NUMPAD = 0x03;

  readonlyattributeDOMString key;
  readonlyattributeDOMString code;
  readonlyattributeunsignedlong location;

  readonlyattributeboolean ctrlKey;
  readonlyattributeboolean shiftKey;
  readonlyattributeboolean altKey;
  readonlyattributeboolean metaKey;

  readonlyattributeboolean repeat;
  readonlyattributeboolean isComposing;

  boolean getModifierState(DOMString keyArg);
};
DOM_KEY_LOCATION_STANDARD The key activation MUST NOT be distinguished as the left or right version of the key, and (other than the NumLock key) did not originate from the numeric keypad (or did not originate with a virtual key corresponding to the numeric keypad).

The Q key on a PC 101 Key US keyboard.
The NumLock key on a PC 101 Key US keyboard.
The 1 key on a PC 101 Key US keyboard located in the main section of the keyboard.

DOM_KEY_LOCATION_LEFT The key activated originated from the left key location (when there is more than one possible location for this key).

The left Control key on a PC 101 Key US keyboard.

DOM_KEY_LOCATION_RIGHT The key activation originated from the right key location (when there is more than one possible location for this key).

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 (when there is more than one possible location for this key). Note that the NumLock key should always be encoded with a location of DOM_KEY_LOCATION_STANDARD.

The 1 key on a PC 101 Key US keyboard located on the numeric pad.

key, of type DOMString, readonly key holds a key attribute value corresponding to the key pressed.

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

The un-initialized value of this attribute MUST be "" (the empty string).

code, of type DOMString, readonly code holds a string that identifies the physical key being pressed. The value is not affected by the current keyboard layout or modifier state, so a particular key will always return the same value.

The un-initialized value of this attribute MUST be "" (the empty string).

location, of type unsigned long, readonly The location attribute contains an indication of the logical location of the key on the device.

This attribute MUST be set to one of the DOM_KEY_LOCATION constants to indicate the location of a key on the device.

If a user agent allows keys to be remapped, then the location value for a remapped key MUST be set to a value which is appropriate for the new key. For example, if the "ControlLeft" key is mapped to the "KeyQ" key, then the location attribute MUST be set to DOM_KEY_LOCATION_STANDARD. Conversely, if the "KeyQ" key is remapped to one of the Control keys, then the location attribute MUST be set to either DOM_KEY_LOCATION_LEFT or DOM_KEY_LOCATION_RIGHT.

The un-initialized value of this attribute MUST be 0.

ctrlKey, of type boolean, readonly true if the Control (control) key modifier was active.

The un-initialized value of this attribute MUST be false.

shiftKey, of type boolean, readonly true if the shift (Shift) key modifier was active.

The un-initialized value of this attribute MUST be false.

altKey, of type boolean, readonly true if the Alt (alternative) (or "Option") key modifier was active.

The un-initialized value of this attribute MUST be false.

metaKey, of type boolean, readonly true if the meta (Meta) key modifier was active.

The "Command" ("⌘") key modifier on Macintosh systems is represented using this key modifier.

The un-initialized value of this attribute MUST be false.

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, beforeinput, 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.

The un-initialized value of this attribute MUST be false.

isComposing, of type boolean, readonly true if the key event occurs as part of a composition session, i.e., after a compositionstart event and before the corresponding compositionend event.

The un-initialized value of this attribute MUST be false.

getModifierState(keyArg) Queries the state of a modifier using a key value.

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

DOMString keyArg A modifier key value. Valid modifier keys are defined in the Modifier Keys table in [UIEvents-Key].

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

5.6.1.2. KeyboardEventInit
dictionaryKeyboardEventInit : EventModifierInit {
  DOMString key = "";
  DOMString code = "";
  unsignedlong location = 0;
  boolean repeat = false;
  boolean isComposing = false;
};
key, of type DOMString, defaulting to "" Initializes the key attribute of the KeyboardEvent object to the unicode character string representing the meaning of a key after taking into account all keyboard modifiers (such as shift-state). This value is the final effective value of the key. If the key is not a printable character, then it should be one of the key values defined in [UIEvents-Key]. code, of type DOMString, defaulting to "" Initializes the code attribute of the KeyboardEvent object to the unicode character string representing the key that was pressed, ignoring any keyboard modifications such as keyboard layout. This value should be one of the code values defined in [UIEvents-Code]. location, of type unsigned long, defaulting to 0 Initializes the location attribute of the KeyboardEvent object to one of the following location numerical constants: repeat, of type boolean, defaulting to false Initializes the repeat attribute of the KeyboardEvent object. This attribute should be set to true if the the current KeyboardEvent is considered part of a repeating sequence of similar events caused by the long depression of any single key, false otherwise. isComposing, of type boolean, defaulting to false Initializes the isComposing attribute of the KeyboardEvent object. This attribute should be set to true if the event being constructed occurs as part of a composition sequence, false otherwise.
Legacy keyboard event implementations 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 might 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. This specification does not define values for either keyCode or charCode, or behavior for charCode. In conforming UI Events implementations, content authors can instead use key and code.

For more information, see the informative appendix on Legacy key attributes.

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

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

5.6.2. Keyboard Event Key Location

The location attribute can be used to disambiguate between key values that can be generated by different physical keys on the keyboard, for example, the left and right Shift key or the physical arrow keys vs. the numpad arrow keys (when NumLock is off).

The following table defines the valid location values for the special keys that have more than one location on the keyboard:

For all other keys not listed in this table, the location attribute MUST always be set to DOM_KEY_LOCATION_STANDARD.

5.6.3. Keyboard Event Order

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

Event Type Notes 1 keydown 2 beforeinput (only for keys which produce a character value) Any default actions related to this key, such as inserting a character in to the DOM. 3 input (only for keys which have updated the DOM) Any events as a result of the key being held for a sustained period (see below). 4 keyup

If the key is depressed for a sustained period, the following events MAY repeat at an environment-dependent rate:

Event Type Notes 1 keydown (with repeat attribute set to true) 2 beforeinput (only for keys which produce a character value) Any default actions related to this key, such as inserting a character in to the DOM. 3 input (only for keys which have updated the DOM)

Typically, any default actions associated with any particular key are completed before the keyup event is dispatched. This might delay the keyup event slightly (though this is not likely to be a perceptible delay).

The event 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 an accelerator key or trigger of some other behavior. If no suitable element is in focus, the event target will be the HTML body element if available, otherwise the root element.

The event target might change between different key events. For example, a keydown event for the Tab key will likely have a different event target than the keyup event on the same keystroke.

5.6.4. Keyboard Event Types

5.6.4.1. keydown
Type keydown Interface KeyboardEvent Sync / Async Sync Bubbles Yes Trusted Targets Element Cancelable Yes Composed Yes Default action Varies: beforeinput and input events; launch text composition system; blur and focus events; keypress event (if supported); activation behavior; other event Context
(trusted events)

A user agent MUST dispatch this event when a key is pressed down. The keydown event type is device dependent and relies on the capabilities of the input devices and how they are mapped in the operating system. This event type MUST be generated after the key mapping. This event type MUST be dispatched before the beforeinput, input, and keyup events associated with the same key.

The default action of the keydown event depends upon the key:

  • If the key is associated with a character, the default action MUST be to dispatch a beforeinput event followed by an input event. In the case where the key which is associated with multiple characters (such as with a macro or certain sequences of dead keys), the default action MUST be to dispatch one set of beforeinput / input events for each character

  • If the key is associated with a text composition system, the default action MUST be to launch that system

  • If the key is the Tab key, the default action MUST be to shift the document focus from the currently focused element (if any) to the new focused element, as described in Focus Event Types

  • If the key is the Enter or key and the current focus is on a state-changing element, the default action MUST be to dispatch a click event, and a DOMActivate event if that event type is supported by the user agent (refer to § 3.5 Activation triggers and behavior for more details)

If this event is canceled, the associated event types MUST NOT be dispatched, and the associated actions MUST NOT be performed.

The keydown and keyup events are traditionally associated with detecting any key, not just those which produce a character value.

5.6.4.2. keyup
Type keyup Interface KeyboardEvent Sync / Async Sync Bubbles Yes Trusted Targets Element Cancelable Yes Composed Yes Default action None Context
(trusted events)

A user agent MUST dispatch this event when a key is released. The keyup event type is device dependent and relies on the capabilities of the input devices and how they are mapped in the operating system. This event type MUST be generated after the key mapping. This event type MUST be dispatched after the keydown, beforeinput, and input events associated with the same key.

The keydown and keyup events are traditionally associated with detecting any key, not just those which produce a character value.

5.7. Composition Events

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 might 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 § 6 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.

Note: While a composition session is active, keyboard events can be dispatched to the DOM if the keyboard is the input device used with the composition session. See the compositionstart event details and IME section for relevent event ordering.

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) might not be available through this interface, in which case the selection MAY be represented by the empty string.

5.7.1. Interface CompositionEvent

Introduced in this specification

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

To create an instance of the CompositionEvent interface, use the CompositionEvent constructor, passing an optional CompositionEventInit dictionary.

5.7.1.1. CompositionEvent
[Exposed=Window]
interfaceCompositionEvent : UIEvent {
  constructor(DOMString type, optionalCompositionEventInit eventInitDict);
  readonlyattributeDOMString data;
};
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 [UAX15]. This attribute MAY be the empty string.

The un-initialized value of this attribute MUST be "" (the empty string).

5.7.1.2. CompositionEventInit
dictionaryCompositionEventInit : UIEventInit {
  DOMString data = "";
};
data, of type DOMString, defaulting to "" Initializes the data attribute of the CompositionEvent object to the characters generated by the IME composition.

5.7.2. Composition Event Order

The Composition Events defined in this specification MUST occur in the following set order relative to one another:

5.7.3. Handwriting Recognition Systems

The following example describes a possible sequence of events when composing a text passage text with a handwriting recognition system, such as on a pen tablet, as modeled using Composition Events.

Event Type CompositionEvent
data Notes 1 compositionstart "" User writes word on tablet surface 2 compositionupdate "test" User rejects first word-match suggestion, selects different match 3 compositionupdate "text" 4 compositionend "text"

5.7.4. Canceling Composition Events

If a keydown event is canceled then any Composition Events that would have fired as a result of that keydown SHOULD not be dispatched:

Event Type Notes 1 keydown The default action is prevented, e.g., by invoking preventDefault(). No Composition Events are dispatched 2 keyup

If the initial compositionstart event is canceled then the text composition session SHOULD be terminated. Regardless of whether or not the composition session is terminated, the compositionend event MUST be sent.

Event Type Notes 1 keydown 2 compositionstart The default action is prevented, e.g., by invoking preventDefault(). No Composition Events are dispatched 3 compositionend 4 keyup

5.7.5. Key Events During Composition

During the composition session, keydown and keyup events MUST still be sent, and these events MUST have the isComposing attribute set to true.

Event Type KeyboardEvent
isComposing Notes 1 keydown false This is the key event that initiates the composition. 2 compositionstart 3 compositionupdate 4 keyup true ... Any key events sent during the composition session MUST have isComposing set to true. 5 keydown true This is the key event that exits the composition. 6 compositionend 7 keyup false

5.7.6. Input Events During Composition

During the composition session, the compositionupdate MUST be dispatched after the beforeinput is sent, but before the input event is sent.

Event Type Notes 1 beforeinput 2 compositionupdate Any DOM updates occur at this point. 3 input

Most IMEs do not support canceling updates during a composition session.

The beforeinput and input events are sent along with the compositionupdate event whenever the DOM is updated as part of the composition. Since there are no DOM updates associated with the compositionend event, beforeinput and input events should not be sent at that time.

Event Type Notes 1 beforeinput Canceling this will prevent the DOM update and the input event. 2 compositionupdate Any DOM updates occur at this point. 3 input Sent only if the DOM was updated. 4 compositionend

5.7.7. Composition Event Types

5.7.7.1. compositionstart
Type compositionstart Interface CompositionEvent Sync / Async Sync Bubbles Yes Trusted Targets Element Cancelable Yes Composed Yes Default action Start a new composition session when a text composition system is enabled Context
(trusted events)

A user agent MUST dispatch this event when a text composition system is enabled and a new composition session is about to begin (or has begun, depending on the text composition system) in preparation for composing a passage of text. This event type is device-dependent, and MAY rely upon the capabilities of the text conversion system and how it is mapped into the operating system. When a keyboard is used to feed an input method editor, this event type is generated after a keydown event, but speech or handwriting recognition systems MAY send this event type without keyboard events. Some implementations MAY populate the data attribute of the compositionstart event with the text currently selected in the document (for editing and replacement). Otherwise, the value of the data attribute MUST be the empty string.

This event MUST be dispatched immediately before a text composition system begins a new composition session, and before the DOM is modified due to the composition process. The default action of this event is for the text composition system to start a new composition session. If this event is canceled, the text composition system SHOULD discard the current composition session.

Canceling the compositionstart event type is distinct from canceling the text composition system itself (e.g., by hitting a cancel button or closing an IME window).

Some IMEs do not support cancelling an in-progress composition session (e.g., such as GTK which doesn’t presently have such an API). In these cases, calling preventDefault() will not stop this event’s default action.

5.7.7.2. compositionupdate
Type compositionupdate Interface CompositionEvent Sync / Async Sync Bubbles Yes Trusted Targets Element Cancelable No Composed Yes Default action None Context
(trusted events)

A user agent SHOULD dispatch this event during a composition session when a text composition system updates its active text passage with a new character, which is reflected in the string in data.

In text composition systems which keep the ongoing composition in sync with the input control, the compositionupdate event MUST be dispatched before the control is updated.

Some text composition systems might not expose this information to the DOM, in which case this event will not fire during the composition process.

If the composition session is canceled, this event will be fired immediately before the compositionend event, and the data attribute will be set to the empty string.

5.7.7.3. compositionend
Type compositionend Interface CompositionEvent Sync / Async Sync Bubbles Yes Trusted Targets Element Cancelable No Composed Yes Default action None Context
(trusted events)

A user agent MUST dispatch this event when a text composition system completes or cancels the current composition session, and the compositionend event MUST be dispatched after the control is updated.

This event is dispatched immediately after the text composition system completes the composition session (e.g., the IME is closed, minimized, switched out of focus, or otherwise dismissed, and the focus switched back to the user agent).


report

Recommend

About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK