From d2516f1e9c9430ad69672d0dae2652d75f88b19e Mon Sep 17 00:00:00 2001 From: Mason Freed Date: Fri, 6 Sep 2024 09:49:45 -0700 Subject: [PATCH 1/7] Remove the rest except TR.html --- fixup-static-export.py | 4 - fixup.js | 4 - images/event-inheritance.svg | 2 +- index-snapshot.html | 827 +------------------------ sections/legacy-event-initializers.txt | 4 +- sections/legacy-event-types.txt | 751 ---------------------- split/composition-events.bs | 4 +- split/composition-events.html | 6 +- split/composition-events.txt | 4 +- split/keyboard-events.bs | 4 +- split/keyboard-events.html | 6 +- split/keyboard-events.txt | 4 +- split/mouse-events.bs | 4 +- split/mouse-events.html | 6 +- split/mouse-events.txt | 16 +- split/ui-events.html | 6 +- split/ui-events.txt | 744 +--------------------- 17 files changed, 45 insertions(+), 2351 deletions(-) diff --git a/fixup-static-export.py b/fixup-static-export.py index a359650b..ff778018 100644 --- a/fixup-static-export.py +++ b/fixup-static-export.py @@ -51,9 +51,6 @@ def strip(line): ['KeyboardEvent-', 'DOM_KEY_LOCATION_LEFT"'], ['KeyboardEvent-', 'DOM_KEY_LOCATION_RIGHT"'], ['KeyboardEvent-', 'DOM_KEY_LOCATION_NUMPAD"'], - ['MutationEvent-', 'MODIFICATION"'], - ['MutationEvent-', 'ADDITION"'], - ['MutationEvent-', 'REMOVAL"'], ] def widl(line): @@ -84,7 +81,6 @@ def widl(line): ['FocusEvent-initFocusEvent', '-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-AbstractView-viewArg-long-detailArg-EventTarget-relatedTargetArg'], ['MouseEvent-initMouseEvent', '-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-AbstractView-viewArg-long-detailArg-long-screenXArg-long-screenYArg-long-clientXArg-long-clientYArg-boolean-ctrlKeyArg-boolean-altKeyArg-boolean-shiftKeyArg-boolean-metaKeyArg-unsigned-short-buttonArg-EventTarget-relatedTargetArg'], ['WheelEvent-initWheelEvent', '-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-AbstractView-viewArg-long-detailArg-long-screenXArg-long-screenYArg-long-clientXArg-long-clientYArg-unsigned-short-buttonArg-EventTarget-relatedTargetArg-DOMString-modifiersListArg-double-deltaXArg-double-deltaYArg-double-deltaZArg-unsigned-long-deltaMode'], - ['MutationEvent-initMutationEvent', '-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-Node-relatedNodeArg-DOMString-prevValueArg-DOMString-newValueArg-DOMString-attrNameArg-unsigned-short-attrChangeArg'], ] def params(line): diff --git a/fixup.js b/fixup.js index f4f904bf..2f49b391 100644 --- a/fixup.js +++ b/fixup.js @@ -11,7 +11,6 @@ bad_ids = [ ["widl-MouseEvent-getModifierState", "-boolean-DOMString-keyArg"], ["widl-MouseEvent-initMouseEvent", "-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-Window-viewArg-long-detailArg-long-screenXArg-long-screenYArg-long-clientXArg-long-clientYArg-boolean-ctrlKeyArg-boolean-altKeyArg-boolean-shiftKeyArg-boolean-metaKeyArg-short-buttonArg-EventTarget-relatedTargetArg"], ["widl-KeyboardEvent-getModifierState", "-boolean-DOMString-keyArg"], - ["widl-MutationEvent-initMutationEvent", "-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-Node-relatedNodeArg-DOMString-prevValueArg-DOMString-newValueArg-DOMString-attrNameArg-unsigned-short-attrChangeArg"], ["widl-CustomEvent-initCustomEvent", "-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-any-detailArg"], ["widl-FocusEvent-initFocusEvent", "-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-Window-viewArg-long-detailArg-EventTarget-relatedTargetArg"], ["widl-WheelEvent-initWheelEvent", "-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-Window-viewArg-long-detailArg-long-screenXArg-long-screenYArg-long-clientXArg-long-clientYArg-short-buttonArg-EventTarget-relatedTargetArg-DOMString-modifiersListArg-double-deltaXArg-double-deltaYArg-double-deltaZArg-unsigned-long-deltaMode"], @@ -44,9 +43,6 @@ idl_constants = { "BUBBLING_PHASE": "#widl-Event-", "CAPTURING_PHASE": "#widl-Event-", "NONE": "#widl-Event-", - "ADDITION": "#widl-MutationEvent-", - "MODIFICATION": "#widl-MutationEvent-", - "REMOVAL": "#widl-MutationEvent-", }; function fixup_ids() { diff --git a/images/event-inheritance.svg b/images/event-inheritance.svg index a09c6aec..2559c57b 100644 --- a/images/event-inheritance.svg +++ b/images/event-inheritance.svg @@ -51,7 +51,7 @@ Event is the base interface. - UIEvent, CustomEvent, and MutationEvent inherit from Event. + UIEvent and CustomEvent inherit from Event. FocusEvent, MouseEvent, KeyboardEvent, and CompositionEvent inherit from UIEvent. WheelEvent inherits from MouseEvent. diff --git a/index-snapshot.html b/index-snapshot.html index 76a53f7c..684f6be8 100644 --- a/index-snapshot.html +++ b/index-snapshot.html @@ -1187,7 +1187,7 @@

Event Types

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. + including lower level device dependent events.

@@ -7639,8 +7639,8 @@

Legacy Event Initializers

-

Initializing all the attributes of a MutationEvent requires calls to two initializer methods: - initEvent and initMutationEvent. +

Initializing all the attributes of a UIEvent requires calls to two initializer methods: + initEvent and initUIEvent.

@@ -8328,24 +8328,6 @@

Legacy Event Types

Yes None - - DOMAttrModified - Sync - Yes - Element - MutationEvent - No - None - - - DOMCharacterDataModified - Sync - Yes - Text, Comment, ProcessingInstruction - MutationEvent - No - None - DOMFocusIn Sync @@ -8364,56 +8346,6 @@

Legacy Event Types

No None - - DOMNodeInserted - Sync - Yes - Element, Attr, Text, Comment, DocumentType, - ProcessingInstruction - MutationEvent - No - None - - - DOMNodeInsertedIntoDocument - Sync - No - Element, Attr, Text, Comment, DocumentType, - ProcessingInstruction - MutationEvent - No - None - - - DOMNodeRemoved - Sync - Yes - Element, Attr, Text, Comment, DocumentType, - ProcessingInstruction - MutationEvent - No - None - - - DOMNodeRemovedFromDocument - Sync - No - Element, Attr, Text, Comment, DocumentType, - ProcessingInstruction - MutationEvent - No - None - - - DOMSubtreeModified - Sync - Yes - Window, Document, DocumentFragment, Element, Attr - - MutationEvent - No - None - keypress Sync @@ -9051,759 +8983,6 @@

keypress e

-
-

Legacy MutationEvent events

- -

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

- -

Note: - None of the event types associated with the MutationEvent interface 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. -

-

DOM4 [DOM4] provides a new mechanism using a - MutationObserver interface which addresses the use cases that mutation events - solve, but in a more performant manner. - Thus, this specification describes mutation events for reference and completeness of legacy - behavior, but deprecates the use of the - MutationEvent interface. -

-
- -
-

Interface MutationEvent

- -

Introduced in DOM Level 2, deprecated in this specification

- -

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

- -
-
// attrChangeType
- -
const unsigned short MODIFICATION = 1
-
-

The Attr was modified in place.

-
- -
const unsigned short ADDITION = 2
-
-

The Attr was just added.

-
- -
const unsigned short REMOVAL = 3
-
-

The Attr was just removed.

-
- -
readonly attribute Node? relatedNode
-
-

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

- -

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

-
- -
readonly attribute DOMString prevValue
-
-

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

- -

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

-
- -
readonly attribute DOMString newValue
-
-

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

- -

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

-
- -
readonly attribute DOMString attrName
-
-

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

- -

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

-
- -
readonly attribute unsigned short attrChange
-
-

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

- -

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

- -

Note: - There is no defined constant for the attrChange value of 0 (the un-initialized value). -

-
- -
void initMutationEvent()
-
-

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

- -
-
DOMString typeArg
-
-

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

-
- -
boolean bubblesArg
-
-

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

-
- -
boolean cancelableArg
-
-

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

-
- -
Node? relatedNodeArg
-
-

Specifies MutationEvent.relatedNode.

-
- -
DOMString prevValueArg
-
-

Specifies MutationEvent.prevValue. - This value MAY be the empty string. -

-
- -
DOMString newValueArg
-
-

Specifies MutationEvent.newValue. - This value MAY be the empty string. -

-
- -
DOMString attrNameArg
-
-

Specifies MutationEvent.attrName. - This value MAY be the empty string. -

-
- -
unsigned short attrChangeArg
-
-

Specifies MutationEvent.attrChange. - This value MAY be 0. -

-
- -
-
- -
-
- -

The mutation event types are listed below.

- - -
-
-
DOMAttrModified
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMAttrModified
InterfaceMutationEvent
Sync / AsyncSync
BubblesYes
Trusted TargetsElement
CancelableNo
Default actionNone
Context
(trusted events)		 - -
- -

A user agent MUST dispatch this event after - an Attr.value has been modified and after an Attr node has been - added to or removed from an Element. - The event target of this event MUST be - the Element node where the change occurred. - It is implementation dependent whether this event type occurs when the children of the - Attr node are changed in ways that do not affect the value of Attr.value. -

- -

Warning! - The DOMAttrModified - event type is defined in this specification for reference and completeness, but this - specification deprecates the use of this event type. -

-
-
-
- - -
-
-
DOMCharacterDataModified
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMCharacterDataModified
InterfaceMutationEvent
Sync / AsyncSync
BubblesYes
Trusted TargetsText, Comment, ProcessingInstruction
CancelableNo
Default actionNone
Context
(trusted events)		 - -
- -

A user agent MUST dispatch this event - after CharacterData.data or ProcessingInstruction.data - have been modified, but the node itself has not been inserted or deleted. - The event target of this event MUST - be the CharacterData node or the ProcessingInstruction node. -

- -

Warning! - The DOMCharacterDataModified - event type is defined in this specification for reference and completeness, but this specification - deprecates the use of this event type. -

-
-
-
- - -
-
-
DOMNodeInserted
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMNodeInserted
InterfaceMutationEvent
Sync / AsyncSync
BubblesYes
Trusted TargetsElement, Attr, Text, Comment, DocumentType, - ProcessingInstruction
CancelableNo
Default actionNone
Context
(trusted events)		 - -
- -

A user agent MUST dispatch this event type when - a node other than an Attr node has been added as a child of another node. - A user agent MAY dispatch this event when - an Attr node has been added to an Element node - (see note below). - This event MUST be dispatched after the insertion has taken place. - The event target of this event MUST be the - node being inserted. -

- -

Note: - For detecting attribute insertion, use the - DOMAttrModified - event type instead. -

- -

Warning! - The DOMNodeInserted event - type is defined in this specification for reference and completeness, but this specification - deprecates the use of this event type. -

-
-
-
- - -
-
-
DOMNodeInsertedIntoDocument
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMNodeInsertedIntoDocument
InterfaceMutationEvent
Sync / AsyncSync
BubblesNo
Trusted TargetsElement, Attr, Text, Comment, DocumentType, - ProcessingInstruction
CancelableNo
Default actionNone
Context
(trusted events)		 - -
- -

A user agent MUST dispatch this event when a node - has been inserted into a document, either through direct insertion of the node or insertion of a - subtree in which it is contained. - A user agent MAY treat an Attr - node as part of an Element's subtree. - This event MUST be dispatched after the insertion has taken place. - The event target of this event MUST be the node - being inserted. - If the node is being directly inserted, the event type - DOMNodeInserted - MUST occur before this event type. -

- -

Warning! - The DOMNodeInsertedIntoDocument - event type is defined in this specification for reference and completeness, but this specification - deprecates the use of this event type. -

-
-
-
- - -
-
-
DOMNodeRemoved
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMNodeRemoved
InterfaceMutationEvent
Sync / AsyncSync
BubblesYes
Trusted TargetsElement, Attr, Text, Comment, DocumentType, - ProcessingInstruction
CancelableNo
Default actionNone
Context
(trusted events)		 - -
- -

A user agent MUST dispatch this event when a node - other than an Attr node is being removed from its parent node. - A user agent MAY dispatch this event when an - Attr node is being removed from its ownerElement - (see note below). - This event MUST be dispatched before the removal takes place. The - event target of this event MUST be the node being removed. -

- -

Note: - For reliably detecting attribute removal, use the - DOMAttrModified - event type instead. -

- -

Warning! - The DOMNodeRemoved event type - is defined in this specification for reference and completeness, but this specification - deprecates the use of this event type. -

-
-
-
- - -
-
-
DOMNodeRemovedFromDocument
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMNodeRemovedFromDocument
InterfaceMutationEvent
Sync / AsyncSync
BubblesNo
Trusted TargetsElement, Attr, Text, Comment, DocumentType, - ProcessingInstruction
CancelableNo
Default actionNone
Context
(trusted events)		 - -
- -

A user agent MUST dispatch this event when a node is - being removed from a document, either through direct removal of the node or removal of a subtree in - which it is contained. - A user agent MAY treat an Attr - node as part of an Element's subtree. - This event MUST be dispatched before the removal takes place. - The event target of this event type MUST be the node - being removed. - If the node is being directly removed, the event type - DOMNodeRemoved - MUST occur before this event type. -

- -

Note: - For reliably detecting attribute removal, use the - DOMAttrModified - event type instead. -

- -

Warning! - The DOMNodeRemovedFromDocument - event type is defined in this specification for reference and completeness, but this specification - deprecates the use of this event type. -

-
-
-
- - -
-
-
DOMSubtreeModified
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMSubtreeModified
InterfaceMutationEvent
Sync / AsyncSync
BubblesYes
Trusted TargetsWindow, Document, DocumentFragment, Element, Attr -
CancelableNo
Default actionNone
Context
(trusted events)		 - -
- -

This is a general event for notification of all changes to the document. - It can be used instead of the more specific mutation and mutation name events. - It MAY be dispatched after a single modification to the document or, at the implementation's - discretion, after multiple changes have occurred. - The latter case SHOULD generally be used to accommodate multiple changes which occur either - simultaneously or in rapid succession. - The target of this event MUST be the lowest common parent of the changes which have taken place. - This event MUST be dispatched after any other events caused by the mutation(s) have occurred. -

- -

Warning! - The DOMSubtreeModified event - type is defined in this specification for reference and completeness, but this specification - deprecates the use of this event type. -

-
-
-
- -
- diff --git a/sections/legacy-event-initializers.txt b/sections/legacy-event-initializers.txt index 8545fa70..6cfd2a75 100644 --- a/sections/legacy-event-initializers.txt +++ b/sections/legacy-event-initializers.txt @@ -14,9 +14,9 @@ derived from the basic {{Event}} interface required that the initializer of fully initialize an event.
-Initializing all the attributes of a MutationEvent requires calls to two +Initializing all the attributes of a UIEvent requires calls to two initializer methods: initEvent and -initMutationEvent. +initUIEvent.
Due in part to the length of time in the development of this standard, some diff --git a/sections/legacy-event-types.txt b/sections/legacy-event-types.txt index e3ba552d..8efe1b05 100644 --- a/sections/legacy-event-types.txt +++ b/sections/legacy-event-types.txt @@ -20,34 +20,10 @@ completeness. | | Async | Phase | target types | | | | | +-----------------------------+----o---+----o-----+--------------------o---------------------+--------o---------+------o-----+------o----+------------------------------------------------+ +| DOMActivate | Sync | Yes | Element | UIEvent | Yes | Yes | None | -+| DOMAttrModified | Sync | Yes | Element | MutationEvent | No | No | None | -+| DOMCharacterDataModified | Sync | Yes | Text, | MutationEvent | No | No | None | - | | | | Comment, | | | | | - | | | | ProcessingInstruction | | | | | +| DOMFocusIn | Sync | Yes | Window, | FocusEvent | No | Yes | None | | | | | Element | | | | | +| DOMFocusOut | Sync | Yes | Window, | FocusEvent | No | Yes | None | | | | | Element | | | | | -+| DOMNodeInserted | Sync | Yes | Element, Attr, | MutationEvent | No | No | None | - | | | | Text, Comment, | | | | | - | | | | DocumentType, | | | | | - | | | | ProcessingInstruction | | | | | -+| DOMNodeInsertedIntoDocument | Sync | No | Element, Attr, | MutationEvent | No | No | None | - | | | | Text, Comment, | | | | | - | | | | DocumentType, | | | | | - | | | | ProcessingInstruction | | | | | -+| DOMNodeRemoved | Sync | Yes | Element, Attr, | MutationEvent | No | No | None | - | | | | Text, Comment, | | | | | - | | | | DocumentType, | | | | | - | | | | ProcessingInstruction | | | | | -+| DOMNodeRemovedFromDocument | Sync | No | Element, Attr, | MutationEvent | No | No | None | - | | | | Text, Comment, | | | | | - | | | | DocumentType, | | | | | - | | | | ProcessingInstruction | | | | | -+| DOMSubtreeModified | Sync | Yes | Window, | MutationEvent | No | No | None | - | | | | Document, | | | | | - | | | | DocumentFragment, | | | | | - | | | | Element, Attr | | | | | +| keypress | Sync | Yes | Element | KeyboardEvent | Yes | Yes | Varies: launch text composition system; | | | | | | | | | EVENT{blur} and EVENT{focus} events; | | | | | | | | | EVENT{DOMActivate} event; other event | @@ -533,731 +509,4 @@ interface TextEvent : UIEvent { Issue: See Text Event section in UI Events Algorithms for the {{TextEvent}} interface and the textInput event. - -

Legacy {{MutationEvent}} events

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

- None of the event types associated with the {{MutationEvent}} interface 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. - -
-

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

-

- DOM4 [[!DOM]] provides a new mechanism using a - MutationObserver interface which addresses the use cases that - mutation events solve, but in a more performant manner. Thus, this - specification describes mutation events for reference and completeness of - legacy behavior, but deprecates the use of the {{MutationEvent}} - interface. -

-
- -

Interface MutationEvent

- -

Introduced in DOM Level 2, deprecated in this - specification

- - The MutationEvent interface provides specific contextual - information associated with Mutation events. - - To create an instance of the MutationEvent interface, use - the {{Document/createEvent()}} method call. - - 
-		[Exposed=Window]
-		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;
-
-			undefined initMutationEvent(DOMString typeArg,
-				optional boolean bubblesArg = false,
-				optional boolean cancelableArg = false,
-				optional Node? relatedNodeArg = null,
-				optional DOMString prevValueArg = "",
-				optional DOMString newValueArg = "",
-				optional DOMString attrNameArg = "",
-				optional unsigned short attrChangeArg = 0);
-		};
-
- -
-
MODIFICATION
-
- The Attr was modified in place. -
- -
ADDITION
-
- The Attr was just added. -
- -
REMOVAL
-
- The Attr was just removed. -
- -
relatedNode
-
- 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 EVENT{DOMAttrModified} event, it indicates the - Attr node which was modified, added, or removed. - - The un-initialized value of this attribute MUST be - null. -
- -
prevValue
-
- prevValue indicates the previous value of the - Attr node in EVENT{DOMAttrModified} events, and of - the CharacterData node in - EVENT{DOMCharacterDataModified} events. - - The un-initialized value of this attribute MUST be - "" (the empty string). -
- -
newValue
-
- newValue indicates the new value of the - Attr node in EVENT{DOMAttrModified} events, and of - the CharacterData node in - EVENT{DOMCharacterDataModified} events. - - The un-initialized value of this attribute MUST be - "" (the empty string). -
- -
attrName
-
- attrName indicates the name of the changed - Attr node in a EVENT{DOMAttrModified} event. - - The un-initialized value of this attribute MUST be - "" (the empty string). -
- -
attrChange
-
- attrChange indicates the type of change which - triggered the EVENT{DOMAttrModified} event. The values can be - MODIFICATION, ADDITION, or - REMOVAL. - - The un-initialized value of this attribute MUST be - 0. - -

- There is no defined constant for the attrChange value of 0 (the - un-initialized value). -

-
- -
initMutationEvent(typeArg)
-
- Initializes attributes of a MutationEvent object. - This method has the same behavior as {{Event/initEvent()}}. - -
-
DOMString typeArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter. -
- -
boolean bubblesArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter. -
- -
boolean cancelableArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter. -
- -
Node? relatedNodeArg
-
- Specifies {{MutationEvent}}.relatedNode. -
- -
DOMString prevValueArg
-
- Specifies {{MutationEvent}}.prevValue. This value MAY be the empty string. -
- -
DOMString newValueArg
-
- Specifies {{MutationEvent}}.newValue. - This value MAY be the empty string. -
- -
DOMString attrNameArg
-
- Specifies {{MutationEvent}}.attrName. - This value MAY be the empty string. -
- -
unsigned short attrChangeArg
-
- Specifies {{MutationEvent}}.attrChange. - This value MAY be 0. -
-
-
-
- -

Legacy {{MutationEvent}} event types

- - The mutation event types are listed below. - -
DOMAttrModified
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMAttrModified
Interface{{MutationEvent}}
Sync / AsyncSync
BubblesYes
Trusted TargetsElement
CancelableNo
ComposedNo
Default actionNone
Context
(trusted events)		 -
    -
  • {{Event}}.{{Event/target}} : - element whose attribute is being modified
    • -
  • {{MutationEvent}}.attrName : - the name of the changed Attr node
    • -
  • {{MutationEvent}}.attrChange : - the numerical code corresponding to the most applicable attrChangeType
    • -
  • {{MutationEvent}}.relatedNode : - the Attr node that has been modified, added, or removed.
    • -
  • {{MutationEvent}}.newValue : - new value of the attribute, if the Attr node has been added or modified
    • -
  • {{MutationEvent}}.prevValue : - previous value of the attribute, if the Attr node has been removed or modified
    • -
-
- - A user agent MUST dispatch this event after an - Attr.value has been modified and after an - Attr node has been added to or removed from an - Element. The event target of this event MUST be - the Element node where the change occurred. It is - implementation dependent whether this event type occurs when the - children of the Attr node are changed in ways that do - not affect the value of Attr.value. - -

- The EVENT{DOMAttrModified} event type is defined in this - specification for reference and completeness, but this specification - deprecates the use of this event type. -

- -
DOMCharacterDataModified
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMCharacterDataModified
Interface{{MutationEvent}}
Sync / AsyncSync
BubblesYes
Trusted TargetsText, Comment, ProcessingInstruction
CancelableNo
ComposedNo
Default actionNone
Context
(trusted events)		 -
    -
  • {{Event}}.{{Event/target}} : - object whose content is being modified
    • -
  • {{MutationEvent}}.attrName : - the empty string
    • -
  • {{MutationEvent}}.attrChange : - 0
    • -
  • {{MutationEvent}}.relatedNode : - parent node of the object whose content is being modified
    • -
  • {{MutationEvent}}.newValue : - new value of the object
    • -
  • {{MutationEvent}}.prevValue : - previous value of the object
    • -
-
- - A user agent MUST dispatch this event after - CharacterData.data or - ProcessingInstruction.data have been modified, but the - node itself has not been inserted or deleted. The event - target of this event MUST be the CharacterData node - or the ProcessingInstruction node. - -

- The EVENT{DOMCharacterDataModified} event type is defined in this - specification for reference and completeness, but this specification - deprecates the use of this event type. -

- -
DOMNodeInserted
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMNodeInserted
Interface{{MutationEvent}}
Sync / AsyncSync
BubblesYes
Trusted TargetsElement, Attr, Text, Comment, DocumentType, - ProcessingInstruction
CancelableNo
ComposedNo
Default actionNone
Context
(trusted events)		 -
    -
  • {{Event}}.{{Event/target}} : - element which is being inserted
    • -
  • {{MutationEvent}}.attrName : - the empty string
    • -
  • {{MutationEvent}}.attrChange : - 0
    • -
  • {{MutationEvent}}.relatedNode : - parent node of the node that has been inserted, or the ownerElement in the case of Attr nodes
    • -
  • {{MutationEvent}}.newValue : - the empty string
    • -
  • {{MutationEvent}}.prevValue : - the empty string
    • -
-
- - A user agent MUST dispatch this event type when a node other - than an Attr node has been added as a child of another - node. A user agent MAY dispatch this event when an - Attr node has been added to an Element - node (see note below). This - event MUST be dispatched after the insertion has taken place. The - event target of this event MUST be the node being inserted. - -

- For detecting attribute insertion, use the EVENT{DOMAttrModified} - event type instead. -

- -

- The EVENT{DOMNodeInserted} event type is defined in this - specification for reference and completeness, but this specification - deprecates the use of this event type. -

- -
DOMNodeInsertedIntoDocument
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMNodeInsertedIntoDocument
Interface{{MutationEvent}}
Sync / AsyncSync
BubblesNo
Trusted TargetsElement, Attr, Text, Comment, DocumentType, - ProcessingInstruction
CancelableNo
ComposedNo
Default actionNone
Context
(trusted events)		 -
    -
  • {{Event}}.{{Event/target}} : - element which is being inserted
    • -
  • {{MutationEvent}}.attrName : - the empty string
    • -
  • {{MutationEvent}}.attrChange : - 0
    • -
  • {{MutationEvent}}.relatedNode : - parent node of the node that has been inserted, or the ownerElement in the case of Attr nodes
    • -
  • {{MutationEvent}}.newValue : - the empty string
    • -
  • {{MutationEvent}}.prevValue : - the empty string
    • -
-
- - A user agent MUST dispatch this event when a node has been - inserted into a document, either through direct insertion of the - node or insertion of a subtree in which it is contained. A user - agent MAY treat an Attr node as part of an - Element's subtree. This event MUST be dispatched after - the insertion has taken place. The event target of this event - MUST be the node being inserted. If the node is being directly - inserted, the event type EVENT{DOMNodeInserted} MUST occur before - this event type. - -

- The EVENT{DOMNodeInsertedIntoDocument} event type is defined in this - specification for reference and completeness, but this specification - deprecates the use of this event type. -

- -
DOMNodeRemoved
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMNodeRemoved
Interface{{MutationEvent}}
Sync / AsyncSync
BubblesYes
Trusted TargetsElement, Attr, Text, Comment, DocumentType, - ProcessingInstruction
CancelableNo
ComposedNo
Default actionNone
Context
(trusted events)		 -
    -
  • {{Event}}.{{Event/target}} : - element which is being removed
    • -
  • {{MutationEvent}}.attrName : - the empty string
    • -
  • {{MutationEvent}}.attrChange : - 0
    • -
  • {{MutationEvent}}.relatedNode : - the parent node of the node being removed, or the ownerElement in the case of Attr nodes
    • -
  • {{MutationEvent}}.newValue : - the empty string
    • -
  • {{MutationEvent}}.prevValue : - the empty string
    • -
-
- - A user agent MUST dispatch this event when a node other than - an Attr node is being removed from its parent node. A - user agent MAY dispatch this event when an Attr - node is being removed from its ownerElement (see note below). This event MUST be - dispatched before the removal takes place. The event target - of this event MUST be the node being removed. - -

- For reliably detecting attribute removal, use the - EVENT{DOMAttrModified} event type instead. -

- -

- The EVENT{DOMNodeRemoved} event type is defined in this - specification for reference and completeness, but this specification - deprecates the use of this event type. -

- -
DOMNodeRemovedFromDocument
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMNodeRemovedFromDocument
Interface{{MutationEvent}}
Sync / AsyncSync
BubblesNo
Trusted TargetsElement, Attr, Text, Comment, DocumentType, - ProcessingInstruction
CancelableNo
ComposedNo
Default actionNone
Context
(trusted events)		 -
    -
  • {{Event}}.{{Event/target}} : - element which is being removed
    • -
  • {{MutationEvent}}.attrName : - the empty string
    • -
  • {{MutationEvent}}.attrChange : - 0
    • -
  • {{MutationEvent}}.relatedNode : - the parent node of the node being removed, or the ownerElement in the case of Attr nodes
    • -
  • {{MutationEvent}}.newValue : - the empty string
    • -
  • {{MutationEvent}}.prevValue : - the empty string
    • -
-
- - A user agent MUST dispatch this event when a node is being - removed from a document, either through direct removal of the node - or removal of a subtree in which it is contained. A user - agent MAY treat an Attr node as part of an - Element's subtree. This event MUST be dispatched before - the removal takes place. The event target of this event type - MUST be the node being removed. If the node is being directly - removed, the event type EVENT{DOMNodeRemoved} MUST occur before this - event type. - -

- For reliably detecting attribute removal, use the - EVENT{DOMAttrModified} event type instead. -

- -

- The EVENT{DOMNodeRemovedFromDocument} event type is defined in this - specification for reference and completeness, but this specification - deprecates the use of this event type. -

- -
DOMSubtreeModified
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMSubtreeModified
Interface{{MutationEvent}}
Sync / AsyncSync
BubblesYes
Trusted TargetsWindow, Document, DocumentFragment, Element, Attr -
CancelableNo
ComposedNo
Default actionNone
Context
(trusted events)		 -
    -
  • {{Event}}.{{Event/target}} : - parent node of subtree being modified
    • -
  • {{MutationEvent}}.attrName : - the empty string
    • -
  • {{MutationEvent}}.attrChange : - 0
    • -
  • {{MutationEvent}}.relatedNode : - null
    • -
  • {{MutationEvent}}.newValue : - the empty string
    • -
  • {{MutationEvent}}.prevValue : - the empty string
    • -
-
- - This is a general event for notification of all changes to the - document. It can be used instead of the more specific mutation and - mutation name events. It MAY be dispatched after a single - modification to the document or, at the implementation's discretion, - after multiple changes have occurred. The latter case SHOULD - generally be used to accommodate multiple changes which occur either - simultaneously or in rapid succession. The target of this event MUST - be the lowest common parent of the changes which have taken place. - This event MUST be dispatched after any other events caused by the - mutation(s) have occurred. - -

- The EVENT{DOMSubtreeModified} event type is defined in this - specification for reference and completeness, but this specification - deprecates the use of this event type. -

- diff --git a/split/composition-events.bs b/split/composition-events.bs index f86f8cc4..8808c623 100644 --- a/split/composition-events.bs +++ b/split/composition-events.bs @@ -426,9 +426,9 @@ And finally: fully initialize an event.
- Initializing all the attributes of a MutationEvent requires calls to two + Initializing all the attributes of a UIEvent requires calls to two initializer methods: initEvent and - initMutationEvent. + initUIEvent.
Due in part to the length of time in the development of this standard, some diff --git a/split/composition-events.html b/split/composition-events.html index dfa6591a..9e1194bf 100644 --- a/split/composition-events.html +++ b/split/composition-events.html @@ -1221,8 +1221,8 @@

Event interface required that the initializer of each of the derived interfaces be called explicitly in order to fully initialize an event.

-
Initializing all the attributes of a MutationEvent requires calls to two - initializer methods: initEvent and initMutationEvent.
+
Initializing all the attributes of a UIEvent requires calls to two + initializer methods: initEvent and initUIEvent.

Due in part to the length of time in the development of this standard, some implementations MAY have taken a dependency on these (now deprecated) initializer methods. For completeness, these legacy event initializers are @@ -1944,4 +1944,4 @@

I el.innerHTML = markup; return el.content; } -} \ No newline at end of file +} diff --git a/split/composition-events.txt b/split/composition-events.txt index e27d2328..852d65b4 100644 --- a/split/composition-events.txt +++ b/split/composition-events.txt @@ -473,9 +473,9 @@ And finally: fully initialize an event.
- Initializing all the attributes of a MutationEvent requires calls to two + Initializing all the attributes of a UIEvent requires calls to two initializer methods: initEvent and - initMutationEvent. + initUIEvent.
Due in part to the length of time in the development of this standard, some diff --git a/split/keyboard-events.bs b/split/keyboard-events.bs index 32266a9a..eb91b360 100644 --- a/split/keyboard-events.bs +++ b/split/keyboard-events.bs @@ -1565,9 +1565,9 @@ And finally: fully initialize an event.
- Initializing all the attributes of a MutationEvent requires calls to two + Initializing all the attributes of a UIEvent requires calls to two initializer methods: initEvent and - initMutationEvent. + initUIEvent.
Due in part to the length of time in the development of this standard, some diff --git a/split/keyboard-events.html b/split/keyboard-events.html index b2e1e450..a71587eb 100644 --- a/split/keyboard-events.html +++ b/split/keyboard-events.html @@ -2686,8 +2686,8 @@

Event interface required that the initializer of each of the derived interfaces be called explicitly in order to fully initialize an event.

-
Initializing all the attributes of a MutationEvent requires calls to two - initializer methods: initEvent and initMutationEvent.
+
Initializing all the attributes of a UIEvent requires calls to two + initializer methods: initEvent and initUIEvent.

Due in part to the length of time in the development of this standard, some implementations MAY have taken a dependency on these (now deprecated) initializer methods. For completeness, these legacy event initializers are @@ -4106,4 +4106,4 @@

I el.innerHTML = markup; return el.content; } -} \ No newline at end of file +} diff --git a/split/keyboard-events.txt b/split/keyboard-events.txt index 6631428f..09477e11 100644 --- a/split/keyboard-events.txt +++ b/split/keyboard-events.txt @@ -1701,9 +1701,9 @@ And finally: fully initialize an event.
- Initializing all the attributes of a MutationEvent requires calls to two + Initializing all the attributes of a UIEvent requires calls to two initializer methods: initEvent and - initMutationEvent. + initUIEvent.
Due in part to the length of time in the development of this standard, some diff --git a/split/mouse-events.bs b/split/mouse-events.bs index 57557705..10157231 100644 --- a/split/mouse-events.bs +++ b/split/mouse-events.bs @@ -1289,9 +1289,9 @@ with the following supplemental additions: fully initialize an event.
- Initializing all the attributes of a MutationEvent requires calls to two + Initializing all the attributes of a UIEvent requires calls to two initializer methods: initEvent and - initMutationEvent. + initUIEvent.
Due in part to the length of time in the development of this standard, some diff --git a/split/mouse-events.html b/split/mouse-events.html index da281b11..8c6c6823 100644 --- a/split/mouse-events.html +++ b/split/mouse-events.html @@ -2136,8 +2136,8 @@

Event interface required that the initializer of each of the derived interfaces be called explicitly in order to fully initialize an event.

-
Initializing all the attributes of a MutationEvent requires calls to two - initializer methods: initEvent and initMutationEvent.
+
Initializing all the attributes of a UIEvent requires calls to two + initializer methods: initEvent and initUIEvent.

Due in part to the length of time in the development of this standard, some implementations MAY have taken a dependency on these (now deprecated) initializer methods. For completeness, these legacy event initializers are @@ -3118,4 +3118,4 @@

I el.innerHTML = markup; return el.content; } -} \ No newline at end of file +} diff --git a/split/mouse-events.txt b/split/mouse-events.txt index 34ad7bfb..51b6f458 100644 --- a/split/mouse-events.txt +++ b/split/mouse-events.txt @@ -14,7 +14,7 @@ Former Editor: Doug Schepers, Mar 2008 - May 2011 !Tests: web-platform-tests uievents/ (ongoing work) Abstract: *** Mouse Events *** - + Note: This is an experimental split of the UI Events spec into smaller, event-specific specs. The split was made from an out-of-date snapshot, so the information here is not current, so please focus on the overall structure rather than the specifics of the @@ -60,9 +60,9 @@ spec:infra; type:dfn; text:code point TODO.

Conformance

- + Boilerplate? - +

Stylistic Conventions

This specification follows the @@ -190,7 +190,7 @@ with the following supplemental additions: The horizontal offset from the nearest ancestor element which is a stacking context, is positioned, or paints in the positioned phase when painting a stacking context. - + The un-initialized value of this attribute MUST be 0. @@ -1637,7 +1637,7 @@ with the following supplemental additions:

Legacy Event Initializers

This section is normative. - + The following features are obsolete and should only be implemented by user agents that require compatibility with legacy software. @@ -1650,9 +1650,9 @@ with the following supplemental additions: fully initialize an event.
- Initializing all the attributes of a MutationEvent requires calls to two + Initializing all the attributes of a UIEvent requires calls to two initializer methods: initEvent and - initMutationEvent. + initUIEvent.
Due in part to the length of time in the development of this standard, some @@ -1809,7 +1809,7 @@ with the following supplemental additions: This section will be deleted. Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. +Many of these are properly defined elsewhere and should be linked to directly. Terms which should be defined in this spec should be defined inline. : activation behavior diff --git a/split/ui-events.html b/split/ui-events.html index e03e827f..54efd7a8 100644 --- a/split/ui-events.html +++ b/split/ui-events.html @@ -994,8 +994,8 @@

Event interface required that the initializer of each of the derived interfaces be called explicitly in order to fully initialize an event.

-
Initializing all the attributes of a MutationEvent requires calls to two - initializer methods: initEvent and initMutationEvent.
+
Initializing all the attributes of a UIEvent requires calls to two + initializer methods: initEvent and initUIEvent.

Due in part to the length of time in the development of this standard, some implementations MAY have taken a dependency on these (now deprecated) initializer methods. For completeness, these legacy event initializers are @@ -1612,4 +1612,4 @@

I el.innerHTML = markup; return el.content; } -} \ No newline at end of file +} diff --git a/split/ui-events.txt b/split/ui-events.txt index 3b07f1cd..d4810256 100644 --- a/split/ui-events.txt +++ b/split/ui-events.txt @@ -14,7 +14,7 @@ Former Editor: Doug Schepers, Mar 2008 - May 2011 !Tests: web-platform-tests uievents/ (ongoing work) Abstract: *** UI Events (core) *** - + Note: This is an experimental split of the UI Events spec into smaller, event-specific specs. The split was made from an out-of-date snapshot, so the information here is not current, so please focus on the overall structure rather than the specifics of the @@ -60,9 +60,9 @@ spec:infra; type:dfn; text:code point TODO.

Conformance

- + Boilerplate? - +

Stylistic Conventions

This specification follows the @@ -583,736 +583,10 @@ with the following supplemental additions: | | | including the activation behavior | ++---+-------------+---------------------------------------------------+ -

Legacy {{MutationEvent}} events

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

- None of the event types associated with the {{MutationEvent}} interface 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. - -
-

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

-

- DOM4 [[!DOM]] provides a new mechanism using a - MutationObserver interface which addresses the use cases that - mutation events solve, but in a more performant manner. Thus, this - specification describes mutation events for reference and completeness of - legacy behavior, but deprecates the use of the {{MutationEvent}} - interface. -

-
- -

Interface MutationEvent

- -

Introduced in DOM Level 2, deprecated in this - specification

- - The MutationEvent interface provides specific contextual - information associated with Mutation events. - - To create an instance of the MutationEvent interface, use - the {{Document/createEvent()}} method call. - - 
-		[Exposed=Window]
-		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;
-
-			undefined initMutationEvent(DOMString typeArg,
-				optional boolean bubblesArg = false,
-				optional boolean cancelableArg = false,
-				optional Node? relatedNodeArg = null,
-				optional DOMString prevValueArg = "",
-				optional DOMString newValueArg = "",
-				optional DOMString attrNameArg = "",
-				optional unsigned short attrChangeArg = 0);
-		};
-
- -
-
MODIFICATION
-
- The Attr was modified in place. -
- -
ADDITION
-
- The Attr was just added. -
- -
REMOVAL
-
- The Attr was just removed. -
- -
relatedNode
-
- 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 EVENT{DOMAttrModified} event, it indicates the - Attr node which was modified, added, or removed. - - The un-initialized value of this attribute MUST be - null. -
- -
prevValue
-
- prevValue indicates the previous value of the - Attr node in EVENT{DOMAttrModified} events, and of - the CharacterData node in - EVENT{DOMCharacterDataModified} events. - - The un-initialized value of this attribute MUST be - "" (the empty string). -
- -
newValue
-
- newValue indicates the new value of the - Attr node in EVENT{DOMAttrModified} events, and of - the CharacterData node in - EVENT{DOMCharacterDataModified} events. - - The un-initialized value of this attribute MUST be - "" (the empty string). -
- -
attrName
-
- attrName indicates the name of the changed - Attr node in a EVENT{DOMAttrModified} event. - - The un-initialized value of this attribute MUST be - "" (the empty string). -
- -
attrChange
-
- attrChange indicates the type of change which - triggered the EVENT{DOMAttrModified} event. The values can be - MODIFICATION, ADDITION, or - REMOVAL. - - The un-initialized value of this attribute MUST be - 0. - -

- There is no defined constant for the attrChange value of 0 (the - un-initialized value). -

-
- -
initMutationEvent(typeArg)
-
- Initializes attributes of a MutationEvent object. - This method has the same behavior as {{Event/initEvent()}}. - -
-
DOMString typeArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter. -
- -
boolean bubblesArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter. -
- -
boolean cancelableArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter. -
- -
Node? relatedNodeArg
-
- Specifies {{MutationEvent}}.relatedNode. -
- -
DOMString prevValueArg
-
- Specifies {{MutationEvent}}.prevValue. This value MAY be the empty string. -
- -
DOMString newValueArg
-
- Specifies {{MutationEvent}}.newValue. - This value MAY be the empty string. -
- -
DOMString attrNameArg
-
- Specifies {{MutationEvent}}.attrName. - This value MAY be the empty string. -
- -
unsigned short attrChangeArg
-
- Specifies {{MutationEvent}}.attrChange. - This value MAY be 0. -
-
-
-
- -

Legacy {{MutationEvent}} event types

- - The mutation event types are listed below. - -

DOMAttrModified

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMAttrModified
Interface{{MutationEvent}}
Sync / AsyncSync
BubblesYes
Trusted TargetsElement
CancelableNo
ComposedNo
Default actionNone
Context
(trusted events)		 -
    -
  • {{Event}}.{{Event/target}} : - element whose attribute is being modified
    • -
  • {{MutationEvent}}.attrName : - the name of the changed Attr node
    • -
  • {{MutationEvent}}.attrChange : - the numerical code corresponding to the most applicable attrChangeType
    • -
  • {{MutationEvent}}.relatedNode : - the Attr node that has been modified, added, or removed.
    • -
  • {{MutationEvent}}.newValue : - new value of the attribute, if the Attr node has been added or modified
    • -
  • {{MutationEvent}}.prevValue : - previous value of the attribute, if the Attr node has been removed or modified
    • -
-
- - A user agent MUST dispatch this event after an - Attr.value has been modified and after an - Attr node has been added to or removed from an - Element. The event target of this event MUST be - the Element node where the change occurred. It is - implementation dependent whether this event type occurs when the - children of the Attr node are changed in ways that do - not affect the value of Attr.value. - -

- The EVENT{DOMAttrModified} event type is defined in this - specification for reference and completeness, but this specification - deprecates the use of this event type. -

- -

DOMCharacterDataModified

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMCharacterDataModified
Interface{{MutationEvent}}
Sync / AsyncSync
BubblesYes
Trusted TargetsText, Comment, ProcessingInstruction
CancelableNo
ComposedNo
Default actionNone
Context
(trusted events)		 -
    -
  • {{Event}}.{{Event/target}} : - object whose content is being modified
    • -
  • {{MutationEvent}}.attrName : - the empty string
    • -
  • {{MutationEvent}}.attrChange : - 0
    • -
  • {{MutationEvent}}.relatedNode : - parent node of the object whose content is being modified
    • -
  • {{MutationEvent}}.newValue : - new value of the object
    • -
  • {{MutationEvent}}.prevValue : - previous value of the object
    • -
-
- - A user agent MUST dispatch this event after - CharacterData.data or - ProcessingInstruction.data have been modified, but the - node itself has not been inserted or deleted. The event - target of this event MUST be the CharacterData node - or the ProcessingInstruction node. - -

- The EVENT{DOMCharacterDataModified} event type is defined in this - specification for reference and completeness, but this specification - deprecates the use of this event type. -

- -

DOMNodeInserted

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMNodeInserted
Interface{{MutationEvent}}
Sync / AsyncSync
BubblesYes
Trusted TargetsElement, Attr, Text, Comment, DocumentType, - ProcessingInstruction
CancelableNo
ComposedNo
Default actionNone
Context
(trusted events)		 -
    -
  • {{Event}}.{{Event/target}} : - element which is being inserted
    • -
  • {{MutationEvent}}.attrName : - the empty string
    • -
  • {{MutationEvent}}.attrChange : - 0
    • -
  • {{MutationEvent}}.relatedNode : - parent node of the node that has been inserted, or the ownerElement in the case of Attr nodes
    • -
  • {{MutationEvent}}.newValue : - the empty string
    • -
  • {{MutationEvent}}.prevValue : - the empty string
    • -
-
- - A user agent MUST dispatch this event type when a node other - than an Attr node has been added as a child of another - node. A user agent MAY dispatch this event when an - Attr node has been added to an Element - node (see note below). This - event MUST be dispatched after the insertion has taken place. The - event target of this event MUST be the node being inserted. - -

- For detecting attribute insertion, use the EVENT{DOMAttrModified} - event type instead. -

- -

- The EVENT{DOMNodeInserted} event type is defined in this - specification for reference and completeness, but this specification - deprecates the use of this event type. -

- -

DOMNodeInsertedIntoDocument

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMNodeInsertedIntoDocument
Interface{{MutationEvent}}
Sync / AsyncSync
BubblesNo
Trusted TargetsElement, Attr, Text, Comment, DocumentType, - ProcessingInstruction
CancelableNo
ComposedNo
Default actionNone
Context
(trusted events)		 -
    -
  • {{Event}}.{{Event/target}} : - element which is being inserted
    • -
  • {{MutationEvent}}.attrName : - the empty string
    • -
  • {{MutationEvent}}.attrChange : - 0
    • -
  • {{MutationEvent}}.relatedNode : - parent node of the node that has been inserted, or the ownerElement in the case of Attr nodes
    • -
  • {{MutationEvent}}.newValue : - the empty string
    • -
  • {{MutationEvent}}.prevValue : - the empty string
    • -
-
- - A user agent MUST dispatch this event when a node has been - inserted into a document, either through direct insertion of the - node or insertion of a subtree in which it is contained. A user - agent MAY treat an Attr node as part of an - Element's subtree. This event MUST be dispatched after - the insertion has taken place. The event target of this event - MUST be the node being inserted. If the node is being directly - inserted, the event type EVENT{DOMNodeInserted} MUST occur before - this event type. - -

- The EVENT{DOMNodeInsertedIntoDocument} event type is defined in this - specification for reference and completeness, but this specification - deprecates the use of this event type. -

- -

DOMNodeRemoved

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMNodeRemoved
Interface{{MutationEvent}}
Sync / AsyncSync
BubblesYes
Trusted TargetsElement, Attr, Text, Comment, DocumentType, - ProcessingInstruction
CancelableNo
ComposedNo
Default actionNone
Context
(trusted events)		 -
    -
  • {{Event}}.{{Event/target}} : - element which is being removed
    • -
  • {{MutationEvent}}.attrName : - the empty string
    • -
  • {{MutationEvent}}.attrChange : - 0
    • -
  • {{MutationEvent}}.relatedNode : - the parent node of the node being removed, or the ownerElement in the case of Attr nodes
    • -
  • {{MutationEvent}}.newValue : - the empty string
    • -
  • {{MutationEvent}}.prevValue : - the empty string
    • -
-
- - A user agent MUST dispatch this event when a node other than - an Attr node is being removed from its parent node. A - user agent MAY dispatch this event when an Attr - node is being removed from its ownerElement (see note below). This event MUST be - dispatched before the removal takes place. The event target - of this event MUST be the node being removed. - -

- For reliably detecting attribute removal, use the - EVENT{DOMAttrModified} event type instead. -

- -

- The EVENT{DOMNodeRemoved} event type is defined in this - specification for reference and completeness, but this specification - deprecates the use of this event type. -

- -

DOMNodeRemovedFromDocument

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMNodeRemovedFromDocument
Interface{{MutationEvent}}
Sync / AsyncSync
BubblesNo
Trusted TargetsElement, Attr, Text, Comment, DocumentType, - ProcessingInstruction
CancelableNo
ComposedNo
Default actionNone
Context
(trusted events)		 -
    -
  • {{Event}}.{{Event/target}} : - element which is being removed
    • -
  • {{MutationEvent}}.attrName : - the empty string
    • -
  • {{MutationEvent}}.attrChange : - 0
    • -
  • {{MutationEvent}}.relatedNode : - the parent node of the node being removed, or the ownerElement in the case of Attr nodes
    • -
  • {{MutationEvent}}.newValue : - the empty string
    • -
  • {{MutationEvent}}.prevValue : - the empty string
    • -
-
- - A user agent MUST dispatch this event when a node is being - removed from a document, either through direct removal of the node - or removal of a subtree in which it is contained. A user - agent MAY treat an Attr node as part of an - Element's subtree. This event MUST be dispatched before - the removal takes place. The event target of this event type - MUST be the node being removed. If the node is being directly - removed, the event type EVENT{DOMNodeRemoved} MUST occur before this - event type. - -

- For reliably detecting attribute removal, use the - EVENT{DOMAttrModified} event type instead. -

- -

- The EVENT{DOMNodeRemovedFromDocument} event type is defined in this - specification for reference and completeness, but this specification - deprecates the use of this event type. -

- -

DOMSubtreeModified

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMSubtreeModified
Interface{{MutationEvent}}
Sync / AsyncSync
BubblesYes
Trusted TargetsWindow, Document, DocumentFragment, Element, Attr -
CancelableNo
ComposedNo
Default actionNone
Context
(trusted events)		 -
    -
  • {{Event}}.{{Event/target}} : - parent node of subtree being modified
    • -
  • {{MutationEvent}}.attrName : - the empty string
    • -
  • {{MutationEvent}}.attrChange : - 0
    • -
  • {{MutationEvent}}.relatedNode : - null
    • -
  • {{MutationEvent}}.newValue : - the empty string
    • -
  • {{MutationEvent}}.prevValue : - the empty string
    • -
-
- - This is a general event for notification of all changes to the - document. It can be used instead of the more specific mutation and - mutation name events. It MAY be dispatched after a single - modification to the document or, at the implementation's discretion, - after multiple changes have occurred. The latter case SHOULD - generally be used to accommodate multiple changes which occur either - simultaneously or in rapid succession. The target of this event MUST - be the lowest common parent of the changes which have taken place. - This event MUST be dispatched after any other events caused by the - mutation(s) have occurred. - -

- The EVENT{DOMSubtreeModified} event type is defined in this - specification for reference and completeness, but this specification - deprecates the use of this event type. -

-

Legacy Event Initializers

This section is normative. - + The following features are obsolete and should only be implemented by user agents that require compatibility with legacy software. @@ -1325,9 +599,9 @@ with the following supplemental additions: fully initialize an event.
- Initializing all the attributes of a MutationEvent requires calls to two + Initializing all the attributes of a UIEvent requires calls to two initializer methods: initEvent and - initMutationEvent. + initUIEvent.
Due in part to the length of time in the development of this standard, some @@ -1613,16 +887,16 @@ with the following supplemental additions:

Authoring tools

Add references to these events so that the linker doesn't complain about exporting them. - + EVENT{unload}, EVENT{load}, EVENT{abort}, EVENT{error} - +

Glossary \[DELETE]

This section will be deleted. Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. +Many of these are properly defined elsewhere and should be linked to directly. Terms which should be defined in this spec should be defined inline. : host language From 3d7234b9e856d56430cec39fdbb5863421053b9e Mon Sep 17 00:00:00 2001 From: Mason Freed Date: Fri, 6 Sep 2024 09:52:27 -0700 Subject: [PATCH 2/7] TR --- TR.html | 782 +------------------------------------------------------- 1 file changed, 2 insertions(+), 780 deletions(-) diff --git a/TR.html b/TR.html index 4dece3bd..49c7e51a 100644 --- a/TR.html +++ b/TR.html @@ -7558,8 +7558,8 @@

-

Initializing all the attributes of a MutationEvent requires calls to two initializer methods: - initEvent and initMutationEvent. +

Initializing all the attributes of a UIEvent requires calls to two initializer methods: + initEvent and initUIEvent.

@@ -8109,24 +8109,6 @@

DOMAttrModified - Sync - Yes - Element - MutationEvent - No - None - - - DOMCharacterDataModified - Sync - Yes - Text, Comment, ProcessingInstruction - MutationEvent - No - None - DOMFocusIn Sync @@ -8145,56 +8127,6 @@

No None - - DOMNodeInserted - Sync - Yes - Element, Attr, Text, Comment, DocumentType, - ProcessingInstruction - MutationEvent - No - None - - - DOMNodeInsertedIntoDocument - Sync - No - Element, Attr, Text, Comment, DocumentType, - ProcessingInstruction - MutationEvent - No - None - - - DOMNodeRemoved - Sync - Yes - Element, Attr, Text, Comment, DocumentType, - ProcessingInstruction - MutationEvent - No - None - - - DOMNodeRemovedFromDocument - Sync - No - Element, Attr, Text, Comment, DocumentType, - ProcessingInstruction - MutationEvent - No - None - - - DOMSubtreeModified - Sync - Yes - Window, Document, DocumentFragment, Element, Attr - - MutationEvent - No - None - keypress Sync @@ -8829,716 +8761,6 @@

- -
-

C.4 Legacy MutationEvent events

- -

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

- -
Note

Note: - None of the event types associated with the MutationEvent interface 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
-

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

-

DOM4 [DOM4] provides a new mechanism using a - MutationObserver interface which addresses the use cases that mutation events - solve, but in a more performant manner. - Thus, this specification describes mutation events for reference and completeness of legacy - behavior, but deprecates the use of the - MutationEvent interface. -

-
- -
-

C.4.1 Interface MutationEvent

- -

Introduced in DOM Level 2, deprecated in this specification

- -

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

- - 
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 (DOMString typeArg, boolean bubblesArg, boolean cancelableArg, Node? relatedNodeArg, DOMString prevValueArg, DOMString newValueArg, DOMString attrNameArg, unsigned short attrChangeArg);
-};
C.4.1.1 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. -

- -

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

- -
Note

Note: - There is no defined constant for the attrChange value of 0 (the un-initialized value). -

-
attrName of type DOMString, readonly
-

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

- -

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

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

- -

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

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

- -

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

-
relatedNode of type Node, readonly , nullable
-

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

- -

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

-
C.4.1.2 Methods
initMutationEvent
-

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

- - -
ParameterTypeNullableOptionalDescription
typeArgDOMString✘✘ -

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

-
bubblesArgboolean✘✘ -

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

-
cancelableArgboolean✘✘ -

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

-
relatedNodeArgNode✔✘ -

Specifies MutationEvent.relatedNode.

-
prevValueArgDOMString✘✘ -

Specifies MutationEvent.prevValue. - This value MAY be the empty string. -

-
newValueArgDOMString✘✘ -

Specifies MutationEvent.newValue. - This value MAY be the empty string. -

-
attrNameArgDOMString✘✘ -

Specifies MutationEvent.attrName. - This value MAY be the empty string. -

-
attrChangeArgunsigned short✘✘ -

Specifies MutationEvent.attrChange. - This value MAY be 0. -

-
Return type: void
C.4.1.3 Constants
ADDITION of type unsigned short
-

The Attr was just added.

-
MODIFICATION of type unsigned short
-

The Attr was modified in place.

-
REMOVAL of type unsigned short
-

The Attr was just removed.

-
-
- -

The mutation event types are listed below.

- - -
-
-
DOMAttrModified
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMAttrModified
InterfaceMutationEvent
Sync / AsyncSync
BubblesYes
Trusted TargetsElement
CancelableNo
Default actionNone
Context
(trusted events)		 - -
- -

A user agent MUST dispatch this event after - an Attr.value has been modified and after an Attr node has been - added to or removed from an Element. - The event target of this event MUST be - the Element node where the change occurred. - It is implementation dependent whether this event type occurs when the children of the - Attr node are changed in ways that do not affect the value of Attr.value. -

- -
Warning

Warning! - The DOMAttrModified - event type is defined in this specification for reference and completeness, but this - specification deprecates the use of this event type. -

-
-
-
- - -
-
-
DOMCharacterDataModified
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMCharacterDataModified
InterfaceMutationEvent
Sync / AsyncSync
BubblesYes
Trusted TargetsText, Comment, ProcessingInstruction
CancelableNo
Default actionNone
Context
(trusted events)		 - -
- -

A user agent MUST dispatch this event - after CharacterData.data or ProcessingInstruction.data - have been modified, but the node itself has not been inserted or deleted. - The event target of this event MUST - be the CharacterData node or the ProcessingInstruction node. -

- -
Warning

Warning! - The DOMCharacterDataModified - event type is defined in this specification for reference and completeness, but this specification - deprecates the use of this event type. -

-
-
-
- - -
-
-
DOMNodeInserted
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMNodeInserted
InterfaceMutationEvent
Sync / AsyncSync
BubblesYes
Trusted TargetsElement, Attr, Text, Comment, DocumentType, - ProcessingInstruction
CancelableNo
Default actionNone
Context
(trusted events)		 - -
- -

A user agent MUST dispatch this event type when - a node other than an Attr node has been added as a child of another node. - A user agent MAY dispatch this event when - an Attr node has been added to an Element node - (see note below). - This event MUST be dispatched after the insertion has taken place. - The event target of this event MUST be the - node being inserted. -

- -
Note

Note: - For detecting attribute insertion, use the - DOMAttrModified - event type instead. -

- -
Warning

Warning! - The DOMNodeInserted event - type is defined in this specification for reference and completeness, but this specification - deprecates the use of this event type. -

-
-
-
- - -
-
-
DOMNodeInsertedIntoDocument
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMNodeInsertedIntoDocument
InterfaceMutationEvent
Sync / AsyncSync
BubblesNo
Trusted TargetsElement, Attr, Text, Comment, DocumentType, - ProcessingInstruction
CancelableNo
Default actionNone
Context
(trusted events)		 - -
- -

A user agent MUST dispatch this event when a node - has been inserted into a document, either through direct insertion of the node or insertion of a - subtree in which it is contained. - A user agent MAY treat an Attr - node as part of an Element's subtree. - This event MUST be dispatched after the insertion has taken place. - The event target of this event MUST be the node - being inserted. - If the node is being directly inserted, the event type - DOMNodeInserted - MUST occur before this event type. -

- -
Warning

Warning! - The DOMNodeInsertedIntoDocument - event type is defined in this specification for reference and completeness, but this specification - deprecates the use of this event type. -

-
-
-
- - -
-
-
DOMNodeRemoved
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMNodeRemoved
InterfaceMutationEvent
Sync / AsyncSync
BubblesYes
Trusted TargetsElement, Attr, Text, Comment, DocumentType, - ProcessingInstruction
CancelableNo
Default actionNone
Context
(trusted events)		 - -
- -

A user agent MUST dispatch this event when a node - other than an Attr node is being removed from its parent node. - A user agent MAY dispatch this event when an - Attr node is being removed from its ownerElement - (see note below). - This event MUST be dispatched before the removal takes place. The - event target of this event MUST be the node being removed. -

- -
Note

Note: - For reliably detecting attribute removal, use the - DOMAttrModified - event type instead. -

- -
Warning

Warning! - The DOMNodeRemoved event type - is defined in this specification for reference and completeness, but this specification - deprecates the use of this event type. -

-
-
-
- - -
-
-
DOMNodeRemovedFromDocument
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMNodeRemovedFromDocument
InterfaceMutationEvent
Sync / AsyncSync
BubblesNo
Trusted TargetsElement, Attr, Text, Comment, DocumentType, - ProcessingInstruction
CancelableNo
Default actionNone
Context
(trusted events)		 - -
- -

A user agent MUST dispatch this event when a node is - being removed from a document, either through direct removal of the node or removal of a subtree in - which it is contained. - A user agent MAY treat an Attr - node as part of an Element's subtree. - This event MUST be dispatched before the removal takes place. - The event target of this event type MUST be the node - being removed. - If the node is being directly removed, the event type - DOMNodeRemoved - MUST occur before this event type. -

- -
Note

Note: - For reliably detecting attribute removal, use the - DOMAttrModified - event type instead. -

- -
Warning

Warning! - The DOMNodeRemovedFromDocument - event type is defined in this specification for reference and completeness, but this specification - deprecates the use of this event type. -

-
-
-
- - -
-
-
DOMSubtreeModified
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDOMSubtreeModified
InterfaceMutationEvent
Sync / AsyncSync
BubblesYes
Trusted TargetsWindow, Document, DocumentFragment, Element, Attr -
CancelableNo
Default actionNone
Context
(trusted events)		 - -
- -

This is a general event for notification of all changes to the document. - It can be used instead of the more specific mutation and mutation name events. - It MAY be dispatched after a single modification to the document or, at the implementation's - discretion, after multiple changes have occurred. - The latter case SHOULD generally be used to accommodate multiple changes which occur either - simultaneously or in rapid succession. - The target of this event MUST be the lowest common parent of the changes which have taken place. - This event MUST be dispatched after any other events caused by the mutation(s) have occurred. -

- -
Warning

Warning! - The DOMSubtreeModified event - type is defined in this specification for reference and completeness, but this specification - deprecates the use of this event type. -

-
-
-
- -
- From 84dd4bedcc04d65dbda6f829cbbaa0f442fc4193 Mon Sep 17 00:00:00 2001 From: Gary Kacmarcik Date: Fri, 6 Sep 2024 14:53:20 -0700 Subject: [PATCH 3/7] Remove ancient ReSpec scripts --- _todo.txt | 59 -------------- fixup-static-export.py | 179 ----------------------------------------- fixup.js | 116 -------------------------- key-table-builder.js | 69 ---------------- 4 files changed, 423 deletions(-) delete mode 100644 _todo.txt delete mode 100644 fixup-static-export.py delete mode 100644 fixup.js delete mode 100644 key-table-builder.js diff --git a/_todo.txt b/_todo.txt deleted file mode 100644 index 298f8630..00000000 --- a/_todo.txt +++ /dev/null @@ -1,59 +0,0 @@ -TODO - -code class="attr" -code class="attribute-name" - - -EventModifierInit is in the Mouse section but it's shared -between mouse and keyboard events. - -Event table text is too small for most tables. -But the big event list table needs the small text. -Add class="xxx" support to tables - - -current-click-count paragraph looks orphaned - -FATAL ERROR: No 'idl-name' refs found for 'long'. -
view
-
detail
- - -support isbn in references -eg: for DWW95 - - -biblio: -title on spec is "1.0 (second edition)" not 1.1 - [XML-NAMES11] - Tim Bray; et al. Namespaces in XML 1.1 (Second Edition). 16 August 2006. REC. URL: http://www.w3.org/TR/xml-names11/ - -unused: - [KeyProps] - Legacy Keyboard Event Properties, - D. Schepers, Editor. - World Wide Web Consortium, work in progress, 04 August 2010. - This edition of Legacy Keyboard Event Properties is https://dvcs.w3.org/hg/dom3events/raw-file/tip/html/Note-KeyProps.html. - The latest edition of Legacy Keyboard Event Properties is available at https://dvcs.w3.org/hg/dom3events/raw-file/tip/html/Note-KeyProps.html. - -unused: - [ECMAScript] - ECMAScript Language Specification, - 5.1 Edition. - European Computer Manufacturers Association, Standard ECMA-262, June 2011. - This version of the ECMAScript Language is available from http://ecma-international.org/ecma-262/5.1/. - - - - -Add missing paragraph to STOD - - -
- -

This document is derived from the specification known as Document Object Model Events - Level 3, which in turn builds on the Document Object Model Events Level 2 specification - [DOM2 Events]. -

- -
diff --git a/fixup-static-export.py b/fixup-static-export.py deleted file mode 100644 index ff778018..00000000 --- a/fixup-static-export.py +++ /dev/null @@ -1,179 +0,0 @@ -# Script to cleanup the static page generated by respec to produce a valid WD. - -import re - -# Remove attributes added by respec. -stripstr = [ - # data-bug-xxx is for the bug-assist.js script.. - ' data-bug-product="WebAppsWG" data-bug-component="DOM3 Events" typeof="bibo:Document w3p:WD" about="" property="dcterms:language" content="en" prefix="bibo: http://purl.org/ontology/bibo/ w3p: http://www.w3.org/2001/02pd/rec54#"', - ' property="dcterms:title"', - ' property="dcterms:issued" datatype="xsd:dateTime" content="2013-11-05T08:00:00.000Z"', - ' property="dcterms:issued" datatype="xsd:dateTime" content="2014-09-25T07:00:00.000Z"', - ' rel="bibo:editor" inlist=""', - ' typeof="foaf:Person"', - ' property="foaf:name"', - ' content="Gary Kacmarcik"', - ' content="Travis Leithead"', - ' property="dcterms:abstract" datatype=""', - ' typeof="bibo:Chapter" resource="#[A-Za-z0-9_-]+" rel="bibo:Chapter"', - ' aria-label="False"', - ' aria-label="True"', - ' about=""', - # More bug-assist.js stuff to remove for WD. - '', - '
Select text and
', - # Respec's TOC generator adds these turds (which the validator complains about). - '
    ', -] - -def strip(line): - for str in stripstr: - pattern = '^(.*)' - pattern += str - pattern += '(.*)$' - while True: - m = re.match(pattern, line) - if not m: - break - line = m.group(1) + m.group(2) + '\n' - return line - -# Fixup refs to WebIDL consts by adding the interface name prefix. -widlstr = [ - ['Event-', 'NONE"'], - ['Event-', 'CAPTURING_PHASE"'], - ['Event-', 'AT_TARGET"'], - ['Event-', 'BUBBLING_PHASE"'], - ['WheelEvent-', 'DOM_DELTA_PIXEL"'], - ['WheelEvent-', 'DOM_DELTA_LINE"'], - ['WheelEvent-', 'DOM_DELTA_PAGE"'], - ['KeyboardEvent-', 'DOM_KEY_LOCATION_STANDARD"'], - ['KeyboardEvent-', 'DOM_KEY_LOCATION_LEFT"'], - ['KeyboardEvent-', 'DOM_KEY_LOCATION_RIGHT"'], - ['KeyboardEvent-', 'DOM_KEY_LOCATION_NUMPAD"'], -] - -def widl(line): - for str in widlstr: - pattern = '^(.*href="#)(' - pattern += str[1] - pattern += '.*)$' - m = re.match(pattern, line) - if m: - line = m.group(1) + 'widl-' + str[0] + m.group(2) + '\n' - return line - -# Cleanup the unwieldy method names by removing the param list. -paramstr = [ - ['Event-stopPropagation', '-void'], - ['Event-preventDefault', '-void'], - ['Event-initEvent', '-void-DOMString-eventTypeArg-boolean-bubblesArg-boolean-cancelableArg'], - ['Event-stopImmediatePropagation', '-void'], - ['EventTarget-addEventListener', '-void-DOMString-type-EventListener-listener-boolean-useCapture'], - ['EventTarget-removeEventListener', '-void-DOMString-type-EventListener-listener-boolean-useCapture'], - ['EventTarget-dispatchEvent', '-boolean-Event-event'], - ['EventListener-handleEvent', '-void-Event-event'], - ['DocumentEvent-createEvent', '-Event-DOMString-eventInterface'], - ['MouseEvent-getModifierState', '-boolean-DOMString-keyArg'], - ['KeyboardEvent-getModifierState', '-boolean-DOMString-keyArg'], - ['CustomEvent-initCustomEvent', '-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-any-detailArg'], - ['UIEvent-initUIEvent', '-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-AbstractView-viewArg-long-detailArg'], - ['FocusEvent-initFocusEvent', '-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-AbstractView-viewArg-long-detailArg-EventTarget-relatedTargetArg'], - ['MouseEvent-initMouseEvent', '-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-AbstractView-viewArg-long-detailArg-long-screenXArg-long-screenYArg-long-clientXArg-long-clientYArg-boolean-ctrlKeyArg-boolean-altKeyArg-boolean-shiftKeyArg-boolean-metaKeyArg-unsigned-short-buttonArg-EventTarget-relatedTargetArg'], - ['WheelEvent-initWheelEvent', '-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-AbstractView-viewArg-long-detailArg-long-screenXArg-long-screenYArg-long-clientXArg-long-clientYArg-unsigned-short-buttonArg-EventTarget-relatedTargetArg-DOMString-modifiersListArg-double-deltaXArg-double-deltaYArg-double-deltaZArg-unsigned-long-deltaMode'], -] - -def params(line): - for str in paramstr: - pattern = '^(.*#widl-' - pattern += str[0] - pattern += ")" - pattern += str[1] - pattern += '(.*)$' - m = re.match(pattern, line) - if m: - line = m.group(1) + m.group(2) + '\n' - return line - -# Re-add the reference links which are mysteriously removed. -refstr = [ - ['ref-BCP-47', 'BCP-47'], - ['references-charmod', 'CharMod'], - ['references-DOMCore', 'DOM3 Core'], - ['references-DOM2Events', 'DOM2 Events'], - ['references-ECMAScript', 'ECMAScript'], - ['references-HTML5', 'HTML5'], - ['references-Java', 'Java'], - ['RFC2119', 'RFC2119'], - ['references-UnicodeNormalization', 'UAX #15'], - ['references-UIEvents', 'UIEvents'], - ['references-Unicode', 'Unicode'], - ['references-WebIDL', 'WEB IDL'], - ['references-Namespaces10', 'XML Namespaces 1.0'], - ['ref-ARIA', 'ARIA'], - ['ref-xforms', 'XFORMS'], - ['references-CSS2', 'CSS2.1'], - ['references-DASE', 'DASE'], - ['references-DOMLS', 'DOM3 Load and Save'], - ['references-DOMRange', 'DOM2 Range'], - ['references-DOM4', 'DOM4'], - ['references-DWW95', 'DWW95'], - ['references-HTML40', 'HTML 4.01'], - ['references-HTMLEd', 'HTML Editing'], - ['references-ISO-9995-2-3', 'ISO9995-2/3'], - ['references-ISO-9995-8', 'ISO9995-8'], - ['references-KeyEvent', 'KeyEvent for Java'], - ['references-Keys', 'Keys enumeration for .Net'], - ['references-KeyProps', 'KeyProps'], - ['references-OCAP', 'OCAP'], - ['references-pcre', 'PCRE'], - ['ref-rfc20', 'RFC20'], - #['ref-US-ASCII', 'US-ASCII'], - ['references-UAAG2', 'UAAG 2.0'], - ['references-WEB4CE', 'WEB4CE'], - ['ref-WIN1252', 'WIN1252'], - ['references-XML', 'XML 1.0'], -] - -def refs(line): - for str in refstr: - pattern = '^(.*
    \[)' - pattern += str[1] - pattern += '(\].*)$' - m = re.match(pattern, line) - if m: - line = m.group(1) + '' + str[1] + '' + m.group(2) + '\n' - return line - -# Don't use acronym inside reference name. -replacestr = [ - ['\[US-ASCII\]', '[US-ASCII]'], - ['id="idl-def-KeyboardEventInit">partial dictionary', 'id="idl-def-KeyboardEventInit-extra">partial dictionary'], - ['
    initCustomEvent', '
    initCustomEvent'], -] - -def replace(line): - for str in replacestr: - pattern = '^(.*)' - pattern += str[0] - pattern += '(.*)$' - m = re.match(pattern, line) - if m: - line = m.group(1) + str[1] + m.group(2) + '\n' - return line - -def process(fout, index, line): - line = strip(line) - line = widl(line) - line = params(line) - line = refs(line) - line = replace(line) - fout.write(line) - -# Overview.xhtml is the static file exported by respec. -with open('Overview.xhtml', 'r') as fin: - with open('WD-DOM3-Events.html', 'w') as fout: - index = 0 - for line in fin: - process(fout, index, line) - index += 1 diff --git a/fixup.js b/fixup.js deleted file mode 100644 index 2f49b391..00000000 --- a/fixup.js +++ /dev/null @@ -1,116 +0,0 @@ -/* ReSpec creates really awkward names for IDL methods, like: - * widl-MouseEvent-initMouseEvent-void-DOMString-typeArg-boolean-canBubbleArg-boolean-cancelableArg-AbstractView-viewArg-long-detailArg-long-screenXArg-long-screenYArg-long-clientXArg-long-clientYArg-boolean-ctrlKeyArg-boolean-altKeyArg-boolean-shiftKeyArg-boolean-metaKeyArg-unsigned-short-buttonArg-EventTarget-relatedTargetArg - * instead of simply: - * widl-MouseEvent-initMouseEvent - * - * This script fixes them. - */ - -bad_ids = [ - ["widl-UIEvent-initUIEvent", "-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-Window-viewArg-long-detailArg"], - ["widl-MouseEvent-getModifierState", "-boolean-DOMString-keyArg"], - ["widl-MouseEvent-initMouseEvent", "-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-Window-viewArg-long-detailArg-long-screenXArg-long-screenYArg-long-clientXArg-long-clientYArg-boolean-ctrlKeyArg-boolean-altKeyArg-boolean-shiftKeyArg-boolean-metaKeyArg-short-buttonArg-EventTarget-relatedTargetArg"], - ["widl-KeyboardEvent-getModifierState", "-boolean-DOMString-keyArg"], - ["widl-CustomEvent-initCustomEvent", "-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-any-detailArg"], - ["widl-FocusEvent-initFocusEvent", "-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-Window-viewArg-long-detailArg-EventTarget-relatedTargetArg"], - ["widl-WheelEvent-initWheelEvent", "-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-Window-viewArg-long-detailArg-long-screenXArg-long-screenYArg-long-clientXArg-long-clientYArg-short-buttonArg-EventTarget-relatedTargetArg-DOMString-modifiersListArg-double-deltaXArg-double-deltaYArg-double-deltaZArg-unsigned-long-deltaMode"], - // 2013-11-05 version: ["widl-KeyboardEvent-initKeyboardEvent", "-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-Window-viewArg-long-detailArg-DOMString-keyArg-unsigned-long-locationArg-DOMString-modifiersListArg-boolean-repeat"], - ["widl-KeyboardEvent-initKeyboardEvent", "-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-Window-viewArg-DOMString-keyArg-unsigned-long-locationArg-DOMString-modifiersListArg-boolean-repeat-DOMString-locale"], - ["widl-CompositionEvent-initCompositionEvent", "-void-DOMString-typeArg-boolean-bubblesArg-boolean-cancelableArg-Window-viewArg-DOMString-dataArg-DOMString-locale"], - - // The following definitions were removed from the D3E spec for the 2014-09-25 WD because they - // were already defined in other specs. - //["widl-Event-initEvent", "-void-DOMString-eventTypeArg-boolean-bubblesArg-boolean-cancelableArg"], - //["widl-Event-preventDefault", "-void"], - //["widl-Event-stopImmediatePropagation", "-void"], - //["widl-Event-stopPropagation", "-void"], - //["widl-EventTarget-addEventListener", "-void-DOMString-type-EventListener-listener-boolean-useCapture"], - //["widl-EventTarget-dispatchEvent", "-boolean-Event-event"], - //["widl-EventTarget-removeEventListener", "-void-DOMString-type-EventListener-listener-boolean-useCapture"], - //["widl-EventListener-handleEvent", "-void-Event-event"], - //["widl-DocumentEvent-createEvent", "-Event-DOMString-eventInterface"], -]; - -idl_constants = { - "DOM_DELTA_LINE": "#widl-WheelEvent-", - "DOM_DELTA_PAGE": "#widl-WheelEvent-", - "DOM_DELTA_PIXEL": "#widl-WheelEvent-", - "DOM_KEY_LOCATION_LEFT": "#widl-KeyboardEvent-", - "DOM_KEY_LOCATION_NUMPAD": "#widl-KeyboardEvent-", - "DOM_KEY_LOCATION_RIGHT": "#widl-KeyboardEvent-", - "DOM_KEY_LOCATION_STANDARD": "#widl-KeyboardEvent-", - "AT_TARGET": "#widl-Event-", - "BUBBLING_PHASE": "#widl-Event-", - "CAPTURING_PHASE": "#widl-Event-", - "NONE": "#widl-Event-", -}; - -function fixup_ids() { - console.log('Fixing up bad ids'); - for (var i = 0; i < bad_ids.length; i++) { - var name = bad_ids[i][0]; - var signature = bad_ids[i][1]; - var el = document.getElementById(name + signature); - if (el) { - el.id = name; - } else { - console.log('ERROR - unable to fixup: ' + name + signature); - } - } - console.log("Finished fixing up bad ids"); -} - -function fixup_idl_method_hrefs() { - console.log('Fixing up IDL hrefs'); - var els = document.getElementsByClassName('idlMethName'); - for (var i = 0; i < els.length; i++) { - var href = els[i].firstChild.attributes[0].value; - var found = false; - for (var j = 0; j < bad_ids.length; j++) { - var badid = bad_ids[j][0] + bad_ids[j][1]; - if (href == '#' + badid) { - els[i].firstChild.href = '#' + bad_ids[j][0]; - found = true; - } - } - if (!found) { - console.log('ERROR - unable to find href match: ' + href); - } - } - console.log('Finished fixing up IDL hrefs'); -} - -function fixup_idl_constant_hrefs() { - console.log('Fixing up IDL constants'); - var els = document.getElementsByClassName('idlConstName'); - for (var i = 0; i < els.length; i++) { - var href = els[i].firstChild.attributes[0].value; - var raw_href = href.slice(1) - if (raw_href in idl_constants) { - var new_href = idl_constants[raw_href] + raw_href; - //console.log('found: ' + raw_href + " changing to " + new_href); - els[i].firstChild.href = new_href; - } else { - console.log('ERROR - unable to find: ' + raw_href); - } - } - console.log('Finished fixing up IDL constants'); -} - -function fixup() { - // Wait until ReSpec is done. - var check = bad_ids[0][0] + bad_ids[0][1]; - if (!document.getElementById(check)) { - console.log("waiting"); - setTimeout(fixup, 500); - return; - } - - fixup_ids(); - fixup_idl_method_hrefs(); - fixup_idl_constant_hrefs(); -} - -if (window.addEventListener) { - window.addEventListener('load', fixup, false); -} diff --git a/key-table-builder.js b/key-table-builder.js deleted file mode 100644 index b106bc8b..00000000 --- a/key-table-builder.js +++ /dev/null @@ -1,69 +0,0 @@ -/* Convert tags into a proper of key info. - * The document must be structured as follows: - *
    - * Key description. - * ... - *
    - * where: - * name: The name of the 'key' attribute. - * noid: (optional) Don't generate an id for this key. - * - * Multiple key-tables can be present in a single document. - */ -function create_key_tables() { - keytables = document.getElementsByClassName("key-table"); - for (var i = 0; i < keytables.length; i++) { - create_key_table(keytables[i]); - } -} - -function create_key_table(tablediv) { - var table = document.createElement('table'); - table.setAttribute('class', 'data-table key-value-table'); - - var row = table.insertRow(-1); - var cell; - - // Build the header row. - cell = document.createElement('th'); - cell.setAttribute('width', '20%'); - cell.appendChild(document.createTextNode('Key')); - row.appendChild(cell); - cell = document.createElement('th'); - cell.setAttribute('width', '80%'); - cell.appendChild(document.createTextNode('Typical Usage (Informative)')); - row.appendChild(cell); - - while (tablediv.hasChildNodes()) { - var key = tablediv.removeChild(tablediv.firstChild); - if (key.nodeType != 1) { - continue; - } - var keyname = key.getAttribute('name'); - var noid = key.getAttribute('noid'); - - row = table.insertRow(-1); - var code; - - cell = row.insertCell(-1); - cell.setAttribute('class', 'key-table-key'); - code = document.createElement('code'); - if (noid == null) - code.id = 'key-' + keyname; - code.setAttribute('class', 'key'); - code.appendChild(document.createTextNode("'" + keyname + "'")); - cell.appendChild(code); - - cell = row.insertCell(-1); - while (key.hasChildNodes()) { - var child = key.removeChild(key.firstChild); - cell.appendChild(child); - } - } - - tablediv.appendChild(table); -} - -if (window.addEventListener) { - window.addEventListener('load', create_key_tables, false); -} From bf2295b120f9900f9b3bf9f263717d0882331561 Mon Sep 17 00:00:00 2001 From: Gary Kacmarcik Date: Fri, 6 Sep 2024 14:53:58 -0700 Subject: [PATCH 4/7] Remove the experimental "split" directory --- split/composition-events.bs | 638 ----- split/composition-events.html | 1947 ---------------- split/composition-events.txt | 685 ------ split/focus-events.bs | 552 ----- split/focus-events.html | 1782 -------------- split/focus-events.txt | 586 ----- split/input-events.bs | 312 --- split/input-events.html | 1513 ------------ split/input-events.txt | 345 --- split/keyboard-events.bs | 2282 ------------------ split/keyboard-events.html | 4109 --------------------------------- split/keyboard-events.txt | 2427 ------------------- split/mouse-events.bs | 1555 ------------- split/mouse-events.html | 3121 ------------------------- split/mouse-events.txt | 1916 --------------- split/ui-events.bs | 884 ------- split/ui-events.html | 1615 ------------- split/ui-events.txt | 932 -------- split/wheel-events.bs | 489 ---- split/wheel-events.html | 1640 ------------- split/wheel-events.txt | 534 ----- 21 files changed, 29864 deletions(-) delete mode 100644 split/composition-events.bs delete mode 100644 split/composition-events.html delete mode 100644 split/composition-events.txt delete mode 100644 split/focus-events.bs delete mode 100644 split/focus-events.html delete mode 100644 split/focus-events.txt delete mode 100644 split/input-events.bs delete mode 100644 split/input-events.html delete mode 100644 split/input-events.txt delete mode 100644 split/keyboard-events.bs delete mode 100644 split/keyboard-events.html delete mode 100644 split/keyboard-events.txt delete mode 100644 split/mouse-events.bs delete mode 100644 split/mouse-events.html delete mode 100644 split/mouse-events.txt delete mode 100644 split/ui-events.bs delete mode 100644 split/ui-events.html delete mode 100644 split/ui-events.txt delete mode 100644 split/wheel-events.bs delete mode 100644 split/wheel-events.html delete mode 100644 split/wheel-events.txt diff --git a/split/composition-events.bs b/split/composition-events.bs deleted file mode 100644 index 8808c623..00000000 --- a/split/composition-events.bs +++ /dev/null @@ -1,638 +0,0 @@ -

    Composition Events

    - -
    -Shortname: composition-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
-	*** Composition Events ***
-
-	Note: This is an experimental split of the UI Events spec into smaller, event-specific
-	specs. The split was made from an out-of-date snapshot, so the information here is not
-	current, so please focus on the overall structure rather than the specifics of the
-	content. If this experiment goes well, then we will split the current spec after all
-	outstanding pull requests have been handled.
-
    - -
    -urlPrefix: https://www.w3.org/TR/WebIDL/#idl-; type: type;
-	text: long
-urlPrefix: https://w3c.github.io/selection-api/#widl-Window-getSelection-Selection; type: dfn; for: Document
-	text: getSelection()
-url: https://www.w3.org/TR/2004/REC-xml-20040204/#NT-S; type: dfn;
-	text: white space
-url: https://www.w3.org/TR/uievents-key/#key-attribute-value; type: dfn; spec: uievents-key;
-	text: key attribute value
-url: https://www.w3.org/TR/uievents-key/#keys-modifier; type: dfn; spec: uievents-key;
-	text: modifier keys table
-url: https://html.spec.whatwg.org/multipage/forms.html#context-menus; type: dfn;
-	text: contextmenu
-url: https://www.w3.org/TR/pointerevents3/#pointerevent-interface; type: interface; spec: pointerevents3
-	text: PointerEvent
-url: https://dom.spec.whatwg.org/#concept-tree-ancestor; type: dfn;
-	text: ancestor
-url: https://www.w3.org/TR/CSS21/visuren.html#x43; type: dfn;
-	text: stacking context
-url: https://drafts.csswg.org/css-position-3/#positioned-box; type: dfn;
-	text: positioned
-url: https://drafts.csswg.org/css-position-4/#paint-a-stacking-context; type: dfn;
-	text: painting a stacking context
-
    - -
    -spec:dom; type:interface; text:Document
-spec:dom; type:dfn; for:Event; text:target
-spec:infra; type:dfn; text:code point
-
    - -

    Introduction

    - -

    Overview

    - - TODO. - -

    Conformance

    - - Boilerplate? - -

    Stylistic Conventions

    - -This specification follows the -Proposed W3C Specification Conventions, -with the following supplemental additions: - -* The key cap printed on a key is shown as - ↓, = or Q. This is used to refer to a - key from the user's perspective without regard for the - {{KeyboardEvent/key}} and {{KeyboardEvent/code}} values in the - generated {{KeyboardEvent}}. - -* Glyphs representing character are shown as: "𣧂". - -* Unicode character encodings are shown as: U+003d. - -* Names of key values generated by a key press (i.e., the value of - {{KeyboardEvent}}.{{KeyboardEvent/key}}) are shown as: - "ArrowDown", "=", "q" or "Q". - -* Names of key codes associated with the physical keys (i.e., the - value of {{KeyboardEvent}}.{{KeyboardEvent/code}}) are shown as: - "ArrowDown", "Equal" or "KeyQ". - - -In addition, certain terms are used in this specification with particular -meanings. The term implementation applies to a browser, content -authoring tool, or other user agent that implements this specification, -while a content author is a person who writes script or code that takes -advantage of the interfaces, methods, attributes, events, and other features -described in this specification in order to make Web applications, and a user is -the person who uses those Web applications in an implementation. - -And finally: - -

    This is a note.

    - - - -

    This is an open issue.

    - -

    This is a warning.

    - -
    -	  interface Example {
-	      // This is an IDL definition.
-	  };
-
    - -

    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 - [[#keys]] 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 {{CompositionEvent/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. - -

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

    CompositionEvent

    - - 
    -			[Exposed=Window]
-			interface CompositionEvent : UIEvent {
-				constructor(DOMString type, optional CompositionEventInit eventInitDict = {});
-				readonly attribute USVString data;
-			};
-
    - -
    -
    data
    -
    - 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). -
    -
    - -

    CompositionEventInit

    - - 
    -			dictionary CompositionEventInit : UIEventInit {
-				DOMString data = "";
-			};
-
    - -
    -
    data
    -
    - Initializes the data attribute of the - CompositionEvent object to the characters generated by the IME - composition. -
    -
    - -

    Composition Event Order

    - -

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

    - -
    - - - - -
    Event TypeNotes
    1compositionstart
    2compositionupdateMultiple events
    3compositionend
    - -

    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}}
    {{CompositionEvent/data}}    		Notes
    1compositionstart""
    User writes word on tablet surface
    2compositionupdate"test"
    User rejects first word-match suggestion, selects different match
    3compositionupdate"text"
    4compositionend"text"
    - -

    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 TypeNotes
    1keydownThe default action is prevented, e.g., by invoking {{Event/preventDefault()}}.
    No Composition Events are dispatched
    2keyup
    - - 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 TypeNotes
    1keydown
    2compositionstartThe default action is prevented, e.g., by invoking {{Event/preventDefault()}}.
    No Composition Events are dispatched
    3compositionend
    4keyup
    - -

    Key Events During Composition

    - - During the composition session, keydown and keyup events - MUST still be sent, and these events MUST have the - {{KeyboardEvent/isComposing}} attribute set to true. - - - - - - - - - - - -
    Event Type{{KeyboardEvent}}
    {{KeyboardEvent/isComposing}}    		Notes
    1keydownfalseThis is the key event that initiates the composition.
    2compositionstart
    3compositionupdate
    4keyuptrue
    ...Any key events sent during the composition session MUST have isComposing set to true.
    5keydowntrueThis is the key event that exits the composition.
    6compositionend
    7keyupfalse
    - -

    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 TypeNotes
    1beforeinput
    2compositionupdate
    Any DOM updates occur at this point.
    3input
    - -

    - 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 TypeNotes
    1beforeinput Canceling this will prevent the DOM update and the input event.
    2compositionupdate
    Any DOM updates occur at this point.
    3inputSent only if the DOM was updated.
    4compositionend
    - -

    Composition Event Types

    - -

    compositionstart

    - - - - - - - - - - - -
    Typecompositionstart
    Interface{{CompositionEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    ComposedYes
    Default actionStart a new composition session when a text composition system is enabled
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : focused element processing the composition
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    • {{CompositionEvent}}.{{CompositionEvent/data}} : the original string being edited, otherwise the empty string
    - - 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 - {{CompositionEvent/data}} attribute of the compositionstart - event with the text currently selected in the document (for editing - and replacement). Otherwise, the value of the - {{CompositionEvent/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 {{Event/preventDefault()}} will not - stop this event's default action. -

    - -

    compositionupdate

    - - - - - - - - - - - -
    Typecompositionupdate
    Interface{{CompositionEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableNo
    ComposedYes
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : focused element processing the composition, null if not accessible
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    • {{CompositionEvent}}.{{CompositionEvent/data}} : the string comprising the current results of the composition session, which MAY be the empty string if the content has been deleted
    - - 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 {{CompositionEvent/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 - {{CompositionEvent/data}} attribute will be set to the empty - string. - -

    compositionend

    - - - - - - - - - - - -
    Typecompositionend
    Interface{{CompositionEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableNo
    ComposedYes
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : focused element processing the composition
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    • {{CompositionEvent}}.{{CompositionEvent/data}} : the string comprising the final result of the composition session, which MAY be the empty string if the content has been deleted or if the composition process has been canceled
    - - 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). - -

    Legacy Event Initializers

    - - This section is normative. - - The following features are obsolete and should only be implemented by - user agents that require compatibility with legacy software. - - Early versions of this specification included an initialization method on - the interface (for example initMouseEvent) that required a long - list of parameters that, in most cases, did not fully initialize all - attributes of the event object. Because of this, event interfaces which were - derived from the basic {{Event}} interface required that the initializer of - each of the derived interfaces be called explicitly in order to - fully initialize an event. - -
    - Initializing all the attributes of a UIEvent requires calls to two - initializer methods: initEvent and - initUIEvent. -
    - - Due in part to the length of time in the development of this standard, some - implementations MAY have taken a dependency on these (now deprecated) - initializer methods. For completeness, these legacy event initializers are - described in this section. - -

    Initializers for interface CompositionEvent

    - - This section is informative - -

    - The argument list to this legacy CompositionEvent initializer does not - include the detailArg (present in other initializers) and - adds the locale argument (see [[#changes-drafts]]); it is - necessary to preserve this inconsistency for compatibility with existing - implementations. -

    - - 
    -		partial interface CompositionEvent {
-			// Originally introduced (and deprecated) in this specification
-			undefined initCompositionEvent(DOMString typeArg,
-				optional boolean bubblesArg = false,
-				optional boolean cancelableArg = false,
-				optional WindowProxy? viewArg = null,
-				optional DOMString dataArg = "");
-		};
-
    - -
    -
    initCompositionEvent(typeArg)
    -
    - Initializes attributes of a CompositionEvent - object. This method has the same behavior as - UIEvent.initUIEvent(). The value of {{UIEvent/detail}} - remains undefined. - -

    - The initCompositionEvent method is deprecated. -

    - -
    -
    DOMString typeArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    boolean bubblesArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    boolean cancelableArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    Window? viewArg
    -
    - Specifies {{UIEvent/view}}. This value MAY be null. -
    - -
    DOMString dataArg
    -
    - Specifies {{CompositionEvent/data}}. -
    -
    -
    -
    - -

    Security Considerations

    - - TODO - Add specific concerns for this spec - -

    Acknowledgements

    - - TODO - -

    Refs to other UIEvent specs \[DELETE]

    - - This section will be deleted. - - Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references. - - beforeinput - keydown - keyup - input - -

    Things defined in other sections

    -

    Activation triggers and behavior

    -

    Default actions and cancelable events

    -

    Event dispatch and DOM event flow

    -

    Web browsers and other dynamic or interactive user agents

    -

    Authoring tools

    - -

    Things defined in KeyboardEvents

    -

    Keyboard events and key values

    -

    Input Method Editors

    -

    Key Legends

    - -

    Things defined in Changes

    -

    Changes between different drafts of UI Events

    - -

    Glossary \[DELETE]

    - -This section will be deleted. - -Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline. - -: 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 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 - [[#event-flow-activation]] for more details. - -: activation trigger -:: An event which is defined to initiate an activation behavior. Refer - to [[#event-flow-activation]] for more details. - -: 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 - [[#event-flow-default-cancel]]. - -: 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 event - target. Each event is an instantiation of one specific event - type. - -: event target -:: The object to which an event is targeted using the [[#event-flow]]. - The event target is the value of the {{Event/target}} attribute. - -: 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 UI Events, and they integrate and extend the objects - and models defined in this specification. - -: IME -: input method editor -:: An input method editor (IME), also known as a front end - processor, is an application that performs the conversion between - keystrokes and ideographs or other characters, usually by user-guided - dictionary lookup, often used in East Asian languages (e.g., Chinese, - Japanese, Korean). An IME MAY also be used for dictionary-based word - completion, such as on mobile devices. See [[#keys-IME]] for treatment of - IMEs in this specification. See also text composition system. - -: 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. - -: un-initialized value -:: The value of any event attribute (such as {{Event/bubbles}} or - {{Event/currentTarget}}) before the event has been initialized with - {{Event/initEvent()}}. The un-initialized values of an event apply - immediately after a new event has been created using the method - {{Document/createEvent()}}. - -: 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 [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the - requirements for a conforming user agent. - -: Window -:: The Window is the object referred to by the current document's - browsing context's Window Proxy object as defined in - HTML5 - [[HTML5]]. - diff --git a/split/composition-events.html b/split/composition-events.html deleted file mode 100644 index 9e1194bf..00000000 --- a/split/composition-events.html +++ /dev/null @@ -1,1947 +0,0 @@ - - - - - Composition Events - - - - - - - - - - - - - - - - -
    -

    -

    Composition Events

    -

    Editor’s Draft,

    -
    - More details about this document -
    -
    -
    This version: -
    https://w3c.github.io/uievents/ -
    Latest published version: -
    https://www.w3.org/TR/uievents/ -
    Feedback: -
    GitHub -
    Editors: -
    (Google) -
    (Microsoft) -
    Former Editor: -
    Doug Schepers (Mar 2008 - May 2011) -
    Tests: -
    web-platform-tests uievents/ (ongoing work) -
    -
    -
    -
    -

    Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

    -
    -
    -
    -

    Abstract

    -

    *** Composition Events ***

    -

    Note: This is an experimental split of the UI Events spec into smaller, event-specific - - specs. The split was made from an out-of-date snapshot, so the information here is not - current, so please focus on the overall structure rather than the specifics of the - content. If this experiment goes well, then we will split the current spec after all - outstanding pull requests have been handled.

    -
    -

    Status of this document

    -
    -

    This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

    -

    This document was published by the Web Applications Working Group as an Editors Draft. This document is intended to become a W3C Recommendation.

    -

    -

    This document was published by the Web Applications Working Group as a Working Draft. - - Feedback and comments on this specification are welcome. Please use GitHub issues Historical discussions can be found in the public-webapps@w3.org archives.

    -

    Publication as an Editors Draft does not imply endorsement by W3C and its Members. This is a draft document and may - be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite - this document as other than work in progress.

    -

    This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

    -

    This document is governed by the 2 November 2021 W3C Process Document.

    -
    -
    - -
    -

    1. Introduction

    -

    1.1. Overview

    -

    TODO.

    -

    1.2. Conformance

    -

    Boilerplate?

    -

    2. Stylistic Conventions

    -

    This specification follows the Proposed W3C Specification Conventions, -with the following supplemental additions:

    -
      -
    • -

      The key cap printed on a key is shown as ↓, = or Q. This is used to refer to a -key from the user’s perspective without regard for the key and code values in the -generated KeyboardEvent.

      -
    • -

      Glyphs representing character are shown as: "𣧂".

      -
    • -

      Unicode character encodings are shown as: U+003d.

      -
    • -

      Names of key values generated by a key press (i.e., the value of KeyboardEvent.key) are shown as: "ArrowDown", "=", "q" or "Q".

      -
    • -

      Names of key codes associated with the physical keys (i.e., the -value of KeyboardEvent.code) are shown as: "ArrowDown", "Equal" or "KeyQ".

      -
    -

    In addition, certain terms are used in this specification with particular -meanings. The term implementation applies to a browser, content -authoring tool, or other user agent that implements this specification, -while a content author is a person who writes script or code that takes -advantage of the interfaces, methods, attributes, events, and other features -described in this specification in order to make Web applications, and a user is -the person who uses those Web applications in an implementation.

    -

    And finally:

    -

    This is a note.

    -

    This is an open issue.

    -

    This is a warning.

    -
    interface Example {
-    // This is an IDL definition.
-};
-
    -

    3. 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 § 7.2.1 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.

    -

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

    -

    3.1.1. CompositionEvent

    -
    [Exposed=Window]
-interface CompositionEvent : UIEvent {
-  constructor(DOMString type, optional CompositionEventInit eventInitDict = {});
-  readonly attribute USVString data;
-};
-
    -
    -
    data, of type USVString, 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).

    -
    -

    3.1.2. CompositionEventInit

    -
    dictionary CompositionEventInit : 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. -
    -

    3.2. Composition Event Order

    -

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

    - - - - - - - -
    - Event Type - Notes -
    1 - compositionstart - -
    2 - compositionupdate - Multiple events -
    3 - compositionend - -
    -

    3.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" - -
    -

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

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

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

    3.7. Composition Event Types

    -

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

    -

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

    -

    3.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).

    -

    4. Legacy Event Initializers

    -

    This section is normative.

    -

    The following features are obsolete and should only be implemented by user agents that require compatibility with legacy software.

    -

    Early versions of this specification included an initialization method on - the interface (for example initMouseEvent) that required a long - list of parameters that, in most cases, did not fully initialize all - attributes of the event object. Because of this, event interfaces which were - derived from the basic Event interface required that the initializer of each of the derived interfaces be called explicitly in order to - fully initialize an event.

    -
    Initializing all the attributes of a UIEvent requires calls to two - initializer methods: initEvent and initUIEvent.
    -

    Due in part to the length of time in the development of this standard, some - implementations MAY have taken a dependency on these (now deprecated) - initializer methods. For completeness, these legacy event initializers are - described in this section.

    -

    4.1. Initializers for interface CompositionEvent

    -

    This section is informative

    -

    The argument list to this legacy CompositionEvent initializer does not - include the detailArg (present in other initializers) and - adds the locale argument (see § 7.3.1 Changes between different drafts of UI Events); it is - necessary to preserve this inconsistency for compatibility with existing - implementations.

    -
    partial interface CompositionEvent {
-  // Originally introduced (and deprecated) in this specification
-  undefined initCompositionEvent(DOMString typeArg,
-    optional boolean bubblesArg = false,
-    optional boolean cancelableArg = false,
-    optional WindowProxy? viewArg = null,
-    optional DOMString dataArg = "");
-};
-
    -
    -
    initCompositionEvent(typeArg) -
    - Initializes attributes of a CompositionEvent object. This method has the same behavior as UIEvent.initUIEvent(). The value of detail remains undefined. -

    The initCompositionEvent method is deprecated.

    -
    -
    DOMString typeArg -
    Refer to the initEvent() method for a description of this parameter. -
    boolean bubblesArg -
    Refer to the initEvent() method for a description of this parameter. -
    boolean cancelableArg -
    Refer to the initEvent() method for a description of this parameter. -
    Window? viewArg -
    Specifies view. This value MAY be null. -
    DOMString dataArg -
    Specifies data. -
    -
    -

    5. Security Considerations

    -

    TODO - Add specific concerns for this spec

    -

    6. Acknowledgements

    -

    TODO

    -

    7. Refs to other UIEvent specs [DELETE]

    -

    This section will be deleted.

    -

    Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references.

    -

    beforeinput keydown keyup input

    -

    7.1. Things defined in other sections

    -

    7.1.1. Activation triggers and behavior

    -

    7.1.2. Default actions and cancelable events

    -

    7.1.3. Event dispatch and DOM event flow

    -

    7.1.4. Web browsers and other dynamic or interactive user agents

    -

    7.1.5. Authoring tools

    -

    7.2. Things defined in KeyboardEvents

    -

    7.2.1. Keyboard events and key values

    -

    7.2.2. Input Method Editors

    -

    7.2.3. Key Legends

    -

    7.3. Things defined in Changes

    -

    7.3.1. Changes between different drafts of UI Events

    -

    8. Glossary [DELETE]

    -

    This section will be deleted.

    -

    Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline.

    -
    -
    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 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 § 7.1.1 Activation triggers and behavior for more details.

    -
    activation trigger -
    -

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

    -
    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 preventDefault() method. For more details, see § 7.1.2 Default actions and cancelable events.

    -
    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 event -target. Each event is an instantiation of one specific event -type.

    -
    event target -
    -

    The object to which an event is targeted using the § 7.1.3 Event dispatch and DOM event flow. -The event target is the value of the target attribute.

    -
    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 UI Events, and they integrate and extend the objects -and models defined in this specification.

    -
    IME -
    input method editor -
    -

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

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

    -
    un-initialized value -
    -

    The value of any event attribute (such as bubbles or currentTarget) before the event has been initialized with initEvent(). The un-initialized values of an event apply -immediately after a new event has been created using the method createEvent().

    -
    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 § 7.1.4 Web browsers and other dynamic or interactive user agents and § 7.1.5 Authoring tools for details on the -requirements for a conforming user agent.

    -
    Window -
    -

    The Window is the object referred to by the current document’s -browsing context’s Window Proxy object as defined in HTML5 [HTML5].

    -
    -
    -
    -

    Conformance

    -

    Document conventions

    -

    Conformance requirements are expressed - with a combination of descriptive assertions - and RFC 2119 terminology. - The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” - in the normative parts of this document - are to be interpreted as described in RFC 2119. - However, for readability, - these words do not appear in all uppercase letters in this specification.

    -

    All of the text of this specification is normative - except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

    -

    Examples in this specification are introduced with the words “for example” - or are set apart from the normative text - with class="example", - like this:

    -
    - -

    This is an example of an informative example.

    -
    -

    Informative notes begin with the word “Note” - and are set apart from the normative text - with class="note", - like this:

    -

    Note, this is an informative note.

    -
    -

    Conformant Algorithms

    -

    Requirements phrased in the imperative as part of algorithms - (such as "strip any leading space characters" - or "return false and abort these steps") - are to be interpreted with the meaning of the key word - ("must", "should", "may", etc) - used in introducing the algorithm.

    -

    Conformance requirements phrased as algorithms or specific steps - can be implemented in any manner, - so long as the end result is equivalent. - In particular, the algorithms defined in this specification - are intended to be easy to understand - and are not intended to be performant. - Implementers are encouraged to optimize.

    -
    -
    - -

    Index

    -

    Terms defined by this specification

    - -

    Terms defined by reference

    -
      -
    • - [DOM] defines the following terms: -
        -
      • Event -
      • bubbles -
      • createEvent(interface) -
      • currentTarget -
      • document -
      • initEvent(type) -
      • preventDefault() -
      • target -
      -
    • - [HTML] defines the following terms: -
        -
      • WindowProxy -
      -
    • - [UIEVENTS] defines the following terms: -
        -
      • KeyboardEvent -
      • UIEvent -
      • UIEventInit -
      • code -
      • detail -
      • isComposing -
      • key -
      • view -
      -
    • - [WEBDRIVER-BIDI] defines the following terms: -
        -
      • event type -
      -
    • - [WEBIDL] defines the following terms: -
        -
      • DOMString -
      • Exposed -
      • USVString -
      • boolean -
      • undefined -
      -
    -

    References

    -

    Normative References

    -
    -
    [DOM] -
    Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/ -
    [HTML] -
    Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/ -
    [RFC2119] -
    S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119 -
    [UIEVENTS] -
    Gary Kacmarcik; Travis Leithead. UI Events. URL: https://w3c.github.io/uievents/ -
    [WEBDRIVER-BIDI] -
    WebDriver BiDi URL: https://w3c.github.io/webdriver-bidi/ -
    [WEBIDL] -
    Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/ -
    -

    Informative References

    -
    -
    [HTML5] -
    Ian Hickson; et al. HTML5. URL: https://www.w3.org/html/wg/drafts/html/master/ -
    [UAX15] -
    Ken Whistler. Unicode Normalization Forms. 17 August 2022. Unicode Standard Annex #15. URL: https://www.unicode.org/reports/tr15/tr15-53.html -
    [Unicode] -
    The Unicode Standard. URL: https://www.unicode.org/versions/latest/ -
    -

    IDL Index

    -
    [Exposed=Window]
-interface CompositionEvent : UIEvent {
-  constructor(DOMString type, optional CompositionEventInit eventInitDict = {});
-  readonly attribute USVString data;
-};
-
-dictionary CompositionEventInit : UIEventInit {
-  DOMString data = "";
-};
-
-partial interface CompositionEvent {
-  // Originally introduced (and deprecated) in this specification
-  undefined initCompositionEvent(DOMString typeArg,
-    optional boolean bubblesArg = false,
-    optional boolean cancelableArg = false,
-    optional WindowProxy? viewArg = null,
-    optional DOMString dataArg = "");
-};
-
-
    - - - diff --git a/split/composition-events.txt b/split/composition-events.txt deleted file mode 100644 index 852d65b4..00000000 --- a/split/composition-events.txt +++ /dev/null @@ -1,685 +0,0 @@ -

    Composition Events

    - -
    -Shortname: composition-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
-	*** Composition Events ***
-	
-	Note: This is an experimental split of the UI Events spec into smaller, event-specific
-	specs. The split was made from an out-of-date snapshot, so the information here is not
-	current, so please focus on the overall structure rather than the specifics of the
-	content. If this experiment goes well, then we will split the current spec after all
-	outstanding pull requests have been handled.
-
    - -
    -urlPrefix: https://www.w3.org/TR/WebIDL/#idl-; type: type;
-	text: long
-urlPrefix: https://w3c.github.io/selection-api/#widl-Window-getSelection-Selection; type: dfn; for: Document
-	text: getSelection()
-url: https://www.w3.org/TR/2004/REC-xml-20040204/#NT-S; type: dfn;
-	text: white space
-url: https://www.w3.org/TR/uievents-key/#key-attribute-value; type: dfn; spec: uievents-key;
-	text: key attribute value
-url: https://www.w3.org/TR/uievents-key/#keys-modifier; type: dfn; spec: uievents-key;
-	text: modifier keys table
-url: https://html.spec.whatwg.org/multipage/forms.html#context-menus; type: dfn;
-	text: contextmenu
-url: https://www.w3.org/TR/pointerevents3/#pointerevent-interface; type: interface; spec: pointerevents3
-	text: PointerEvent
-url: https://dom.spec.whatwg.org/#concept-tree-ancestor; type: dfn;
-	text: ancestor
-url: https://www.w3.org/TR/CSS21/visuren.html#x43; type: dfn;
-	text: stacking context
-url: https://drafts.csswg.org/css-position-3/#positioned-box; type: dfn;
-	text: positioned
-url: https://drafts.csswg.org/css-position-4/#paint-a-stacking-context; type: dfn;
-	text: painting a stacking context
-
    - -
    -spec:dom; type:interface; text:Document
-spec:dom; type:dfn; for:Event; text:target
-spec:infra; type:dfn; text:code point
-
    - -

    Introduction

    - -

    Overview

    - - TODO. - -

    Conformance

    - - Boilerplate? - -

    Stylistic Conventions

    - -This specification follows the -Proposed W3C Specification Conventions, -with the following supplemental additions: - -* The key cap printed on a key is shown as - KEYCAP{↓}, KEYCAP{=} or KEYCAP{Q}. This is used to refer to a - key from the user's perspective without regard for the - {{KeyboardEvent/key}} and {{KeyboardEvent/code}} values in the - generated {{KeyboardEvent}}. - -* Glyphs representing character are shown as: GLYPH{𣧂}. - -* Unicode character encodings are shown as: UNI{U+003d}. - -* Names of key values generated by a key press (i.e., the value of - {{KeyboardEvent}}.{{KeyboardEvent/key}}) are shown as: - KEY{ArrowDown}, KEY_NOLINK{=}, KEY_NOLINK{q} or KEY_NOLINK{Q}. - -* Names of key codes associated with the physical keys (i.e., the - value of {{KeyboardEvent}}.{{KeyboardEvent/code}}) are shown as: - CODE{ArrowDown}, CODE{Equal} or CODE{KeyQ}. - - -In addition, certain terms are used in this specification with particular -meanings. The term implementation applies to a browser, content -authoring tool, or other user agent that implements this specification, -while a content author is a person who writes script or code that takes -advantage of the interfaces, methods, attributes, events, and other features -described in this specification in order to make Web applications, and a user is -the person who uses those Web applications in an implementation. - -And finally: - -

    This is a note.

    - - - -

    This is an open issue.

    - -

    This is a warning.

    - -
    -	  interface Example {
-	      // This is an IDL definition.
-	  };
-
    - -

    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 - [[#keys]] for examples on how Composition Events are used in combination - with keyboard events. - - Conceptually, a composition session consists of one EVENT{compositionstart} - event, one or more EVENT{compositionupdate} events, and one - EVENT{compositionend} event, with the value of the {{CompositionEvent/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 EVENT{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. - -

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

    CompositionEvent

    - - 
    -			[Exposed=Window]
-			interface CompositionEvent : UIEvent {
-				constructor(DOMString type, optional CompositionEventInit eventInitDict = {});
-				readonly attribute USVString data;
-			};
-
    - -
    -
    data
    -
    - 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). -
    -
    - -

    CompositionEventInit

    - - 
    -			dictionary CompositionEventInit : UIEventInit {
-				DOMString data = "";
-			};
-
    - -
    -
    data
    -
    - Initializes the data attribute of the - CompositionEvent object to the characters generated by the IME - composition. -
    -
    - -

    Composition Event Order

    - -

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

    - - ++---+-------------------+---------------------------------------------+ - =| # | Event Type | Notes | - +---+-------------------+---------------------------------------------+ - +| 1 | compositionstart | | - +| 2 | compositionupdate | Multiple events | - +| 3 | compositionend | | - ++---+-------------------+---------------------------------------------+ - -

    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}}
    | Notes | - | | | {{CompositionEvent/data}} | | - +---+-------------------+------------o--------------+------------------------------+ - +| 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" | | - ++---+-------------------+----------------------------------------------------------+ - -

    Canceling Composition Events

    - - If a EVENT{keydown} event is canceled then any Composition Events that - would have fired as a result of that EVENT{keydown} SHOULD not be - dispatched: - - ++---+------------+----------------------------------------------------+ - =| # | Event Type | Notes | - +---+------------+----------------------------------------------------+ - +| 1 | keydown | The default action is prevented, e.g., by | - | | | invoking {{Event/preventDefault()}}. | - +| | | No Composition Events are dispatched | - +| 2 | keyup | | - ++---+------------+----------------------------------------------------+ - - If the initial EVENT{compositionstart} event is canceled then the text - composition session SHOULD be terminated. Regardless of whether or not - the composition session is terminated, the EVENT{compositionend} event - MUST be sent. - - ++---+------------------+-----------------------------------------------+ - =| # | Event Type | Notes | - +---+------------------+-----------------------------------------------+ - +| 1 | keydown | | - +| 2 | compositionstart | The default action is prevented, | - | | | e.g., by invoking {{Event/preventDefault()}}. | - +| | | No Composition Events are dispatched | - +| 3 | compositionend | | - +| 4 | keyup | | - ++---+------------------+-----------------------------------------------+ - -

    Key Events During Composition

    - - During the composition session, EVENT{keydown} and EVENT{keyup} events - MUST still be sent, and these events MUST have the - {{KeyboardEvent/isComposing}} attribute set to true. - - ++---+-------------------+-------------------------------+------------------------------+ - =| # | Event Type | {{KeyboardEvent}}
    | Notes | - | | | {{KeyboardEvent/isComposing}} | | - +---+-------------------+--------------o----------------+------------------------------+ - +| 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 | | - ++---+-------------------+-------------------------------+------------------------------+ - -

    Input Events During Composition

    - - During the composition session, the EVENT{compositionupdate} MUST be - dispatched after the EVENT{beforeinput} is sent, but before the - EVENT{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 EVENT{beforeinput} and EVENT{input} events are sent along with the - EVENT{compositionupdate} event whenever the DOM is updated as part of - the composition. Since there are no DOM updates associated with the - EVENT{compositionend} event, EVENT{beforeinput} and EVENT{input} events - should not be sent at that time. - - ++---+-------------------+-----------------------------------------------+ - =| # | Event Type | Notes | - +---+-------------------+-----------------------------------------------+ - +| 1 | beforeinput | Canceling this will prevent the DOM | - | | | update and the EVENT{input} event. | - +| 2 | compositionupdate | | - +| | | Any DOM updates occur at this point. | - +| 3 | input | Sent only if the DOM was updated. | - +| 4 | compositionend | | - ++---+-------------------+-----------------------------------------------+ - -

    Composition Event Types

    - -

    compositionstart

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| 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) |
    • {{Event}}.{{Event/target}} : focused element processing the composition
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    • {{CompositionEvent}}.{{CompositionEvent/data}} : the original string being | - | | edited, otherwise the empty string
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - 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 EVENT{keydown} event, - but speech or handwriting recognition systems MAY send this event - type without keyboard events. Some implementations MAY populate the - {{CompositionEvent/data}} attribute of the EVENT{compositionstart} - event with the text currently selected in the document (for editing - and replacement). Otherwise, the value of the - {{CompositionEvent/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 EVENT{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 {{Event/preventDefault()}} will not - stop this event's default action. -

    - -

    compositionupdate

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| Type | compositionupdate | - +| Interface | {{CompositionEvent}} | - +| Sync / Async | Sync | - +| Bubbles | Yes | - +| Trusted Targets | Element | - +| Cancelable | No | - +| Composed | Yes | - +| Default action | None | - +| Context
    |
      | - | (trusted events) |
    • {{Event}}.{{Event/target}} : focused element processing the composition, | - | | null if not accessible
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    • {{CompositionEvent}}.{{CompositionEvent/data}} : the string comprising the | - | | current results of the composition session, which MAY be the empty string | - | | if the content has been deleted
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - 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 {{CompositionEvent/data}}. - - In text composition systems which keep the ongoing - composition in sync with the input control, the - EVENT{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 EVENT{compositionend} event, and the - {{CompositionEvent/data}} attribute will be set to the empty - string. - -

    compositionend

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| Type | compositionend | - +| Interface | {{CompositionEvent}} | - +| Sync / Async | Sync | - +| Bubbles | Yes | - +| Trusted Targets | Element | - +| Cancelable | No | - +| Composed | Yes | - +| Default action | None | - +| Context
    |
      | - | (trusted events) |
    • {{Event}}.{{Event/target}} : focused element processing the composition
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    • {{CompositionEvent}}.{{CompositionEvent/data}} : the string comprising the final | - | | result of the composition session, which MAY be the empty string if the | - | | content has been deleted or if the composition process has been canceled
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - A user agent MUST dispatch this event when a text - composition system completes or cancels the current composition - session, and the EVENT{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). - -

    Legacy Event Initializers

    - - This section is normative. - - The following features are obsolete and should only be implemented by - user agents that require compatibility with legacy software. - - Early versions of this specification included an initialization method on - the interface (for example initMouseEvent) that required a long - list of parameters that, in most cases, did not fully initialize all - attributes of the event object. Because of this, event interfaces which were - derived from the basic {{Event}} interface required that the initializer of - each of the derived interfaces be called explicitly in order to - fully initialize an event. - -
    - Initializing all the attributes of a UIEvent requires calls to two - initializer methods: initEvent and - initUIEvent. -
    - - Due in part to the length of time in the development of this standard, some - implementations MAY have taken a dependency on these (now deprecated) - initializer methods. For completeness, these legacy event initializers are - described in this section. - -

    Initializers for interface CompositionEvent

    - - This section is informative - -

    - The argument list to this legacy CompositionEvent initializer does not - include the detailArg (present in other initializers) and - adds the locale argument (see [[#changes-drafts]]); it is - necessary to preserve this inconsistency for compatibility with existing - implementations. -

    - - 
    -		partial interface CompositionEvent {
-			// Originally introduced (and deprecated) in this specification
-			undefined initCompositionEvent(DOMString typeArg,
-				optional boolean bubblesArg = false,
-				optional boolean cancelableArg = false,
-				optional WindowProxy? viewArg = null,
-				optional DOMString dataArg = "");
-		};
-
    - -
    -
    initCompositionEvent(typeArg)
    -
    - Initializes attributes of a CompositionEvent - object. This method has the same behavior as - UIEvent.initUIEvent(). The value of {{UIEvent/detail}} - remains undefined. - -

    - The initCompositionEvent method is deprecated. -

    - -
    -
    DOMString typeArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    boolean bubblesArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    boolean cancelableArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    Window? viewArg
    -
    - Specifies {{UIEvent/view}}. This value MAY be null. -
    - -
    DOMString dataArg
    -
    - Specifies {{CompositionEvent/data}}. -
    -
    -
    -
    - -

    Security Considerations

    - - TODO - Add specific concerns for this spec - -

    Acknowledgements

    - - TODO - -

    Refs to other UIEvent specs \[DELETE]

    - - This section will be deleted. - - Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references. - - beforeinput - keydown - keyup - input - -

    Things defined in other sections

    -

    Activation triggers and behavior

    -

    Default actions and cancelable events

    -

    Event dispatch and DOM event flow

    -

    Web browsers and other dynamic or interactive user agents

    -

    Authoring tools

    - -

    Things defined in KeyboardEvents

    -

    Keyboard events and key values

    -

    Input Method Editors

    -

    Key Legends

    - -

    Things defined in Changes

    -

    Changes between different drafts of UI Events

    - -

    Glossary \[DELETE]

    - -This section will be deleted. - -Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline. - -: 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 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 - [[#event-flow-activation]] for more details. - -: activation trigger -:: An event which is defined to initiate an activation behavior. Refer - to [[#event-flow-activation]] for more details. - -: 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 - [[#event-flow-default-cancel]]. - -: 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 event - target. Each event is an instantiation of one specific event - type. - -: event target -:: The object to which an event is targeted using the [[#event-flow]]. - The event target is the value of the {{Event/target}} attribute. - -: 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 UI Events, and they integrate and extend the objects - and models defined in this specification. - -: IME -: input method editor -:: An input method editor (IME), also known as a front end - processor, is an application that performs the conversion between - keystrokes and ideographs or other characters, usually by user-guided - dictionary lookup, often used in East Asian languages (e.g., Chinese, - Japanese, Korean). An IME MAY also be used for dictionary-based word - completion, such as on mobile devices. See [[#keys-IME]] for treatment of - IMEs in this specification. See also text composition system. - -: 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. - -: un-initialized value -:: The value of any event attribute (such as {{Event/bubbles}} or - {{Event/currentTarget}}) before the event has been initialized with - {{Event/initEvent()}}. The un-initialized values of an event apply - immediately after a new event has been created using the method - {{Document/createEvent()}}. - -: 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 [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the - requirements for a conforming user agent. - -: Window -:: The Window is the object referred to by the current document's - browsing context's Window Proxy object as defined in - HTML5 - [[HTML5]]. - diff --git a/split/focus-events.bs b/split/focus-events.bs deleted file mode 100644 index 245b6463..00000000 --- a/split/focus-events.bs +++ /dev/null @@ -1,552 +0,0 @@ -

    Focus Events

    - -
    -Shortname: focus-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
-	*** Focus Events ***
-
-	Note: This is an experimental split of the UI Events spec into smaller, event-specific
-	specs. The split was made from an out-of-date snapshot, so the information here is not
-	current, so please focus on the overall structure rather than the specifics of the
-	content. If this experiment goes well, then we will split the current spec after all
-	outstanding pull requests have been handled.
-
    - -
    -urlPrefix: https://www.w3.org/TR/WebIDL/#idl-; type: type;
-	text: long
-urlPrefix: https://w3c.github.io/selection-api/#widl-Window-getSelection-Selection; type: dfn; for: Document
-	text: getSelection()
-url: https://www.w3.org/TR/2004/REC-xml-20040204/#NT-S; type: dfn;
-	text: white space
-url: https://www.w3.org/TR/uievents-key/#key-attribute-value; type: dfn; spec: uievents-key;
-	text: key attribute value
-url: https://www.w3.org/TR/uievents-key/#keys-modifier; type: dfn; spec: uievents-key;
-	text: modifier keys table
-url: https://html.spec.whatwg.org/multipage/forms.html#context-menus; type: dfn;
-	text: contextmenu
-url: https://www.w3.org/TR/pointerevents3/#pointerevent-interface; type: interface; spec: pointerevents3
-	text: PointerEvent
-url: https://dom.spec.whatwg.org/#concept-tree-ancestor; type: dfn;
-	text: ancestor
-url: https://www.w3.org/TR/CSS21/visuren.html#x43; type: dfn;
-	text: stacking context
-url: https://drafts.csswg.org/css-position-3/#positioned-box; type: dfn;
-	text: positioned
-url: https://drafts.csswg.org/css-position-4/#paint-a-stacking-context; type: dfn;
-	text: painting a stacking context
-
    - -
    -spec:dom; type:interface; text:Document
-spec:dom; type:dfn; for:Event; text:target
-spec:infra; type:dfn; text:code point
-
    - -

    Introduction

    - -

    Overview

    - - TODO. - -

    Conformance

    - - Boilerplate? - -

    Stylistic Conventions

    - -This specification follows the -Proposed W3C Specification Conventions, -with the following supplemental additions: - -

    This is a note.

    - - - -

    This is an open issue.

    - -

    This is a warning.

    - -
    -	  interface Example {
-	      // This is an IDL definition.
-	  };
-
    - -

    Focus Events

    - -

    - This interface and its associated event types and - [[#events-focusevent-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. -

    - -

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

    FocusEvent

    - - 
    -			[Exposed=Window]
-			interface FocusEvent : UIEvent {
-				constructor(DOMString type, optional FocusEventInit eventInitDict = {});
-				readonly attribute EventTarget? 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. -
    -
    - -

    FocusEventInit

    - - 
    -			dictionary FocusEventInit : UIEventInit {
-				EventTarget? relatedTarget = null;
-			};
-
    - -
    -
    FocusEventInit . relatedTarget
    -
    - The {{FocusEventInit/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). -
    -
    - -

    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 TypeNotes
    User shifts focus
    1focusSent after first target element receives focus
    2focusinFollows the focus event
    User shifts focus
    3blurSent after first target element loses focus
    4focusoutFollows the blur event
    5focusSent after second target element receives focus
    6focusinFollows the focus event
    - -

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

    - -

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

    Focus Event Types

    - - The Focus event types are listed below. - -

    blur

    - - - - - - - - - - - -
    Typeblur
    Interface{{FocusEvent}}
    Sync / AsyncSync
    BubblesNo
    Trusted TargetsWindow, Element
    CancelableNo
    ComposedYes
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : event target losing focus
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    • {{FocusEvent}}.{{FocusEvent/relatedTarget}} : event target receiving focus.
    - - 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 does not bubble. - -

    focus

    - - - - - - - - - - - -
    Typefocus
    Interface{{FocusEvent}}
    Sync / AsyncSync
    BubblesNo
    Trusted TargetsWindow, Element
    CancelableNo
    ComposedYes
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : event target receiving focus
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    • {{FocusEvent}}.{{FocusEvent/relatedTarget}} : event target losing focus (if any).
    - - 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 does not bubble. - -

    focusin

    - - - - - - - - - - - -
    Typefocusin
    Interface{{FocusEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsWindow, Element
    CancelableNo
    ComposedYes
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : event target receiving focus
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    • {{FocusEvent}}.{{FocusEvent/relatedTarget}} : event target losing focus (if any).
    - - A user agent MUST dispatch this event when an event target - receives focus. The event target MUST be the element which - received focus. The [=focus=] event MUST fire before the dispatch of - this event type. This event type is similar to [=focus=], but does - bubble. - -

    focusout

    - - - - - - - - - - - -
    Typefocusout
    Interface{{FocusEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsWindow, Element
    CancelableNo
    ComposedYes
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : event target losing focus
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    • {{FocusEvent}}.{{FocusEvent/relatedTarget}} : event target receiving focus.
    - - A user agent MUST dispatch this event when an event target - loses focus. The event target MUST be the element which lost - focus. The [=blur=] event MUST fire before the dispatch of this event - type. This event type is similar to [=blur=], but does bubble. - -

    Legacy {{FocusEvent}} events

    - -

    Legacy {{FocusEvent}} event types

    - -

    DOMFocusIn

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    TypeDOMFocusIn
    Interface{{FocusEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsWindow, Element
    CancelableNo
    ComposedYes
    Default actionNone
    Context
    (trusted events)    		 -
      -
    • {{Event}}.{{Event/target}} : - event target receiving focus
      • -
    • {{UIEvent}}.{{UIEvent/view}} : - Window
      • -
    • {{UIEvent}}.{{UIEvent/detail}} : - 0
      • -
    • {{FocusEvent}}.{{FocusEvent/relatedTarget}} : - null
      • -
    -
    - - 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 - MUST be dispatched after the event type focus. - -

    - The DOMFocusIn event type is defined in this - specification for reference and completeness, but this - specification deprecates the use of this event type in - favor of the related event types focus and focusin. -

    - -

    DOMFocusOut

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    TypeDOMFocusOut
    Interface{{FocusEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsWindow, Element
    CancelableNo
    ComposedYes
    Default actionNone
    Context
    (trusted events)    		 -
      -
    • {{Event}}.{{Event/target}} : - event target losing focus
      • -
    • {{UIEvent}}.{{UIEvent/view}} : - Window
      • -
    • {{UIEvent}}.{{UIEvent/detail}} : - 0
      • -
    • {{FocusEvent}}.{{FocusEvent/relatedTarget}} : - null
      • -
    -
    - - 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 MUST be - dispatched after the event type blur. - -

    - The DOMFocusOut event type is defined in this - specification for reference and completeness, but this - specification deprecates the use of this event type in - favor of the related event types blur and focusout. -

    - -

    Legacy FocusEvent event order

    - - The following is the typical sequence of events when a focus is shifted - between elements, including the deprecated DOMFocusIn and - DOMFocusOut events. The order shown assumes that no element is - initially focused. - - - - - - - - - - - - - - -
    Event TypeNotes
    User shifts focus
    1focusinSent before first target element receives focus
    2focusSent after first target element receives focus
    3DOMFocusInIf supported
    User shifts focus
    4focusoutSent before first target element loses focus
    5focusinSent before second target element receives focus
    6blurSent after first target element loses focus
    7DOMFocusOutIf supported
    8focusSent after second target element receives focus
    9DOMFocusInIf supported
    - -

    Security Considerations

    - - TODO - Add specific concerns for this spec - -

    Acknowledgements

    - - TODO - -

    Refs to other UIEvent specs \[DELETE]

    - - This section will be deleted. - - Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references. - -

    Things defined in other sections

    - -

    Activation triggers and behavior

    -

    Composition Events

    -

    Default actions and cancelable events

    -

    Event dispatch and DOM event flow

    -

    Web browsers and other dynamic or interactive user agents

    -

    Authoring tools

    - -

    Glossary \[DELETE]

    - -This section will be deleted. - -Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline. - -: 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 event - target. Each event is an instantiation of one specific event - type. - -: event focus -:: Event focus is a special state of receptivity and concentration on a - 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 - [[#events-focusevent-doc-focus]]. - -: event target -:: The object to which an event is targeted using the [[#event-flow]]. - The event target is the value of the {{Event/target}} attribute. - -: event focus ring -:: An event focus ring is an ordered set of event 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. - -: 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 UI Events, and they integrate and extend the objects - and models defined in this specification. - -: un-initialized value -:: The value of any event attribute (such as {{Event/bubbles}} or - {{Event/currentTarget}}) before the event has been initialized with - {{Event/initEvent()}}. The un-initialized values of an event apply - immediately after a new event has been created using the method - {{Document/createEvent()}}. - -: 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 [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the - requirements for a conforming user agent. - -: Window -:: The Window is the object referred to by the current document's - browsing context's Window Proxy object as defined in - HTML5 - [[HTML5]]. - diff --git a/split/focus-events.html b/split/focus-events.html deleted file mode 100644 index 39852767..00000000 --- a/split/focus-events.html +++ /dev/null @@ -1,1782 +0,0 @@ - - - - - Focus Events - - - - - - - - - - - - - - - - -
    -

    -

    Focus Events

    -

    Editor’s Draft,

    -
    - More details about this document -
    -
    -
    This version: -
    https://w3c.github.io/uievents/ -
    Latest published version: -
    https://www.w3.org/TR/uievents/ -
    Feedback: -
    GitHub -
    Editors: -
    (Google) -
    (Microsoft) -
    Former Editor: -
    Doug Schepers (Mar 2008 - May 2011) -
    Tests: -
    web-platform-tests uievents/ (ongoing work) -
    -
    -
    -
    -

    Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

    -
    -
    -
    -

    Abstract

    -

    *** Focus Events ***

    -

    Note: This is an experimental split of the UI Events spec into smaller, event-specific - - specs. The split was made from an out-of-date snapshot, so the information here is not - current, so please focus on the overall structure rather than the specifics of the - content. If this experiment goes well, then we will split the current spec after all - outstanding pull requests have been handled.

    -
    -

    Status of this document

    -
    -

    This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

    -

    This document was published by the Web Applications Working Group as an Editors Draft. This document is intended to become a W3C Recommendation.

    -

    -

    This document was published by the Web Applications Working Group as a Working Draft. - - Feedback and comments on this specification are welcome. Please use GitHub issues Historical discussions can be found in the public-webapps@w3.org archives.

    -

    Publication as an Editors Draft does not imply endorsement by W3C and its Members. This is a draft document and may - be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite - this document as other than work in progress.

    -

    This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

    -

    This document is governed by the 2 November 2021 W3C Process Document.

    -
    -
    - -
    -

    1. Introduction

    -

    1.1. Overview

    -

    TODO.

    -

    1.2. Conformance

    -

    Boilerplate?

    -

    2. Stylistic Conventions

    -

    This specification follows the Proposed W3C Specification Conventions, -with the following supplemental additions:

    -

    This is a note.

    -

    This is an open issue.

    -

    This is a warning.

    -
    interface Example {
-    // This is an IDL definition.
-};
-
    -

    3. Focus Events

    -

    This interface and its associated event types and § 3.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.

    -

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

    -

    3.1.1. FocusEvent

    -
    [Exposed=Window]
-interface FocusEvent : UIEvent {
-  constructor(DOMString type, optional FocusEventInit eventInitDict = {});
-  readonly attribute EventTarget? 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.

    -
    -

    3.1.2. FocusEventInit

    -
    dictionary FocusEventInit : 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). -
    -

    3.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 - focus - Sent after first target element receives focus -
    2 - focusin - Follows the focus event -
    - - User shifts focus -
    3 - blur - Sent after first target element loses focus -
    4 - focusout - Follows the blur event -
    5 - focus - Sent after second target element receives focus -
    6 - focusin - Follows the focus event -
    -

    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.

    -

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

    -

    3.4. Focus Event Types

    -

    The Focus event types are listed below.

    -

    3.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 does not bubble.

    -

    3.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 does not bubble.

    -

    3.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 receives focus. The event target MUST be the element which - received focus. The focus event MUST fire before the dispatch of - this event type. This event type is similar to focus, but does - bubble.

    -

    3.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 loses focus. The event target MUST be the element which lost - focus. The blur event MUST fire before the dispatch of this event - type. This event type is similar to blur, but does bubble.

    -

    4. Legacy FocusEvent events

    -

    4.1. Legacy FocusEvent event types

    -

    4.1.1. DOMFocusIn

    - - - - - - - - - - - -
    Type - DOMFocusIn -
    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 receives focus. The focus MUST be given to the - element before the dispatch of this event type. This event type - MUST be dispatched after the event type focus.

    -

    The DOMFocusIn event type is defined in this - specification for reference and completeness, but this - specification deprecates the use of this event type in - favor of the related event types focus and focusin.

    -

    4.1.2. DOMFocusOut

    - - - - - - - - - - - -
    Type - DOMFocusOut -
    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 loses focus. The focus MUST be taken from the element - before the dispatch of this event type. This event type MUST be - dispatched after the event type blur.

    -

    The DOMFocusOut event type is defined in this - specification for reference and completeness, but this - specification deprecates the use of this event type in - favor of the related event types blur and focusout.

    -

    4.2. Legacy FocusEvent event order

    -

    The following is the typical sequence of events when a focus is shifted - between elements, including the deprecated DOMFocusIn and DOMFocusOut events. The order shown 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 -
    3 - DOMFocusIn - If supported -
    - - User shifts focus -
    4 - focusout - Sent before first target element loses focus -
    5 - focusin - Sent before second target element receives focus -
    6 - blur - Sent after first target element loses focus -
    7 - DOMFocusOut - If supported -
    8 - focus - Sent after second target element receives focus -
    9 - DOMFocusIn - If supported -
    -

    5. Security Considerations

    -

    TODO - Add specific concerns for this spec

    -

    6. Acknowledgements

    -

    TODO

    -

    7. Refs to other UIEvent specs [DELETE]

    -

    This section will be deleted.

    -

    Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references.

    -

    7.1. Things defined in other sections

    -

    7.1.1. Activation triggers and behavior

    -

    7.1.2. Composition Events

    -

    7.1.3. Default actions and cancelable events

    -

    7.1.4. Event dispatch and DOM event flow

    -

    7.1.5. Web browsers and other dynamic or interactive user agents

    -

    7.1.6. Authoring tools

    -

    8. Glossary [DELETE]

    -

    This section will be deleted.

    -

    Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline.

    -
    -
    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 event -target. Each event is an instantiation of one specific event -type.

    -
    event focus -
    -

    Event focus is a special state of receptivity and concentration on a -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 § 3.3 Document Focus and Focus Context.

    -
    event target -
    -

    The object to which an event is targeted using the § 7.1.4 Event dispatch and DOM event flow. -The event target is the value of the target attribute.

    -
    event focus ring -
    -

    An event focus ring is an ordered set of event 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.

    -
    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 UI Events, and they integrate and extend the objects -and models defined in this specification.

    -
    un-initialized value -
    -

    The value of any event attribute (such as bubbles or currentTarget) before the event has been initialized with initEvent(). The un-initialized values of an event apply -immediately after a new event has been created using the method createEvent().

    -
    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 § 7.1.5 Web browsers and other dynamic or interactive user agents and § 7.1.6 Authoring tools for details on the -requirements for a conforming user agent.

    -
    Window -
    -

    The Window is the object referred to by the current document’s -browsing context’s Window Proxy object as defined in HTML5 [HTML5].

    -
    -
    -
    -

    Conformance

    -

    Document conventions

    -

    Conformance requirements are expressed - with a combination of descriptive assertions - and RFC 2119 terminology. - The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” - in the normative parts of this document - are to be interpreted as described in RFC 2119. - However, for readability, - these words do not appear in all uppercase letters in this specification.

    -

    All of the text of this specification is normative - except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

    -

    Examples in this specification are introduced with the words “for example” - or are set apart from the normative text - with class="example", - like this:

    -
    - -

    This is an example of an informative example.

    -
    -

    Informative notes begin with the word “Note” - and are set apart from the normative text - with class="note", - like this:

    -

    Note, this is an informative note.

    -
    -

    Conformant Algorithms

    -

    Requirements phrased in the imperative as part of algorithms - (such as "strip any leading space characters" - or "return false and abort these steps") - are to be interpreted with the meaning of the key word - ("must", "should", "may", etc) - used in introducing the algorithm.

    -

    Conformance requirements phrased as algorithms or specific steps - can be implemented in any manner, - so long as the end result is equivalent. - In particular, the algorithms defined in this specification - are intended to be easy to understand - and are not intended to be performant. - Implementers are encouraged to optimize.

    -
    -
    - -

    Index

    -

    Terms defined by this specification

    - -

    Terms defined by reference

    -
      -
    • - [DOM] defines the following terms: -
        -
      • Event -
      • EventTarget -
      • bubbles -
      • createEvent(interface) -
      • currentTarget -
      • document -
      • initEvent(type) -
      • target -
      -
    • - [UIEVENTS] defines the following terms: -
        -
      • UIEvent -
      • UIEventInit -
      • detail -
      • view -
      -
    • - [WEBDRIVER-BIDI] defines the following terms: -
        -
      • event type -
      -
    • - [WEBIDL] defines the following terms: -
        -
      • DOMString -
      • Exposed -
      -
    -

    References

    -

    Normative References

    -
    -
    [DOM] -
    Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/ -
    [RFC2119] -
    S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119 -
    [UIEVENTS] -
    Gary Kacmarcik; Travis Leithead. UI Events. URL: https://w3c.github.io/uievents/ -
    [WEBDRIVER-BIDI] -
    WebDriver BiDi URL: https://w3c.github.io/webdriver-bidi/ -
    [WEBIDL] -
    Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/ -
    -

    Informative References

    -
    -
    [HTML5] -
    Ian Hickson; et al. HTML5. URL: https://www.w3.org/html/wg/drafts/html/master/ -
    [UAAG20] -
    James Allan; et al. User Agent Accessibility Guidelines (UAAG) 2.0. URL: https://www.w3.org/TR/2015/NOTE-UAAG20-20151215/ -
    -

    IDL Index

    -
    [Exposed=Window]
-interface FocusEvent : UIEvent {
-  constructor(DOMString type, optional FocusEventInit eventInitDict = {});
-  readonly attribute EventTarget? relatedTarget;
-};
-
-dictionary FocusEventInit : UIEventInit {
-  EventTarget? relatedTarget = null;
-};
-
-
    - - - \ No newline at end of file diff --git a/split/focus-events.txt b/split/focus-events.txt deleted file mode 100644 index 3e4cdee0..00000000 --- a/split/focus-events.txt +++ /dev/null @@ -1,586 +0,0 @@ -

    Focus Events

    - -
    -Shortname: focus-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
-	*** Focus Events ***
-	
-	Note: This is an experimental split of the UI Events spec into smaller, event-specific
-	specs. The split was made from an out-of-date snapshot, so the information here is not
-	current, so please focus on the overall structure rather than the specifics of the
-	content. If this experiment goes well, then we will split the current spec after all
-	outstanding pull requests have been handled.
-
    - -
    -urlPrefix: https://www.w3.org/TR/WebIDL/#idl-; type: type;
-	text: long
-urlPrefix: https://w3c.github.io/selection-api/#widl-Window-getSelection-Selection; type: dfn; for: Document
-	text: getSelection()
-url: https://www.w3.org/TR/2004/REC-xml-20040204/#NT-S; type: dfn;
-	text: white space
-url: https://www.w3.org/TR/uievents-key/#key-attribute-value; type: dfn; spec: uievents-key;
-	text: key attribute value
-url: https://www.w3.org/TR/uievents-key/#keys-modifier; type: dfn; spec: uievents-key;
-	text: modifier keys table
-url: https://html.spec.whatwg.org/multipage/forms.html#context-menus; type: dfn;
-	text: contextmenu
-url: https://www.w3.org/TR/pointerevents3/#pointerevent-interface; type: interface; spec: pointerevents3
-	text: PointerEvent
-url: https://dom.spec.whatwg.org/#concept-tree-ancestor; type: dfn;
-	text: ancestor
-url: https://www.w3.org/TR/CSS21/visuren.html#x43; type: dfn;
-	text: stacking context
-url: https://drafts.csswg.org/css-position-3/#positioned-box; type: dfn;
-	text: positioned
-url: https://drafts.csswg.org/css-position-4/#paint-a-stacking-context; type: dfn;
-	text: painting a stacking context
-
    - -
    -spec:dom; type:interface; text:Document
-spec:dom; type:dfn; for:Event; text:target
-spec:infra; type:dfn; text:code point
-
    - -

    Introduction

    - -

    Overview

    - - TODO. - -

    Conformance

    - - Boilerplate? - -

    Stylistic Conventions

    - -This specification follows the -Proposed W3C Specification Conventions, -with the following supplemental additions: - -

    This is a note.

    - - - -

    This is an open issue.

    - -

    This is a warning.

    - -
    -	  interface Example {
-	      // This is an IDL definition.
-	  };
-
    - -

    Focus Events

    - -

    - This interface and its associated event types and - [[#events-focusevent-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. -

    - -

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

    FocusEvent

    - - 
    -			[Exposed=Window]
-			interface FocusEvent : UIEvent {
-				constructor(DOMString type, optional FocusEventInit eventInitDict = {});
-				readonly attribute EventTarget? 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. -
    -
    - -

    FocusEventInit

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

    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 | focus | Sent after first target element receives focus | - +| 2 | focusin | Follows the focus event | - +| | | User shifts focus | - +| 3 | blur | Sent after first target element loses focus | - +| 4 | focusout | Follows the blur event | - +| 5 | focus | Sent after second target element receives focus | - +| 6 | focusin | Follows the focus event | - ++---+------------+----------------------------------------------------+ - -

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

    - -

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

    Focus Event Types

    - - The Focus event types are listed below. - -

    blur

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| Type | blur | - +| Interface | {{FocusEvent}} | - +| Sync / Async | Sync | - +| Bubbles | No | - +| Trusted Targets | Window, Element | - +| Cancelable | No | - +| Composed | Yes | - +| Default action | None | - +| Context
    |
      | - | (trusted events) |
    • {{Event}}.{{Event/target}} : event target losing focus
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    • {{FocusEvent}}.{{FocusEvent/relatedTarget}} : event target receiving | - | | focus.
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - 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 does not bubble. - -

    focus

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| Type | focus | - +| Interface | {{FocusEvent}} | - +| Sync / Async | Sync | - +| Bubbles | No | - +| Trusted Targets | Window, Element | - +| Cancelable | No | - +| Composed | Yes | - +| Default action | None | - +| Context
    |
      | - | (trusted events) |
    • {{Event}}.{{Event/target}} : event target receiving focus
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    • {{FocusEvent}}.{{FocusEvent/relatedTarget}} : event target losing | - | | focus (if any).
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - 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 does not bubble. - -

    focusin

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| Type | focusin | - +| Interface | {{FocusEvent}} | - +| Sync / Async | Sync | - +| Bubbles | Yes | - +| Trusted Targets | Window, Element | - +| Cancelable | No | - +| Composed | Yes | - +| Default action | None | - +| Context
    |
      | - | (trusted events) |
    • {{Event}}.{{Event/target}} : event target receiving focus
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    • {{FocusEvent}}.{{FocusEvent/relatedTarget}} : event target losing | - | | focus (if any).
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - A user agent MUST dispatch this event when an event target - receives focus. The event target MUST be the element which - received focus. The [=focus=] event MUST fire before the dispatch of - this event type. This event type is similar to [=focus=], but does - bubble. - -

    focusout

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| Type | focusout | - +| Interface | {{FocusEvent}} | - +| Sync / Async | Sync | - +| Bubbles | Yes | - +| Trusted Targets | Window, Element | - +| Cancelable | No | - +| Composed | Yes | - +| Default action | None | - +| Context
    |
      | - | (trusted events) |
    • {{Event}}.{{Event/target}} : event target losing focus
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    • {{FocusEvent}}.{{FocusEvent/relatedTarget}} : event target receiving | - | | focus.
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - A user agent MUST dispatch this event when an event target - loses focus. The event target MUST be the element which lost - focus. The [=blur=] event MUST fire before the dispatch of this event - type. This event type is similar to [=blur=], but does bubble. - -

    Legacy {{FocusEvent}} events

    - -

    Legacy {{FocusEvent}} event types

    - -

    DOMFocusIn

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    TypeDOMFocusIn
    Interface{{FocusEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsWindow, Element
    CancelableNo
    ComposedYes
    Default actionNone
    Context
    (trusted events)    		 -
      -
    • {{Event}}.{{Event/target}} : - event target receiving focus
      • -
    • {{UIEvent}}.{{UIEvent/view}} : - Window
      • -
    • {{UIEvent}}.{{UIEvent/detail}} : - 0
      • -
    • {{FocusEvent}}.{{FocusEvent/relatedTarget}} : - null
      • -
    -
    - - 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 - MUST be dispatched after the event type EVENT{focus}. - -

    - The EVENT{DOMFocusIn} event type is defined in this - specification for reference and completeness, but this - specification deprecates the use of this event type in - favor of the related event types EVENT{focus} and EVENT{focusin}. -

    - -

    DOMFocusOut

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    TypeDOMFocusOut
    Interface{{FocusEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsWindow, Element
    CancelableNo
    ComposedYes
    Default actionNone
    Context
    (trusted events)    		 -
      -
    • {{Event}}.{{Event/target}} : - event target losing focus
      • -
    • {{UIEvent}}.{{UIEvent/view}} : - Window
      • -
    • {{UIEvent}}.{{UIEvent/detail}} : - 0
      • -
    • {{FocusEvent}}.{{FocusEvent/relatedTarget}} : - null
      • -
    -
    - - 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 MUST be - dispatched after the event type EVENT{blur}. - -

    - The EVENT{DOMFocusOut} event type is defined in this - specification for reference and completeness, but this - specification deprecates the use of this event type in - favor of the related event types EVENT{blur} and EVENT{focusout}. -

    - -

    Legacy FocusEvent event order

    - - The following is the typical sequence of events when a focus is shifted - between elements, including the deprecated EVENT{DOMFocusIn} and - EVENT{DOMFocusOut} events. The order shown 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 | - +| 3 | DOMFocusIn | If supported | - +| | | User shifts focus | - +| 4 | focusout | Sent before first target element loses focus | - +| 5 | focusin | Sent before second target element receives focus | - +| 6 | blur | Sent after first target element loses focus | - +| 7 | DOMFocusOut | If supported | - +| 8 | focus | Sent after second target element receives focus | - +| 9 | DOMFocusIn | If supported | - ++---+-------------+---------------------------------------------------+ - -

    Security Considerations

    - - TODO - Add specific concerns for this spec - -

    Acknowledgements

    - - TODO - -

    Refs to other UIEvent specs \[DELETE]

    - - This section will be deleted. - - Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references. - -

    Things defined in other sections

    - -

    Activation triggers and behavior

    -

    Composition Events

    -

    Default actions and cancelable events

    -

    Event dispatch and DOM event flow

    -

    Web browsers and other dynamic or interactive user agents

    -

    Authoring tools

    - -

    Glossary \[DELETE]

    - -This section will be deleted. - -Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline. - -: 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 event - target. Each event is an instantiation of one specific event - type. - -: event focus -:: Event focus is a special state of receptivity and concentration on a - 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 - [[#events-focusevent-doc-focus]]. - -: event target -:: The object to which an event is targeted using the [[#event-flow]]. - The event target is the value of the {{Event/target}} attribute. - -: event focus ring -:: An event focus ring is an ordered set of event 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. - -: 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 UI Events, and they integrate and extend the objects - and models defined in this specification. - -: un-initialized value -:: The value of any event attribute (such as {{Event/bubbles}} or - {{Event/currentTarget}}) before the event has been initialized with - {{Event/initEvent()}}. The un-initialized values of an event apply - immediately after a new event has been created using the method - {{Document/createEvent()}}. - -: 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 [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the - requirements for a conforming user agent. - -: Window -:: The Window is the object referred to by the current document's - browsing context's Window Proxy object as defined in - HTML5 - [[HTML5]]. - diff --git a/split/input-events.bs b/split/input-events.bs deleted file mode 100644 index 2097322d..00000000 --- a/split/input-events.bs +++ /dev/null @@ -1,312 +0,0 @@ -

    Input Events

    - -
    -Shortname: input-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
-	*** Input Events ***
-
-	Note: This is an experimental split of the UI Events spec into smaller, event-specific
-	specs. The split was made from an out-of-date snapshot, so the information here is not
-	current, so please focus on the overall structure rather than the specifics of the
-	content. If this experiment goes well, then we will split the current spec after all
-	outstanding pull requests have been handled.
-
    - -
    -urlPrefix: https://www.w3.org/TR/WebIDL/#idl-; type: type;
-	text: long
-urlPrefix: https://w3c.github.io/selection-api/#widl-Window-getSelection-Selection; type: dfn; for: Document
-	text: getSelection()
-url: https://www.w3.org/TR/2004/REC-xml-20040204/#NT-S; type: dfn;
-	text: white space
-url: https://www.w3.org/TR/uievents-key/#key-attribute-value; type: dfn; spec: uievents-key;
-	text: key attribute value
-url: https://www.w3.org/TR/uievents-key/#keys-modifier; type: dfn; spec: uievents-key;
-	text: modifier keys table
-url: https://html.spec.whatwg.org/multipage/forms.html#context-menus; type: dfn;
-	text: contextmenu
-url: https://www.w3.org/TR/pointerevents3/#pointerevent-interface; type: interface; spec: pointerevents3
-	text: PointerEvent
-url: https://dom.spec.whatwg.org/#concept-tree-ancestor; type: dfn;
-	text: ancestor
-url: https://www.w3.org/TR/CSS21/visuren.html#x43; type: dfn;
-	text: stacking context
-url: https://drafts.csswg.org/css-position-3/#positioned-box; type: dfn;
-	text: positioned
-url: https://drafts.csswg.org/css-position-4/#paint-a-stacking-context; type: dfn;
-	text: painting a stacking context
-
    - -
    -spec:dom; type:interface; text:Document
-spec:dom; type:dfn; for:Event; text:target
-spec:infra; type:dfn; text:code point
-
    - -

    Introduction

    - -

    Overview

    - - TODO. - -

    Conformance

    - - Boilerplate? - -

    Stylistic Conventions

    - -This specification follows the -Proposed W3C Specification Conventions, -with the following supplemental additions: - -

    This is a note.

    - - - -

    This is an open issue.

    - -

    This is a warning.

    - -
    -	  interface Example {
-	      // This is an IDL definition.
-	  };
-
    - -

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

    Interface InputEvent

    - -

    Introduced in DOM Level 3

    - -

    InputEvent

    - - 
    -			[Exposed=Window]
-			interface InputEvent : UIEvent {
-				constructor(DOMString type, optional InputEventInit eventInitDict = {});
-				readonly attribute USVString? data;
-				readonly attribute boolean isComposing;
-				readonly attribute DOMString inputType;
-			};
-
    - -
    -
    data
    -
    - 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
    -
    - 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
    -
    - 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 "". -
    -
    - -

    InputEventInit

    - - 
    -			dictionary InputEventInit : UIEventInit {
-				DOMString? data = null;
-				boolean isComposing = false;
-				DOMString inputType = "";
-			};
-
    - -
    -
    data
    -
    - Initializes the data attribute of the InputEvent object. -
    - -
    isComposing
    -
    - Initializes the isComposing attribute of the InputEvent object. -
    - -
    inputType
    -
    - Initializes the inputType attribute of the InputEvent object. -
    -
    - -

    Input Event Order

    - - The input events defined in this specification MUST occur in a set order - relative to one another. - - - - - - -
    Event TypeNotes
    1beforeinput
    DOM element is updated
    2input
    - -

    Input Event Types

    - -

    beforeinput

    - - - - - - - - - - - -
    Typebeforeinput
    Interface{{InputEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement (specifically: control types such as HTMLInputElement, etc.) or any Element with contenteditable attribute enabled
    CancelableYes
    ComposedYes
    Default actionUpdate the DOM element
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : event target that is about to be updated
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    • {{InputEvent}}.{{InputEvent/data}} : the string containing the data that will be added to the element, which MAY be null if the content will be deleted
    • {{InputEvent}}.{{InputEvent/isComposing}} : true if this event is dispatched during a dead key sequence or while an input method editor is active (such that composition events are being dispatched); false otherwise.
    - - A user agent MUST dispatch this event when the DOM is about - to be updated. - -

    input

    - - - - - - - - - - - -
    Typeinput
    Interface{{InputEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement (specifically: control types such as HTMLInputElement, etc.) or any Element with contenteditable attribute enabled
    CancelableNo
    ComposedYes
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : event target that was just updated
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    • {{InputEvent}}.{{InputEvent/data}} : the string containing the data that has been added to the element, which MAY be the empty string if the content has been deleted
    • {{InputEvent}}.{{InputEvent/isComposing}} : true if this event is dispatched during a dead key sequence or while an input method editor is active (such that composition events are being dispatched); false otherwise.
    - - A user agent MUST dispatch this event immediately after the - DOM has been updated. - -

    Security Considerations

    - - TODO - Add specific concerns for this spec - -

    Acknowledgements

    - - TODO - - Note: Include people from Editing/Input who have contributed. - -

    Refs to other UIEvent specs \[DELETE]

    - - This section will be deleted. - - Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references. - - compositionend - compositionstart - -

    Things defined in other sections

    - -

    Activation triggers and behavior

    -

    Composition Events

    -

    Default actions and cancelable events

    -

    Event dispatch and DOM event flow

    -

    Web browsers and other dynamic or interactive user agents

    -

    Authoring tools

    - -

    Things defined in KeyboardEvents

    -

    Dead keys

    -

    Input Method Editors

    - -

    Glossary \[DELETE]

    - -This section will be deleted. - -Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline. - -: 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 event - target. Each event is an instantiation of one specific event - type. - -: event target -:: The object to which an event is targeted using the [[#event-flow]]. - The event target is the value of the {{Event/target}} attribute. - -: 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 [[#keys-IME]] for treatment of - IMEs in this specification. See also text composition system. - -: 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. - -: un-initialized value -:: The value of any event attribute (such as {{Event/bubbles}} or - {{Event/currentTarget}}) before the event has been initialized with - {{Event/initEvent()}}. The un-initialized values of an event apply - immediately after a new event has been created using the method - {{Document/createEvent()}}. - -: 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 [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the - requirements for a conforming user agent. - -: Window -:: The Window is the object referred to by the current document's - browsing context's Window Proxy object as defined in - HTML5 - [[HTML5]]. - diff --git a/split/input-events.html b/split/input-events.html deleted file mode 100644 index d482a0f6..00000000 --- a/split/input-events.html +++ /dev/null @@ -1,1513 +0,0 @@ - - - - - Input Events - - - - - - - - - - - - - - - - -
    -

    -

    Input Events

    -

    Editor’s Draft,

    -
    - More details about this document -
    -
    -
    This version: -
    https://w3c.github.io/uievents/ -
    Latest published version: -
    https://www.w3.org/TR/uievents/ -
    Feedback: -
    GitHub -
    Editors: -
    (Google) -
    (Microsoft) -
    Former Editor: -
    Doug Schepers (Mar 2008 - May 2011) -
    Tests: -
    web-platform-tests uievents/ (ongoing work) -
    -
    -
    -
    -

    Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

    -
    -
    -
    -

    Abstract

    -

    *** Input Events ***

    -

    Note: This is an experimental split of the UI Events spec into smaller, event-specific - - specs. The split was made from an out-of-date snapshot, so the information here is not - current, so please focus on the overall structure rather than the specifics of the - content. If this experiment goes well, then we will split the current spec after all - outstanding pull requests have been handled.

    -
    -

    Status of this document

    -
    -

    This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

    -

    This document was published by the Web Applications Working Group as an Editors Draft. This document is intended to become a W3C Recommendation.

    -

    -

    This document was published by the Web Applications Working Group as a Working Draft. - - Feedback and comments on this specification are welcome. Please use GitHub issues Historical discussions can be found in the public-webapps@w3.org archives.

    -

    Publication as an Editors Draft does not imply endorsement by W3C and its Members. This is a draft document and may - be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite - this document as other than work in progress.

    -

    This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

    -

    This document is governed by the 2 November 2021 W3C Process Document.

    -
    -
    - -
    -

    1. Introduction

    -

    1.1. Overview

    -

    TODO.

    -

    1.2. Conformance

    -

    Boilerplate?

    -

    2. Stylistic Conventions

    -

    This specification follows the Proposed W3C Specification Conventions, -with the following supplemental additions:

    -

    This is a note.

    -

    This is an open issue.

    -

    This is a warning.

    -
    interface Example {
-    // This is an IDL definition.
-};
-
    -

    3. 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, ...).

    -

    3.1. Interface InputEvent

    -

    Introduced in DOM Level 3

    -

    3.1.1. InputEvent

    -
    [Exposed=Window]
-interface InputEvent : UIEvent {
-  constructor(DOMString type, optional InputEventInit eventInitDict = {});
-  readonly attribute USVString? data;
-  readonly attribute boolean isComposing;
-  readonly attribute DOMString inputType;
-};
-
    -
    -
    data, of type USVString, 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 "".

    -
    -

    3.1.2. InputEventInit

    -
    dictionary InputEventInit : UIEventInit {
-  DOMString? data = null;
-  boolean isComposing = false;
-  DOMString inputType = "";
-};
-
    -
    -
    data, of type DOMString, nullable, defaulting to null -
    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. -
    -

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

    3.3. Input Event Types

    -

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

    -

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

    -

    4. Security Considerations

    -

    TODO - Add specific concerns for this spec

    -

    5. Acknowledgements

    -

    TODO

    -

    Note: Include people from Editing/Input who have contributed.

    -

    6. Refs to other UIEvent specs [DELETE]

    -

    This section will be deleted.

    -

    Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references.

    -

    compositionend compositionstart

    -

    6.1. Things defined in other sections

    -

    6.1.1. Activation triggers and behavior

    -

    6.1.2. Composition Events

    -

    6.1.3. Default actions and cancelable events

    -

    6.1.4. Event dispatch and DOM event flow

    -

    6.1.5. Web browsers and other dynamic or interactive user agents

    -

    6.1.6. Authoring tools

    -

    6.2. Things defined in KeyboardEvents

    -

    6.2.1. Dead keys

    -

    6.2.2. Input Method Editors

    -

    7. Glossary [DELETE]

    -

    This section will be deleted.

    -

    Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline.

    -
    -
    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 event -target. Each event is an instantiation of one specific event -type.

    -
    event target -
    -

    The object to which an event is targeted using the § 6.1.4 Event dispatch and DOM event flow. -The event target is the value of the target attribute.

    -
    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 § 6.2.2 Input Method Editors for treatment of -IMEs in this specification. See also text composition system.

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

    -
    un-initialized value -
    -

    The value of any event attribute (such as bubbles or currentTarget) before the event has been initialized with initEvent(). The un-initialized values of an event apply -immediately after a new event has been created using the method createEvent().

    -
    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 § 6.1.5 Web browsers and other dynamic or interactive user agents and § 6.1.6 Authoring tools for details on the -requirements for a conforming user agent.

    -
    Window -
    -

    The Window is the object referred to by the current document’s -browsing context’s Window Proxy object as defined in HTML5 [HTML5].

    -
    -
    -
    -

    Conformance

    -

    Document conventions

    -

    Conformance requirements are expressed - with a combination of descriptive assertions - and RFC 2119 terminology. - The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” - in the normative parts of this document - are to be interpreted as described in RFC 2119. - However, for readability, - these words do not appear in all uppercase letters in this specification.

    -

    All of the text of this specification is normative - except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

    -

    Examples in this specification are introduced with the words “for example” - or are set apart from the normative text - with class="example", - like this:

    -
    - -

    This is an example of an informative example.

    -
    -

    Informative notes begin with the word “Note” - and are set apart from the normative text - with class="note", - like this:

    -

    Note, this is an informative note.

    -
    -

    Conformant Algorithms

    -

    Requirements phrased in the imperative as part of algorithms - (such as "strip any leading space characters" - or "return false and abort these steps") - are to be interpreted with the meaning of the key word - ("must", "should", "may", etc) - used in introducing the algorithm.

    -

    Conformance requirements phrased as algorithms or specific steps - can be implemented in any manner, - so long as the end result is equivalent. - In particular, the algorithms defined in this specification - are intended to be easy to understand - and are not intended to be performant. - Implementers are encouraged to optimize.

    -
    -
    - -

    Index

    -

    Terms defined by this specification

    - -

    Terms defined by reference

    -
      -
    • - [DOM] defines the following terms: -
        -
      • Event -
      • bubbles -
      • createEvent(interface) -
      • currentTarget -
      • document -
      • initEvent(type) -
      • target -
      -
    • - [UIEVENTS] defines the following terms: -
        -
      • UIEvent -
      • UIEventInit -
      • detail -
      • view -
      -
    • - [WEBDRIVER-BIDI] defines the following terms: -
        -
      • event type -
      -
    • - [WEBIDL] defines the following terms: -
        -
      • DOMString -
      • Exposed -
      • USVString -
      • boolean -
      -
    -

    References

    -

    Normative References

    -
    -
    [DOM] -
    Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/ -
    [RFC2119] -
    S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119 -
    [UIEVENTS] -
    Gary Kacmarcik; Travis Leithead. UI Events. URL: https://w3c.github.io/uievents/ -
    [WEBDRIVER-BIDI] -
    WebDriver BiDi URL: https://w3c.github.io/webdriver-bidi/ -
    [WEBIDL] -
    Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/ -
    -

    Informative References

    -
    -
    [HTML5] -
    Ian Hickson; et al. HTML5. URL: https://www.w3.org/html/wg/drafts/html/master/ -
    [Input-Events] -
    Johannes Wilm; Ben Peters. Input Events Level 1. URL: https://cdn.staticaly.com/gh/w3c/input-events/v1/index.html -
    [UAX15] -
    Ken Whistler. Unicode Normalization Forms. 17 August 2022. Unicode Standard Annex #15. URL: https://www.unicode.org/reports/tr15/tr15-53.html -
    [Unicode] -
    The Unicode Standard. URL: https://www.unicode.org/versions/latest/ -
    -

    IDL Index

    -
    [Exposed=Window]
-interface InputEvent : UIEvent {
-  constructor(DOMString type, optional InputEventInit eventInitDict = {});
-  readonly attribute USVString? data;
-  readonly attribute boolean isComposing;
-  readonly attribute DOMString inputType;
-};
-
-dictionary InputEventInit : UIEventInit {
-  DOMString? data = null;
-  boolean isComposing = false;
-  DOMString inputType = "";
-};
-
-
    - - - \ No newline at end of file diff --git a/split/input-events.txt b/split/input-events.txt deleted file mode 100644 index 7dfa98a1..00000000 --- a/split/input-events.txt +++ /dev/null @@ -1,345 +0,0 @@ -

    Input Events

    - -
    -Shortname: input-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
-	*** Input Events ***
-	
-	Note: This is an experimental split of the UI Events spec into smaller, event-specific
-	specs. The split was made from an out-of-date snapshot, so the information here is not
-	current, so please focus on the overall structure rather than the specifics of the
-	content. If this experiment goes well, then we will split the current spec after all
-	outstanding pull requests have been handled.
-
    - -
    -urlPrefix: https://www.w3.org/TR/WebIDL/#idl-; type: type;
-	text: long
-urlPrefix: https://w3c.github.io/selection-api/#widl-Window-getSelection-Selection; type: dfn; for: Document
-	text: getSelection()
-url: https://www.w3.org/TR/2004/REC-xml-20040204/#NT-S; type: dfn;
-	text: white space
-url: https://www.w3.org/TR/uievents-key/#key-attribute-value; type: dfn; spec: uievents-key;
-	text: key attribute value
-url: https://www.w3.org/TR/uievents-key/#keys-modifier; type: dfn; spec: uievents-key;
-	text: modifier keys table
-url: https://html.spec.whatwg.org/multipage/forms.html#context-menus; type: dfn;
-	text: contextmenu
-url: https://www.w3.org/TR/pointerevents3/#pointerevent-interface; type: interface; spec: pointerevents3
-	text: PointerEvent
-url: https://dom.spec.whatwg.org/#concept-tree-ancestor; type: dfn;
-	text: ancestor
-url: https://www.w3.org/TR/CSS21/visuren.html#x43; type: dfn;
-	text: stacking context
-url: https://drafts.csswg.org/css-position-3/#positioned-box; type: dfn;
-	text: positioned
-url: https://drafts.csswg.org/css-position-4/#paint-a-stacking-context; type: dfn;
-	text: painting a stacking context
-
    - -
    -spec:dom; type:interface; text:Document
-spec:dom; type:dfn; for:Event; text:target
-spec:infra; type:dfn; text:code point
-
    - -

    Introduction

    - -

    Overview

    - - TODO. - -

    Conformance

    - - Boilerplate? - -

    Stylistic Conventions

    - -This specification follows the -Proposed W3C Specification Conventions, -with the following supplemental additions: - -

    This is a note.

    - - - -

    This is an open issue.

    - -

    This is a warning.

    - -
    -	  interface Example {
-	      // This is an IDL definition.
-	  };
-
    - -

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

    Interface InputEvent

    - -

    Introduced in DOM Level 3

    - -

    InputEvent

    - - 
    -			[Exposed=Window]
-			interface InputEvent : UIEvent {
-				constructor(DOMString type, optional InputEventInit eventInitDict = {});
-				readonly attribute USVString? data;
-				readonly attribute boolean isComposing;
-				readonly attribute DOMString inputType;
-			};
-
    - -
    -
    data
    -
    - 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
    -
    - true if the input event occurs as part of a - composition session, i.e., after a EVENT{compositionstart} event - and before the corresponding EVENT{compositionend} event. - - The un-initialized value of this attribute MUST be - false. -
    - -
    inputType
    -
    - 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 "". -
    -
    - -

    InputEventInit

    - - 
    -			dictionary InputEventInit : UIEventInit {
-				DOMString? data = null;
-				boolean isComposing = false;
-				DOMString inputType = "";
-			};
-
    - -
    -
    data
    -
    - Initializes the data attribute of the InputEvent object. -
    - -
    isComposing
    -
    - Initializes the isComposing attribute of the InputEvent object. -
    - -
    inputType
    -
    - Initializes the inputType attribute of the InputEvent object. -
    -
    - -

    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 | | - ++---+-------------+---------------------------------------------------+ - -

    Input Event Types

    - -

    beforeinput

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| 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) |
    • {{Event}}.{{Event/target}} : event target that is about to be updated
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    • {{InputEvent}}.{{InputEvent/data}} : the string containing the data that will | - | | be added to the element, which MAY be null if the content will | - | | be deleted
      • | - | |
    • {{InputEvent}}.{{InputEvent/isComposing}} : true if this event is | - | | dispatched during a dead key sequence or while an | - | | input method editor is active (such that | - | | composition events are being dispatched);| - | | false otherwise.
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - A user agent MUST dispatch this event when the DOM is about - to be updated. - -

    input

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| 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) |
    • {{Event}}.{{Event/target}} : event target that was just updated
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    • {{InputEvent}}.{{InputEvent/data}} : the string containing the data that has | - | | been added to the element, which MAY be the empty string if the content | - | | has been deleted
      • | - | |
    • {{InputEvent}}.{{InputEvent/isComposing}} : true if this event is | - | | dispatched during a dead key sequence or while an | - | | input method editor is active (such that | - | | composition events are being dispatched);| - | | false otherwise.
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - A user agent MUST dispatch this event immediately after the - DOM has been updated. - -

    Security Considerations

    - - TODO - Add specific concerns for this spec - -

    Acknowledgements

    - - TODO - - Note: Include people from Editing/Input who have contributed. - -

    Refs to other UIEvent specs \[DELETE]

    - - This section will be deleted. - - Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references. - - compositionend - compositionstart - -

    Things defined in other sections

    - -

    Activation triggers and behavior

    -

    Composition Events

    -

    Default actions and cancelable events

    -

    Event dispatch and DOM event flow

    -

    Web browsers and other dynamic or interactive user agents

    -

    Authoring tools

    - -

    Things defined in KeyboardEvents

    -

    Dead keys

    -

    Input Method Editors

    - -

    Glossary \[DELETE]

    - -This section will be deleted. - -Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline. - -: 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 event - target. Each event is an instantiation of one specific event - type. - -: event target -:: The object to which an event is targeted using the [[#event-flow]]. - The event target is the value of the {{Event/target}} attribute. - -: 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 [[#keys-IME]] for treatment of - IMEs in this specification. See also text composition system. - -: 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. - -: un-initialized value -:: The value of any event attribute (such as {{Event/bubbles}} or - {{Event/currentTarget}}) before the event has been initialized with - {{Event/initEvent()}}. The un-initialized values of an event apply - immediately after a new event has been created using the method - {{Document/createEvent()}}. - -: 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 [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the - requirements for a conforming user agent. - -: Window -:: The Window is the object referred to by the current document's - browsing context's Window Proxy object as defined in - HTML5 - [[HTML5]]. - diff --git a/split/keyboard-events.bs b/split/keyboard-events.bs deleted file mode 100644 index eb91b360..00000000 --- a/split/keyboard-events.bs +++ /dev/null @@ -1,2282 +0,0 @@ -

    Keyboard Events

    - -
    -Shortname: keyboard-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
-	*** Keyboard Events ***
-
-	Note: This is an experimental split of the UI Events spec into smaller, event-specific
-	specs. The split was made from an out-of-date snapshot, so the information here is not
-	current, so please focus on the overall structure rather than the specifics of the
-	content. If this experiment goes well, then we will split the current spec after all
-	outstanding pull requests have been handled.
-
    - -
    -urlPrefix: https://www.w3.org/TR/WebIDL/#idl-; type: type;
-	text: long
-urlPrefix: https://w3c.github.io/selection-api/#widl-Window-getSelection-Selection; type: dfn; for: Document
-	text: getSelection()
-url: https://www.w3.org/TR/2004/REC-xml-20040204/#NT-S; type: dfn;
-	text: white space
-url: https://www.w3.org/TR/uievents-key/#key-attribute-value; type: dfn; spec: uievents-key;
-	text: key attribute value
-url: https://www.w3.org/TR/uievents-key/#keys-modifier; type: dfn; spec: uievents-key;
-	text: modifier keys table
-url: https://html.spec.whatwg.org/multipage/forms.html#context-menus; type: dfn;
-	text: contextmenu
-url: https://www.w3.org/TR/pointerevents3/#pointerevent-interface; type: interface; spec: pointerevents3
-	text: PointerEvent
-url: https://dom.spec.whatwg.org/#concept-tree-ancestor; type: dfn;
-	text: ancestor
-url: https://www.w3.org/TR/CSS21/visuren.html#x43; type: dfn;
-	text: stacking context
-url: https://drafts.csswg.org/css-position-3/#positioned-box; type: dfn;
-	text: positioned
-url: https://drafts.csswg.org/css-position-4/#paint-a-stacking-context; type: dfn;
-	text: painting a stacking context
-
    - -
    -spec:dom; type:interface; text:Document
-spec:dom; type:dfn; for:Event; text:target
-spec:infra; type:dfn; text:code point
-
    - -
    -{
-	"DWW95": {
-		"title": "Developing International Software for Windows 95 and Windows NT: A Handbook for International Software Design",
-		"authors": [ "N. Kano" ],
-		"publisher": "Microsoft Press",
-		"date": "1995",
-		"isbn": "1-55615-840-8"
-	},
-	"US-ASCII": {
-		"title": "Coded Character Set - 7-Bit American Standard Code for Information Interchange",
-		"publisher": "Standard ANSI X3.4-1986",
-		"date": "1986"
-	},
-	"WIN1252": {
-		"title": "Windows 1252 a Coded Character Set - 8-Bit",
-		"href": "https://www.microsoft.com/globaldev/reference/sbcs/1252.htm",
-		"publisher": "Microsoft Corporation"
-	}
-}
-
    - -

    Introduction

    - -

    Overview

    - - TODO. - -

    Conformance

    - - Boilerplate? - -

    Stylistic Conventions

    - -This specification follows the -Proposed W3C Specification Conventions, -with the following supplemental additions: - -* The key cap printed on a key is shown as - ↓, = or Q. This is used to refer to a - key from the user's perspective without regard for the - {{KeyboardEvent/key}} and {{KeyboardEvent/code}} values in the - generated {{KeyboardEvent}}. - -* Glyphs representing character are shown as: "𣧂". - -* Unicode character encodings are shown as: U+003d. - -* Names of key values generated by a key press (i.e., the value of - {{KeyboardEvent}}.{{KeyboardEvent/key}}) are shown as: - "ArrowDown", "=", "q" or "Q". - -* Names of key codes associated with the physical keys (i.e., the - value of {{KeyboardEvent}}.{{KeyboardEvent/code}}) are shown as: - "ArrowDown", "Equal" or "KeyQ". - - -In addition, certain terms are used in this specification with particular -meanings. The term implementation applies to a browser, content -authoring tool, or other user agent that implements this specification, -while a content author is a person who writes script or code that takes -advantage of the interfaces, methods, attributes, events, and other features -described in this specification in order to make Web applications, and a user is -the person who uses those Web applications in an implementation. - -And finally: - -

    This is a note.

    - - - -

    This is an open issue.

    - -

    This is a warning.

    - -
    -	  interface Example {
-	      // This is an IDL definition.
-	  };
-
    - -

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

    - -

    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: {{KeyboardEvent/ctrlKey}}, - {{KeyboardEvent/shiftKey}}, {{KeyboardEvent/altKey}}, - {{KeyboardEvent/metaKey}}. These attributes are equivalent to using the - method {{KeyboardEvent/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. - -

    KeyboardEvent

    - - 
    -			[Exposed=Window]
-			interface KeyboardEvent : UIEvent {
-				constructor(DOMString type, optional KeyboardEventInit eventInitDict = {});
-				// 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;
-
-				readonly attribute DOMString key;
-				readonly attribute DOMString code;
-				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 boolean 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 - {{KeyboardEvent/location}} of - {{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}}. - -

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

    -
    - -
    key
    -
    - 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
    -
    - 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
    -
    - The {{KeyboardEvent/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 - {{KeyboardEvent/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 {{KeyboardEvent/location}} attribute MUST be set to - {{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}}. Conversely, if the - "KeyQ" key is remapped to one of the Control keys, - then the {{KeyboardEvent/location}} attribute MUST be set to - either {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} or - {{KeyboardEvent/DOM_KEY_LOCATION_RIGHT}}. - - The un-initialized value of this attribute MUST be - 0. -
    - -
    ctrlKey
    -
    - true if the Control (control) key modifier - was active. - - The un-initialized value of this attribute MUST be - false. -
    - -
    shiftKey
    -
    - true if the shift (Shift) key modifier was - active. - - The un-initialized value of this attribute MUST be - false. -
    - -
    altKey
    -
    - true if the Alt (alternative) (or - "Option") key modifier was active. - - The un-initialized value of this attribute MUST be - false. -
    - -
    metaKey
    -
    - 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
    -
    - 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 {{KeyboardEvent/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
    -
    - 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 {{KeyboardEvent/location}}. -

    -
    -
    -
    -
    - -

    KeyboardEventInit

    - - 
    -			dictionary KeyboardEventInit : EventModifierInit {
-				DOMString key = "";
-				DOMString code = "";
-				unsigned long location = 0;
-				boolean repeat = false;
-				boolean isComposing = false;
-			};
-
    - -
    -
    key
    -
    - 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
    -
    - 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
    -
    - Initializes the {{KeyboardEvent/location}} attribute of the - KeyboardEvent object to one of the following location numerical - constants: - - * {{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}} (numerical value 0) - * {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} (numerical value 1) - * {{KeyboardEvent/DOM_KEY_LOCATION_RIGHT}} (numerical value 2) - * {{KeyboardEvent/DOM_KEY_LOCATION_NUMPAD}} (numerical value 3) -
    - -
    repeat
    -
    - 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
    -
    - 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 {{KeyboardEvent/key}} and {{KeyboardEvent/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. -

    - -

    Keyboard Event Key Location

    - - The {{KeyboardEvent/location}} attribute can be used to disambiguate - between {{KeyboardEvent/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 {{KeyboardEvent/location}} values - for the special keys that have more than one location on the keyboard: - - - - - - - -
    {{KeyboardEvent}} . {{KeyboardEvent/key}}Valid {{KeyboardEvent/location}} values
    "Shift", "Control", "Alt", "Meta"{{KeyboardEvent/DOM_KEY_LOCATION_LEFT}}, {{KeyboardEvent/DOM_KEY_LOCATION_RIGHT}}
    "ArrowDown", "ArrowLeft", "ArrowRight", "ArrowUp"{{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}}, {{KeyboardEvent/DOM_KEY_LOCATION_NUMPAD}}
    "End", "Home", "PageDown", "PageUp"{{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}}, {{KeyboardEvent/DOM_KEY_LOCATION_NUMPAD}}
    "0", "1", "2", "2", "4", "5", "6", "7", "8", "9", ".", "Enter", "+", "-", "*", "/"{{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}}, {{KeyboardEvent/DOM_KEY_LOCATION_NUMPAD}}
    - - For all other keys not listed in this table, the - {{KeyboardEvent/location}} attribute MUST always be set to - {{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}}. - -

    Keyboard Event Order

    - - The keyboard events defined in this specification occur in a set order - relative to one another, for any given key: - - - - - - - - - -
    Event TypeNotes
    1keydown
    2beforeinput(only for keys which produce a character value)
    Any default actions related to this key, such as inserting a character in to the DOM.
    3input(only for keys which have updated the DOM)
    Any events as a result of the key being held for a sustained period (see below).
    4keyup
    - - If the key is depressed for a sustained period, the following events MAY - repeat at an environment-dependent rate: - - - - - - - -
    Event TypeNotes
    1keydown(with {{KeyboardEvent/repeat}} attribute set to true)
    2beforeinput(only for keys which produce a character value)
    Any default actions related to this key, such as inserting a character in to the DOM.
    3input(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. - -

    Keyboard Event Types

    - -

    keydown

    - - - - - - - - - - - -
    Typekeydown
    Interface{{KeyboardEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    ComposedYes
    Default actionVaries: beforeinput and input events; launch text composition system; blur and focus events; keypress event (if supported); activation behavior; other event
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : focused element processing the key event or if no element focused, then the body element if available, otherwise the root element
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    • {{KeyboardEvent}}.{{KeyboardEvent/key}} : the key value of the key pressed.
    • {{KeyboardEvent}}.{{KeyboardEvent/code}} : the code value associated with the key's physical placement on the keyboard.
    • {{KeyboardEvent}}.{{KeyboardEvent/location}} : the location of the key on the device.
    • {{KeyboardEvent}}.{{KeyboardEvent/altKey}} : true if Alt modifier was active, otherwise false
    • {{KeyboardEvent}}.{{KeyboardEvent/shiftKey}} : true if Shift modifier was active, otherwise false
    • {{KeyboardEvent}}.{{KeyboardEvent/ctrlKey}} : true if Control modifier was active, otherwise false
    • {{KeyboardEvent}}.{{KeyboardEvent/metaKey}} : true if Meta modifier was active, otherwise false
    • {{KeyboardEvent}}.{{KeyboardEvent/repeat}} : true if a key has been depressed long enough to trigger key repetition, otherwise false
    • {{KeyboardEvent}}.{{KeyboardEvent/isComposing}} : true if the key event occurs as part of a composition session, otherwise false
    - - 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   (Space) 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 [[#event-flow-activation]] 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. -

    - -

    keyup

    - - - - - - - - - - - -
    Typekeyup
    Interface{{KeyboardEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    ComposedYes
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : focused element processing the key event or if no element focused, then the body element if available, otherwise the root element
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    • {{KeyboardEvent}}.{{KeyboardEvent/key}} : the key value of the key pressed.
    • {{KeyboardEvent}}.{{KeyboardEvent/code}} : the code value associated with the key's physical placement on the keyboard.
    • {{KeyboardEvent}}.{{KeyboardEvent/location}} : the location of the key on the device.
    • {{KeyboardEvent}}.{{KeyboardEvent/altKey}} : true if Alt modifier was active, otherwise false
    • {{KeyboardEvent}}.{{KeyboardEvent/shiftKey}} : true if Shift modifier was active, otherwise false
    • {{KeyboardEvent}}.{{KeyboardEvent/ctrlKey}} : true if Control modifier was active, otherwise false
    • {{KeyboardEvent}}.{{KeyboardEvent/metaKey}} : true if Meta modifier was active, otherwise false
    • {{KeyboardEvent}}.{{KeyboardEvent/repeat}} : true if a key has been depressed long enough to trigger key repetition, otherwise false
    • {{KeyboardEvent}}.{{KeyboardEvent/isComposing}} : true if the key event occurs as part of a composition session, otherwise false
    - - 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. -

    - - -

    Keyboard events and key values

    - - This section contains necessary information regarding keyboard events: - - * Explanation of keyboard layout, mapping, and key values. - * Relations between keys, such as dead keys or modifiers keys. - * Relations between keyboard events and their default actions. - * The set of key values, and guidelines on how to extend this set. - -

    - This section uses Serbian and Kanji characters which could be misrepresented or - unavailable in the PDF version or printed version of this specification. -

    - -

    Keyboard Input

    - - This section is non-normative - - The relationship of each key to the complete keyboard has three separate - aspects, each of which vary among different models and configurations of - keyboards, particularly for locale-specific reasons: - - * Mechanical layout: the dimensions, size, and placement - of the physical keys on the keyboard - * Visual markings: the labels (or legends) that - mark each key - * Functional mapping: the abstract key-value association - of each key. - - This specification only defines the functional mapping, in terms of - key values and - code values, - but briefly describes key legends - for background. - -

    Key Legends

    - - This section is informative - - The key legend is the visual marking that is printed or embossed on the - key cap (the rectangular "cap" that covers the mechanical - switch for the key). These markings normally consist of one or more - characters that a keystroke on that key will produce (such as "G", - "8", or "ш"), or names or symbols which indicate that key's - function (such as an upward-pointing arrow "⇧" indicating - Shift, or the string "Enter"). Keys are often - referred to by this marking (e.g., Press the "Shift" and - "G" keys.). Note, however, that the visual appearance - of the key has no bearing on its digital representation, and in many - configurations may be completely inaccurate. Even the control and - function keys, such as Enter, may be mapped to different - functionality, or even mapped as character keys. - -

    - Many keyboards contain keys that do not normally produce any characters, - even though the symbol might have a Unicode equivalent. For example, the - Shift key might bear the symbol "⇧", which has the - Unicode code point U+21E7, but - pressing the Shift key will not produce this character value, - and there is no Unicode code point for Shift. -

    - -

    Key codes

    - - A key {{KeyboardEvent/code}} is an attribute of a keyboard event that can be - used to identify the physical key associated with the keyboard event. It is - similar to USB Usage IDs in that it provides a low-level value (similar to a - scancode) that is vendor-neutral. - - The primary purpose of the {{KeyboardEvent/code}} attribute is to provide a - consistent and coherent way to identify keys based on their physical - location. In addition, it also provides a stable name (unaffected by the - current keyboard state) that uniquely identifies each key on the keyboard. - - The list of valid {{KeyboardEvent/code}} values is defined in the - [[!UIEvents-Code]]. - -

    Motivation for the {{KeyboardEvent/code}} Attribute

    - - The standard PC keyboard has a set of keys (which we refer to as - writing system keys) that generate different - {{KeyboardEvent/key}} values based on the current keyboard layout - selected by the user. This situation makes it difficult to write code - that detects keys based on their physical location since the code would - need to know which layout is in effect in order to know which - {{KeyboardEvent/key}} values to check for. A real-world example of this - is a game that wants to use the "W", "A", "S" and - "D" keys to control player movement. The {{KeyboardEvent/code}} - attribute solves this problem by providing a stable value to check that - is not affected by the current keyboard layout. - - In addition, the values in the {{KeyboardEvent/key}} attribute depend as - well on the current keyboard state. Because of this, the order in which - keys are pressed and released in relation to modifier keys can affect - the values stored in the {{KeyboardEvent/key}} attribute. The - {{KeyboardEvent/code}} attribute solves this problem by providing a - stable value that is not affected by the current keyboard state. - -

    The Relationship Between {{KeyboardEvent/key}} and {{KeyboardEvent/code}}

    - -
    -
    {{KeyboardEvent/key}}
    -
    The {{KeyboardEvent/key}} attribute is intended for users who - are interested in the meaning of the key being pressed, taking - into account the current keyboard layout (and IME; - dead keys are given a unique - {{KeyboardEvent/key}} value). Example use case: Detecting - modified keys or bare modifier keys (e.g., to perform an action - in response to a keyboard shortcut). -
    - -
    {{KeyboardEvent/code}}
    -
    The {{KeyboardEvent/code}} attribute is intended for users who - are interested in the key that was pressed by the user, without - any layout modifications applied. Example use case: Detecting - WASD keys (e.g., for movement controls in a game) or trapping - all keys (e.g., in a remote desktop client to send all keys to - the remote host). -
    -
    - -

    code Examples

    - -
    - Handling the Left and Right Alt Keys - - - - - - - -
    Keyboard Layout{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		{{KeyboardEvent}}
    {{KeyboardEvent/code}}    		Notes
    US"Alt""AltLeft"{{KeyboardEvent/DOM_KEY_LOCATION_LEFT}}
    French"Alt""AltLeft"{{KeyboardEvent/DOM_KEY_LOCATION_LEFT}}
    US"Alt""AltRight"{{KeyboardEvent/DOM_KEY_LOCATION_RIGHT}}
    French"AltGraph""AltRight"{{KeyboardEvent/DOM_KEY_LOCATION_RIGHT}}
    - - In this example, checking the {{KeyboardEvent/key}} attribute permits - matching Alt without worrying about which Alt key (left or - right) was pressed. Checking the {{KeyboardEvent/code}} attribute - permits matching the right Alt key ("AltRight") without worrying - about which layout is currently in effect. - - Note that, in the French example, the Alt and AltGraph keys - retain their left and right location, even though there is only one of - each key. -
    - -
    - Handling the Single Quote Key - - - - - - -
    Keyboard Layout{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		{{KeyboardEvent}}
    {{KeyboardEvent/code}}    		Notes
    US"'""Quote"
    Japanese":""Quote"
    US Intl"Dead""Quote"
    - - This example shows how dead key values are encoded in the - attributes. The {{KeyboardEvent/key}} values vary based on the - current locale, whereas the {{KeyboardEvent/code}} attribute returns - a consistent value. -
    - -
    - Handling the "2" Key (with and without Shift pressed) on - various keyboard layouts. - - - - - - - - - -
    Keyboard Layout{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		{{KeyboardEvent}}
    {{KeyboardEvent/code}}    		Notes
    US"2""Digit2"
    US"@""Digit2"{{KeyboardEvent/shiftKey}}
    UK"2""Digit2"
    UK""""Digit2"{{KeyboardEvent/shiftKey}}
    French"é""Digit2"
    French"2""Digit2"{{KeyboardEvent/shiftKey}}
    - - Regardless of the current locale or the modifier key state, pressing - the key labelled "2" on a US keyboard always results in - "Digit2" in the {{KeyboardEvent/code}} attribute. - -
    - -
    - Sequence of Keyboard Events : Shift and 2 - - - Compare the attribute values in the following two key event - sequences. They both produce the "@" character on a US - keyboard, but differ in the order in which the keys are released. In - the first sequence, the order is: Shift (down), 2 - (down), 2 (up), Shift (up). - - - - - - - - -
    Event Type{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		{{KeyboardEvent}}
    {{KeyboardEvent/code}}    		Notes
    1keydown"Shift""ShiftLeft"{{KeyboardEvent/DOM_KEY_LOCATION_LEFT}}
    2keydown"@""Digit2"{{KeyboardEvent/shiftKey}}
    3keypress"@""Digit2"(if supported)
    4keyup"@""Digit2"{{KeyboardEvent/shiftKey}}
    5keyup"Shift""ShiftLeft"{{KeyboardEvent/DOM_KEY_LOCATION_LEFT}}
    - - In the second sequence, the Shift is released before the 2, - resulting in the following event order: Shift (down), - 2 (down), Shift (up), 2 (up). - - - - - - - - -
    Event Type{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		{{KeyboardEvent}}
    {{KeyboardEvent/code}}    		Notes
    1keydown"Shift""ShiftLeft"{{KeyboardEvent/DOM_KEY_LOCATION_LEFT}}
    2keydown"@""Digit2"{{KeyboardEvent/shiftKey}}
    3keypress"@""Digit2"(if supported)
    4keyup"Shift""ShiftLeft"{{KeyboardEvent/DOM_KEY_LOCATION_LEFT}}
    5keyup"2""Digit2"
    - - Note that the values contained in the {{KeyboardEvent/key}} - attribute does not match between the keydown and keyup events for - the "2" key. The {{KeyboardEvent/code}} attribute provides a - consistent value that is not affected by the current modifier state. - -
    - -

    {{KeyboardEvent/code}} and Virtual Keyboards

    - - The usefulness of the {{KeyboardEvent/code}} attribute is less obvious - for virtual keyboards (and also for remote controls and chording - keyboards). In general, if a virtual (or remote control) keyboard is - mimicking the layout and functionality of a standard keyboard, then it - MUST also set the {{KeyboardEvent/code}} attribute as appropriate. For - keyboards which are not mimicking the layout of a standard keyboard, - then the {{KeyboardEvent/code}} attribute MAY be set to the closest - match on a standard keyboard or it MAY be left undefined. - - For virtual keyboards with keys that produce different values based on - some modifier state, the {{KeyboardEvent/code}} value should be the - {{KeyboardEvent/key}} value generated when the button is pressed while - the device is in its factory-reset state. - -

    Keyboard Event key Values

    - - A key value is a DOMString that can be used to indicate any - given key on a keyboard, regardless of position or state, by the value it - produces. These key values MAY be used as return values for keyboard events - generated by the implementation, or as input values by the content author to - specify desired input (such as for keyboard shortcuts). - - The list of valid key values is defined in [[!UIEvents-Key]]. - - Key values can be used to detect the value of a key which has been pressed, - using the {{KeyboardEvent/key}} attribute. Content authors can retrieve the - character value of upper- or lower-case letters, number, symbols, or - other character-producing keys, and also the key value of control - keys, modifier keys, function keys, or other keys that do not generate - characters. These values can be used for monitoring particular input - strings, for detecting and acting on modifier key input in combination with - other inputs (such as a mouse), for creating virtual keyboards, or for any - number of other purposes. - - Key values can also be used by content authors in string comparisons, as - values for markup attributes (such as the HTML accesskey) in - conforming host languages, or for other related purposes. A - conforming host language SHOULD allow content authors to use either - of the two equivalent string values for a key value: the character - value, or the key value. - -

    - While implementations will use the most relevant value for a key - independently of the platform or keyboard layout mappings, content authors - can not make assumptions on the ability of keyboard devices to generate - them. When using keyboard events and key values for shortcut-key - combinations, content authors can consider using numbers and function - keys (F4, F5, and so on) instead of letters ([[DWW95]]) - given that most keyboard layouts will provide keys for those. -

    - - A key value does not indicate a specific key on the physical keyboard, nor - does it reflect the character printed on the key. A key value indicates the - current value of the event with consideration to the current state of all - active keys and key input modes (including shift modes), as reflected in the - operating-system mapping of the keyboard and reported to the implementation. - In other words, the key value for the key labeled O on a - QWERTY keyboard has the key value "o" in an unshifted state and - "O" in a shifted state. Because a user can map their keyboard to an - arbitrary custom configuration, the content author is encouraged not to - assume that a relationship exists between the shifted and unshifted states - of a key and the majuscule form (uppercase or capital letters) and minuscule - form (lowercase or small letters) of a character representation, but is - encouraged instead to use the value of the {{KeyboardEvent/key}} attribute. - For example, the Standard "102" Keyboard layout depicted in [[UIEvents-Code]] - illustrates one possible set of key mappings on one possible keyboard - layout. Many others exist, both standard and idiosyncratic. - -

    - To simplify dead key support, when the operating-system mapping of - the keyboard is handling a dead key state, the current state of the - dead key sequence is not reported via the {{KeyboardEvent/key}} attribute. - Rather, a key value of "Dead" is reported. Instead, implementations - generate composition events which - contain the intermediate state of the dead key sequence reported via the - {{CompositionEvent/data}} attribute. As in the previous example, the key - value for the key marked O on a QWERTY keyboard has a - {{CompositionEvent/data}} value of "ö" in an - unshifted state during a dead-key operation to add an umlaut diacritic, and - "Ö" in a shifted state during a dead-key - operation to add an umlaut diacritic. -

    - - It is also important to note that there is not a one-to-one relationship - between key event states and key values. A particular key value might be - associated with multiple keys. For example, many standard keyboards contain - more than one key with the Shift key value (normally distinguished - by the {{KeyboardEvent/location}} values - {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} and - {{KeyboardEvent/DOM_KEY_LOCATION_RIGHT}}) or 8 key value (normally - distinguished by the {{KeyboardEvent/location}} values - {{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}} and - {{KeyboardEvent/DOM_KEY_LOCATION_NUMPAD}}), and user-configured custom - keyboard layouts MAY duplicate any key value in multiple key-state scenarios - (note that {{KeyboardEvent/location}} is intended for standard keyboard - layouts, and cannot always indicate a meaningful distinction). - - Finally, the meaning of any given character representation is - context-dependent and complex. For example, in some contexts, the asterisk - (star) glyph ("*") represents a footnote or - emphasis (when bracketing a passage of text). However, in some documents or - executable programs it is equivalent to the mathematical multiplication - operation, while in other documents or executable programs, that function is - reserved for the multiplication symbol ("×", Unicode value - U+00D7) or the Latin small letter "x" - (due to the lack of a multiplication key on many keyboards and the - superficial resemblance of the glyphs "×" and "x"). Thus, - the semantic meaning or function of character representations is outside the - scope of this specification. - -

    Modifier keys

    - - Keyboard input uses modifier keys to change the normal behavior of a - key. Like other keys, modifier keys generate keydown and - keyup events, as shown in the example below. Some modifiers are - activated while the key is being pressed down or maintained pressed such - as Alt, Control, Shift, AltGraph, or - Meta. Other modifiers are activated depending on their state - such as CapsLock, NumLock, or ScrollLock. Change - in the state happens when the modifier key is being pressed down. The - {{KeyboardEvent}} interface provides convenient attributes for some - common modifiers keys: {{KeyboardEvent/ctrlKey}}, - {{KeyboardEvent/shiftKey}}, {{KeyboardEvent/altKey}}, - {{KeyboardEvent/metaKey}}. Some operating systems simulate the - AltGraph modifier key with the combination of the Alt - and Control modifier keys. Implementations are encouraged to use - the AltGraph modifier key. - -
    - This example describes a possible sequence of events - associated with the generation of the Unicode character Q (Latin - Capital Letter Q, Unicode code point U+0051) on a US - keyboard using a US mapping: - - - - - - - - - -
    Event Type{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		ModifiersNotes
    1keydown"Shift"{{KeyboardEvent/shiftKey}}
    2keydown"Q"{{KeyboardEvent/shiftKey}}Latin Capital Letter Q
    3beforeinput
    4input
    5keyup"Q"{{KeyboardEvent/shiftKey}}
    6keyup"Shift"
    -
    - -
    - Th example describes an alternate sequence of keys to the - example above, where the Shift key is released before the - Q key. The key value for the Q key will revert to its - unshifted value for the keyup event: - - - - - - - - - -
    Event Type{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		ModifiersNotes
    1keydown"Shift"{{KeyboardEvent/shiftKey}}
    2keydown"Q"{{KeyboardEvent/shiftKey}}Latin Capital Letter Q
    3beforeinput
    4input
    5keyup"Shift"
    6keyup"q"Latin Small Letter Q
    -
    - -
    - The following example describes a possible sequence of keys that - does not generate a Unicode character (using the same configuration - as the previous example): - - - - - - - - -
    Event Type{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		ModifiersNotes
    1keydown"Control"{{KeyboardEvent/ctrlKey}}
    2keydown"v"{{KeyboardEvent/ctrlKey}}Latin Small Letter V
    No beforeinput or input events are generated.
    3keyup"v"{{KeyboardEvent/ctrlKey}}Latin Small Letter V
    4keyup"Control"
    -
    - -
    - The following example shows the sequence of events when both Shift and - Control are pressed: - - - - - - - - - - -
    Event Type{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		ModifiersNotes
    1keydown"Control"{{KeyboardEvent/ctrlKey}}
    2keydown"Shift"{{KeyboardEvent/ctrlKey}}, {{KeyboardEvent/shiftKey}}
    3keydown"V"{{KeyboardEvent/ctrlKey}}, {{KeyboardEvent/shiftKey}}Latin Capital Letter V
    No beforeinput or input events are generated.
    4keyup"V"{{KeyboardEvent/ctrlKey}}, {{KeyboardEvent/shiftKey}}Latin Capital Letter V
    5keyup"Shift"{{KeyboardEvent/ctrlKey}}
    6keyup"Control"
    -
    - -
    - For non-US keyboard layouts, the sequence of events is the same, but - the value of the key is based on the current keyboard layout. This - example shows a sequence of events when an Arabic keyboard layout is - used: - - - - - - - - -
    Event Type{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		ModifiersNotes
    1keydown"Control"{{KeyboardEvent/ctrlKey}}
    2keydown"ر"{{KeyboardEvent/ctrlKey}}Arabic Letter Reh
    No beforeinput or input events are generated.
    3keyup"ر"{{KeyboardEvent/ctrlKey}}Arabic Letter Reh
    4keyup"Control"
    -
    - -

    - The value in the keydown and keyup events varies based on - the current keyboard layout in effect when the key is pressed. This - means that the v key on a US layout and the ر key on an - Arabic layout will generate different events even though they are the - same physical key. To identify these events as coming from the same - physical key, you will need to make use of the {{KeyboardEvent/code}} - attribute. -

    - - In some cases, modifier keys change the {{KeyboardEvent/key}} - value for a key event. For example, on some MacOS keyboards, the key - labeled "delete" functions the same as the Backspace key on the - Windows OS when unmodified, but when modified by the Fn key, - acts as the Delete key, and the value of {{KeyboardEvent/key}} - will match the most appropriate function of the key in its current - modified state. - -

    Dead keys

    - - Some keyboard input uses dead keys for the input of composed - character sequences. Unlike the handwriting sequence, in which users - enter the base character first, keyboard input requires to enter a - special state when a dead key is pressed and emit the - character(s) only when one of a limited number of legal base - character is entered. - -

    - The MacOS and Linux operating systems use input methods to process - dead keys. -

    - - The dead keys (across all keyboard layouts and mappings) are - represented by the key value Dead. In response to any dead key - press, composition events must - be dispatched by the user agent and the compositionupdate event's - {{CompositionEvent/data}} value must be the character value of the - current state of the dead key combining sequence. - - While Unicode combining characters always follow the handwriting - sequence, with the combining character trailing the corresponding - letter, typical dead key input MAY reverse the sequence, with the - combining character before the corresponding letter. For example, the - word naïve, using the combining diacritic ¨, would be - represented sequentially in Unicode as nai¨ve, but MAY be typed - na¨ive. The sequence of keystrokes U+0302 (Combining - Circumflex Accent key) and U+0065 (key marked with the Latin Small - Letter E) will likely produce (on a French keyboard using a french - mapping and without any modifier activated) the Unicode character - "ê" (Latin Small Letter E With Circumflex), as preferred by - the Unicode Normalization Form NFC. - -
    - - - - - - - - - - -
    Event Type{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		{{KeyboardEvent}}
    {{KeyboardEvent/isComposing}}    		{{CompositionEvent}}
    {{CompositionEvent/data}}    		Notes
    1keydown"Dead"falseCombining Circumflex Accent (Dead Key)
    2compositionstart""
    3compositionupdateU+0302
    4keyup"Dead"true
    5keydown"ê"true
    6compositionupdate"ê"
    7compositionend"ê"
    8keyup"e"falseLatin Small Letter E
    -
    - -

    - In the second keydown event (step 5), the key value (assuming the - event is not suppressed) will not be "e" (Latin Small - Letter E key) under normal circumstances because the value delivered to - the user agent will already be modified by the dead key operation. -

    - - This process might be aborted when a user types an unsupported base - character (that is, a base character for which the active - diacritical mark is not available) after pressing a dead key: - -
    - - - - - - - - - - -
    Event Type{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		{{KeyboardEvent}}
    {{KeyboardEvent/isComposing}}    		{{CompositionEvent}}
    {{CompositionEvent/data}}    		Notes
    1keydown"Dead"falseCombining Circumflex Accent (Dead Key)
    2compositionstart""
    3compositionupdateU+0302
    4keyup"Dead"true
    5keydown"q"trueLatin Small Letter Q
    6compositionupdate""
    7compositionend""
    8keyup"q"false
    -
    - -

    Input Method Editors

    - - This specification includes a model for input method editors - (IMEs), through the {{CompositionEvent}} interface and events. - However, Composition Events and Keyboard Events do not necessarily map - as a one-to-one relationship. As an example, receiving a keydown - for the Accept key value does not necessarily imply that the - text currently selected in the IME is being accepted, but - indicates only that a keystroke happened, disconnected from the - IME Accept functionality (which would normally result in a - compositionend event in most IME systems). Keyboard - events cannot be used to determine the current state of the input method - editor, which can be obtained through the {{CompositionEvent/data}} - attribute of the {{CompositionEvent}} interface. Additionally, - IME systems and devices vary in their functionality, and in which - keys are used for activating that functionality, such that the - Convert and Accept keys MAY be represented by other - available keys. Keyboard events correspond to the events generated by - the input device after the keyboard layout mapping. - -

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

    - - The following example describes a possible sequence of keys to generate - the Unicode character "市" (Kanji character, part of CJK - Unified Ideographs) using Japanese input methods. This example assumes - that the input method editor is activated and in the Japanese-Romaji - input mode. The keys Convert and Accept MAY be replaced - by others depending on the input device in use and the configuration of - the IME, e.g., it can be respectively U+0020 (Space key) and - Enter. - -

    - "詩" (poem) and "市" (city) are - homophones, both pronounced し (shi/si), so the user - needs to use the Convert key to select the proper option. -

    - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event Type{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		{{KeyboardEvent}}
    {{KeyboardEvent/isComposing}}    		{{CompositionEvent}}
    {{CompositionEvent/data}}    		Notes
    1keydown"s"falseLatin Small Letter S
    2compositionstart""
    3beforeinput
    4compositionupdate"s"
    DOM is updated
    5input
    6keyup"s"true
    7keydown"i"trueLatin Small Letter I
    8beforeinput
    9compositionupdate"し"shi
    DOM is updated
    10input
    11keyup"i"true
    12keydown"Convert"trueConvert
    13beforeinput
    14compositionupdate"詩""poem"
    DOM is updated
    15input
    16keyup"Convert"true
    17keydown"Convert"trueConvert
    18beforeinput
    19compositionupdate"市""city"
    DOM is updated
    20input
    21keyup"Convert"true
    22keydown"Accept"trueAccept
    23compositionend"市"
    24keyup"Accept"false
    -
    - - IME composition can also be canceled as in the following example, with - conditions identical to the previous example. The key Cancel - might also be replaced by others depending on the input device in use - and the configuration of the IME, e.g., it could be U+001B (Escape - key). - -
    - - - - - - - - - - - - - - - - - - - -
    Event Type{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		{{KeyboardEvent}}
    {{KeyboardEvent/isComposing}}    		{{CompositionEvent}}
    {{CompositionEvent/data}}    		Notes
    1keydown"s"falseLatin Small Letter S
    2compositionstart""
    3compositionupdate"s"
    4keyup"s"true
    5keydown"i"trueLatin Small Letter I
    6compositionupdate"し"shi
    7keyup"i"true
    8keydown"Convert"trueConvert
    9compositionupdate"詩""poem"
    10keyup"Convert"true
    11keydown"Convert"trueConvert
    12compositionupdate"市""city"
    13keyup"Convert"true
    14keydown"Cancel"trueCancel
    15compositionupdate""
    16compositionend""
    17keyup"Cancel"false
    -
    - -

    - Some input method editors (such as on the MacOS operating system) - might set an empty string to the composition data attribute - before canceling a composition. -

    - -
    Input Method Editor mode keys
    - - Some keys on certain devices are intended to activate input - method editor functionality, or to change the mode of an active - input method editor. Custom keys for this purpose can be - defined for different devices or language modes. The keys defined in - this specification for this purpose are: "Alphanumeric", - "CodeInput", "FinalMode", "HangulMode", "HanjaMode", - "Hiragana", "JunjaMode", "KanaMode", "KanjiMode", - "Katakana", and "Romaji". When one of these keys is - pressed, and no IME is currently active, the appropriate - IME is expected to be activated in the mode indicated by the - key (if available). If an IME is already active when the key - is pressed, the active IME might change to the indicated - mode, or a different IME might be launched, or the might MAY - be ignored, on a device- and application-specific basis. - - This specification also defines other keys which are intended for - operation specifically with input method editors: - "Accept", "AllCandidates", "Cancel", "Convert", - "Compose", "Zenkaku" (FullWidth), "Hankaku" (HalfWidth), "NextCandidate", - "NonConvert", and "PreviousCandidate". The functions of these - keys are not defined in this specification — refer to other - resources for details on input method editor functionality. - -

    - Keys with input method editor functions are not restricted to - that purpose, and can have other device- or implementation-specific - purposes. -

    - -

    Default actions and cancelable keyboard events

    - - Canceling the default action of a keydown event MUST NOT - affect its respective keyup event, but it MUST prevent the - respective beforeinput and input (and keypress if - supported) events from being generated. The following example describes - a possible sequence of keys to generate the Unicode character Q (Latin - Capital Letter Q) on a US keyboard using a US mapping: - -
    - - - - - - - -
    Event Type{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		{{InputEvent}}
    {{InputEvent/data}}    		ModifiersNotes
    1keydown"Shift"{{KeyboardEvent/shiftKey}}
    2keydown"Q"{{KeyboardEvent/shiftKey}}The default action is prevented, e.g., by invoking {{Event/preventDefault()}}.
    No beforeinput or input (or keypress, if supported) events are generated
    3keyup"Q"{{KeyboardEvent/shiftKey}}
    4keyup"Shift"
    -
    - - If the key is a modifier key, the keystroke MUST still be taken into - account for the modifiers states. The following example describes a - possible sequence of keys to generate the Unicode character Q (Latin - Capital Letter Q) on a US keyboard using a US mapping: - -
    - - - - - - - - -
    Event Type{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		{{InputEvent}}
    {{InputEvent/data}}    		ModifiersNotes
    1keydown"Shift"{{KeyboardEvent/shiftKey}}The default action is prevented, e.g., by invoking {{Event/preventDefault()}}.
    2keydown"Q"{{KeyboardEvent/shiftKey}}
    3beforeinput"Q"
    4input
    5keyup"Q"{{KeyboardEvent/shiftKey}}
    6keyup"Shift"
    -
    - - If the key is part of a sequence of several keystrokes, whether it is a - dead key or it is contributing to an Input Method Editor - sequence, the keystroke MUST be ignored (not taken into account) only if - the default action is canceled on the keydown event. - Canceling a dead key on a keyup event has no effect on - beforeinput or input events. The following example uses - the dead key "Dead" (U+0302 Combining Circumflex Accent key) and - "e" (U+0065, Latin Small Letter E key) on a French - keyboard using a French mapping and without any modifier activated: - -
    - - - - - - - - -
    Event Type{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		{{InputEvent}}
    {{InputEvent/data}}    		Notes
    1keydown"Dead"The default action is prevented, e.g., by invoking {{Event/preventDefault()}}.
    2keyup"Dead"
    3keydown"e"
    4beforeinput"e"
    5input
    6keyup"e"
    -
    - -

    Constructing Mouse and Keyboard Events

    - - Generally, when a constructor of an {{Event}} interface, or of an interface - inherited from the {{Event}} interface, is invoked, the steps described in - [[!DOM]] should be followed. However the {{KeyboardEvent}} and - {{MouseEvent}} interfaces provide additional dictionary members for - initializing the internal state of the {{Event}} object's key modifiers: - specifically, the internal state queried for using the - {{KeyboardEvent/getModifierState()}} and {{MouseEvent/getModifierState()}} - methods. This section supplements the DOM4 steps for intializing a new - {{Event}} object with these optional modifier states. - - For the purposes of constructing a {{KeyboardEvent}}, {{MouseEvent}}, or - object derived from these objects using the algorithm below, all - {{KeyboardEvent}}, {{MouseEvent}}, and derived objects have - internal key modifier state which can be set and - retrieved using the key modifier names - described in the - Modifier Keys table - in [[UIEvents-Key]]. - - The following steps supplement the algorithm defined for constructing - events in DOM4: - - * If the {{Event}} being constructed is a {{KeyboardEvent}} or - {{MouseEvent}} object or an object that derives from either of these, - and a {{EventModifierInit}} argument was provided to the constructor, - then run the following sub-steps: - - * For each {{EventModifierInit}} argument, if the dictionary member - begins with the string "modifier", then let the - key modifier name be the - dictionary member's name excluding the prefix - "modifier", and set the {{Event}} object's - internal key modifier state - that matches the key modifier name - to the corresponding value. - -

    Legacy {{KeyboardEvent}} events

    - - The keypress event is the traditional method for capturing key events - and processing them before the DOM is updated with the effects of the key - press. Code that makes use of the keypress event typically relies on - the legacy {{KeyboardEvent/charCode}}, {{KeyboardEvent/keyCode}}, and - {{UIEvent/which}} attributes. - - Note that the keypress event is specific to key events, and has been - replaced by the more general event sequence of beforeinput and - input events. These new input events are not specific to - keyboard actions and can be used to capture user input regardless of the - original source. - -

    Legacy {{KeyboardEvent}} event types

    - -

    keypress

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typekeypress
    Interface{{KeyboardEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    ComposedYes
    Default actionVaries: - launch text composition system; - blur and focus events; - DOMActivate event; - other event
    Context
    (trusted events)    		 -
      -
    • {{Event}}.{{Event/target}} : - focused element processing the key event or if no element focused, then the - body element if available, otherwise the - root element
      • -
    • {{UIEvent}}.{{UIEvent/view}} : - Window
      • -
    • {{UIEvent}}.{{UIEvent/detail}} : - 0
      • -
    • {{KeyboardEvent}}.{{UIEvent/which}} : - legacy numerical code for this key
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/charCode}} : - legacy character value for this event
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/keyCode}} : - legacy numerical code for this key
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/key}} : - the key value of the key pressed.
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/code}} : - the code value associated with the key's physical placement on the keyboard.
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/location}} : - the location of the key on the device.
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/altKey}} : - true if Alt modifier was active, otherwise false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/shiftKey}} : - true if Shift modifier was active, otherwise false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/ctrlKey}} : - true if Control modifier was active, otherwise false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/metaKey}} : - true if Meta modifier was active, otherwise false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/repeat}} : - false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/isComposing}} : - true if the key event occurs as part of a composition session, otherwise false
      • -
    -
    - - If supported by a user agent, this event MUST be dispatched - when a key is pressed down, if and only if that key normally - produces a character value. The keypress 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. It - MUST NOT be fired when using an input method editor. - - If this event is canceled, it should prevent the input event - from firing, in addition to canceling the default action. - - Authors SHOULD use the beforeinput event instead of the - keypress event. - -

    - The keypress event is traditionally associated with detecting - a character value rather than a physical key, and might not - be available on all keys in some configurations. -

    - -

    - The keypress event type is defined in this specification for - reference and completeness, but this specification deprecates - the use of this event type. When in editing contexts, authors can - subscribe to the beforeinput event instead. -

    - -

    keypress event order

    - - The keypress event type MUST be dispatched after the - keydown event and before the keyup event associated with - the same key. - - The keypress event type MUST be dispatched after the - beforeinput event and before the input event associated - with the same key. - - The sequence of key events for user-agents the support the - keypress event is demonstrated in the following example: - -
    - - - - - - - - -
    Event Type{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		{{InputEvent}}
    {{InputEvent/data}}    		Notes
    1keydown"a"
    2beforeinput"a"
    3keypress"a"
    Any default actions related to this key, such as inserting a character in to the DOM.
    4input
    5keyup"a"
    -
    - -

    Legacy Event Initializers

    - - This section is normative. - - The following features are obsolete and should only be implemented by - user agents that require compatibility with legacy software. - - Early versions of this specification included an initialization method on - the interface (for example initMouseEvent) that required a long - list of parameters that, in most cases, did not fully initialize all - attributes of the event object. Because of this, event interfaces which were - derived from the basic {{Event}} interface required that the initializer of - each of the derived interfaces be called explicitly in order to - fully initialize an event. - -
    - Initializing all the attributes of a UIEvent requires calls to two - initializer methods: initEvent and - initUIEvent. -
    - - Due in part to the length of time in the development of this standard, some - implementations MAY have taken a dependency on these (now deprecated) - initializer methods. For completeness, these legacy event initializers are - described in this section. - -

    Initializers for interface KeyboardEvent

    - - This section is informative - -

    - The argument list to this legacy KeyboardEvent initializer does not - include the detailArg (present in other initializers) and - adds the locale argument (see [[#changes-drafts]]); it is - necessary to preserve this inconsistency for compatibility with existing - implementations. -

    - - 
    -		partial interface KeyboardEvent {
-			// Originally introduced (and deprecated) in this specification
-			undefined initKeyboardEvent(DOMString typeArg,
-				optional boolean bubblesArg = false,
-				optional boolean cancelableArg = false,
-				optional Window? viewArg = null,
-				optional DOMString keyArg = "",
-				optional unsigned long locationArg = 0,
-				optional boolean ctrlKey = false,
-				optional boolean altKey = false,
-				optional boolean shiftKey = false,
-				optional boolean metaKey = false);
-		};
-
    - -
    -
    initKeyboardEvent(typeArg)
    -
    - Initializes attributes of a {{KeyboardEvent}} object. This - method has the same behavior as UIEvent.initUIEvent(). - The value of {{UIEvent/detail}} remains undefined. - -

    - The initKeyboardEvent method is deprecated. -

    - -
    -
    DOMString typeArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    boolean bubblesArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    boolean cancelableArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    Window? viewArg
    -
    - Specifies {{UIEvent/view}}. This value MAY be null. -
    - -
    DOMString keyArg
    -
    - Specifies {{KeyboardEvent/key}}. -
    - -
    unsigned long locationArg
    -
    - Specifies {{KeyboardEvent/location}}. -
    - -
    boolean ctrlKey
    -
    - Specifies whether the Control key modifier is active. -
    - -
    boolean altKey
    -
    - Specifies whether the Alt key modifier is active. -
    - -
    boolean shiftKey
    -
    - Specifies whether the Shift key modifier is active. -
    - -
    boolean metaKey
    -
    - Specifies whether the Meta key modifier is active. -
    -
    -
    -
    - -

    Legacy Key & Mouse Event Attributes

    - - This section is non-normative. The following attributes are obsolete and should - only be implemented by user agents that require compatibility with legacy - software that requires these keyboard events. - - These features were never formally specified and the current browser - implementations vary in significant ways. - -

    Legacy {{KeyboardEvent}} supplemental interface

    - - This section is non-normative - - Browser support for keyboards has traditionally relied on three ad-hoc - attributes, {{KeyboardEvent/keyCode}}, {{KeyboardEvent/charCode}}, and - {{UIEvent}}'s {{UIEvent/which}}. - - All three of these attributes return a numerical code that represents some - aspect of the key pressed: {{KeyboardEvent/keyCode}} is an index of the key - itself. {{KeyboardEvent/charCode}} is the ASCII value of the character keys. - {{UIEvent/which}} is the character value where available and otherwise - the key index. The values for these attributes, and the availability of the - attribute, is inconsistent across platforms, keyboard languages and layouts, - user agents, versions, and even event types. - -

    Interface KeyboardEvent (supplemental)

    - - The partial {{KeyboardEvent}} interface is an informative extension of - the {{KeyboardEvent}} interface, which adds the - {{KeyboardEvent/charCode}} and {{KeyboardEvent/keyCode}} attributes. - - The partial {{KeyboardEvent}} interface can be obtained by using the - {{Document/createEvent()}} method call in - implementations that support this extension. - - 
    -			partial interface KeyboardEvent {
-			  // The following support legacy user agents
-			  readonly attribute unsigned long charCode;
-			  readonly attribute unsigned long keyCode;
-			};
-
    - -
    -
    charCode
    -
    - {{KeyboardEvent/charCode}} holds a character value, for - keypress events which generate character input. The value - is the Unicode reference number (code point) of that character - (e.g. event.charCode = event.key.charCodeAt(0) for - printable characters). For keydown or keyup - events, the value of {{KeyboardEvent/charCode}} is - 0. -
    - -
    keyCode
    -
    - {{KeyboardEvent/keyCode}} holds a system- and - implementation-dependent numerical code signifying the - unmodified identifier associated with the key pressed. Unlike - the {{KeyboardEvent/key}} attribute, the set of possible values - are not normatively defined in this specification. Typically, - these value of the {{KeyboardEvent/keyCode}} SHOULD represent - the decimal codepoint in ASCII [[RFC20]][[US-ASCII]] or Windows - 1252 [[WIN1252]], but MAY be drawn from a different appropriate - character set. Implementations that are unable to identify a key - use the key value 0. - - See [[#legacy-key-models]] for more details on how to determine - the values for {{KeyboardEvent/keyCode}}. -
    -
    - -

    Interface KeyboardEventInit (supplemental)

    - - Browsers that include support for {{KeyboardEvent/keyCode}} - and {{KeyboardEvent/charCode}} in - {{KeyboardEvent}} should also add the following members to the - {{KeyboardEventInit}} dictionary. - - The partial {{KeyboardEventInit}} dictionary is an informative extension - of the {{KeyboardEventInit}} dictionary, which adds - {{KeyboardEvent/charCode}} and {{KeyboardEvent/keyCode}} - members to initialize the corresponding - {{KeyboardEvent}} attributes. - - 
    -			partial dictionary KeyboardEventInit {
-			  // The following support legacy user agents
-			  unsigned long charCode = 0;
-			  unsigned long keyCode = 0;
-			};
-
    - -
    -
    charCode
    -
    - Initializes the {{KeyboardEvent/charCode}} attribute of the - {{KeyboardEvent}} to the Unicode code point for the event's - character. -
    - -
    keyCode
    -
    - Initializes the {{KeyboardEvent/keyCode}} attribute of the - {{KeyboardEvent}} to the system- and implementation-dependent - numerical code signifying the unmodified identifier associated - with the key pressed. -
    -
    - -

    Legacy key models

    - - This section is non-normative - - Implementations differ on which values are exposed on these attributes for - different event types. An implementation MAY choose to expose both virtual - key codes and character codes in the {{KeyboardEvent/keyCode}} property - (conflated model), or report separate {{KeyboardEvent/keyCode}} and - {{KeyboardEvent/charCode}} properties (split model). - -

    How to determine {{KeyboardEvent/keyCode}} for keydown and keyup events

    - - The {{KeyboardEvent/keyCode}} for keydown or keyup events - is calculated as follows: - - * Read the virtual key code from the operating system's event - information, if such information is available. - - * If an Input Method Editor is processing key input and the event is - keydown, return 229. - - * If input key when pressed without modifiers would insert a numerical - character (0-9), return the ASCII code of that numerical character. - - * If input key when pressed without modifiers would insert a lower - case character in the a-z alphabetical range, return the ASCII code - of the upper case equivalent. - - * If the implementation supports a key code conversion table for the - operating system and platform, look up the value. If the conversion - table specifies an alternate virtual key value for the given input, - return the specified value. - - * If the key's function, as determined in an implementation-specific - way, corresponds to one of the keys in the - [[#fixed-virtual-key-codes]] table, return the corresponding key - code. - - * Return the virtual key code from the operating system. - - * If no key code was found, return 0. - -

    How to determine {{KeyboardEvent/keyCode}} for keypress events

    - - The {{KeyboardEvent/keyCode}} for keypress events is calculated - as follows: - - * If the implementation supports a conflated model, set - {{KeyboardEvent/keyCode}} to the Unicode code point of the character - being entered. - - * If the implementation supports a split model, set - {{KeyboardEvent/keyCode}} to 0. - -

    Fixed virtual key codes

    - - The virtual key codes for the following keys do not usually change with - keyboard layouts on desktop systems: - - - - - - - - - - - - - - - - - - - - - -
    KeyVirtual Key
    Code    		Notes
    Backspace8
    Tab9
    Enter13
    Shift16
    Control17
    Alt18
    CapsLock20
    Escape27Esc
    Space32
    PageUp33
    PageDown34
    End35
    Home36
    ArrowLeft37
    ArrowUp38
    ArrowRight39
    ArrowDown40
    Delete46Del
    - -

    Optionally fixed virtual key codes

    - - The following punctuation characters MAY change virtual codes between - keyboard layouts, but reporting these values will likely be more - compatible with legacy content expecting US-English keyboard layout: - - - - - - - - - - - - - - - - - - - - - - - - - -
    KeyCharacterVirtual Key
    Code
    Semicolon";"186
    Colon":"186
    Equals sign"="187
    Plus"+"187
    Comma","188
    Less than sign"<"188
    Minus"-"189
    Underscore"_"189
    Period"."190
    Greater than sign">"190
    Forward slash"/"191
    Question mark"?"191
    Backtick"`"192
    Tilde"~"192
    Opening squace bracket"["219
    Opening curly brace"{"219
    Backslash"\"220
    Pipe"|"220
    Closing square bracket"]"221
    Closing curly brace"}"221
    Single quote"'"222
    Double quote"""222
    - -

    Legacy Event Types

    - - This section is normative. The following event types are obsolete and should - only be implemented by user agents that require compatibility with legacy - software. - -

    Legacy {{KeyboardEvent}} events

    - - The keypress event is the traditional method for capturing key events - and processing them before the DOM is updated with the effects of the key - press. Code that makes use of the keypress event typically relies on - the legacy {{KeyboardEvent/charCode}}, {{KeyboardEvent/keyCode}}, and - {{UIEvent/which}} attributes. - - Note that the keypress event is specific to key events, and has been - replaced by the more general event sequence of beforeinput and - input events. These new input events are not specific to - keyboard actions and can be used to capture user input regardless of the - original source. - -

    Legacy {{KeyboardEvent}} event types

    - -
    keypress
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typekeypress
    Interface{{KeyboardEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    ComposedYes
    Default actionVaries: - launch text composition system; - blur and focus events; - DOMActivate event; - other event
    Context
    (trusted events)    		 -
      -
    • {{Event}}.{{Event/target}} : - focused element processing the key event or if no element focused, then the - body element if available, otherwise the - root element
      • -
    • {{UIEvent}}.{{UIEvent/view}} : - Window
      • -
    • {{UIEvent}}.{{UIEvent/detail}} : - 0
      • -
    • {{KeyboardEvent}}.{{UIEvent/which}} : - legacy numerical code for this key
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/charCode}} : - legacy character value for this event
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/keyCode}} : - legacy numerical code for this key
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/key}} : - the key value of the key pressed.
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/code}} : - the code value associated with the key's physical placement on the keyboard.
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/location}} : - the location of the key on the device.
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/altKey}} : - true if Alt modifier was active, otherwise false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/shiftKey}} : - true if Shift modifier was active, otherwise false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/ctrlKey}} : - true if Control modifier was active, otherwise false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/metaKey}} : - true if Meta modifier was active, otherwise false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/repeat}} : - false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/isComposing}} : - true if the key event occurs as part of a composition session, otherwise false
      • -
    -
    - - If supported by a user agent, this event MUST be dispatched - when a key is pressed down, if and only if that key normally - produces a character value. The keypress 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. It - MUST NOT be fired when using an input method editor. - - If this event is canceled, it should prevent the input event - from firing, in addition to canceling the default action. - - Authors SHOULD use the beforeinput event instead of the - keypress event. - -

    - The keypress event is traditionally associated with detecting - a character value rather than a physical key, and might not - be available on all keys in some configurations. -

    - -

    - The keypress event type is defined in this specification for - reference and completeness, but this specification deprecates - the use of this event type. When in editing contexts, authors can - subscribe to the beforeinput event instead. -

    - -

    keypress event order

    - - The keypress event type MUST be dispatched after the - keydown event and before the keyup event associated with - the same key. - - The keypress event type MUST be dispatched after the - beforeinput event and before the input event associated - with the same key. - - The sequence of key events for user-agents the support the - keypress event is demonstrated in the following example: - -
    - - - - - - - - -
    Event Type{{KeyboardEvent}}
    {{KeyboardEvent/key}}    		{{InputEvent}}
    {{InputEvent/data}}    		Notes
    1keydown"a"
    2beforeinput"a"
    3keypress"a"
    Any default actions related to this key, such as inserting a character in to the DOM.
    4input
    5keyup"a"
    -
    - -

    Security Considerations

    - - TODO - Add specific concerns for this spec - -

    Acknowledgements

    - - TODO - -

    Refs to other UIEvent specs \[DELETE]

    - - This section will be deleted. - - Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references. - - beforeinput - blur - click - compositionend - compositionstart - compositionupdate - DOMActivate - input - -

    Things defined in other sections

    - -

    Activation triggers and behavior

    -

    Default actions and cancelable events

    -

    Event dispatch and DOM event flow

    -

    Focus Events

    -

    Web browsers and other dynamic or interactive user agents

    -

    Authoring tools

    - -

    Things defined in CompositionEvents

    -

    Composition Events

    - -

    Things defined in Changes

    -

    Changes between different drafts of UI Events

    - -

    Glossary \[DELETE]

    - -This section will be deleted. - -Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline. - -: 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 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 - [[#event-flow-activation]] for more details. - -: activation trigger -:: An event which is defined to initiate an activation behavior. Refer - to [[#event-flow-activation]] for more details. - -: body element -:: In HTML or XHTML documents, the body element represents the contents of the - document. In a well-formed HTML document, the body element is a first - descendant of the root element. - -: 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, each - belonging to the set of valid Unicode character categories. - In this specification, character values are denoted as a unicode string - (e.g., U+0020) or a glyph representation of the same code point (e.g., - " "), and are color coded to help distinguish these two representations. - -

    - In source code, some key values, such as non-graphic characters, can 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 - [[#event-flow-default-cancel]]. - -: 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. - -: 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 event - target. Each event is an instantiation of one specific event - type. - -: event target -:: The object to which an event is targeted using the [[#event-flow]]. - The event target is the value of the {{Event/target}} attribute. - -: 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 UI Events, and they integrate and extend the objects - and models defined in this specification. - -: IME -: input method editor -:: An input method editor (IME), also known as a front end - processor, is an application that performs the conversion between - keystrokes and ideographs or other characters, usually by user-guided - dictionary lookup, often used in East Asian languages (e.g., Chinese, - Japanese, Korean). An IME MAY also be used for dictionary-based word - completion, such as on mobile devices. See [[#keys-IME]] for treatment of - IMEs in this specification. See also text composition system. - -: 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, et al.) and dead key states. - -: key value -:: A key value is a character value or multi-character string (such as - "Enter", "Tab", or "MediaTrackNext") 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. - -: 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). See [[#keys-modifiers]] for more information about modifier keys and - refer to the [=Modifier Keys table=] in [[UIEvents-Key]] for a list - of valid modifier keys. - -: 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. - -: 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. - -: Unicode character categories -:: A subset of the General Category values that are defined for each Unicode - code point. This subset contains all the - Letter (Ll, - Lm, - Lo, - Lt, - Lu), - Number (Nd, - Nl, - No), - Punctuation (Pc, - Pd, - Pe, - Pf, - Pi, - Po, - Ps) - and Symbol (Sc, - Sk, - Sm, - So) - category values. - -: un-initialized value -:: The value of any event attribute (such as {{Event/bubbles}} or - {{Event/currentTarget}}) before the event has been initialized with - {{Event/initEvent()}}. The un-initialized values of an event apply - immediately after a new event has been created using the method - {{Document/createEvent()}}. - -: 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 [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the - requirements for a conforming user agent. - -: Window -:: The Window is the object referred to by the current document's - browsing context's Window Proxy object as defined in - HTML5 - [[HTML5]]. - diff --git a/split/keyboard-events.html b/split/keyboard-events.html deleted file mode 100644 index a71587eb..00000000 --- a/split/keyboard-events.html +++ /dev/null @@ -1,4109 +0,0 @@ - - - - - Keyboard Events - - - - - - - - - - - - - - - - -
    -

    -

    Keyboard Events

    -

    Editor’s Draft,

    -
    - More details about this document -
    -
    -
    This version: -
    https://w3c.github.io/uievents/ -
    Latest published version: -
    https://www.w3.org/TR/uievents/ -
    Feedback: -
    GitHub -
    Editors: -
    (Google) -
    (Microsoft) -
    Former Editor: -
    Doug Schepers (Mar 2008 - May 2011) -
    Tests: -
    web-platform-tests uievents/ (ongoing work) -
    -
    -
    -
    -

    Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

    -
    -
    -
    -

    Abstract

    -

    *** Keyboard Events ***

    -

    Note: This is an experimental split of the UI Events spec into smaller, event-specific - - specs. The split was made from an out-of-date snapshot, so the information here is not - current, so please focus on the overall structure rather than the specifics of the - content. If this experiment goes well, then we will split the current spec after all - outstanding pull requests have been handled.

    -
    -

    Status of this document

    -
    -

    This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

    -

    This document was published by the Web Applications Working Group as an Editors Draft. This document is intended to become a W3C Recommendation.

    -

    -

    This document was published by the Web Applications Working Group as a Working Draft. - - Feedback and comments on this specification are welcome. Please use GitHub issues Historical discussions can be found in the public-webapps@w3.org archives.

    -

    Publication as an Editors Draft does not imply endorsement by W3C and its Members. This is a draft document and may - be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite - this document as other than work in progress.

    -

    This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

    -

    This document is governed by the 2 November 2021 W3C Process Document.

    -
    -
    - -
    -

    1. Introduction

    -

    1.1. Overview

    -

    TODO.

    -

    1.2. Conformance

    -

    Boilerplate?

    -

    2. Stylistic Conventions

    -

    This specification follows the Proposed W3C Specification Conventions, -with the following supplemental additions:

    -
      -
    • -

      The key cap printed on a key is shown as ↓, = or Q. This is used to refer to a -key from the user’s perspective without regard for the key and code values in the -generated KeyboardEvent.

      -
    • -

      Glyphs representing character are shown as: "𣧂".

      -
    • -

      Unicode character encodings are shown as: U+003d.

      -
    • -

      Names of key values generated by a key press (i.e., the value of KeyboardEvent.key) are shown as: "ArrowDown", "=", "q" or "Q".

      -
    • -

      Names of key codes associated with the physical keys (i.e., the -value of KeyboardEvent.code) are shown as: "ArrowDown", "Equal" or "KeyQ".

      -
    -

    In addition, certain terms are used in this specification with particular -meanings. The term implementation applies to a browser, content -authoring tool, or other user agent that implements this specification, -while a content author is a person who writes script or code that takes -advantage of the interfaces, methods, attributes, events, and other features -described in this specification in order to make Web applications, and a user is -the person who uses those Web applications in an implementation.

    -

    And finally:

    -

    This is a note.

    -

    This is an open issue.

    -

    This is a warning.

    -
    interface Example {
-    // This is an IDL definition.
-};
-
    -

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

    -

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

    -

    3.1.1. KeyboardEvent

    -
    [Exposed=Window]
-interface KeyboardEvent : UIEvent {
-  constructor(DOMString type, optional KeyboardEventInit eventInitDict = {});
-  // 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;
-
-  readonly attribute DOMString key;
-  readonly attribute DOMString code;
-  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 boolean 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.

    -
    -
    -

    3.1.2. KeyboardEventInit

    -
    dictionary KeyboardEventInit : EventModifierInit {
-  DOMString key = "";
-  DOMString code = "";
-  unsigned long 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.

    -

    3.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:

    - - - - - - - - -
    KeyboardEvent . key - Valid location values -
    "Shift", "Control", "Alt", "Meta" - DOM_KEY_LOCATION_LEFT, DOM_KEY_LOCATION_RIGHT -
    "ArrowDown", "ArrowLeft", "ArrowRight", "ArrowUp" - DOM_KEY_LOCATION_STANDARD, DOM_KEY_LOCATION_NUMPAD -
    "End", "Home", "PageDown", "PageUp" - DOM_KEY_LOCATION_STANDARD, DOM_KEY_LOCATION_NUMPAD -
    "0", "1", "2", "2", "4", "5", "6", "7", "8", "9", ".", "Enter", "+", "-", "*", "/" - DOM_KEY_LOCATION_STANDARD, DOM_KEY_LOCATION_NUMPAD -
    -

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

    -

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

    -

    3.4. Keyboard Event Types

    -

    3.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   (Space) 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 § 9.1.1 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.

    -

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

    -

    4. Keyboard events and key values

    -

    This section contains necessary information regarding keyboard events:

    -
      -
    • -

      Explanation of keyboard layout, mapping, and key values.

      -
    • -

      Relations between keys, such as dead keys or modifiers keys.

      -
    • -

      Relations between keyboard events and their default actions.

      -
    • -

      The set of key values, and guidelines on how to extend this set.

      -
    -

    This section uses Serbian and Kanji characters which could be misrepresented or - unavailable in the PDF version or printed version of this specification.

    -

    4.1. Keyboard Input

    -

    This section is non-normative

    -

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

    -
      -
    • -

      Mechanical layout: the dimensions, size, and placement -of the physical keys on the keyboard

      -
    • -

      Visual markings: the labels (or legends) that -mark each key

      -
    • -

      Functional mapping: the abstract key-value association -of each key.

      -
    -

    This specification only defines the functional mapping, in terms of key values and code values, - but briefly describes key legends for background.

    -

    4.1.1. Key Legends

    -

    This section is informative

    -

    The key legend is the visual marking that is printed or embossed on the key cap (the rectangular "cap" that covers the mechanical - switch for the key). These markings normally consist of one or more - characters that a keystroke on that key will produce (such as "G", "8", or "ш"), or names or symbols which indicate that key’s - function (such as an upward-pointing arrow "⇧" indicating Shift, or the string "Enter"). Keys are often - referred to by this marking (e.g., Press the "Shift" and "G" keys.). Note, however, that the visual appearance - of the key has no bearing on its digital representation, and in many - configurations may be completely inaccurate. Even the control and - function keys, such as Enter, may be mapped to different - functionality, or even mapped as character keys.

    -

    Many keyboards contain keys that do not normally produce any characters, - even though the symbol might have a Unicode equivalent. For example, the Shift key might bear the symbol "⇧", which has the - Unicode code point U+21E7, but - pressing the Shift key will not produce this character value, - and there is no Unicode code point for Shift.

    -

    4.2. Key codes

    -

    A key code is an attribute of a keyboard event that can be - used to identify the physical key associated with the keyboard event. It is - similar to USB Usage IDs in that it provides a low-level value (similar to a - scancode) that is vendor-neutral.

    -

    The primary purpose of the code attribute is to provide a - consistent and coherent way to identify keys based on their physical - location. In addition, it also provides a stable name (unaffected by the - current keyboard state) that uniquely identifies each key on the keyboard.

    -

    The list of valid code values is defined in the [UIEvents-Code].

    -

    4.2.1. Motivation for the code Attribute

    -

    The standard PC keyboard has a set of keys (which we refer to as writing system keys) that generate different key values based on the current keyboard layout - selected by the user. This situation makes it difficult to write code - that detects keys based on their physical location since the code would - need to know which layout is in effect in order to know which key values to check for. A real-world example of this - is a game that wants to use the "W", "A", "S" and "D" keys to control player movement. The code attribute solves this problem by providing a stable value to check that - is not affected by the current keyboard layout.

    -

    In addition, the values in the key attribute depend as - well on the current keyboard state. Because of this, the order in which - keys are pressed and released in relation to modifier keys can affect - the values stored in the key attribute. The code attribute solves this problem by providing a - stable value that is not affected by the current keyboard state.

    -

    4.2.2. The Relationship Between key and code

    -
    -
    key -
    The key attribute is intended for users who - are interested in the meaning of the key being pressed, taking - into account the current keyboard layout (and IME; dead keys are given a unique key value). Example use case: Detecting - modified keys or bare modifier keys (e.g., to perform an action - in response to a keyboard shortcut). -
    code -
    The code attribute is intended for users who - are interested in the key that was pressed by the user, without - any layout modifications applied. Example use case: Detecting - WASD keys (e.g., for movement controls in a game) or trapping - all keys (e.g., in a remote desktop client to send all keys to - the remote host). -
    -

    4.2.3. code Examples

    -
    - Handling the Left and Right Alt Keys - - - - - - - - -
    Keyboard Layout - KeyboardEvent
    key -     		KeyboardEvent
    code -     		Notes -
    US - "Alt" - "AltLeft" - DOM_KEY_LOCATION_LEFT -
    French - "Alt" - "AltLeft" - DOM_KEY_LOCATION_LEFT -
    US - "Alt" - "AltRight" - DOM_KEY_LOCATION_RIGHT -
    French - "AltGraph" - "AltRight" - DOM_KEY_LOCATION_RIGHT -
    -

    In this example, checking the key attribute permits - matching Alt without worrying about which Alt key (left or - right) was pressed. Checking the code attribute - permits matching the right Alt key ("AltRight") without worrying - about which layout is currently in effect.

    -

    Note that, in the French example, the Alt and AltGraph keys - retain their left and right location, even though there is only one of - each key.

    -
    -
    - Handling the Single Quote Key - - - - - - - -
    Keyboard Layout - KeyboardEvent
    key -     		KeyboardEvent
    code -     		Notes -
    US - "'" - "Quote" - -
    Japanese - ":" - "Quote" - -
    US Intl - "Dead" - "Quote" - -
    -

    This example shows how dead key values are encoded in the - attributes. The key values vary based on the - current locale, whereas the code attribute returns - a consistent value.

    -
    -
    - Handling the "2" Key (with and without Shift pressed) on - various keyboard layouts. - - - - - - - - - - -
    Keyboard Layout - KeyboardEvent
    key -     		KeyboardEvent
    code -     		Notes -
    US - "2" - "Digit2" - -
    US - "@" - "Digit2" - shiftKey -
    UK - "2" - "Digit2" - -
    UK - """ - "Digit2" - shiftKey -
    French - "é" - "Digit2" - -
    French - "2" - "Digit2" - shiftKey -
    -

    Regardless of the current locale or the modifier key state, pressing - the key labelled "2" on a US keyboard always results in "Digit2" in the code attribute.

    -
    -
    - Sequence of Keyboard Events : Shift and 2 -

    Compare the attribute values in the following two key event - sequences. They both produce the "@" character on a US - keyboard, but differ in the order in which the keys are released. In - the first sequence, the order is: Shift (down), 2 (down), 2 (up), Shift (up).

    - - - - - - - - - -
    - Event Type - KeyboardEvent
    key -     		KeyboardEvent
    code -     		Notes -
    1 - keydown - "Shift" - "ShiftLeft" - DOM_KEY_LOCATION_LEFT -
    2 - keydown - "@" - "Digit2" - shiftKey -
    3 - keypress - "@" - "Digit2" - (if supported) -
    4 - keyup - "@" - "Digit2" - shiftKey -
    5 - keyup - "Shift" - "ShiftLeft" - DOM_KEY_LOCATION_LEFT -
    -

    In the second sequence, the Shift is released before the 2, - resulting in the following event order: Shift (down), 2 (down), Shift (up), 2 (up).

    - - - - - - - - - -
    - Event Type - KeyboardEvent
    key -     		KeyboardEvent
    code -     		Notes -
    1 - keydown - "Shift" - "ShiftLeft" - DOM_KEY_LOCATION_LEFT -
    2 - keydown - "@" - "Digit2" - shiftKey -
    3 - keypress - "@" - "Digit2" - (if supported) -
    4 - keyup - "Shift" - "ShiftLeft" - DOM_KEY_LOCATION_LEFT -
    5 - keyup - "2" - "Digit2" - -
    -

    Note that the values contained in the key attribute does not match between the keydown and keyup events for - the "2" key. The code attribute provides a - consistent value that is not affected by the current modifier state.

    -
    -

    4.2.4. code and Virtual Keyboards

    -

    The usefulness of the code attribute is less obvious - for virtual keyboards (and also for remote controls and chording - keyboards). In general, if a virtual (or remote control) keyboard is - mimicking the layout and functionality of a standard keyboard, then it - MUST also set the code attribute as appropriate. For - keyboards which are not mimicking the layout of a standard keyboard, - then the code attribute MAY be set to the closest - match on a standard keyboard or it MAY be left undefined.

    -

    For virtual keyboards with keys that produce different values based on - some modifier state, the code value should be the key value generated when the button is pressed while - the device is in its factory-reset state.

    -

    4.3. Keyboard Event key Values

    -

    A key value is a DOMString that can be used to indicate any - given key on a keyboard, regardless of position or state, by the value it - produces. These key values MAY be used as return values for keyboard events - generated by the implementation, or as input values by the content author to - specify desired input (such as for keyboard shortcuts).

    -

    The list of valid key values is defined in [UIEvents-Key].

    -

    Key values can be used to detect the value of a key which has been pressed, - using the key attribute. Content authors can retrieve the character value of upper- or lower-case letters, number, symbols, or - other character-producing keys, and also the key value of control - keys, modifier keys, function keys, or other keys that do not generate - characters. These values can be used for monitoring particular input - strings, for detecting and acting on modifier key input in combination with - other inputs (such as a mouse), for creating virtual keyboards, or for any - number of other purposes.

    -

    Key values can also be used by content authors in string comparisons, as - values for markup attributes (such as the HTML accesskey) in - conforming host languages, or for other related purposes. A - conforming host language SHOULD allow content authors to use either - of the two equivalent string values for a key value: the character - value, or the key value.

    -

    While implementations will use the most relevant value for a key - independently of the platform or keyboard layout mappings, content authors - can not make assumptions on the ability of keyboard devices to generate - them. When using keyboard events and key values for shortcut-key - combinations, content authors can consider using numbers and function - keys (F4, F5, and so on) instead of letters ([DWW95]) - given that most keyboard layouts will provide keys for those.

    -

    A key value does not indicate a specific key on the physical keyboard, nor - does it reflect the character printed on the key. A key value indicates the - current value of the event with consideration to the current state of all - active keys and key input modes (including shift modes), as reflected in the - operating-system mapping of the keyboard and reported to the implementation. - In other words, the key value for the key labeled O on a QWERTY keyboard has the key value "o" in an unshifted state and "O" in a shifted state. Because a user can map their keyboard to an - arbitrary custom configuration, the content author is encouraged not to - assume that a relationship exists between the shifted and unshifted states - of a key and the majuscule form (uppercase or capital letters) and minuscule - form (lowercase or small letters) of a character representation, but is - encouraged instead to use the value of the key attribute. - For example, the Standard "102" Keyboard layout depicted in [UIEvents-Code] illustrates one possible set of key mappings on one possible keyboard - layout. Many others exist, both standard and idiosyncratic.

    -

    To simplify dead key support, when the operating-system mapping of - the keyboard is handling a dead key state, the current state of the - dead key sequence is not reported via the key attribute. - Rather, a key value of "Dead" is reported. Instead, implementations - generate composition events which - contain the intermediate state of the dead key sequence reported via the data attribute. As in the previous example, the key - value for the key marked O on a QWERTY keyboard has a data value of "ö" in an - unshifted state during a dead-key operation to add an umlaut diacritic, and "Ö" in a shifted state during a dead-key - operation to add an umlaut diacritic.

    -

    It is also important to note that there is not a one-to-one relationship - between key event states and key values. A particular key value might be - associated with multiple keys. For example, many standard keyboards contain - more than one key with the Shift key value (normally distinguished - by the location values DOM_KEY_LOCATION_LEFT and DOM_KEY_LOCATION_RIGHT) or 8 key value (normally - distinguished by the location values DOM_KEY_LOCATION_STANDARD and DOM_KEY_LOCATION_NUMPAD), and user-configured custom - keyboard layouts MAY duplicate any key value in multiple key-state scenarios - (note that location is intended for standard keyboard - layouts, and cannot always indicate a meaningful distinction).

    -

    Finally, the meaning of any given character representation is - context-dependent and complex. For example, in some contexts, the asterisk - (star) glyph ("*") represents a footnote or - emphasis (when bracketing a passage of text). However, in some documents or - executable programs it is equivalent to the mathematical multiplication - operation, while in other documents or executable programs, that function is - reserved for the multiplication symbol ("×", Unicode value U+00D7) or the Latin small letter "x" (due to the lack of a multiplication key on many keyboards and the - superficial resemblance of the glyphs "×" and "x"). Thus, - the semantic meaning or function of character representations is outside the - scope of this specification.

    -

    4.3.1. Modifier keys

    -

    Keyboard input uses modifier keys to change the normal behavior of a - key. Like other keys, modifier keys generate keydown and keyup events, as shown in the example below. Some modifiers are - activated while the key is being pressed down or maintained pressed such - as Alt, Control, Shift, AltGraph, or Meta. Other modifiers are activated depending on their state - such as CapsLock, NumLock, or ScrollLock. Change - in the state happens when the modifier key is being pressed down. The KeyboardEvent interface provides convenient attributes for some - common modifiers keys: ctrlKey, shiftKey, altKey, metaKey. Some operating systems simulate the AltGraph modifier key with the combination of the Alt and Control modifier keys. Implementations are encouraged to use - the AltGraph modifier key.

    -
    - This example describes a possible sequence of events - associated with the generation of the Unicode character Q (Latin - Capital Letter Q, Unicode code point U+0051) on a US - keyboard using a US mapping: - - - - - - - - - - -
    - Event Type - KeyboardEvent
    key -     		Modifiers - Notes -
    1 - keydown - "Shift" - shiftKey - -
    2 - keydown - "Q" - shiftKey - Latin Capital Letter Q -
    3 - beforeinput - - - -
    4 - input - - - -
    5 - keyup - "Q" - shiftKey - -
    6 - keyup - "Shift" - - -
    -
    -
    - Th example describes an alternate sequence of keys to the - example above, where the Shift key is released before the Q key. The key value for the Q key will revert to its - unshifted value for the keyup event: - - - - - - - - - - -
    - Event Type - KeyboardEvent
    key -     		Modifiers - Notes -
    1 - keydown - "Shift" - shiftKey - -
    2 - keydown - "Q" - shiftKey - Latin Capital Letter Q -
    3 - beforeinput - - - -
    4 - input - - - -
    5 - keyup - "Shift" - - -
    6 - keyup - "q" - - Latin Small Letter Q -
    -
    -
    - The following example describes a possible sequence of keys that - does not generate a Unicode character (using the same configuration - as the previous example): - - - - - - - - - -
    - Event Type - KeyboardEvent
    key -     		Modifiers - Notes -
    1 - keydown - "Control" - ctrlKey - -
    2 - keydown - "v" - ctrlKey - Latin Small Letter V -
    - - - - No beforeinput or input events are generated. -
    3 - keyup - "v" - ctrlKey - Latin Small Letter V -
    4 - keyup - "Control" - - -
    -
    -
    - The following example shows the sequence of events when both Shift and Control are pressed: - - - - - - - - - - - -
    - Event Type - KeyboardEvent
    key -     		Modifiers - Notes -
    1 - keydown - "Control" - ctrlKey - -
    2 - keydown - "Shift" - ctrlKey, shiftKey - -
    3 - keydown - "V" - ctrlKey, shiftKey - Latin Capital Letter V -
    - - - - No beforeinput or input events are generated. -
    4 - keyup - "V" - ctrlKey, shiftKey - Latin Capital Letter V -
    5 - keyup - "Shift" - ctrlKey - -
    6 - keyup - "Control" - - -
    -
    -
    - For non-US keyboard layouts, the sequence of events is the same, but - the value of the key is based on the current keyboard layout. This - example shows a sequence of events when an Arabic keyboard layout is - used: - - - - - - - - - -
    - Event Type - KeyboardEvent
    key -     		Modifiers - Notes -
    1 - keydown - "Control" - ctrlKey - -
    2 - keydown - "ر" - ctrlKey - Arabic Letter Reh -
    - - - - No beforeinput or input events are generated. -
    3 - keyup - "ر" - ctrlKey - Arabic Letter Reh -
    4 - keyup - "Control" - - -
    -
    -

    The value in the keydown and keyup events varies based on - the current keyboard layout in effect when the key is pressed. This - means that the v key on a US layout and the ر key on an - Arabic layout will generate different events even though they are the - same physical key. To identify these events as coming from the same - physical key, you will need to make use of the code attribute.

    -

    In some cases, modifier keys change the key value for a key event. For example, on some MacOS keyboards, the key - labeled "delete" functions the same as the Backspace key on the - Windows OS when unmodified, but when modified by the Fn key, - acts as the Delete key, and the value of key will match the most appropriate function of the key in its current - modified state.

    -

    4.3.2. Dead keys

    -

    Some keyboard input uses dead keys for the input of composed - character sequences. Unlike the handwriting sequence, in which users - enter the base character first, keyboard input requires to enter a - special state when a dead key is pressed and emit the - character(s) only when one of a limited number of legal base - character is entered.

    -

    The MacOS and Linux operating systems use input methods to process dead keys.

    -

    The dead keys (across all keyboard layouts and mappings) are - represented by the key value Dead. In response to any dead key - press, composition events must - be dispatched by the user agent and the compositionupdate event’s data value must be the character value of the - current state of the dead key combining sequence.

    -

    While Unicode combining characters always follow the handwriting - sequence, with the combining character trailing the corresponding - letter, typical dead key input MAY reverse the sequence, with the - combining character before the corresponding letter. For example, the - word naïve, using the combining diacritic ¨, would be - represented sequentially in Unicode as nai¨ve, but MAY be typed na¨ive. The sequence of keystrokes U+0302 (Combining - Circumflex Accent key) and U+0065 (key marked with the Latin Small - Letter E) will likely produce (on a French keyboard using a french - mapping and without any modifier activated) the Unicode character "ê" (Latin Small Letter E With Circumflex), as preferred by - the Unicode Normalization Form NFC.

    -
    - - - - - - - - - - - - - -
    - Event Type - KeyboardEvent
    key -     		KeyboardEvent
    isComposing -     		CompositionEvent
    data -     		Notes -
    1 - keydown - "Dead" - false - - Combining Circumflex Accent (Dead Key) -
    2 - compositionstart - - - "" - -
    3 - compositionupdate - - - U+0302 - -
    4 - keyup - "Dead" - true - - -
    5 - keydown - "ê" - true - - -
    6 - compositionupdate - - - "ê" - -
    7 - compositionend - - - "ê" - -
    8 - keyup - "e" - false - - Latin Small Letter E -
    -
    -

    In the second keydown event (step 5), the key value (assuming the - event is not suppressed) will not be "e" (Latin Small - Letter E key) under normal circumstances because the value delivered to - the user agent will already be modified by the dead key operation.

    -

    This process might be aborted when a user types an unsupported base - character (that is, a base character for which the active - diacritical mark is not available) after pressing a dead key:

    -
    - - - - - - - - - - - - - -
    - Event Type - KeyboardEvent
    key -     		KeyboardEvent
    isComposing -     		CompositionEvent
    data -     		Notes -
    1 - keydown - "Dead" - false - - Combining Circumflex Accent (Dead Key) -
    2 - compositionstart - - - "" - -
    3 - compositionupdate - - - U+0302 - -
    4 - keyup - "Dead" - true - - -
    5 - keydown - "q" - true - - Latin Small Letter Q -
    6 - compositionupdate - - - "" - -
    7 - compositionend - - - "" - -
    8 - keyup - "q" - false - - -
    -
    -

    4.3.3. Input Method Editors

    -

    This specification includes a model for input method editors (IMEs), through the CompositionEvent interface and events. - However, Composition Events and Keyboard Events do not necessarily map - as a one-to-one relationship. As an example, receiving a keydown for the Accept key value does not necessarily imply that the - text currently selected in the IME is being accepted, but - indicates only that a keystroke happened, disconnected from the IME Accept functionality (which would normally result in a compositionend event in most IME systems). Keyboard - events cannot be used to determine the current state of the input method - editor, which can be obtained through the data attribute of the CompositionEvent interface. Additionally, IME systems and devices vary in their functionality, and in which - keys are used for activating that functionality, such that the Convert and Accept keys MAY be represented by other - available keys. Keyboard events correspond to the events generated by - the input device after the keyboard layout mapping.

    -

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

    -

    The following example describes a possible sequence of keys to generate - the Unicode character "市" (Kanji character, part of CJK - Unified Ideographs) using Japanese input methods. This example assumes - that the input method editor is activated and in the Japanese-Romaji - input mode. The keys Convert and Accept MAY be replaced - by others depending on the input device in use and the configuration of - the IME, e.g., it can be respectively U+0020 (Space key) and Enter.

    -

    "詩" (poem) and "市" (city) are - homophones, both pronounced し (shi/si), so the user - needs to use the Convert key to select the proper option.

    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Event Type - KeyboardEvent
    key -     		KeyboardEvent
    isComposing -     		CompositionEvent
    data -     		Notes -
    1 - keydown - "s" - false - - Latin Small Letter S -
    2 - compositionstart - - - "" - -
    3 - beforeinput - - - - -
    4 - compositionupdate - - - "s" - -
    - - - - - DOM is updated -
    5 - input - - - - -
    6 - keyup - "s" - true - - -
    7 - keydown - "i" - true - - Latin Small Letter I -
    8 - beforeinput - - - - -
    9 - compositionupdate - - - "し" - shi -
    - - - - - DOM is updated -
    10 - input - - - - -
    11 - keyup - "i" - true - - -
    12 - keydown - "Convert" - true - - Convert -
    13 - beforeinput - - - - -
    14 - compositionupdate - - - "詩" - "poem" -
    - - - - - DOM is updated -
    15 - input - - - - -
    16 - keyup - "Convert" - true - - -
    17 - keydown - "Convert" - true - - Convert -
    18 - beforeinput - - - - -
    19 - compositionupdate - - - "市" - "city" -
    - - - - - DOM is updated -
    20 - input - - - - -
    21 - keyup - "Convert" - true - - -
    22 - keydown - "Accept" - true - - Accept -
    23 - compositionend - - - "市" - -
    24 - keyup - "Accept" - false - - -
    -
    -

    IME composition can also be canceled as in the following example, with - conditions identical to the previous example. The key Cancel might also be replaced by others depending on the input device in use - and the configuration of the IME, e.g., it could be U+001B (Escape - key).

    -
    - - - - - - - - - - - - - - - - - - - - - - -
    - Event Type - KeyboardEvent
    key -     		KeyboardEvent
    isComposing -     		CompositionEvent
    data -     		Notes -
    1 - keydown - "s" - false - - Latin Small Letter S -
    2 - compositionstart - - - "" - -
    3 - compositionupdate - - - "s" - -
    4 - keyup - "s" - true - - -
    5 - keydown - "i" - true - - Latin Small Letter I -
    6 - compositionupdate - - - "し" - shi -
    7 - keyup - "i" - true - - -
    8 - keydown - "Convert" - true - - Convert -
    9 - compositionupdate - - - "詩" - "poem" -
    10 - keyup - "Convert" - true - - -
    11 - keydown - "Convert" - true - - Convert -
    12 - compositionupdate - - - "市" - "city" -
    13 - keyup - "Convert" - true - - -
    14 - keydown - "Cancel" - true - - Cancel -
    15 - compositionupdate - - - "" - -
    16 - compositionend - - - "" - -
    17 - keyup - "Cancel" - false - - -
    -
    -

    Some input method editors (such as on the MacOS operating system) - might set an empty string to the composition data attribute - before canceling a composition.

    -
    4.3.3.1. Input Method Editor mode keys
    -

    Some keys on certain devices are intended to activate input - method editor functionality, or to change the mode of an active input method editor. Custom keys for this purpose can be - defined for different devices or language modes. The keys defined in - this specification for this purpose are: "Alphanumeric", "CodeInput", "FinalMode", "HangulMode", "HanjaMode", "Hiragana", "JunjaMode", "KanaMode", "KanjiMode", "Katakana", and "Romaji". When one of these keys is - pressed, and no IME is currently active, the appropriate IME is expected to be activated in the mode indicated by the - key (if available). If an IME is already active when the key - is pressed, the active IME might change to the indicated - mode, or a different IME might be launched, or the might MAY - be ignored, on a device- and application-specific basis.

    -

    This specification also defines other keys which are intended for - operation specifically with input method editors: "Accept", "AllCandidates", "Cancel", "Convert", "Compose", "Zenkaku" (FullWidth), "Hankaku" (HalfWidth), "NextCandidate", "NonConvert", and "PreviousCandidate". The functions of these - keys are not defined in this specification — refer to other - resources for details on input method editor functionality.

    -

    Keys with input method editor functions are not restricted to - that purpose, and can have other device- or implementation-specific - purposes.

    -

    4.3.4. Default actions and cancelable keyboard events

    -

    Canceling the default action of a keydown event MUST NOT - affect its respective keyup event, but it MUST prevent the - respective beforeinput and input (and keypress if - supported) events from being generated. The following example describes - a possible sequence of keys to generate the Unicode character Q (Latin - Capital Letter Q) on a US keyboard using a US mapping:

    -
    - - - - - - - - - - -
    - Event Type - KeyboardEvent
    key -     		InputEvent
    data -     		Modifiers - Notes -
    1 - keydown - "Shift" - - shiftKey - -
    2 - keydown - "Q" - - shiftKey - The default action is prevented, e.g., by invoking preventDefault(). -
    - - - - - No beforeinput or input (or keypress, if supported) events are generated -
    3 - keyup - "Q" - - shiftKey - -
    4 - keyup - "Shift" - - - -
    -
    -

    If the key is a modifier key, the keystroke MUST still be taken into - account for the modifiers states. The following example describes a - possible sequence of keys to generate the Unicode character Q (Latin - Capital Letter Q) on a US keyboard using a US mapping:

    -
    - - - - - - - - - - - -
    - Event Type - KeyboardEvent
    key -     		InputEvent
    data -     		Modifiers - Notes -
    1 - keydown - "Shift" - - shiftKey - The default action is prevented, e.g., by invoking preventDefault(). -
    2 - keydown - "Q" - - shiftKey - -
    3 - beforeinput - - "Q" - - -
    4 - input - - - - -
    5 - keyup - "Q" - - shiftKey - -
    6 - keyup - "Shift" - - - -
    -
    -

    If the key is part of a sequence of several keystrokes, whether it is a dead key or it is contributing to an Input Method Editor - sequence, the keystroke MUST be ignored (not taken into account) only if - the default action is canceled on the keydown event. - Canceling a dead key on a keyup event has no effect on beforeinput or input events. The following example uses - the dead key "Dead" (U+0302 Combining Circumflex Accent key) and "e" (U+0065, Latin Small Letter E key) on a French - keyboard using a French mapping and without any modifier activated:

    -
    - - - - - - - - - - - -
    - Event Type - KeyboardEvent
    key -     		InputEvent
    data -     		Notes -
    1 - keydown - "Dead" - - The default action is prevented, e.g., by invoking preventDefault(). -
    2 - keyup - "Dead" - - -
    3 - keydown - "e" - - -
    4 - beforeinput - - "e" - -
    5 - input - - - -
    6 - keyup - "e" - - -
    -
    -

    5. Constructing Mouse and Keyboard Events

    -

    Generally, when a constructor of an Event interface, or of an interface - inherited from the Event interface, is invoked, the steps described in [DOM] should be followed. However the KeyboardEvent and MouseEvent interfaces provide additional dictionary members for - initializing the internal state of the Event object’s key modifiers: - specifically, the internal state queried for using the getModifierState() and getModifierState() methods. This section supplements the DOM4 steps for intializing a new Event object with these optional modifier states.

    -

    For the purposes of constructing a KeyboardEvent, MouseEvent, or - object derived from these objects using the algorithm below, all KeyboardEvent, MouseEvent, and derived objects have internal key modifier state which can be set and - retrieved using the key modifier names described in the Modifier Keys table in [UIEvents-Key].

    -

    The following steps supplement the algorithm defined for constructing - events in DOM4:

    - -

    6. Legacy Event Initializers

    -

    This section is normative.

    -

    The following features are obsolete and should only be implemented by user agents that require compatibility with legacy software.

    -

    Early versions of this specification included an initialization method on - the interface (for example initMouseEvent) that required a long - list of parameters that, in most cases, did not fully initialize all - attributes of the event object. Because of this, event interfaces which were - derived from the basic Event interface required that the initializer of each of the derived interfaces be called explicitly in order to - fully initialize an event.

    -
    Initializing all the attributes of a UIEvent requires calls to two - initializer methods: initEvent and initUIEvent.
    -

    Due in part to the length of time in the development of this standard, some - implementations MAY have taken a dependency on these (now deprecated) - initializer methods. For completeness, these legacy event initializers are - described in this section.

    -

    6.1. Initializers for interface KeyboardEvent

    -

    This section is informative

    -

    The argument list to this legacy KeyboardEvent initializer does not - include the detailArg (present in other initializers) and - adds the locale argument (see § 9.3.1 Changes between different drafts of UI Events); it is - necessary to preserve this inconsistency for compatibility with existing - implementations.

    -
    partial interface KeyboardEvent {
-  // Originally introduced (and deprecated) in this specification
-  undefined initKeyboardEvent(DOMString typeArg,
-    optional boolean bubblesArg = false,
-    optional boolean cancelableArg = false,
-    optional Window? viewArg = null,
-    optional DOMString keyArg = "",
-    optional unsigned long locationArg = 0,
-    optional boolean ctrlKey = false,
-    optional boolean altKey = false,
-    optional boolean shiftKey = false,
-    optional boolean metaKey = false);
-};
-
    -
    -
    initKeyboardEvent(typeArg) -
    - Initializes attributes of a KeyboardEvent object. This - method has the same behavior as UIEvent.initUIEvent(). - The value of detail remains undefined. -

    The initKeyboardEvent method is deprecated.

    -
    -
    DOMString typeArg -
    Refer to the initEvent() method for a description of this parameter. -
    boolean bubblesArg -
    Refer to the initEvent() method for a description of this parameter. -
    boolean cancelableArg -
    Refer to the initEvent() method for a description of this parameter. -
    Window? viewArg -
    Specifies view. This value MAY be null. -
    DOMString keyArg -
    Specifies key. -
    unsigned long locationArg -
    Specifies location. -
    boolean ctrlKey -
    Specifies whether the Control key modifier is active. -
    boolean altKey -
    Specifies whether the Alt key modifier is active. -
    boolean shiftKey -
    Specifies whether the Shift key modifier is active. -
    boolean metaKey -
    Specifies whether the Meta key modifier is active. -
    -
    -

    7. Legacy Key & Mouse Event Attributes

    -

    This section is non-normative. The following attributes are obsolete and should - only be implemented by user agents that require compatibility with legacy - software that requires these keyboard events.

    -

    These features were never formally specified and the current browser - implementations vary in significant ways.

    -

    7.1. Legacy KeyboardEvent supplemental interface

    -

    This section is non-normative

    -

    Browser support for keyboards has traditionally relied on three ad-hoc - attributes, keyCode, charCode, and UIEvent's which.

    -

    All three of these attributes return a numerical code that represents some - aspect of the key pressed: keyCode is an index of the key - itself. charCode is the ASCII value of the character keys. which is the character value where available and otherwise - the key index. The values for these attributes, and the availability of the - attribute, is inconsistent across platforms, keyboard languages and layouts, user agents, versions, and even event types.

    -

    7.1.1. Interface KeyboardEvent (supplemental)

    -

    The partial KeyboardEvent interface is an informative extension of - the KeyboardEvent interface, which adds the charCode and keyCode attributes.

    -

    The partial KeyboardEvent interface can be obtained by using the createEvent() method call in - implementations that support this extension.

    -
    partial interface KeyboardEvent {
-  // The following support legacy user agents
-  readonly attribute unsigned long charCode;
-  readonly attribute unsigned long keyCode;
-};
-
    -
    -
    charCode, of type unsigned long, readonly -
    charCode holds a character value, for keypress events which generate character input. The value - is the Unicode reference number (code point) of that character - (e.g. event.charCode = event.key.charCodeAt(0) for - printable characters). For keydown or keyup events, the value of charCode is 0. -
    keyCode, of type unsigned long, readonly -
    - keyCode holds a system- and - implementation-dependent numerical code signifying the - unmodified identifier associated with the key pressed. Unlike - the key attribute, the set of possible values - are not normatively defined in this specification. Typically, - these value of the keyCode SHOULD represent - the decimal codepoint in ASCII [RFC20][US-ASCII] or Windows - 1252 [WIN1252], but MAY be drawn from a different appropriate - character set. Implementations that are unable to identify a key - use the key value 0. -

    See § 7.2 Legacy key models for more details on how to determine - the values for keyCode.

    -
    -

    7.1.2. Interface KeyboardEventInit (supplemental)

    -

    Browsers that include support for keyCode and charCode in KeyboardEvent should also add the following members to the KeyboardEventInit dictionary.

    -

    The partial KeyboardEventInit dictionary is an informative extension - of the KeyboardEventInit dictionary, which adds charCode and keyCode members to initialize the corresponding KeyboardEvent attributes.

    -
    partial dictionary KeyboardEventInit {
-  // The following support legacy user agents
-  unsigned long charCode = 0;
-  unsigned long keyCode = 0;
-};
-
    -
    -
    charCode, of type unsigned long, defaulting to 0 -
    Initializes the charCode attribute of the KeyboardEvent to the Unicode code point for the event’s - character. -
    keyCode, of type unsigned long, defaulting to 0 -
    Initializes the keyCode attribute of the KeyboardEvent to the system- and implementation-dependent - numerical code signifying the unmodified identifier associated - with the key pressed. -
    -

    7.2. Legacy key models

    -

    This section is non-normative

    -

    Implementations differ on which values are exposed on these attributes for - different event types. An implementation MAY choose to expose both virtual - key codes and character codes in the keyCode property - (conflated model), or report separate keyCode and charCode properties (split model).

    -

    7.2.1. How to determine keyCode for keydown and keyup events

    -

    The keyCode for keydown or keyup events - is calculated as follows:

    -
      -
    • -

      Read the virtual key code from the operating system’s event -information, if such information is available.

      -
    • -

      If an Input Method Editor is processing key input and the event is keydown, return 229.

      -
    • -

      If input key when pressed without modifiers would insert a numerical -character (0-9), return the ASCII code of that numerical character.

      -
    • -

      If input key when pressed without modifiers would insert a lower -case character in the a-z alphabetical range, return the ASCII code -of the upper case equivalent.

      -
    • -

      If the implementation supports a key code conversion table for the -operating system and platform, look up the value. If the conversion -table specifies an alternate virtual key value for the given input, -return the specified value.

      -
    • -

      If the key’s function, as determined in an implementation-specific -way, corresponds to one of the keys in the § 7.2.3 Fixed virtual key codes table, return the corresponding key -code.

      -
    • -

      Return the virtual key code from the operating system.

      -
    • -

      If no key code was found, return 0.

      -
    -

    7.2.2. How to determine keyCode for keypress events

    -

    The keyCode for keypress events is calculated - as follows:

    -
      -
    • -

      If the implementation supports a conflated model, set keyCode to the Unicode code point of the character -being entered.

      -
    • -

      If the implementation supports a split model, set keyCode to 0.

      -
    -

    7.2.3. Fixed virtual key codes

    -

    The virtual key codes for the following keys do not usually change with - keyboard layouts on desktop systems:

    - - - - - - - - - - - - - - - - - - - - - - -
    Key - Virtual Key
    Code -     		Notes -
    Backspace - 8 - -
    Tab - 9 - -
    Enter - 13 - -
    Shift - 16 - -
    Control - 17 - -
    Alt - 18 - -
    CapsLock - 20 - -
    Escape - 27 - Esc -
    Space - 32 - -
    PageUp - 33 - -
    PageDown - 34 - -
    End - 35 - -
    Home - 36 - -
    ArrowLeft - 37 - -
    ArrowUp - 38 - -
    ArrowRight - 39 - -
    ArrowDown - 40 - -
    Delete - 46 - Del -
    -

    7.2.4. Optionally fixed virtual key codes

    -

    The following punctuation characters MAY change virtual codes between - keyboard layouts, but reporting these values will likely be more - compatible with legacy content expecting US-English keyboard layout:

    - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Key - Character - Virtual Key
    Code -
    Semicolon - ";" - 186 -
    Colon - ":" - 186 -
    Equals sign - "=" - 187 -
    Plus - "+" - 187 -
    Comma - "," - 188 -
    Less than sign - "<" - 188 -
    Minus - "-" - 189 -
    Underscore - "_" - 189 -
    Period - "." - 190 -
    Greater than sign - ">" - 190 -
    Forward slash - "/" - 191 -
    Question mark - "?" - 191 -
    Backtick - "`" - 192 -
    Tilde - "~" - 192 -
    Opening squace bracket - "[" - 219 -
    Opening curly brace - "{" - 219 -
    Backslash - "\" - 220 -
    Pipe - "|" - 220 -
    Closing square bracket - "]" - 221 -
    Closing curly brace - "}" - 221 -
    Single quote - "'" - 222 -
    Double quote - """ - 222 -
    -

    8. Legacy Event Types

    -

    This section is normative. The following event types are obsolete and should - only be implemented by user agents that require compatibility with legacy - software.

    -

    8.1. Legacy KeyboardEvent events

    -

    The keypress event is the traditional method for capturing key events - and processing them before the DOM is updated with the effects of the key - press. Code that makes use of the keypress event typically relies on - the legacy charCode, keyCode, and which attributes.

    -

    Note that the keypress event is specific to key events, and has been - replaced by the more general event sequence of beforeinput and input events. These new input events are not specific to - keyboard actions and can be used to capture user input regardless of the - original source.

    -

    8.1.1. Legacy KeyboardEvent event types

    -
    8.1.1.1. keypress
    - - - - - - - - - - - -
    Type - keypress -
    Interface - KeyboardEvent -
    Sync / Async - Sync -
    Bubbles - Yes -
    Trusted Targets - Element -
    Cancelable - Yes -
    Composed - Yes -
    Default action - Varies: - launch text composition system; blur and focus events; DOMActivate event; - other event -
    Context
    (trusted events) -     		- -
    -

    If supported by a user agent, this event MUST be dispatched - when a key is pressed down, if and only if that key normally - produces a character value. The keypress 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. It - MUST NOT be fired when using an input method editor.

    -

    If this event is canceled, it should prevent the input event - from firing, in addition to canceling the default action.

    -

    Authors SHOULD use the beforeinput event instead of the keypress event.

    -

    The keypress event is traditionally associated with detecting - a character value rather than a physical key, and might not - be available on all keys in some configurations.

    -

    The keypress event type is defined in this specification for - reference and completeness, but this specification deprecates the use of this event type. When in editing contexts, authors can - subscribe to the beforeinput event instead.

    -

    8.1.2. keypress event order

    -

    The keypress event type MUST be dispatched after the keydown event and before the keyup event associated with - the same key.

    -

    The keypress event type MUST be dispatched after the beforeinput event and before the input event associated - with the same key.

    -

    The sequence of key events for user-agents the support the keypress event is demonstrated in the following example:

    -
    - - - - - - - - - - - -
    - Event Type - KeyboardEvent
    key -     		InputEvent
    data -     		Notes -
    1 - keydown - "a" - - -
    2 - beforeinput - - "a" - -
    3 - keypress - "a" - - -
    - - - - Any default actions related to this key, such as inserting a character in to the DOM. -
    4 - input - - - -
    5 - keyup - "a" - - -
    -
    -

    9. Other UIEvents [DELETE]

    -

    This section will be deleted.

    -

    Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references.

    -

    beforeinput blur click compositionend compositionstart compositionupdate DOMActivate input

    -

    9.1. Things defined in other sections

    -

    9.1.1. Activation triggers and behavior

    -

    9.1.2. Default actions and cancelable events

    -

    9.1.3. Event dispatch and DOM event flow

    -

    9.1.4. Focus Events

    -

    9.1.5. Web browsers and other dynamic or interactive user agents

    -

    9.1.6. Authoring tools

    -

    9.2. Things defined in CompositionEvents

    -

    9.2.1. Composition Events

    -

    9.3. Things defined in Changes

    -

    9.3.1. Changes between different drafts of UI Events

    -

    10. Glossary [DELETE]

    -

    This section will be deleted.

    -

    Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline.

    -
    -
    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 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 § 9.1.1 Activation triggers and behavior for more details.

    -
    activation trigger -
    -

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

    -
    body element -
    -

    In HTML or XHTML documents, the body element represents the contents of the -document. In a well-formed HTML document, the body element is a first -descendant of the root element.

    -
    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, each -belonging to the set of valid Unicode character categories. -In this specification, character values are denoted as a unicode string -(e.g., U+0020) or a glyph representation of the same code point (e.g., " "), and are color coded to help distinguish these two representations.

    -

    In source code, some key values, such as non-graphic characters, can 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 preventDefault() method. For more details, see § 9.1.2 Default actions and cancelable events.

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

    -
    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 event -target. Each event is an instantiation of one specific event -type.

    -
    event target -
    -

    The object to which an event is targeted using the § 9.1.3 Event dispatch and DOM event flow. -The event target is the value of the target attribute.

    -
    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 UI Events, and they integrate and extend the objects -and models defined in this specification.

    -
    IME -
    input method editor -
    -

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

    -
    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, et al.) and dead key states.

    -
    key value -
    -

    A key value is a character value or multi-character string (such as "Enter", "Tab", or "MediaTrackNext") 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.

    -
    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). See § 4.3.1 Modifier keys for more information about modifier keys and -refer to the Modifier Keys table in [UIEvents-Key] for a list -of valid modifier keys.

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

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

    -
    Unicode character categories -
    -

    A subset of the General Category values that are defined for each Unicode -code point. This subset contains all the -Letter (Ll, Lm, Lo, Lt, Lu), -Number (Nd, Nl, No), -Punctuation (Pc, Pd, Pe, Pf, Pi, Po, Ps) -and Symbol (Sc, Sk, Sm, So) -category values.

    -
    un-initialized value -
    -

    The value of any event attribute (such as bubbles or currentTarget) before the event has been initialized with initEvent(). The un-initialized values of an event apply -immediately after a new event has been created using the method createEvent().

    -
    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 § 9.1.5 Web browsers and other dynamic or interactive user agents and § 9.1.6 Authoring tools for details on the -requirements for a conforming user agent.

    -
    Window -
    -

    The Window is the object referred to by the current document’s -browsing context’s Window Proxy object as defined in HTML5 [HTML5].

    -
    -
    -
    -

    Conformance

    -

    Document conventions

    -

    Conformance requirements are expressed - with a combination of descriptive assertions - and RFC 2119 terminology. - The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” - in the normative parts of this document - are to be interpreted as described in RFC 2119. - However, for readability, - these words do not appear in all uppercase letters in this specification.

    -

    All of the text of this specification is normative - except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

    -

    Examples in this specification are introduced with the words “for example” - or are set apart from the normative text - with class="example", - like this:

    -
    - -

    This is an example of an informative example.

    -
    -

    Informative notes begin with the word “Note” - and are set apart from the normative text - with class="note", - like this:

    -

    Note, this is an informative note.

    -
    -

    Conformant Algorithms

    -

    Requirements phrased in the imperative as part of algorithms - (such as "strip any leading space characters" - or "return false and abort these steps") - are to be interpreted with the meaning of the key word - ("must", "should", "may", etc) - used in introducing the algorithm.

    -

    Conformance requirements phrased as algorithms or specific steps - can be implemented in any manner, - so long as the end result is equivalent. - In particular, the algorithms defined in this specification - are intended to be easy to understand - and are not intended to be performant. - Implementers are encouraged to optimize.

    -
    -
    - -

    Index

    -

    Terms defined by this specification

    - -

    Terms defined by reference

    -
      -
    • - [CSS-DISPLAY-4] defines the following terms: -
        -
      • root element -
      -
    • - [CSS21] defines the following terms: -
        -
      • focus -
      -
    • - [DOM] defines the following terms: -
        -
      • Event -
      • bubbles -
      • createEvent(interface) -
      • currentTarget -
      • document -
      • initEvent(type) -
      • preventDefault() -
      • target -
      -
    • - [HTML] defines the following terms: -
        -
      • Window -
      -
    • - [UIEVENTS] defines the following terms: -
        -
      • CompositionEvent -
      • EventModifierInit -
      • InputEvent -
      • MouseEvent -
      • UIEvent -
      • data (for CompositionEvent) -
      • data (for InputEvent) -
      • detail -
      • getModifierState(keyArg) -
      • view -
      • which -
      -
    • - [UIEvents-Key] defines the following terms: -
        -
      • key attribute value -
      • modifier keys table -
      -
    • - [WEBDRIVER-BIDI] defines the following terms: -
        -
      • event type -
      -
    • - [WEBIDL] defines the following terms: -
        -
      • DOMString -
      • Exposed -
      • boolean -
      • undefined -
      • unsigned long -
      -
    -

    References

    -

    Normative References

    -
    -
    [CSS-DISPLAY-4] -
    CSS Display Module Level 4 URL: https://drafts.csswg.org/css-display-4/ -
    [CSS21] -
    Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. URL: https://drafts.csswg.org/css2/ -
    [DOM] -
    Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/ -
    [HTML] -
    Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/ -
    [RFC2119] -
    S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119 -
    [UIEVENTS] -
    Gary Kacmarcik; Travis Leithead. UI Events. URL: https://w3c.github.io/uievents/ -
    [UIEvents-Code] -
    Gary Kacmarcik; Travis Leithead. UI Events KeyboardEvent code Values. URL: https://w3c.github.io/uievents-code/ -
    [UIEvents-Key] -
    Gary Kacmarcik; Travis Leithead. UI Events KeyboardEvent key Values. URL: https://w3c.github.io/uievents-key/ -
    [WEBDRIVER-BIDI] -
    WebDriver BiDi URL: https://w3c.github.io/webdriver-bidi/ -
    [WEBIDL] -
    Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/ -
    -

    Informative References

    -
    -
    [DWW95] -
    N. Kano. Developing International Software for Windows 95 and Windows NT: A Handbook for International Software Design. 1995. -
    [HTML5] -
    Ian Hickson; et al. HTML5. URL: https://www.w3.org/html/wg/drafts/html/master/ -
    [RFC20] -
    V.G. Cerf. ASCII format for network interchange. October 1969. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc20 -
    [US-ASCII] -
    Coded Character Set - 7-Bit American Standard Code for Information Interchange. 1986. -
    [WIN1252] -
    Windows 1252 a Coded Character Set - 8-Bit. URL: https://www.microsoft.com/globaldev/reference/sbcs/1252.htm -
    -

    IDL Index

    -
    [Exposed=Window]
-interface KeyboardEvent : UIEvent {
-  constructor(DOMString type, optional KeyboardEventInit eventInitDict = {});
-  // 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;
-
-  readonly attribute DOMString key;
-  readonly attribute DOMString code;
-  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 boolean isComposing;
-
-  boolean getModifierState(DOMString keyArg);
-};
-
-dictionary KeyboardEventInit : EventModifierInit {
-  DOMString key = "";
-  DOMString code = "";
-  unsigned long location = 0;
-  boolean repeat = false;
-  boolean isComposing = false;
-};
-
-partial interface KeyboardEvent {
-  // Originally introduced (and deprecated) in this specification
-  undefined initKeyboardEvent(DOMString typeArg,
-    optional boolean bubblesArg = false,
-    optional boolean cancelableArg = false,
-    optional Window? viewArg = null,
-    optional DOMString keyArg = "",
-    optional unsigned long locationArg = 0,
-    optional boolean ctrlKey = false,
-    optional boolean altKey = false,
-    optional boolean shiftKey = false,
-    optional boolean metaKey = false);
-};
-
-partial interface KeyboardEvent {
-  // The following support legacy user agents
-  readonly attribute unsigned long charCode;
-  readonly attribute unsigned long keyCode;
-};
-
-partial dictionary KeyboardEventInit {
-  // The following support legacy user agents
-  unsigned long charCode = 0;
-  unsigned long keyCode = 0;
-};
-
-
    - - - diff --git a/split/keyboard-events.txt b/split/keyboard-events.txt deleted file mode 100644 index 09477e11..00000000 --- a/split/keyboard-events.txt +++ /dev/null @@ -1,2427 +0,0 @@ -

    Keyboard Events

    - -
    -Shortname: keyboard-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
-	*** Keyboard Events ***
-	
-	Note: This is an experimental split of the UI Events spec into smaller, event-specific
-	specs. The split was made from an out-of-date snapshot, so the information here is not
-	current, so please focus on the overall structure rather than the specifics of the
-	content. If this experiment goes well, then we will split the current spec after all
-	outstanding pull requests have been handled.
-
    - -
    -urlPrefix: https://www.w3.org/TR/WebIDL/#idl-; type: type;
-	text: long
-urlPrefix: https://w3c.github.io/selection-api/#widl-Window-getSelection-Selection; type: dfn; for: Document
-	text: getSelection()
-url: https://www.w3.org/TR/2004/REC-xml-20040204/#NT-S; type: dfn;
-	text: white space
-url: https://www.w3.org/TR/uievents-key/#key-attribute-value; type: dfn; spec: uievents-key;
-	text: key attribute value
-url: https://www.w3.org/TR/uievents-key/#keys-modifier; type: dfn; spec: uievents-key;
-	text: modifier keys table
-url: https://html.spec.whatwg.org/multipage/forms.html#context-menus; type: dfn;
-	text: contextmenu
-url: https://www.w3.org/TR/pointerevents3/#pointerevent-interface; type: interface; spec: pointerevents3
-	text: PointerEvent
-url: https://dom.spec.whatwg.org/#concept-tree-ancestor; type: dfn;
-	text: ancestor
-url: https://www.w3.org/TR/CSS21/visuren.html#x43; type: dfn;
-	text: stacking context
-url: https://drafts.csswg.org/css-position-3/#positioned-box; type: dfn;
-	text: positioned
-url: https://drafts.csswg.org/css-position-4/#paint-a-stacking-context; type: dfn;
-	text: painting a stacking context
-
    - -
    -spec:dom; type:interface; text:Document
-spec:dom; type:dfn; for:Event; text:target
-spec:infra; type:dfn; text:code point
-
    - -
    -{
-	"DWW95": {
-		"title": "Developing International Software for Windows 95 and Windows NT: A Handbook for International Software Design",
-		"authors": [ "N. Kano" ],
-		"publisher": "Microsoft Press",
-		"date": "1995",
-		"isbn": "1-55615-840-8"
-	},
-	"US-ASCII": {
-		"title": "Coded Character Set - 7-Bit American Standard Code for Information Interchange",
-		"publisher": "Standard ANSI X3.4-1986",
-		"date": "1986"
-	},
-	"WIN1252": {
-		"title": "Windows 1252 a Coded Character Set - 8-Bit",
-		"href": "https://www.microsoft.com/globaldev/reference/sbcs/1252.htm",
-		"publisher": "Microsoft Corporation"
-	}
-}
-
    - -

    Introduction

    - -

    Overview

    - - TODO. - -

    Conformance

    - - Boilerplate? - -

    Stylistic Conventions

    - -This specification follows the -Proposed W3C Specification Conventions, -with the following supplemental additions: - -* The key cap printed on a key is shown as - KEYCAP{↓}, KEYCAP{=} or KEYCAP{Q}. This is used to refer to a - key from the user's perspective without regard for the - {{KeyboardEvent/key}} and {{KeyboardEvent/code}} values in the - generated {{KeyboardEvent}}. - -* Glyphs representing character are shown as: GLYPH{𣧂}. - -* Unicode character encodings are shown as: UNI{U+003d}. - -* Names of key values generated by a key press (i.e., the value of - {{KeyboardEvent}}.{{KeyboardEvent/key}}) are shown as: - KEY{ArrowDown}, KEY_NOLINK{=}, KEY_NOLINK{q} or KEY_NOLINK{Q}. - -* Names of key codes associated with the physical keys (i.e., the - value of {{KeyboardEvent}}.{{KeyboardEvent/code}}) are shown as: - CODE{ArrowDown}, CODE{Equal} or CODE{KeyQ}. - - -In addition, certain terms are used in this specification with particular -meanings. The term implementation applies to a browser, content -authoring tool, or other user agent that implements this specification, -while a content author is a person who writes script or code that takes -advantage of the interfaces, methods, attributes, events, and other features -described in this specification in order to make Web applications, and a user is -the person who uses those Web applications in an implementation. - -And finally: - -

    This is a note.

    - - - -

    This is an open issue.

    - -

    This is a warning.

    - -
    -	  interface Example {
-	      // This is an IDL definition.
-	  };
-
    - -

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

    - -

    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: {{KeyboardEvent/ctrlKey}}, - {{KeyboardEvent/shiftKey}}, {{KeyboardEvent/altKey}}, - {{KeyboardEvent/metaKey}}. These attributes are equivalent to using the - method {{KeyboardEvent/getModifierState()}} with KEYCAP{Control}, - KEYCAP{Shift}, KEYCAP{Alt}, or KEYCAP{Meta} respectively. - - To create an instance of the {{KeyboardEvent}} interface, use the - {{KeyboardEvent}} constructor, passing an optional - {{KeyboardEventInit}} dictionary. - -

    KeyboardEvent

    - - 
    -			[Exposed=Window]
-			interface KeyboardEvent : UIEvent {
-				constructor(DOMString type, optional KeyboardEventInit eventInitDict = {});
-				// 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;
-
-				readonly attribute DOMString key;
-				readonly attribute DOMString code;
-				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 boolean 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 KEYCAP{NumLock} - key) did not originate from the numeric keypad (or did not - originate with a virtual key corresponding to the numeric - keypad). - -

    - The KEYCAP{Q} key on a PC 101 Key US keyboard.
    - The KEYCAP{NumLock} key on a PC 101 Key US keyboard.
    - The KEYCAP{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 KEYCAP{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 KEYCAP{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 - KEYCAP{NumLock} key should always be encoded with a - {{KeyboardEvent/location}} of - {{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}}. - -

    - The KEYCAP{1} key on a PC 101 Key US keyboard located on the - numeric pad. -

    -
    - -
    key
    -
    - 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
    -
    - 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
    -
    - The {{KeyboardEvent/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 - {{KeyboardEvent/location}} value for a remapped key MUST be set - to a value which is appropriate for the new key. For example, if - the CODE{ControlLeft} key is mapped to the CODE{KeyQ} key, then - the {{KeyboardEvent/location}} attribute MUST be set to - {{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}}. Conversely, if the - CODE{KeyQ} key is remapped to one of the KEYCAP{Control} keys, - then the {{KeyboardEvent/location}} attribute MUST be set to - either {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} or - {{KeyboardEvent/DOM_KEY_LOCATION_RIGHT}}. - - The un-initialized value of this attribute MUST be - 0. -
    - -
    ctrlKey
    -
    - true if the KEYCAP{Control} (control) key modifier - was active. - - The un-initialized value of this attribute MUST be - false. -
    - -
    shiftKey
    -
    - true if the shift (KEYCAP{Shift}) key modifier was - active. - - The un-initialized value of this attribute MUST be - false. -
    - -
    altKey
    -
    - true if the KEYCAP{Alt} (alternative) (or - GLYPH{Option}) key modifier was active. - - The un-initialized value of this attribute MUST be - false. -
    - -
    metaKey
    -
    - true if the meta (KEYCAP{Meta}) key modifier was - active. - -

    - The GLYPH{Command} (GLYPH{⌘}) key modifier on Macintosh - systems is represented using this key modifier. -

    - - The un-initialized value of this attribute MUST be - false. -
    - -
    repeat
    -
    - true if the key has been pressed in a sustained - manner. Holding down a key MUST result in the repeating the - events EVENT{keydown}, EVENT{beforeinput}, EVENT{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 {{KeyboardEvent/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
    -
    - true if the key event occurs as part of a - composition session, i.e., after a EVENT{compositionstart} event - and before the corresponding EVENT{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 {{KeyboardEvent/location}}. -

    -
    -
    -
    -
    - -

    KeyboardEventInit

    - - 
    -			dictionary KeyboardEventInit : EventModifierInit {
-				DOMString key = "";
-				DOMString code = "";
-				unsigned long location = 0;
-				boolean repeat = false;
-				boolean isComposing = false;
-			};
-
    - -
    -
    key
    -
    - 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
    -
    - 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
    -
    - Initializes the {{KeyboardEvent/location}} attribute of the - KeyboardEvent object to one of the following location numerical - constants: - - * {{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}} (numerical value 0) - * {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} (numerical value 1) - * {{KeyboardEvent/DOM_KEY_LOCATION_RIGHT}} (numerical value 2) - * {{KeyboardEvent/DOM_KEY_LOCATION_NUMPAD}} (numerical value 3) -
    - -
    repeat
    -
    - 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
    -
    - 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 {{KeyboardEvent/key}} and {{KeyboardEvent/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. -

    - -

    Keyboard Event Key Location

    - - The {{KeyboardEvent/location}} attribute can be used to disambiguate - between {{KeyboardEvent/key}} values that can be generated by different - physical keys on the keyboard, for example, the left and right - KEYCAP{Shift} key or the physical arrow keys vs. the numpad arrow keys - (when KEYCAP{NumLock} is off). - - The following table defines the valid {{KeyboardEvent/location}} values - for the special keys that have more than one location on the keyboard: - - ++---------------------------------+----------------------------------------------+ - =| {{KeyboardEvent}} . | Valid {{KeyboardEvent/location}} values | - | {{KeyboardEvent/key}} | | - +---------------------------------+----------------------------------------------+ - +| KEY{Shift}, KEY{Control}, | {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}}, | - | KEY{Alt}, KEY{Meta} | {{KeyboardEvent/DOM_KEY_LOCATION_RIGHT}} | - +---------------------------------+----------------------------------------------+ - +| KEY{ArrowDown}, KEY{ArrowLeft}, | {{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}}, | - | KEY{ArrowRight}, KEY{ArrowUp} | {{KeyboardEvent/DOM_KEY_LOCATION_NUMPAD}} | - +---------------------------------+----------------------------------------------+ - +| KEY{End}, KEY{Home}, | {{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}}, | - | KEY{PageDown}, KEY{PageUp} | {{KeyboardEvent/DOM_KEY_LOCATION_NUMPAD}} | - +---------------------------------+----------------------------------------------+ - +| KEY_NOLINK{0}, KEY_NOLINK{1}, | {{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}}, | - | KEY_NOLINK{2}, KEY_NOLINK{2}, | {{KeyboardEvent/DOM_KEY_LOCATION_NUMPAD}} | - | KEY_NOLINK{4}, KEY_NOLINK{5}, | | - | KEY_NOLINK{6}, KEY_NOLINK{7}, | | - | KEY_NOLINK{8}, KEY_NOLINK{9}, | | - | KEY_NOLINK{.}, KEY{Enter}, | | - | KEY_NOLINK{+}, KEY_NOLINK{-}, | | - | KEY_NOLINK{*}, KEY_NOLINK{/} | | - ++---------------------------------+----------------------------------------------+ - - For all other keys not listed in this table, the - {{KeyboardEvent/location}} attribute MUST always be set to - {{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}}. - -

    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 {{KeyboardEvent/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 EVENT{keyup} event is dispatched. This might - delay the EVENT{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 EVENT{keydown} event for the KEYCAP{Tab} key will likely have - a different event target than the EVENT{keyup} event on the same - keystroke. - -

    Keyboard Event Types

    - -

    keydown

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| Type | keydown | - +| Interface | {{KeyboardEvent}} | - +| Sync / Async | Sync | - +| Bubbles | Yes | - +| Trusted Targets | Element | - +| Cancelable | Yes | - +| Composed | Yes | - +| Default action | Varies: EVENT{beforeinput} and EVENT{input} events; launch | - | | text composition system; EVENT{blur} and EVENT{focus} events; EVENT{keypress} | - | | event (if supported); activation behavior; other event | - +| Context
    |
      | - | (trusted events) |
    • {{Event}}.{{Event/target}} : focused element processing the key event or if no | - | | element focused, then the body element if available, otherwise the | - | | root element
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    • {{KeyboardEvent}}.{{KeyboardEvent/key}} : the key value of the key pressed.
      • | - | |
    • {{KeyboardEvent}}.{{KeyboardEvent/code}} : the code value associated with the | - | | key's physical placement on the keyboard.
      • | - | |
    • {{KeyboardEvent}}.{{KeyboardEvent/location}} : the location of the key on the | - | | device.
      • | - | |
    • {{KeyboardEvent}}.{{KeyboardEvent/altKey}} : true if KEYCAP{Alt} | - | | modifier was active, otherwise false
      • | - | |
    • {{KeyboardEvent}}.{{KeyboardEvent/shiftKey}} : true if KEYCAP{Shift}| - | | modifier was active, otherwise false
      • | - | |
    • {{KeyboardEvent}}.{{KeyboardEvent/ctrlKey}} : true if KEYCAP{Control}| - | | modifier was active, otherwise false
      • | - | |
    • {{KeyboardEvent}}.{{KeyboardEvent/metaKey}} : true if KEYCAP{Meta} | - | | modifier was active, otherwise false
      • | - | |
    • {{KeyboardEvent}}.{{KeyboardEvent/repeat}} : true if a key has been | - | | depressed long enough to trigger key repetition, otherwise false
      • | - | |
    • {{KeyboardEvent}}.{{KeyboardEvent/isComposing}} : true if the key | - | | event occurs as part of a composition session, otherwise false
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - A user agent MUST dispatch this event when a key is pressed - down. The EVENT{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 - EVENT{beforeinput}, EVENT{input}, and EVENT{keyup} events associated - with the same key. - - The default action of the EVENT{keydown} event depends upon the key: - - * If the key is associated with a character, the default action - MUST be to dispatch a EVENT{beforeinput} event followed by an - EVENT{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 EVENT{beforeinput} / EVENT{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 KEYCAP{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 KEYCAP{Enter} or KEYCAP{ } (Space) key and the - current focus is on a state-changing element, the default action - MUST be to dispatch a EVENT{click} event, and a - EVENT{DOMActivate} event if that event type is supported by the - user agent (refer to [[#event-flow-activation]] 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 EVENT{keydown} and EVENT{keyup} events are traditionally - associated with detecting any key, not just those which produce a - character value. -

    - -

    keyup

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| Type | keyup | - +| Interface | {{KeyboardEvent}} | - +| Sync / Async | Sync | - +| Bubbles | Yes | - +| Trusted Targets | Element | - +| Cancelable | Yes | - +| Composed | Yes | - +| Default action | None | - +| Context
    |
      | - | (trusted events) |
    • {{Event}}.{{Event/target}} : focused element processing the key event or if no | - | | element focused, then the body element if available, otherwise the | - | | root element
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    • {{KeyboardEvent}}.{{KeyboardEvent/key}} : the key value of the key pressed.
      • | - | |
    • {{KeyboardEvent}}.{{KeyboardEvent/code}} : the code value associated with the | - | | key's physical placement on the keyboard.
      • | - | |
    • {{KeyboardEvent}}.{{KeyboardEvent/location}} : the location of the key on the | - | | device.
      • | - | |
    • {{KeyboardEvent}}.{{KeyboardEvent/altKey}} : true if KEYCAP{Alt} | - | | modifier was active, otherwise false
      • | - | |
    • {{KeyboardEvent}}.{{KeyboardEvent/shiftKey}} : true if KEYCAP{Shift}| - | | modifier was active, otherwise false
      • | - | |
    • {{KeyboardEvent}}.{{KeyboardEvent/ctrlKey}} : true if KEYCAP{Control}| - | | modifier was active, otherwise false
      • | - | |
    • {{KeyboardEvent}}.{{KeyboardEvent/metaKey}} : true if KEYCAP{Meta} | - | | modifier was active, otherwise false
      • | - | |
    • {{KeyboardEvent}}.{{KeyboardEvent/repeat}} : true if a key has been | - | | depressed long enough to trigger key repetition, otherwise false
      • | - | |
    • {{KeyboardEvent}}.{{KeyboardEvent/isComposing}} : true if the key | - | | event occurs as part of a composition session, otherwise false
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - A user agent MUST dispatch this event when a key is released. - The EVENT{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 - EVENT{keydown}, EVENT{beforeinput}, and EVENT{input} events - associated with the same key. - -

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

    - - -

    Keyboard events and key values

    - - This section contains necessary information regarding keyboard events: - - * Explanation of keyboard layout, mapping, and key values. - * Relations between keys, such as dead keys or modifiers keys. - * Relations between keyboard events and their default actions. - * The set of key values, and guidelines on how to extend this set. - -

    - This section uses Serbian and Kanji characters which could be misrepresented or - unavailable in the PDF version or printed version of this specification. -

    - -

    Keyboard Input

    - - This section is non-normative - - The relationship of each key to the complete keyboard has three separate - aspects, each of which vary among different models and configurations of - keyboards, particularly for locale-specific reasons: - - * Mechanical layout: the dimensions, size, and placement - of the physical keys on the keyboard - * Visual markings: the labels (or legends) that - mark each key - * Functional mapping: the abstract key-value association - of each key. - - This specification only defines the functional mapping, in terms of - key values and - code values, - but briefly describes key legends - for background. - -

    Key Legends

    - - This section is informative - - The key legend is the visual marking that is printed or embossed on the - key cap (the rectangular "cap" that covers the mechanical - switch for the key). These markings normally consist of one or more - characters that a keystroke on that key will produce (such as GLYPH{G}, - GLYPH{8}, or GLYPH{ш}), or names or symbols which indicate that key's - function (such as an upward-pointing arrow GLYPH{⇧} indicating - KEYCAP{Shift}, or the string "Enter"). Keys are often - referred to by this marking (e.g., Press the "Shift" and - "G" keys.). Note, however, that the visual appearance - of the key has no bearing on its digital representation, and in many - configurations may be completely inaccurate. Even the control and - function keys, such as KEYCAP{Enter}, may be mapped to different - functionality, or even mapped as character keys. - -

    - Many keyboards contain keys that do not normally produce any characters, - even though the symbol might have a Unicode equivalent. For example, the - KEYCAP{Shift} key might bear the symbol GLYPH{⇧}, which has the - Unicode code point UNI{U+21E7}, but - pressing the KEYCAP{Shift} key will not produce this character value, - and there is no Unicode code point for KEYCAP{Shift}. -

    - -

    Key codes

    - - A key {{KeyboardEvent/code}} is an attribute of a keyboard event that can be - used to identify the physical key associated with the keyboard event. It is - similar to USB Usage IDs in that it provides a low-level value (similar to a - scancode) that is vendor-neutral. - - The primary purpose of the {{KeyboardEvent/code}} attribute is to provide a - consistent and coherent way to identify keys based on their physical - location. In addition, it also provides a stable name (unaffected by the - current keyboard state) that uniquely identifies each key on the keyboard. - - The list of valid {{KeyboardEvent/code}} values is defined in the - [[!UIEvents-Code]]. - -

    Motivation for the {{KeyboardEvent/code}} Attribute

    - - The standard PC keyboard has a set of keys (which we refer to as - writing system keys) that generate different - {{KeyboardEvent/key}} values based on the current keyboard layout - selected by the user. This situation makes it difficult to write code - that detects keys based on their physical location since the code would - need to know which layout is in effect in order to know which - {{KeyboardEvent/key}} values to check for. A real-world example of this - is a game that wants to use the GLYPH{W}, GLYPH{A}, GLYPH{S} and - GLYPH{D} keys to control player movement. The {{KeyboardEvent/code}} - attribute solves this problem by providing a stable value to check that - is not affected by the current keyboard layout. - - In addition, the values in the {{KeyboardEvent/key}} attribute depend as - well on the current keyboard state. Because of this, the order in which - keys are pressed and released in relation to modifier keys can affect - the values stored in the {{KeyboardEvent/key}} attribute. The - {{KeyboardEvent/code}} attribute solves this problem by providing a - stable value that is not affected by the current keyboard state. - -

    The Relationship Between {{KeyboardEvent/key}} and {{KeyboardEvent/code}}

    - -
    -
    {{KeyboardEvent/key}}
    -
    The {{KeyboardEvent/key}} attribute is intended for users who - are interested in the meaning of the key being pressed, taking - into account the current keyboard layout (and IME; - dead keys are given a unique - {{KeyboardEvent/key}} value). Example use case: Detecting - modified keys or bare modifier keys (e.g., to perform an action - in response to a keyboard shortcut). -
    - -
    {{KeyboardEvent/code}}
    -
    The {{KeyboardEvent/code}} attribute is intended for users who - are interested in the key that was pressed by the user, without - any layout modifications applied. Example use case: Detecting - WASD keys (e.g., for movement controls in a game) or trapping - all keys (e.g., in a remote desktop client to send all keys to - the remote host). -
    -
    - -

    code Examples

    - -
    - Handling the Left and Right Alt Keys - - ++----------+----------------------+----------------------+------------------------------------------+ - =| Keyboard |{{KeyboardEvent}}
    |{{KeyboardEvent}}
    | Notes | - | Layout |{{KeyboardEvent/key}} |{{KeyboardEvent/code}}| | - +----------+----------o-----------+----------o-----------+------------------------------------------+ - +| US | KEY{Alt} | CODE{AltLeft} | {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} | - +| French | KEY{Alt} | CODE{AltLeft} | {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} | - +| US | KEY{Alt} | CODE{AltRight} | {{KeyboardEvent/DOM_KEY_LOCATION_RIGHT}} | - +| French | KEY{AltGraph} | CODE{AltRight} | {{KeyboardEvent/DOM_KEY_LOCATION_RIGHT}} | - ++----------+----------------------+----------------------+------------------------------------------+ - - In this example, checking the {{KeyboardEvent/key}} attribute permits - matching KEYCAP{Alt} without worrying about which Alt key (left or - right) was pressed. Checking the {{KeyboardEvent/code}} attribute - permits matching the right Alt key (CODE{AltRight}) without worrying - about which layout is currently in effect. - - Note that, in the French example, the KEYCAP{Alt} and KEYCAP{AltGraph} keys - retain their left and right location, even though there is only one of - each key. -
    - -
    - Handling the Single Quote Key - - ++----------+----------------------+----------------------+--------+ - =| Keyboard |{{KeyboardEvent}}
    |{{KeyboardEvent}}
    | Notes | - | Layout |{{KeyboardEvent/key}} |{{KeyboardEvent/code}}| | - +----------+----------o-----------+-----------o----------+--------+ - +| US | KEY_NOLINK{'} | CODE{Quote} | | - +| Japanese | KEY_NOLINK{:} | CODE{Quote} | | - +| US Intl | KEY{Dead} | CODE{Quote} | | - ++----------+----------------------+----------------------+--------+ - - This example shows how dead key values are encoded in the - attributes. The {{KeyboardEvent/key}} values vary based on the - current locale, whereas the {{KeyboardEvent/code}} attribute returns - a consistent value. -
    - -
    - Handling the GLYPH{2} Key (with and without Shift pressed) on - various keyboard layouts. - - ++----------+----------------------+----------------------+----------------------------+ - =| Keyboard |{{KeyboardEvent}}
    |{{KeyboardEvent}}
    | Notes | - | Layout |{{KeyboardEvent/key}} |{{KeyboardEvent/code}}| | - +----------+----------o-----------+----------o-----------+----------------------------+ - +| US | KEY_NOLINK{2} | CODE{Digit2} | | - +| US | KEY_NOLINK{@} | CODE{Digit2} | {{KeyboardEvent/shiftKey}} | - +| UK | KEY_NOLINK{2} | CODE{Digit2} | | - +| UK | KEY_NOLINK{"} | CODE{Digit2} | {{KeyboardEvent/shiftKey}} | - +| French | KEY_NOLINK{é} | CODE{Digit2} | | - +| French | KEY_NOLINK{2} | CODE{Digit2} | {{KeyboardEvent/shiftKey}} | - ++----------+----------------------+----------------------+----------------------------+ - - Regardless of the current locale or the modifier key state, pressing - the key labelled GLYPH{2} on a US keyboard always results in - CODE{Digit2} in the {{KeyboardEvent/code}} attribute. - -
    - -
    - Sequence of Keyboard Events : KEYCAP{Shift} and KEYCAP{2} - - - Compare the attribute values in the following two key event - sequences. They both produce the GLYPH{@} character on a US - keyboard, but differ in the order in which the keys are released. In - the first sequence, the order is: KEYCAP{Shift} (down), KEYCAP{2} - (down), KEYCAP{2} (up), KEYCAP{Shift} (up). - - ++---+----------+----------------------+----------------------+-----------------------------------------+ - =| # | Event |{{KeyboardEvent}}
    |{{KeyboardEvent}}
    | Notes | - | | Type |{{KeyboardEvent/key}} |{{KeyboardEvent/code}}| | - +---+----------+----------o-----------+----------o-----------+-----------------------------------------+ - +| 1 | keydown | KEY{Shift} | CODE{ShiftLeft} | {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} | - +| 2 | keydown | KEY_NOLINK{@} | CODE{Digit2} | {{KeyboardEvent/shiftKey}} | - +| 3 | keypress | KEY_NOLINK{@} | CODE{Digit2} | (if supported) | - +| 4 | keyup | KEY_NOLINK{@} | CODE{Digit2} | {{KeyboardEvent/shiftKey}} | - +| 5 | keyup | KEY{Shift} | CODE{ShiftLeft} | {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} | - ++---+----------+----------------------+----------------------+-----------------------------------------+ - - In the second sequence, the Shift is released before the 2, - resulting in the following event order: KEYCAP{Shift} (down), - KEYCAP{2} (down), KEYCAP{Shift} (up), KEYCAP{2} (up). - - ++---+----------+----------------------+----------------------+-----------------------------------------+ - =| # | Event |{{KeyboardEvent}}
    |{{KeyboardEvent}}
    | Notes | - | | Type |{{KeyboardEvent/key}} |{{KeyboardEvent/code}}| | - +---+----------+----------o-----------+----------o-----------+-----------------------------------------+ - +| 1 | keydown | KEY{Shift} | CODE{ShiftLeft} | {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} | - +| 2 | keydown | KEY_NOLINK{@} | CODE{Digit2} | {{KeyboardEvent/shiftKey}} | - +| 3 | keypress | KEY_NOLINK{@} | CODE{Digit2} | (if supported) | - +| 4 | keyup | KEY{Shift} | CODE{ShiftLeft} | {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} | - +| 5 | keyup | KEY_NOLINK{2} | CODE{Digit2} | | - ++---+----------+----------------------+----------------------+-----------------------------------------+ - - Note that the values contained in the {{KeyboardEvent/key}} - attribute does not match between the keydown and keyup events for - the GLYPH{2} key. The {{KeyboardEvent/code}} attribute provides a - consistent value that is not affected by the current modifier state. - -
    - -

    {{KeyboardEvent/code}} and Virtual Keyboards

    - - The usefulness of the {{KeyboardEvent/code}} attribute is less obvious - for virtual keyboards (and also for remote controls and chording - keyboards). In general, if a virtual (or remote control) keyboard is - mimicking the layout and functionality of a standard keyboard, then it - MUST also set the {{KeyboardEvent/code}} attribute as appropriate. For - keyboards which are not mimicking the layout of a standard keyboard, - then the {{KeyboardEvent/code}} attribute MAY be set to the closest - match on a standard keyboard or it MAY be left undefined. - - For virtual keyboards with keys that produce different values based on - some modifier state, the {{KeyboardEvent/code}} value should be the - {{KeyboardEvent/key}} value generated when the button is pressed while - the device is in its factory-reset state. - -

    Keyboard Event key Values

    - - A key value is a DOMString that can be used to indicate any - given key on a keyboard, regardless of position or state, by the value it - produces. These key values MAY be used as return values for keyboard events - generated by the implementation, or as input values by the content author to - specify desired input (such as for keyboard shortcuts). - - The list of valid key values is defined in [[!UIEvents-Key]]. - - Key values can be used to detect the value of a key which has been pressed, - using the {{KeyboardEvent/key}} attribute. Content authors can retrieve the - character value of upper- or lower-case letters, number, symbols, or - other character-producing keys, and also the key value of control - keys, modifier keys, function keys, or other keys that do not generate - characters. These values can be used for monitoring particular input - strings, for detecting and acting on modifier key input in combination with - other inputs (such as a mouse), for creating virtual keyboards, or for any - number of other purposes. - - Key values can also be used by content authors in string comparisons, as - values for markup attributes (such as the HTML accesskey) in - conforming host languages, or for other related purposes. A - conforming host language SHOULD allow content authors to use either - of the two equivalent string values for a key value: the character - value, or the key value. - -

    - While implementations will use the most relevant value for a key - independently of the platform or keyboard layout mappings, content authors - can not make assumptions on the ability of keyboard devices to generate - them. When using keyboard events and key values for shortcut-key - combinations, content authors can consider using numbers and function - keys (KEYCAP{F4}, KEYCAP{F5}, and so on) instead of letters ([[DWW95]]) - given that most keyboard layouts will provide keys for those. -

    - - A key value does not indicate a specific key on the physical keyboard, nor - does it reflect the character printed on the key. A key value indicates the - current value of the event with consideration to the current state of all - active keys and key input modes (including shift modes), as reflected in the - operating-system mapping of the keyboard and reported to the implementation. - In other words, the key value for the key labeled KEYCAP{O} on a - QWERTY keyboard has the key value KEY_NOLINK{o} in an unshifted state and - KEY_NOLINK{O} in a shifted state. Because a user can map their keyboard to an - arbitrary custom configuration, the content author is encouraged not to - assume that a relationship exists between the shifted and unshifted states - of a key and the majuscule form (uppercase or capital letters) and minuscule - form (lowercase or small letters) of a character representation, but is - encouraged instead to use the value of the {{KeyboardEvent/key}} attribute. - For example, the Standard "102" Keyboard layout depicted in [[UIEvents-Code]] - illustrates one possible set of key mappings on one possible keyboard - layout. Many others exist, both standard and idiosyncratic. - -

    - To simplify dead key support, when the operating-system mapping of - the keyboard is handling a dead key state, the current state of the - dead key sequence is not reported via the {{KeyboardEvent/key}} attribute. - Rather, a key value of KEY{Dead} is reported. Instead, implementations - generate composition events which - contain the intermediate state of the dead key sequence reported via the - {{CompositionEvent/data}} attribute. As in the previous example, the key - value for the key marked KEYCAP{O} on a QWERTY keyboard has a - {{CompositionEvent/data}} value of "ö" in an - unshifted state during a dead-key operation to add an umlaut diacritic, and - "Ö" in a shifted state during a dead-key - operation to add an umlaut diacritic. -

    - - It is also important to note that there is not a one-to-one relationship - between key event states and key values. A particular key value might be - associated with multiple keys. For example, many standard keyboards contain - more than one key with the KEYCAP{Shift} key value (normally distinguished - by the {{KeyboardEvent/location}} values - {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} and - {{KeyboardEvent/DOM_KEY_LOCATION_RIGHT}}) or KEYCAP{8} key value (normally - distinguished by the {{KeyboardEvent/location}} values - {{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}} and - {{KeyboardEvent/DOM_KEY_LOCATION_NUMPAD}}), and user-configured custom - keyboard layouts MAY duplicate any key value in multiple key-state scenarios - (note that {{KeyboardEvent/location}} is intended for standard keyboard - layouts, and cannot always indicate a meaningful distinction). - - Finally, the meaning of any given character representation is - context-dependent and complex. For example, in some contexts, the asterisk - (star) glyph (GLYPH{*}) represents a footnote or - emphasis (when bracketing a passage of text). However, in some documents or - executable programs it is equivalent to the mathematical multiplication - operation, while in other documents or executable programs, that function is - reserved for the multiplication symbol (GLYPH{×}, Unicode value - UNI{U+00D7}) or the Latin small letter "x" - (due to the lack of a multiplication key on many keyboards and the - superficial resemblance of the glyphs GLYPH{×} and GLYPH{x}). Thus, - the semantic meaning or function of character representations is outside the - scope of this specification. - -

    Modifier keys

    - - Keyboard input uses modifier keys to change the normal behavior of a - key. Like other keys, modifier keys generate EVENT{keydown} and - EVENT{keyup} events, as shown in the example below. Some modifiers are - activated while the key is being pressed down or maintained pressed such - as KEYCAP{Alt}, KEYCAP{Control}, KEYCAP{Shift}, KEYCAP{AltGraph}, or - KEYCAP{Meta}. Other modifiers are activated depending on their state - such as KEYCAP{CapsLock}, KEYCAP{NumLock}, or KEYCAP{ScrollLock}. Change - in the state happens when the modifier key is being pressed down. The - {{KeyboardEvent}} interface provides convenient attributes for some - common modifiers keys: {{KeyboardEvent/ctrlKey}}, - {{KeyboardEvent/shiftKey}}, {{KeyboardEvent/altKey}}, - {{KeyboardEvent/metaKey}}. Some operating systems simulate the - KEYCAP{AltGraph} modifier key with the combination of the KEYCAP{Alt} - and KEYCAP{Control} modifier keys. Implementations are encouraged to use - the KEYCAP{AltGraph} modifier key. - -
    - This example describes a possible sequence of events - associated with the generation of the Unicode character Q (Latin - Capital Letter Q, Unicode code point UNI{U+0051}) on a US - keyboard using a US mapping: - - ++---+-------------+----------------------+----------------------------+------------------------+ - =| # | Event Type |{{KeyboardEvent}}
    | Modifiers | Notes | - | | |{{KeyboardEvent/key}} | | | - +---+-------------+----------o-----------+-------------o--------------+------------------------+ - +| 1 | keydown | KEY{Shift} | {{KeyboardEvent/shiftKey}} | | - +| 2 | keydown | KEY_NOLINK{Q} | {{KeyboardEvent/shiftKey}} | Latin Capital Letter Q | - +| 3 | beforeinput | | | | - +| 4 | input | | | | - +| 5 | keyup | KEY_NOLINK{Q} | {{KeyboardEvent/shiftKey}} | | - +| 6 | keyup | KEY{Shift} | | | - ++---+-------------+----------------------+----------------------------+------------------------+ -
    - -
    - Th example describes an alternate sequence of keys to the - example above, where the KEYCAP{Shift} key is released before the - KEYCAP{Q} key. The key value for the KEYCAP{Q} key will revert to its - unshifted value for the EVENT{keyup} event: - - ++---+-------------+----------------------+----------------------------+------------------------+ - =| # | Event Type |{{KeyboardEvent}}
    | Modifiers | Notes | - | | |{{KeyboardEvent/key}} | | | - +---+-------------+----------o-----------+-------------o--------------+------------------------+ - +| 1 | keydown | KEY{Shift} | {{KeyboardEvent/shiftKey}} | | - +| 2 | keydown | KEY_NOLINK{Q} | {{KeyboardEvent/shiftKey}} | Latin Capital Letter Q | - +| 3 | beforeinput | | | | - +| 4 | input | | | | - +| 5 | keyup | KEY{Shift} | | | - +| 6 | keyup | KEY_NOLINK{q} | | Latin Small Letter Q | - ++---+-------------+----------------------+----------------------------+------------------------+ -
    - -
    - The following example describes a possible sequence of keys that - does not generate a Unicode character (using the same configuration - as the previous example): - - ++---+-------------+----------------------+----------------------------+----------------------------+ - =| # | Event Type |{{KeyboardEvent}}
    | Modifiers | Notes | - | | |{{KeyboardEvent/key}} | | | - +---+-------------+----------o-----------+-------------o--------------+----------------------------+ - +| 1 | keydown | KEY{Control} | {{KeyboardEvent/ctrlKey}} | | - +| 2 | keydown | KEY_NOLINK{v} | {{KeyboardEvent/ctrlKey}} | Latin Small Letter V | - +| | | | | No EVENT{beforeinput} | - | | | | | or EVENT{input} events are | - | | | | | generated. | - +| 3 | keyup | KEY_NOLINK{v} | {{KeyboardEvent/ctrlKey}} | Latin Small Letter V | - +| 4 | keyup | KEY{Control} | | | - ++---+-------------+----------------------+----------------------------+----------------------------+ -
    - -
    - The following example shows the sequence of events when both KEYCAP{Shift} and - KEYCAP{Control} are pressed: - - ++---+-------------+----------------------+----------------------------+----------------------------+ - =| # | Event Type |{{KeyboardEvent}}
    | Modifiers | Notes | - | | |{{KeyboardEvent/key}} | | | - +---+-------------+----------o-----------+-------------o--------------+----------------------------+ - +| 1 | keydown | KEY{Control} | {{KeyboardEvent/ctrlKey}} | | - +| 2 | keydown | KEY{Shift} | {{KeyboardEvent/ctrlKey}}, | | - | | | | {{KeyboardEvent/shiftKey}} | | - +| 3 | keydown | KEY_NOLINK{V} | {{KeyboardEvent/ctrlKey}}, | Latin Capital Letter V | - | | | | {{KeyboardEvent/shiftKey}} | | - +| | | | | No EVENT{beforeinput} | - | | | | | or EVENT{input} events are | - | | | | | generated. | - +| 4 | keyup | KEY_NOLINK{V} | {{KeyboardEvent/ctrlKey}}, | Latin Capital Letter V | - | | | | {{KeyboardEvent/shiftKey}} | | - +| 5 | keyup | KEY{Shift} | {{KeyboardEvent/ctrlKey}} | | - +| 6 | keyup | KEY{Control} | | | - ++---+-------------+----------------------+----------------------------+----------------------------+ -
    - -
    - For non-US keyboard layouts, the sequence of events is the same, but - the value of the key is based on the current keyboard layout. This - example shows a sequence of events when an Arabic keyboard layout is - used: - - ++---+-------------+----------------------+----------------------------+----------------------------+ - =| # | Event Type |{{KeyboardEvent}}
    | Modifiers | Notes | - | | |{{KeyboardEvent/key}} | | | - +---+-------------+----------o-----------+-------------o--------------+----------------------------+ - +| 1 | keydown | KEY{Control} | {{KeyboardEvent/ctrlKey}} | | - +| 2 | keydown | KEY_NOLINK{ر} | {{KeyboardEvent/ctrlKey}} | Arabic Letter Reh | - +| | | | | No EVENT{beforeinput} | - | | | | | or EVENT{input} events are | - | | | | | generated. | - +| 3 | keyup | KEY_NOLINK{ر} | {{KeyboardEvent/ctrlKey}} | Arabic Letter Reh | - +| 4 | keyup | KEY{Control} | | | - ++---+-------------+----------------------+----------------------------+----------------------------+ -
    - -

    - The value in the EVENT{keydown} and EVENT{keyup} events varies based on - the current keyboard layout in effect when the key is pressed. This - means that the KEYCAP{v} key on a US layout and the KEYCAP{ر} key on an - Arabic layout will generate different events even though they are the - same physical key. To identify these events as coming from the same - physical key, you will need to make use of the {{KeyboardEvent/code}} - attribute. -

    - - In some cases, modifier keys change the {{KeyboardEvent/key}} - value for a key event. For example, on some MacOS keyboards, the key - labeled "delete" functions the same as the KEYCAP{Backspace} key on the - Windows OS when unmodified, but when modified by the KEYCAP{Fn} key, - acts as the KEYCAP{Delete} key, and the value of {{KeyboardEvent/key}} - will match the most appropriate function of the key in its current - modified state. - -

    Dead keys

    - - Some keyboard input uses dead keys for the input of composed - character sequences. Unlike the handwriting sequence, in which users - enter the base character first, keyboard input requires to enter a - special state when a dead key is pressed and emit the - character(s) only when one of a limited number of legal base - character is entered. - -

    - The MacOS and Linux operating systems use input methods to process - dead keys. -

    - - The dead keys (across all keyboard layouts and mappings) are - represented by the key value KEYCAP{Dead}. In response to any dead key - press, composition events must - be dispatched by the user agent and the EVENT{compositionupdate} event's - {{CompositionEvent/data}} value must be the character value of the - current state of the dead key combining sequence. - - While Unicode combining characters always follow the handwriting - sequence, with the combining character trailing the corresponding - letter, typical dead key input MAY reverse the sequence, with the - combining character before the corresponding letter. For example, the - word naïve, using the combining diacritic ¨, would be - represented sequentially in Unicode as nai¨ve, but MAY be typed - na¨ive. The sequence of keystrokes UNI{U+0302} (Combining - Circumflex Accent key) and UNI{U+0065} (key marked with the Latin Small - Letter E) will likely produce (on a French keyboard using a french - mapping and without any modifier activated) the Unicode character - GLYPH{ê} (Latin Small Letter E With Circumflex), as preferred by - the Unicode Normalization Form NFC. - -
    - ++---+-------------------+----------------------+-----------------------------+-------------------------+----------------------+ - =| # | Event Type |{{KeyboardEvent}}
    |{{KeyboardEvent}}
    |{{CompositionEvent}}
    | Notes | - | | |{{KeyboardEvent/key}} |{{KeyboardEvent/isComposing}}|{{CompositionEvent/data}}| | - +---+-------------------+----------o-----------+-------------o---------------+------------o------------+----------------------+ - +| 1 | keydown | KEY{Dead} | false | | Combining Circumflex | - | | | | | | Accent (Dead Key) | - +| 2 | compositionstart | | | "" | | - +| 3 | compositionupdate | | | UNI{U+0302} | | - +| 4 | keyup | KEY{Dead} | true | | | - +| 5 | keydown | KEY_NOLINK{ê} | true | | | - +| 6 | compositionupdate | | | GLYPH{ê} | | - +| 7 | compositionend | | | GLYPH{ê} | | - +| 8 | keyup | KEY_NOLINK{e} | false | | Latin Small Letter E | - ++---+-------------------+----------------------+-----------------------------+-------------------------+----------------------+ -
    - -

    - In the second EVENT{keydown} event (step 5), the key value (assuming the - event is not suppressed) will not be KEY_NOLINK{e} (Latin Small - Letter E key) under normal circumstances because the value delivered to - the user agent will already be modified by the dead key operation. -

    - - This process might be aborted when a user types an unsupported base - character (that is, a base character for which the active - diacritical mark is not available) after pressing a dead key: - -
    - ++---+-------------------+----------------------+-----------------------------+-------------------------+----------------------+ - =| # | Event Type |{{KeyboardEvent}}
    |{{KeyboardEvent}}
    |{{CompositionEvent}}
    | Notes | - | | |{{KeyboardEvent/key}} |{{KeyboardEvent/isComposing}}|{{CompositionEvent/data}}| | - +---+-------------------+----------o-----------+--------------o--------------+------------o------------+----------------------+ - +| 1 | keydown | KEY{Dead} | false | | Combining Circumflex | - | | | | | | Accent (Dead Key) | - +| 2 | compositionstart | | | "" | | - +| 3 | compositionupdate | | | UNI{U+0302} | | - +| 4 | keyup | KEY{Dead} | true | | | - +| 5 | keydown | KEY_NOLINK{q} | true | | Latin Small Letter Q | - +| 6 | compositionupdate | | | "" | | - +| 7 | compositionend | | | "" | | - +| 8 | keyup | KEY_NOLINK{q} | false | | | - ++---+-------------------+----------------------+-----------------------------+-------------------------+----------------------+ -
    - -

    Input Method Editors

    - - This specification includes a model for input method editors - (IMEs), through the {{CompositionEvent}} interface and events. - However, Composition Events and Keyboard Events do not necessarily map - as a one-to-one relationship. As an example, receiving a EVENT{keydown} - for the KEYCAP{Accept} key value does not necessarily imply that the - text currently selected in the IME is being accepted, but - indicates only that a keystroke happened, disconnected from the - IME Accept functionality (which would normally result in a - EVENT{compositionend} event in most IME systems). Keyboard - events cannot be used to determine the current state of the input method - editor, which can be obtained through the {{CompositionEvent/data}} - attribute of the {{CompositionEvent}} interface. Additionally, - IME systems and devices vary in their functionality, and in which - keys are used for activating that functionality, such that the - KEYCAP{Convert} and KEYCAP{Accept} keys MAY be represented by other - available keys. Keyboard events correspond to the events generated by - the input device after the keyboard layout mapping. - -

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

    - - The following example describes a possible sequence of keys to generate - the Unicode character GLYPH{市} (Kanji character, part of CJK - Unified Ideographs) using Japanese input methods. This example assumes - that the input method editor is activated and in the Japanese-Romaji - input mode. The keys KEYCAP{Convert} and KEYCAP{Accept} MAY be replaced - by others depending on the input device in use and the configuration of - the IME, e.g., it can be respectively UNI{U+0020} (Space key) and - KEYCAP{Enter}. - -

    - GLYPH{詩} (poem) and GLYPH{市} (city) are - homophones, both pronounced し (shi/si), so the user - needs to use the KEYCAP{Convert} key to select the proper option. -

    - -
    - ++----+-------------------+----------------------+-----------------------------+-------------------------+----------------------+ - =| # | Event Type |{{KeyboardEvent}}
    |{{KeyboardEvent}}
    |{{CompositionEvent}}
    | Notes | - | | |{{KeyboardEvent/key}} |{{KeyboardEvent/isComposing}}|{{CompositionEvent/data}}| | - +----+-------------------+----------o-----------+--------------o--------------+------------o------------+----------------------+ - +| 1 | keydown | KEY_NOLINK{s} | false | | Latin Small Letter S | - +| 2 | compositionstart | | | GLYPH{} | | - +| 3 | beforeinput | | | | | - +| 4 | compositionupdate | | | GLYPH{s} | | - +| | | | | | DOM is updated | - +| 5 | input | | | | | - +| 6 | keyup | KEY_NOLINK{s} | true | | | - +| 7 | keydown | KEY_NOLINK{i} | true | | Latin Small Letter I | - +| 8 | beforeinput | | | | | - +| 9 | compositionupdate | | | GLYPH{し} | shi | - +| | | | | | DOM is updated | - +| 10 | input | | | | | - +| 11 | keyup | KEY_NOLINK{i} | true | | | - +| 12 | keydown | KEY{Convert} | true | | Convert | - +| 13 | beforeinput | | | | | - +| 14 | compositionupdate | | | GLYPH{詩} | "poem" | - +| | | | | | DOM is updated | - +| 15 | input | | | | | - +| 16 | keyup | KEY{Convert} | true | | | - +| 17 | keydown | KEY{Convert} | true | | Convert | - +| 18 | beforeinput | | | | | - +| 19 | compositionupdate | | | GLYPH{市} | "city" | - +| | | | | | DOM is updated | - +| 20 | input | | | | | - +| 21 | keyup | KEY{Convert} | true | | | - +| 22 | keydown | KEY{Accept} | true | | Accept | - +| 23 | compositionend | | | GLYPH{市} | | - +| 24 | keyup | KEY{Accept} | false | | | - ++----+-------------------+----------------------+-----------------------------+-------------------------+----------------------+ -
    - - IME composition can also be canceled as in the following example, with - conditions identical to the previous example. The key KEYCAP{Cancel} - might also be replaced by others depending on the input device in use - and the configuration of the IME, e.g., it could be UNI{U+001B} (Escape - key). - -
    - ++----+-------------------+----------------------+-----------------------------+-------------------------+----------------------+ - =| # | Event Type |{{KeyboardEvent}}
    |{{KeyboardEvent}}
    |{{CompositionEvent}}
    | Notes | - | | |{{KeyboardEvent/key}} |{{KeyboardEvent/isComposing}}|{{CompositionEvent/data}}| | - +----+-------------------+----------o-----------+--------------o--------------+------------o------------+----------------------+ - +| 1 | keydown | KEY_NOLINK{s} | false | | Latin Small Letter S | - +| 2 | compositionstart | | | GLYPH{} | | - +| 3 | compositionupdate | | | GLYPH{s} | | - +| 4 | keyup | KEY_NOLINK{s} | true | | | - +| 5 | keydown | KEY_NOLINK{i} | true | | Latin Small Letter I | - +| 6 | compositionupdate | | | GLYPH{し} | shi | - +| 7 | keyup | KEY_NOLINK{i} | true | | | - +| 8 | keydown | KEY{Convert} | true | | Convert | - +| 9 | compositionupdate | | | GLYPH{詩} | "poem" | - +| 10 | keyup | KEY{Convert} | true | | | - +| 11 | keydown | KEY{Convert} | true | | Convert | - +| 12 | compositionupdate | | | GLYPH{市} | "city" | - +| 13 | keyup | KEY{Convert} | true | | | - +| 14 | keydown | KEY{Cancel} | true | | Cancel | - +| 15 | compositionupdate | | | GLYPH{} | | - +| 16 | compositionend | | | GLYPH{} | | - +| 17 | keyup | KEY{Cancel} | false | | | - ++----+-------------------+----------------------+-----------------------------+-------------------------+----------------------+ -
    - -

    - Some input method editors (such as on the MacOS operating system) - might set an empty string to the composition data attribute - before canceling a composition. -

    - -
    Input Method Editor mode keys
    - - Some keys on certain devices are intended to activate input - method editor functionality, or to change the mode of an active - input method editor. Custom keys for this purpose can be - defined for different devices or language modes. The keys defined in - this specification for this purpose are: KEY{Alphanumeric}, - KEY{CodeInput}, KEY{FinalMode}, KEY{HangulMode}, KEY{HanjaMode}, - KEY{Hiragana}, KEY{JunjaMode}, KEY{KanaMode}, KEY{KanjiMode}, - KEY{Katakana}, and KEY{Romaji}. When one of these keys is - pressed, and no IME is currently active, the appropriate - IME is expected to be activated in the mode indicated by the - key (if available). If an IME is already active when the key - is pressed, the active IME might change to the indicated - mode, or a different IME might be launched, or the might MAY - be ignored, on a device- and application-specific basis. - - This specification also defines other keys which are intended for - operation specifically with input method editors: - KEY{Accept}, KEY{AllCandidates}, KEY{Cancel}, KEY{Convert}, - KEY{Compose}, KEY{Zenkaku} (FullWidth), KEY{Hankaku} (HalfWidth), KEY{NextCandidate}, - KEY{NonConvert}, and KEY{PreviousCandidate}. The functions of these - keys are not defined in this specification — refer to other - resources for details on input method editor functionality. - -

    - Keys with input method editor functions are not restricted to - that purpose, and can have other device- or implementation-specific - purposes. -

    - -

    Default actions and cancelable keyboard events

    - - Canceling the default action of a EVENT{keydown} event MUST NOT - affect its respective EVENT{keyup} event, but it MUST prevent the - respective EVENT{beforeinput} and EVENT{input} (and EVENT{keypress} if - supported) events from being generated. The following example describes - a possible sequence of keys to generate the Unicode character Q (Latin - Capital Letter Q) on a US keyboard using a US mapping: - -
    - ++---+-------------+----------------------+--------------------+----------------------------+-----------------------------------+ - =| # | Event Type |{{KeyboardEvent}}
    |{{InputEvent}}
    | Modifiers | Notes | - | | |{{KeyboardEvent/key}} |{{InputEvent/data}} | | | - +---+-------------+----------o-----------+---------o----------+--------------o-------------+-----------------------------------+ - +| 1 | keydown | KEY{Shift} | | {{KeyboardEvent/shiftKey}} | | - +| 2 | keydown | KEY_NOLINK{Q} | | {{KeyboardEvent/shiftKey}} | The default action is | - | | | | | | prevented, e.g., by invoking | - | | | | | | {{Event/preventDefault()}}. | - +| | | | | | No EVENT{beforeinput} or | - | | | | | | EVENT{input} (or EVENT{keypress}, | - | | | | | | if supported) events are | - | | | | | | generated | - +| 3 | keyup | KEY_NOLINK{Q} | | {{KeyboardEvent/shiftKey}} | | - +| 4 | keyup | KEY{Shift} | | | | - ++---+-------------+----------------------+--------------------+----------------------------+-----------------------------------+ -
    - - If the key is a modifier key, the keystroke MUST still be taken into - account for the modifiers states. The following example describes a - possible sequence of keys to generate the Unicode character Q (Latin - Capital Letter Q) on a US keyboard using a US mapping: - -
    - ++---+-------------+----------------------+--------------------+----------------------------+-----------------------------------+ - =| # | Event Type |{{KeyboardEvent}}
    |{{InputEvent}}
    | Modifiers | Notes | - | | |{{KeyboardEvent/key}} |{{InputEvent/data}} | | | - +---+-------------+----------o-----------+---------o----------+--------------o-------------+-----------------------------------+ - +| 1 | keydown | KEY{Shift} | | {{KeyboardEvent/shiftKey}} | The default action is | - | | | | | | prevented, e.g., by invoking | - | | | | | | {{Event/preventDefault()}}. | - +| 2 | keydown | KEY_NOLINK{Q} | | {{KeyboardEvent/shiftKey}} | | - +| 3 | beforeinput | | GLYPH{Q} | | | - +| 4 | input | | | | | - +| 5 | keyup | KEY_NOLINK{Q} | | {{KeyboardEvent/shiftKey}} | | - +| 6 | keyup | KEY{Shift} | | | | - ++---+-------------+----------------------+--------------------+----------------------------+-----------------------------------+ -
    - - If the key is part of a sequence of several keystrokes, whether it is a - dead key or it is contributing to an Input Method Editor - sequence, the keystroke MUST be ignored (not taken into account) only if - the default action is canceled on the EVENT{keydown} event. - Canceling a dead key on a EVENT{keyup} event has no effect on - EVENT{beforeinput} or EVENT{input} events. The following example uses - the dead key KEY{Dead} (UNI{U+0302} Combining Circumflex Accent key) and - KEY_NOLINK{e} (UNI{U+0065}, Latin Small Letter E key) on a French - keyboard using a French mapping and without any modifier activated: - -
    - ++---+-------------+----------------------+--------------------+-----------------------------------+ - =| # | Event Type |{{KeyboardEvent}}
    |{{InputEvent}}
    | Notes | - | | |{{KeyboardEvent/key}} |{{InputEvent/data}} | | - +---+-------------+----------o-----------+---------o----------+-----------------------------------+ - +| 1 | keydown | KEY{Dead} | | The default action is | - | | | | | prevented, e.g., by invoking | - | | | | | {{Event/preventDefault()}}. | - +| 2 | keyup | KEY{Dead} | | | - +| 3 | keydown | KEY_NOLINK{e} | | | - +| 4 | beforeinput | | GLYPH{e} | | - +| 5 | input | | | | - +| 6 | keyup | KEY_NOLINK{e} | | | - ++---+-------------+----------------------+--------------------+-----------------------------------+ -
    - -

    Constructing Mouse and Keyboard Events

    - - Generally, when a constructor of an {{Event}} interface, or of an interface - inherited from the {{Event}} interface, is invoked, the steps described in - [[!DOM]] should be followed. However the {{KeyboardEvent}} and - {{MouseEvent}} interfaces provide additional dictionary members for - initializing the internal state of the {{Event}} object's key modifiers: - specifically, the internal state queried for using the - {{KeyboardEvent/getModifierState()}} and {{MouseEvent/getModifierState()}} - methods. This section supplements the DOM4 steps for intializing a new - {{Event}} object with these optional modifier states. - - For the purposes of constructing a {{KeyboardEvent}}, {{MouseEvent}}, or - object derived from these objects using the algorithm below, all - {{KeyboardEvent}}, {{MouseEvent}}, and derived objects have - internal key modifier state which can be set and - retrieved using the key modifier names - described in the - Modifier Keys table - in [[UIEvents-Key]]. - - The following steps supplement the algorithm defined for constructing - events in DOM4: - - * If the {{Event}} being constructed is a {{KeyboardEvent}} or - {{MouseEvent}} object or an object that derives from either of these, - and a {{EventModifierInit}} argument was provided to the constructor, - then run the following sub-steps: - - * For each {{EventModifierInit}} argument, if the dictionary member - begins with the string "modifier", then let the - key modifier name be the - dictionary member's name excluding the prefix - "modifier", and set the {{Event}} object's - internal key modifier state - that matches the key modifier name - to the corresponding value. - -

    Legacy {{KeyboardEvent}} events

    - - The EVENT{keypress} event is the traditional method for capturing key events - and processing them before the DOM is updated with the effects of the key - press. Code that makes use of the EVENT{keypress} event typically relies on - the legacy {{KeyboardEvent/charCode}}, {{KeyboardEvent/keyCode}}, and - {{UIEvent/which}} attributes. - - Note that the EVENT{keypress} event is specific to key events, and has been - replaced by the more general event sequence of EVENT{beforeinput} and - EVENT{input} events. These new input events are not specific to - keyboard actions and can be used to capture user input regardless of the - original source. - -

    Legacy {{KeyboardEvent}} event types

    - -

    keypress

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typekeypress
    Interface{{KeyboardEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    ComposedYes
    Default actionVaries: - launch text composition system; - EVENT{blur} and EVENT{focus} events; - EVENT{DOMActivate} event; - other event
    Context
    (trusted events)    		 -
      -
    • {{Event}}.{{Event/target}} : - focused element processing the key event or if no element focused, then the - body element if available, otherwise the - root element
      • -
    • {{UIEvent}}.{{UIEvent/view}} : - Window
      • -
    • {{UIEvent}}.{{UIEvent/detail}} : - 0
      • -
    • {{KeyboardEvent}}.{{UIEvent/which}} : - legacy numerical code for this key
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/charCode}} : - legacy character value for this event
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/keyCode}} : - legacy numerical code for this key
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/key}} : - the key value of the key pressed.
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/code}} : - the code value associated with the key's physical placement on the keyboard.
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/location}} : - the location of the key on the device.
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/altKey}} : - true if KEYCAP{Alt} modifier was active, otherwise false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/shiftKey}} : - true if KEYCAP{Shift} modifier was active, otherwise false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/ctrlKey}} : - true if KEYCAP{Control} modifier was active, otherwise false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/metaKey}} : - true if KEYCAP{Meta} modifier was active, otherwise false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/repeat}} : - false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/isComposing}} : - true if the key event occurs as part of a composition session, otherwise false
      • -
    -
    - - If supported by a user agent, this event MUST be dispatched - when a key is pressed down, if and only if that key normally - produces a character value. The EVENT{keypress} 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. It - MUST NOT be fired when using an input method editor. - - If this event is canceled, it should prevent the EVENT{input} event - from firing, in addition to canceling the default action. - - Authors SHOULD use the EVENT{beforeinput} event instead of the - EVENT{keypress} event. - -

    - The EVENT{keypress} event is traditionally associated with detecting - a character value rather than a physical key, and might not - be available on all keys in some configurations. -

    - -

    - The EVENT{keypress} event type is defined in this specification for - reference and completeness, but this specification deprecates - the use of this event type. When in editing contexts, authors can - subscribe to the EVENT{beforeinput} event instead. -

    - -

    EVENT{keypress} event order

    - - The EVENT{keypress} event type MUST be dispatched after the - EVENT{keydown} event and before the EVENT{keyup} event associated with - the same key. - - The EVENT{keypress} event type MUST be dispatched after the - EVENT{beforeinput} event and before the EVENT{input} event associated - with the same key. - - The sequence of key events for user-agents the support the - EVENT{keypress} event is demonstrated in the following example: - -
    - ++---+-------------+------------------------+---------------------+--------------------------------+ - =| # | Event Type | {{KeyboardEvent}}
    | {{InputEvent}}
    | Notes | - | | | {{KeyboardEvent/key}} | {{InputEvent/data}} | | - +---+-------------+-----------o------------+----------o----------+--------------------------------+ - +| 1 | keydown | KEY_NOLINK{a} | | | - +| 2 | beforeinput | | GLYPH{a} | | - +| 3 | keypress | KEY_NOLINK{a} | | | - +| | | | | Any default actions | - | | | | | related to this key, such as | - | | | | | inserting a character in to | - | | | | | the DOM. | - +| 4 | input | | | | - +| 5 | keyup | KEY_NOLINK{a} | | | - ++---+-------------+------------------------+---------------------+--------------------------------+ -
    - -

    Legacy Event Initializers

    - - This section is normative. - - The following features are obsolete and should only be implemented by - user agents that require compatibility with legacy software. - - Early versions of this specification included an initialization method on - the interface (for example initMouseEvent) that required a long - list of parameters that, in most cases, did not fully initialize all - attributes of the event object. Because of this, event interfaces which were - derived from the basic {{Event}} interface required that the initializer of - each of the derived interfaces be called explicitly in order to - fully initialize an event. - -
    - Initializing all the attributes of a UIEvent requires calls to two - initializer methods: initEvent and - initUIEvent. -
    - - Due in part to the length of time in the development of this standard, some - implementations MAY have taken a dependency on these (now deprecated) - initializer methods. For completeness, these legacy event initializers are - described in this section. - -

    Initializers for interface KeyboardEvent

    - - This section is informative - -

    - The argument list to this legacy KeyboardEvent initializer does not - include the detailArg (present in other initializers) and - adds the locale argument (see [[#changes-drafts]]); it is - necessary to preserve this inconsistency for compatibility with existing - implementations. -

    - - 
    -		partial interface KeyboardEvent {
-			// Originally introduced (and deprecated) in this specification
-			undefined initKeyboardEvent(DOMString typeArg,
-				optional boolean bubblesArg = false,
-				optional boolean cancelableArg = false,
-				optional Window? viewArg = null,
-				optional DOMString keyArg = "",
-				optional unsigned long locationArg = 0,
-				optional boolean ctrlKey = false,
-				optional boolean altKey = false,
-				optional boolean shiftKey = false,
-				optional boolean metaKey = false);
-		};
-
    - -
    -
    initKeyboardEvent(typeArg)
    -
    - Initializes attributes of a {{KeyboardEvent}} object. This - method has the same behavior as UIEvent.initUIEvent(). - The value of {{UIEvent/detail}} remains undefined. - -

    - The initKeyboardEvent method is deprecated. -

    - -
    -
    DOMString typeArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    boolean bubblesArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    boolean cancelableArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    Window? viewArg
    -
    - Specifies {{UIEvent/view}}. This value MAY be null. -
    - -
    DOMString keyArg
    -
    - Specifies {{KeyboardEvent/key}}. -
    - -
    unsigned long locationArg
    -
    - Specifies {{KeyboardEvent/location}}. -
    - -
    boolean ctrlKey
    -
    - Specifies whether the Control key modifier is active. -
    - -
    boolean altKey
    -
    - Specifies whether the Alt key modifier is active. -
    - -
    boolean shiftKey
    -
    - Specifies whether the Shift key modifier is active. -
    - -
    boolean metaKey
    -
    - Specifies whether the Meta key modifier is active. -
    -
    -
    -
    - -

    Legacy Key & Mouse Event Attributes

    - - This section is non-normative. The following attributes are obsolete and should - only be implemented by user agents that require compatibility with legacy - software that requires these keyboard events. - - These features were never formally specified and the current browser - implementations vary in significant ways. - -

    Legacy {{KeyboardEvent}} supplemental interface

    - - This section is non-normative - - Browser support for keyboards has traditionally relied on three ad-hoc - attributes, {{KeyboardEvent/keyCode}}, {{KeyboardEvent/charCode}}, and - {{UIEvent}}'s {{UIEvent/which}}. - - All three of these attributes return a numerical code that represents some - aspect of the key pressed: {{KeyboardEvent/keyCode}} is an index of the key - itself. {{KeyboardEvent/charCode}} is the ASCII value of the character keys. - {{UIEvent/which}} is the character value where available and otherwise - the key index. The values for these attributes, and the availability of the - attribute, is inconsistent across platforms, keyboard languages and layouts, - user agents, versions, and even event types. - -

    Interface KeyboardEvent (supplemental)

    - - The partial {{KeyboardEvent}} interface is an informative extension of - the {{KeyboardEvent}} interface, which adds the - {{KeyboardEvent/charCode}} and {{KeyboardEvent/keyCode}} attributes. - - The partial {{KeyboardEvent}} interface can be obtained by using the - {{Document/createEvent()}} method call in - implementations that support this extension. - - 
    -			partial interface KeyboardEvent {
-			  // The following support legacy user agents
-			  readonly attribute unsigned long charCode;
-			  readonly attribute unsigned long keyCode;
-			};
-
    - -
    -
    charCode
    -
    - {{KeyboardEvent/charCode}} holds a character value, for - EVENT{keypress} events which generate character input. The value - is the Unicode reference number (code point) of that character - (e.g. event.charCode = event.key.charCodeAt(0) for - printable characters). For EVENT{keydown} or EVENT{keyup} - events, the value of {{KeyboardEvent/charCode}} is - 0. -
    - -
    keyCode
    -
    - {{KeyboardEvent/keyCode}} holds a system- and - implementation-dependent numerical code signifying the - unmodified identifier associated with the key pressed. Unlike - the {{KeyboardEvent/key}} attribute, the set of possible values - are not normatively defined in this specification. Typically, - these value of the {{KeyboardEvent/keyCode}} SHOULD represent - the decimal codepoint in ASCII [[RFC20]][[US-ASCII]] or Windows - 1252 [[WIN1252]], but MAY be drawn from a different appropriate - character set. Implementations that are unable to identify a key - use the key value KEYCAP{0}. - - See [[#legacy-key-models]] for more details on how to determine - the values for {{KeyboardEvent/keyCode}}. -
    -
    - -

    Interface KeyboardEventInit (supplemental)

    - - Browsers that include support for {{KeyboardEvent/keyCode}} - and {{KeyboardEvent/charCode}} in - {{KeyboardEvent}} should also add the following members to the - {{KeyboardEventInit}} dictionary. - - The partial {{KeyboardEventInit}} dictionary is an informative extension - of the {{KeyboardEventInit}} dictionary, which adds - {{KeyboardEvent/charCode}} and {{KeyboardEvent/keyCode}} - members to initialize the corresponding - {{KeyboardEvent}} attributes. - - 
    -			partial dictionary KeyboardEventInit {
-			  // The following support legacy user agents
-			  unsigned long charCode = 0;
-			  unsigned long keyCode = 0;
-			};
-
    - -
    -
    charCode
    -
    - Initializes the {{KeyboardEvent/charCode}} attribute of the - {{KeyboardEvent}} to the Unicode code point for the event's - character. -
    - -
    keyCode
    -
    - Initializes the {{KeyboardEvent/keyCode}} attribute of the - {{KeyboardEvent}} to the system- and implementation-dependent - numerical code signifying the unmodified identifier associated - with the key pressed. -
    -
    - -

    Legacy key models

    - - This section is non-normative - - Implementations differ on which values are exposed on these attributes for - different event types. An implementation MAY choose to expose both virtual - key codes and character codes in the {{KeyboardEvent/keyCode}} property - (conflated model), or report separate {{KeyboardEvent/keyCode}} and - {{KeyboardEvent/charCode}} properties (split model). - -

    How to determine {{KeyboardEvent/keyCode}} for EVENT{keydown} and EVENT{keyup} events

    - - The {{KeyboardEvent/keyCode}} for EVENT{keydown} or EVENT{keyup} events - is calculated as follows: - - * Read the virtual key code from the operating system's event - information, if such information is available. - - * If an Input Method Editor is processing key input and the event is - EVENT{keydown}, return 229. - - * If input key when pressed without modifiers would insert a numerical - character (0-9), return the ASCII code of that numerical character. - - * If input key when pressed without modifiers would insert a lower - case character in the a-z alphabetical range, return the ASCII code - of the upper case equivalent. - - * If the implementation supports a key code conversion table for the - operating system and platform, look up the value. If the conversion - table specifies an alternate virtual key value for the given input, - return the specified value. - - * If the key's function, as determined in an implementation-specific - way, corresponds to one of the keys in the - [[#fixed-virtual-key-codes]] table, return the corresponding key - code. - - * Return the virtual key code from the operating system. - - * If no key code was found, return 0. - -

    How to determine {{KeyboardEvent/keyCode}} for EVENT{keypress} events

    - - The {{KeyboardEvent/keyCode}} for EVENT{keypress} events is calculated - as follows: - - * If the implementation supports a conflated model, set - {{KeyboardEvent/keyCode}} to the Unicode code point of the character - being entered. - - * If the implementation supports a split model, set - {{KeyboardEvent/keyCode}} to 0. - -

    Fixed virtual key codes

    - - The virtual key codes for the following keys do not usually change with - keyboard layouts on desktop systems: - - ++------------+-------------+-------+ - =| Key | Virtual Key | Notes | - | |
    Code | | - +------------+------o------+---o---+ - +| Backspace | 8 | | - +| Tab | 9 | | - +| Enter | 13 | | - +| Shift | 16 | | - +| Control | 17 | | - +| Alt | 18 | | - +| CapsLock | 20 | | - +| Escape | 27 | Esc | - +| Space | 32 | | - +| PageUp | 33 | | - +| PageDown | 34 | | - +| End | 35 | | - +| Home | 36 | | - +| ArrowLeft | 37 | | - +| ArrowUp | 38 | | - +| ArrowRight | 39 | | - +| ArrowDown | 40 | | - +| Delete | 46 | Del | - ++------------+-------------+-------+ - -

    Optionally fixed virtual key codes

    - - The following punctuation characters MAY change virtual codes between - keyboard layouts, but reporting these values will likely be more - compatible with legacy content expecting US-English keyboard layout: - - ++------------------------+-----------------+-------------+ - =| Key | Character | Virtual Key | - | | |
    Code | - +------------------------+--------o--------+------o------+ - +| Semicolon | GLYPH{;} | 186 | - +| Colon | GLYPH{:} | 186 | - +| Equals sign | GLYPH{=} | 187 | - +| Plus | GLYPH{+} | 187 | - +| Comma | GLYPH{,} | 188 | - +| Less than sign | GLYPH{<} | 188 | - +| Minus | GLYPH{-} | 189 | - +| Underscore | GLYPH{_} | 189 | - +| Period | GLYPH{.} | 190 | - +| Greater than sign | GLYPH{>} | 190 | - +| Forward slash | GLYPH{/} | 191 | - +| Question mark | GLYPH{?} | 191 | - +| Backtick | GLYPH{`} | 192 | - +| Tilde | GLYPH{~} | 192 | - +| Opening squace bracket | GLYPH{[} | 219 | - +| Opening curly brace | GLYPH{{} | 219 | - +| Backslash | GLYPH{\} | 220 | - +| Pipe | GLYPH{|} | 220 | - +| Closing square bracket | GLYPH{]} | 221 | - +| Closing curly brace | GLYPH{}} | 221 | - +| Single quote | GLYPH{'} | 222 | - +| Double quote | GLYPH{"} | 222 | - ++------------------------+-----------------+-------------+ - -

    Legacy Event Types

    - - This section is normative. The following event types are obsolete and should - only be implemented by user agents that require compatibility with legacy - software. - -

    Legacy {{KeyboardEvent}} events

    - - The EVENT{keypress} event is the traditional method for capturing key events - and processing them before the DOM is updated with the effects of the key - press. Code that makes use of the EVENT{keypress} event typically relies on - the legacy {{KeyboardEvent/charCode}}, {{KeyboardEvent/keyCode}}, and - {{UIEvent/which}} attributes. - - Note that the EVENT{keypress} event is specific to key events, and has been - replaced by the more general event sequence of EVENT{beforeinput} and - EVENT{input} events. These new input events are not specific to - keyboard actions and can be used to capture user input regardless of the - original source. - -

    Legacy {{KeyboardEvent}} event types

    - -
    keypress
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typekeypress
    Interface{{KeyboardEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    ComposedYes
    Default actionVaries: - launch text composition system; - EVENT{blur} and EVENT{focus} events; - EVENT{DOMActivate} event; - other event
    Context
    (trusted events)    		 -
      -
    • {{Event}}.{{Event/target}} : - focused element processing the key event or if no element focused, then the - body element if available, otherwise the - root element
      • -
    • {{UIEvent}}.{{UIEvent/view}} : - Window
      • -
    • {{UIEvent}}.{{UIEvent/detail}} : - 0
      • -
    • {{KeyboardEvent}}.{{UIEvent/which}} : - legacy numerical code for this key
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/charCode}} : - legacy character value for this event
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/keyCode}} : - legacy numerical code for this key
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/key}} : - the key value of the key pressed.
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/code}} : - the code value associated with the key's physical placement on the keyboard.
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/location}} : - the location of the key on the device.
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/altKey}} : - true if KEYCAP{Alt} modifier was active, otherwise false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/shiftKey}} : - true if KEYCAP{Shift} modifier was active, otherwise false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/ctrlKey}} : - true if KEYCAP{Control} modifier was active, otherwise false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/metaKey}} : - true if KEYCAP{Meta} modifier was active, otherwise false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/repeat}} : - false
      • -
    • {{KeyboardEvent}}.{{KeyboardEvent/isComposing}} : - true if the key event occurs as part of a composition session, otherwise false
      • -
    -
    - - If supported by a user agent, this event MUST be dispatched - when a key is pressed down, if and only if that key normally - produces a character value. The EVENT{keypress} 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. It - MUST NOT be fired when using an input method editor. - - If this event is canceled, it should prevent the EVENT{input} event - from firing, in addition to canceling the default action. - - Authors SHOULD use the EVENT{beforeinput} event instead of the - EVENT{keypress} event. - -

    - The EVENT{keypress} event is traditionally associated with detecting - a character value rather than a physical key, and might not - be available on all keys in some configurations. -

    - -

    - The EVENT{keypress} event type is defined in this specification for - reference and completeness, but this specification deprecates - the use of this event type. When in editing contexts, authors can - subscribe to the EVENT{beforeinput} event instead. -

    - -

    EVENT{keypress} event order

    - - The EVENT{keypress} event type MUST be dispatched after the - EVENT{keydown} event and before the EVENT{keyup} event associated with - the same key. - - The EVENT{keypress} event type MUST be dispatched after the - EVENT{beforeinput} event and before the EVENT{input} event associated - with the same key. - - The sequence of key events for user-agents the support the - EVENT{keypress} event is demonstrated in the following example: - -
    - ++---+-------------+------------------------+---------------------+--------------------------------+ - =| # | Event Type | {{KeyboardEvent}}
    | {{InputEvent}}
    | Notes | - | | | {{KeyboardEvent/key}} | {{InputEvent/data}} | | - +---+-------------+-----------o------------+----------o----------+--------------------------------+ - +| 1 | keydown | KEY_NOLINK{a} | | | - +| 2 | beforeinput | | GLYPH{a} | | - +| 3 | keypress | KEY_NOLINK{a} | | | - +| | | | | Any default actions | - | | | | | related to this key, such as | - | | | | | inserting a character in to | - | | | | | the DOM. | - +| 4 | input | | | | - +| 5 | keyup | KEY_NOLINK{a} | | | - ++---+-------------+------------------------+---------------------+--------------------------------+ -
    - -

    Security Considerations

    - - TODO - Add specific concerns for this spec - -

    Acknowledgements

    - - TODO - -

    Refs to other UIEvent specs \[DELETE]

    - - This section will be deleted. - - Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references. - - beforeinput - blur - click - compositionend - compositionstart - compositionupdate - DOMActivate - input - -

    Things defined in other sections

    - -

    Activation triggers and behavior

    -

    Default actions and cancelable events

    -

    Event dispatch and DOM event flow

    -

    Focus Events

    -

    Web browsers and other dynamic or interactive user agents

    -

    Authoring tools

    - -

    Things defined in CompositionEvents

    -

    Composition Events

    - -

    Things defined in Changes

    -

    Changes between different drafts of UI Events

    - -

    Glossary \[DELETE]

    - -This section will be deleted. - -Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline. - -: 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 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 - [[#event-flow-activation]] for more details. - -: activation trigger -:: An event which is defined to initiate an activation behavior. Refer - to [[#event-flow-activation]] for more details. - -: body element -:: In HTML or XHTML documents, the body element represents the contents of the - document. In a well-formed HTML document, the body element is a first - descendant of the root element. - -: 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, each - belonging to the set of valid Unicode character categories. - In this specification, character values are denoted as a unicode string - (e.g., UNI{U+0020}) or a glyph representation of the same code point (e.g., - GLYPH{ }), and are color coded to help distinguish these two representations. - -

    - In source code, some key values, such as non-graphic characters, can 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., - GLYPH{ö}, GLYPH{é}, GLYPH{â}). - -: 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 - [[#event-flow-default-cancel]]. - -: 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. - -: 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 event - target. Each event is an instantiation of one specific event - type. - -: event target -:: The object to which an event is targeted using the [[#event-flow]]. - The event target is the value of the {{Event/target}} attribute. - -: 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 UI Events, and they integrate and extend the objects - and models defined in this specification. - -: IME -: input method editor -:: An input method editor (IME), also known as a front end - processor, is an application that performs the conversion between - keystrokes and ideographs or other characters, usually by user-guided - dictionary lookup, often used in East Asian languages (e.g., Chinese, - Japanese, Korean). An IME MAY also be used for dictionary-based word - completion, such as on mobile devices. See [[#keys-IME]] for treatment of - IMEs in this specification. See also text composition system. - -: 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 (KEYCAP{Shift}, KEYCAP{Alt}, et al.) and dead key states. - -: key value -:: A key value is a character value or multi-character string (such as - KEY{Enter}, KEY{Tab}, or KEY{MediaTrackNext}) 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. - -: 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 KEYCAP{Shift} key), or to alter - what functionality the key triggers (as with the KEYCAP{Fn} or KEYCAP{Alt} - keys). See [[#keys-modifiers]] for more information about modifier keys and - refer to the [=Modifier Keys table=] in [[UIEvents-Key]] for a list - of valid modifier keys. - -: 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. - -: 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. - -: Unicode character categories -:: A subset of the General Category values that are defined for each Unicode - code point. This subset contains all the - Letter (Ll, - Lm, - Lo, - Lt, - Lu), - Number (Nd, - Nl, - No), - Punctuation (Pc, - Pd, - Pe, - Pf, - Pi, - Po, - Ps) - and Symbol (Sc, - Sk, - Sm, - So) - category values. - -: un-initialized value -:: The value of any event attribute (such as {{Event/bubbles}} or - {{Event/currentTarget}}) before the event has been initialized with - {{Event/initEvent()}}. The un-initialized values of an event apply - immediately after a new event has been created using the method - {{Document/createEvent()}}. - -: 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 [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the - requirements for a conforming user agent. - -: Window -:: The Window is the object referred to by the current document's - browsing context's Window Proxy object as defined in - HTML5 - [[HTML5]]. - diff --git a/split/mouse-events.bs b/split/mouse-events.bs deleted file mode 100644 index 10157231..00000000 --- a/split/mouse-events.bs +++ /dev/null @@ -1,1555 +0,0 @@ -

    Mouse Events

    - -
    -Shortname: mouse-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
-	*** Mouse Events ***
-
-	Note: This is an experimental split of the UI Events spec into smaller, event-specific
-	specs. The split was made from an out-of-date snapshot, so the information here is not
-	current, so please focus on the overall structure rather than the specifics of the
-	content. If this experiment goes well, then we will split the current spec after all
-	outstanding pull requests have been handled.
-
    - -
    -urlPrefix: https://www.w3.org/TR/WebIDL/#idl-; type: type;
-	text: long
-urlPrefix: https://w3c.github.io/selection-api/#widl-Window-getSelection-Selection; type: dfn; for: Document
-	text: getSelection()
-url: https://www.w3.org/TR/2004/REC-xml-20040204/#NT-S; type: dfn;
-	text: white space
-url: https://www.w3.org/TR/uievents-key/#key-attribute-value; type: dfn; spec: uievents-key;
-	text: key attribute value
-url: https://www.w3.org/TR/uievents-key/#keys-modifier; type: dfn; spec: uievents-key;
-	text: modifier keys table
-url: https://html.spec.whatwg.org/multipage/forms.html#context-menus; type: dfn;
-	text: contextmenu
-url: https://www.w3.org/TR/pointerevents3/#pointerevent-interface; type: interface; spec: pointerevents3
-	text: PointerEvent
-url: https://dom.spec.whatwg.org/#concept-tree-ancestor; type: dfn;
-	text: ancestor
-url: https://www.w3.org/TR/CSS21/visuren.html#x43; type: dfn;
-	text: stacking context
-url: https://drafts.csswg.org/css-position-3/#positioned-box; type: dfn;
-	text: positioned
-url: https://drafts.csswg.org/css-position-4/#paint-a-stacking-context; type: dfn;
-	text: painting a stacking context
-
    - -
    -spec:dom; type:interface; text:Document
-spec:dom; type:dfn; for:Event; text:target
-spec:infra; type:dfn; text:code point
-
    - -

    Introduction

    - -

    Overview

    - - TODO. - -

    Conformance

    - - Boilerplate? - -

    Stylistic Conventions

    - -This specification follows the -Proposed W3C Specification Conventions, -with the following supplemental additions: - -

    This is a note.

    - - - -

    This is an open issue.

    - -

    This is a warning.

    - -
    -	  interface Example {
-	      // This is an IDL definition.
-	  };
-
    - -

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

    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 {{MouseEvent/clientX}} - and {{MouseEvent/clientY}} for calculation of other coordinates (such - as target coordinates exposed by DOM Level 0 implementations or - other proprietary attributes, e.g., pageX). -

    - -

    MouseEvent

    - - 
    -			[Exposed=Window]
-			interface MouseEvent : UIEvent {
-				constructor(DOMString type, optional MouseEventInit eventInitDict = {});
-				readonly attribute long screenX;
-				readonly attribute long screenY;
-				readonly attribute long clientX;
-				readonly attribute long clientY;
-				readonly attribute long layerX;
-				readonly attribute long layerY;
-
-				readonly attribute boolean ctrlKey;
-				readonly attribute boolean shiftKey;
-				readonly attribute boolean altKey;
-				readonly attribute boolean metaKey;
-
-				readonly attribute short button;
-				readonly attribute unsigned short buttons;
-
-				readonly attribute EventTarget? relatedTarget;
-
-				boolean getModifierState(DOMString keyArg);
-			};
-
    - -
    -
    screenX
    -
    - 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
    -
    - 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
    -
    - 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
    -
    - 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. -
    - -
    layerX
    -
    - The horizontal offset from the nearest ancestor element which - is a stacking context, is positioned, or paints in the - positioned phase when painting a stacking context. - - The un-initialized value of this attribute MUST be - 0. -
    - -
    layerY
    -
    - The vertical offset from the nearest ancestor element which - is a stacking context, is positioned, or paints in the - positioned phase when painting a stacking context. - - The un-initialized value of this attribute MUST be - 0. -
    - -
    ctrlKey
    -
    - Refer to the {{KeyboardEvent}}'s {{KeyboardEvent/ctrlKey}} attribute. - - The un-initialized value of this attribute MUST be - false. -
    - -
    shiftKey
    -
    - Refer to the {{KeyboardEvent}}'s {{KeyboardEvent/shiftKey}} attribute. - - The un-initialized value of this attribute MUST be - false. -
    - -
    altKey
    -
    - Refer to the {{KeyboardEvent}}'s {{KeyboardEvent/altKey}} attribute. - - The un-initialized value - of this attribute MUST be false. -
    - -
    metaKey
    -
    - Refer to the {{KeyboardEvent}}'s {{KeyboardEvent/metaKey}} attribute. - - The un-initialized value - of this attribute MUST be false. -
    - -
    button
    -
    - During mouse events caused by the depression or release of a mouse button, - {{MouseEvent/button}} MUST be used to indicate which pointer device button - changed state. - - The value of the {{MouseEvent/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 {{MouseEvent/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
    -
    - During any mouse events, {{MouseEvent/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 - {{MouseEvent/buttons}} attribute and the {{MouseEvent/button}} - attribute are very different. The value of {{MouseEvent/button}} - is assumed to be valid during mousedown / mouseup - event handlers, whereas the {{MouseEvent/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 {{MouseEvent/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
    -
    - 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 {{KeyboardEvent/getModifierState()}} - method for a description of this parameter. -
    -
    -
    -
    - -

    MouseEventInit

    - - 
    -			dictionary MouseEventInit : EventModifierInit {
-				long screenX = 0;
-				long screenY = 0;
-				long clientX = 0;
-				long clientY = 0;
-
-				short button = 0;
-				unsigned short buttons = 0;
-				EventTarget? relatedTarget = null;
-			};
-
    - -
    -
    screenX
    -
    - Initializes the {{MouseEvent/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
    -
    - Initializes the {{MouseEvent/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
    -
    - Initializes the {{MouseEvent/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
    -
    - Initializes the {{MouseEvent/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
    -
    - Initializes the {{MouseEvent/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
    -
    - Initializes the {{MouseEvent/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 {{MouseEvent/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 - {{MouseEvent/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
    -
    - 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. -

    - -

    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 {{KeyboardEvent/getModifierState()}}. The steps for - constructing events using this dictionary are defined in the - event constructors section. - - 
    -		dictionary EventModifierInit : 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
    -
    - 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 - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter Control - must return true. -
    - -
    shiftKey
    -
    - 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 - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter Shift must - return true. -
    - -
    altKey
    -
    - 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 - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter Alt must - return true. -
    - -
    metaKey
    -
    - 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 - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with either the parameter Meta - must return true. -
    - -
    modifierAltGraph
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter AltGraph must - return true. -
    - -
    modifierCapsLock
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter CapsLock must - return true. -
    - -
    modifierFn
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter Fn must - return true. -
    - -
    modifierFnLock
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter FnLock must - return true. -
    - -
    modifierHyper
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter Hyper must - return true. -
    - -
    modifierNumLock
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter NumLock must - return true. -
    - -
    modifierScrollLock
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter ScrollLock must - return true. -
    - -
    modifierSuper
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter Super must - return true. -
    - -
    modifierSymbol
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter Symbol must - return true. -
    - -
    modifierSymbolLock
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter SymbolLock must - return true. -
    -
    - -

    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 TypeElementNotes
    1mousemove
    Pointing device is moved into element A...
    2mouseoverA
    3mouseenterA
    4mousemoveAMultiple mousemove events
    Pointing device is moved out of element A...
    5mouseoutA
    6mouseleaveA
    - - 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 TypeElementNotes
    1mousemove
    Pointing device is moved into element A...
    2mouseoverA
    3mouseenterA
    4mousemoveAMultiple mousemove events
    Pointing device is moved into nested element B...
    5mouseoutA
    6mouseoverB
    7mouseenterB
    8mousemoveBMultiple mousemove events
    Pointing device is moved from element B into A...
    9mouseoutB
    10mouseleaveB
    11mouseoverA
    12mousemoveAMultiple mousemove events
    Pointing device is moved out of element A...
    13mouseoutA
    14mouseleaveA
    - - 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 TypeElementNotes
    1mousemove
    Pointing device is moved into element C, the topmost element in the stack
    2mouseoverC
    3mouseenterA
    4mouseenterB
    5mouseenterC
    6mousemoveCMultiple mousemove events
    Pointing device is moved out of element C...
    7mouseoutC
    8mouseleaveC
    9mouseleaveB
    10mouseleaveA
    - -

    - 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 TypeNotes
    1mousedown
    2mousemoveOPTIONAL, multiple events, some limits
    3mouseup
    4click
    5mousemoveOPTIONAL, multiple events, some limits
    6mousedown
    7mousemoveOPTIONAL, multiple events, some limits
    8mouseup
    9click
    10dblclick
    - -

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

    - -

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

    auxclick

    - - - - - - - - - - - -
    Typeauxclick
    Interface{{PointerEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    ComposedYes
    Default actionVaries
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : topmost event target
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : indicates the current click count; the attribute value MUST be 1 when the user begins this action and increments by 1 for each click.
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed, 0 if no buttons pressed
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : null
    • For {{PointerEvent}} specific attributes, see the [[!pointerevents3]] spec.
    - - 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 {{MouseEvent/button}} value is not 0, - {{MouseEvent/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 - {{MouseEvent/button}} or {{MouseEvent/buttons}} attributes. Typical - default actions of the auxclick event type are as follows: - - * If the event target has associated activation behavior, - the default action MUST be to execute that activation - behavior (see [[#event-flow-activation]]). - -

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

    - -

    click

    - - - - - - - - - - - -
    Typeclick
    Interface{{PointerEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    ComposedYes
    Default actionVaries
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : topmost event target
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : indicates the current click count; the attribute value MUST be 1 when the user begins this action and increments by 1 for each click.
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed, 0 if no buttons pressed
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : null
    • For {{PointerEvent}} specific attributes, see the [[!pointerevents3]] spec.
    - - 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 {{MouseEvent/button}} value is 0, - {{MouseEvent/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 [[#event-flow-activation]]. - -

    - 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 - {{MouseEvent/button}} or {{MouseEvent/buttons}} attributes. Typical - default actions of the click event type are as follows: - - * If the event target has associated activation behavior, - the default action MUST be to execute that activation - behavior (see [[#event-flow-activation]]). - - * If the event target is focusable, the default - action MUST be to give that element document focus. - -

    contextmenu

    - - - - - - - - - - - -
    Typecontextmenu
    Interface{{PointerEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    ComposedYes
    Default actionInvoke a context menu if supported.
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : topmost event target
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed, 0 if no buttons pressed
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : null
    - - A user agent MUST dispatch this event before invoking a context menu. - - When the contextmenu event is triggered by right mouse button, the - contextmenu event MUST be dispatched after the mousedown event. - -

    - Depending on the platform, the contextmenu event may be dispatched - before or after the mouseup event. -

    - -

    dblclick

    - - - - - - - - - - - -
    Typedblclick
    Interface{{MouseEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    ComposedYes
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : topmost event target
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : indicates the current click count
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed, 0 if no buttons pressed
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : null
    - - 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 {{MouseEvent/button}} - or {{MouseEvent/buttons}} attributes. The typical - default actions of the dblclick event type match those - of the click event type. - -

    mousedown

    - - - - - - - - - - - -
    Typemousedown
    Interface{{MouseEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    ComposedYes
    Default actionVaries: 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)
    • {{Event}}.{{Event/target}} : topmost event target
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : indicates the current click count incremented by one. For example, if no click happened before the mousedown, {{UIEvent/detail}} will contain the value 1
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed, 0 if no buttons pressed
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : null
    - - 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. -

    - -

    mouseenter

    - - - - - - - - - - - -
    Typemouseenter
    Interface{{MouseEvent}}
    Sync / AsyncSync
    BubblesNo
    Trusted TargetsElement
    CancelableNo
    ComposedNo
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : topmost event target
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/button}} : 0
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed, 0 if no buttons pressed
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the event target a pointing device is exiting, if any.
    - - 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. -

    - -

    mouseleave

    - - - - - - - - - - - -
    Typemouseleave
    Interface{{MouseEvent}}
    Sync / AsyncSync
    BubblesNo
    Trusted TargetsElement
    CancelableNo
    ComposedNo
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : topmost event target
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/button}} : 0
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed, 0 if no buttons pressed
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the event target a pointing device is exiting, if any.
    - - 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. -

    - -

    mousemove

    - - - - - - - - - - - -
    Typemousemove
    Interface{{MouseEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    ComposedYes
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : topmost event target
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/button}} : 0
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed, 0 if no buttons pressed
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : null
    - - 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, but was changed to reflect existing interoperability between - user agents. -

    - -

    mouseout

    - - - - - - - - - - - -
    Typemouseout
    Interface{{MouseEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    ComposedYes
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : topmost event target
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/button}} : 0
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed, 0 if no buttons pressed
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the event target a pointing device is entering, if any.
    - - 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. -

    - -

    mouseover

    - - - - - - - - - - - -
    Typemouseover
    Interface{{MouseEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    ComposedYes
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : topmost event target
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/button}} : 0
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed, 0 if no buttons pressed
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the event target a pointing device is entering, if any.
    - - 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. -

    - -

    mouseup

    - - - - - - - - - - - -
    Typemouseup
    Interface{{MouseEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    ComposedYes
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : topmost event target
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : indicates the current click count incremented by one.
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed, 0 if no buttons pressed
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : null
    - - A user agent MUST dispatch this event when a pointing device - button is released over an element. - -

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

    - -

    Constructing Mouse and Keyboard Events

    - - Generally, when a constructor of an {{Event}} interface, or of an interface - inherited from the {{Event}} interface, is invoked, the steps described in - [[!DOM]] should be followed. However the {{KeyboardEvent}} and - {{MouseEvent}} interfaces provide additional dictionary members for - initializing the internal state of the {{Event}} object's key modifiers: - specifically, the internal state queried for using the - {{KeyboardEvent/getModifierState()}} and {{MouseEvent/getModifierState()}} - methods. This section supplements the DOM4 steps for intializing a new - {{Event}} object with these optional modifier states. - - For the purposes of constructing a {{KeyboardEvent}}, {{MouseEvent}}, or - object derived from these objects using the algorithm below, all - {{KeyboardEvent}}, {{MouseEvent}}, and derived objects have - internal key modifier state which can be set and - retrieved using the key modifier names - described in the - Modifier Keys table - in [[UIEvents-Key]]. - - The following steps supplement the algorithm defined for constructing - events in DOM4: - - * If the {{Event}} being constructed is a {{KeyboardEvent}} or - {{MouseEvent}} object or an object that derives from either of these, - and a {{EventModifierInit}} argument was provided to the constructor, - then run the following sub-steps: - - * For each {{EventModifierInit}} argument, if the dictionary member - begins with the string "modifier", then let the - key modifier name be the - dictionary member's name excluding the prefix - "modifier", and set the {{Event}} object's - internal key modifier state - that matches the key modifier name - to the corresponding value. - -

    Legacy Event Initializers

    - - This section is normative. - - The following features are obsolete and should only be implemented by - user agents that require compatibility with legacy software. - - Early versions of this specification included an initialization method on - the interface (for example initMouseEvent) that required a long - list of parameters that, in most cases, did not fully initialize all - attributes of the event object. Because of this, event interfaces which were - derived from the basic {{Event}} interface required that the initializer of - each of the derived interfaces be called explicitly in order to - fully initialize an event. - -
    - Initializing all the attributes of a UIEvent requires calls to two - initializer methods: initEvent and - initUIEvent. -
    - - Due in part to the length of time in the development of this standard, some - implementations MAY have taken a dependency on these (now deprecated) - initializer methods. For completeness, these legacy event initializers are - described in this section. - -

    Initializers for interface MouseEvent

    - - This section is informative - - 
    -		partial interface MouseEvent {
-			// Deprecated in this specification
-			undefined initMouseEvent(DOMString typeArg,
-				optional boolean bubblesArg = false,
-				optional boolean cancelableArg = false,
-				optional Window? viewArg = null,
-				optional long detailArg = 0,
-				optional long screenXArg = 0,
-				optional long screenYArg = 0,
-				optional long clientXArg = 0,
-				optional long clientYArg = 0,
-				optional boolean ctrlKeyArg = false,
-				optional boolean altKeyArg = false,
-				optional boolean shiftKeyArg = false,
-				optional boolean metaKeyArg = false,
-				optional short buttonArg = 0,
-				optional EventTarget? relatedTargetArg = null);
-		};
-
    - -
    -
    initMouseEvent(typeArg)
    -
    - Initializes attributes of a {{MouseEvent}} object. This - method has the same behavior as UIEvent.initUIEvent(). - -

    - The initMouseEvent method is deprecated, but - supported for backwards-compatibility with widely-deployed - implementations. -

    - -
    -
    DOMString typeArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    boolean bubblesArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    boolean cancelableArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    Window? viewArg
    -
    - Specifies {{UIEvent/view}}. This value MAY be null. -
    - -
    long detailArg
    -
    - Specifies {{UIEvent/detail}}. -
    - -
    long screenXArg
    -
    - Specifies {{MouseEvent/screenX}}. -
    - -
    long screenYArg
    -
    - Specifies {{MouseEvent/screenY}}. -
    - -
    long clientXArg
    -
    - Specifies {{MouseEvent/clientX}}. -
    - -
    long clientYArg
    -
    - Specifies {{MouseEvent/clientY}}. -
    - -
    boolean ctrlKeyArg
    -
    - Specifies {{MouseEvent/ctrlKey}}. -
    - -
    boolean altKeyArg
    -
    - Specifies {{MouseEvent/altKey}}. -
    - -
    boolean shiftKeyArg
    -
    - Specifies {{MouseEvent/shiftKey}}. -
    - -
    boolean metaKeyArg
    -
    - Specifies {{MouseEvent/metaKey}}. -
    - -
    short buttonArg
    -
    - Specifies {{MouseEvent/button}}. -
    - -
    EventTarget? relatedTargetArg
    -
    - Specifies {{MouseEvent/relatedTarget}}. This value MAY - be null. -
    -
    -
    -
    - -

    Security Considerations

    - - TODO - Add specific concerns for this spec - -

    Acknowledgements

    - - TODO - -

    Refs to other UIEvent specs \[DELETE]

    - - This section will be deleted. - - Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references. - -

    Things defined in other sections

    - -

    Activation triggers and behavior

    -

    Composition Events

    -

    Default actions and cancelable events

    -

    Event dispatch and DOM event flow

    -

    Web browsers and other dynamic or interactive user agents

    -

    Authoring tools

    - -

    Things defined in KeyboardEvents

    -

    Modifier keys

    - -

    Glossary \[DELETE]

    - -This section will be deleted. - -Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline. - -: 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 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 - [[#event-flow-activation]] for more details. - -: activation trigger -:: An event which is defined to initiate an activation behavior. Refer - to [[#event-flow-activation]] for more details. - -: body element -:: In HTML or XHTML documents, the body element represents the contents of the - document. In a well-formed HTML document, the body element is a first - descendant of the root element. - -: 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. - -: 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 - [[#event-flow-default-cancel]]. - -: 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 event - target. Each event is an instantiation of one specific event - type. - -: event target -:: The object to which an event is targeted using the [[#event-flow]]. - The event target is the value of the {{Event/target}} attribute. - -: 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 UI 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. - -: 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 graphical user - interfaces this is the element under the user's pointing device. A user - interface's hit testing facility is used to determine the target. For - specific details regarding hit testing and stacking order, refer to the - host language. - -: un-initialized value -:: The value of any event attribute (such as {{Event/bubbles}} or - {{Event/currentTarget}}) before the event has been initialized with - {{Event/initEvent()}}. The un-initialized values of an event apply - immediately after a new event has been created using the method - {{Document/createEvent()}}. - -: 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 [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the - requirements for a conforming user agent. - -: Window -:: The Window is the object referred to by the current document's - browsing context's Window Proxy object as defined in - HTML5 - [[HTML5]]. - diff --git a/split/mouse-events.html b/split/mouse-events.html deleted file mode 100644 index 8c6c6823..00000000 --- a/split/mouse-events.html +++ /dev/null @@ -1,3121 +0,0 @@ - - - - - Mouse Events - - - - - - - - - - - - - - - - -
    -

    -

    Mouse Events

    -

    Editor’s Draft,

    -
    - More details about this document -
    -
    -
    This version: -
    https://w3c.github.io/uievents/ -
    Latest published version: -
    https://www.w3.org/TR/uievents/ -
    Feedback: -
    GitHub -
    Editors: -
    (Google) -
    (Microsoft) -
    Former Editor: -
    Doug Schepers (Mar 2008 - May 2011) -
    Tests: -
    web-platform-tests uievents/ (ongoing work) -
    -
    -
    -
    -

    Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

    -
    -
    -
    -

    Abstract

    -

    *** Mouse Events ***

    -

    Note: This is an experimental split of the UI Events spec into smaller, event-specific - - specs. The split was made from an out-of-date snapshot, so the information here is not - current, so please focus on the overall structure rather than the specifics of the - content. If this experiment goes well, then we will split the current spec after all - outstanding pull requests have been handled.

    -
    -

    Status of this document

    -
    -

    This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

    -

    This document was published by the Web Applications Working Group as an Editors Draft. This document is intended to become a W3C Recommendation.

    -

    -

    This document was published by the Web Applications Working Group as a Working Draft. - - Feedback and comments on this specification are welcome. Please use GitHub issues Historical discussions can be found in the public-webapps@w3.org archives.

    -

    Publication as an Editors Draft does not imply endorsement by W3C and its Members. This is a draft document and may - be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite - this document as other than work in progress.

    -

    This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

    -

    This document is governed by the 2 November 2021 W3C Process Document.

    -
    -
    - -
    -

    1. Introduction

    -

    1.1. Overview

    -

    TODO.

    -

    1.2. Conformance

    -

    Boilerplate?

    -

    2. Stylistic Conventions

    -

    This specification follows the Proposed W3C Specification Conventions, -with the following supplemental additions:

    -

    This is a note.

    -

    This is an open issue.

    -

    This is a warning.

    -
    interface Example {
-    // This is an IDL definition.
-};
-
    -

    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.

    -

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

    -

    3.1.1. MouseEvent

    -
    [Exposed=Window]
-interface MouseEvent : UIEvent {
-  constructor(DOMString type, optional MouseEventInit eventInitDict = {});
-  readonly attribute long screenX;
-  readonly attribute long screenY;
-  readonly attribute long clientX;
-  readonly attribute long clientY;
-  readonly attribute long layerX;
-  readonly attribute long layerY;
-
-  readonly attribute boolean ctrlKey;
-  readonly attribute boolean shiftKey;
-  readonly attribute boolean altKey;
-  readonly attribute boolean metaKey;
-
-  readonly attribute short button;
-  readonly attribute unsigned short buttons;
-
-  readonly attribute EventTarget? 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.

    -
    layerX, of type long, readonly -
    - The horizontal offset from the nearest ancestor element which - is a stacking context, is positioned, or paints in the - positioned phase when painting a stacking context. -

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

    -
    layerY, of type long, readonly -
    - The vertical offset from the nearest ancestor element which - is a stacking context, is positioned, or paints in the - positioned phase when painting a stacking context. -

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

    3.1.2. MouseEventInit

    -
    dictionary MouseEventInit : EventModifierInit {
-  long screenX = 0;
-  long screenY = 0;
-  long clientX = 0;
-  long clientY = 0;
-
-  short button = 0;
-  unsigned short 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.

    -

    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.

    -
    dictionary EventModifierInit : 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. -
    -

    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.

    -

    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.

    -

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

    -

    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 § 8.1.1 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:

    - -

    3.4.3. contextmenu

    - - - - - - - - - - - -
    Type - contextmenu -
    Interface - PointerEvent -
    Sync / Async - Sync -
    Bubbles - Yes -
    Trusted Targets - Element -
    Cancelable - Yes -
    Composed - Yes -
    Default action - Invoke a context menu if supported. -
    Context
    (trusted events) -     		- -
    -

    A user agent MUST dispatch this event before invoking a context menu.

    -

    When the contextmenu event is triggered by right mouse button, the contextmenu event MUST be dispatched after the mousedown event.

    -

    Depending on the platform, the contextmenu event may be dispatched - before or after the mouseup event.

    -

    3.4.4. 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. The typical default actions of the dblclick event type match those - of the click event type.

    -

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

    -

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

    -

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

    -

    3.4.8. 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, but was changed to reflect existing interoperability between - user agents.

    -

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

    -

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

    -

    3.4.11. mouseup

    - - - - - - - - - - - -
    Type - mouseup -
    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 - button is released over an element.

    -

    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.

    -

    4. Constructing Mouse and Keyboard Events

    -

    Generally, when a constructor of an Event interface, or of an interface - inherited from the Event interface, is invoked, the steps described in [DOM] should be followed. However the KeyboardEvent and MouseEvent interfaces provide additional dictionary members for - initializing the internal state of the Event object’s key modifiers: - specifically, the internal state queried for using the getModifierState() and getModifierState() methods. This section supplements the DOM4 steps for intializing a new Event object with these optional modifier states.

    -

    For the purposes of constructing a KeyboardEvent, MouseEvent, or - object derived from these objects using the algorithm below, all KeyboardEvent, MouseEvent, and derived objects have internal key modifier state which can be set and - retrieved using the key modifier names described in the Modifier Keys table in [UIEvents-Key].

    -

    The following steps supplement the algorithm defined for constructing - events in DOM4:

    - -

    5. Legacy Event Initializers

    -

    This section is normative.

    -

    The following features are obsolete and should only be implemented by user agents that require compatibility with legacy software.

    -

    Early versions of this specification included an initialization method on - the interface (for example initMouseEvent) that required a long - list of parameters that, in most cases, did not fully initialize all - attributes of the event object. Because of this, event interfaces which were - derived from the basic Event interface required that the initializer of each of the derived interfaces be called explicitly in order to - fully initialize an event.

    -
    Initializing all the attributes of a UIEvent requires calls to two - initializer methods: initEvent and initUIEvent.
    -

    Due in part to the length of time in the development of this standard, some - implementations MAY have taken a dependency on these (now deprecated) - initializer methods. For completeness, these legacy event initializers are - described in this section.

    -

    5.1. Initializers for interface MouseEvent

    -

    This section is informative

    -
    partial interface MouseEvent {
-  // Deprecated in this specification
-  undefined initMouseEvent(DOMString typeArg,
-    optional boolean bubblesArg = false,
-    optional boolean cancelableArg = false,
-    optional Window? viewArg = null,
-    optional long detailArg = 0,
-    optional long screenXArg = 0,
-    optional long screenYArg = 0,
-    optional long clientXArg = 0,
-    optional long clientYArg = 0,
-    optional boolean ctrlKeyArg = false,
-    optional boolean altKeyArg = false,
-    optional boolean shiftKeyArg = false,
-    optional boolean metaKeyArg = false,
-    optional short buttonArg = 0,
-    optional EventTarget? relatedTargetArg = null);
-};
-
    -
    -
    initMouseEvent(typeArg) -
    - Initializes attributes of a MouseEvent object. This - method has the same behavior as UIEvent.initUIEvent(). -

    The initMouseEvent method is deprecated, but - supported for backwards-compatibility with widely-deployed - implementations.

    -
    -
    DOMString typeArg -
    Refer to the initEvent() method for a description of this parameter. -
    boolean bubblesArg -
    Refer to the initEvent() method for a description of this parameter. -
    boolean cancelableArg -
    Refer to the initEvent() method for a description of this parameter. -
    Window? viewArg -
    Specifies view. This value MAY be null. -
    long detailArg -
    Specifies detail. -
    long screenXArg -
    Specifies screenX. -
    long screenYArg -
    Specifies screenY. -
    long clientXArg -
    Specifies clientX. -
    long clientYArg -
    Specifies clientY. -
    boolean ctrlKeyArg -
    Specifies ctrlKey. -
    boolean altKeyArg -
    Specifies altKey. -
    boolean shiftKeyArg -
    Specifies shiftKey. -
    boolean metaKeyArg -
    Specifies metaKey. -
    short buttonArg -
    Specifies button. -
    EventTarget? relatedTargetArg -
    Specifies relatedTarget. This value MAY - be null. -
    -
    -

    6. Security Considerations

    -

    TODO - Add specific concerns for this spec

    -

    7. Acknowledgements

    -

    TODO

    -

    8. Refs to other UIEvent specs [DELETE]

    -

    This section will be deleted.

    -

    Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references.

    -

    8.1. Things defined in other sections

    -

    8.1.1. Activation triggers and behavior

    -

    8.1.2. Composition Events

    -

    8.1.3. Default actions and cancelable events

    -

    8.1.4. Event dispatch and DOM event flow

    -

    8.1.5. Web browsers and other dynamic or interactive user agents

    -

    8.1.6. Authoring tools

    -

    8.2. Things defined in KeyboardEvents

    -

    8.2.1. Modifier keys

    -

    9. Glossary [DELETE]

    -

    This section will be deleted.

    -

    Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline.

    -
    -
    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 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 § 8.1.1 Activation triggers and behavior for more details.

    -
    activation trigger -
    -

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

    -
    body element -
    -

    In HTML or XHTML documents, the body element represents the contents of the -document. In a well-formed HTML document, the body element is a first -descendant of the root element.

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

    -
    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 preventDefault() method. For more details, see § 8.1.3 Default actions and cancelable events.

    -
    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 event -target. Each event is an instantiation of one specific event -type.

    -
    event target -
    -

    The object to which an event is targeted using the § 8.1.4 Event dispatch and DOM event flow. -The event target is the value of the target attribute.

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

    -
    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 graphical user -interfaces this is the element under the user’s pointing device. A user -interface’s hit testing facility is used to determine the target. For -specific details regarding hit testing and stacking order, refer to the host language.

    -
    un-initialized value -
    -

    The value of any event attribute (such as bubbles or currentTarget) before the event has been initialized with initEvent(). The un-initialized values of an event apply -immediately after a new event has been created using the method createEvent().

    -
    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 § 8.1.5 Web browsers and other dynamic or interactive user agents and § 8.1.6 Authoring tools for details on the -requirements for a conforming user agent.

    -
    Window -
    -

    The Window is the object referred to by the current document’s -browsing context’s Window Proxy object as defined in HTML5 [HTML5].

    -
    -
    -
    -

    Conformance

    -

    Document conventions

    -

    Conformance requirements are expressed - with a combination of descriptive assertions - and RFC 2119 terminology. - The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” - in the normative parts of this document - are to be interpreted as described in RFC 2119. - However, for readability, - these words do not appear in all uppercase letters in this specification.

    -

    All of the text of this specification is normative - except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

    -

    Examples in this specification are introduced with the words “for example” - or are set apart from the normative text - with class="example", - like this:

    -
    - -

    This is an example of an informative example.

    -
    -

    Informative notes begin with the word “Note” - and are set apart from the normative text - with class="note", - like this:

    -

    Note, this is an informative note.

    -
    -

    Conformant Algorithms

    -

    Requirements phrased in the imperative as part of algorithms - (such as "strip any leading space characters" - or "return false and abort these steps") - are to be interpreted with the meaning of the key word - ("must", "should", "may", etc) - used in introducing the algorithm.

    -

    Conformance requirements phrased as algorithms or specific steps - can be implemented in any manner, - so long as the end result is equivalent. - In particular, the algorithms defined in this specification - are intended to be easy to understand - and are not intended to be performant. - Implementers are encouraged to optimize.

    -
    -
    - -

    Index

    -

    Terms defined by this specification

    - -

    Terms defined by reference

    -
      -
    • - [] defines the following terms: -
        -
      • ancestor -
      • painting a stacking context -
      • positioned -
      • stacking context -
      -
    • - [CSS-DISPLAY-4] defines the following terms: -
        -
      • root element -
      -
    • - [DOM] defines the following terms: -
        -
      • Event -
      • EventTarget -
      • bubbles -
      • createEvent(interface) -
      • currentTarget -
      • document -
      • event listener -
      • initEvent(type) -
      • preventDefault() -
      • target -
      -
    • - [HTML] defines the following terms: -
        -
      • Window -
      -
    • - [POINTEREVENTS3] defines the following terms: -
        -
      • PointerEvent -
      -
    • - [UIEVENTS] defines the following terms: -
        -
      • KeyboardEvent -
      • UIEvent -
      • UIEventInit -
      • altKey -
      • ctrlKey -
      • detail -
      • getModifierState(keyArg) -
      • metaKey -
      • shiftKey -
      • view -
      -
    • - [WEBDRIVER-BIDI] defines the following terms: -
        -
      • event type -
      -
    • - [WEBIDL] defines the following terms: -
        -
      • DOMString -
      • Exposed -
      • boolean -
      • long -
      • short -
      • undefined -
      • unsigned short -
      -
    -

    References

    -

    Normative References

    -
    -
    [CSS-DISPLAY-4] -
    CSS Display Module Level 4 URL: https://drafts.csswg.org/css-display-4/ -
    [DOM] -
    Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/ -
    [HTML] -
    Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/ -
    [POINTEREVENTS3] -
    Patrick Lauke; Navid Zolghadr. Pointer Events. URL: https://w3c.github.io/pointerevents/ -
    [RFC2119] -
    S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119 -
    [UIEVENTS] -
    Gary Kacmarcik; Travis Leithead. UI Events. URL: https://w3c.github.io/uievents/ -
    [WEBDRIVER-BIDI] -
    WebDriver BiDi URL: https://w3c.github.io/webdriver-bidi/ -
    [WEBIDL] -
    Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/ -
    -

    Informative References

    -
    -
    [CSS2] -
    Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. URL: https://drafts.csswg.org/css2/ -
    [HTML401] -
    Dave Raggett; Arnaud Le Hors; Ian Jacobs. HTML 4.01 Specification. 27 March 2018. REC. URL: https://www.w3.org/TR/html401/ -
    [HTML5] -
    Ian Hickson; et al. HTML5. URL: https://www.w3.org/html/wg/drafts/html/master/ -
    [UIEvents-Key] -
    Gary Kacmarcik; Travis Leithead. UI Events KeyboardEvent key Values. URL: https://w3c.github.io/uievents-key/ -
    -

    IDL Index

    -
    [Exposed=Window]
-interface MouseEvent : UIEvent {
-  constructor(DOMString type, optional MouseEventInit eventInitDict = {});
-  readonly attribute long screenX;
-  readonly attribute long screenY;
-  readonly attribute long clientX;
-  readonly attribute long clientY;
-  readonly attribute long layerX;
-  readonly attribute long layerY;
-
-  readonly attribute boolean ctrlKey;
-  readonly attribute boolean shiftKey;
-  readonly attribute boolean altKey;
-  readonly attribute boolean metaKey;
-
-  readonly attribute short button;
-  readonly attribute unsigned short buttons;
-
-  readonly attribute EventTarget? relatedTarget;
-
-  boolean getModifierState(DOMString keyArg);
-};
-
-dictionary MouseEventInit : EventModifierInit {
-  long screenX = 0;
-  long screenY = 0;
-  long clientX = 0;
-  long clientY = 0;
-
-  short button = 0;
-  unsigned short buttons = 0;
-  EventTarget? relatedTarget = null;
-};
-
-dictionary EventModifierInit : 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;
-};
-
-partial interface MouseEvent {
-  // Deprecated in this specification
-  undefined initMouseEvent(DOMString typeArg,
-    optional boolean bubblesArg = false,
-    optional boolean cancelableArg = false,
-    optional Window? viewArg = null,
-    optional long detailArg = 0,
-    optional long screenXArg = 0,
-    optional long screenYArg = 0,
-    optional long clientXArg = 0,
-    optional long clientYArg = 0,
-    optional boolean ctrlKeyArg = false,
-    optional boolean altKeyArg = false,
-    optional boolean shiftKeyArg = false,
-    optional boolean metaKeyArg = false,
-    optional short buttonArg = 0,
-    optional EventTarget? relatedTargetArg = null);
-};
-
-
    - - - diff --git a/split/mouse-events.txt b/split/mouse-events.txt deleted file mode 100644 index 51b6f458..00000000 --- a/split/mouse-events.txt +++ /dev/null @@ -1,1916 +0,0 @@ -

    Mouse Events

    - -
    -Shortname: mouse-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
-	*** Mouse Events ***
-
-	Note: This is an experimental split of the UI Events spec into smaller, event-specific
-	specs. The split was made from an out-of-date snapshot, so the information here is not
-	current, so please focus on the overall structure rather than the specifics of the
-	content. If this experiment goes well, then we will split the current spec after all
-	outstanding pull requests have been handled.
-
    - -
    -urlPrefix: https://www.w3.org/TR/WebIDL/#idl-; type: type;
-	text: long
-urlPrefix: https://w3c.github.io/selection-api/#widl-Window-getSelection-Selection; type: dfn; for: Document
-	text: getSelection()
-url: https://www.w3.org/TR/2004/REC-xml-20040204/#NT-S; type: dfn;
-	text: white space
-url: https://www.w3.org/TR/uievents-key/#key-attribute-value; type: dfn; spec: uievents-key;
-	text: key attribute value
-url: https://www.w3.org/TR/uievents-key/#keys-modifier; type: dfn; spec: uievents-key;
-	text: modifier keys table
-url: https://html.spec.whatwg.org/multipage/forms.html#context-menus; type: dfn;
-	text: contextmenu
-url: https://www.w3.org/TR/pointerevents3/#pointerevent-interface; type: interface; spec: pointerevents3
-	text: PointerEvent
-url: https://dom.spec.whatwg.org/#concept-tree-ancestor; type: dfn;
-	text: ancestor
-url: https://www.w3.org/TR/CSS21/visuren.html#x43; type: dfn;
-	text: stacking context
-url: https://drafts.csswg.org/css-position-3/#positioned-box; type: dfn;
-	text: positioned
-url: https://drafts.csswg.org/css-position-4/#paint-a-stacking-context; type: dfn;
-	text: painting a stacking context
-
    - -
    -spec:dom; type:interface; text:Document
-spec:dom; type:dfn; for:Event; text:target
-spec:infra; type:dfn; text:code point
-
    - -

    Introduction

    - -

    Overview

    - - TODO. - -

    Conformance

    - - Boilerplate? - -

    Stylistic Conventions

    - -This specification follows the -Proposed W3C Specification Conventions, -with the following supplemental additions: - -

    This is a note.

    - - - -

    This is an open issue.

    - -

    This is a warning.

    - -
    -	  interface Example {
-	      // This is an IDL definition.
-	  };
-
    - -

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

    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 {{MouseEvent/clientX}} - and {{MouseEvent/clientY}} for calculation of other coordinates (such - as target coordinates exposed by DOM Level 0 implementations or - other proprietary attributes, e.g., pageX). -

    - -

    MouseEvent

    - - 
    -			[Exposed=Window]
-			interface MouseEvent : UIEvent {
-				constructor(DOMString type, optional MouseEventInit eventInitDict = {});
-				readonly attribute long screenX;
-				readonly attribute long screenY;
-				readonly attribute long clientX;
-				readonly attribute long clientY;
-				readonly attribute long layerX;
-				readonly attribute long layerY;
-
-				readonly attribute boolean ctrlKey;
-				readonly attribute boolean shiftKey;
-				readonly attribute boolean altKey;
-				readonly attribute boolean metaKey;
-
-				readonly attribute short button;
-				readonly attribute unsigned short buttons;
-
-				readonly attribute EventTarget? relatedTarget;
-
-				boolean getModifierState(DOMString keyArg);
-			};
-
    - -
    -
    screenX
    -
    - 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
    -
    - 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
    -
    - 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
    -
    - 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. -
    - -
    layerX
    -
    - The horizontal offset from the nearest ancestor element which - is a stacking context, is positioned, or paints in the - positioned phase when painting a stacking context. - - The un-initialized value of this attribute MUST be - 0. -
    - -
    layerY
    -
    - The vertical offset from the nearest ancestor element which - is a stacking context, is positioned, or paints in the - positioned phase when painting a stacking context. - - The un-initialized value of this attribute MUST be - 0. -
    - -
    ctrlKey
    -
    - Refer to the {{KeyboardEvent}}'s {{KeyboardEvent/ctrlKey}} attribute. - - The un-initialized value of this attribute MUST be - false. -
    - -
    shiftKey
    -
    - Refer to the {{KeyboardEvent}}'s {{KeyboardEvent/shiftKey}} attribute. - - The un-initialized value of this attribute MUST be - false. -
    - -
    altKey
    -
    - Refer to the {{KeyboardEvent}}'s {{KeyboardEvent/altKey}} attribute. - - The un-initialized value - of this attribute MUST be false. -
    - -
    metaKey
    -
    - Refer to the {{KeyboardEvent}}'s {{KeyboardEvent/metaKey}} attribute. - - The un-initialized value - of this attribute MUST be false. -
    - -
    button
    -
    - During mouse events caused by the depression or release of a mouse button, - {{MouseEvent/button}} MUST be used to indicate which pointer device button - changed state. - - The value of the {{MouseEvent/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 {{MouseEvent/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 EVENT{mousedown} and - EVENT{mouseup} depend on the specific mouse - button in use. -

    - - The un-initialized value - of this attribute MUST be 0. -
    - -
    buttons
    -
    - During any mouse events, {{MouseEvent/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 - {{MouseEvent/buttons}} attribute and the {{MouseEvent/button}} - attribute are very different. The value of {{MouseEvent/button}} - is assumed to be valid during EVENT{mousedown} / EVENT{mouseup} - event handlers, whereas the {{MouseEvent/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 {{MouseEvent/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 - EVENT{mousedown} and EVENT{mouseup} depend on the specific mouse - button in use. -

    - - The un-initialized value - of this attribute MUST be 0. -
    - -
    relatedTarget
    -
    - 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 {{KeyboardEvent/getModifierState()}} - method for a description of this parameter. -
    -
    -
    -
    - -

    MouseEventInit

    - - 
    -			dictionary MouseEventInit : EventModifierInit {
-				long screenX = 0;
-				long screenY = 0;
-				long clientX = 0;
-				long clientY = 0;
-
-				short button = 0;
-				unsigned short buttons = 0;
-				EventTarget? relatedTarget = null;
-			};
-
    - -
    -
    screenX
    -
    - Initializes the {{MouseEvent/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
    -
    - Initializes the {{MouseEvent/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
    -
    - Initializes the {{MouseEvent/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
    -
    - Initializes the {{MouseEvent/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
    -
    - Initializes the {{MouseEvent/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
    -
    - Initializes the {{MouseEvent/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 {{MouseEvent/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 - {{MouseEvent/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
    -
    - 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. -

    - -

    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 {{KeyboardEvent/getModifierState()}}. The steps for - constructing events using this dictionary are defined in the - event constructors section. - - 
    -		dictionary EventModifierInit : 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
    -
    - Initializes the ctrlKey attribute of the - {{MouseEvent}} or {{KeyboardEvent}} - objects to true if the KEYCAP{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 - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter KEYCAP{Control} - must return true. -
    - -
    shiftKey
    -
    - Initializes the shiftKey attribute of the - {{MouseEvent}} or {{KeyboardEvent}} - objects to true if the KEYCAP{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 - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter KEYCAP{Shift} must - return true. -
    - -
    altKey
    -
    - Initializes the altKey attribute of the - {{MouseEvent}} or {{KeyboardEvent}} - objects to true if the KEYCAP{Alt} - (alternative) (or KEYCAP{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 - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter KEYCAP{Alt} must - return true. -
    - -
    metaKey
    -
    - Initializes the metaKey attribute of the - {{MouseEvent}} or {{KeyboardEvent}} - objects to true if the KEYCAP{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 - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with either the parameter KEYCAP{Meta} - must return true. -
    - -
    modifierAltGraph
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter KEYCAP{AltGraph} must - return true. -
    - -
    modifierCapsLock
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter KEYCAP{CapsLock} must - return true. -
    - -
    modifierFn
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter KEYCAP{Fn} must - return true. -
    - -
    modifierFnLock
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter KEYCAP{FnLock} must - return true. -
    - -
    modifierHyper
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter KEYCAP{Hyper} must - return true. -
    - -
    modifierNumLock
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter KEYCAP{NumLock} must - return true. -
    - -
    modifierScrollLock
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter KEYCAP{ScrollLock} must - return true. -
    - -
    modifierSuper
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter KEYCAP{Super} must - return true. -
    - -
    modifierSymbol
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter KEYCAP{Symbol} must - return true. -
    - -
    modifierSymbolLock
    -
    - Initializes the event object's key modifier state such that calls to the - {{MouseEvent/getModifierState()}} or - {{KeyboardEvent/getModifierState()}} - when provided with the parameter KEYCAP{SymbolLock} must - return true. -
    -
    - -

    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 | - +---+------------+----o----+------------------------------------------+ - +| 1 | mousemove | | | - +| | | | Pointing device is moved into | - | | | | element A... | - +| 2 | mouseover | A | | - +| 3 | mouseenter | A | | - +| 4 | mousemove | A | Multiple EVENT{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 | - +----+------------+----o----+-----------------------------------------+ - +| 1 | mousemove | | | - +| | | | Pointing device is moved into | - | | | | element A... | - +| 2 | mouseover | A | | - +| 3 | mouseenter | A | | - +| 4 | mousemove | A | Multiple EVENT{mousemove} events | - +| | | | Pointing device is moved into | - | | | | nested element B... | - +| 5 | mouseout | A | | - +| 6 | mouseover | B | | - +| 7 | mouseenter | B | | - +| 8 | mousemove | B | Multiple EVENT{mousemove} events | - +| | | | Pointing device is moved from | - | | | | element B into A... | - +| 9 | mouseout | B | | - +| 10 | mouseleave | B | | - +| 11 | mouseover | A | | - +| 12 | mousemove | A | Multiple EVENT{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 | - +----+------------+----o----+-----------------------------------------+ - +| 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 EVENT{mousemove} events | - +| | | | Pointing device is moved out of | - | | | | element C... | - +| 7 | mouseout | C | | - +| 8 | mouseleave | C | | - +| 9 | mouseleave | B | | - +| 10 | mouseleave | A | | - ++----+------------+---------------------------------------------------+ - -

    - The EVENT{mouseover}/EVENT{mouseout} events are only fired once, while - EVENT{mouseenter}/EVENT{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 EVENT{mousemove} events - allowed between the EVENT{mousedown} and EVENT{mouseup} events while - still firing a EVENT{click} or EVENT{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 EVENT{click} and EVENT{dblclick} - events when the event target of the associated EVENT{mousedown} and - EVENT{mouseup} events is the same element with no EVENT{mouseout} or - EVENT{mouseleave} events intervening, and SHOULD fire EVENT{click} and - EVENT{dblclick} events on the nearest common inclusive ancestor when the - associated EVENT{mousedown} and EVENT{mouseup} event targets are - different. - -

    - If a EVENT{mousedown} event was targeted at an HTML document's body - element, and the corresponding EVENT{mouseup} event was targeted at - the root element, then the EVENT{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 - EVENT{mousedown} event, no events for that element will be dispatched - for EVENT{mouseup}, EVENT{click}, or EVENT{dblclick}, nor any default - activation events. However, the EVENT{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 EVENT{mouseup} event, the - EVENT{click} and subsequent events will not be dispatched. -

    - -

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

    auxclick

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| Type | auxclick | - +| Interface | {{PointerEvent}} | - +| Sync / Async | Sync | - +| Bubbles | Yes | - +| Trusted Targets | Element | - +| Cancelable | Yes | - +| Composed | Yes | - +| Default action | Varies | - +| Context
    |
      | - | (trusted events) |
    • {{Event}}.{{Event/target}} : topmost event target
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : indicates the | - | | current click count; the attribute value MUST | - | | be 1 when the user begins this action and increments by | - | | 1 for each click.
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if KEYCAP{Alt} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if KEYCAP{Control} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if KEYCAP{Shift} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if KEYCAP{Meta} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently | - | | depressed, 0 if no buttons pressed
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : null
      • | - | |
    • For {{PointerEvent}} specific attributes, see the [[!pointerevents3]] spec.
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - The EVENT{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 EVENT{auxclick} event should only be fired for the non-primary pointer - buttons (i.e., when {{MouseEvent/button}} value is not 0, - {{MouseEvent/buttons}} value is greater than 1). The primary button - (like the left button on a standard mouse) MUST NOT fire - EVENT{auxclick} events. See EVENT{click} for a corresponding event that - is associated with the primary button. - - The EVENT{auxclick} event MAY be preceded by the EVENT{mousedown} and - EVENT{mouseup} events on the same element, disregarding changes - between other node types (e.g., text nodes). Depending upon the - environment configuration, the EVENT{auxclick} event MAY be dispatched - if one or more of the event types EVENT{mouseover}, - EVENT{mousemove}, and EVENT{mouseout} occur between the press and - release of the pointing device button. - - The default action of the EVENT{auxclick} event type varies - based on the event target of the event and the value of the - {{MouseEvent/button}} or {{MouseEvent/buttons}} attributes. Typical - default actions of the EVENT{auxclick} event type are as follows: - - * If the event target has associated activation behavior, - the default action MUST be to execute that activation - behavior (see [[#event-flow-activation]]). - -

    - 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 EVENT{auxclick} event is dispatched after - any EVENT{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 auxclick 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. - } - }); - -

    - -

    click

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| Type | click | - +| Interface | {{PointerEvent}} | - +| Sync / Async | Sync | - +| Bubbles | Yes | - +| Trusted Targets | Element | - +| Cancelable | Yes | - +| Composed | Yes | - +| Default action | Varies | - +| Context
    |
      | - | (trusted events) |
    • {{Event}}.{{Event/target}} : topmost event target
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : indicates the | - | | current click count; the attribute value MUST | - | | be 1 when the user begins this action and increments by | - | | 1 for each click.
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if KEYCAP{Alt} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if KEYCAP{Control} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if KEYCAP{Shift} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if KEYCAP{Meta} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently | - | | depressed, 0 if no buttons pressed
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : null
      • | - | |
    • For {{PointerEvent}} specific attributes, see the [[!pointerevents3]] spec.
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - The EVENT{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 EVENT{click} event should only be fired for the primary pointer - button (i.e., when {{MouseEvent/button}} value is 0, - {{MouseEvent/buttons}} value is 1). Secondary buttons - (like the middle or right button on a standard mouse) MUST NOT fire - EVENT{click} events. See EVENT{auxclick} for a corresponding event that - is associated with the non-primary buttons. - - The EVENT{click} event MAY be preceded by the EVENT{mousedown} and - EVENT{mouseup} events on the same element, disregarding changes - between other node types (e.g., text nodes). Depending upon the - environment configuration, the EVENT{click} event MAY be dispatched - if one or more of the event types EVENT{mouseover}, - EVENT{mousemove}, and EVENT{mouseout} occur between the press and - release of the pointing device button. The EVENT{click} event MAY - also be followed by the EVENT{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 - EVENT{click} event (if it falls within the normal temporal - hysteresis for a EVENT{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 - EVENT{click} event type MUST be dispatched as part of an element - activation, as described in [[#event-flow-activation]]. - -

    - For maximum accessibility, content authors are encouraged to use the - EVENT{click} event type when defining activation behavior for custom - controls, rather than other pointing-device event types such as - EVENT{mousedown} or EVENT{mouseup}, which are more device-specific. - Though the EVENT{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 EVENT{click} event type varies - based on the event target of the event and the value of the - {{MouseEvent/button}} or {{MouseEvent/buttons}} attributes. Typical - default actions of the EVENT{click} event type are as follows: - - * If the event target has associated activation behavior, - the default action MUST be to execute that activation - behavior (see [[#event-flow-activation]]). - - * If the event target is focusable, the default - action MUST be to give that element document focus. - -

    contextmenu

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| Type | contextmenu | - +| Interface | {{PointerEvent}} | - +| Sync / Async | Sync | - +| Bubbles | Yes | - +| Trusted Targets | Element | - +| Cancelable | Yes | - +| Composed | Yes | - +| Default action | Invoke a context menu if supported. | - +| Context
    |
      | - | (trusted events) |
    • {{Event}}.{{Event/target}} : topmost event target
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if KEYCAP{Alt} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if KEYCAP{Control} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if KEYCAP{Shift} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if KEYCAP{Meta} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently | - | | depressed, 0 if no buttons pressed
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : null
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - A user agent MUST dispatch this event before invoking a context menu. - - When the EVENT{contextmenu} event is triggered by right mouse button, the - EVENT{contextmenu} event MUST be dispatched after the EVENT{mousedown} event. - -

    - Depending on the platform, the EVENT{contextmenu} event may be dispatched - before or after the EVENT{mouseup} event. -

    - -

    dblclick

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| Type | dblclick | - +| Interface | {{MouseEvent}} | - +| Sync / Async | Sync | - +| Bubbles | Yes | - +| Trusted Targets | Element | - +| Cancelable | Yes | - +| Composed | Yes | - +| Default action | None | - +| Context
    |
      | - | (trusted events) |
    • {{Event}}.{{Event/target}} : topmost event target
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : indicates the | - | | current click count
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if KEYCAP{Alt} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if KEYCAP{Control} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if KEYCAP{Shift} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if KEYCAP{Meta} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently | - | | depressed, 0 if no buttons pressed
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : null
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - 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 - EVENT{mousedown}, EVENT{mouseup}, and EVENT{dblclick}. This event - type MUST be dispatched after the event type EVENT{click} if a click - and double click occur simultaneously, and after the event type - EVENT{mouseup} otherwise. - - As with the EVENT{click} event, the EVENT{dblclick} event should - only be fired for the primary pointer button. Secondary buttons MUST - NOT fire EVENT{dblclick} events. - -

    - Canceling the EVENT{click} event does not affect the firing of a - EVENT{dblclick} event. -

    - - As with the EVENT{click} event type, the default action of - the EVENT{dblclick} event type varies based on the event - target of the event and the value of the {{MouseEvent/button}} - or {{MouseEvent/buttons}} attributes. The typical - default actions of the EVENT{dblclick} event type match those - of the EVENT{click} event type. - -

    mousedown

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| 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) |
    • {{Event}}.{{Event/target}} : topmost event target
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : indicates the | - | | current click count incremented by one. For | - | | example, if no click happened before the EVENT{mousedown}, {{UIEvent/detail}} | - | | will contain the value 1
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if KEYCAP{Alt} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if KEYCAP{Control} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if KEYCAP{Shift} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if KEYCAP{Meta} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently | - | | depressed, 0 if no buttons pressed
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : null
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - A user agent MUST dispatch this event when a pointing device - button is pressed over an element. - -

    - Many implementations use the EVENT{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 EVENT{mousedown} event is dispatched. -

    - -

    mouseenter

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| Type | mouseenter | - +| Interface | {{MouseEvent}} | - +| Sync / Async | Sync | - +| Bubbles | No | - +| Trusted Targets | Element | - +| Cancelable | No | - +| Composed | No | - +| Default action | None | - +| Context
    |
      | - | (trusted events) |
    • {{Event}}.{{Event/target}} : topmost event target
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if KEYCAP{Alt} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if KEYCAP{Control} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if KEYCAP{Shift} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if KEYCAP{Meta} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/button}} : 0
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently | - | | depressed, 0 if no buttons pressed
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the event target | - | | a pointing device is exiting, if any.
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - 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 EVENT{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 EVENT{mouseleave} event type. -

    - -

    mouseleave

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| Type | mouseleave | - +| Interface | {{MouseEvent}} | - +| Sync / Async | Sync | - +| Bubbles | No | - +| Trusted Targets | Element | - +| Cancelable | No | - +| Composed | No | - +| Default action | None | - +| Context
    |
      | - | (trusted events) |
    • {{Event}}.{{Event/target}} : topmost event target
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if KEYCAP{Alt} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if KEYCAP{Control} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if KEYCAP{Shift} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if KEYCAP{Meta} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/button}} : 0
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently | - | | depressed, 0 if no buttons pressed
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the event target | - | | a pointing device is exiting, if any.
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - 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 EVENT{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 EVENT{mouseenter} event type. -

    - -

    mousemove

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| Type | mousemove | - +| Interface | {{MouseEvent}} | - +| Sync / Async | Sync | - +| Bubbles | Yes | - +| Trusted Targets | Element | - +| Cancelable | Yes | - +| Composed | Yes | - +| Default action | None | - +| Context
    |
      | - | (trusted events) |
    • {{Event}}.{{Event/target}} : topmost event target
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if KEYCAP{Alt} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if KEYCAP{Control} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if KEYCAP{Shift} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if KEYCAP{Meta} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/button}} : 0
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently | - | | depressed, 0 if no buttons pressed
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : null
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - 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 EVENT{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, - EVENT{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, but was changed to reflect existing interoperability between - user agents. -

    - -

    mouseout

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| Type | mouseout | - +| Interface | {{MouseEvent}} | - +| Sync / Async | Sync | - +| Bubbles | Yes | - +| Trusted Targets | Element | - +| Cancelable | Yes | - +| Composed | Yes | - +| Default action | None | - +| Context
    |
      | - | (trusted events) |
    • {{Event}}.{{Event/target}} : topmost event target
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if KEYCAP{Alt} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if KEYCAP{Control} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if KEYCAP{Shift} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if KEYCAP{Meta} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/button}} : 0
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently | - | | depressed, 0 if no buttons pressed
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the event target | - | | a pointing device is entering, if any.
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - 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 EVENT{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 EVENT{mouseover} event type. -

    - -

    mouseover

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| Type | mouseover | - +| Interface | {{MouseEvent}} | - +| Sync / Async | Sync | - +| Bubbles | Yes | - +| Trusted Targets | Element | - +| Cancelable | Yes | - +| Composed | Yes | - +| Default action | None | - +| Context
    |
      | - | (trusted events) |
    • {{Event}}.{{Event/target}} : topmost event target
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if KEYCAP{Alt} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if KEYCAP{Control} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if KEYCAP{Shift} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if KEYCAP{Meta} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/button}} : 0
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently | - | | depressed, 0 if no buttons pressed
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the event target | - | | a pointing device is entering, if any.
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - 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 EVENT{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 EVENT{mouseout} event type. -

    - -

    mouseup

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| Type | mouseup | - +| Interface | {{MouseEvent}} | - +| Sync / Async | Sync | - +| Bubbles | Yes | - +| Trusted Targets | Element | - +| Cancelable | Yes | - +| Composed | Yes | - +| Default action | None | - +| Context
    |
      | - | (trusted events) |
    • {{Event}}.{{Event/target}} : topmost event target
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : indicates the | - | | current click count incremented by one.
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on | - | | the screen
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position | - | | within the viewport
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position | - | | within the containing element
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if KEYCAP{Alt} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if KEYCAP{Control} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if KEYCAP{Shift} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if KEYCAP{Meta} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently | - | | depressed, 0 if no buttons pressed
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : null
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - A user agent MUST dispatch this event when a pointing device - button is released over an element. - -

    - In some implementation environments, such as a browser, a - EVENT{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. -

    - -

    Constructing Mouse and Keyboard Events

    - - Generally, when a constructor of an {{Event}} interface, or of an interface - inherited from the {{Event}} interface, is invoked, the steps described in - [[!DOM]] should be followed. However the {{KeyboardEvent}} and - {{MouseEvent}} interfaces provide additional dictionary members for - initializing the internal state of the {{Event}} object's key modifiers: - specifically, the internal state queried for using the - {{KeyboardEvent/getModifierState()}} and {{MouseEvent/getModifierState()}} - methods. This section supplements the DOM4 steps for intializing a new - {{Event}} object with these optional modifier states. - - For the purposes of constructing a {{KeyboardEvent}}, {{MouseEvent}}, or - object derived from these objects using the algorithm below, all - {{KeyboardEvent}}, {{MouseEvent}}, and derived objects have - internal key modifier state which can be set and - retrieved using the key modifier names - described in the - Modifier Keys table - in [[UIEvents-Key]]. - - The following steps supplement the algorithm defined for constructing - events in DOM4: - - * If the {{Event}} being constructed is a {{KeyboardEvent}} or - {{MouseEvent}} object or an object that derives from either of these, - and a {{EventModifierInit}} argument was provided to the constructor, - then run the following sub-steps: - - * For each {{EventModifierInit}} argument, if the dictionary member - begins with the string "modifier", then let the - key modifier name be the - dictionary member's name excluding the prefix - "modifier", and set the {{Event}} object's - internal key modifier state - that matches the key modifier name - to the corresponding value. - -

    Legacy Event Initializers

    - - This section is normative. - - The following features are obsolete and should only be implemented by - user agents that require compatibility with legacy software. - - Early versions of this specification included an initialization method on - the interface (for example initMouseEvent) that required a long - list of parameters that, in most cases, did not fully initialize all - attributes of the event object. Because of this, event interfaces which were - derived from the basic {{Event}} interface required that the initializer of - each of the derived interfaces be called explicitly in order to - fully initialize an event. - -
    - Initializing all the attributes of a UIEvent requires calls to two - initializer methods: initEvent and - initUIEvent. -
    - - Due in part to the length of time in the development of this standard, some - implementations MAY have taken a dependency on these (now deprecated) - initializer methods. For completeness, these legacy event initializers are - described in this section. - -

    Initializers for interface MouseEvent

    - - This section is informative - - 
    -		partial interface MouseEvent {
-			// Deprecated in this specification
-			undefined initMouseEvent(DOMString typeArg,
-				optional boolean bubblesArg = false,
-				optional boolean cancelableArg = false,
-				optional Window? viewArg = null,
-				optional long detailArg = 0,
-				optional long screenXArg = 0,
-				optional long screenYArg = 0,
-				optional long clientXArg = 0,
-				optional long clientYArg = 0,
-				optional boolean ctrlKeyArg = false,
-				optional boolean altKeyArg = false,
-				optional boolean shiftKeyArg = false,
-				optional boolean metaKeyArg = false,
-				optional short buttonArg = 0,
-				optional EventTarget? relatedTargetArg = null);
-		};
-
    - -
    -
    initMouseEvent(typeArg)
    -
    - Initializes attributes of a {{MouseEvent}} object. This - method has the same behavior as UIEvent.initUIEvent(). - -

    - The initMouseEvent method is deprecated, but - supported for backwards-compatibility with widely-deployed - implementations. -

    - -
    -
    DOMString typeArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    boolean bubblesArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    boolean cancelableArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    Window? viewArg
    -
    - Specifies {{UIEvent/view}}. This value MAY be null. -
    - -
    long detailArg
    -
    - Specifies {{UIEvent/detail}}. -
    - -
    long screenXArg
    -
    - Specifies {{MouseEvent/screenX}}. -
    - -
    long screenYArg
    -
    - Specifies {{MouseEvent/screenY}}. -
    - -
    long clientXArg
    -
    - Specifies {{MouseEvent/clientX}}. -
    - -
    long clientYArg
    -
    - Specifies {{MouseEvent/clientY}}. -
    - -
    boolean ctrlKeyArg
    -
    - Specifies {{MouseEvent/ctrlKey}}. -
    - -
    boolean altKeyArg
    -
    - Specifies {{MouseEvent/altKey}}. -
    - -
    boolean shiftKeyArg
    -
    - Specifies {{MouseEvent/shiftKey}}. -
    - -
    boolean metaKeyArg
    -
    - Specifies {{MouseEvent/metaKey}}. -
    - -
    short buttonArg
    -
    - Specifies {{MouseEvent/button}}. -
    - -
    EventTarget? relatedTargetArg
    -
    - Specifies {{MouseEvent/relatedTarget}}. This value MAY - be null. -
    -
    -
    -
    - -

    Security Considerations

    - - TODO - Add specific concerns for this spec - -

    Acknowledgements

    - - TODO - -

    Refs to other UIEvent specs \[DELETE]

    - - This section will be deleted. - - Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references. - -

    Things defined in other sections

    - -

    Activation triggers and behavior

    -

    Composition Events

    -

    Default actions and cancelable events

    -

    Event dispatch and DOM event flow

    -

    Web browsers and other dynamic or interactive user agents

    -

    Authoring tools

    - -

    Things defined in KeyboardEvents

    -

    Modifier keys

    - -

    Glossary \[DELETE]

    - -This section will be deleted. - -Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline. - -: 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 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 - [[#event-flow-activation]] for more details. - -: activation trigger -:: An event which is defined to initiate an activation behavior. Refer - to [[#event-flow-activation]] for more details. - -: body element -:: In HTML or XHTML documents, the body element represents the contents of the - document. In a well-formed HTML document, the body element is a first - descendant of the root element. - -: 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. - -: 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 - [[#event-flow-default-cancel]]. - -: 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 event - target. Each event is an instantiation of one specific event - type. - -: event target -:: The object to which an event is targeted using the [[#event-flow]]. - The event target is the value of the {{Event/target}} attribute. - -: 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 UI 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. - -: 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 graphical user - interfaces this is the element under the user's pointing device. A user - interface's hit testing facility is used to determine the target. For - specific details regarding hit testing and stacking order, refer to the - host language. - -: un-initialized value -:: The value of any event attribute (such as {{Event/bubbles}} or - {{Event/currentTarget}}) before the event has been initialized with - {{Event/initEvent()}}. The un-initialized values of an event apply - immediately after a new event has been created using the method - {{Document/createEvent()}}. - -: 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 [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the - requirements for a conforming user agent. - -: Window -:: The Window is the object referred to by the current document's - browsing context's Window Proxy object as defined in - HTML5 - [[HTML5]]. - diff --git a/split/ui-events.bs b/split/ui-events.bs deleted file mode 100644 index b66cde19..00000000 --- a/split/ui-events.bs +++ /dev/null @@ -1,884 +0,0 @@ -

    UI Events

    - -
    -Shortname: uievents-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
-	*** UI Events (core) ***
-
-	Note: This is an experimental split of the UI Events spec into smaller, event-specific
-	specs. The split was made from an out-of-date snapshot, so the information here is not
-	current, so please focus on the overall structure rather than the specifics of the
-	content. If this experiment goes well, then we will split the current spec after all
-	outstanding pull requests have been handled.
-
    - -
    -urlPrefix: https://www.w3.org/TR/WebIDL/#idl-; type: type;
-	text: long
-urlPrefix: https://w3c.github.io/selection-api/#widl-Window-getSelection-Selection; type: dfn; for: Document
-	text: getSelection()
-url: https://www.w3.org/TR/2004/REC-xml-20040204/#NT-S; type: dfn;
-	text: white space
-url: https://www.w3.org/TR/uievents-key/#key-attribute-value; type: dfn; spec: uievents-key;
-	text: key attribute value
-url: https://www.w3.org/TR/uievents-key/#keys-modifier; type: dfn; spec: uievents-key;
-	text: modifier keys table
-url: https://html.spec.whatwg.org/multipage/forms.html#context-menus; type: dfn;
-	text: contextmenu
-url: https://www.w3.org/TR/pointerevents3/#pointerevent-interface; type: interface; spec: pointerevents3
-	text: PointerEvent
-url: https://dom.spec.whatwg.org/#concept-tree-ancestor; type: dfn;
-	text: ancestor
-url: https://www.w3.org/TR/CSS21/visuren.html#x43; type: dfn;
-	text: stacking context
-url: https://drafts.csswg.org/css-position-3/#positioned-box; type: dfn;
-	text: positioned
-url: https://drafts.csswg.org/css-position-4/#paint-a-stacking-context; type: dfn;
-	text: painting a stacking context
-
    - -
    -spec:dom; type:interface; text:Document
-spec:dom; type:dfn; for:Event; text:target
-spec:infra; type:dfn; text:code point
-
    - -

    Introduction

    - -

    Overview

    - - TODO. - -

    Conformance

    - - Boilerplate? - -

    Stylistic Conventions

    - -This specification follows the -Proposed W3C Specification Conventions, -with the following supplemental additions: - -

    This is a note.

    - - - -

    This is an open issue.

    - -

    This is a warning.

    - -
    -	  interface Example {
-	      // This is an IDL definition.
-	  };
-
    - -

    User Interface Events

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

    - -

    UIEvent

    - - 
    -			[Exposed=Window]
-			interface UIEvent : Event {
-				constructor(DOMString type, optional UIEventInit eventInitDict = {});
-				readonly attribute Window? view;
-				readonly attribute long 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. -
    -
    - -

    UIEventInit

    - - 
    -			dictionary UIEventInit : 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. -
    -
    - -

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

    load

    - - - - - - - - - - -
    Typeload
    Interface{{UIEvent}} if generated from a user interface, {{Event}} otherwise.
    Sync / AsyncAsync
    BubblesNo
    Trusted TargetsWindow, Document, Element
    CancelableNo
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : common object whose contained resources have loaded
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    - - 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. -

    - -

    unload

    - - - - - - - - - - -
    Typeunload
    Interface{{UIEvent}} if generated from a user interface, {{Event}} otherwise.
    Sync / AsyncSync
    BubblesNo
    Trusted TargetsWindow, Document, Element
    CancelableNo
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : common object whose contained resources have been removed
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    - - 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. - -

    abort

    - - - - - - - - - - -
    Typeabort
    Interface{{UIEvent}} if generated from a user interface, {{Event}} otherwise.
    Sync / AsyncSync
    BubblesNo
    Trusted TargetsWindow, Element
    CancelableNo
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : element whose resources have been stopped from loading without error
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    - - 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. - -

    error

    - - - - - - - - - - -
    Typeerror
    Interface{{UIEvent}} if generated from a user interface, {{Event}} otherwise.
    Sync / AsyncAsync
    BubblesNo
    Trusted TargetsWindow, Element
    CancelableNo
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : element whose resources have been stopped from loading due to error
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    - - 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. - -

    select

    - - - - - - - - - - -
    Typeselect
    Interface{{UIEvent}} if generated from a user interface, {{Event}} otherwise.
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableNo
    Default actionNone
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : element whose text content has been selected
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    - - 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. -

    - -

    Extending Events

    - - -This section is non-normative - -

    Introduction

    - - This specification defines several interfaces and many events, however, this - is not an exhaustive set of events for all purposes. To allow content - authors and implementers to add desired functionality, this specification - provides two mechanisms for extend this set of interfaces and events without - creating conflicts: custom - events and implementation-specific - extensions. - -

    Custom Events

    - - A script author MAY wish to define an application in terms of functional - components, with event types that are meaningful to the application - architecture. The content author can use the {{CustomEvent}} interface to - create their own events appropriate to the level of abstraction they are - using. - -
    - A content author might have created an application which features a - dynamically generated bar chart. This bar chart is meant to be updated every - 5 minutes, or when a feed shows new information, or when the user refreshes - it manually by clicking a button. There are several handlers that have to be - called when the chart needs to be updated: the application has to fetch the - most recent data, show an icon to the user that the event is being updated, - and rebuild the chart. To manage this, the content author can choose to - create a custom updateChart event, which is fired whenever one of the - trigger conditions is met: - - 
    
-		var chartData = ...;
-		var evt = document.createEvent("CustomEvent");
-		evt.initCustomEvent( "updateChart", true, false, { data: chartData });
-		document.documentElement.dispatchEvent(evt);
-
    -
    - -

    Implementation-Specific Extensions

    - - While a new event is being designed and prototyped, or when an event is - intended for implementation-specific functionality, it is desirable to - distinguish it from standardized events. Implementors SHOULD prefix event - types specific to their implementations with a short string to distinguish - it from the same event in other implementations and from standardized - events. This is similar to the - vendor-specific keyword prefixes - in CSS, though without the dashes ("-") used in CSS, since that - can cause problems when used as an attribute name in Javascript. - -
    - A particular browser vendor, FooCorp, might wish to introduce a - new event, jump. This vendor implements - fooJump in their browser, using their - vendor-specific prefix: "foo". Early adopters start - experimenting with the event, using - someElement.addEventListener("fooJump", doJump, false ), - and provide feedback to FooCorp, who change the behavior of fooJump accordingly. - - After some time, another vendor, BarOrg, decides they also want - the functionality, but implement it slightly differently, so they use - their own vendor-specific prefix, "bar" in their event type - name: barJump. Content authors - experimenting with this version of the jump event type register events with BarOrg's - event type name. Content authors who wish to write code that accounts - for both browsers can either register each event type separately with - specific handlers, or use the same handler and switch on the name of the - event type. Thus, early experiments in different codebases do not - conflict, and the early adopter is able to write easily-maintained code - for multiple implementations. - - Eventually, as the feature matures, the behavior of both browsers - stabilizes and might converge due to content author and user feedback or - through formal standardization. As this stabilization occurs, and risk - of conflicts decrease, content authors can remove the forked code, and - use the jump event type name (even before - it is formally standardized) using the same event handler and the more - generic registration method someElement.addEventListener( "jump", - doJump, false). -
    - -

    Known Implementation-Specific Prefixes

    - - At the time of writing, the following event-type name prefixes are known to exist: - - - - - - - -
    PrefixWeb EngineOrganization
    moz, MozGeckoMozilla
    ms, MSTridentMicrosoft
    o, OPrestoOpera Software
    webkitWebKitApple, Google, others
    - -

    Legacy {{UIEvent}} events

    - -

    Legacy {{UIEvent}} event types

    - -

    DOMActivate

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    TypeDOMActivate
    Interface{{UIEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    ComposedYes
    Default actionNone
    Context
    (trusted events)    		 -
      -
    • {{Event}}.{{Event/target}} : - element being activated
      • -
    • {{UIEvent}}.{{UIEvent/view}} : - Window
      • -
    • {{UIEvent}}.{{UIEvent/detail}} : - 0
      • -
    -
    - - A user agent MUST dispatch this event when a button, link, or - other state-changing element is activated. Refer to - [[#event-flow-activation]] for more details. - -

    - The DOMActivate event type is defined in this - specification for reference and completeness, but this specification - deprecates the use of this event type in favor of the related - event type click. Other specifications MAY define and - maintain their own DOMActivate event type for backwards - compatibility. -

    - -

    - While DOMActivate and click are not completely equivalent, - implemented behavior for the click event type has - developed to encompass the most critical accessibility aspects for which - the DOMActivate event type was designed, and is more - widely implemented. Content authors are encouraged to use the - click event type rather than the related mousedown - or mouseup event type to ensure maximum accessibility. -

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

    - The DOMActivate event type is REQUIRED to be supported for - XForms [[XFORMS11]], 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 a user agent - conforming to UI Events, 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 event target - has a DOMActivate event listener registered. -

    -
    - -

    - Don't rely upon the interoperable support of DOMActivate in many - user agents. Instead, the click event type should - be used since it will provide more accessible behavior due to broader - implementation support. -

    - -

    - The DOMActivate event type is deprecated in this - specification. -

    - -

    Activation event order

    - - If the DOMActivate event is supported by the user - agent, then the events MUST be dispatched in a set order relative to - each other: (with only pertinent events listed): - - - - - - -
    Event TypeNotes
    1click
    2DOMActivatedefault action, if supported by the user agent; synthesized; isTrusted="true"
    3All other default actions, including the activation behavior
    - - If the focused element is activated by a key event, then the following - shows the typical sequence of events (with only pertinent events listed): - - - - - - - -
    Event TypeNotes
    1keydownMUST be a key which can activate the element, such as the Enter or    (spacebar) key, or the element is not activated
    2clickdefault action; synthesized; isTrusted="true"
    3DOMActivatedefault action, if supported by the user agent; synthesized; isTrusted="true"
    4All other default actions, including the activation behavior
    - - -

    Legacy Event Initializers

    - - This section is normative. - - The following features are obsolete and should only be implemented by - user agents that require compatibility with legacy software. - - Early versions of this specification included an initialization method on - the interface (for example initMouseEvent) that required a long - list of parameters that, in most cases, did not fully initialize all - attributes of the event object. Because of this, event interfaces which were - derived from the basic {{Event}} interface required that the initializer of - each of the derived interfaces be called explicitly in order to - fully initialize an event. - -
    - Initializing all the attributes of a UIEvent requires calls to two - initializer methods: initEvent and - initUIEvent. -
    - - Due in part to the length of time in the development of this standard, some - implementations MAY have taken a dependency on these (now deprecated) - initializer methods. For completeness, these legacy event initializers are - described in this section. - -

    Initializers for interface UIEvent

    - - This section is informative - - 
    -		partial interface UIEvent {
-			// Deprecated in this specification
-			undefined initUIEvent(DOMString typeArg,
-				optional boolean bubblesArg = false,
-				optional boolean cancelableArg = false,
-				optional Window? viewArg = null,
-				optional long detailArg = 0);
-		};
-
    - -
    -
    initUIEvent(typeArg)
    -
    - Initializes attributes of an {{UIEvent}} object. - This method has the same behavior as {{Event/initEvent()}}. - -

    - The initUIEvent method is deprecated, but - supported for backwards-compatibility with widely-deployed - implementations. -

    - -
    -
    DOMString typeArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    boolean bubblesArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    boolean cancelableArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    Window? viewArg
    -
    - Specifies {{UIEvent/view}}. This value MAY be null. -
    - -
    long detailArg
    -
    - Specifies {{UIEvent/detail}}. -
    -
    -
    -
    - -

    Security Considerations

    - - This appendix discusses security considerations for UI Events implementations. - The discussion is limited to security issues that arise directly from - implementation of the event model, APIs and events defined in this - specification. Implementations typically support other features like scripting - languages, other APIs and additional events not defined in this document. These - features constitute an unknown factor and are out of scope of this document. - Implementers SHOULD consult the specifications of such features for their - respective security considerations. - - Many of the event types defined in this specification are dispatched in response - to user actions. This allows malicious event listeners to gain access to - information users would typically consider confidential, e.g., typos they might - have made when filling out a form, if they reconsider their answer to a multiple - choice question shortly before submitting a form, their typing rate or primary - input mechanism. In the worst case, malicious event listeners could capture all - user interactions and submit them to a third party through means (not defined in - this specification) that are generally available in DOM implementations, such as - the XMLHttpRequest interface. - - In DOM implementations that support facilities to load external data, events - like the error event can provide access to sensitive information about - the environment of the computer system or network. An example would be a - malicious HTML document that attempts to embed a resource on the local network - or the localhost on different ports. An embedded DOM application could - then listen for error and load events to determine which other - computers in a network are accessible from the local system or which ports are - open on the system to prepare further attacks. - - An implementation of UI Events alone is generally insufficient to perform - attacks of this kind and the security considerations of the facilities that - possibly support such attacks apply. For conformance with this specification, - DOM implementations MAY take reasonable steps to ensure that DOM - applications do not get access to confidential or sensitive information. For - example, they might choose not to dispatch load events to nodes that - attempt to embed resources on the local network. - -

    Acknowledgements

    - - Many people contributed to the DOM specifications (Level 1, 2 or 3), - including participants of the DOM Working Group, the DOM Interest Group, - the WebAPI Working Group, and the WebApps Working Group. - - We especially thank the following: - Andrew Watson (Object Management Group), - Andy Heninger (IBM), - Angel Diaz (IBM), - Anne van Kesteren (Opera Software), - Arnaud Le Hors (W3C and IBM), - Arun Ranganathan (AOL), - Ashok Malhotra (IBM and Microsoft), - Ben Chang (Oracle), - Bill Shea (Merrill Lynch), - Bill Smith (Sun), - Björn Höhrmann, - Bob Sutor (IBM), - Charles McCathie-Nevile (Opera Software, Co-Chair), - Chris Lovett (Microsoft), - Chris Wilson (Microsoft), - Christophe Jolif (ILOG), - David Brownell (Sun), - David Ezell (Hewlett-Packard Company), - David Singer (IBM), - Dean Jackson (W3C, W3C Team Contact), - Dimitris Dimitriadis (Improve AB and invited expert), - Don Park (invited), - Doug Schepers (Vectoreal), - Elena Litani (IBM), - Eric Vasilik (Microsoft), - Gavin Nicol (INSO), - Gorm Haug Eriksen (Opera Software), - Ian Davis (Talis Information Limited), - Ian Hickson (Google), - Ian Jacobs (W3C), - James Clark (invited), - James Davidson (Sun), - Jared Sorensen (Novell), - Jeroen van Rotterdam (X-Hive Corporation), - Joe Kesselman (IBM), - Joe Lapp (webMethods), - Joe Marini (Macromedia), - John Robinson (AOL), - Johnny Stenback (Netscape/AOL), - Jon Ferraiolo (Adobe), - Jonas Sicking (Mozilla Foundation), - Jonathan Marsh (Microsoft), - Jonathan Robie (Texcel Research and Software AG), - Kim Adamson-Sharpe (SoftQuad Software Inc.), - Lauren Wood (SoftQuad Software Inc., former Chair), - Laurence Cable (Sun), - Luca Mascaro (HTML Writers Guild), - Maciej Stachowiak (Apple Computer), - Marc Hadley (Sun Microsystems), - Mark Davis (IBM), - Mark Scardina (Oracle), - Martin Dürst (W3C), - Mary Brady (NIST), - Michael Shenfield (Research In Motion), - Mick Goulish (Software AG), - Mike Champion (Arbortext and Software AG), - Miles Sabin (Cromwell Media), - Patti Lutsky (Arbortext), - Paul Grosso (Arbortext), - Peter Sharpe (SoftQuad Software Inc.), - Phil Karlton (Netscape), - Philippe Le Hégaret (W3C, W3C Team Contact and former Chair), - Ramesh Lekshmynarayanan (Merrill Lynch), - Ray Whitmer (iMall, Excite@Home, and Netscape/AOL, Chair), - Rezaur Rahman (Intel), - Rich Rollman (Microsoft), - Rick Gessner (Netscape), - Rick Jelliffe (invited), - Rob Relyea (Microsoft), - Robin Berjon (Expway, Co-Chair), - Scott Hayman (Research In Motion), - Scott Isaacs (Microsoft), - Sharon Adler (INSO), - Stéphane Sire (IntuiLab), - Steve Byrne (JavaSoft), - Tim Bray (invited), - Tim Yu (Oracle), - Tom Pixley (Netscape/AOL), - T.V. Raman (Google). - Vidur Apparao (Netscape) and - Vinod Anupam (Lucent). - - Former editors: - Tom Pixley (Netscape Communications Corporation) until July 2002; - Philippe Le Hégaret (W3C) until November 2003; - Björn Höhrmann (Invited Expert) until January 2008; - and Jacob Rossi (Microsoft) from March 2011 to October 2011. - - Contributors: - In the WebApps Working Group, the following people made substantial - material contributions in the process of refining and revising this - specification: - Bob Lund (Cable Laboratories), - Cameron McCormack (Invited Expert / Mozilla), - Daniel Danilatos (Google), - Gary Kacmarcik (Google), - Glenn Adams (Samsung), - Hallvord R. M. Steen (Opera), - Hironori Bono (Google), - Mark Vickers (Comcast), - Masayuki Nakano (Mozilla), - Olli Pettay (Mozilla), - Takayoshi Kochi (Google) and - Travis Leithead (Microsoft). - - Glossary contributors: - Arnaud Le Hors (W3C) and - Robert S. Sutor (IBM Research). - - Test suite contributors: - Carmelo Montanez (NIST), - Fred Drake, - Mary Brady (NIST), - Neil Delima (IBM), - Rick Rivello (NIST), - Robert Clary (Netscape), - with a special mention to Curt Arnold. - - Thanks to all those who have helped to improve this specification by - sending suggestions and corrections (please, keep bugging us with your - issues!), or writing informative books or Web sites: - Al Gilman, - Alex Russell, - Alexander J. Vincent, - Alexey Proskuryakov, - Arkadiusz Michalski, - Brad Pettit, - Cameron McCormack, - Chris Rebert, - Curt Arnold, - David Flanagan, - Dylan Schiemann, - Erik Arvidsson, - Garrett Smith, - Giuseppe Pascale, - James Su, - Jan Goyvaerts (regular-expressions.info), - Jorge Chamorro, - Kazuyuki Ashimura, - Ken Rehor, - Magnus Kristiansen, - Martijn Wargers, - Martin Dürst, - Michael B. Allen, - Mike Taylor, - Misha Wolf, - Ojan Vafai, - Oliver Hunt, - Paul Irish, - Peter-Paul Koch, - Richard Ishida, - Sean Hogan, - Sergey Ilinsky, - Sigurd Lerstad, - Steven Pemberton, - Tony Chang, - William Edney and - Øistein E. Andersen. - -

    Refs to other UIEvent specs \[DELETE]

    - - This section will be deleted. - - Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references. - -

    Things defined in other sections

    - -

    Activation triggers and behavior

    -

    Composition Events

    -

    Default actions and cancelable events

    -

    Event dispatch and DOM event flow

    -

    Focus Events

    -

    Web browsers and other dynamic or interactive user agents

    -

    Authoring tools

    - - Add references to these events so that the linker doesn't complain about exporting them. - - unload, load, abort, error - - -

    Glossary \[DELETE]

    - -This section will be deleted. - -Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline. - -: 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 UI Events, and they integrate and extend the objects - and models defined in this specification. - -: un-initialized value -:: The value of any event attribute (such as {{Event/bubbles}} or - {{Event/currentTarget}}) before the event has been initialized with - {{Event/initEvent()}}. The un-initialized values of an event apply - immediately after a new event has been created using the method - {{Document/createEvent()}}. - -: 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 [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the - requirements for a conforming user agent. - -: Window -:: The Window is the object referred to by the current document's - browsing context's Window Proxy object as defined in - HTML5 - [[HTML5]]. - diff --git a/split/ui-events.html b/split/ui-events.html deleted file mode 100644 index 54efd7a8..00000000 --- a/split/ui-events.html +++ /dev/null @@ -1,1615 +0,0 @@ - - - - - UI Events - - - - - - - - - - - - - - - - -
    -

    -

    UI Events

    -

    Editor’s Draft,

    -
    - More details about this document -
    -
    -
    This version: -
    https://w3c.github.io/uievents/ -
    Latest published version: -
    https://www.w3.org/TR/uievents/ -
    Feedback: -
    GitHub -
    Editors: -
    (Google) -
    (Microsoft) -
    Former Editor: -
    Doug Schepers (Mar 2008 - May 2011) -
    Tests: -
    web-platform-tests uievents/ (ongoing work) -
    -
    -
    -
    -

    Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

    -
    -
    -
    -

    Abstract

    -

    *** UI Events (core) ***

    -

    Note: This is an experimental split of the UI Events spec into smaller, event-specific - - specs. The split was made from an out-of-date snapshot, so the information here is not - current, so please focus on the overall structure rather than the specifics of the - content. If this experiment goes well, then we will split the current spec after all - outstanding pull requests have been handled.

    -
    -

    Status of this document

    -
    -

    This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

    -

    This document was published by the Web Applications Working Group as an Editors Draft. This document is intended to become a W3C Recommendation.

    -

    -

    This document was published by the Web Applications Working Group as a Working Draft. - - Feedback and comments on this specification are welcome. Please use GitHub issues Historical discussions can be found in the public-webapps@w3.org archives.

    -

    Publication as an Editors Draft does not imply endorsement by W3C and its Members. This is a draft document and may - be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite - this document as other than work in progress.

    -

    This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

    -

    This document is governed by the 2 November 2021 W3C Process Document.

    -
    -
    - -
    -

    1. Introduction

    -

    2. Overview

    -

    TODO.

    -

    3. Conformance

    -

    Boilerplate?

    -

    4. Stylistic Conventions

    -

    This specification follows the Proposed W3C Specification Conventions, -with the following supplemental additions:

    -

    This is a note.

    -

    This is an open issue.

    -

    This is a warning.

    -
    interface Example {
-    // This is an IDL definition.
-};
-
    -

    5. User Interface Events

    -

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

    -

    5.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. UIEvent

    -
    [Exposed=Window]
-interface UIEvent : Event {
-  constructor(DOMString type, optional UIEventInit eventInitDict = {});
-  readonly attribute Window? view;
-  readonly attribute long 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.2. UIEventInit

    -
    dictionary UIEventInit : 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.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.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.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.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.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.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.

    -

    6. Legacy Event Initializers

    -

    This section is normative.

    -

    The following features are obsolete and should only be implemented by user agents that require compatibility with legacy software.

    -

    Early versions of this specification included an initialization method on - the interface (for example initMouseEvent) that required a long - list of parameters that, in most cases, did not fully initialize all - attributes of the event object. Because of this, event interfaces which were - derived from the basic Event interface required that the initializer of each of the derived interfaces be called explicitly in order to - fully initialize an event.

    -
    Initializing all the attributes of a UIEvent requires calls to two - initializer methods: initEvent and initUIEvent.
    -

    Due in part to the length of time in the development of this standard, some - implementations MAY have taken a dependency on these (now deprecated) - initializer methods. For completeness, these legacy event initializers are - described in this section.

    -

    6.1. Initializers for interface UIEvent

    -

    This section is informative

    -
    partial interface UIEvent {
-  // Deprecated in this specification
-  undefined initUIEvent(DOMString typeArg,
-    optional boolean bubblesArg = false,
-    optional boolean cancelableArg = false,
-    optional Window? viewArg = null,
-    optional long detailArg = 0);
-};
-
    -
    -
    initUIEvent(typeArg) -
    - Initializes attributes of an UIEvent object. - This method has the same behavior as initEvent(). -

    The initUIEvent method is deprecated, but - supported for backwards-compatibility with widely-deployed - implementations.

    -
    -
    DOMString typeArg -
    Refer to the initEvent() method for a description of this parameter. -
    boolean bubblesArg -
    Refer to the initEvent() method for a description of this parameter. -
    boolean cancelableArg -
    Refer to the initEvent() method for a description of this parameter. -
    Window? viewArg -
    Specifies view. This value MAY be null. -
    long detailArg -
    Specifies detail. -
    -
    -

    7. Other UIEvents [DELETE]

    -

    This section will be deleted.

    -

    Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references.

    -

    7.1. Things defined in other sections

    -

    7.1.1. Activation triggers and behavior

    -

    7.1.2. Composition Events

    -

    7.1.3. Default actions and cancelable events

    -

    7.1.4. Event dispatch and DOM event flow

    -

    7.1.5. Focus Events

    -

    7.1.6. Web browsers and other dynamic or interactive user agents

    -

    7.1.7. Authoring tools

    -

    Add references to these events so that the linker doesn’t complain about exporting them.

    -

    unload, load, abort, error

    -

    8. Glossary [DELETE]

    -

    This section will be deleted.

    -

    Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline.

    -
    -
    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 UI Events, and they integrate and extend the objects -and models defined in this specification.

    -
    un-initialized value -
    -

    The value of any event attribute (such as bubbles or currentTarget) before the event has been initialized with initEvent(). The un-initialized values of an event apply -immediately after a new event has been created using the method createEvent().

    -
    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 § 7.1.6 Web browsers and other dynamic or interactive user agents and § 7.1.7 Authoring tools for details on the -requirements for a conforming user agent.

    -
    Window -
    -

    The Window is the object referred to by the current document’s -browsing context’s Window Proxy object as defined in HTML5 [HTML5].

    -
    -
    -
    -

    Conformance

    -

    Document conventions

    -

    Conformance requirements are expressed - with a combination of descriptive assertions - and RFC 2119 terminology. - The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” - in the normative parts of this document - are to be interpreted as described in RFC 2119. - However, for readability, - these words do not appear in all uppercase letters in this specification.

    -

    All of the text of this specification is normative - except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

    -

    Examples in this specification are introduced with the words “for example” - or are set apart from the normative text - with class="example", - like this:

    -
    - -

    This is an example of an informative example.

    -
    -

    Informative notes begin with the word “Note” - and are set apart from the normative text - with class="note", - like this:

    -

    Note, this is an informative note.

    -
    -

    Conformant Algorithms

    -

    Requirements phrased in the imperative as part of algorithms - (such as "strip any leading space characters" - or "return false and abort these steps") - are to be interpreted with the meaning of the key word - ("must", "should", "may", etc) - used in introducing the algorithm.

    -

    Conformance requirements phrased as algorithms or specific steps - can be implemented in any manner, - so long as the end result is equivalent. - In particular, the algorithms defined in this specification - are intended to be easy to understand - and are not intended to be performant. - Implementers are encouraged to optimize.

    -
    -
    - -

    Index

    -

    Terms defined by this specification

    - -

    Terms defined by reference

    -
      -
    • - [DOM] defines the following terms: -
        -
      • Event -
      • EventInit -
      • bubbles -
      • createEvent(interface) -
      • currentTarget -
      • document -
      • initEvent(type) -
      • target -
      -
    • - [HTML] defines the following terms: -
        -
      • Window -
      • input -
      • textarea -
      -
    • - [WEBIDL] defines the following terms: -
        -
      • DOMString -
      • Exposed -
      • boolean -
      • long -
      • undefined -
      -
    -

    References

    -

    Normative References

    -
    -
    [DOM] -
    Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/ -
    [HTML] -
    Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/ -
    [RFC2119] -
    S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119 -
    [WEBIDL] -
    Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/ -
    -

    Informative References

    -
    -
    [Editing] -
    A. Gregor. HTML Editing APIs. URL: https://dvcs.w3.org/hg/editing/raw-file/tip/editing.html -
    [HTML5] -
    Ian Hickson; et al. HTML5. URL: https://www.w3.org/html/wg/drafts/html/master/ -
    -

    IDL Index

    -
    [Exposed=Window]
-interface UIEvent : Event {
-  constructor(DOMString type, optional UIEventInit eventInitDict = {});
-  readonly attribute Window? view;
-  readonly attribute long detail;
-};
-
-dictionary UIEventInit : EventInit {
-  Window? view = null;
-  long detail = 0;
-};
-
-partial interface UIEvent {
-  // Deprecated in this specification
-  undefined initUIEvent(DOMString typeArg,
-    optional boolean bubblesArg = false,
-    optional boolean cancelableArg = false,
-    optional Window? viewArg = null,
-    optional long detailArg = 0);
-};
-
-
    - - - diff --git a/split/ui-events.txt b/split/ui-events.txt deleted file mode 100644 index d4810256..00000000 --- a/split/ui-events.txt +++ /dev/null @@ -1,932 +0,0 @@ -

    UI Events

    - -
    -Shortname: uievents-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
-	*** UI Events (core) ***
-
-	Note: This is an experimental split of the UI Events spec into smaller, event-specific
-	specs. The split was made from an out-of-date snapshot, so the information here is not
-	current, so please focus on the overall structure rather than the specifics of the
-	content. If this experiment goes well, then we will split the current spec after all
-	outstanding pull requests have been handled.
-
    - -
    -urlPrefix: https://www.w3.org/TR/WebIDL/#idl-; type: type;
-	text: long
-urlPrefix: https://w3c.github.io/selection-api/#widl-Window-getSelection-Selection; type: dfn; for: Document
-	text: getSelection()
-url: https://www.w3.org/TR/2004/REC-xml-20040204/#NT-S; type: dfn;
-	text: white space
-url: https://www.w3.org/TR/uievents-key/#key-attribute-value; type: dfn; spec: uievents-key;
-	text: key attribute value
-url: https://www.w3.org/TR/uievents-key/#keys-modifier; type: dfn; spec: uievents-key;
-	text: modifier keys table
-url: https://html.spec.whatwg.org/multipage/forms.html#context-menus; type: dfn;
-	text: contextmenu
-url: https://www.w3.org/TR/pointerevents3/#pointerevent-interface; type: interface; spec: pointerevents3
-	text: PointerEvent
-url: https://dom.spec.whatwg.org/#concept-tree-ancestor; type: dfn;
-	text: ancestor
-url: https://www.w3.org/TR/CSS21/visuren.html#x43; type: dfn;
-	text: stacking context
-url: https://drafts.csswg.org/css-position-3/#positioned-box; type: dfn;
-	text: positioned
-url: https://drafts.csswg.org/css-position-4/#paint-a-stacking-context; type: dfn;
-	text: painting a stacking context
-
    - -
    -spec:dom; type:interface; text:Document
-spec:dom; type:dfn; for:Event; text:target
-spec:infra; type:dfn; text:code point
-
    - -

    Introduction

    - -

    Overview

    - - TODO. - -

    Conformance

    - - Boilerplate? - -

    Stylistic Conventions

    - -This specification follows the -Proposed W3C Specification Conventions, -with the following supplemental additions: - -

    This is a note.

    - - - -

    This is an open issue.

    - -

    This is a warning.

    - -
    -	  interface Example {
-	      // This is an IDL definition.
-	  };
-
    - -

    User Interface Events

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

    - -

    UIEvent

    - - 
    -			[Exposed=Window]
-			interface UIEvent : Event {
-				constructor(DOMString type, optional UIEventInit eventInitDict = {});
-				readonly attribute Window? view;
-				readonly attribute long 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. -
    -
    - -

    UIEventInit

    - - 
    -			dictionary UIEventInit : 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. -
    -
    - -

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

    load

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| 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) |
    • {{Event}}.{{Event/target}} : common object whose contained resources have | - | | loaded
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - 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, EVENT{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. -

    - -

    unload

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| 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) |
    • {{Event}}.{{Event/target}} : common object whose contained resources have | - | | been removed
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - 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. - -

    abort

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| 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) |
    • {{Event}}.{{Event/target}} : element whose resources have been stopped from | - | | loading without error
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - 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. - -

    error

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| 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) |
    • {{Event}}.{{Event/target}} : element whose resources have been stopped from | - | | loading due to error
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - 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. - -

    select

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| 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) |
    • {{Event}}.{{Event/target}} : element whose text content has been selected
      • | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    | - ++------------------+--------------------------------------------------------------------------------------+ - - 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 - EVENT{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 EVENT{select} event might not be available for all elements in - all languages. For example, in [[HTML5]], EVENT{select} events can - be dispatched only on form <{input}> and <{textarea}> elements. - Implementations can dispatch EVENT{select} events in any context - deemed appropriate, including text selections outside of form - controls, or image or markup selections such as in SVG. -

    - -

    Extending Events

    - - -This section is non-normative - -

    Introduction

    - - This specification defines several interfaces and many events, however, this - is not an exhaustive set of events for all purposes. To allow content - authors and implementers to add desired functionality, this specification - provides two mechanisms for extend this set of interfaces and events without - creating conflicts: custom - events and implementation-specific - extensions. - -

    Custom Events

    - - A script author MAY wish to define an application in terms of functional - components, with event types that are meaningful to the application - architecture. The content author can use the {{CustomEvent}} interface to - create their own events appropriate to the level of abstraction they are - using. - -
    - A content author might have created an application which features a - dynamically generated bar chart. This bar chart is meant to be updated every - 5 minutes, or when a feed shows new information, or when the user refreshes - it manually by clicking a button. There are several handlers that have to be - called when the chart needs to be updated: the application has to fetch the - most recent data, show an icon to the user that the event is being updated, - and rebuild the chart. To manage this, the content author can choose to - create a custom updateChart event, which is fired whenever one of the - trigger conditions is met: - - 
    
-		var chartData = ...;
-		var evt = document.createEvent("CustomEvent");
-		evt.initCustomEvent( "updateChart", true, false, { data: chartData });
-		document.documentElement.dispatchEvent(evt);
-
    -
    - -

    Implementation-Specific Extensions

    - - While a new event is being designed and prototyped, or when an event is - intended for implementation-specific functionality, it is desirable to - distinguish it from standardized events. Implementors SHOULD prefix event - types specific to their implementations with a short string to distinguish - it from the same event in other implementations and from standardized - events. This is similar to the - vendor-specific keyword prefixes - in CSS, though without the dashes ("-") used in CSS, since that - can cause problems when used as an attribute name in Javascript. - -
    - A particular browser vendor, FooCorp, might wish to introduce a - new event, jump. This vendor implements - fooJump in their browser, using their - vendor-specific prefix: "foo". Early adopters start - experimenting with the event, using - someElement.addEventListener("fooJump", doJump, false ), - and provide feedback to FooCorp, who change the behavior of fooJump accordingly. - - After some time, another vendor, BarOrg, decides they also want - the functionality, but implement it slightly differently, so they use - their own vendor-specific prefix, "bar" in their event type - name: barJump. Content authors - experimenting with this version of the jump event type register events with BarOrg's - event type name. Content authors who wish to write code that accounts - for both browsers can either register each event type separately with - specific handlers, or use the same handler and switch on the name of the - event type. Thus, early experiments in different codebases do not - conflict, and the early adopter is able to write easily-maintained code - for multiple implementations. - - Eventually, as the feature matures, the behavior of both browsers - stabilizes and might converge due to content author and user feedback or - through formal standardization. As this stabilization occurs, and risk - of conflicts decrease, content authors can remove the forked code, and - use the jump event type name (even before - it is formally standardized) using the same event handler and the more - generic registration method someElement.addEventListener( "jump", - doJump, false). -
    - -

    Known Implementation-Specific Prefixes

    - - At the time of writing, the following event-type name prefixes are known to exist: - - ++---------------------+------------+-----------------------+ - =| Prefix | Web Engine | Organization | - +---------------------+------------+-----------------------+ - +| moz, | Gecko | Mozilla | - | Moz | | | - +| ms, | Trident | Microsoft | - | MS | | | - +| o, | Presto | Opera Software | - | O | | | - +| webkit | WebKit | Apple, Google, others | - ++---------------------+------------+-----------------------+ - -

    Legacy {{UIEvent}} events

    - -

    Legacy {{UIEvent}} event types

    - -

    DOMActivate

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    TypeDOMActivate
    Interface{{UIEvent}}
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    ComposedYes
    Default actionNone
    Context
    (trusted events)    		 -
      -
    • {{Event}}.{{Event/target}} : - element being activated
      • -
    • {{UIEvent}}.{{UIEvent/view}} : - Window
      • -
    • {{UIEvent}}.{{UIEvent/detail}} : - 0
      • -
    -
    - - A user agent MUST dispatch this event when a button, link, or - other state-changing element is activated. Refer to - [[#event-flow-activation]] for more details. - -

    - The EVENT{DOMActivate} event type is defined in this - specification for reference and completeness, but this specification - deprecates the use of this event type in favor of the related - event type EVENT{click}. Other specifications MAY define and - maintain their own EVENT{DOMActivate} event type for backwards - compatibility. -

    - -

    - While EVENT{DOMActivate} and EVENT{click} are not completely equivalent, - implemented behavior for the EVENT{click} event type has - developed to encompass the most critical accessibility aspects for which - the EVENT{DOMActivate} event type was designed, and is more - widely implemented. Content authors are encouraged to use the - EVENT{click} event type rather than the related EVENT{mousedown} - or EVENT{mouseup} event type to ensure maximum accessibility. -

    - - Implementations which support the EVENT{DOMActivate} event type - SHOULD also dispatch a EVENT{DOMActivate} event as a default - action of a EVENT{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. - -
    -

    - The EVENT{DOMActivate} event type is REQUIRED to be supported for - XForms [[XFORMS11]], 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 - EVENT{DOMActivate} event type, the XForms user agent has - to synthesize and dispatch its own EVENT{DOMActivate} events based on - the appropriate activation triggers. -

    - -

    - Thus, when a EVENT{click} event is dispatched by a user agent - conforming to UI Events, the XForms user agent has to determine - whether to synthesize a EVENT{DOMActivate} event with the same relevant - properties as a default action of that EVENT{click} event. - Appropriate cues might be whether the EVENT{click} event is trusted, or whether its event target - has a EVENT{DOMActivate} event listener registered. -

    -
    - -

    - Don't rely upon the interoperable support of EVENT{DOMActivate} in many - user agents. Instead, the EVENT{click} event type should - be used since it will provide more accessible behavior due to broader - implementation support. -

    - -

    - The EVENT{DOMActivate} event type is deprecated in this - specification. -

    - -

    Activation event order

    - - If the DOMActivate event is supported by the user - agent, then the events MUST be dispatched in a set order relative to - each other: (with only pertinent events listed): - - ++---+-------------+---------------------------------------------------+ - =| # | Event Type | Notes | - +---+-------------+---------------------------------------------------+ - +| 1 | click | | - +| 2 | DOMActivate | default action, if supported by the | - | | | user agent; synthesized; | - | | | isTrusted="true" | - +| 3 | | All other default actions, | - | | | including the activation behavior | - ++---+-------------+---------------------------------------------------+ - - If the focused element is activated by a key event, then the following - shows the typical sequence of events (with only pertinent events listed): - - ++---+-------------+---------------------------------------------------+ - =| # | Event Type | Notes | - +---+-------------+---------------------------------------------------+ - +| 1 | keydown | MUST be a key which can activate the element, | - | | | such as the KEYCAP{Enter} or KEYCAP{  } | - | | | (spacebar) key, or the element is not activated | - +| 2 | click | default action; synthesized; | - | | | isTrusted="true" | - +| 3 | DOMActivate | default action, if supported by the | - | | | user agent; synthesized; | - | | | isTrusted="true" | - +| 4 | | All other default actions, | - | | | including the activation behavior | - ++---+-------------+---------------------------------------------------+ - -

    Legacy Event Initializers

    - - This section is normative. - - The following features are obsolete and should only be implemented by - user agents that require compatibility with legacy software. - - Early versions of this specification included an initialization method on - the interface (for example initMouseEvent) that required a long - list of parameters that, in most cases, did not fully initialize all - attributes of the event object. Because of this, event interfaces which were - derived from the basic {{Event}} interface required that the initializer of - each of the derived interfaces be called explicitly in order to - fully initialize an event. - -
    - Initializing all the attributes of a UIEvent requires calls to two - initializer methods: initEvent and - initUIEvent. -
    - - Due in part to the length of time in the development of this standard, some - implementations MAY have taken a dependency on these (now deprecated) - initializer methods. For completeness, these legacy event initializers are - described in this section. - -

    Initializers for interface UIEvent

    - - This section is informative - - 
    -		partial interface UIEvent {
-			// Deprecated in this specification
-			undefined initUIEvent(DOMString typeArg,
-				optional boolean bubblesArg = false,
-				optional boolean cancelableArg = false,
-				optional Window? viewArg = null,
-				optional long detailArg = 0);
-		};
-
    - -
    -
    initUIEvent(typeArg)
    -
    - Initializes attributes of an {{UIEvent}} object. - This method has the same behavior as {{Event/initEvent()}}. - -

    - The initUIEvent method is deprecated, but - supported for backwards-compatibility with widely-deployed - implementations. -

    - -
    -
    DOMString typeArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    boolean bubblesArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    boolean cancelableArg
    -
    - Refer to the {{Event/initEvent()}} method for a description of this parameter. -
    - -
    Window? viewArg
    -
    - Specifies {{UIEvent/view}}. This value MAY be null. -
    - -
    long detailArg
    -
    - Specifies {{UIEvent/detail}}. -
    -
    -
    -
    - -

    Security Considerations

    - - This appendix discusses security considerations for UI Events implementations. - The discussion is limited to security issues that arise directly from - implementation of the event model, APIs and events defined in this - specification. Implementations typically support other features like scripting - languages, other APIs and additional events not defined in this document. These - features constitute an unknown factor and are out of scope of this document. - Implementers SHOULD consult the specifications of such features for their - respective security considerations. - - Many of the event types defined in this specification are dispatched in response - to user actions. This allows malicious event listeners to gain access to - information users would typically consider confidential, e.g., typos they might - have made when filling out a form, if they reconsider their answer to a multiple - choice question shortly before submitting a form, their typing rate or primary - input mechanism. In the worst case, malicious event listeners could capture all - user interactions and submit them to a third party through means (not defined in - this specification) that are generally available in DOM implementations, such as - the XMLHttpRequest interface. - - In DOM implementations that support facilities to load external data, events - like the EVENT{error} event can provide access to sensitive information about - the environment of the computer system or network. An example would be a - malicious HTML document that attempts to embed a resource on the local network - or the localhost on different ports. An embedded DOM application could - then listen for EVENT{error} and EVENT{load} events to determine which other - computers in a network are accessible from the local system or which ports are - open on the system to prepare further attacks. - - An implementation of UI Events alone is generally insufficient to perform - attacks of this kind and the security considerations of the facilities that - possibly support such attacks apply. For conformance with this specification, - DOM implementations MAY take reasonable steps to ensure that DOM - applications do not get access to confidential or sensitive information. For - example, they might choose not to dispatch EVENT{load} events to nodes that - attempt to embed resources on the local network. - -

    Acknowledgements

    - - Many people contributed to the DOM specifications (Level 1, 2 or 3), - including participants of the DOM Working Group, the DOM Interest Group, - the WebAPI Working Group, and the WebApps Working Group. - - We especially thank the following: - Andrew Watson (Object Management Group), - Andy Heninger (IBM), - Angel Diaz (IBM), - Anne van Kesteren (Opera Software), - Arnaud Le Hors (W3C and IBM), - Arun Ranganathan (AOL), - Ashok Malhotra (IBM and Microsoft), - Ben Chang (Oracle), - Bill Shea (Merrill Lynch), - Bill Smith (Sun), - Björn Höhrmann, - Bob Sutor (IBM), - Charles McCathie-Nevile (Opera Software, Co-Chair), - Chris Lovett (Microsoft), - Chris Wilson (Microsoft), - Christophe Jolif (ILOG), - David Brownell (Sun), - David Ezell (Hewlett-Packard Company), - David Singer (IBM), - Dean Jackson (W3C, W3C Team Contact), - Dimitris Dimitriadis (Improve AB and invited expert), - Don Park (invited), - Doug Schepers (Vectoreal), - Elena Litani (IBM), - Eric Vasilik (Microsoft), - Gavin Nicol (INSO), - Gorm Haug Eriksen (Opera Software), - Ian Davis (Talis Information Limited), - Ian Hickson (Google), - Ian Jacobs (W3C), - James Clark (invited), - James Davidson (Sun), - Jared Sorensen (Novell), - Jeroen van Rotterdam (X-Hive Corporation), - Joe Kesselman (IBM), - Joe Lapp (webMethods), - Joe Marini (Macromedia), - John Robinson (AOL), - Johnny Stenback (Netscape/AOL), - Jon Ferraiolo (Adobe), - Jonas Sicking (Mozilla Foundation), - Jonathan Marsh (Microsoft), - Jonathan Robie (Texcel Research and Software AG), - Kim Adamson-Sharpe (SoftQuad Software Inc.), - Lauren Wood (SoftQuad Software Inc., former Chair), - Laurence Cable (Sun), - Luca Mascaro (HTML Writers Guild), - Maciej Stachowiak (Apple Computer), - Marc Hadley (Sun Microsystems), - Mark Davis (IBM), - Mark Scardina (Oracle), - Martin Dürst (W3C), - Mary Brady (NIST), - Michael Shenfield (Research In Motion), - Mick Goulish (Software AG), - Mike Champion (Arbortext and Software AG), - Miles Sabin (Cromwell Media), - Patti Lutsky (Arbortext), - Paul Grosso (Arbortext), - Peter Sharpe (SoftQuad Software Inc.), - Phil Karlton (Netscape), - Philippe Le Hégaret (W3C, W3C Team Contact and former Chair), - Ramesh Lekshmynarayanan (Merrill Lynch), - Ray Whitmer (iMall, Excite@Home, and Netscape/AOL, Chair), - Rezaur Rahman (Intel), - Rich Rollman (Microsoft), - Rick Gessner (Netscape), - Rick Jelliffe (invited), - Rob Relyea (Microsoft), - Robin Berjon (Expway, Co-Chair), - Scott Hayman (Research In Motion), - Scott Isaacs (Microsoft), - Sharon Adler (INSO), - Stéphane Sire (IntuiLab), - Steve Byrne (JavaSoft), - Tim Bray (invited), - Tim Yu (Oracle), - Tom Pixley (Netscape/AOL), - T.V. Raman (Google). - Vidur Apparao (Netscape) and - Vinod Anupam (Lucent). - - Former editors: - Tom Pixley (Netscape Communications Corporation) until July 2002; - Philippe Le Hégaret (W3C) until November 2003; - Björn Höhrmann (Invited Expert) until January 2008; - and Jacob Rossi (Microsoft) from March 2011 to October 2011. - - Contributors: - In the WebApps Working Group, the following people made substantial - material contributions in the process of refining and revising this - specification: - Bob Lund (Cable Laboratories), - Cameron McCormack (Invited Expert / Mozilla), - Daniel Danilatos (Google), - Gary Kacmarcik (Google), - Glenn Adams (Samsung), - Hallvord R. M. Steen (Opera), - Hironori Bono (Google), - Mark Vickers (Comcast), - Masayuki Nakano (Mozilla), - Olli Pettay (Mozilla), - Takayoshi Kochi (Google) and - Travis Leithead (Microsoft). - - Glossary contributors: - Arnaud Le Hors (W3C) and - Robert S. Sutor (IBM Research). - - Test suite contributors: - Carmelo Montanez (NIST), - Fred Drake, - Mary Brady (NIST), - Neil Delima (IBM), - Rick Rivello (NIST), - Robert Clary (Netscape), - with a special mention to Curt Arnold. - - Thanks to all those who have helped to improve this specification by - sending suggestions and corrections (please, keep bugging us with your - issues!), or writing informative books or Web sites: - Al Gilman, - Alex Russell, - Alexander J. Vincent, - Alexey Proskuryakov, - Arkadiusz Michalski, - Brad Pettit, - Cameron McCormack, - Chris Rebert, - Curt Arnold, - David Flanagan, - Dylan Schiemann, - Erik Arvidsson, - Garrett Smith, - Giuseppe Pascale, - James Su, - Jan Goyvaerts (regular-expressions.info), - Jorge Chamorro, - Kazuyuki Ashimura, - Ken Rehor, - Magnus Kristiansen, - Martijn Wargers, - Martin Dürst, - Michael B. Allen, - Mike Taylor, - Misha Wolf, - Ojan Vafai, - Oliver Hunt, - Paul Irish, - Peter-Paul Koch, - Richard Ishida, - Sean Hogan, - Sergey Ilinsky, - Sigurd Lerstad, - Steven Pemberton, - Tony Chang, - William Edney and - Øistein E. Andersen. - -

    Refs to other UIEvent specs \[DELETE]

    - - This section will be deleted. - - Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references. - -

    Things defined in other sections

    - -

    Activation triggers and behavior

    -

    Composition Events

    -

    Default actions and cancelable events

    -

    Event dispatch and DOM event flow

    -

    Focus Events

    -

    Web browsers and other dynamic or interactive user agents

    -

    Authoring tools

    - - Add references to these events so that the linker doesn't complain about exporting them. - - EVENT{unload}, EVENT{load}, EVENT{abort}, EVENT{error} - - -

    Glossary \[DELETE]

    - -This section will be deleted. - -Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline. - -: 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 UI Events, and they integrate and extend the objects - and models defined in this specification. - -: un-initialized value -:: The value of any event attribute (such as {{Event/bubbles}} or - {{Event/currentTarget}}) before the event has been initialized with - {{Event/initEvent()}}. The un-initialized values of an event apply - immediately after a new event has been created using the method - {{Document/createEvent()}}. - -: 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 [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the - requirements for a conforming user agent. - -: Window -:: The Window is the object referred to by the current document's - browsing context's Window Proxy object as defined in - HTML5 - [[HTML5]]. - diff --git a/split/wheel-events.bs b/split/wheel-events.bs deleted file mode 100644 index 322e5361..00000000 --- a/split/wheel-events.bs +++ /dev/null @@ -1,489 +0,0 @@ -

    Wheel Events

    - -
    -Shortname: wheel-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
-	*** Wheel Events ***
-
-	Note: This is an experimental split of the UI Events spec into smaller, event-specific
-	specs. The split was made from an out-of-date snapshot, so the information here is not
-	current, so please focus on the overall structure rather than the specifics of the
-	content. If this experiment goes well, then we will split the current spec after all
-	outstanding pull requests have been handled.
-
    - -
    -urlPrefix: https://www.w3.org/TR/WebIDL/#idl-; type: type;
-	text: long
-urlPrefix: https://w3c.github.io/selection-api/#widl-Window-getSelection-Selection; type: dfn; for: Document
-	text: getSelection()
-url: https://www.w3.org/TR/2004/REC-xml-20040204/#NT-S; type: dfn;
-	text: white space
-url: https://www.w3.org/TR/uievents-key/#key-attribute-value; type: dfn; spec: uievents-key;
-	text: key attribute value
-url: https://www.w3.org/TR/uievents-key/#keys-modifier; type: dfn; spec: uievents-key;
-	text: modifier keys table
-url: https://html.spec.whatwg.org/multipage/forms.html#context-menus; type: dfn;
-	text: contextmenu
-url: https://www.w3.org/TR/pointerevents3/#pointerevent-interface; type: interface; spec: pointerevents3
-	text: PointerEvent
-url: https://dom.spec.whatwg.org/#concept-tree-ancestor; type: dfn;
-	text: ancestor
-url: https://www.w3.org/TR/CSS21/visuren.html#x43; type: dfn;
-	text: stacking context
-url: https://drafts.csswg.org/css-position-3/#positioned-box; type: dfn;
-	text: positioned
-url: https://drafts.csswg.org/css-position-4/#paint-a-stacking-context; type: dfn;
-	text: painting a stacking context
-
    - -
    -spec:dom; type:interface; text:Document
-spec:dom; type:dfn; for:Event; text:target
-spec:infra; type:dfn; text:code point
-spec:uievents; type:attribute; text:screenX
-spec:uievents; type:attribute; text:screenY
-spec:uievents; type:attribute; text:clientX
-spec:uievents; type:attribute; text:clientY
-
    - -

    Introduction

    - -

    Overview

    - - TODO. - -

    Conformance

    - - Boilerplate? - -

    Stylistic Conventions

    - -This specification follows the -Proposed W3C Specification Conventions, -with the following supplemental additions: - -

    This is a note.

    - - - -

    This is an open issue.

    - -

    This is a warning.

    - -
    -	  interface Example {
-	      // This is an IDL definition.
-	  };
-
    - -

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

    - - A user agent MUST create a wheel event transaction when the first wheel event - is fired, so that all subsequent wheel events within a implementation-specific amount of - time can be targetted at the same element. A wheel event transaction is series of - wheel events that are associated with a single user gesture. The - wheel event transaction MUST have an associated event target that is the - topmost event target at the time the first wheel event occurs in the group. - -

    - If a series of wheel events targetted in a scrollable element start above a child element, - later events for the same user gesture may occur over the child element. -

    - -

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

    WheelEvent

    - - 
    -			[Exposed=Window]
-			interface WheelEvent : MouseEvent {
-				constructor(DOMString type, optional WheelEventInit eventInitDict = {});
-				// DeltaModeCode
-				const unsigned long DOM_DELTA_PIXEL = 0x00;
-				const unsigned long DOM_DELTA_LINE	= 0x01;
-				const unsigned long DOM_DELTA_PAGE	= 0x02;
-
-				readonly attribute double deltaX;
-				readonly attribute double deltaY;
-				readonly attribute double deltaZ;
-				readonly attribute unsigned long 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
    -
    - 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
    -
    - 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
    -
    - 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
    -
    - The deltaMode attribute contains an indication of - the units of measurement for the delta values. The - default value is {{WheelEvent/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. -
    -
    - -

    WheelEventInit

    - - 
    -			dictionary WheelEventInit : MouseEventInit {
-				double deltaX = 0.0;
-				double deltaY = 0.0;
-				double deltaZ = 0.0;
-				unsigned long deltaMode = 0;
-			};
-
    - -
    -
    deltaX
    -
    See deltaZ attribute.
    - -
    deltaY
    -
    See deltaZ attribute.
    - -
    deltaZ
    -
    - Initializes the {{WheelEvent/deltaZ}} attribute of the {{WheelEvent}} - object. Relative positive values for this attribute (as well as - the {{WheelEvent/deltaX}} and {{WheelEvent/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
    -
    - Initializes the {{WheelEvent/deltaMode}} attribute on the - {{WheelEvent}} object to the enumerated values 0, 1, or 2, which - represent the amount of pixels scrolled - ({{WheelEvent/DOM_DELTA_PIXEL}}), lines scrolled - ({{WheelEvent/DOM_DELTA_LINE}}), or pages scrolled - ({{WheelEvent/DOM_DELTA_PAGE}}) if the rotation of the - wheel would have resulted in scrolling. -
    -
    - -

    Wheel Event Types

    - -

    wheel

    - - - - - - - - - - - -
    Typewheel
    Interface{{WheelEvent}}
    Sync / AsyncAsync
    BubblesYes
    Trusted TargetsElement
    CancelableVaries
    ComposedYes
    Default actionScroll (or zoom) the document
    Context
    (trusted events)
    • {{Event}}.{{Event/target}} : element target for the current wheel event transaction
    • {{UIEvent}}.{{UIEvent/view}} : Window
    • {{UIEvent}}.{{UIEvent/detail}} : 0
    • {{MouseEvent}}.{{MouseEvent/screenX}} : if the wheel is associated with a pointing device, the value based on the pointer position on the screen, otherwise 0
    • {{MouseEvent}}.{{MouseEvent/screenY}} : if the wheel is associated with a pointing device, the value based on the pointer position on the screen, otherwise 0
    • {{MouseEvent}}.{{MouseEvent/clientX}} : if the wheel is associated with a pointing device, the value based on the pointer position within the viewport, otherwise 0
    • {{MouseEvent}}.{{MouseEvent/clientY}} : if the wheel is associated with a pointing device, the value based on the pointer position within the viewport, otherwise 0
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
    • {{MouseEvent}}.{{MouseEvent/button}} : if wheel is associated with a pointing device, value based on current button pressed, otherwise 0
    • {{MouseEvent}}.{{MouseEvent/buttons}} : if wheel is associated with a pointing device, value based on all buttons current depressed, 0 if no buttons pressed
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the event target the pointing device is pointing at, if any
    • {{WheelEvent}}.{{WheelEvent/deltaX}} : expected amount that the page will scroll along the x-axis according to the deltaMode units; or an implementation-specific value of movement of a wheel around the x-axis
    • {{WheelEvent}}.{{WheelEvent/deltaY}} : expected amount that the page will scroll along the y-axis according to the deltaMode units; or an implementation-specific value of movement of a wheel around the y-axis
    • {{WheelEvent}}.{{WheelEvent/deltaZ}} : expected amount that the page will scroll along the z-axis according to the deltaMode units; or an implementation-specific value of movement of a wheel around the z-axis
    • {{WheelEvent}}.{{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. -

    - -

    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 the user - agent should generate wheel events whose - cancelable property is false, indicating that - preventDefault cannot be used to prevent or interrupt - scrolling. Otherwise cancelable will be true. -

    - -

    - In particular, a user agent should generate only uncancelable - wheel events when it - observes - that there are no non-passive listeners for the event. -

    - -

    Security Considerations

    - - TODO - Add specific concerns for this spec - -

    Acknowledgements

    - - TODO - -

    Refs to other UIEvent specs \[DELETE]

    - - This section will be deleted. - - Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references. - -

    Things defined in other sections

    - -

    Activation triggers and behavior

    -

    Composition Events

    -

    Default actions and cancelable events

    -

    Event dispatch and DOM event flow

    -

    Focus Events

    -

    Web browsers and other dynamic or interactive user agents

    -

    Authoring tools

    - -

    Glossary \[DELETE]

    - -This section will be deleted. - -Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline. - -: 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 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 - [[#event-flow-activation]] for more details. - -: activation trigger -:: An event which is defined to initiate an activation behavior. Refer - to [[#event-flow-activation]] for more details. - -: 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 - [[#event-flow-default-cancel]]. - -: delta -:: The estimated scroll amount (in pixels, lines, or pages) that the user agent - will scroll or zoom the page in response to the physical movement of an - input device that supports the {{WheelEvent}} interface (such as a mouse - wheel or touch pad). The value of a delta (e.g., the - {{WheelEvent/deltaX}}, {{WheelEvent/deltaY}}, or {{WheelEvent/deltaZ}} - attributes) is to be interpreted in the context of the current - {{WheelEvent/deltaMode}} property. The relationship between the physical - movement of a wheel (or other device) 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. - -: 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 event - target. Each event is an instantiation of one specific event - type. - -: event target -:: The object to which an event is targeted using the [[#event-flow]]. - The event target is the value of the {{Event/target}} attribute. - -: 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 UI Events, and they integrate and extend the objects - and models defined in this specification. - -: 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. - -: 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 graphical user - interfaces this is the element under the user's pointing device. A user - interface's hit testing facility is used to determine the target. For - specific details regarding hit testing and stacking order, refer to the - host language. - -: un-initialized value -:: The value of any event attribute (such as {{Event/bubbles}} or - {{Event/currentTarget}}) before the event has been initialized with - {{Event/initEvent()}}. The un-initialized values of an event apply - immediately after a new event has been created using the method - {{Document/createEvent()}}. - -: 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 [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the - requirements for a conforming user agent. - -: Window -:: The Window is the object referred to by the current document's - browsing context's Window Proxy object as defined in - HTML5 - [[HTML5]]. - - diff --git a/split/wheel-events.html b/split/wheel-events.html deleted file mode 100644 index b06268c9..00000000 --- a/split/wheel-events.html +++ /dev/null @@ -1,1640 +0,0 @@ - - - - - Wheel Events - - - - - - - - - - - - - - - - -
    -

    -

    Wheel Events

    -

    Editor’s Draft,

    -
    - More details about this document -
    -
    -
    This version: -
    https://w3c.github.io/uievents/ -
    Latest published version: -
    https://www.w3.org/TR/uievents/ -
    Feedback: -
    GitHub -
    Editors: -
    (Google) -
    (Microsoft) -
    Former Editor: -
    Doug Schepers (Mar 2008 - May 2011) -
    Tests: -
    web-platform-tests uievents/ (ongoing work) -
    -
    -
    -
    -

    Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

    -
    -
    -
    -

    Abstract

    -

    *** Wheel Events ***

    -

    Note: This is an experimental split of the UI Events spec into smaller, event-specific - - specs. The split was made from an out-of-date snapshot, so the information here is not - current, so please focus on the overall structure rather than the specifics of the - content. If this experiment goes well, then we will split the current spec after all - outstanding pull requests have been handled.

    -
    -

    Status of this document

    -
    -

    This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

    -

    This document was published by the Web Applications Working Group as an Editors Draft. This document is intended to become a W3C Recommendation.

    -

    -

    This document was published by the Web Applications Working Group as a Working Draft. - - Feedback and comments on this specification are welcome. Please use GitHub issues Historical discussions can be found in the public-webapps@w3.org archives.

    -

    Publication as an Editors Draft does not imply endorsement by W3C and its Members. This is a draft document and may - be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite - this document as other than work in progress.

    -

    This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

    -

    This document is governed by the 2 November 2021 W3C Process Document.

    -
    -
    - -
    -

    1. Introduction

    -

    1.1. Overview

    -

    TODO.

    -

    1.2. Conformance

    -

    Boilerplate?

    -

    2. Stylistic Conventions

    -

    This specification follows the Proposed W3C Specification Conventions, -with the following supplemental additions:

    -

    This is a note.

    -

    This is an open issue.

    -

    This is a warning.

    -
    interface Example {
-    // This is an IDL definition.
-};
-
    -

    3. 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).

    -

    A user agent MUST create a wheel event transaction when the first wheel event - is fired, so that all subsequent wheel events within a implementation-specific amount of - time can be targetted at the same element. A wheel event transaction is series of - wheel events that are associated with a single user gesture. The wheel event transaction MUST have an associated event target that is the topmost event target at the time the first wheel event occurs in the group.

    -

    If a series of wheel events targetted in a scrollable element start above a child element, - later events for the same user gesture may occur over the child element.

    -

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

    -

    3.1.1. WheelEvent

    -
    [Exposed=Window]
-interface WheelEvent : MouseEvent {
-  constructor(DOMString type, optional WheelEventInit eventInitDict = {});
-  // DeltaModeCode
-  const unsigned long DOM_DELTA_PIXEL = 0x00;
-  const unsigned long DOM_DELTA_LINE  = 0x01;
-  const unsigned long DOM_DELTA_PAGE  = 0x02;
-
-  readonly attribute double deltaX;
-  readonly attribute double deltaY;
-  readonly attribute double deltaZ;
-  readonly attribute unsigned long 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.

    -
    -

    3.1.2. WheelEventInit

    -
    dictionary WheelEventInit : MouseEventInit {
-  double deltaX = 0.0;
-  double deltaY = 0.0;
-  double deltaZ = 0.0;
-  unsigned long 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. -
    -

    3.2. Wheel Event Types

    -

    3.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 : element target for the current wheel event transaction -
    • 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 implementation-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 implementation-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 implementation-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.

    -

    3.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 the user - agent should generate wheel events whose cancelable property is false, indicating that preventDefault cannot be used to prevent or interrupt - scrolling. Otherwise cancelable will be true.

    -

    In particular, a user agent should generate only uncancelable wheel events when it observes - that there are no non-passive listeners for the event.

    -

    4. Security Considerations

    -

    TODO - Add specific concerns for this spec

    -

    5. Acknowledgements

    -

    TODO

    -

    6. Refs to other UIEvent specs [DELETE]

    -

    This section will be deleted.

    -

    Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references.

    -

    6.1. Things defined in other sections

    -

    6.1.1. Activation triggers and behavior

    -

    6.1.2. Composition Events

    -

    6.1.3. Default actions and cancelable events

    -

    6.1.4. Event dispatch and DOM event flow

    -

    6.1.5. Focus Events

    -

    6.1.6. Web browsers and other dynamic or interactive user agents

    -

    6.1.7. Authoring tools

    -

    7. Glossary [DELETE]

    -

    This section will be deleted.

    -

    Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline.

    -
    -
    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 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 § 6.1.1 Activation triggers and behavior for more details.

    -
    activation trigger -
    -

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

    -
    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 preventDefault() method. For more details, see § 6.1.3 Default actions and cancelable events.

    -
    delta -
    -

    The estimated scroll amount (in pixels, lines, or pages) that the user agent -will scroll or zoom the page in response to the physical movement of an -input device that supports the WheelEvent interface (such as a mouse -wheel or touch pad). The value of a delta (e.g., the deltaX, deltaY, or deltaZ attributes) is to be interpreted in the context of the current deltaMode property. The relationship between the physical -movement of a wheel (or other device) 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.

    -
    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 event -target. Each event is an instantiation of one specific event -type.

    -
    event target -
    -

    The object to which an event is targeted using the § 6.1.4 Event dispatch and DOM event flow. -The event target is the value of the target attribute.

    -
    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 UI Events, and they integrate and extend the objects -and models defined in this specification.

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

    -
    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 graphical user -interfaces this is the element under the user’s pointing device. A user -interface’s hit testing facility is used to determine the target. For -specific details regarding hit testing and stacking order, refer to the host language.

    -
    un-initialized value -
    -

    The value of any event attribute (such as bubbles or currentTarget) before the event has been initialized with initEvent(). The un-initialized values of an event apply -immediately after a new event has been created using the method createEvent().

    -
    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 § 6.1.6 Web browsers and other dynamic or interactive user agents and § 6.1.7 Authoring tools for details on the -requirements for a conforming user agent.

    -
    Window -
    -

    The Window is the object referred to by the current document’s -browsing context’s Window Proxy object as defined in HTML5 [HTML5].

    -
    -
    -
    -

    Conformance

    -

    Document conventions

    -

    Conformance requirements are expressed - with a combination of descriptive assertions - and RFC 2119 terminology. - The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” - in the normative parts of this document - are to be interpreted as described in RFC 2119. - However, for readability, - these words do not appear in all uppercase letters in this specification.

    -

    All of the text of this specification is normative - except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

    -

    Examples in this specification are introduced with the words “for example” - or are set apart from the normative text - with class="example", - like this:

    -
    - -

    This is an example of an informative example.

    -
    -

    Informative notes begin with the word “Note” - and are set apart from the normative text - with class="note", - like this:

    -

    Note, this is an informative note.

    -
    -

    Conformant Algorithms

    -

    Requirements phrased in the imperative as part of algorithms - (such as "strip any leading space characters" - or "return false and abort these steps") - are to be interpreted with the meaning of the key word - ("must", "should", "may", etc) - used in introducing the algorithm.

    -

    Conformance requirements phrased as algorithms or specific steps - can be implemented in any manner, - so long as the end result is equivalent. - In particular, the algorithms defined in this specification - are intended to be easy to understand - and are not intended to be performant. - Implementers are encouraged to optimize.

    -
    -
    - -

    Index

    -

    Terms defined by this specification

    - -

    Terms defined by reference

    -
      -
    • - [DOM] defines the following terms: -
        -
      • Event -
      • bubbles -
      • createEvent(interface) -
      • currentTarget -
      • document -
      • initEvent(type) -
      • preventDefault() -
      • target -
      -
    • - [UIEVENTS] defines the following terms: -
        -
      • MouseEvent -
      • MouseEventInit -
      • UIEvent -
      • altKey -
      • button -
      • buttons -
      • clientX -
      • clientY -
      • ctrlKey -
      • detail -
      • metaKey -
      • relatedTarget -
      • screenX -
      • screenY -
      • shiftKey -
      • view -
      -
    • - [WEBDRIVER-BIDI] defines the following terms: -
        -
      • event type -
      -
    • - [WEBIDL] defines the following terms: -
        -
      • DOMString -
      • Exposed -
      • double -
      • unsigned long -
      -
    -

    References

    -

    Normative References

    -
    -
    [DOM] -
    Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/ -
    [RFC2119] -
    S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119 -
    [UIEVENTS] -
    Gary Kacmarcik; Travis Leithead. UI Events. URL: https://w3c.github.io/uievents/ -
    [WEBDRIVER-BIDI] -
    WebDriver BiDi URL: https://w3c.github.io/webdriver-bidi/ -
    [WEBIDL] -
    Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/ -
    -

    Informative References

    -
    -
    [HTML5] -
    Ian Hickson; et al. HTML5. URL: https://www.w3.org/html/wg/drafts/html/master/ -
    -

    IDL Index

    -
    [Exposed=Window]
-interface WheelEvent : MouseEvent {
-  constructor(DOMString type, optional WheelEventInit eventInitDict = {});
-  // DeltaModeCode
-  const unsigned long DOM_DELTA_PIXEL = 0x00;
-  const unsigned long DOM_DELTA_LINE  = 0x01;
-  const unsigned long DOM_DELTA_PAGE  = 0x02;
-
-  readonly attribute double deltaX;
-  readonly attribute double deltaY;
-  readonly attribute double deltaZ;
-  readonly attribute unsigned long deltaMode;
-};
-
-dictionary WheelEventInit : MouseEventInit {
-  double deltaX = 0.0;
-  double deltaY = 0.0;
-  double deltaZ = 0.0;
-  unsigned long deltaMode = 0;
-};
-
-
    - - - \ No newline at end of file diff --git a/split/wheel-events.txt b/split/wheel-events.txt deleted file mode 100644 index 52ae1035..00000000 --- a/split/wheel-events.txt +++ /dev/null @@ -1,534 +0,0 @@ -

    Wheel Events

    - -
    -Shortname: wheel-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
-	*** Wheel Events ***
-	
-	Note: This is an experimental split of the UI Events spec into smaller, event-specific
-	specs. The split was made from an out-of-date snapshot, so the information here is not
-	current, so please focus on the overall structure rather than the specifics of the
-	content. If this experiment goes well, then we will split the current spec after all
-	outstanding pull requests have been handled.
-
    - -
    -urlPrefix: https://www.w3.org/TR/WebIDL/#idl-; type: type;
-	text: long
-urlPrefix: https://w3c.github.io/selection-api/#widl-Window-getSelection-Selection; type: dfn; for: Document
-	text: getSelection()
-url: https://www.w3.org/TR/2004/REC-xml-20040204/#NT-S; type: dfn;
-	text: white space
-url: https://www.w3.org/TR/uievents-key/#key-attribute-value; type: dfn; spec: uievents-key;
-	text: key attribute value
-url: https://www.w3.org/TR/uievents-key/#keys-modifier; type: dfn; spec: uievents-key;
-	text: modifier keys table
-url: https://html.spec.whatwg.org/multipage/forms.html#context-menus; type: dfn;
-	text: contextmenu
-url: https://www.w3.org/TR/pointerevents3/#pointerevent-interface; type: interface; spec: pointerevents3
-	text: PointerEvent
-url: https://dom.spec.whatwg.org/#concept-tree-ancestor; type: dfn;
-	text: ancestor
-url: https://www.w3.org/TR/CSS21/visuren.html#x43; type: dfn;
-	text: stacking context
-url: https://drafts.csswg.org/css-position-3/#positioned-box; type: dfn;
-	text: positioned
-url: https://drafts.csswg.org/css-position-4/#paint-a-stacking-context; type: dfn;
-	text: painting a stacking context
-
    - -
    -spec:dom; type:interface; text:Document
-spec:dom; type:dfn; for:Event; text:target
-spec:infra; type:dfn; text:code point
-spec:uievents; type:attribute; text:screenX
-spec:uievents; type:attribute; text:screenY
-spec:uievents; type:attribute; text:clientX
-spec:uievents; type:attribute; text:clientY
-
    - -

    Introduction

    - -

    Overview

    - - TODO. - -

    Conformance

    - - Boilerplate? - -

    Stylistic Conventions

    - -This specification follows the -Proposed W3C Specification Conventions, -with the following supplemental additions: - -

    This is a note.

    - - - -

    This is an open issue.

    - -

    This is a warning.

    - -
    -	  interface Example {
-	      // This is an IDL definition.
-	  };
-
    - -

    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 - EVENT{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 - EVENT{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). -

    - - A user agent MUST create a wheel event transaction when the first wheel event - is fired, so that all subsequent wheel events within a implementation-specific amount of - time can be targetted at the same element. A wheel event transaction is series of - wheel events that are associated with a single user gesture. The - wheel event transaction MUST have an associated event target that is the - topmost event target at the time the first wheel event occurs in the group. - -

    - If a series of wheel events targetted in a scrollable element start above a child element, - later events for the same user gesture may occur over the child element. -

    - -

    Interface WheelEvent

    - -

    Introduced in this specification

    - - The {{WheelEvent}} interface provides specific contextual information - associated with EVENT{wheel} events. - - To create an instance of the {{WheelEvent}} interface, use the {{WheelEvent}} constructor, - passing an optional {{WheelEventInit}} dictionary. - -

    WheelEvent

    - - 
    -			[Exposed=Window]
-			interface WheelEvent : MouseEvent {
-				constructor(DOMString type, optional WheelEventInit eventInitDict = {});
-				// DeltaModeCode
-				const unsigned long DOM_DELTA_PIXEL = 0x00;
-				const unsigned long DOM_DELTA_LINE	= 0x01;
-				const unsigned long DOM_DELTA_PAGE	= 0x02;
-
-				readonly attribute double deltaX;
-				readonly attribute double deltaY;
-				readonly attribute double deltaZ;
-				readonly attribute unsigned long 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
    -
    - In user agents where the default action of the EVENT{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
    -
    - In user agents where the default action of the EVENT{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
    -
    - In user agents where the default action of the EVENT{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
    -
    - The deltaMode attribute contains an indication of - the units of measurement for the delta values. The - default value is {{WheelEvent/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. -
    -
    - -

    WheelEventInit

    - - 
    -			dictionary WheelEventInit : MouseEventInit {
-				double deltaX = 0.0;
-				double deltaY = 0.0;
-				double deltaZ = 0.0;
-				unsigned long deltaMode = 0;
-			};
-
    - -
    -
    deltaX
    -
    See deltaZ attribute.
    - -
    deltaY
    -
    See deltaZ attribute.
    - -
    deltaZ
    -
    - Initializes the {{WheelEvent/deltaZ}} attribute of the {{WheelEvent}} - object. Relative positive values for this attribute (as well as - the {{WheelEvent/deltaX}} and {{WheelEvent/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
    -
    - Initializes the {{WheelEvent/deltaMode}} attribute on the - {{WheelEvent}} object to the enumerated values 0, 1, or 2, which - represent the amount of pixels scrolled - ({{WheelEvent/DOM_DELTA_PIXEL}}), lines scrolled - ({{WheelEvent/DOM_DELTA_LINE}}), or pages scrolled - ({{WheelEvent/DOM_DELTA_PAGE}}) if the rotation of the - wheel would have resulted in scrolling. -
    -
    - -

    Wheel Event Types

    - -

    wheel

    - - ++------------------+--------------------------------------------------------------------------------------+ event-definition - =| % | | - +------------------+--------------------------------------------------------------------------------------+ - +| 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}}.{{Event/target}} : element target for the current | - | | wheel event transaction | - | |
    • {{UIEvent}}.{{UIEvent/view}} : Window
      • | - | |
    • {{UIEvent}}.{{UIEvent/detail}} : 0
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenX}} : if the wheel is associated with a | - | | pointing device, the value based on the pointer position on the screen, | - | | otherwise 0
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/screenY}} : if the wheel is associated with a | - | | pointing device, the value based on the pointer position on the screen, | - | | otherwise 0
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientX}} : if the wheel is associated with a | - | | pointing device, the value based on the pointer position within the viewport, | - | | otherwise 0
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/clientY}} : if the wheel is associated with a | - | | pointing device, the value based on the pointer position within the viewport, | - | | otherwise 0
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/altKey}} : true if KEYCAP{Alt} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if KEYCAP{Control} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/shiftKey}} : true if KEYCAP{Shift} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/metaKey}} : true if KEYCAP{Meta} | - | | modifier was active, otherwise false
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/button}} : if wheel is associated with a pointing | - | | device, value based on current button pressed, otherwise 0
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/buttons}} : if wheel is associated with a pointing | - | | device, value based on all buttons current depressed, | - | | 0 if no buttons pressed
      • | - | |
    • {{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the event target | - | | the pointing device is pointing at, if any
      • | - | |
    • {{WheelEvent}}.{{WheelEvent/deltaX}} : expected amount that the page will scroll | - | | along the x-axis according to the deltaMode units; or an implementation-specific | - | | value of movement of a wheel around the x-axis
      • | - | |
    • {{WheelEvent}}.{{WheelEvent/deltaY}} : expected amount that the page will scroll | - | | along the y-axis according to the deltaMode units; or an implementation-specific | - | | value of movement of a wheel around the y-axis
      • | - | |
    • {{WheelEvent}}.{{WheelEvent/deltaZ}} : expected amount that the page will scroll | - | | along the z-axis according to the deltaMode units; or an implementation-specific | - | | value of movement of a wheel around the z-axis
      • | - | |
    • {{WheelEvent}}.{{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 - EVENT{wheel} event with multiple non-zero axes or as separate - EVENT{wheel} events for each non-zero axis. - - The typical default action of the EVENT{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. -

    - -

    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 the user - agent should generate wheel events whose - cancelable property is false, indicating that - preventDefault cannot be used to prevent or interrupt - scrolling. Otherwise cancelable will be true. -

    - -

    - In particular, a user agent should generate only uncancelable - wheel events when it - observes - that there are no non-passive listeners for the event. -

    - -

    Security Considerations

    - - TODO - Add specific concerns for this spec - -

    Acknowledgements

    - - TODO - -

    Refs to other UIEvent specs \[DELETE]

    - - This section will be deleted. - - Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy). - This will be deleted once we have proper cross-references. - -

    Things defined in other sections

    - -

    Activation triggers and behavior

    -

    Composition Events

    -

    Default actions and cancelable events

    -

    Event dispatch and DOM event flow

    -

    Focus Events

    -

    Web browsers and other dynamic or interactive user agents

    -

    Authoring tools

    - -

    Glossary \[DELETE]

    - -This section will be deleted. - -Temporary glossary terms (for bikeshed linker). -Many of these are properly defined elsewhere and should be linked to directly. -Terms which should be defined in this spec should be defined inline. - -: 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 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 - [[#event-flow-activation]] for more details. - -: activation trigger -:: An event which is defined to initiate an activation behavior. Refer - to [[#event-flow-activation]] for more details. - -: 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 - [[#event-flow-default-cancel]]. - -: delta -:: The estimated scroll amount (in pixels, lines, or pages) that the user agent - will scroll or zoom the page in response to the physical movement of an - input device that supports the {{WheelEvent}} interface (such as a mouse - wheel or touch pad). The value of a delta (e.g., the - {{WheelEvent/deltaX}}, {{WheelEvent/deltaY}}, or {{WheelEvent/deltaZ}} - attributes) is to be interpreted in the context of the current - {{WheelEvent/deltaMode}} property. The relationship between the physical - movement of a wheel (or other device) 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. - -: 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 event - target. Each event is an instantiation of one specific event - type. - -: event target -:: The object to which an event is targeted using the [[#event-flow]]. - The event target is the value of the {{Event/target}} attribute. - -: 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 UI Events, and they integrate and extend the objects - and models defined in this specification. - -: 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. - -: 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 graphical user - interfaces this is the element under the user's pointing device. A user - interface's hit testing facility is used to determine the target. For - specific details regarding hit testing and stacking order, refer to the - host language. - -: un-initialized value -:: The value of any event attribute (such as {{Event/bubbles}} or - {{Event/currentTarget}}) before the event has been initialized with - {{Event/initEvent()}}. The un-initialized values of an event apply - immediately after a new event has been created using the method - {{Document/createEvent()}}. - -: 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 [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the - requirements for a conforming user agent. - -: Window -:: The Window is the object referred to by the current document's - browsing context's Window Proxy object as defined in - HTML5 - [[HTML5]]. - - From 7379a927e6274f53c997f5678e2f1d3440e260f9 Mon Sep 17 00:00:00 2001 From: Gary Kacmarcik Date: Fri, 6 Sep 2024 14:55:38 -0700 Subject: [PATCH 5/7] Remove ancient TR snapshot of spec --- TR.html | 9867 ---------------------------------------------------- w3c-tr.css | 200 -- 2 files changed, 10067 deletions(-) delete mode 100644 TR.html delete mode 100644 w3c-tr.css diff --git a/TR.html b/TR.html deleted file mode 100644 index 49c7e51a..00000000 --- a/TR.html +++ /dev/null @@ -1,9867 +0,0 @@ - - - - UI Events (formerly DOM Level 3 Events) - - - - - - - - - -

    Abstract

    -

    This specification defines UI Events which extend the DOM Event objects defined in - [DOM4]. UI Events are those typically implemented by - visual user agents for handling user interaction such as mouse and keyboard input. -

    -

    Status of This Document

    - - - -

    - This section describes the status of this document at the time of its publication. - Other documents may supersede this document. A list of current W3C publications and the - latest revision of this technical report can be found in the W3C technical reports index at - http://www.w3.org/TR/. -

    - -

    - Implementers should be aware that this document is not stable. - Implementers who are not taking part in the discussions are likely to find the - specification changing out from under them in incompatible ways. - Vendors interested in implementing this document before it eventually reaches - the Candidate Recommendation stage should join the aforementioned mailing lists - and take part in the discussions. -

    - -

    - The previous version of the UI Events specification was extending DOM Level 3 Events but has been abandoned for now, due to the lack of time to work out the details of 'locale'. Future extensions may also be subsumed by additional work and proposals around the InputDevice API, allowing access to information related to the physical device responsible for an event. -

    - - -

    - This document was published by the Web Applications Working Group as a Working Draft. - - This document is intended to become a W3C Recommendation. - - - If you wish to make comments regarding this document, please send them to - www-dom@w3.org - (subscribe, - archives). - All comments are welcome. -

    - -

    - Publication as a Working Draft does not imply endorsement by the W3C - Membership. This is a draft document and may be updated, replaced or obsoleted by other - documents at any time. It is inappropriate to cite this document as other than work in - progress. -

    - -

    - This document was produced by a group operating under the - 5 February 2004 W3C Patent - Policy. - W3C maintains a public list of any patent - disclosures - made in connection with the deliverables of the group; that page also includes - instructions for disclosing a patent. An individual who has actual knowledge of a patent - which the individual believes contains - Essential - Claim(s) must disclose the information in accordance with - section - 6 of the W3C Patent Policy. -

    - -

    This document is governed by the 1 August 2014 W3C Process Document. -

    - -

    Table of Contents

    - - - - - -
    -

    1. Introduction

    - -
    -

    1.1 Overview

    -

    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.

    -
    - -
    -

    1.2 Conformance

    -

    This section is normative.

    - -

    Within this specification, the key words MUST, MUST NOT, REQUIRED, - SHALL, SHALL NOT, SHOULD, SHOULD NOT, - RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in - [RFC2119].

    - -

    This specification is to be understood in the context of the DOM Level 3 Core specification - [DOM3 Core] and the general - considerations for DOM implementations apply. - For example, handling of namespace URIs is discussed in - XML Namespaces. - For additional information about - conformance, - please see the DOM Level 3 Core specification - [DOM3 Core]. - A user agent is not required to conform - to the entirety of another specification in order to conform to this specification, but it MUST - conform to the specific parts of any other specification which are called out in this specification - (e.g., a conforming UI Events user agent MUST support - the DOMString data type as defined in Web IDL, but need - not support every method or data type defined in Web IDL in order to - conform to UI Events). -

    - -

    This specification defines several classes of conformance for different - user agents, specifications, and content authors: -

    -
    -
    Web browsers and other dynamic or interactive - user agents -
    -
    -

    A dynamic or interactive user agent, referred to - here as a browser (be it a Web browser, AT (Accessibility Technology) application, - or other similar program), conforms to UI Events if it supports: -

    -
      -
    • the Core module defined in - [DOM3 Core] -
      • -
    • the Event dispatch and DOM event flow mechanism -
      • -
    • all the interfaces and events with their associated methods, attributes, and - semantics defined in this specification with the exception of those marked as - deprecated (a conforming user - agent MAY implement the deprecated interfaces, events, or APIs for backwards - compatibility, but is not required to do so in order to be conforming) -
      • -
    • the complete set of key and code values defined in - [DOM3 key Values] and - [DOM3 code Values] - (subject to platform availability), and -
      • -
    • all other normative requirements defined in this specification. -
      • -
    -

    A conforming browser MUST dispatch events appropriate - to the given EventTarget when the conditions defined - for that event type have been met. -

    - -

    A browser conforms specifically to UI Events if it implements - the interfaces and related event types - specified in Event Types. -

    - -

    A conforming browser MUST support scripting, declarative interactivity, or some other means of - detecting and dispatching events in the manner described by this specification, and MUST support - the APIs specified for that event type. -

    - -

    In addition to meeting all other conformance criteria, a conforming browser MAY implement - features of this specification marked as - deprecated, for backwards compatibility with - existing content, but such implementation is discouraged. -

    - -

    A conforming browser MAY also support features not found in this specification, but which use - the Event dispatch and DOM event flow mechanism, interfaces, events, - or other features defined in this specification, and MAY implement additional interfaces and - event types appropriate to that implementation. - Such features can be later standardized in future specifications. -

    - -

    A browser which does not conform to all required portions of this specification MUST NOT claim - conformance to UI Events. - Such an implementation which does conform to portions of this specification MAY claim - conformance to those specific portions. -

    - -

    A conforming browser MUST also be a conforming implementation of the IDL fragments in this - specification, as described in the Web IDL specification [WEBIDL]. -

    -
    - -
    Authoring tools
    -
    -

    A content authoring tool conforms to UI Events if it produces content which uses the - event types and - Event dispatch and DOM event flow model, consistent in a manner as - defined in this specification. -

    -

    A content authoring tool MUST NOT claim conformance to UI Events for content it produces - which uses features of this specification marked as - deprecated in this specification. -

    -

    A conforming content authoring tool SHOULD provide to the content author a means to use all - event types and interfaces appropriate to all - host languages in the content document being - produced. -

    -
    - -
    Content authors and content
    -
    -

    A content author creates conforming UI Events content if that content uses the - event types and - Event dispatch and DOM event flow model, consistent in a manner as - defined in this specification. -

    -

    A content author SHOULD NOT use features of this specification marked as - deprecated, but SHOULD rely instead upon - replacement mechanisms defined in this specification and elsewhere. -

    -

    Conforming content MUST use the semantics of the interfaces and - event types as described in this specification. -

    - -
    Note

    Authoring Note: - Content authors are advised to follow best practices as described in - accessibility and - internationalization guideline - specifications. -

    -
    - -
    Specifications and host languages
    -
    -

    A specification or host language conforms - to UI Events if it references and uses the - Event dispatch and DOM event flow mechanism, interfaces, events, - or other features defined in [DOM4], and does not extend these - features in incompatible ways. -

    -

    A specification or host language conforms - specifically to UI Events if it references and uses the interfaces and - related event types specified in - Event Types. - A conforming specification MAY define additional interfaces and - event types appropriate to that specification, - or MAY extend the UI Events interfaces and - event types in a manner that does not contradict - or conflict with the definitions of those interfaces and - event types in this specification. -

    - -

    Specifications or host languages which - reference UI Events SHOULD NOT use or recommend features of this - specification marked as deprecated, but - SHOULD use or recommend the indicated replacement for that the feature (if available). -

    -
    -
    -
    - -
    -

    1.3 Stylistic Conventions

    -

    This specification follows the Proposed W3C Specification - Conventions, with the following supplemental additions:

    - -
    -
    Key and character values
    -
      -
    • Names of key values are shown as: '=' (e.g., the value of - KeyboardEvent.key). -
      • -
    • Names of key codes are shown as: 'Equal' (e.g., the value of - KeyboardEvent.code). -
      • -
    • Character values of keys are shown as: '\u003d' (e.g., the code point - of the key value). -
      • -
    • Glyphs representing character values are shown as: '=' (e.g., the - key cap or font associated with a character value). -
      • -
    -
    - -

    In addition, certain terms are used in this specification with particular meanings. The term implementation applies to a browser, content authoring tool, - or other user agent that implements this specification, while a content author is a person who writes script or code - that takes advantage of the interfaces, methods, attributes, events, and other features described in this specification in order to make Web applications, and a - user is the person who uses those Web applications in an implementation.

    -
    -
    - - -
    -

    2. Issues

    - -
    Issue 1

    Open issues in this specification are called out using this convention.

    -
    - - -
    -

    3. DOM Event Architecture

    - -

    This section is informative.

    - -
    -

    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.

    - -
    - Graphical representation of an event dispatched in a DOM tree using the DOM event flow -
    Fig. 1 Graphical representation of an event dispatched in a DOM tree using the DOM event flow
    -
    - -

    Event objects are dispatched to an 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 current event targets through which - the event object MUST pass. For DOM implementations, the propagation path MUST reflect the hierarchical tree - structure of the document. The last item in the list MUST be the event target. The - preceding items in the list are referred to as the target's ancestors, and the immediately preceding item as the target's parent. Once determined, the - propagation path MUST NOT be changed. For DOM implementations, this applies even if an element in the propagation path is moved within the - DOM or removed from the DOM.

    - -
    -
    -

    In the DOM event flow, event listeners might change the position of the - event target in the document while the event object is being dispatched. Such changes do not affect the propagation path.

    -
    - -

    Note that event listeners are not copied over when Node are copied using methods such as - Node.cloneNode or Range.cloneContents - [DOM Range]. -

    - -

    Exceptions thrown inside event listeners MUST NOT stop the propagation of the event or affect the - propagation path. The exception itself MUST NOT propagate outside the scope of the event - handler.

    - -
    -
    -

    In the following code, the exception thrown from the call to throw "Error" does not propagate into the parent scope - (which would prevent the console.log statement from executing):

    -
    var e = document.createEvent("Event");
-e.initEvent("myevent", false, false);
-var target = document.createElement("div");
-target.addEventListener("myevent", function () {
-   throw "Error";
-});
-target.dispatchEvent(e); // Causes the event listener to throw an exception...
-// The previously thrown exception doesn't affect the code that follows:
-console.log("Exceptions? No problem");
    -
    - -

    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 Window 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. - -
    2. The target phase: The event object MUST arrive at the event object's - 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. - -
    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 Window. 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.
      4. -
    - -

    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 - MUST NOT be changed. Adding or removing listeners does not affect the current target's candidate event listeners.

    - -

    Finally, the implementation MUST process all candidate event handlers in order and trigger - each handler 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.
      • -
    - -

    In the production of the propagation path, the event propagates from the Window - to the document object during the capture phase, and from the document object to the - Window during the bubble phase.

    - -

    After an event completes all the phases of its propagation path, its - Event.currentTarget MUST be set to null and the Event.eventPhase MUST be - set to 0 (NONE). All other attributes of the Event (or interface derived from Event) - are unchanged (including the Event.target attribute, which MUST continue to reference the - event target).

    - -

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

    - -

    Events are typically dispatched by the implementation as a result of a user action, in response to the completion of a task, or to signal progress during asynchronous - activity (such as a network request). Some events can be used to control the behavior that the implementation MAY take next (or undo an action that the implementation - already took). Events in this category are said to be cancelable and the behavior they cancel is called their - default action. Cancelable event objects can be associated with one or more default actions. - To cancel an event, call the Event.preventDefault() method.

    - -
    -
    -

    A mousedown event is dispatched immediately after the user presses down a button on a - pointing device (typically a mouse). One possible default action taken by the implementation is to set up a state - machine that allows the user to drag images or select text. The default action depends on what happens next — for - example, if the user's pointing device is over text, a text selection might begin. If the user's pointing device is over an image, then an image-drag action could - begin. Preventing the default action of a mousedown - event prevents these actions from occuring.

    -
    - -

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

    - -
    -
    -

    The default action associated with the click event on <input - type="checkbox"> elements toggles the checked IDL attribute value of that element. If the click - event's default action is cancelled, then the value is restored to its former state.

    -
    - -

    When an event is canceled, then the conditional default actions associated with the event MUST be skipped (or - as mentioned above, if the default actions are carried out before the dispatch, their effect MUST be undone). - Whether an event object is cancelable MUST be indicated by the Event.cancelable attribute. - Event.preventDefault() stops all related default actions of an event object. The - Event.defaultPrevented attribute indicates whether an event has already been canceled (e.g., by a prior event listener). If the - DOM application itself initiated the dispatch, then the return value of the EventTarget.dispatchEvent() - method indicates whether the event object was cancelled.

    - -
    Note

    Authoring Note: Many implementations additionally interpret an event listener's return value, such as the value false, to mean - that the default action of cancelable events will be cancelled (though window.onerror handlers are cancelled - by returning true).

    - -
    Note

    Authoring Note: Some cancelable events might not have any observable default actions. For - example, the mousemove event.

    - -

    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 SHOULD 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 the - default action of a wheel event, while another implementation might instead zoom the document as its default action.

    -
    -
    - -
    -

    3.3 Synchronous and asynchronous events

    - -

    Events MAY be dispatched 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.

    - -
    -
    -

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

    - -
    -
    -

    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 document load (such as the DOMContentLoaded event from HTML5) is not guaranteed.

    -
    - -
    -

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

    - -
    Note

    Authoring Note: Certain events, such as hotkeys or control keys pressed in a certain sequence, can be - swallowed by the operating system or the application, interrupting the expected event order.

    -
    -
    - -
    -

    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 the - click event. This event always triggers the - default action, even if the isTrusted attribute is false (this behavior is retained for backward-compatibility). - All other untrusted events MUST behave - as if the Event.preventDefault() method had been called on that event.

    -
    - -
    -

    3.5 Activation triggers and behavior

    - -

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

    - -
    -
    -

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

    - -
    -
    -

    When a user activates a hyperlink using a keyboard, such as by focusing the hyperlink element - and pressing the 'Enter' or ' ' 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

    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.

    -
    - -
    -

    3.5.2 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):

    - - - - - - - - - - - - - - - - - -
    Event NameNotes
    1.click
    - All 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):

    - - - - - - - - - - - - - - - - - - - - - - -
    Event NameNotes
    1.keydownMUST be a key which can activate the element, such as the - 'Enter' or ' ' key, - or the element is not activated
    2.clickdefault action; synthesized; isTrusted="true"
    - All default actions, - including the activation behavior -
    -
    -
    - -
    -

    3.6 Event exceptions

    - -

    This section is informative.

    - -

    Event operations can throw a DOMException as specified in their method descriptions.

    - -
    Note

    Note: The exception EventException introduced in DOM Level 2 is - removed in this specification as part of this specification's normative support of Web IDL. EventException formerly defined - an exception code UNSPECIFIED_EVENT_TYPE_ERR which is replaced in this specification by the use of a DOMException of type - InvalidStateError.

    - -

    The following DOMException types are used in this specification.

    - - - - - - - - - - - - - - -
    TypeDescription
    InvalidStateErrorThrown when the Event.type was not specified by initializing the event before dispatchEvent was - called. Also thrown when the Event object provided to dispatchEvent is already being dispatched.
    NotSupportedErrorThrown when DocumentEvent.createEvent() is passed an Event - interface that the implementation does not support.
    -
    - -
    -

    3.7 Constructing Mouse and Keyboard Events

    - -

    Generally, when a constructor of an Event interface, - or of an interface inherited from the Event interface, - is invoked, the steps described in DOM4 [DOM4] should be followed. - However the KeyboardEvent and - MouseEvent interfaces provide additional - dictionary members for initializing the internal state of the - Event object's key modifiers: specifically, the - internal state queried for using the - KeyboardEvent.getModifierState() - and MouseEvent.getModifierState() - methods. This section supplements the DOM4 steps for intializing a new - Event object with these optional modifier states. -

    - -

    For the purposes of constructing a KeyboardEvent, - MouseEvent, or object derived from these objects - using the algorithm below, all - KeyboardEvent, - MouseEvent, and derived ojects have - internal key modifier state which can be set and - retreived using the key modifier names: - 'AltGraph' - 'CapsLock' - 'Fn' - 'FnLock' - 'Hyper' - 'NumLock' - 'OS' - 'ScrollLock' - 'Super' - 'Symbol' and - 'SymbolLock'. - -

    The following steps supplement the algorithm defined for constructing events in DOM4:

    - -
      -
    1. If the Event being constructed is a - KeyboardEvent or - MouseEvent object or an object that - derives from either of these, and a - EventModifierInit - argument was provided to the constructor, then run the following sub-steps: -
        -
      1. For each EventModifierInit - argument, if the dictionary member begins with the string "keyModifierState", then - let the key modifier name be the dictionary member's name - excluding the prefix "keyModifierState", and set the - Event object's - internal key modifier state that - matches the key modifier name to the corresponding value. -
      -
    -
    -
    - - -
    -

    4. Basic Event Interfaces

    - -

    The basic event interfaces defined in DOM4 - [DOM4] are fundamental to UI Events. - These basic event interfaces MUST always be supported by the implementation: -

    - -
      -
    • The Event interface and its following constants, methods and attributes: -
        -
      • NONE constant
        • -
      • CAPTURING_PHASE constant
        • -
      • AT_TARGET constant
        • -
      • BUBBLING_PHASE constant
        • -
      • type attribute
        • -
      • target attribute
        • -
      • currentTarget attribute
        • -
      • eventPhase attribute
        • -
      • bubbles attribute
        • -
      • cancelable attribute
        • -
      • timeStamp attribute
        • -
      • defaultPrevented attribute
        • -
      • isTrusted attribute
        • -
      • stopPropagation() method
        • -
      • stopImmediatePropagation() method
        • -
      • preventDefault() method
        • -
      • initEvent() method
        • -
      -
      • -
    • The CustomEvent interface and its following method and attribute: -
        -
      • initCustomEvent() method
        • -
      • detail attribute
        • -
      -
      • -
    • The EventTarget interface and its following methods: -
        -
      • addEventListener() method
        • -
      • removeEventListener() method
        • -
      • dispatchEvent() method
        • -
      -
      • -
    • The EventListener interface and its handleEvent method
      • -
    • The Document interface's createEvent method
      • -
    - -

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

    -

    The following chart describes the inheritance structure of interfaces defined in this specification. -

    - -
    - Graphical representation of inheritance of interfaces defined by this specification -
    Fig. 2 Graphical representation of inheritance of interfaces defined by this specification
    -
    - -
    -

    4.1 List of Event Types

    - -

    Each event MUST be associated with a type, called event type and available as the type - attribute on the event object. The event type MUST be of type DOMString.

    - -

    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 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 an informative summary of the event types defined in this specification.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event TypeSync / AsyncBubbling phaseTrusted event target typesDOM interfaceCancelableDefault Action
    abortSyncNoWindow, ElementEventNoNone
    beforeinputSyncYesElementInputEventYesUpdate the DOM element
    blurSyncNoWindow, ElementFocusEventNoNone
    clickSyncYesElementMouseEventYesVaries: - for targets with an associated activation - behavior, executes the activation behavior; - for focusable targets, gives the element focus. -
    compositionstartSyncYesElementCompositionEventYesShow a text composition system candidate window
    compositionupdateSyncYesElementCompositionEventNoNone
    compositionendSyncYesElementCompositionEventNoNone
    dblclickSyncYesElementMouseEventNoVaries: - for targets with an associated activation - behavior, executes the activation behavior; - for focusable targets, gives the element focus; - for selectable targets, selects part or all of the - element's content. -
    errorAsyncNoWindow, ElementEventNoNone
    focusSyncNoWindow, ElementFocusEventNoNone
    focusinSyncYesWindow, ElementFocusEventNoNone
    focusoutSyncYesWindow, ElementFocusEventNoNone
    inputSyncYesElementInputEventNoNone
    keydownSyncYesElementKeyboardEventYesVaries: - beforeinput and input events; - launch text composition system; - blur and focus events; - keypress event; - activation behavior; - other event
    keyupSyncYesElementKeyboardEventYesNone
    loadAsyncNoWindow, Document, ElementEventNoNone
    mousedownSyncYesElementMouseEventYesVaries: start a drag/drop operation; start a text selection; start a scroll/pan interaction (in combination with the middle mouse button, if supported)
    mouseenterSyncNoElementMouseEventNoNone
    mouseleaveSyncNoElementMouseEventNoNone
    mousemoveSyncYesElementMouseEventYesNone
    mouseoutSyncYesElementMouseEventYesNone
    mouseoverSyncYesElementMouseEventYesNone
    mouseupSyncYesElementMouseEventYesInvoke a context menu (in combination with the right mouse button, if supported)
    resizeSyncNoWindow, ElementUIEventNoNone
    scrollAsyncNo / YesDocument, ElementUIEventNoNone
    selectSyncYesElementEventNoNone
    unloadSyncNoWindow, Document, ElementEventNoNone
    wheelAsyncYesElementWheelEventYesScroll (or zoom) the document
    - -

    For a list of events which are deprecated in this specification, see the Legacy Event Types appendix - at the end of this document.

    - -
    -
    -

    The following is one way to interpret the above tables: the load event will - trigger event listeners attached on Element nodes for that event and on the capture and target phases. This event is not cancelable. If an event listener for the - load event is attached to a node other than Window, - Document, or Element nodes, or if it is attached to the bubbling phase only, this event listener would not be triggered.

    -
    - -
    Note

    Note: Don't interpret the above tables as definitive for the listed event types. For example, the load event is used in other - specifications, for example, in XMLHttpRequest. Similarly, dispatchEvent can be used to dispatch untrusted events to - listeners on any object that also implements EventTarget.

    - -
    Note

    Note: The event objects associated with the event types described above contain additional context information--refer to the description of the DOM - interfaces for further information.

    -
    - -
    - - -
    -

    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 Event Types

    -

    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 - DocumentEvent.createEvent("UIEvent") - method call. -

    - - 
    [Constructor(DOMString type, optional UIEventInit eventInitDict)]
-interface UIEvent : Event {
-    readonly    attribute Window? view;
-    readonly    attribute long    detail;
-};
    5.1.1.1 Attributes
    detail of type long, readonly
    -

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

    - -

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

    -
    view of type Window, readonly , nullable
    -

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

    - -

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

    -
    - - 
    dictionary UIEventInit : EventInit {
-    Window? view = null;
-    long    detail = 0;
-};
    5.1.1.2 Dictionary UIEventInit Members
    detail of type long, defaulting to 0
    -

    This value is initialized to a number that is application-specific. -

    -
    view of type Window, nullable, defaulting to null
    -

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

    -
    - -
    - -

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

    - - -
    -
    -
    load
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typeload
    InterfaceUIEvent if generated from a user interface, Event otherwise.
    Sync / AsyncAsync
    BubblesNo
    Trusted TargetsWindow, Document, Element
    CancelableNo
    Default actionNone
    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.

    - -
    Note

    Note: 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.

    -
    -
    -
    - - -
    -
    -
    unload
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typeunload
    InterfaceUIEvent if generated from a user interface, Event otherwise.
    Sync / AsyncSync
    BubblesNo
    Trusted TargetsWindow, Document, Element
    CancelableNo
    Default actionNone
    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.

    -
    -
    -
    - - -
    -
    -
    abort
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typeabort
    InterfaceUIEvent if generated from a user interface, Event otherwise.
    Sync / AsyncSync
    BubblesNo
    Trusted TargetsWindow, Element
    CancelableNo
    Default actionNone
    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.

    -
    -
    -
    - - -
    -
    -
    error
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typeerror
    InterfaceUIEvent if generated from a user interface, Event otherwise.
    Sync / AsyncAsync
    BubblesNo
    Trusted TargetsWindow, Element
    CancelableNo
    Default actionNone
    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.

    -
    -
    -
    - - -
    -
    -
    select
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typeselect
    InterfaceUIEvent if generated from a user interface, Event otherwise.
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableNo
    Default actionNone
    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.

    - -
    Note

    Note: 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 [HTML Editing].

    - -
    Note

    Note: 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.

    -
    -
    -
    - - -
    -
    -
    resize
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typeresize
    InterfaceUIEvent
    Sync / AsyncSync
    BubblesNo
    Trusted TargetsWindow, Element
    CancelableNo
    Default actionNone
    Context
    (trusted events)    		 - -
    - -

    A user agent MUST dispatch this event when a document view has been resized. This event type is dispatched after - all effects for that occurrence of resizing of that particular event target have been executed by the user agent.

    - -

    User agents which support continuous reflow of the document's layout during user-initiated resizing MUST dispatch - this event synchronously after each reflow of the document.

    - -

    The Window object SHOULD always be resizable. A - host language MAY define certain elements to be resizable, and under what conditions (e.g., specific elements like <iframe>, or elements - with particular characteristics like width and height). However, this specification does not define the behavior for elements.

    - -
    Note

    Note: The resize event is distinct from the - SVG zoom event types, though both can occur at the same time, or as the consequence of the same user action. In particular, browser - font zooming or page zooming will not necessarily trigger a resize event.

    - -
    Note

    Note: In previous DOM Events specifications, the resize - event type was defined to have a bubbling phase, but for performance reasons, this was not implemented in most - user agents, and this specification removes the bubbling phase for this event.

    -
    -
    -
    - - -
    -
    -
    scroll
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typescroll
    InterfaceUIEvent
    Sync / AsyncAsync
    BubblesNo / Yes
    Trusted TargetsDocument, Element
    CancelableNo
    Default actionNone
    Context
    (trusted events)    		 - -
    - -

    A user agent MUST dispatch this event when a document view or an element has been scrolled. This event type is dispatched - after the scroll has occurred.

    - -

    When dispatched on the Document element, this event type MUST - bubble to the Window object.

    -
    -
    -
    -
    - -
    -

    5.2 Focus Event Types

    - -
    Note

    Note: - This interface and its associated event types and - focus event order - were designed in accordance to the concepts and guidelines defined in - User Agent Accessibility Guidelines 2.0 - [UAAG 2.0], - 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 - DocumentEvent.createEvent("FocusEvent") - method call. -

    - - 
    [Constructor(DOMString typeArg, optional FocusEventInit focusEventInitDict)]
-interface FocusEvent : UIEvent {
-    readonly    attribute EventTarget? relatedTarget;
-};
    5.2.1.1 Attributes
    relatedTarget of type EventTarget, readonly , nullable
    -

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

    -
    - - 
    dictionary FocusEventInit : UIEventInit {
-    EventTarget? relatedTarget = null;
-};
    5.2.1.2 Dictionary FocusEventInit Members
    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). -

    -
    - -
    - -
    -

    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 NameNotes
    User shifts focus
    1.focusinSent before first target element receives focus
    2.focusSent after first target element receives focus
    User shifts focus
    3.focusoutSent before first target element loses focus
    4.focusinSent before second target element receives focus
    5.blurSent after first target element loses focus
    6.focusSent after second target element receives focus
    - -
    Note

    Note: 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. -

    -
    - -

    The Focus event types are listed below.

    - - -
    -
    -
    blur
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typeblur
    InterfaceFocusEvent
    Sync / AsyncSync
    BubblesNo
    Trusted TargetsWindow, Element
    CancelableNo
    Default actionNone
    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.

    -
    -
    -
    - - -
    -
    -
    focus
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typefocus
    InterfaceFocusEvent
    Sync / AsyncSync
    BubblesNo
    Trusted TargetsWindow, Element
    CancelableNo
    Default actionNone
    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.

    -
    -
    -
    - - -
    -
    -
    focusin
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typefocusin
    InterfaceFocusEvent
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsWindow, Element
    CancelableNo
    Default actionNone
    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.

    - -
    Note

    Note: When using this event type, the content author can use the event's - FocusEvent.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.

    -
    -
    -
    - - -
    -
    -
    focusout
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typefocusout
    InterfaceFocusEvent
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsWindow, Element
    CancelableNo
    Default actionNone
    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 Event Types

    - -

    The mouse event module originates from the [HTML 4.01] 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. -

    - -
    Note

    Note: - 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 - DocumentEvent.createEvent("MouseEvent") - method call. -

    - -
    Note

    Note: - 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). -

    - - 
    [Constructor(DOMString typeArg, optional MouseEventInit mouseEventInitDict)]
-interface MouseEvent : UIEvent {
-    readonly    attribute long           screenX;
-    readonly    attribute long           screenY;
-    readonly    attribute long           clientX;
-    readonly    attribute long           clientY;
-    readonly    attribute boolean        ctrlKey;
-    readonly    attribute boolean        shiftKey;
-    readonly    attribute boolean        altKey;
-    readonly    attribute boolean        metaKey;
-    readonly    attribute short          button;
-    readonly    attribute EventTarget?   relatedTarget;
-    // Introduced in this specification
-    readonly    attribute unsigned short buttons;
-    boolean getModifierState (DOMString keyArg);
-};
    5.3.1.1 Attributes
    altKey of type boolean, readonly
    -

    Refer to the KeyboardEvent.altKey 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 MouseEvent.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).
      • -
    - -

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

    - -
    Note

    Note: - 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. -

    - -
    Note

    Authoring Note: - 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. -

    - -
    Note

    Note: - 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 MouseEvent.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, ... ). -

    - -
    Note

    Note: - 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. -

    - -
    Note

    Authoring Note: - 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. -

    -
    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.ctrlKey attribute.

    - -

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

    -
    metaKey of type boolean, readonly
    -

    Refer to the KeyboardEvent.metaKey attribute.

    - -

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

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

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

    -
    shiftKey of type boolean, readonly
    -

    Refer to the KeyboardEvent.shiftKey attribute.

    - -

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

    -
    5.3.1.2 Methods
    getModifierState
    -

    Introduced in this specification

    - -

    Queries the state of a modifier using a key value. - See Modifier keys for a list of valid (case-sensitive) arguments to this method. -

    - -

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

    - - -
    ParameterTypeNullableOptionalDescription
    keyArgDOMString✘✘ -

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

    -
    Return type: boolean
    - - 
    dictionary MouseEventInit : EventModifierInit {
-    long           screenX = 0;
-    long           screenY = 0;
-    long           clientX = 0;
-    long           clientY = 0;
-    short          button = 0;
-    unsigned short buttons = 0;
-    EventTarget?   relatedTarget = null;
-};
    5.3.1.3 Dictionary MouseEventInit Members
    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. -

    - -
    Note

    Note: - 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. -

    - -
    Note

    Note: - 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 } -

    -
    -
    clientX of type long, defaulting to 0
    -

    See clientY (substituting "horizontal" for "vertical").

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

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

    -
    screenX of type long, defaulting to 0
    -

    See screenY (substituting "horizontal" for "veritcal").

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

    -
    - -
    - -

    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 - KeyboardEvent.getModifierState(). - The steps for constructing events using this dictionary are defined in the - event constructors section.

    - - 
    dictionary EventModifierInit : 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 modifierOS = false;
-    boolean modifierScrollLock = false;
-    boolean modifierSuper = false;
-    boolean modifierSymbol = false;
-    boolean modifierSymbolLock = false;
-};
    5.3.2.1 Dictionary EventModifierInit Members
    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 - MouseEvent.getModifierState() or - KeyboardEvent.getModifierState() - when provided with the parameter 'Alt' must - return true.

    -
    ctrlKey of type boolean, defaulting to false
    -

    Initializes the altKey attribute of the - MouseEvent or - KeyboardEvent - objects to true if the 'Control' - (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 - MouseEvent.getModifierState() or - KeyboardEvent.getModifierState() - when provided with either the parameter 'Control' or - the parameter 'Accel' 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 - MouseEvent.getModifierState() or - KeyboardEvent.getModifierState() - when provided with either the parameter 'Meta' or - the parameter 'Accel' must return true.

    -
    modifierAltGraph of type boolean, defaulting to false
    -

    Initializes the event object's key modifier state such that calls to the - MouseEvent.getModifierState() or - KeyboardEvent.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 - MouseEvent.getModifierState() or - KeyboardEvent.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 - MouseEvent.getModifierState() or - KeyboardEvent.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 - MouseEvent.getModifierState() or - KeyboardEvent.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 - MouseEvent.getModifierState() or - KeyboardEvent.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 - MouseEvent.getModifierState() or - KeyboardEvent.getModifierState() - when provided with the parameter 'NumLock' must - return true.

    -
    modifierOS of type boolean, defaulting to false
    -

    Initializes the event object's key modifier state such that calls to the - MouseEvent.getModifierState() or - KeyboardEvent.getModifierState() - when provided with the parameter 'OS' must - return true.

    -
    modifierScrollLock of type boolean, defaulting to false
    -

    Initializes the event object's key modifier state such that calls to the - MouseEvent.getModifierState() or - KeyboardEvent.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 - MouseEvent.getModifierState() or - KeyboardEvent.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 - MouseEvent.getModifierState() or - KeyboardEvent.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 - MouseEvent.getModifierState() or - KeyboardEvent.getModifierState() - when provided with the parameter 'SymbolLock' 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 - MouseEvent.getModifierState() or - KeyboardEvent.getModifierState() - when provided with the parameter 'Shift' 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 NameElementNotes
    1.mousemove
    Pointing device is moved into element A...
    2.mouseoverA
    3.mouseenterA
    4.mousemoveAMultiple events
    Pointing device is moved out of element A...
    5.mouseoutA
    6.mouseleaveA
    - -

    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 NameElementNotes
    1.mousemove
    Pointing device is moved into element A...
    2.mouseoverA
    3.mouseenterA
    4.mousemoveAMultiple events
    Pointing device is moved into nested element B...
    5.mouseoutA
    6.mouseoverB
    7.mouseenterB
    8.mousemoveBMultiple events
    Pointing device is moved from element B into A...
    9.mouseoutB
    10.mouseleaveB
    11.mouseoverA
    12.mousemoveAMultiple events
    Pointing device is moved out of element A...
    13.mouseoutA
    14.mouseleaveA
    - -

    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 -
    Fig. 3 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 NameElementNotes
    1.mousemove
    Pointing device is moved into element C, the topmost element in the stack
    2.mouseoverC
    3.mouseenterA
    4.mouseenterB
    5.mouseenterC
    6.mousemoveCMultiple events
    Pointing device is moved out of element C...
    7.mouseoutC
    8.mouseleaveC
    9.mouseleaveB
    10.mouseleaveA
    - -
    Note

    Note: 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 NameNotes
    1.mousedown
    2.mousemoveOPTIONAL, multiple events, some limits
    3.mouseup
    4.click
    5.mousemoveOPTIONAL, multiple events, some limits
    6.mousedown
    7.mousemoveOPTIONAL, multiple events, some limits
    8.mouseup
    9.click
    10.dblclick
    - -
    Note

    Note: 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.

    -
    - -
    - -

    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.

    - - -
    -
    -
    click
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typeclick
    InterfaceMouseEvent
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    Default actionVaries
    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 MouseEvent.button value is 0, - MouseEvent.buttons value is 1). - Secondary buttons (like the middle or right button on a standard mouse) MUST NOT fire - click events. -

    - -

    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 Activation triggers and behavior.

    - -
    Note

    Note: 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 - MouseEvent.button - or MouseEvent.buttons attributes. - Typical default actions - of the click event type are as follows: -

    - - -
    -
    -
    - - -
    -
    -
    dblclick
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typedblclick
    InterfaceMouseEvent
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    Default actionNone
    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. -

    - -
    Note

    Note: 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 - MouseEvent.button or - MouseEvent.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.
      • -
    -
    -
    -
    - - -
    -
    -
    mousedown
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typemousedown
    InterfaceMouseEvent
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    Default actionVaries: 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.

    - -
    Note

    Note: 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.

    - -
    -
    -
    - - -
    -
    -
    mouseenter
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typemouseenter
    InterfaceMouseEvent
    Sync / AsyncSync
    BubblesNo
    Trusted TargetsElement
    CancelableNo
    Default actionNone
    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. 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.

    - -
    Note

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

    - -
    -
    -
    - - -
    -
    -
    mouseleave
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typemouseleave
    InterfaceMouseEvent
    Sync / AsyncSync
    BubblesNo
    Trusted TargetsElement
    CancelableNo
    Default actionNone
    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. 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.

    - -
    Note

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

    -
    -
    -
    - - -
    -
    -
    mousemove
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typemousemove
    InterfaceMouseEvent
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    Default actionNone
    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. -

    - -
    Note

    Authoring Note: 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. -

    - -
    Note

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

    -
    -
    -
    - - -
    -
    -
    mouseout
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typemouseout
    InterfaceMouseEvent
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    Default actionNone
    Context
    (trusted events)    		 - -
    - -

    A user agent MUST dispatch this event when a pointing device is moved off of the boundaries of an element. 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.

    - -
    Note

    Note: See also the mouseover event type.

    -
    -
    -
    - - -
    -
    -
    mouseover
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typemouseover
    InterfaceMouseEvent
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    Default actionNone
    Context
    (trusted events)    		 - -
    - -

    A user agent MUST dispatch this event when a pointing device is moved onto the boundaries of an element. 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.

    - -
    Note

    Note: See also the mouseout event type.

    -
    -
    -
    - - -
    -
    -
    mouseup
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typemouseup
    InterfaceMouseEvent
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    Default actionInvoke 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.

    - -
    Note

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

    - -
    Note

    Authoring Note: 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 Event Types

    -

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

    - -
    Note

    Authoring Note: - 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. -

    - -
    Note

    Note: - 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 - DocumentEvent.createEvent("WheelEvent") - method call. -

    - - 
    [Constructor(DOMString typeArg, optional WheelEventInit wheelEventInitDict)]
-interface WheelEvent : MouseEvent {
-    // DeltaModeCode
-    const unsigned long DOM_DELTA_PIXEL = 0x00;
-    const unsigned long DOM_DELTA_LINE = 0x01;
-    const unsigned long DOM_DELTA_PAGE = 0x02;
-    readonly    attribute double        deltaX;
-    readonly    attribute double        deltaY;
-    readonly    attribute double        deltaZ;
-    readonly    attribute unsigned long deltaMode;
-};
    5.4.1.1 Attributes
    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. -

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

    -
    5.4.1.2 Constants
    DOM_DELTA_LINE of type unsigned long
    -

    The units of measurement for the delta MUST be - individual lines of text. This is the case for many form controls. -

    -
    DOM_DELTA_PAGE of type unsigned long
    -

    The units of measurement for the delta MUST be - pages, either defined as a single screen or as a demarcated page. -

    -
    DOM_DELTA_PIXEL of type unsigned long
    -

    The units of measurement for the delta MUST be - pixels. This is the most typical case in most operating system and implementation - configurations. -

    -
    - - 
    dictionary WheelEventInit : MouseEventInit {
-    double        deltaX = 0.0;
-    double        deltaY = 0.0;
-    double        deltaZ = 0.0;
-    unsigned long deltaMode = 0;
-};
    5.4.1.3 Dictionary WheelEventInit Members
    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. -

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

    -
    - -
    - -

    The Wheel event types are listed below.

    - - -
    -
    -
    wheel
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typewheel
    InterfaceWheelEvent
    Sync / AsyncAsync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    Default actionScroll (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).

    - -
    Note

    Note: 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.5 Keyboard Event Types

    - -

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

    - -
    Note

    Authoring Note: - 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.5.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: - 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. -

    - - 
    [Constructor(DOMString typeArg, optional KeyboardEventInit keyboardEventInitDict)]
-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;
-    readonly    attribute DOMString     key;
-    readonly    attribute DOMString     code;
-    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 boolean       isComposing;
-    boolean getModifierState (DOMString keyArg);
-};
    5.5.1.1 Attributes
    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.

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

    -
    ctrlKey of type boolean, readonly
    -

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

    - -

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

    -
    key of type DOMString, readonly
    -

    key holds the key value of the key pressed. - If the value is has a printed representation, it MUST be a non-empty Unicode character - string, conforming to the algorithm for determining the key value defined in this specification. - 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

    Note: 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).

    -
    location of type unsigned long, readonly
    -

    The location attribute contains an indication of the 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. In case a DOM implementation wishes to provide a new location value, a - value different from the defined constant values MUST be used.

    - -

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

    -
    metaKey of type boolean, readonly
    -

    true if the meta ('Meta') key modifier was active.

    - -
    Note

    Note: 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.

    -
    shiftKey of type boolean, readonly
    -

    true if the shift ('Shift') key modifier was active.

    - -

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

    -
    5.5.1.2 Methods
    getModifierState
    -

    Queries the state of a modifier using a key value. - See Modifier keys for a list of valid (case-sensitive) arguments to this method. -

    - - -
    ParameterTypeNullableOptionalDescription
    keyArgDOMString✘✘ -

    A modifier key value. Valid modifier keys are defined in the - Modifier Keys table in - [DOM3 key Values]. -

    - -

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

    - -
    Note

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

    -
    Return type: boolean
    5.5.1.3 Constants
    DOM_KEY_LOCATION_LEFT of type unsigned long
    -

    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_NUMPAD of type unsigned long
    -

    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.

    -
    -
    DOM_KEY_LOCATION_RIGHT of type unsigned long
    -

    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_STANDARD of type unsigned long
    -

    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.

    -
    -
    - - 
    dictionary KeyboardEventInit : EventModifierInit {
-    DOMString     key = "";
-    DOMString     code = "";
-    unsigned long location = 0;
-    boolean       repeat = false;
-    boolean       isComposing = false;
-};
    5.5.1.4 Dictionary KeyboardEventInit Members
    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 - [DOM3 code Values]. -

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

    -
    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 modifications (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 - [DOM3 key Values]. -

    -
    location of type unsigned long, defaulting to 0
    -

    Initializes the location attribute of the KeyboardEvent - object to one of the following location numerical constants: -

    -
      -
    • KeyboardEvent.DOM_KEY_LOCATION_STANDARD (numerical value 0)
      • -
    • KeyboardEvent.DOM_KEY_LOCATION_LEFT (numerical value 1)
      • -
    • KeyboardEvent.DOM_KEY_LOCATION_RIGHT (numerical value 2)
      • -
    • KeyboardEvent.DOM_KEY_LOCATION_NUMPAD (numerical value 3)
      • -
    -
    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. -

    -
    - -
    - -
    Warning
    -

    Warning!

    -

    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 - KeyboardEvent.key and - KeyboardEvent.code. -

    -

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

    -
    - -
    Note

    Note: - 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. -

    - -
    Note

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

    - -
    -

    5.5.2 Keyboard Event Order

    -

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

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameNotes
    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 NameNotes
    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)
    - -
    Note

    Note: - 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. -

    - -
    Note

    Note: - 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. -

    -
    - -

    The keyboard event types are listed below.

    - - -
    -
    -
    keydown
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typekeydown
    InterfaceKeyboardEvent
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    Default actionVaries: - beforeinput and input events; - launch text composition system; - blur and focus events; - keypress event; - 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 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.

    - -
    Note

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

    -
    -
    -
    - - -
    -
    -
    keyup
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typekeyup
    InterfaceKeyboardEvent
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    Default actionNone
    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.

    - -
    Note

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

    -
    -
    -
    -
    - -
    -

    5.6 Composition Event Types

    - -

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

    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.6.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 DocumentEvent.createEvent("CompositionEvent") - method call.

    - - 
    [Constructor(DOMString typeArg, optional CompositionEventInit compositionEventInitDict)]
-interface CompositionEvent : UIEvent {
-    readonly    attribute DOMString data;
-};
    5.6.1.1 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 the empty string. -

    - -

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

    -
    - - 
    dictionary CompositionEventInit : UIEventInit {
-    DOMString data = "";
-};
    5.6.1.2 Dictionary CompositionEventInit Members
    data of type DOMString, defaulting to ""
    -

    Initializes the data attribute of the CompositionEvent - object to the characters generated by the IME composition. -

    -
    - -
    - -
    -

    5.6.2 Composition Event Order

    - -

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

    - - - - - - - - - - - - - - - - - - - - - - -
    Event NameNotes
    1.compositionstart
    2.compositionupdateMultiple events
    3.compositionend
    -
    - -
    -

    5.6.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 NameCompositionEvent
    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.6.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 NameNotes
    1.keydownThe default action is - prevented, e.g., by invoking Event.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 NameNotes
    1.keydown
    2.compositionstartThe default action is - prevented, e.g., by invoking Event.preventDefault(). -
    No Composition Events are dispatched
    3.compositionend
    4.keyup
    -
    - -
    -

    5.6.5 Key Events During Composition

    -

    During the composition session, all keydown - and keyup events MAY be suppressed.

    - -
    -
    5.6.5.1 Including Key Events During Composition
    - -

    If a user agent does not suppress these events during - composition, then it MUST set the key event's - isComposing - attribute to true for any events that occur during a composition session. -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboardEvent
    isComposing    		Notes
    1.keydownfalseThis is the key event that initiates the composition.
    2.compositionstart
    3.compositionupdate
    4.keyuptrue
    ...Any key events sent during the composition session MUST have isComposing set to true.
    5.keydowntrueThis is the key event that exits the composition.
    6.compositionend
    7.keyupfalse
    - -
    - -
    -
    5.6.5.2 Suppressing Key Events During Composition
    - -

    If key events are suppressed between - compositionstart and - compositionend, then the first - or last key pressed might result in unmatched - keydown and - keyup events. - If a user agent suppresses key events during composition, - then it MUST ensure that all keydown and - keyup events occur in matching pairs. -

    - -

    To ensure that the initial keydown has a - matching keyup, a - user agent might insert an extra - keyup to match the - keydown that initiated a composition session, - as shown in the following example: -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboardEvent
    isComposing    		Notes
    1.keydownfalseThis is the key event that initiates the composition.
    2.compositionstart
    3.compositionupdate
    4.keyuptrueThis event would normally be suppressed because of the ongoing composition session, but it is sent - to match the previously sent keydown - event.
    ...Any other key events that occur during the composition session are suppressed.
    5.compositionend
    - -

    To ensure that the composition session doesn't end with a dangling - keyup event, a - user agent can choose either (A) to suppress this - keyup event, or (B) to insert an extra - keydown event.

    - -

    An example event sequence where both the - keydown and - keyup events have - been suppressed:

    - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboardEvent
    isComposing    		Notes
    keydown for key that exits IME suppressed - during composition session
    1.compositionend
    A keyup event would normally be sent - at this time, but it is suppressed to avoid generating an unmatched - keyup event.
    - -

    An example event sequence where a keydown has been inserted: -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboardEvent
    isComposing    		Notes
    keydown for key that exits IME suppressed - during composition session
    1.compositionend
    2.keydownfalseThis is key event that was suppressed earlier. It is sent now to match the upcoming - keyup.
    3.keyupfalse
    - -
    - -
    - -
    -

    5.6.6 Composition Event Types

    -

    The composition event types are listed below.

    - - -
    -
    -
    compositionstart
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typecompositionstart
    InterfaceCompositionEvent
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    Default actionStart 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.

    - -
    Note

    Note: 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).

    - -
    Note

    Note: 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.

    -
    -
    -
    - - -
    -
    -
    compositionupdate
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typecompositionupdate
    InterfaceCompositionEvent
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableNo
    Default actionNone
    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 CompositionEvent.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 CompositionEvent.data attribute will be set to the - empty string. -

    -
    -
    -
    - - -
    -
    -
    compositionend
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typecompositionend
    InterfaceCompositionEvent
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableNo
    Default actionNone
    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). -

    -
    -
    -
    -
    -
    - -
    - - -
    -

    6. Keyboard events and key values

    - -

    This section contains necessary information regarding keyboard events:

    - -
      -
    • Explanation of keyboard layout, mapping, and key values.
      • -
    • Relations between keys, such as dead keys or modifiers keys.
      • -
    • Relations between keyboard events and their default actions.
      • -
    • The set of key values, and guidelines on how to extend this set.
      • -
    - -
    Note

    Note: This section uses Serbian and Kanji characters which could - be misrepresented or unavailable in the PDF version or printed version of this specification. -

    - -
    -

    6.1 Keyboard Input

    - -

    This section is informative

    - -

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

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

    This specification only defines the functional mapping, in terms of - key values and - code values, - but briefly describes - key legends - for background. -

    - -
    -

    6.1.1 Key Legends

    - -

    This section is informative

    - -

    The key legend is the visual marking that is printed or embossed on the key cap (the rectangular - 'cap' that covers the mechanical switch for the key). - These markings normally consist of one or more characters that a keystroke on that key - will produce (such as - 'F', - '8', or - 'ш'), - or names or symbols which indicate that key's function (such as an upward-pointing arrow - ⇧ indicating 'Shift', - or the string 'Enter'). - Keys are often referred to by this marking - (e.g., Press the 'Shift' and 'F' keys.). - Note, however, that the visual appearance of the key has no bearing on its digital representation, - and in many configurations may be completely inaccurate. - Even the control and function keys, such as 'Enter', MAY be mapped to different - functionality, or even mapped as character keys. -

    - -

    For historical reasons, the character keys are typically marked with the capital-letter equivalents - of the character value they produce, e.g., the 'F' key (the key marked with the glyph - 'F'), will produce the character value 'f' when - pressed without an active modifier key ('Shift') or modifier state - ('CapsLock'). -

    - -
    Note

    Note: - Many keyboards contain keys that do not normally produce any characters, even though the symbol might - have a Unicode equivalent. - For example, the 'Shift' key might bear the symbol - ⇧, which has the - Unicode code point '\u21E7', - but pressing the 'Shift' key will not produce this character value, and - there is no Unicode code point for - 'Shift'. -

    -
    - -
    - -
    -

    6.2 Key codes

    - -

    A key code is an attribute of a keyboard event that can be used to identify the physical - key associated with the keyboard event. It is similar to USB Usage IDs in that it provides - a low-level value (similar to a scancode) that is vendor-neutral. -

    - -

    The primary purpose of the code attribute is to provide a consistent and coherent way - to identify keys based on their physical location. In addition, it also provides a stable name - (unaffected by the current keyboard state) that uniquely identifies each key on the keyboard. -

    - -

    The list of valid code values is defined in the - DOM Level 3 KeyboardEvent code Values Specification [DOM3 code Values]. -

    - -
    -

    6.2.1 Motivation for Adding the code Attribute

    - -

    The standard PC keyboard has a set of keys (which - we refer to as writing system keys) - that generate different key values - based on the current keyboard layout selected by the user. - This situation makes it difficult to write code that detects keys based on their physical - location since the code would need to know which layout is in effect in order to know which - key values to check for. - A real-world example of this is a game that wants to use the - 'W', - 'A', - 'S' and - 'D' - keys to control player movement. - The code attribute solves this problem by providing - a stable value to check that is not affected by the current keyboard layout. -

    - -

    In addition, the values in the key attribute depend as well - on the current keyboard state. - Because of this, the order in which keys are pressed and released in relation to modifier keys - can affect the values stored in the key attribute. - The code attribute solves this problem by providing - a stable value that is not affected by the current keyboard state. -

    -
    - -
    -

    6.2.2 The Relationship Between key and code

    -
    -
    key
    -
    The key attribute is intended for users who are interested in the meaning of the key - being pressed, taking into account the current keyboard layout (and IME; dead keys - are given a unique key value). - Example use case: Detecting modified keys or bare modifier keys (e.g., to perform an action in - response to a keyboard shortcut).
    - -
    code
    -
    The code attribute is intended for users who are interested in the key that was pressed - by the user, without any layout modifications applied. - Example use case: Detecting WASD keys (e.g., for movement controls in a game) or trapping all keys - (e.g., in a remote desktop client to send all keys to the remote host). -
    -
    -
    - -
    -

    6.2.3 code Examples

    -
    -
    -

    Handling the Left and Right Alt Keys

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Keyboard LayoutKeyboardEvent
    key    		KeyboardEvent
    code    		Notes
    US'Alt''AltLeft'DOM_KEY_LOCATION_LEFT
    French'Alt''AltLeft'DOM_KEY_LOCATION_LEFT
    US'Alt''AltRight'DOM_KEY_LOCATION_RIGHT
    French'AltGr''AltRight'DOM_KEY_LOCATION_RIGHT
    -

    In this example, checking the key attribute permits matching 'Alt' without worrying about which Alt key (left or right) was pressed. - Checking the code attribute permits matching the right Alt key ('AltRight') without worrying about which layout is currently in effect. -

    -

    Note that, in the French example, the 'Alt' and - 'AltGr' keys retain their left and right location, even through there - is only one of each key. -

    -
    - -
    -
    -

    Handling the Single Quote Key

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Keyboard LayoutKeyboardEvent
    key    		KeyboardEvent
    code    		Notes
    US''''Quote'
    Japanese':''Quote'
    US Intl'Dead''Quote'
    -

    This example shows how dead key values are encoded in the attributes. The - key values vary based on the current locale, whereas the code attribute - returns a consistent value. -

    -
    - -
    -
    -

    Handling the '2' Key (with and without Shift pressed)

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Keyboard LayoutKeyboardEvent
    key    		KeyboardEvent
    code    		Notes
    US'2''Digit2'
    US'@''Digit2'shiftKey
    UK'2''Digit2'
    UK'"''Digit2'shiftKey
    French'é''Digit2'
    French'2''Digit2'shiftKey
    -

    Regardless of the current locale or the modifier key state, pressing the key labelled '2' - on a US keyboard always results in 'Digit2' in the code attribute. -

    -
    - -
    -
    -

    Sequence of Keyboard Events : 'Shift' and '2'

    -

    Compare the attribute values in the following two key event sequences. They both produce the - '@' character on a US keyboard, but differ in the order in which the - keys are released. In the first sequence, the order is: - 'Shift' (down), - '2' (down), - '2' (up), - 'Shift' (up). -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboard LayoutKeyboardEvent
    key    		KeyboardEvent
    code    		Notes
    1.keydownUS'Shift''ShiftLeft'DOM_KEY_LOCATION_LEFT
    2.keydownUS'@''Digit2'shiftKey
    3.keypressUS'@'''
    4.keyupUS'@''Digit2'shiftKey
    5.keyupUS'Shift''ShiftLeft'DOM_KEY_LOCATION_LEFT
    -

    In the second sequence, the Shift is released before the 2, resulting in the following event order: - 'Shift' (down), - '2' (down), - 'Shift' (up), - '2' (up). -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboard LayoutKeyboardEvent
    key    		KeyboardEvent
    code    		Notes
    1.keydownUS'Shift''ShiftLeft'DOM_KEY_LOCATION_LEFT
    2.keydownUS'@''Digit2'shiftKey
    3.keypressUS'@'''
    4.keyupUS'Shift''ShiftLeft'DOM_KEY_LOCATION_LEFT
    5.keyupUS'2''Digit2'
    -

    Note that the values contained in the key attribute does not match between - the keydown and keyup events for the '2' key. The code attribute provides a consistent value - that is not affected by the current modifier state. -

    -
    -
    - -
    -

    6.2.4 code and Virtual Keyboards

    -

    The usefulness of the code attribute is less obvious for virtual keyboards (and also - for remote controls and chording keyboards). - In general, if a virtual (or remote control) keyboard is mimicking the layout and functionality - of a standard keyboard, then it MUST also set the code attribute as appropriate. - For keyboards which are not mimicking the layout of a standard keyboard, then the code - attribute MAY be set to the closest match on a standard keyboard or it MAY be left undefined. -

    -

    For virtual keyboards with keys that produce different values based on some modifier state, - the code value should be the key value - generated when the button is pressed while the device is in its factory-reset state. -

    -
    - -
    - -
    -

    6.3 Keyboard Event key Values

    - -

    A key value is a DOMString that can be used to indicate any given key on a keyboard, regardless of position or state, by the value it produces. These - key values MAY be used as return values for keyboard events generated by the implementation, or as input values by the content author to specify desired input (such - as for keyboard shortcuts). -

    - -

    The list of valid key values is defined in the - DOM Level 3 KeyboardEvent key Values Specification [DOM3 key Values]. -

    - -

    Key values can be used to detect the value of a key which has been pressed, using the KeyboardEvent.key - attribute. Content authors can retrieve the - character value of upper- or lower-case letters, number, symbols, or other character-producing keys, and also the key - value of control keys, modifier keys, function keys, or other keys that do not generate characters. These values can be used for monitoring particular - input strings, for detecting and acting on modifier key input in combination with other inputs (such as a mouse), for creating virtual keyboards, or for any number - of other purposes.

    - -

    Key values can also be used by content authors in string comparisons, as values for markup attributes (such as the HTML accesskey) in conforming host languages, or for other related purposes. A conforming host language - SHOULD allow content authors to use either of the two equivalent string values for a key value: the character value, - or the key value.

    - -
    Note

    Note: While implementations will use the most relevant value for a key independently of the platform or keyboard layout mappings, - content authors can not make assumptions on the ability of keyboard devices to generate them. When using keyboard events and key values for shortcut-key combinations, - content authors can consider using numbers and function keys (F4, F5, and so on) instead of letters ([DWW95]) - given that most keyboard layouts will provide keys for those.

    - -

    A key value does not indicate a specific key on the physical keyboard, nor does it reflect the character printed on the key. A key - value indicates the current value of the event with consideration to the current state of all active keys and key input modes - (including shift modes), as reflected in the operating-system mapping of the keyboard and reported to the implementation. In other - words, the key value for the key marked 'O' on a QWERTY keyboard - has the key value 'o' in an unshifted state and 'O' in a shifted state. - Because a user can map their keyboard to an arbitrary custom configuration, the content author is encouraged not to assume that a - relationship exists between the shifted and unshifted states of a key and the majuscule form (uppercase or capital letters) - and minuscule form (lowercase or small letters) of a character representation, but is encouraged instead to use the value of the - KeyboardEvent.key attribute. For example, the Standard "102" Keyboard layout - depicted in [DOM3 code Values] illustrates one possible set of - key mappings on one possible keyboard layout. Many others exist, both standard and - idiosyncratic.

    - -
    Note

    Note: To simplify dead key support, when the operating-system - mapping of the keyboard is handling a dead key state, the current state of the dead - key sequence is not reported via the KeyboardEvent.key attribute. Rather, a key value of - 'Dead' is reported. Instead, implementations generate composition events - which contain the intermediate state of the dead key sequence reported via the - CompositionEvent.data attribute. As in the previous example, the key value for - the key marked 'O' on a QWERTY keyboard has a - CompositionEvent.data value of 'ö' in an unshifted - state during a dead-key operation to add an umlaut diacritic, and 'Ö' in a shifted state during a dead-key - operation to add an umlaut diacritic.

    - -

    It is also important to note that there is not a one-to-one relationship between key event states and key values. A particular key value might be associated with - multiple keys. For example, many standard keyboards contain more than one key with the 'Shift' key value (normally distinguished by the - KeyboardEvent.location values DOM_KEY_LOCATION_LEFT - and DOM_KEY_LOCATION_RIGHT) or '8' key value (normally - distinguished by the KeyboardEvent.location values - DOM_KEY_LOCATION_STANDARD - and DOM_KEY_LOCATION_NUMPAD), and user-configured - custom keyboard layouts MAY duplicate any key value in multiple key-state scenarios (note that KeyboardEvent.location - is intended for standard keyboard layouts, and cannot always indicate a meaningful distinction).

    - -

    Finally, the meaning of any given character representation is context-dependent and complex. For example, in some contexts, the asterisk (star) glyph ('*') represents a footnote or emphasis (when bracketing a passage of text). However, in some documents or executable programs it is equivalent - to the mathematical multiplication operation, while in other documents or executable programs, that function is reserved for the multiplication symbol ('×', - Unicode value '\u00D7') or the Latin small letter 'x' (due to the lack of a multiplication key on many keyboards - and the superficial resemblance of the glyphs '×' and 'x'). Thus, the semantic meaning or function of - character representations is outside the scope of this specification.

    - -
    -

    6.3.1 Key Values and Unicode

    - -

    The character values described in this specification are Unicode [Unicode] - codepoints, and as such, have certain advantages.

    - -

    The most obvious advantage is that it allows the content author to use the full range of internationalized language functionality available in the implementation, - regardless of the limitations of the text input devices on the system. This opens up possibilities for virtual keyboards and Web-application-based input method editors.

    - -

    Another benefit is that it allows the content author to utilize the Unicode general category properties programmatically.

    - -

    With legacy keyboard event attributes such as keyCode and charCode, content authors are forced to - filter key input using cryptic, platform- and implementation-specific numeric codes, with poor internationalization, such as the following pseudocode:

    - -
    -
    -
    if ( ( event.charCode == 45 || event.charCode == 36 ) ||
-     ( event.charCode >= 48 && event.charCode <= 57 ) ||
-     ( event.charCode >= 96 && event.charCode <= 105 ) ) {
-   // minus sign, dollar sign, and numeric characters from keyboard and numpad
-   // ...
-}
-else if ( ( event.charCode >= 65 && event.charCode <= 90 ) ||
-          ( event.charCode >= 97 && event.charCode <= 122 ) ) {
-   // alphabetic characters from Latin character set, A-Z, a-z
-   // ...
-}
-else {
-   // ...
-}
-
    -
    - -

    With key values and regular expressions, however, content authors can support selective and intuitive ranges for key-based input, in a cross-platform manner with - advanced internationalization support, such as the following pseudocode:

    - -
    -
    -
    if ( event.key == "-" || event.key.match("\p{Sc}") || event.key.match("\p{N}") ) {
-   // minus sign, any currency symbol, and numeric characters (regardless of key location)
-   // ...
-}
-else if ( event.key.match("\p{L}") ) {
-   // alphabetic characters from any language, upper and lower case
-   // ...
-}
-else {
-   // ...
-}
-
    -
    - -

    In addition, because Unicode categorizes each assigned code point into a group of code points used by a particular - human writing system, even more advanced capabilities are possible.

    - -
    -
    -

    A content author can match characters from a particular human script (e.g., Tibetan) using a regular expression such as - \p{Tibetan}, to filter out other characters, or discover if a code point is in - a certain code block (range of code points), using a regular expression like \p{InCyrillic}.

    -
    - -

    To facilitate this, implementations SHOULD support Unicode range detection using regular expressions, in a manner such as the Perl Compatible Regular Expressions - (PCRE) [PCRE].

    -
    - -
    -

    6.3.2 Modifier keys

    - -

    Keyboard input uses modifier keys to change the normal behavior of a key. - Like other keys, modifier keys generate - keydown - and - keyup - events, as shown in the example below. - Some modifiers are activated while the key is being pressed down or maintained pressed such as - 'Alt', - 'Control', - 'Shift', - 'AltGraph', - or - 'Meta'. - Others modifiers are activated depending on their state such as - 'CapsLock', - 'NumLock', - or - 'ScrollLock'. - Change in the state happens when the modifier key is being pressed down. - The - KeyboardEvent - interface provides convenient attributes for some common modifiers keys: - KeyboardEvent.ctrlKey, - KeyboardEvent.shiftKey, - KeyboardEvent.altKey, - KeyboardEvent.metaKey. - Some operating systems simulate the - 'AltGraph' - modifier key with the combination of the - 'Alt' - and - 'Control' - modifier keys. - Implementations are encouraged to use the - 'AltGraph' - modifier key. -

    - -

    The following example describes a possible sequence of events associated with the generation of the Unicode character Q (Latin Capital Letter Q, Unicode code point '\u0051') on a US keyboard using a US mapping:

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboardEvent
    key    		ModifiersNotes
    1.keydown'Shift'shiftKey
    2.keydown'Q'shiftKeyLatin Capital Letter Q
    3.beforeinput'Q'
    4.input
    5.keyup'Q'shiftKey
    6.keyup'Shift'
    -
    - -

    The following example describes an alternate sequence of keys to the example above, where the 'Shift' key is released before the 'Q' key. The key value for the key labeled 'Q' will revert to its unshifted value for the - keyup event:

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboardEvent
    key    		ModifiersNotes
    1.keydown'Shift'shiftKey
    2.keydown'Q'shiftKeyLatin Capital Letter Q
    3.beforeinput'Q'
    4.input
    5.keyup'Shift'
    6.keyup'q'Latin Small Letter Q
    -
    - -

    The following example describes a possible sequence of keys that does not generate a Unicode character (using the same configuration):

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboardEvent
    key    		ModifiersNotes
    1.keydown'Control'ctrlKey
    2.keydown'v'ctrlKeyLatin Small Letter V
    No beforeinput or input events are generated.
    3.keyup'v'ctrlKeyLatin Small Letter V
    4.keyup'Control'
    -
    - -

    The following example shows the sequence of events when both 'Shift' and - 'Control' are pressed:

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboardEvent
    key    		ModifiersNotes
    1.keydown'Control'ctrlKey
    2.keydown'Shift'ctrlKey - shiftKey
    3.keydown'V'ctrlKey - shiftKeyLatin Capital Letter V
    No beforeinput or input events are generated.
    4.keyup'V'ctrlKey - shiftKeyLatin Capital Letter V
    5.keyup'Shift'ctrlKey
    6.keyup'Control'
    -
    - -

    For non-US keyboard layouts, the sequence of events is the same, but the value of the key is based on the current - keyboard layout. The following example shows a sequence of events when an Arabic keyboard layout is used:

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboardEvent
    key    		ModifiersNotes
    1.keydown'Control'ctrlKey
    2.keydown'ر'ctrlKeyArabic Letter Reh
    3.keyup'ر'ctrlKeyArabic Letter Reh
    4.keyup'Control'
    -
    - -
    Note

    Note: - The value in the keydown and keyup events varies based on the current keyboard - layout in effect when the key is pressed. - This means that the 'v' key on a US layout and the - 'ر' key on an Arabic layout will generate different - events even though they are the same physical key. - To identify these events as coming from the same physical key, you will need - to make use of the code attribute. -

    - -

    In some cases, modifier keys change the key value value for a key event. - For example, on some MacOS keyboards, the key labeled 'delete' - functions the same as the 'Backspace' key on the - Windows OS when unmodified, but when modified by the 'Fn' - key, acts as the 'Delete' key, and the value of the - key value will match the most appropriate function of the key in its current - modified state. -

    - -
    - -
    -

    6.3.3 Dead keys

    - -

    Some keyboard input uses dead keys for the input of composed character sequences. Unlike the handwriting sequence, - in which users enter the base character first, keyboard input requires to enter a special state when a dead key is - pressed and emit the character(s) only when one of a limited number of legal base character is entered.

    - -
    Note

    Note: The MacOS and Linux operating systems use input methods to process - dead keys. -

    - -

    The dead keys (across all keyboard layouts and mappings) are represented by the - key value 'Dead'. In response to any dead key press, - composition events must be dispatched by the user agent and the - compositionupdate event's - CompositionEvent.data value must be the character value of the current state - of the dead key combining sequence.

    - -

    While Unicode combining characters always follow the handwriting sequence, with the - combining character trailing the corresponding letter, typical dead key input MAY reverse the sequence, with the - combining character before the corresponding letter. For example, the word naïve, using the combining diacritic - ¨, would be represented sequentially in Unicode as nai¨ve, but MAY be typed na¨ive. The sequence - of keystrokes '\u0302' (Combining Circumflex Accent key) and '\u0065' - (key marked with the Latin Small Letter E) will likely produce (on a French keyboard using a french mapping and without - any modifier activated) the Unicode character 'ê' (Latin Small Letter E With Circumflex), as - preferred by the Unicode Normalization Form NFC:

    - -
    Note

    Note: The keydown and keyup events shown in these - examples would normally be suppressed during the composition session. - They are included in these examples to make the user actions (pressing and releasing keys) more apparent. -

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboardEvent
    key    		KeyboardEvent
    isComposing    		CompositionEvent
    data    		Notes
    1.keydown'Dead'falseCombining Circumflex Accent (Dead Key)
    2.compositionstart''
    3.compositionupdate'\u0302'
    4.keyup'Dead'true
    5.keydown'ê'true
    6.compositionupdate'ê'
    7.compositionend'ê'
    8.keyup'e'falseLatin Small Letter E
    -
    - -
    Note

    Note: In the second keydown event (step 5), the key value - (assuming the event is not suppressed) will - not be 'e' (Latin Small Letter E key) under normal circumstances - because the value delivered to the user agent will already be modified by the dead key operation.

    - -

    This process might be aborted when a user types an unsupported base character (that is, a base character for which the which the active diacritical mark is not - available) after pressing a dead key:

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboardEvent
    key    		KeyboardEvent
    isComposing    		CompositionEvent
    data    		Notes
    1.keydown'Dead'falseCombining Circumflex Accent (Dead Key)
    2.compositionstart''
    3.compositionupdate'\u0302'
    4.keyup'Dead'true
    5.keydown'q'trueLatin Small Letter Q
    6.compositionupdate''
    7.compositionend''
    8.keyup'q'false
    -
    -
    - -
    -

    6.3.4 Input Method Editors

    - -

    This specification includes a model for input method editors (IMEs), through the CompositionEvent - interface and events. However, Composition Events and Keyboard Events do not necessarily map as a one-to-one relationship. As an example, receiving a keydown for the 'Accept' key value does not necessarily imply - that the text currently selected in the IME is being accepted, but indicates only that a keystroke happened, disconnected - from the IME Accept functionality (which would normally result in a - compositionend event in most IME systems). Keyboard events cannot be used to determine the current - state of the input method editor, which can be obtained through the data attribute of the - CompositionEvent interface. Additionally, IME systems and devices vary in their functionality, and in which keys - are used for activating that functionality, such that the 'Convert' and 'Accept' keys MAY be represented - by other available keys. Keyboard events correspond to the events generated by the input device after the keyboard layout mapping.

    - -
    Note

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

    - -

    The following example describes a possible sequence of keys to generate the Unicode character '市' (Kanji character, part of CJK Unified Ideographs) using Japanese - input methods. This example assumes that the input method editor is activated and in the Japanese-Romaji input mode. The keys 'Convert' - and 'Accept' MAY be replaced by others depending on the input device in use and the configuration of the IME, e.g., it can be respectively - '\u0020' (Space key) and 'Enter'.

    - -
    Note

    Note: '詩' (poem) and '市' (city) are homophones, both - pronounced し (shi), so the user needs to use the 'Convert' key to select the proper option.

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboardEvent
    key    		KeyboardEvent
    isComposing    		CompositionEvent
    data    		Notes
    1.keydown's'falseLatin Small Letter S
    2.compositionstart''
    3.compositionupdate's'
    4.keyup's'true
    5.keydown'i'trueLatin Small Letter I
    6.compositionupdate'し'
    7.keyup'i'true
    8.keydown'Convert'trueConvert
    9.compositionupdate'詩'
    10.keyup'Convert'true
    11.keydown'Convert'trueConvert
    12.compositionupdate'市'
    13.keyup'Convert'true
    14.keydown'Accept'trueAccept
    15.compositionend'市'
    16.keyup'Accept'false
    -
    - -

    IME composition can also be canceled as in the following example, with conditions identical to the previous example. - The key 'Cancel' might also be replaced by others depending on the input device in use and - the configuration of the IME, e.g., it could be '\u001B' (Escape key).

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboardEvent
    key    		KeyboardEvent
    isComposing    		CompositionEvent
    data    		Notes
    1.keydown's'falseLatin Small Letter S
    2.compositionstart''
    3.compositionupdate's'
    4.keyup's'true
    5.keydown'i'trueLatin Small Letter I
    6.compositionupdate'し'
    7.keyup'i'true
    8.keydown'Convert'trueConvert
    9.compositionupdate'詩'
    10.keyup'Convert'true
    11.keydown'Convert'trueConvert
    12.compositionupdate'市'
    13.keyup'Convert'true
    14.keydown'Cancel'trueCancel
    15.compositionupdate''
    16.compositionend''
    17.keyup'Cancel'false
    -
    - -
    Note

    Note: Some input method editors (such as on the MacOS operating system) might set an - empty string to the composition data attribute before canceling a composition.

    - -
    -
    6.3.4.1 Input Method Editor mode keys
    - -

    Some keys on certain devices are intended to activate input method editor functionality, or to change the mode of an active - input method editor. Custom keys for this purpose can be defined for different devices or language modes. The keys defined - in this specification for this purpose are: Alphanumeric, CodeInput, FinalMode, HangulMode, HanjaMode, - Hiragana, JunjaMode, KanaMode, - KanjiMode, Katakana, and RomanCharacters. When one of these keys is pressed, and no IME - is currently active, the appropriate IME is expected to be activated in the mode indicated by the key (if available). If - an IME is already active when the key is pressed, the active IME might change to - the indicated mode, or a different IME might be launched, or the might MAY be ignored, on a device- and application-specific - basis.

    - -

    This specification also defines other keys which are intended for operation specifically with input method editors: - Accept, AllCandidates, Cancel, Convert, Compose, FullWidth, HalfWidth, NextCandidate, - Nonconvert, and PreviousCandidate. The functions of these keys are not defined in this specification — refer to other resources for details - on input method editor functionality.

    - -
    Note

    Note: Keys with input method editor functions are not restricted to that purpose, and can have other device- or implementation-specific - purposes.

    -
    -
    - -
    -

    6.3.5 Default actions and cancelable keyboard events

    - -

    Canceling the - default action - of a - keydown - event MUST NOT affect its respective - keyup - event, but it MUST prevent the respective - beforeinput - and - input - (and - keypress - if supported) events from being generated. - The following example describes a possible sequence of keys to generate the Unicode character - Q (Latin Capital Letter Q) on a US keyboard using a US mapping: -

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboardEvent
    key    		InputEvent
    data    		ModifiersNotes
    1.keydown'Shift'shiftKey
    2.keydown'Q'shiftKeyThe default action is - prevented, e.g., by invoking Event.preventDefault(). -
    No - beforeinput - or - input - (or - keypress, - if supported) events are generated -
    3.keyup'Q'shiftKey
    4.keyup'Shift'
    -
    - -

    If the key is a modifier key, the keystroke MUST still be taken into account for the modifiers states. The following example describes a possible sequence of keys - to generate the Unicode character Q (Latin Capital Letter Q) on a US keyboard using a US mapping:

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboardEvent
    key    		InputEvent
    data    		ModifiersNotes
    1.keydown'Shift'shiftKeyThe default action is - prevented, e.g., by invoking Event.preventDefault(). -
    2.keydown'Q'shiftKey
    3.beforeinput'Q'
    4.input
    5.keyup'Q'shiftKey
    6.keyup'Shift'
    -
    - -

    If the key is part of a sequence of several keystrokes, whether it is a dead key or - it is contributing to an Input Method Editor sequence, the keystroke MUST be ignored (not taken into account) only if the - default action is canceled on the - keydown event. Canceling a - dead key on a - keyup event has no effect on - beforeinput or - input events. - The following example uses the dead key 'Dead' ('\u0302' Combining Circumflex - Accent key) and 'e' ('\u0065', Latin Small Letter E key) on a French - keyboard using a French mapping and without any modifier activated:

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboardEvent
    key    		InputEvent
    data    		Notes
    1.keydown'Dead'The default action is - prevented, e.g., by invoking Event.preventDefault(). -
    2.keyup'Dead'
    3.keydown'e'
    4.beforeinput'e'
    5.input
    6.keyup'e'
    -
    -
    - -
    -

    6.3.6 Guidelines for selecting key values

    - -

    This section is normative.

    - -

    To determine the appropriate key value for a key, use the following algorithm: -

    - -
      -
    1. If there exists an appropriate character in the key values set, - then the - KeyboardEvent.key - attribute MUST be a string consisting of the key value of that character. -
      2. -
    2. If the key generates a printable character, - and there exists an appropriate - Unicode code point, - then the - KeyboardEvent.key - attribute MUST be a string consisting of the char value of that character. -
      3. -
    3. If more than one key is being pressed and the key combination includes one or more modifier keys that result in the key - no longer producing a printable character (e.g., 'Control' + 'a'), - then the key value should be the printable key value that would have been - produced if the key had been typed with the default keyboard layout - with no modifier keys except for 'Shift' and 'AltGr' applied. -
      4. -
    4. Otherwise, the special value 'Unidentified' should be used. -
      5. -
    - -
    -
    -
      -
    • On a US keyboard with a right-handed single-hand Dvorak - key mapping, - the key labeled - 'Q' - maps to the key values - '5' (unmodified) - and - '%' (shifted). - The primary function of this key is to generate the character - '5' ('\u0035'). - Since this character is a character (in Unicode general category - Nd), the - KeyboardEvent.key - attribute value for the unmodified key will be '5'. -
      • -
    • On the same US Dvorak keyboard layout as the previous example, - pressing 'Control' and the key labeled 'Q' - will produce a key value of 'q'. -
      • -
    • On a French PC keyboard with a standard French mapping, the primary function of the - '^' - key is to act as a - dead key - for the combining circumflex diacritical mark. - The value for this key is 'Dead'. -
      • -
    • Also on a French PC keyboard with a standard French mapping, the - 'é' - key (which corresponds to the '2' key on a US keyboard) - generates a key value of 'é' ('\u00e9'). -
      • -
    • On a Korean PC keyboard with a standard Korean mapping, the primary function of the - 'Ha/En' - key is to switch between Hangul and English input. - The predefined key value list has an appropriate entry for this key, - 'HangulMode', - so this will be the key value. -
      • -
    • On some mobile devices, there are special keys to launch specific applications. - For a standard application like Calendar, there is a predefined key value of - 'LaunchCalendar'. -
      • -
    -
    - -

    While every attempt has been made to make this list of key values as complete as possible, new key values - will periodically need to be defined as new input devices are introduced. - Rather than allowing user agents to define their own key values (which may not work across multiple user - agents), bugs should be filed so that this specification can be updated. -

    - -
    -
    - -
    - - -
    -

    A. Legacy Event Initializers

    - -

    This section is informative

    - -

    Early versions of this specification included an initialization method on the - interface (for example initMouseEvent) that required a long list of parameters - that, in most cases, did not fully initialize all attributes of the event object. - Because of this, event interfaces which were derived from the basic Event interface - required that the initializer of each of the derived - interfaces be called explicitly in order to fully initialize an event. -

    - -
    -
    -

    Initializing all the attributes of a UIEvent requires calls to two initializer methods: - initEvent and initUIEvent. -

    -
    - -

    Due in part to the length of time in the development of this standard, some implementations MAY have - taken a dependency on these (now deprecated) initializer methods. - For completeness, these legacy event intializers are described in this Appendix. -

    - -
    -

    A.1 Legacy Event Initializer Interfaces

    -

    This section is informative

    - -

    This section documents legacy initializer methods that were introduced in earlier - versions of this specification. -

    - -
    -

    A.1.1 Initializers for interface CustomEvent

    - - 
    partial interface CustomEvent {
-    // Originally introduced (and deprecated) in this specification
-    void initCustomEvent (DOMString typeArg, boolean bubblesArg, boolean cancelableArg, any detailArg);
-};
    A.1.1.1 Methods
    initCustomEvent
    -

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

    - -
    Warning

    Warning! - The initCustomEvent method is deprecated. -

    - - -
    ParameterTypeNullableOptionalDescription
    typeArgDOMString✘✘

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

    bubblesArgboolean✘✘

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

    cancelableArgboolean✘✘

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

    detailArgany✘✘

    Specifies CustomEvent.detail.

    Return type: void
    -
    - -
    -

    A.1.2 Initializers for interface UIEvent

    - - 
    partial interface UIEvent {
-    // Deprecated in this specification
-    void initUIEvent (DOMString typeArg, boolean bubblesArg, boolean cancelableArg, Window? viewArg, long detailArg);
-};
    A.1.2.1 Methods
    initUIEvent
    -

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

    - -
    Warning

    Warning! - The initUIEvent method is deprecated, but supported for - backwards-compatibility with widely-deployed implementations. -

    - - -
    ParameterTypeNullableOptionalDescription
    typeArgDOMString✘✘ -

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

    -
    bubblesArgboolean✘✘ -

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

    -
    cancelableArgboolean✘✘ -

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

    -
    viewArgWindow✔✘ -

    Specifies UIEvent.view. This value MAY be null.

    -
    detailArglong✘✘ -

    Specifies UIEvent.detail.

    -
    Return type: void
    -
    - -
    -

    A.1.3 Initializers for interface FocusEvent

    - - 
    partial interface FocusEvent {
-    // Originally introduced (and deprecated) in this specification
-    void initFocusEvent (DOMString typeArg, boolean bubblesArg, boolean cancelableArg, Window? viewArg, long detailArg, EventTarget? relatedTargetArg);
-};
    A.1.3.1 Methods
    initFocusEvent
    -

    Initializes attributes of a FocusEvent object. - This method has the same behavior as - UIEvent.initUIEvent(). -

    - -
    Warning

    Warning! - The initFocusEvent method is deprecated. -

    - - -
    ParameterTypeNullableOptionalDescription
    typeArgDOMString✘✘

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

    bubblesArgboolean✘✘

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

    cancelableArgboolean✘✘

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

    viewArgWindow✔✘

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

    detailArglong✘✘

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

    relatedTargetArgEventTarget✔✘

    Specifies FocusEvent.relatedTarget. This value MAY be null.

    Return type: void
    -
    - -
    -

    A.1.4 Initializers for interface MouseEvent

    - - 
    partial interface MouseEvent {
-    // Deprecated in this specification
-    void initMouseEvent (DOMString typeArg, boolean bubblesArg, boolean cancelableArg, Window? viewArg, long detailArg, long screenXArg, long screenYArg, long clientXArg, long clientYArg, boolean ctrlKeyArg, boolean altKeyArg, boolean shiftKeyArg, boolean metaKeyArg, short buttonArg, EventTarget? relatedTargetArg);
-};
    A.1.4.1 Methods
    initMouseEvent
    -

    Initializes attributes of a MouseEvent object. - This method has the same behavior as UIEvent.initUIEvent(). -

    - -
    Warning

    Warning! - The initMouseEvent method is deprecated, but supported for - backwards-compatibility with widely-deployed implementations. -

    - - -
    ParameterTypeNullableOptionalDescription
    typeArgDOMString✘✘ -

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

    -
    bubblesArgboolean✘✘ -

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

    -
    cancelableArgboolean✘✘ -

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

    -
    viewArgWindow✔✘ -

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

    -
    detailArglong✘✘ -

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

    -
    screenXArglong✘✘ -

    Specifies MouseEvent.screenX.

    -
    screenYArglong✘✘ -

    Specifies MouseEvent.screenY.

    -
    clientXArglong✘✘ -

    Specifies MouseEvent.clientX.

    -
    clientYArglong✘✘ -

    Specifies MouseEvent.clientY.

    -
    ctrlKeyArgboolean✘✘ -

    Specifies MouseEvent.ctrlKey.

    -
    altKeyArgboolean✘✘ -

    Specifies MouseEvent.altKey.

    -
    shiftKeyArgboolean✘✘ -

    Specifies MouseEvent.shiftKey.

    -
    metaKeyArgboolean✘✘ -

    Specifies MouseEvent.metaKey.

    -
    buttonArgshort✘✘ -

    Specifies MouseEvent.button.

    -
    relatedTargetArgEventTarget✔✘ -

    Specifies MouseEvent.relatedTarget. This value MAY be null.

    -
    Return type: void
    -
    - -
    -

    A.1.5 Initializers for interface WheelEvent

    - - 
    partial interface WheelEvent {
-    // Originally introduced (and deprecated) in this specification
-    void initWheelEvent (DOMString typeArg, boolean bubblesArg, boolean cancelableArg, Window? viewArg, long detailArg, long screenXArg, long screenYArg, long clientXArg, long clientYArg, short buttonArg, EventTarget? relatedTargetArg, DOMString modifiersListArg, double deltaXArg, double deltaYArg, double deltaZArg, unsigned long deltaMode);
-};
    A.1.5.1 Methods
    initWheelEvent
    -

    Initializes attributes of a WheelEvent object. - This method has the same behavior as - MouseEvent.initMouseEvent(). -

    - -
    Warning

    Warning! - The initWheelEvent method is deprecated. -

    - - -
    ParameterTypeNullableOptionalDescription
    typeArgDOMString✘✘

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

    bubblesArgboolean✘✘

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

    cancelableArgboolean✘✘

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

    viewArgWindow✔✘

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

    detailArglong✘✘

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

    screenXArglong✘✘

    Refer to the MouseEvent.initMouseEvent() method for a description of this parameter.

    screenYArglong✘✘

    Refer to the MouseEvent.initMouseEvent() method for a description of this parameter.

    clientXArglong✘✘

    Refer to the MouseEvent.initMouseEvent() method for a description of this parameter.

    clientYArglong✘✘

    Refer to the MouseEvent.initMouseEvent() method for a description of this parameter.

    buttonArgshort✘✘

    Refer to the MouseEvent.initMouseEvent() method for a description of this parameter.

    relatedTargetArgEventTarget✔✘

    Refer to the MouseEvent.initMouseEvent() method for a description of this parameter.

    modifiersListArgDOMString✘✘ -

    A white space - separated list of modifier key values to be activated on this object. - As an example, "Control Shift" marks the control and shift modifiers as activated - (the MouseEvent.ctrlKey and - MouseEvent.shiftKey inherited attributes - will be true on the initialized WheelEvent object). -

    -
    deltaXArgdouble✘✘

    Specifies WheelEvent.deltaX.

    deltaYArgdouble✘✘

    Specifies WheelEvent.deltaY.

    deltaZArgdouble✘✘

    Specifies WheelEvent.deltaZ.

    deltaModeunsigned long✘✘

    Specifies WheelEvent.deltaMode.

    Return type: void
    -
    - -
    -

    A.1.6 Initializers for interface KeyboardEvent

    -
    Note

    Note: The argument list to this legacy KeyboardEvent initializer does not include - the detailArg (present in other initializers) and adds the locale argument (see - Changes between different drafts of this specification); it is necessary - to preserve this inconsistency for compatibility with existing implementations.

    - 
    partial interface KeyboardEvent {
-    // Originally introduced (and deprecated) in this specification
-    void initKeyboardEvent (DOMString typeArg, boolean bubblesArg, boolean cancelableArg, Window? viewArg, DOMString keyArg, unsigned long locationArg, DOMString modifiersListArg, boolean repeat, DOMString locale);
-};
    A.1.6.1 Methods
    initKeyboardEvent
    -

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

    - -
    Warning

    Warning! - The initKeyboardEvent method is deprecated. -

    - - -
    ParameterTypeNullableOptionalDescription
    typeArgDOMString✘✘

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

    bubblesArgboolean✘✘

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

    cancelableArgboolean✘✘

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

    viewArgWindow✔✘

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

    keyArgDOMString✘✘

    Specifies KeyboardEvent.key.

    locationArgunsigned long✘✘

    Specifies KeyboardEvent.location.

    modifiersListArgDOMString✘✘

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

    -
    repeatboolean✘✘

    Specifies whether the key event is repeating. See KeyboardEvent.repeat.

    localeDOMString✘✘

    Specifies the locale attribute of the KeyboardEvent. -

    Issue 2

    Should we include locale in this specification now?

    Return type: void
    -
    - -
    -

    A.1.7 Initializers for interface CompositionEvent

    -
    Note

    Note: The argument list to this legacy CompositionEvent initializer does not include - the detailArg (present in other initializers) and adds the locale argument (see - Changes between different drafts of this specification); it is necessary - to preserve this inconsistency for compatibility with existing implementations.

    - 
    partial interface CompositionEvent {
-    // Originally introduced (and deprecated) in this specification
-    void initCompositionEvent (DOMString typeArg, boolean bubblesArg, boolean cancelableArg, Window? viewArg, DOMString dataArg, DOMString locale);
-};
    A.1.7.1 Methods
    initCompositionEvent
    -

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

    - -
    Warning

    Warning! - The initCompositionEvent method is deprecated. -

    - - -
    ParameterTypeNullableOptionalDescription
    typeArgDOMString✘✘

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

    bubblesArgboolean✘✘

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

    cancelableArgboolean✘✘

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

    viewArgWindow✔✘

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

    dataArgDOMString✘✘

    Specifies CompositionEvent.data.

    localeDOMString✘✘

    Specifies the locale attribute of the CompositionEvent. -

    Issue 3

    Should we include locale in this specification now?

    -
    Return type: void
    -
    - -
    -
    - - -
    -

    B. Legacy Key Attributes

    -

    This section is informative

    - -

    This section provides a non-normative description of the attributes that are currently used when - handling keyboard events. -

    - -

    These features were never formally specified and the current browser implementations vary in - significant ways. - The large amount of legacy content, including script libraries, that relies upon detecting the - user agent and acting accordingly means that any - attempt to formalize these legacy attributes and events would risk breaking as much content as - it would fix or enable. - Additionally, these attributes are not suitable for international usage, nor do they address - accessibility concerns. -

    - -

    Therefore, this specification does not normatively define the events and attributes commonly employed - for handling keyboard input, though they MAY be present in - user agents for compatibility with legacy content. - Authors SHOULD use the KeyboardEvent.key attribute - instead of the charCode - and keyCode attributes. -

    - -

    However, for the purpose of documenting the current state of these features and their relation to - normative events and attributes, this section provides an informative description. - For implementations which do support these attributes and events, it is suggested that the definitions - provided in this section be used. -

    - -
    -

    B.1 Legacy KeyboardEvent supplemental interface

    -

    This section is informative

    - -

    Browser support for keyboards has traditionally relied on three ad-hoc attributes, - keyCode, charCode, - and which.

    - -

    All three of these attributes return a numerical code that represents some aspect of the key pressed: - keyCode is an index of the key itself. - charCode is the ASCII value of the character keys. - which is the character value where available and otherwise the key index. - The values for these attributes, and the availability of the attribute, is inconsistent across - platforms, keyboard languages and layouts, user agents, - versions, and even event types. -

    - -
    -
    Interface KeyboardEvent (supplemental)
    -
    -

    Introduced in this specification

    - -

    The partial - KeyboardEvent - interface is an informative extension of the - KeyboardEvent - interface, which adds the - charCode, - keyCode, - and which - attributes.

    - -

    The partial - KeyboardEvent - interface can be obtained by using the - DocumentEvent.createEvent("KeyboardEvent") - method call in implementations that support this extension.

    - - 
    partial interface KeyboardEvent {
-    // The following support legacy user agents
-    readonly    attribute unsigned long charCode;
-    readonly    attribute unsigned long keyCode;
-    readonly    attribute unsigned long which;
-};

    Attributes

    charCode of type unsigned long, readonly
    -

    charCode holds a character value, for - keypress events which - generate character input. - The value is the Unicode reference number (code point) of that character (e.g. - event.charCode = event.key.charCodeAt(0) for printable characters). - For keydown or - keyup events, the - value of charCode is 0. -

    -
    keyCode of type unsigned long, readonly
    -

    keyCode holds a system- and implementation-dependent - numerical code signifying the unmodified identifier associated with the key pressed. - Unlike the KeyboardEvent.key - attribute, the set of possible values are not normatively defined in this specification. - Typically, these value of the keyCode - SHOULD represent the decimal codepoint in - ASCII [RFC20][US-ASCII] - or Windows 1252 [WIN1252], - but MAY be drawn from a different appropriate character set. - Implementations that are unable to identify a key use the key value - '0'. -

    - -

    See Legacy key models for more details on how to - determine the values for keyCode. -

    -
    which of type unsigned long, readonly
    -

    which holds a system- and implementation-dependent numerical code - signifying the unmodified identifier associated with the key pressed. - In most cases, the value is identical to - keyCode. -

    -
    - -
    -
    - -
    -
    dictionary KeyboardEventInit (supplemental)
    -
    -

    Browsers that include support for - keyCode, - charCode, - and - which - in KeyboardEvent should also add the following members to the - KeyboardEventInit dictionary. -

    - -

    The partial - KeyboardEventInit - dictionary is an informative extension of the - KeyboardEventInit - dictionary, which adds - charCode, - keyCode, - and which - members to initialize the corresponding KeyboardEvent attributes.

    - - 
    partial dictionary KeyboardEventInit {
-    unsigned long charCode = 0;
-    unsigned long keyCode = 0;
-    unsigned long which = 0;
-};

    Dictionary KeyboardEventInit Members

    charCode of type unsigned long, defaulting to 0
    -

    Initializes the charCode attribute of the - KeyboardEvent to the Unicode code point for the event's character. -

    -
    keyCode of type unsigned long, defaulting to 0
    -

    Initializes the keyCode attribute of the - KeyboardEvent to the system- and implementation-dependent - numerical code signifying the unmodified identifier associated with the key pressed. -

    -
    which of type unsigned long, defaulting to 0
    -

    Initializes the which attribute of the KeyboardEvent - to the implementation-dependent numerical code - signifying the unmodified identifier associated with the key pressed. - In most cases, the value is identical to - keyCode. -

    -
    -
    -
    - -
    - -
    -

    B.2 Legacy key models

    -

    This section is informative

    - -

    Implementations differ on which values are exposed on these attributes for different event types. - An implementation MAY choose to expose both virtual key codes and character codes in the - keyCode property (conflated model), or report - separate keyCode and charCode - properties (split model). -

    - -
    -

    B.2.1 How to determine keyCode for keydown and keyup events

    - -

    The keyCode for - keydown - or keyup events is calculated - as follows: -

    - -
      -
    1. Read the virtual key code from the operating system's event information, if such information - is available.
      2. -
    2. If an Input Method Editor is processing key input and the event is - keydown, return 229.
      3. -
    3. If input key when pressed without modifiers would insert a numerical character (0-9), - return the ASCII code of that numerical character.
      4. -
    4. If input key when pressed without modifiers would insert a lower case character in the - a-z alphabetical range, return the ASCII code of the upper case equivalent.
      5. -
    5. If the implementation supports a key code conversion table for the operating system and platform, - look up the value. If the conversion table specifies an alternate virtual key value for the given - input, return the specified value.
      6. -
    6. If the key's function, as determined in an implementation-specific way, corresponds to one of - the keys in the table of fixed virtual key codes, - return the corresponding key code.
      7. -
    7. Return the virtual key code from the operating system.
      8. -
    8. If no key code was found, return 0.
      9. -
    -
    - -
    -

    B.2.2 How to determine keyCode for keypress events

    - -

    The keyCode for - keypress events is - calculated as follows: -

    - -
      -
    1. If the implementation supports a conflated model, set keyCode - to the Unicode code point of the character being entered.
      2. -
    2. If the implementation supports a split model, set keyCode to 0.
      3. -
    -
    - -
    -

    B.2.3 Fixed virtual key codes

    - -

    The virtual key codes for the following keys do not usually change with keyboard layouts - on desktop systems: -

    - - - - - - - - - - - - - - - - - - - - - - - - - -
    KeyVirtual Key
    Code    		Notes
    'Backspace' 8
    'Tab' 9
    'Enter' 13
    'Shift' 16
    'Control' 17
    'Alt' 18
    'CapsLock' 20
    'Escape' 27 Esc
    ' ' 32 Space
    'PageUp' 33
    'PageDown' 34
    'End' 35
    'Home' 36
    'ArrowLeft' 37
    'ArrowUp' 38
    'ArrowRight' 39
    'ArrowDown' 40
    'Delete' 46 Del
    -
    - -
    -

    B.2.4 Optionally fixed virtual key codes

    - -

    The following punctuation characters MAY change virtual codes between keyboard layouts, but reporting - these values will likely be more compatible with legacy content expecting US-English keyboard layout: -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    KeyCharacterVirtual Key
    Code
    Semicolon ';' 186
    Colon ':' 186
    Equals sign '=' 187
    Plus '+' 187
    Comma ',' 188
    Less than sign '<' 188
    Minus '-' 189
    Underscore '_' 189
    Period '.' 190
    Greater than sign '>' 190
    Forward slash '/' 191
    Question mark '?' 191
    Backtick '`' 192
    Tilde '~' 192
    Opening square bracket '[' 219
    Opening curly brace '{' 219
    Backslash '\' 220
    Pipe '|' 220
    Closing square bracket ']' 221
    Closing curly brace '}' 221
    Single quote ''' 222
    Double quote '"' 222
    -
    -
    -
    - - -
    -

    C. Legacy Event Types

    -

    This section is informative

    - -

    This section provides a non-normative description of the event types that are deprecated in - this document. -

    - -

    The purpose of this section is to document the current state of these features and their relation - to normative events. - For implementations which do support these events, it is suggested that the definitions provided - in this section be used. -

    - -

    The following table provides an informative summary of the event types which are deprecated in - this specification. - They are included here for reference and completeness. -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event TypeSync / AsyncBubbling phaseTrusted event target typesDOM interfaceCancelableDefault Action
    DOMActivateSyncYesElementUIEventYesNone
    DOMFocusInSyncYesWindow, ElementFocusEventNoNone
    DOMFocusOutSyncYesWindow, ElementFocusEventNoNone
    keypressSyncYesElementKeyboardEventYesVaries: - launch text composition system; - blur and focus events; - DOMActivate event; - other event
    - -
    -

    C.1 Legacy UIEvent events

    - - -
    -
    -
    DOMActivate
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    TypeDOMActivate
    InterfaceUIEvent
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    Default actionNone
    Context
    (trusted events)    		 - -
    -

    A user agent MUST dispatch this event when a button, link, or other state-changing element is activated. Refer to - Activation triggers and behavior for more details.

    - -
    Warning

    Warning! The DOMActivate event type is defined in this specification for reference and completeness, but this specification - deprecates the use of this event type in favor of the related event type - click. Other specifications MAY define and maintain their own DOMActivate - event type for backwards compatibility.

    - -
    Note

    Note: While DOMActivate and click are not completely equivalent, implemented behavior for the click - event type has developed to encompass the most critical accessibility aspects for which the - DOMActivate event type was designed, and is more widely implemented. Content authors are encouraged - to use the click event type rather than the related - mousedown or mouseup event type to ensure maximum accessibility.

    -
    -
    -
    - -

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

    - -
    -
    -

    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 a user agent conforming to UI Events, 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 - event target has a - DOMActivate event listener - registered. -

    -
    - -
    Note

    Authoring Note: - Don't rely upon the interoperable support of - DOMActivate - in many user agents. - Instead, the click - event type should be used since it will provide more - accessible behavior due to broader implementation support. -

    - -
    Warning

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

    - -
    -

    C.1.1 Activation event order

    - -

    If the DOMActivate event is supported by the - user agent, then the - events MUST be dispatched in a set order relative to each other: - (with only pertinent events listed): -

    - - - - - - - - - - - - - - - - -
    1.click
    2.DOMActivatedefault action, if supported - by the user agent; synthesized; isTrusted="true" -
    3. - All other default actions, - including the activation behavior -
    - -

    If the focused element is activated by a key event, then the following shows the - typical sequence of events (with only pertinent events listed): -

    - - - - - - - - - - - - - - - - - - - - - -
    1.keydownMUST be a key which can activate the element, such as the - 'Enter' or ' ' key, - or the element is not activated -
    2.clickdefault action; synthesized; isTrusted="true"
    3.DOMActivatedefault action, if supported - by the user agent; synthesized; isTrusted="true" -
    4. - All other default actions, - including the activation behavior -
    -
    -
    - -
    -

    C.2 Legacy FocusEvent events

    - - -
    -
    -
    DOMFocusIn
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    TypeDOMFocusIn
    InterfaceFocusEvent
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsWindow, Element
    CancelableNo
    Default actionNone
    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 MUST be dispatched after the event type - focus. -

    - -
    Warning

    Warning! - The DOMFocusIn event type - is defined in this specification for reference and completeness, but this specification - deprecates the use of this event type in favor - of the related event types focus - and focusin. -

    -
    -
    -
    - - -
    -
    -
    DOMFocusOut
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    TypeDOMFocusOut
    InterfaceFocusEvent
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsWindow, Element
    CancelableNo
    Default actionNone
    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 MUST be dispatched after the event type - blur. -

    - -
    Warning

    Warning! - The DOMFocusOut event - type is defined in this specification for reference and completeness, but this specification - deprecates the use of this event type in - favor of the related event types blur - and focusout. -

    -
    -
    -
    - -
    -

    C.2.1 Legacy FocusEvent event order

    - -

    The following is the typical sequence of events when a focus is shifted between elements, - including the deprecated - DOMFocusIn - and DOMFocusOut - events. The order shown assumes that no element is initially focused. -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    User shifts focus
    1.focusinSent before first target element receives focus
    2.focusSent after first target element receives focus
    3.DOMFocusInIf supported
    User shifts focus
    4.focusoutSent before first target element loses focus
    5.focusinSent before second target element receives focus
    6.blurSent after first target element loses focus
    7.DOMFocusOutIf supported
    8.focusSent after second target element receives focus
    9.DOMFocusInIf supported
    -
    - -
    - -
    -

    C.3 Legacy KeyboardEvent events

    - -

    The keypress event is the - traditional method for capturing key events and processing them before the DOM is updated - with the effects of the key press. - Code that makes use of the - keypress - event typically relies on the legacy - charCode, - keyCode, - and which - attributes. -

    - -

    Note that the keypress event - is specific to key events, and has been replaced by the more general event sequence of - beforeinput - and input events. - These new input events are not specific to keyboard actions and can be used to capture - user input regardless of the original source. -

    - - -
    -
    -
    keypress
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Typekeypress
    InterfaceKeyboardEvent
    Sync / AsyncSync
    BubblesYes
    Trusted TargetsElement
    CancelableYes
    Default actionVaries: - launch text composition system; - blur and focus events; - DOMActivate event; - other event
    Context
    (trusted events)    		 - -
    - -

    If supported by a user agent, this event MUST - be dispatched when a key is pressed down, if and only if that key normally produces a - character value. - The keypress 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. - It MUST NOT be fired when using an input method editor. -

    - -

    If this event is canceled, it should prevent the - input - event from firing, in addition to canceling the - default action. -

    - -

    Authors SHOULD use the - beforeinput - event instead of the - keypress - event. -

    - -
    Note

    Note: - The keypress event is traditionally - associated with detecting a character value rather - than a physical key, and might not be available on all keys in some configurations. -

    - -
    Warning
    -

    Warning!

    -

    The keypress event type is defined - in this specification for reference and completeness, but this specification - deprecates the use of this event type. - When in editing contexts, authors can subscribe to the beforeinput event instead. -

    -
    - -
    -
    -
    - -
    -

    C.3.1 keypress event order

    - -

    The keypress - event type MUST be dispatched after the - keydown - event and before the - keyup - event associated with the same key. -

    - -

    The keypress - event type MUST be dispatched after the - beforeinput - event and before the - input - event associated with the same key. -

    - -

    The sequence of key events for user-agents the support the - keypress event - is demonstrated in the following example: -

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Event NameKeyboardEvent
    key    		InputEvent
    data
    1.keydown'a'
    2.beforeinput'a'
    3.keypress'a'
    Any default actions related to this key, such as inserting a - character in to the DOM. -
    4.input
    5.keyup'a'
    -
    -
    -
    -
    - - -
    -

    D. Extending Events

    -

    This section is informative

    - -
    -

    D.1 Introduction

    - -

    This specification defines several interfaces and many events, however, this is not - an exhaustive set of events for all purposes. - To allow content authors and implementers to add desired functionality, this specification - provides two mechanisms for extend this set of interfaces and events without creating conflicts: - custom events - and implementation-specific extensions. -

    -
    - -
    -

    D.2 Custom Events

    - -

    A script author MAY wish to define an application in terms of functional components, with event - types that are meaningful to the application architecture. - The content author can use the CustomEvent interface - to create their own events appropriate to the level of abstraction they are using. -

    - -
    -
    -

    A content author might have created an application which features a dynamically generated bar chart. - This bar chart is meant to be updated every 5 minutes, or when a feed shows new information, or - when the user refreshes it manually by clicking a button. - There are several handlers that have to be called when the chart needs to be updated: - the application has to fetch the most recent data, show an icon to the user that the event is being - updated, and rebuild the chart. - To manage this, the content author can choose to create a custom updateChart event, - which is fired whenever one of the trigger conditions is met: -

    -
    
-var chartData = ...;
-var evt = document.createEvent("CustomEvent");
-evt.initCustomEvent( "updateChart", true, false, { data: chartData });
-document.documentElement.dispatchEvent(evt);
-
    -
    -
    - -
    -

    D.3 Implementation-Specific Extensions

    - -

    While a new event is being designed and prototyped, or when an event is intended for implementation-specific - functionality, it is desirable to distinguish it from standardized events. - Implementors SHOULD prefix event types specific to their implementations with a short string to distinguish - it from the same event in other implementations and from standardized events. - This is similar to the - vendor-specific keyword prefixes - in CSS, though without the dashes ("-") used in CSS, since that can cause problems when used - as an attribute name in Javascript. -

    - -
    -
    -

    A particular browser vendor, FooCorp, might wish to introduce a new event, jump. - This vendor implements fooJump in their browser, using their - vendor-specific prefix: 'foo'. - Early adopters start experimenting with the event, using - someElement.addEventListener("fooJump", doJump, false ), - and provide feedback to FooCorp, who change the behavior of fooJump accordingly. -

    - -

    After some time, another vendor, BarOrg, decides they also want the functionality, but implement - it slightly differently, so they use their own vendor-specific prefix, "bar" in their - event type name: barJump. - Content authors experimenting with this version of the jump event type - register events with BarOrg's event type name. - Content authors who wish to write code that accounts for both browsers can either register each event type - separately with specific handlers, or use the same handler and switch on the name of the event type. - Thus, early experiments in different codebases do not conflict, and the early adopter is able to write - easily-maintained code for multiple implementations. -

    - -

    Eventually, as the feature matures, the behavior of both browsers stabilizes and might converge due to - content author and user feedback or through formal standardization. - As this stabilization occurs, and risk of conflicts decrease, content authors can remove the forked code, - and use the jump event type name (even before it is formally standardized) - using the same event handler and the more generic registration method - someElement.addEventListener( "jump", doJump, false). -

    -
    - -
    -

    D.3.1 Known Implementation-Specific Prefixes

    - -

    At the time of writing, the following event-type name prefixes are known to exist: -

    - - - - - - - - - - - - - - - - - - - - - - - - - - -
    PrefixWeb Engine (Organization)
    moz, MozGecko (Mozilla)
    ms, MSTrident (Microsoft)
    o, OPresto (Opera Software)
    webkitWebKit (Apple, Google, others)
    -
    -
    -
    - - -
    -

    E. Security Considerations

    - -

    This appendix discusses security considerations for UI Events implementations. - The discussion is limited to security issues that arise directly from implementation of the event - model, APIs and events defined in this specification. - Implementations typically support other features like scripting languages, other APIs and - additional events not defined in this document. - These features constitute an unknown factor and are out of scope of this document. - Implementers SHOULD consult the specifications of such features for their respective - security considerations. -

    - -

    Many of the event types defined in this specification are dispatched in response to user actions. - This allows malicious event listeners to gain access to information users would typically consider - confidential, e.g., typos they might have made when filling out a form, if they reconsider their - answer to a multiple choice question shortly before submitting a form, their typing rate or primary - input mechanism. - In the worst case, malicious event listeners could capture all user interactions and submit them - to a third party through means (not defined in this specification) that are generally available - in DOM implementations, such as the XMLHttpRequest interface. -

    - -

    In DOM implementations that support facilities to load external data, events like the - error event can provide access to sensitive information about - the environment of the computer system or network. - An example would be a malicious HTML document that attempts to embed a resource on the local network - or the localhost on different ports. - An embedded DOM application could then listen - for error and load events - to determine which other computers in a network are accessible from the local system or which ports - are open on the system to prepare further attacks. -

    - -

    An implementation of UI Events alone is generally insufficient to perform attacks of this kind - and the security considerations of the facilities that possibly support such attacks apply. - For conformance with this specification, DOM implementations MAY take reasonable steps to ensure that - DOM applications do not get access to confidential - or sensitive information. - For example, they might choose not to dispatch load events to - nodes that attempt to embed resources on the local network. -

    - -
    - - -
    -

    F. Changes

    - -
    -

    F.1 Changes between DOM Level 2 Events and UI Events (formerly DOM Level 3 Events)

    - -

    Numerous clarifications to the interfaces and event types have been made. - The HTMLEvents module is no longer defined in this document. - The focus and blur - events have been added to the UIEvent - module, and the dblclick event has been added to the - MouseEvent module. - This new specification provides a better separation between the DOM event flow, - the event types, and the DOM interfaces. -

    - -
    -

    F.1.1 Changes to DOM Level 2 event flow

    - -

    This new specification introduced the following new concepts in the event flow: -

    - -
      -
    • Event listeners are now ordered. In DOM Level 2, the event ordering was unspecified.
      • -
    • The event flow now includes the Window, to - reflect existing implementations.
      • -
    -
    - -
    -

    F.1.2 Changes to DOM Level 2 event types

    - -

    Many clarifications have been made on the event types. - The conformance is now explicitly defined against the event types, and not only in terms - of interfaces used by the event types. -

    - -

    "MutationEvents" have been deprecated. - Support for namespaced events, present in early drafts of this specification, has also been removed. -

    - -

    For user agents which support the - DOMNodeInserted - and - DOMNodeRemoved - event types, this specification no longer requires that the event type be fired for - Attr nodes. -

    - -

    The resize event type no longer bubbles and the - mousemove event is now cancelable, reflecting existing - implementations. -

    -
    - -
    -

    F.1.3 Changes to DOM Level 2 Events interfaces

    - -
    -
    Interface Event
    -
    The Event interface has one new attribute, - Event.defaultPrevented, - and one new method, - Event.stopImmediatePropagation(). -
    - Event.timeStamp is now a Number - in the ECMAScript binding. - A proposed correction to make the same change in - [DOM3 Core] is forthcoming. -
    - This specification considers the Event.type attribute - to be case-sensitive, while DOM Level 2 Events considers - Event.type to be case-insensitive. -
    - -
    Interface EventTarget
    -
    The method EventTarget.dispatchEvent() - was modified. -
    - -
    Interface MouseEvent
    -
    The MouseEvent interface has one new method - MouseEvent.getModifierState(). -
    - -
    Exception EventException
    -
    The exception EventException is removed in this - specification. - The prior DISPATCH_REQUEST_ERR code is re-mapped to a DOMException of type - InvalidStateError. -
    -
    -
    - -
    -

    F.1.4 New Interfaces

    - -

    The interfaces - CustomEvent, - FocusEvent, - KeyboardEvent, - CompositionEvent, - and WheelEvent - were added to the Events module. -

    -
    -
    - -
    -

    F.2 Changes between different drafts of UI Events (formerly DOM Level 3 Events)

    - -

    The DOM Level 3 Events document was originally developed between 2000 and 2003, and published - as a W3C Note, pending further feedback and interest from implementers. - In 2006, it was picked up for revision and progress on the Recommendation Track, and was - then revised to reflect the current state of implementation and the - needs of script authors. -

    - -

    Despite its status only as a W3C Note, rather than an official Recommendation, DOM 3 Events - saw some implementation, and was also referenced by other specifications, so care - is being taken to cause minimal disruption, while still adapting the specification to the - current environment. -

    - -

    The current specification has been reordered significantly from the earlier W3C Note form, - and also from the structure of DOM2 Events, in order to clarify the material. - New diagrams have been put in place to represent hierarchies and events flows more clearly. - Here are some of the more important changes between drafts: -

    - -
      -
    • The key identifier feature has been renamed key value to disambiguate - them from unique identifiers for keys. -
      • -
    • The - KeyboardEvent - interface was briefly (from 2003-2010) defined to have keyIdentifier - and keyLocation attributes, but these were removed in favor of the current - key - and location - attributes. These attributes were not widely implemented. -
      • -
    • The KeyboardEvent and - CompositionEvent interfaces defined - a locale attribute. This attribute was underspecified and moved to a separate - specification [UIEvents (Keyboard extensions)]. - Need to update this text once locale's locale is finalized
      • -
    • The KeyboardEvent also had a char - attribute that was only used by the - keypress - event. Since the keypress event has been deprecated, this attribute was no longer useful - and was removed. -
      • -
    • The change, submit, and reset events were removed, - since they were specific to HTML forms, and are specified in - [HTML5]. -
      • -
    • The textInput event, originally proposed as a replacement for - keypress, was - removed in favor of the current - beforeinput - and input events. -
      • -
    • Namespaced events have been removed. -
      • -
    • Updated to use Web IDL. -
      • -
    • EventException has been removed. -
      • -
    -
    -
    - - -
    -

    G. Acknowledgements

    - -

    Many people contributed to the DOM specifications (Level 1, 2 or 3), including - participants of the DOM Working Group, the DOM Interest Group, - the WebAPI Working Group, and the WebApps Working Group. - We especially thank the following: -

    - -

    Andrew Watson (Object Management Group), - Andy Heninger (IBM), - Angel Diaz (IBM), - Anne van Kesteren (Opera Software), - Arnaud Le Hors (W3C and IBM), - Arun Ranganathan (AOL), - Ashok Malhotra (IBM and Microsoft), - Ben Chang (Oracle), - Bill Shea (Merrill Lynch), - Bill Smith (Sun), - Björn Höhrmann, - Bob Sutor (IBM), - Charles McCathie-Nevile (Opera Software, Co-Chair), - Chris Lovett (Microsoft), - Chris Wilson (Microsoft), - Christophe Jolif (ILOG), - David Brownell (Sun), - David Ezell (Hewlett-Packard Company), - David Singer (IBM), - Dean Jackson (W3C, W3C Team Contact), - Dimitris Dimitriadis (Improve AB and invited expert), - Don Park (invited), - Doug Schepers (Vectoreal), - Elena Litani (IBM), - Eric Vasilik (Microsoft), - Gavin Nicol (INSO), - Gorm Haug Eriksen (Opera Software), - Ian Davis (Talis Information Limited), - Ian Hickson (Google), - Ian Jacobs (W3C), - James Clark (invited), - James Davidson (Sun), - Jared Sorensen (Novell), - Jeroen van Rotterdam (X-Hive Corporation), - Joe Kesselman (IBM), - Joe Lapp (webMethods), - Joe Marini (Macromedia), - John Robinson (AOL), - Johnny Stenback (Netscape/AOL), - Jon Ferraiolo (Adobe), - Jonas Sicking (Mozilla Foundation), - Jonathan Marsh (Microsoft), - Jonathan Robie (Texcel Research and Software AG), - Kim Adamson-Sharpe (SoftQuad Software Inc.), - Lauren Wood (SoftQuad Software Inc., former Chair), - Laurence Cable (Sun), - Luca Mascaro (HTML Writers Guild), - Maciej Stachowiak (Apple Computer), - Marc Hadley (Sun Microsystems), - Mark Davis (IBM), - Mark Scardina (Oracle), - Martin Dürst (W3C), - Mary Brady (NIST), - Michael Shenfield (Research In Motion), - Mick Goulish (Software AG), - Mike Champion (Arbortext and Software AG), - Miles Sabin (Cromwell Media), - Patti Lutsky (Arbortext), - Paul Grosso (Arbortext), - Peter Sharpe (SoftQuad Software Inc.), - Phil Karlton (Netscape), - Philippe Le Hégaret (W3C, W3C Team Contact and former Chair), - Ramesh Lekshmynarayanan (Merrill Lynch), - Ray Whitmer (iMall, Excite@Home, and Netscape/AOL, Chair), - Rezaur Rahman (Intel), - Rich Rollman (Microsoft), - Rick Gessner (Netscape), - Rick Jelliffe (invited), - Rob Relyea (Microsoft), - Robin Berjon (Expway, Co-Chair), - Scott Hayman (Research In Motion), - Scott Isaacs (Microsoft), - Sharon Adler (INSO), - Stéphane Sire (IntuiLab), - Steve Byrne (JavaSoft), - Tim Bray (invited), - Tim Yu (Oracle), - Tom Pixley (Netscape/AOL), - T.V. Raman (Google). - Vidur Apparao (Netscape) and - Vinod Anupam (Lucent). -

    - -

    Former editors: - Tom Pixley (Netscape Communications Corporation) until July 2002, - Philippe Le Hégaret (W3C) until November 2003, - Björn Höhrmann (Invited Expert) until January 2008, - Doug Schepers (W3C) from March 2008 to May 2011, - and Jacob Rossi (Microsoft) from March 2011 to October 2011. -

    - -

    Contributors: - In the WebApps Working Group, the following people made substantial material contributions - in the process of refining and revising this specification: - Bob Lund (Cable Laboratories), - Cameron McCormack (Invited Expert / Mozilla), - Daniel Danilatos (Google), - Gary Kacmarcik (Google), - Glenn Adams (Samsung), - Hallvord R. M. Steen (Opera), - Hironori Bono (Google), - Mark Vickers (Comcast), - Masayuki Nakano (Mozilla), - Olli Pettay (Mozilla), - Takayoshi Kochi (Google) and - Travis Leithead (Microsoft). -

    - -

    Glossary contributors: - Arnaud Le Hors (W3C) and - Robert S. Sutor (IBM Research). -

    - -

    Test suite contributors: - Carmelo Montanez (NIST), - Fred Drake, - Mary Brady (NIST), - Neil Delima (IBM), - Rick Rivello (NIST), - Robert Clary (Netscape), - with a special mention to Curt Arnold. -

    - -

    Thanks to all those who have helped to improve this specification by sending suggestions and - corrections (please, keep bugging us with your issues!), or writing informative books or Web sites: - Al Gilman, - Alex Russell, - Alexander J. Vincent, - Alexey Proskuryakov, - Arkadiusz Michalski, - Brad Pettit, - Cameron McCormack, - Curt Arnold, - David Flanagan, - Dylan Schiemann, - Erik Arvidsson, - Garrett Smith, - Giuseppe Pascale, - James Su, - Jan Goyvaerts (regular-expressions.info), - Jorge Chamorro, - Kazuyuki Ashimura, - Ken Rehor, - Magnus Kristiansen, - Martijn Wargers, - Martin Dürst, - Michael B. Allen, - Mike Taylor, - Misha Wolf, - Ojan Vafai, - Oliver Hunt, - Paul Irish, - Peter-Paul Koch, - Richard Ishida, - Sean Hogan, - Sergey Ilinsky, - Sigurd Lerstad, - Steven Pemberton, - Tony Chang, - William Edney and - Øistein E. Andersen. -

    - -
    -

    G.1 Production Systems

    - -

    The current drafts of this specification are lovingly hand-crafted in HTML and SVG, using ReSpec - and custom scripts to format the document according to W3C requirements. -

    - -

    Earlier versions of this specification were written in XML — the HTML, OMG IDL, Java and - ECMAScript bindings were all produced automatically. - Thanks to Joe English, author of cost, - which was used as the basis for producing DOM Level 1. - Thanks also to Gavin Nicol, who wrote the scripts which run on top of cost. - Arnaud Le Hors and Philippe Le Hégaret maintained the scripts. -

    - -

    After DOM Level 1, - Xerces - was used as the basis DOM implementation and wish to thank the authors. - Philippe Le Hégaret and Arnaud Le Hors wrote the - Java programs - which are the DOM application. -

    - -

    Thanks also to Jan Kärrman, author of - html2ps, - which was previously used to generate PostScript versions of the specification. -

    -
    -
    - - -
    -

    H. 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 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.
    - -
    body element
    -
    In HTML or XHTML documents, the body element represents the contents of the document. In a well-formed HTML document, the body element is a first descendant of - the root element.
    - -
    bubbling phase
    -
    The process by which an event can be handled by one of the target's ancestors after being handled by the - 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's ancestors before being handled by the - event target. See the description of the capture phase in the context - of event flow for more details.
    - -
    candidate event handlers
    -
    candidate event listeners
    -
    The list of all event listeners that have been registered on the target object in their order of registration. This - list is captured or frozen before event listeners on the target object are dispatched, and released or un-frozen after this set of candidate event - handlers have been dispatched (allowing these event listeners to add or remove additional listeners on other objects in an event's propagation chain, but not affect - the order of listeners that will be invoked on the target object). - -
    Note

    Note: Initially capturing the candidate event handlers prevents infinite loops of event listener dispatch on a given target object.

    -
    - -
    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. In this - specification, character values are denoted as a unicode string (e.g., '\u0020') or a glyph representation of the same code point (e.g., - ' '), and are color coded to help distinguish these two representations. -
    Note

    Note: In source code, some key values, such as non-graphic characters, can be represented using - the character escape syntax of the programming language in use.

    -
    - -
    current event target
    -
    In an event flow, the current event target is the object associated with the event handler that is currently being - dispatched. This object MAY be the event target itself or one of its ancestors. The current event target changes as the - event propagates from object to object through the various phases of the event flow. - The current event target is the value of the Event.currentTarget attribute.
    - -
    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.
    - -
    delta
    -
    The estimated scroll amount (in pixels, lines, or pages) that the user agent will scroll or zoom the page in response to the physical movement of an input device that - supports the WheelEvent interface (such as a mouse wheel or touch pad). The value of a delta (e.g., the deltaX, deltaY, or deltaZ attributes) is to be - interpreted in the context of the current deltaMode property. The relationship between the physical movement of - a wheel (or other device) 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 event target. Each event is an instantiation - of one specific event type.
    - -
    event focus
    -
    Event 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.
    - -
    event focus ring
    -
    An event focus ring is an ordered set of event 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.
    - -
    event handler
    -
    event listener
    -
    An object that implements the EventListener interface and provides an - EventListener.handleEvent() callback method. Event handlers are language-specific. Event handlers are invoked in the context of a particular object - (the current event target) and are provided with the event object itself. - -
    Note

    Note: In JavaScript, user-defined functions are considered to implement the EventListener interface. Thus the - event object will be provided as the first parameter to the user-defined function when it is invoked. Additionally, JavaScript objects can also implement - the EventListener interface when they define a handleEvent method.

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

    Note: There can be interactions between different event orders. For example, a click event might - be modified by a concurrent keydown 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 using the DOM event flow. The event target is the - value of the Event.target attribute.
    - -
    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.
    - -
    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 UI 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 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.
    - -
    key value
    -
    A key value is a character value or multi-character string (such as 'Enter', - 'Tab', or 'MediaTrackNext') 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.
    - -
    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 Modifier keys - for a list of 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 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 current event targets though which an event object will pass - sequentially on the way to and back from the event target. As the event propagates, each current 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.
    - -
    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.
    - -
    target phase
    -
    The process by which an event can be handled by the event target. - See the description of the target phase in the context of event flow for more details.
    - -
    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.
    - -
    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 graphical user interfaces this is the element under the user's pointing device. A user - interface's hit testing facility is used to determine the target. 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
    -
    A subset of the General Category values that are defined for each Unicode code point. This subset contains all the - Letter (Ll, - Lm, - Lo, - Lt, - Lu), - Number (Nd, - Nl, - No), - Punctuation (Pc, - Pd, - Pe, - Pf, - Pi, - Po, - Ps) - and Symbol (Sc, - Sk, - Sm, - So) - category values.
    - -
    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.
    - -
    un-initialized value
    -
    The value of any event attribute (such as Event.bubbles or - Event.currentTarget) before the event has been initialized with Event.initEvent(). The un-initialized - values of an event apply immediately after a new event has been created using the method - DocumentEvent.createEvent().
    - -
    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.
    - -
    Window
    -
    The Window is the object referred to by the current document's browsing context's Window Proxy object as defined in HTML5 [HTML5].
    -
    -
    - - -
    -

    I. References

    - -

    For the latest version of any W3C specification please consult the list of - W3C Technical Reports - available at http://www.w3.org/TR/. -

    - -
    -

    I.1 Normative References

    - -
    -
    [BCP-47] Best Current Practice 47: Tags for Identifying Languages
    -
    A. Phillips, M. Davis, Editors,
    - September 2009.
    - The specification for describing the structure, content, construction, and semantics of language tags - to indicate the human language used. - Available at http://www.rfc-editor.org/rfc/bcp/bcp47.txt. -
    - -
    [DOM2 Events]
    -
    Document Object Model Level 2 Events Specification,
    - T. Pixley, Editor.
    - World Wide Web Consortium, November 2000.
    - This version of the Document Object Model Level 2 Events Specification is http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113.
    - The latest version of Document Object Model Level 2 Events - is available at http://www.w3.org/TR/DOM-Level-2-Events/. -
    - -
    [DOM3 Core]
    -
    Document Object Model Level 3 Core Specification,
    - A. Le Hors, et al., Editors.
    - World Wide Web Consortium, April 2004.
    - This version of the Document Object Model Level 3 Core Specification is http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/.
    - The latest version of DOM Level 3 Core - is available at http://www.w3.org/TR/DOM-Level-3-Core/. -
    - -
    [DOM3 code Values]
    -
    DOM Level 3 KeyboardEvent code Values,
    - G. Kacmarcik, T. Leithead, Editors.
    - World Wide Web Consortium, April 2014.
    - This version of the DOM Level 3 KeyboardEvent code Values is http://www.w3.org/TR/DOM-Level-3-Events-code/.
    -
    - -
    [DOM3 key Values]
    -
    DOM Level 3 KeyboardEvent key Values,
    - G. Kacmarcik, T. Leithead, Editors.
    - World Wide Web Consortium, April 2014.
    - This version of the DOM Level 3 KeyboardEvent key Values is http://www.w3.org/TR/DOM-Level-3-Events-key/.
    -
    - -
    [ECMAScript]
    -
    ECMAScript Language Specification,
    - 5.1 Edition.
    - European Computer Manufacturers Association, Standard ECMA-262, June 2011.
    - This version of the ECMAScript Language is available from http://ecma-international.org/ecma-262/5.1/. -
    - -
    [HTML5]
    -
    HTML 5,
    - I. Hickson, Editor.
    - World Wide Web Consortium, W3C Recommendation, October 2014.
    - This edition of HTML 5 is http://www.w3.org/TR/2014/REC-html5-20141028/.
    - The latest edition of HTML 5 is available at http://www.w3.org/TR/html5/. -
    - -
    [Java]
    -
    The Java Language Specification,
    - J. Gosling, B. Joy, and G. Steele, Authors.
    - Addison-Wesley, September 1996.
    - Available at http://java.sun.com/docs/books/jls. -
    - - -
    [RFC2119] Key words for use in RFCs to indicate Requirement Levels
    -
    S Bradner, 1997.
    - The specification for how to use English to specify normativity, as if it were a technical language. - Available at http://www.ietf.org/rfc/rfc2119.txt. -
    - -
    [UAX #15]
    -
    Unicode Normalization Forms,
    - The Unicode Standard Annex #15. The Unicode Consortium, 2006.
    - The latest version of this annex is available at http://www.unicode.org/reports/tr15/. -
    - -
    [InputEvents]
    -
    Input Events,
    - Ben Peters, Editor.
    - Not yet published. -
    - -
    [UIEvents]
    -
    UI Events,
    - G. Kacmarcik, T. Leithead, Editors.
    - World Wide Web Consortium, W3C Working Group Note, 12 June 2014. -
    - -
    [Unicode]
    -
    The Unicode Standard, Version 5.0,
    - ISBN 0-321-48091-0, as updated periodically by the publication of new versions.
    - See also Versions of the Unicode Standard, - available at http://www.unicode.org/standard/versions/ for - latest version and additional information on versions of the standard and of the Unicode Character Database. -
    - -
    [WEB IDL]
    -
    Web IDL,
    - C. McCormack. 19 April 2012.
    - This version of the Web IDL Candidate Recommendation is: http://www.w3.org/TR/2012/CR-WebIDL-20120419/.
    - The latest version of Web IDL is available at - http://heycam.github.io/webidl/. -
    - -
    [XML Namespaces 1.0]
    -
    Namespaces in XML 1.0,
    - T. Bray, D. Hollander, A. Layman, and R. Tobin, Editors.
    - World Wide Web Consortium, 16 August 2006.
    - This version of the Namespaces in XML 1.0 Specification is http://www.w3.org/TR/2006/REC-xml-names-20060816.
    - The latest version of Namespaces in XML 1.0 - is available at http://www.w3.org/TR/xml-names/. -
    -
    -
    - -
    -

    I.2 Informative References

    -
    -
    [ARIA]
    -
    Accessible Rich Internet Applications (WAI-ARIA) Version 1.0,
    - J. Craig, M. Cooper, R. Schwerdtfeger, L. Seeman, L. Pappas, Editors.
    - World Wide Web Consortium, 18 January 2011.
    - This version of the WAI-ARIA Candidate Recommendation is http://www.w3.org/TR/2011/CR-wai-aria-20110118/.
    - The latest edition of WAI-ARIA is available at http://www.w3.org/TR/wai-aria/. -
    - -
    [CSS2.1]
    -
    Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification,
    - B. Bos, T. Çelik, I. Hickson, H.W. Lie, Editors.
    - World Wide Web Consortium, 07 June 2011.
    - This version of the CSS 2.1 Recommendation is http://www.w3.org/TR/2011/REC-CSS2-20110607/.
    - The latest version of CSS 2.1 is available at http://www.w3.org/TR/CSS2/. -
    - -
    [DOM2 Range]
    -
    Document Object Model (DOM) Level 2 Traversal and Range Specification,
    - J. Kesselman, J. Robie, M. Champion, P. Sharpe, V. Apparao, L. Wood, Editors.
    - World Wide Web Consortium, November 2000. -
    - -
    [DOM3 Load and Save]
    -
    Document Object Model Level 3 Load and Save Specification,
    - J. Stenback, A. Heninger, Editors.
    - World Wide Web Consortium, April 2004.
    - This version of the DOM Level 3 Load and Save Specification is http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407/.
    - The latest version of DOM Level 3 Load and Save - is available at http://www.w3.org/TR/DOM-Level-3-LS/. -
    - -
    [DOM4]
    -
    W3C DOM4,
    - A. van Kesteren, A. Gregor, Ms2ger, Alex Russell, Robin Berjon, Editors.
    - World Wide Web Consortium, Working Draft, 10 July 2014. -
    - -
    [DWW95]
    -
    Developing International Software for Windows 95 and Windows NT: A Handbook for International Software Design,
    - N. Kano, Author.
    - Microsoft Press, 1995. ISBN 1-55615-840-8. -
    - -
    [HTML 4.01]
    -
    HTML 4.01 Specification,
    - D. Raggett, A. Le Hors, and I. Jacobs, Editors.
    - World Wide Web Consortium, December 1999.
    - This version of the HTML 4.01 Recommendation is http://www.w3.org/TR/1999/REC-html401-19991224.
    - The - latest version of HTML 4 is available at http://www.w3.org/TR/html4/. -
    - -
    [HTML Editing]
    -
    HTML Editing APIs,
    - A. Gregor, Editor.
    - World Wide Web Consortium, work in progress, 13 February 2014. -
    - -
    [KeyProps]
    -
    Legacy Keyboard Event Properties,
    - D. Schepers, Editor.
    - World Wide Web Consortium, work in progress, 04 August 2010.
    - This edition of Legacy Keyboard Event Properties is https://dvcs.w3.org/hg/dom3events/raw-file/tip/html/Note-KeyProps.html.
    - The latest edition of Legacy Keyboard Event Properties - is available at https://dvcs.w3.org/hg/dom3events/raw-file/tip/html/Note-KeyProps.html. -
    - -
    [PCRE]
    -
    Perl Compatible Regular Expressions library.
    - Available at http://www.pcre.org/. -
    - -
    [RFC20] ASCII format for Network Interchange
    -
    V. Cerf, 1969.
    - Available at http://tools.ietf.org/rfc/rfc20.txt -
    - -
    [US-ASCII] Coded Character Set - 7-Bit American Standard Code for Information Interchange
    -
    Standard ANSI X3.4-1986, ANSI, 1986. -
    - -
    [UAAG 2.0]
    -
    User Agent Accessibility Guidelines (UAAG) 2.0,
    - J. Allan, K. Ford, J. Richards, J. Spellman, Editors.
    - World Wide Web Consortium, work in progress, 8 March 2010.
    - This version of the UAAG 2.0 specfication is http://www.w3.org/WAI/UA/2010/ED-UAAG20-20100308/.
    - The latest version of UAAG 2.0 is available at http://www.w3.org/TR/UAAG20/. -
    - -
    [WIN1252]
    -
    Windows 1252 a Coded Character Set - 8-Bit.
    - Microsoft Corporation. -
    - -
    [XFORMS]
    -
    XForms 1.1,
    - J. Boyer, Editor.
    - World Wide Web Consortium, work in progress, 20 October 2009.
    - This edition of XForms 1.1 is http://www.w3.org/TR/2009/REC-xforms-20091020/.
    - The latest edition of XForms is available at http://www.w3.org/TR/xforms/. -
    - -
    [XML 1.0]
    -
    Extensible Markup Language (XML) 1.0,
    - T. Bray, J. Paoli, C. M. Sperberg-McQueen, et. al, Editors.
    - World Wide Web Consortium, August 2006.
    - This version of the XML 1.0 Recommendation is http://www.w3.org/TR/2006/REC-xml-20060816/.
    - The latest version of XML 1.0 is available at http://www.w3.org/TR/xml/. -
    -
    -
    -
    - - - diff --git a/w3c-tr.css b/w3c-tr.css deleted file mode 100644 index 9abdf58c..00000000 --- a/w3c-tr.css +++ /dev/null @@ -1,200 +0,0 @@ -/*Proposed Typographic Conventions for W3C TR docs*/ - -/* For usage, see http://www.w3.org/StyleSheets/spec-conventions.html */ - -.element, .attr, .prop, .attr-value, .prop-value { - font-family: monospace; - font-weight: bold; - font-size: 1.1em; -} - -.element { - color: brown; -} - -.attr { - color: darkgreen; -} - -.prop { - color: navy; -} - -code.attr-value { - background-color: lightgreen; - color: midnightblue; -} - -code.prop-value { - background-color: powderblue; - color: midnightblue; -} - -.attribute-value { - background-color: lightgreen; - color: midnightblue; -} - -.property-value { - background-color: powderblue; - color: midnightblue; -} - -var { - font-family: monospace; -} - -dfn { - font-style: italic; -} - -.term { - font-style: italic; -} - -.term-ref { - font-style: normal; -} - -a.term-ref { - color: black; -} - -.issue, .atrisk, .proposal, .warning, .idl { - font-style: normal; -} - -.issue, .atrisk, .proposal, .idl { - border-style: solid; - border-width: 1px; - padding: 0.1em 0.2em 0em; -} - -div.note, p.note, -div.issue, p.issue, -.idl { - padding: .5em; - margin: 1.4em 1em; - border-style: none; - border-left: 0.3em solid; -} - -div.note, p.note { - border-left: thick double; -} - -.note { - color: green; -} - -pre { - font-family: monospace; - font-style: normal; -} - -.idl { - font-family: monospace; - color: black; - background-color: aliceblue; - border-color: lightsteelblue; -} - - -/* Warnings */ - -div.warning, p.warning { - padding: 1em; - margin: 1.4em 1em; - border-style: none; - border-left: 0.3em solid; -} - -.warning { - color: darkred; - background-color: mistyrose; -} - -.warning > strong:before, .warning > p > strong:before { - /* - content: "\025BA"; - content: "\02623"; - content: "\026A1"; - */ - content: "\026A0"; -} - - -/* Issues */ - -.issue { - background-color: white; - color: crimson; - border: thin solid crimson; -} - -.issue > strong:before, .issue > p > strong:before { - /* - content: "\025BA \000a0\000a0"; - content: "\02623 \000a0\000a0"; - content: "\026A1 \000a0\000a0"; - content: "\025CA \000a0\000a0"; - */ - content: "\026A1 \000a0\000a0"; -} - -.issue a { - color: gold; -} - - -/* Proposal */ - -.proposal { - border: green dotted 2px; -} - -i.proposal { - border-width: 1px; -} - -.atrisk { - background-color: lavenderblush; - border: red dashed 1.5px; -} - -.change { - background-color: greenyellow; -} - - -/* Example */ - -.example { -/* border-bottom: 1px solid orange; - border-top: 1px solid orange; -*//* background-color: lightyellow;*/ - border-bottom: 1px solid #FF4500; - border-top: 1px solid #FF4500; - background-color: white; -} - -div.example { - margin-top: 1em; - padding: 1em; -} - -p.example > strong, div.example > p > strong { -/* background-color: orange;*/ -/* color: lightyellow;*/ - background-color: #FF4500; - color: white; - padding: 0em 0.2em 0em 0.4em; - letter-spacing: 0.05em; -} - -div.example > p > strong { - display: block; - width: 5em; - margin: -2em 0em 1em -1em; - padding: 0.2em 0.2em 0.1em 0.4em; -} From 998e6c9da4adb91cb61935d981f72de9aceb1e1a Mon Sep 17 00:00:00 2001 From: Gary Kacmarcik Date: Fri, 6 Sep 2024 14:56:20 -0700 Subject: [PATCH 6/7] Remove usused .css files (from previous versions) --- geek.css | 22 ---- override.css | 260 --------------------------------------------- spec-WD.css | 269 ---------------------------------------------- spec.css | 295 --------------------------------------------------- styles.css | 210 ------------------------------------ 5 files changed, 1056 deletions(-) delete mode 100644 geek.css delete mode 100644 override.css delete mode 100644 spec-WD.css delete mode 100644 spec.css delete mode 100644 styles.css diff --git a/geek.css b/geek.css deleted file mode 100644 index 389b545a..00000000 --- a/geek.css +++ /dev/null @@ -1,22 +0,0 @@ -span.must, span.required -{ - background-color: #d6ffb9; - box-shadow: 0 0 6px 6px lime; -} - -span.mustnot, span.shallnot, span.shouldnot -{ - background-color: #ffe3e3; - box-shadow: 0 0 6px 6px red; -} - -span.shall, span.should, span.recommended { - background-color: #d6eeff; - box-shadow: 0 0 6px 6px #0985d8; -} - -span.may, span.optional -{ - background-color: #ffffd6; - box-shadow: 0 0 6px 6px yellow; -} \ No newline at end of file diff --git a/override.css b/override.css deleted file mode 100644 index 3cb48113..00000000 --- a/override.css +++ /dev/null @@ -1,260 +0,0 @@ -/* Tweaks to override respec formatting */ - -body { - counter-reset: example; -} - -/* "work in progress" text used in references. */ -.wip { - font-style: italic; -} - -/* Make h5 and h6 easier to see. */ - -section > h5 { - font-style: normal; - font-size: 1em; - font-weight: bold; - color: #005A9C; - margin-bottom: 0.5em; -} - -section > h6 { - font-style: normal; - font-size: 1em; - font-weight: bold; - color: #005A9C; - padding-left: 16px; - margin-bottom: 0.5em; -} - -/* Warnings */ - -section > .warning { - margin-top: 0.5em; - margin-bottom: 0.5em; -} - -dd > .warning { - margin-top: 0.5em; - margin-bottom: 0.5em; -} - -/* Notes */ - -.note-title { - display: none; -} - -section > .note { - margin-top: 0.5em; - margin-bottom: 0.5em; -} - -dd > .note { - margin-top: 0.5em; - margin-bottom: 0.5em; -} - -.note > p { - margin: 0.5em 0; - padding-left: 8px; -} - -.issue { - background-color: #fff0f0; -} - -/* Examples */ - -div.example { - margin-bottom: 1em; -} - -div.example > p { - margin: 0.5em 0 0 0; -} - -div.example > p:first-child { - margin: -0.5em 0 0 0; -} - -div.example > ol,ul,pre,table { - margin: 0; -} - -div.warning > p { - margin: 0.5em 0 0 0; -} - -div.warning > p:first-child { - margin: -0.5em 0 0 0; -} - -.example-title:before { - content: "Example "; -} - -.example-title { - font-weight: bold; - background-color: #FF4500; - color: white; - letter-spacing: 0.05em; - display: block; - width: 6.3em; - margin: -1em 0em 1em -1em; - padding: 0.2em 0.2em 0.1em 0.4em; -} - -.example-title:after { - counter-increment: example; - content: counter(example); -} - -/* Remove extra margin from around each param description */ -.prmDesc > p { - margin: 0 0; -} - -/* "Introduced in DOM Level n" */ - -.intro-dom { - font-size: 0.9em; - font-style: italic; -} - -/* Suppress auto-generated IDL sections in the Appendix. - These tables simply restate the info in the IDL so they're not needed. - */ - -#event-initializers > section > section > h5 { - display: none; -} - -#idl-interface-Event-initializers > h4 + pre + section { - display: none; -} - -#idl-interface-CustomEvent-initializers > h4 + pre + section { - display: none; -} - -#idl-interface-UIEvent-initializers > h4 + pre + section { - display: none; -} - -#idl-interface-FocusEvent-initializers > h4 + pre + section { - display: none; -} - -#idl-interface-MouseEvent-initializers > h4 + pre + section { - display: none; -} - -#idl-interface-WheelEvent-initializers > h4 + pre + section { - display: none; -} - -#idl-interface-KeyboardEvent-initializers > h4 + div + pre + section { - display: none; -} - -#idl-interface-CompositionEvent-initializers > h4 + div + pre + section { - display: none; -} - -/* Formatting for the key value tables. - */ -/* The
    that contains the key table. */ -.key-table { - padding: 0 15px 0 30px; -} - -.key-value-table { - width: 100%; -} - -/* The cell in a key table that contains the key name. */ -.key-table-key { - vertical-align: top; -} - -/* Formatting for the event sequence tables. - */ -.event-sequence-table th { - background:none repeat scroll 0 0 #E8EDFF; - color:#003399; - font-weight:normal; - padding: 0.25em 0.5em 0.25em 0.5em; -} - -.event-sequence-table td { - background:none repeat scroll 0 0 #ffffff; - color:#666699; - padding: 0 0.5em 0 0.5em; -} - -.event-sequence-table tr:hover td { - background:none repeat scroll 0 0 #E8EDFF; - color:#333399; -} - -/* Formatting for the legacy key tables in the Appendix. - */ -.legacy-key-table th { - background:none repeat scroll 0 0 #E8EDFF; - color:#003399; - font-weight:normal; - padding: 0.25em 0.5em 0.25em 0.5em; -} - -.legacy-key-table td { - background:none repeat scroll 0 0 #ffffff; - color:#666699; - padding: 0 0.5em 0 0.5em; -} - -.legacy-key-table tr:hover td { - background:none repeat scroll 0 0 #E8EDFF; - color:#333399; -} - -.cell-center { - text-align: center; -} - -.cell-number { - text-align: right; - min-width: 3em; -} - -/* formatting for data tables (including the keyboard codes) */ -.data-table { - border-collapse:collapse; - text-align:left; - width: 100%; -} - -.data-table th { - background:none repeat scroll 0 0 #B9C9FE; - border-bottom:1px solid #FFFFFF; - border-top:4px solid #AABCFE; - color:#003399; - font-weight:normal; - padding: 2px; - padding-left: 0.5em; -} - -.data-table td { - background:none repeat scroll 0 0 #E8EDFF; - border-bottom:1px solid #FFFFFF; - border-top:1px solid transparent; - color:#666699; - padding: 2px; - padding-left: 1em; -} - -.data-table tr:hover td { - background:none repeat scroll 0 0 #D0DAFD; - color:#333399; -} diff --git a/spec-WD.css b/spec-WD.css deleted file mode 100644 index 16b40be0..00000000 --- a/spec-WD.css +++ /dev/null @@ -1,269 +0,0 @@ -h4 { - text-align: left; - font-family: sans-serif; - font-weight: normal; - color: #005A9C; -} - -/*.attribute-name { - color: black; - background-color: #FFFFD2; -} - -.constant-name { - color: black; - background-color: #DDFFD2; -} - -.method-name { - color: black; - background-color: #D9E6F8; - font-size: large; - font-style: italic; -} - -.parameter-name { - color: black; - background-color: #FEE6F8; -}*/ - -/* Some fun IDL styling */ -.comment { - color: green; -} - -.d3-idl a:first-of-type { - font-weight: bolder; - font-size: larger; -} - -/*ul.toc, ol.toc {list-style: none} -div.toc ul ul, div.toc ol ol {margin-left: 0} -div.toc ul ul ul, div.toc ol ol ol {margin-left: 1em} -div.toc ul ul ul ul, div.toc ol ol ol ol {margin-left: 0} -li.tocline1 {font-weight: bold} -li.tocline2 {font-weight: normal} -li.tocline4 {font-style: italic} -*/ -/* code { font-family: monospace } */ - -div.paramtable { margin-left: 1em } -div.returntable { margin-left: 1em } - -/* default alignment for tables */ -table { - margin-bottom: 1em; -} - -td { - vertical-align: middle; -} - -/* style for event definition tables */ - -.event-definition table { - border: 2px solid black; - width: 95%; -} - -.event-definition td, -.event-definition th { - border-bottom: 1px dashed #ccc; - padding-left: 8px; - padding-right: 8px; -} - -.event-definition th { - text-align: left; - font-weight: normal; - border-right: 1px dashed #ccc; - white-space: nowrap; - background-color: #D9E6F8; - background-color: #F7F5D7; - background-color: #D0DAFD; -} - -.event-definition td { - width: 100%; -} - -.event-definition tr:last-child td { - border-bottom: none; -} - -.event-definition dfn a { - font-size: larger; - /*font-family: monospace; - color: black; - font-weight: normal; - font-style: normal; - padding-left: 1em; - padding-right: 1em; - padding-top: 0.2em; - background-color: #FFC500;*/ -} - -.event-definition dd table { - margin-bottom: -0.02em; -} - -/* Added the d3-idl class here to remove underlines in IDL blocks */ -/*.event-definition a, .d3-idl a { - text-decoration: none -}*/ - -.event-definition td b { - font-weight: normal -} - -.event-definition dd { - margin-top: 4px -} - -/* style for context info event definition lists */ - -.event-definition td > ul > li { - margin-left: -2.5em; - list-style: none; - border-bottom: 1px dashed #ccc; -} - -.event-definition td > ul > li.last { - border-bottom: none; -} - -dt > p, dd > p { - margin-top: 0.5em; -} - -/* style for exception table */ - -.exceptiontable -{ - border-top-style: hidden; - border-right-style: hidden; - border-bottom-style: none; - border-left-style: hidden; - border-collapse: collapse; -} -.exceptiontable td, .exceptiontable th -{ - padding: 0.2em; - vertical-align: top; - border-right-color: currentColor; - border-bottom-color: currentColor; - border-left-color: currentColor; - border-right-width: medium; - border-bottom-width: thin; - border-left-width: medium; - border-right-style: solid; - border-bottom-style: solid; - border-left-style: solid; -} - -/*h1 a, h2 a, h3 a, h4 a, h5 a, h6 a { - color: inherit !important; - font-weight: inherit !important; - text-decoration: none !important; - font-style: inherit !important; -}*/ - -.typeCell { - background-color: #cfcfcf; -} - -h5 { - font-weight: bold; -} - -dl#glossary-list dt a -{ - font-weight: bold; -} - -/*a.eventtype { - text-decoration: none; -}*/ - -/*a.eventtype code { - font-size: 1.13em; - color: #ff6d00; -}*/ - -/* Denotes a key value (the value of the KeyboardEvent.key property) */ -.key { - color: #191970; - background-color: #b0e0e6; -} - -/* Denotes a code value (the physical location of the key on the keyboard) */ -.code { - color: #191970; - background-color: #ffc4ff; -} - -/* Denotes a char value (the code-point for the character) */ -.char { - color: #191970; - background-color: #98fb98; -} - -/* Denotes a char value (an example glyph for the character) */ -.glyph { - color: #191970; - background-color: #ffe4b5; -} - -dl#key-id-set dt { - display: inline; -} - -a.def { - color: inherit; - text-decoration: inherit; - border-bottom: 1px dotted blue; -} - -/*style for table-event-summary and table-key-values */ - -.data-table { - border-collapse:collapse; - text-align:left; -} - -.data-table th { - background:none repeat scroll 0 0 #B9C9FE; - border-bottom:1px solid #FFFFFF; - border-top:4px solid #AABCFE; - color:#003399; - font-weight:normal; - padding: 2px; - padding-left: 0.5em; -} - -.data-table td { - background:none repeat scroll 0 0 #E8EDFF; - border-bottom:1px solid #FFFFFF; - border-top:1px solid transparent; - color:#666699; - padding: 2px; - padding-left: 1em; -} - -.data-table tr:hover td { - background:none repeat scroll 0 0 #D0DAFD; - color:#333399; -} - -/*style for algorithm lists */ -ol.algo { - counter-reset: section; - list-style-type: none; -} - -ol.algo li { - counter-increment: section; - margin-top: 0.5em; -} -ol.algo li:before { content: counters(section, ".") ". "; } -ol.algo li ol.algo li { margin-left: -1em; } diff --git a/spec.css b/spec.css deleted file mode 100644 index 4f067793..00000000 --- a/spec.css +++ /dev/null @@ -1,295 +0,0 @@ -h4 { - text-align: left; - font-family: sans-serif; - font-weight: normal; - color: #005A9C; -} - -.attribute-name { - color: black; - background-color: #FFFFD2; -} - -.constant-name { - color: black; - background-color: #DDFFD2; -} - -.method-name { - color: black; - background-color: #D9E6F8; - font-size: large; - font-style: italic; -} - -.parameter-name { - color: black; - background-color: #FEE6F8; -} - -/* Some fun IDL styling */ -.comment { - color: green; -} - -.idl a:first-of-type { - font-weight: bolder; - font-size: larger; -} - -ul.toc, ol.toc {list-style: none} -div.toc ul ul, div.toc ol ol {margin-left: 0} -div.toc ul ul ul, div.toc ol ol ol {margin-left: 1em} -div.toc ul ul ul ul, div.toc ol ol ol ol {margin-left: 0} -li.tocline1 {font-weight: bold} -li.tocline2 {font-weight: normal} -li.tocline4 {font-style: italic} - -code { font-family: monospace } - -div.paramtable { margin-left: 1em } -div.returntable { margin-left: 1em } - -/* default alignment for tables */ -table { - margin-bottom: 1em; -} - -td { - vertical-align: middle; -} - -/* style for event definition tables */ - -.event-definition table { - border: 2px solid black; - width: 95%; -} - -.event-definition td, -.event-definition th { - border-bottom: 1px dashed #ccc; - padding-left: 8px; - padding-right: 8px; -} - -.event-definition th { - text-align: left; - font-weight: normal; - border-right: 1px dashed #ccc; - white-space: nowrap; - background-color: #D9E6F8; - background-color: #F7F5D7; - background-color: #D0DAFD; -} - -.event-definition td { - width: 100%; -} - -.event-definition tr:last-child td { - border-bottom: none; -} - -.event-definition dfn a { - font-family: monospace; - color: black; - font-weight: normal; - font-style: normal; - padding-left: 1em; - padding-right: 1em; - padding-top: 0.2em; - background-color: #FFC500; -} - -.event-definition dd table { - margin-bottom: -0.02em; -} - -/* Added the idl class here to remove underlines in IDL blocks */ -.event-definition a, .idl a { - text-decoration: none -} - -.event-definition td b { - font-weight: normal -} - -.event-definition dd { - margin-top: 4px -} - -/* style for context info event definition lists */ - -.event-definition td > ul > li { - margin-left: -2.5em; - list-style: none; - border-bottom: 1px dashed #ccc; -} - -.event-definition td > ul > li.last { - border-bottom: none; -} - -dt > p, dd > p { - margin-top: 0.5em; -} - -/* style for exception table */ - -.exceptiontable -{ - border-top-style: hidden; - border-right-style: hidden; - border-bottom-style: none; - border-left-style: hidden; - border-collapse: collapse; -} -.exceptiontable td, .exceptiontable th -{ - padding: 0.2em; - vertical-align: top; - border-right-color: currentColor; - border-bottom-color: currentColor; - border-left-color: currentColor; - border-right-width: medium; - border-bottom-width: thin; - border-left-width: medium; - border-right-style: solid; - border-bottom-style: solid; - border-left-style: solid; -} - -h1 a, h2 a, h3 a, h4 a, h5 a, h6 a { - color: inherit !important; - font-weight: inherit !important; - text-decoration: none !important; - font-style: inherit !important; -} - -.typeCell { - background-color: #cfcfcf; -} - -h5 { - font-weight: bold; -} - -dl#glossary-list dt a -{ - font-weight: bold; -} - -a.eventtype { - text-decoration: none; -} - -a.eventtype code { - font-size: 1.13em; - color: #ff6d00; -} - -/* Denotes a key value (the value of the KeyboardEvent.key property) */ -.key { - color: #191970; - background-color: #b0e0e6; -} - -/* Denotes a char value (the code-point for the character) */ -.char { - color: #191970; - background-color: #98fb98; -} - -/* Denotes a char value (an example glyph for the character) */ -.glyph { - color: #191970; - background-color: #ffe4b5; -} - -dl#key-id-set dt { - display: inline; -} - -a.def { - color: inherit; - text-decoration: inherit; - border-bottom: 1.8px dashed blue; -} - -/*style for table-event-summary and table-key-values */ - -.data-table { - border-collapse:collapse; - text-align:left; -} - -.data-table th { - background:none repeat scroll 0 0 #B9C9FE; - border-bottom:1px solid #FFFFFF; - border-top:4px solid #AABCFE; - color:#003399; - font-weight:normal; - padding: 2px; - padding-left: 0.5em; -} - -.data-table td { - background:none repeat scroll 0 0 #E8EDFF; - border-bottom:1px solid #FFFFFF; - border-top:1px solid transparent; - color:#666699; - padding: 2px; - padding-left: 1em; -} - -.data-table tr:hover td { - background:none repeat scroll 0 0 #D0DAFD; - color:#333399; -} - -/*style for algorithm lists */ -ol.algo { - counter-reset: section; - list-style-type: none; -} - -ol.algo li { - counter-increment: section; - margin-top: 0.5em; -} -ol.algo li:before { content: counters(section, ".") ". "; } -ol.algo li ol.algo li { margin-left: -1em; } - -#turnOnConformanceHighlighting { - position: fixed; - font-size: 12pt; - padding: 5px; - background-color: red; - color: white; - width: 400px; - left: 0; - opacity: 1; - bottom: 0; - -webkit-transform-origin: top left; - -moz-transform-origin: top left; - -ms-transform-origin: top left; - -o-transform-origin: top left; - transform-origin: top left; - - -webkit-transform: rotate(-90deg); - -moz-transform: rotate(-90deg); - -ms-transform: rotate(-90deg); - -o-transform: rotate(-90deg); - transform: rotate(-90deg); - - -webkit-transition: opacity 0.2s linear, bottom 0.3s ease-in; - -moz-transition: opacity 0.2s linear, bottom 0.3s ease-in; - -ms-transition: opacity 0.2s linear, bottom 0.3s ease-in; - -o-transition: opacity 0.2s linear, bottom 0.3s ease-in; - transition: opacity 0.2s linear, bottom 0.3s ease-in; -} -#turnOnConformanceHighlighting[class=off] { - opacity: 0; - bottom: 100px; -} \ No newline at end of file diff --git a/styles.css b/styles.css deleted file mode 100644 index c946415c..00000000 --- a/styles.css +++ /dev/null @@ -1,210 +0,0 @@ -.note { border-left-style: solid; border-left-width: 0.25em; background: none repeat scroll 0 0 #E9FBE9; border-color: #52E052; } -.note em, .warning em, .note i, .warning i { font-style: normal; } -p.note, div.note { padding: 0.5em 2em; } -span.note { padding: 0 2em; } -.note p:first-child { margin-top: 0; } -.note p:last-child { margin-bottom: 0; } -p.note:before { content: 'Note: '; font-weight: bolder;} - -.warning { background-color: #F9F0D4; border: medium double #FF0000; margin: 1em; padding: 1em; } -.warning p:first-child { margin-top: 0; } -.warning p:last-child { margin-bottom: 0; } -.warning:before { font-style: normal; } -p.warning:before { content: '\26A0 Warning! '; font-weight:bolder;} -.warning em, .warning i { font-style: normal; } - -.critical {margin:1em; border:double red; padding:1em; background-color:#F9F0D4;} - -.XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; } -.XXX > :first-child { margin-top: 0; } -p .XXX { line-height: 3em; } - -pre.idl, pre.idl-ignore { border: solid thin #d3d3d3; background: #FCFCFC; color: black; padding: 0.5em 1em; position: relative; } -pre.idl :link, pre.idl :visited, pre.idl-ignore :link, pre.idl-ignore :visited { color: inherit; background: transparent; } -pre.idl::before, pre.idl-ignore::before { content: "IDL"; font: bold small sans-serif; padding: 0.5em; background: white; position: absolute; top: 0; margin: -1px 0 0 -4em; width: 1.5em; border: thin solid; border-radius: 0 0 0 0.5em } - -.intro-dom { - font-size: 0.9em; - font-style: italic; -} - -.comment { - color: green; -} - -.example:before { content: 'Example ' counter(example) ':'; font-weight: bolder; } -.example pre:last-child { margin-bottom: 0; } -.example code.pre {white-space: pre;} -} - - -/* Used when spelling out words or symbols phonetically. */ -span.phonetic { - font-style: italic; -} - -/* KEY - * Denotes a key value (the value of the KeyboardEvent.key property). - */ -code.key { - color: #191970; - background-color: #b0e0e6; - padding: 0 2px; - border: 1px solid #b0d0d6; - border-radius: 3px; -} -code.key a:link, code.key a:visited { - color: #191970; - text-decoration: none; -} -code.key:hover, code.key a:hover { - color: #000000; - background-color: #b0d0d6; -} - -/* CODE - * Denotes a code value that indicates the physical location of the key on - * the keyboard). This is the value of the KeyboardEvent.code property. - */ -code.code { - color: #191970; - background-color: #ffc4ff; - padding: 0 2px; - border: 1px solid #f0a4f0; - border-radius: 3px; -} -code.code a:link, code.code a:visited { - color: #191970; - text-decoration: none; -} -code.code:hover, code.code a:hover { - color: #000000; - background-color: #f0a4f0; -} - -/* Denotes a string displayed on the keycap. */ -code.keycap { - padding: 0 2px; - border: 1px solid black; - border-radius: 3px; -} - -/* Denotes a Unicode code-point for the character. */ -code.unicode { - color: #191970; - background-color: #98fb98; -} - -/* Denotes an example glyph for the character. */ -code.glyph { - color: #191970; - background-color: #ffe4b5; -} - - -/* Formatting for data tables (including the keyboard codes) */ -.data-table { - border-collapse:collapse; - text-align:left; - width: 100%; -} - -.data-table th { - background:none repeat scroll 0 0 #B9C9FE; - border-bottom:1px solid #FFFFFF; - border-top:4px solid #AABCFE; - color:#003399; - font-weight:normal; - padding: 0.4em 1em; -} - -.data-table td { - background:none repeat scroll 0 0 #E8EDFF; - border-bottom:1px solid #FFFFFF; - border-top:1px solid transparent; - color:#666699; - padding: 0.4em 1em; -} - -.data-table tr:hover td { - background:none repeat scroll 0 0 #D0DAFD; - color:#333399; -} - -/* Formatting for the event sequence tables. - */ -.event-sequence-table th { - background:none repeat scroll 0 0 #E8EDFF; - color:#003399; - font-weight:normal; - padding: 0.25em 0.5em 0.25em 0.5em; - font-size: 0.9em; -} - -.event-sequence-table td { - background:none repeat scroll 0 0 #ffffff; - color:#666699; - padding: 0 0.5em 0 0.5em; - font-size: 0.8em; - vertical-align: top; -} - -.event-sequence-table tr:hover td { - background:none repeat scroll 0 0 #E8EDFF; -} - -.example .event-sequence-table { - border: 1px solid #000000; - margin: 3px; -} - -.example .event-sequence-table td { - background:none repeat scroll 0 0 #FCFAEE; -} - -.example .event-sequence-table th { - background:none repeat scroll 0 0 #ede19b; -} - -.cell-center { - text-align: center; -} - -.cell-number { - text-align: right; -} - - -/* The cell in a code table that contains the code value. */ -.code-table-code { - vertical-align: top; -} - -.event-definition { - border: 2px solid black; - width: 95%; -} -.event-definition td, -.event-definition th { - border-bottom: 1px dashed #ccc; - padding-left: 8px; - padding-right: 8px; - font-size: 0.9em; -} -.event-definition th { - text-align: left; - font-weight: normal; - border-right: 1px dashed #ccc; - white-space: nowrap; - background-color: #D9E6F8; - background-color: #F7F5D7; - background-color: #D0DAFD; -} -.event-definition td { - width: 100%; -} -.event-definition td > ul > li, -.event-definition td > ul > li > p { - margin-top: 0; - margin-bottom: 0; -} From 7bc3a40f0c05ed6c25503d0e3e7ed57bfc130abc Mon Sep 17 00:00:00 2001 From: Gary Kacmarcik Date: Fri, 6 Sep 2024 16:07:51 -0700 Subject: [PATCH 7/7] Remove experimental split spec processing from build.py --- build.py | 35 ++++++++--------------------------- 1 file changed, 8 insertions(+), 27 deletions(-) diff --git a/build.py b/build.py index c8b1ab64..53407753 100755 --- a/build.py +++ b/build.py @@ -1,6 +1,6 @@ #!/usr/bin/env python -"""Script to build the spec.""" +"""Script to build the Bikeshed (.bs) files for the UI Events spec.""" from __future__ import print_function @@ -11,6 +11,11 @@ DEBUG = False +# This Parser processes the base *.txt files in the section/ directory to produce a set +# of output *.bs files that can be used as input to Bikeshed to create the final .html +# file. +# This pre-processing marks up the Key and Code values (with appropriate links) and +# generates HTML tables from the ASCII markup. class Parser(): """Pre-bikeshed parser for uievents spec.""" @@ -274,6 +279,8 @@ def process_main_spec(): 'glossary', ] + # Generate an .include file for each .txt file in the sections/ directory. + # These .include files are referenced by the main index.bs file. for section in sections: infilename = 'sections/' + section + '.txt' outfilename = 'sections/' + section + '.include' @@ -291,34 +298,8 @@ def process_main_spec(): cmd.append('--line-numbers') subprocess.call(cmd) -def process_split_spec(): - # Split version of the UIEvents spec. - split_sections = [ - 'composition-events', - 'focus-events', - 'input-events', - 'keyboard-events', - 'mouse-events', - 'ui-events', - 'wheel-events', - ] - for section in split_sections: - infilename = 'split/' + section + '.txt' - outfilename = 'split/' + section + '.bs' - - # Generate the bikeshed file. - parser = Parser() - parser.process(infilename, outfilename) - - print('Bikeshedding split specs...') - for section in split_sections: - print('...' + section) - cmd = ["bikeshed", "spec", "split/" + section + ".bs"] - subprocess.call(cmd) - def main(): process_main_spec() - #process_split_spec() if __name__ == '__main__': main()