From 09a203188460734950f9cbf4a424c36ae7d93a6c Mon Sep 17 00:00:00 2001 From: Gary Kacmarcik Date: Fri, 7 Jun 2024 15:10:04 -0700 Subject: [PATCH] Split event types source file by event type This splits the event-types.txt file into smaller files (by event type) so that they are easier to manage. This should help reduce conflicts while converting the event types to an algorithmic description. The generated spec should be identical after this cl. --- build.py | 7 + index.bs | 23 + sections/event-types-compositionevent.txt | 345 +++ sections/event-types-focusevent.txt | 253 ++ sections/event-types-inputevent.txt | 168 + sections/event-types-keyboardevent.txt | 583 ++++ sections/event-types-mouseevent.txt | 1513 +++++++++ sections/event-types-uievent.txt | 242 ++ sections/event-types-wheelevent.txt | 310 ++ sections/event-types.txt | 3416 --------------------- 10 files changed, 3444 insertions(+), 3416 deletions(-) create mode 100644 sections/event-types-compositionevent.txt create mode 100644 sections/event-types-focusevent.txt create mode 100644 sections/event-types-inputevent.txt create mode 100644 sections/event-types-keyboardevent.txt create mode 100644 sections/event-types-mouseevent.txt create mode 100644 sections/event-types-uievent.txt create mode 100644 sections/event-types-wheelevent.txt diff --git a/build.py b/build.py index 3a71988..76d8c37 100755 --- a/build.py +++ b/build.py @@ -258,6 +258,13 @@ def process_main_spec(): 'architecture', 'event-interfaces', 'event-types', + 'event-types-uievent', + 'event-types-focusevent', + 'event-types-mouseevent', + 'event-types-wheelevent', + 'event-types-inputevent', + 'event-types-keyboardevent', + 'event-types-compositionevent', 'keyboard', 'legacy-event-initializers', 'legacy-key-attributes', diff --git a/index.bs b/index.bs index 5cf2551..0677539 100644 --- a/index.bs +++ b/index.bs @@ -95,9 +95,32 @@ path: sections/event-interfaces.include +
 path: sections/event-types.include
 
+
+path: sections/event-types-uievent.include
+
+
+path: sections/event-types-focusevent.include
+
+
+path: sections/event-types-mouseevent.include
+
+
+path: sections/event-types-wheelevent.include
+
+
+path: sections/event-types-inputevent.include
+
+
+path: sections/event-types-keyboardevent.include
+
+
+path: sections/event-types-compositionevent.include
+
+
diff --git a/sections/event-types-compositionevent.txt b/sections/event-types-compositionevent.txt
new file mode 100644
index 0000000..d7fda0a
--- /dev/null
+++ b/sections/event-types-compositionevent.txt
@@ -0,0 +1,345 @@
+

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
| | + ++------------------+--------------------------------------------------------------------------------------+ + + 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
| | + ++------------------+--------------------------------------------------------------------------------------+ + + 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
| | + ++------------------+--------------------------------------------------------------------------------------+ + + 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). + diff --git a/sections/event-types-focusevent.txt b/sections/event-types-focusevent.txt new file mode 100644 index 0000000..ef6b46a --- /dev/null +++ b/sections/event-types-focusevent.txt @@ -0,0 +1,253 @@ +

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
| | + ++------------------+--------------------------------------------------------------------------------------+ + + 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
| | + ++------------------+--------------------------------------------------------------------------------------+ + + 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
| | + ++------------------+--------------------------------------------------------------------------------------+ + + 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
| | + ++------------------+--------------------------------------------------------------------------------------+ + + 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. + diff --git a/sections/event-types-inputevent.txt b/sections/event-types-inputevent.txt new file mode 100644 index 0000000..7153a6c --- /dev/null +++ b/sections/event-types-inputevent.txt @@ -0,0 +1,168 @@ +

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

+ +
InputEvent
+ +

Introduced in DOM Level 3

+ +
+			[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
| | + ++------------------+--------------------------------------------------------------------------------------+ + + 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
| | + ++------------------+--------------------------------------------------------------------------------------+ + + A user agent MUST dispatch this event immediately after the + DOM has been updated. + + diff --git a/sections/event-types-keyboardevent.txt b/sections/event-types-keyboardevent.txt new file mode 100644 index 0000000..0ac791e --- /dev/null +++ b/sections/event-types-keyboardevent.txt @@ -0,0 +1,583 @@ +

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

+ diff --git a/sections/event-types-mouseevent.txt b/sections/event-types-mouseevent.txt new file mode 100644 index 0000000..8d93ed0 --- /dev/null +++ b/sections/event-types-mouseevent.txt @@ -0,0 +1,1513 @@ +

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

+ diff --git a/sections/event-types-uievent.txt b/sections/event-types-uievent.txt new file mode 100644 index 0000000..a322c19 --- /dev/null +++ b/sections/event-types-uievent.txt @@ -0,0 +1,242 @@ +

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

+ diff --git a/sections/event-types-wheelevent.txt b/sections/event-types-wheelevent.txt new file mode 100644 index 0000000..f371fbb --- /dev/null +++ b/sections/event-types-wheelevent.txt @@ -0,0 +1,310 @@ +

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

+ + diff --git a/sections/event-types.txt b/sections/event-types.txt index c5bb47f..2e3cf46 100644 --- a/sections/event-types.txt +++ b/sections/event-types.txt @@ -1,4 +1,3 @@ -

Event Types

@@ -9,3418 +8,3 @@ 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. -

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

- -

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

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

- -

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

- - -

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

- -
InputEvent
- -

Introduced in DOM Level 3

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

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

- -

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