-Shortname: composition-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
- *** Composition Events ***
-
- Note: This is an experimental split of the UI Events spec into smaller, event-specific
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
-
-This specification follows the
-Proposed W3C Specification Conventions,
-with the following supplemental additions:
-
-* The key cap printed on a key is shown as
- ↓, = or Q. This is used to refer to a
- key from the user's perspective without regard for the
- {{KeyboardEvent/key}} and {{KeyboardEvent/code}} values in the
- generated {{KeyboardEvent}}.
-
-* Glyphs representing character are shown as: "𣧂".
-
-* Unicode character encodings are shown as: U+003d.
-
-* Names of key values generated by a key press (i.e., the value of
- {{KeyboardEvent}}.{{KeyboardEvent/key}}) are shown as:
- "ArrowDown", "=", "q" or "Q".
-
-* Names of key codes associated with the physical keys (i.e., the
- value of {{KeyboardEvent}}.{{KeyboardEvent/code}}) are shown as:
- "ArrowDown", "Equal" or "KeyQ".
-
-
-In addition, certain terms are used in this specification with particular
-meanings. The term implementation applies to a browser, content
-authoring tool, or other user agent that implements this specification,
-while a content author is a person who writes script or code that takes
-advantage of the interfaces, methods, attributes, events, and other features
-described in this specification in order to make Web applications, and a user is
-the person who uses those Web applications in an implementation.
-
-And finally:
-
-
This is a note.
-
-
-
-
This is an open issue.
-
-
This is a warning.
-
-
- interface Example {
- // This is an IDL definition.
- };
-
-
-
Composition Events
-
- Composition Events provide a means for inputing text in a supplementary or
- alternate manner than by Keyboard Events, in order to allow the use of
- characters that might not be commonly available on keyboard. For example,
- Composition Events might be used to add accents to characters despite their
- absence from standard US keyboards, to build up logograms of many Asian
- languages from their base components or categories, to select word choices
- from a combination of key presses on a mobile device keyboard, or to convert
- voice commands into text using a speech recognition processor. Refer to
- [[#keys]] for examples on how Composition Events are used in combination
- with keyboard events.
-
- Conceptually, a composition session consists of one compositionstart
- event, one or more compositionupdate events, and one
- compositionend event, with the value of the {{CompositionEvent/data}}
- attribute persisting between each stage of this event chain during
- each session.
-
-
Note:
- While a composition session is active, keyboard events can be dispatched to
- the DOM if the keyboard is the input device used with the composition
- session. See the compositionstart event details and
- IME section for relevent event ordering.
-
-
- Not all IME systems or devices expose the necessary data to the DOM,
- so the active composition string (the Reading Window or candidate
- selection menu option) might not be available through this interface, in
- which case the selection MAY be represented by the empty string.
-
-
Interface CompositionEvent
-
-
Introduced in this specification
-
- The {{CompositionEvent}} interface provides specific contextual
- information associated with Composition Events.
-
- To create an instance of the {{CompositionEvent}} interface,
- use the {{CompositionEvent}} constructor, passing an optional
- {{CompositionEventInit}} dictionary.
-
-
- 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).
-
-
- 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.
-
-
-
- If the initial compositionstart event is canceled then the text
- composition session SHOULD be terminated. Regardless of whether or not
- the composition session is terminated, the compositionend event
- MUST be sent.
-
-
-
- During the composition session, keydown and keyup events
- MUST still be sent, and these events MUST have the
- {{KeyboardEvent/isComposing}} attribute set to true.
-
-
-
- During the composition session, the compositionupdate MUST be
- dispatched after the beforeinput is sent, but before the
- input event is sent.
-
-
- Most IMEs do not support canceling updates during a composition session.
-
-
- The beforeinput and input events are sent along with the
- compositionupdate event whenever the DOM is updated as part of
- the composition. Since there are no DOM updates associated with the
- compositionend event, beforeinput and input events
- should not be sent at that time.
-
-
{{CompositionEvent}}.{{CompositionEvent/data}} : the original string being edited, otherwise the empty string
-
-
- A user agent MUST dispatch this event when a text
- composition system is enabled and a new composition session is
- about to begin (or has begun, depending on the text composition
- system) in preparation for composing a passage of text. This
- event type is device-dependent, and MAY rely upon the capabilities
- of the text conversion system and how it is mapped into the
- operating system. When a keyboard is used to feed an input method
- editor, this event type is generated after a keydown event,
- but speech or handwriting recognition systems MAY send this event
- type without keyboard events. Some implementations MAY populate the
- {{CompositionEvent/data}} attribute of the compositionstart
- event with the text currently selected in the document (for editing
- and replacement). Otherwise, the value of the
- {{CompositionEvent/data}} attribute MUST be the empty string.
-
- This event MUST be dispatched immediately before a text
- composition system begins a new composition session, and before
- the DOM is modified due to the composition process. The default
- action of this event is for the text composition system to
- start a new composition session. If this event is canceled, the
- text composition system SHOULD discard the current
- composition session.
-
-
- Canceling the compositionstartevent 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
-
-
-
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
{{CompositionEvent}}.{{CompositionEvent/data}} : the string comprising the current results of the composition session, which MAY be the empty string if the content has been deleted
-
-
- A user agent SHOULD dispatch this event during a composition
- session when a text composition system updates its active
- text passage with a new character, which is reflected in the string
- in {{CompositionEvent/data}}.
-
- In text composition systems which keep the ongoing
- composition in sync with the input control, the
- compositionupdate event MUST be dispatched before the control
- is updated.
-
- Some text composition systems might not expose this
- information to the DOM, in which case this event will not fire
- during the composition process.
-
- If the composition session is canceled, this event will be fired
- immediately before the compositionend event, and the
- {{CompositionEvent/data}} attribute will be set to the empty
- string.
-
-
compositionend
-
-
-
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
{{CompositionEvent}}.{{CompositionEvent/data}} : the string comprising the final result of the composition session, which MAY be the empty string if the content has been deleted or if the composition process has been canceled
-
-
- A user agent MUST dispatch this event when a text
- composition system completes or cancels the current composition
- session, and the compositionend event MUST be dispatched
- after the control is updated.
-
- This event is dispatched immediately after the text composition
- system completes the composition session (e.g., the IME
- is closed, minimized, switched out of focus, or otherwise dismissed,
- and the focus switched back to the user agent).
-
-
Legacy Event Initializers
-
- This section is normative.
-
- The following features are obsolete and should only be implemented by
- user agents that require compatibility with legacy software.
-
- Early versions of this specification included an initialization method on
- the interface (for example initMouseEvent) that required a long
- list of parameters that, in most cases, did not fully initialize all
- attributes of the event object. Because of this, event interfaces which were
- derived from the basic {{Event}} interface required that the initializer of
- each of the derived interfaces be called explicitly in order to
- fully initialize an event.
-
-
- Initializing all the attributes of a MutationEvent requires calls to two
- initializer methods: initEvent and
- initMutationEvent.
-
-
- Due in part to the length of time in the development of this standard, some
- implementations MAY have taken a dependency on these (now deprecated)
- initializer methods. For completeness, these legacy event initializers are
- described in this section.
-
-
Initializers for interface CompositionEvent
-
- This section is informative
-
-
- The argument list to this legacy CompositionEvent initializer does not
- include the detailArg (present in other initializers) and
- adds the locale argument (see [[#changes-drafts]]); it is
- necessary to preserve this inconsistency for compatibility with existing
- implementations.
-
- Initializes attributes of a CompositionEvent
- object. This method has the same behavior as
- UIEvent.initUIEvent(). The value of {{UIEvent/detail}}
- remains undefined.
-
-
- The initCompositionEvent method is deprecated.
-
-
-
-
DOMString typeArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
boolean bubblesArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
boolean cancelableArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
Window? viewArg
-
- Specifies {{UIEvent/view}}. This value MAY be null.
-
-
-
DOMString dataArg
-
- Specifies {{CompositionEvent/data}}.
-
-
-
-
-
-
Security Considerations
-
- TODO - Add specific concerns for this spec
-
-
Acknowledgements
-
- TODO
-
-
Refs to other UIEvent specs \[DELETE]
-
- This section will be deleted.
-
- Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
- beforeinput
- keydown
- keyup
- input
-
-
Things defined in other sections
-
Activation triggers and behavior
-
Default actions and cancelable events
-
Event dispatch and DOM event flow
-
Web browsers and other dynamic or interactive user agents
-
Authoring tools
-
-
Things defined in KeyboardEvents
-
Keyboard events and key values
-
Input Method Editors
-
Key Legends
-
-
Things defined in Changes
-
Changes between different drafts of UI Events
-
-
Glossary \[DELETE]
-
-This section will be deleted.
-
-Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-: activation behavior
-:: The action taken when an event, typically initiated by users through
- an input device, causes an element to fulfill a defined task. The task MAY
- be defined for that element by the host language, or by
- author-defined variables, or both. The default task for any given element
- MAY be a generic action, or MAY be unique to that element. For example, the
- activation behavior of an HTML or SVG <a> element is to
- cause the user agent to traverse the link specified in the
- href attribute, with the further optional parameter of
- specifying the browsing context for the traversal (such as the current
- window or tab, a named window, or a new window). The activation behavior of
- an HTML <input> element with the type
- attribute value submit is be to send the values of the form
- elements to an author-defined IRI by the author-defined HTTP method. See
- [[#event-flow-activation]] for more details.
-
-: activation trigger
-:: An event which is defined to initiate an activation behavior. Refer
- to [[#event-flow-activation]] for more details.
-
-: default action
-:: A default action is an OPTIONAL supplementary behavior that an
- implementation MUST perform in combination with the dispatch of the event
- object. Each event type definition, and each specification, defines the
- default action for that event type, if it has one. An instance of an
- event MAY have more than one default action under some circumstances,
- such as when associated with an activation trigger. A default
- action MAY be cancelled through the invocation of the
- {{Event/preventDefault()}} method. For more details, see
- [[#event-flow-default-cancel]].
-
-: empty string
-:: The empty string is a value of type DOMString of length
- 0, i.e., a string which contains no characters (neither
- printing nor control characters).
-
-: event
-:: An event is the representation of some occurrence (such as a mouse click on
- the presentation of an element, the removal of child node from an element,
- or any number of other possibilities) which is associated with its event
- target. Each event is an instantiation of one specific event
- type.
-
-: event target
-:: The object to which an event is targeted using the [[#event-flow]].
- The event target is the value of the {{Event/target}} attribute.
-
-: host language
-:: Any language which integrates the features of another language or API
- specification, while normatively referencing the origin specification rather
- than redefining those features, and extending those features only in ways
- defined by the origin specification. An origin specification typically is
- only intended to be implemented in the context of one or more host
- languages, not as a standalone language. For example, XHTML, HTML, and SVG
- are host languages for UI Events, and they integrate and extend the objects
- and models defined in this specification.
-
-: IME
-: input method editor
-:: An input method editor (IME), also known as a front end
- processor, is an application that performs the conversion between
- keystrokes and ideographs or other characters, usually by user-guided
- dictionary lookup, often used in East Asian languages (e.g., Chinese,
- Japanese, Korean). An IME MAY also be used for dictionary-based word
- completion, such as on mobile devices. See [[#keys-IME]] for treatment of
- IMEs in this specification. See also text composition system.
-
-: text composition system
-:: A software component that interprets some form of alternate input (such as a
- input method editor, a speech processor, or a handwriting recognition
- system) and converts it to text.
-
-: un-initialized value
-:: The value of any event attribute (such as {{Event/bubbles}} or
- {{Event/currentTarget}}) before the event has been initialized with
- {{Event/initEvent()}}. The un-initialized values of an event apply
- immediately after a new event has been created using the method
- {{Document/createEvent()}}.
-
-: user agent
-:: A program, such as a browser or content authoring tool, normally running on
- a client machine, which acts on a user's behalf in retrieving, interpreting,
- executing, presenting, or creating content. Users MAY act on the content
- using different user agents at different times, for different purposes. See
- the [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the
- requirements for a conforming user agent.
-
-: Window
-:: The Window is the object referred to by the current document's
- browsing context's Window Proxy object as defined in
- HTML5
- [[HTML5]].
-
diff --git a/split/composition-events.html b/split/composition-events.html
deleted file mode 100644
index dfa6591..0000000
--- a/split/composition-events.html
+++ /dev/null
@@ -1,1947 +0,0 @@
-
-
-
-
- Composition Events
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Note: This is an experimental split of the UI Events spec into smaller, event-specific
-
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
-
Status of this document
-
-
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
-
This document was published by the Web Applications Working Group as an Editors Draft. This document is intended to become a W3C Recommendation.
Publication as an Editors Draft does not imply endorsement by W3C and its Members. This is a draft document and may
- be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite
- this document as other than work in progress.
-
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
The key cap printed on a key is shown as ↓, = or Q. This is used to refer to a
-key from the user’s perspective without regard for the key and code values in the
-generated KeyboardEvent.
-
-
Glyphs representing character are shown as: "𣧂".
-
-
Unicode character encodings are shown as: U+003d.
-
-
Names of key values generated by a key press (i.e., the value of KeyboardEvent.key) are shown as: "ArrowDown", "=", "q" or "Q".
In addition, certain terms are used in this specification with particular
-meanings. The term implementation applies to a browser, content
-authoring tool, or other user agent that implements this specification,
-while a content author is a person who writes script or code that takes
-advantage of the interfaces, methods, attributes, events, and other features
-described in this specification in order to make Web applications, and a user is
-the person who uses those Web applications in an implementation.
-
And finally:
-
This is a note.
-
This is an open issue.
-
This is a warning.
-
interface Example {
- // This is an IDL definition.
-};
-
-
3. Composition Events
-
Composition Events provide a means for inputing text in a supplementary or
- alternate manner than by Keyboard Events, in order to allow the use of
- characters that might not be commonly available on keyboard. For example,
- Composition Events might be used to add accents to characters despite their
- absence from standard US keyboards, to build up logograms of many Asian
- languages from their base components or categories, to select word choices
- from a combination of key presses on a mobile device keyboard, or to convert
- voice commands into text using a speech recognition processor. Refer to § 7.2.1 Keyboard events and key values for examples on how Composition Events are used in combination
- with keyboard events.
-
Conceptually, a composition session consists of one compositionstart event, one or more compositionupdate events, and one compositionend event, with the value of the data attribute persisting between each stage of this event chain during
- each session.
-
Note: While a composition session is active, keyboard events can be dispatched to
- the DOM if the keyboard is the input device used with the composition
- session. See the compositionstart event details and IME section for relevent event ordering.
-
Not all IME systems or devices expose the necessary data to the DOM,
- so the active composition string (the Reading Window or candidate
- selection menu option) might not be available through this interface, in
- which case the selection MAY be represented by the empty string.
-
3.1. Interface CompositionEvent
-
Introduced in this specification
-
The CompositionEvent interface provides specific contextual
- information associated with Composition Events.
- 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 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.
If the initial compositionstart event is canceled then the text
- composition session SHOULD be terminated. Regardless of whether or not
- the composition session is terminated, the compositionend event
- MUST be sent.
Most IMEs do not support canceling updates during a composition session.
-
The beforeinput and input events are sent along with the compositionupdate event whenever the DOM is updated as part of
- the composition. Since there are no DOM updates associated with the compositionend event, beforeinput and input events
- should not be sent at that time.
A user agent MUST dispatch this event when a text
- composition system is enabled and a new composition session is
- about to begin (or has begun, depending on the text composition
- system) in preparation for composing a passage of text. This
- event type is device-dependent, and MAY rely upon the capabilities
- of the text conversion system and how it is mapped into the
- operating system. When a keyboard is used to feed an input method
- editor, this event type is generated after a keydown event,
- but speech or handwriting recognition systems MAY send this event
- type without keyboard events. Some implementations MAY populate the data attribute of the compositionstart event with the text currently selected in the document (for editing
- and replacement). Otherwise, the value of the data attribute MUST be the empty string.
-
This event MUST be dispatched immediately before a text
- composition system begins a new composition session, and before
- the DOM is modified due to the composition process. The default
- action of this event is for the text composition system to
- start a new composition session. If this event is canceled, the text composition system SHOULD discard the current
- composition session.
Some IMEs do not support cancelling an in-progress composition
- session (e.g., such as GTK which doesn’t presently have such an
- API). In these cases, calling preventDefault() will not
- stop this event’s default action.
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 data.
-
In text composition systems which keep the ongoing
- composition in sync with the input control, the compositionupdate event MUST be dispatched before the control
- is updated.
-
Some text composition systems might not expose this
- information to the DOM, in which case this event will not fire
- during the composition process.
-
If the composition session is canceled, this event will be fired
- immediately before the compositionend event, and the data attribute will be set to the empty
- string.
CompositionEvent.data : the string comprising the final result of the composition session, which MAY be the empty string if the content has been deleted or if the composition process has been canceled
-
-
-
A user agent MUST dispatch this event when a text
- composition system completes or cancels the current composition
- session, and the compositionend event MUST be dispatched
- after the control is updated.
-
This event is dispatched immediately after the text composition
- system completes the composition session (e.g., the IME is closed, minimized, switched out of focus, or otherwise dismissed,
- and the focus switched back to the user agent).
-
4. Legacy Event Initializers
-
This section is normative.
-
The following features are obsolete and should only be implemented by user agents that require compatibility with legacy software.
-
Early versions of this specification included an initialization method on
- the interface (for example initMouseEvent) that required a long
- list of parameters that, in most cases, did not fully initialize all
- attributes of the event object. Because of this, event interfaces which were
- derived from the basic Event interface required that the initializer of each of the derived interfaces be called explicitly in order to
- fully initialize an event.
-
Initializing all the attributes of a MutationEvent requires calls to two
- initializer methods: initEvent and initMutationEvent.
-
Due in part to the length of time in the development of this standard, some
- implementations MAY have taken a dependency on these (now deprecated)
- initializer methods. For completeness, these legacy event initializers are
- described in this section.
-
4.1. Initializers for interface CompositionEvent
-
This section is informative
-
The argument list to this legacy CompositionEvent initializer does not
- include the detailArg (present in other initializers) and
- adds the locale argument (see § 7.3.1 Changes between different drafts of UI Events); it is
- necessary to preserve this inconsistency for compatibility with existing
- implementations.
- Initializes attributes of a CompositionEvent object. This method has the same behavior as UIEvent.initUIEvent(). The value of detail remains undefined.
-
The initCompositionEvent method is deprecated.
-
-
DOMString typeArg
-
Refer to the initEvent() method for a description of this parameter.
-
boolean bubblesArg
-
Refer to the initEvent() method for a description of this parameter.
-
boolean cancelableArg
-
Refer to the initEvent() method for a description of this parameter.
-
Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
beforeinput keydown keyup input
-
7.1. Things defined in other sections
-
7.1.1. Activation triggers and behavior
-
7.1.2. Default actions and cancelable events
-
7.1.3. Event dispatch and DOM event flow
-
7.1.4. Web browsers and other dynamic or interactive user agents
-
7.1.5. Authoring tools
-
7.2. Things defined in KeyboardEvents
-
7.2.1. Keyboard events and key values
-
7.2.2. Input Method Editors
-
7.2.3. Key Legends
-
7.3. Things defined in Changes
-
7.3.1. Changes between different drafts of UI Events
-
8. Glossary [DELETE]
-
This section will be deleted.
-
Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-
activation behavior
-
-
The action taken when an event, typically initiated by users through
-an input device, causes an element to fulfill a defined task. The task MAY
-be defined for that element by the host language, or by
-author-defined variables, or both. The default task for any given element
-MAY be a generic action, or MAY be unique to that element. For example, the
-activation behavior of an HTML or SVG <a> element is to
-cause the user agent to traverse the link specified in the href attribute, with the further optional parameter of
-specifying the browsing context for the traversal (such as the current
-window or tab, a named window, or a new window). The activation behavior of
-an HTML <input> element with the type attribute value submit is be to send the values of the form
-elements to an author-defined IRI by the author-defined HTTP method. See § 7.1.1 Activation triggers and behavior for more details.
A default action is an OPTIONAL supplementary behavior that an
-implementation MUST perform in combination with the dispatch of the event
-object. Each event type definition, and each specification, defines the default action for that event type, if it has one. An instance of an
-event MAY have more than one default action under some circumstances,
-such as when associated with an activation trigger. A default
-action MAY be cancelled through the invocation of the preventDefault() method. For more details, see § 7.1.2 Default actions and cancelable events.
-
empty string
-
-
The empty string is a value of type DOMString of length 0, i.e., a string which contains no characters (neither
-printing nor control characters).
-
event
-
-
An event is the representation of some occurrence (such as a mouse click on
-the presentation of an element, the removal of child node from an element,
-or any number of other possibilities) which is associated with its event
-target. Each event is an instantiation of one specific event
-type.
Any language which integrates the features of another language or API
-specification, while normatively referencing the origin specification rather
-than redefining those features, and extending those features only in ways
-defined by the origin specification. An origin specification typically is
-only intended to be implemented in the context of one or more host
-languages, not as a standalone language. For example, XHTML, HTML, and SVG
-are host languages for UI Events, and they integrate and extend the objects
-and models defined in this specification.
-
IME
-
input method editor
-
-
An input method editor (IME), also known as a front end
-processor, is an application that performs the conversion between
-keystrokes and ideographs or other characters, usually by user-guided
-dictionary lookup, often used in East Asian languages (e.g., Chinese,
-Japanese, Korean). An IME MAY also be used for dictionary-based word
-completion, such as on mobile devices. See § 7.2.2 Input Method Editors for treatment of
-IMEs in this specification. See also text composition system.
-
text composition system
-
-
A software component that interprets some form of alternate input (such as a input method editor, a speech processor, or a handwriting recognition
-system) and converts it to text.
-
un-initialized value
-
-
The value of any event attribute (such as bubbles or currentTarget) before the event has been initialized with initEvent(). The un-initialized values of an event apply
-immediately after a new event has been created using the method createEvent().
-
user agent
-
-
A program, such as a browser or content authoring tool, normally running on
-a client machine, which acts on a user’s behalf in retrieving, interpreting,
-executing, presenting, or creating content. Users MAY act on the content
-using different user agents at different times, for different purposes. See
-the § 7.1.4 Web browsers and other dynamic or interactive user agents and § 7.1.5 Authoring tools for details on the
-requirements for a conforming user agent.
-
Window
-
-
The Window is the object referred to by the current document’s
-browsing context’s Window Proxy object as defined in HTML5[HTML5].
-
-
-
-
Conformance
-
Document conventions
-
Conformance requirements are expressed
- with a combination of descriptive assertions
- and RFC 2119 terminology.
- The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”
- in the normative parts of this document
- are to be interpreted as described in RFC 2119.
- However, for readability,
- these words do not appear in all uppercase letters in this specification.
-
All of the text of this specification is normative
- except sections explicitly marked as non-normative, examples, and notes. [RFC2119]
-
Examples in this specification are introduced with the words “for example”
- or are set apart from the normative text
- with class="example",
- like this:
-
-
-
This is an example of an informative example.
-
-
Informative notes begin with the word “Note”
- and are set apart from the normative text
- with class="note",
- like this:
-
Note, this is an informative note.
-
-
Conformant Algorithms
-
Requirements phrased in the imperative as part of algorithms
- (such as "strip any leading space characters"
- or "return false and abort these steps")
- are to be interpreted with the meaning of the key word
- ("must", "should", "may", etc)
- used in introducing the algorithm.
-
Conformance requirements phrased as algorithms or specific steps
- can be implemented in any manner,
- so long as the end result is equivalent.
- In particular, the algorithms defined in this specification
- are intended to be easy to understand
- and are not intended to be performant.
- Implementers are encouraged to optimize.
-
-
-
\ No newline at end of file
diff --git a/split/composition-events.txt b/split/composition-events.txt
deleted file mode 100644
index e27d232..0000000
--- a/split/composition-events.txt
+++ /dev/null
@@ -1,685 +0,0 @@
-
Composition Events
-
-
-Shortname: composition-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
- *** Composition Events ***
-
- Note: This is an experimental split of the UI Events spec into smaller, event-specific
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
-
-This specification follows the
-Proposed W3C Specification Conventions,
-with the following supplemental additions:
-
-* The key cap printed on a key is shown as
- KEYCAP{↓}, KEYCAP{=} or KEYCAP{Q}. This is used to refer to a
- key from the user's perspective without regard for the
- {{KeyboardEvent/key}} and {{KeyboardEvent/code}} values in the
- generated {{KeyboardEvent}}.
-
-* Glyphs representing character are shown as: GLYPH{𣧂}.
-
-* Unicode character encodings are shown as: UNI{U+003d}.
-
-* Names of key values generated by a key press (i.e., the value of
- {{KeyboardEvent}}.{{KeyboardEvent/key}}) are shown as:
- KEY{ArrowDown}, KEY_NOLINK{=}, KEY_NOLINK{q} or KEY_NOLINK{Q}.
-
-* Names of key codes associated with the physical keys (i.e., the
- value of {{KeyboardEvent}}.{{KeyboardEvent/code}}) are shown as:
- CODE{ArrowDown}, CODE{Equal} or CODE{KeyQ}.
-
-
-In addition, certain terms are used in this specification with particular
-meanings. The term implementation applies to a browser, content
-authoring tool, or other user agent that implements this specification,
-while a content author is a person who writes script or code that takes
-advantage of the interfaces, methods, attributes, events, and other features
-described in this specification in order to make Web applications, and a user is
-the person who uses those Web applications in an implementation.
-
-And finally:
-
-
This is a note.
-
-
-
-
This is an open issue.
-
-
This is a warning.
-
-
- interface Example {
- // This is an IDL definition.
- };
-
-
-
Composition Events
-
- Composition Events provide a means for inputing text in a supplementary or
- alternate manner than by Keyboard Events, in order to allow the use of
- characters that might not be commonly available on keyboard. For example,
- Composition Events might be used to add accents to characters despite their
- absence from standard US keyboards, to build up logograms of many Asian
- languages from their base components or categories, to select word choices
- from a combination of key presses on a mobile device keyboard, or to convert
- voice commands into text using a speech recognition processor. Refer to
- [[#keys]] for examples on how Composition Events are used in combination
- with keyboard events.
-
- Conceptually, a composition session consists of one EVENT{compositionstart}
- event, one or more EVENT{compositionupdate} events, and one
- EVENT{compositionend} event, with the value of the {{CompositionEvent/data}}
- attribute persisting between each stage of this event chain during
- each session.
-
-
Note:
- While a composition session is active, keyboard events can be dispatched to
- the DOM if the keyboard is the input device used with the composition
- session. See the EVENT{compositionstart} event details and
- IME section for relevent event ordering.
-
-
- Not all IME systems or devices expose the necessary data to the DOM,
- so the active composition string (the Reading Window or candidate
- selection menu option) might not be available through this interface, in
- which case the selection MAY be represented by the empty string.
-
-
Interface CompositionEvent
-
-
Introduced in this specification
-
- The {{CompositionEvent}} interface provides specific contextual
- information associated with Composition Events.
-
- To create an instance of the {{CompositionEvent}} interface,
- use the {{CompositionEvent}} constructor, passing an optional
- {{CompositionEventInit}} dictionary.
-
-
- 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).
-
-
- 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
{{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.
-
{{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.
-
-
{{CompositionEvent}}.{{CompositionEvent/data}} : the string comprising the final |
- | | result of the composition session, which MAY be the empty string if the |
- | | content has been deleted or if the composition process has been canceled
|
- | |
|
- ++------------------+--------------------------------------------------------------------------------------+
-
- A user agent MUST dispatch this event when a text
- composition system completes or cancels the current composition
- session, and the EVENT{compositionend} event MUST be dispatched
- after the control is updated.
-
- This event is dispatched immediately after the text composition
- system completes the composition session (e.g., the IME
- is closed, minimized, switched out of focus, or otherwise dismissed,
- and the focus switched back to the user agent).
-
-
Legacy Event Initializers
-
- This section is normative.
-
- The following features are obsolete and should only be implemented by
- user agents that require compatibility with legacy software.
-
- Early versions of this specification included an initialization method on
- the interface (for example initMouseEvent) that required a long
- list of parameters that, in most cases, did not fully initialize all
- attributes of the event object. Because of this, event interfaces which were
- derived from the basic {{Event}} interface required that the initializer of
- each of the derived interfaces be called explicitly in order to
- fully initialize an event.
-
-
- Initializing all the attributes of a MutationEvent requires calls to two
- initializer methods: initEvent and
- initMutationEvent.
-
-
- Due in part to the length of time in the development of this standard, some
- implementations MAY have taken a dependency on these (now deprecated)
- initializer methods. For completeness, these legacy event initializers are
- described in this section.
-
-
Initializers for interface CompositionEvent
-
- This section is informative
-
-
- The argument list to this legacy CompositionEvent initializer does not
- include the detailArg (present in other initializers) and
- adds the locale argument (see [[#changes-drafts]]); it is
- necessary to preserve this inconsistency for compatibility with existing
- implementations.
-
- Initializes attributes of a CompositionEvent
- object. This method has the same behavior as
- UIEvent.initUIEvent(). The value of {{UIEvent/detail}}
- remains undefined.
-
-
- The initCompositionEvent method is deprecated.
-
-
-
-
DOMString typeArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
boolean bubblesArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
boolean cancelableArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
Window? viewArg
-
- Specifies {{UIEvent/view}}. This value MAY be null.
-
-
-
DOMString dataArg
-
- Specifies {{CompositionEvent/data}}.
-
-
-
-
-
-
Security Considerations
-
- TODO - Add specific concerns for this spec
-
-
Acknowledgements
-
- TODO
-
-
Refs to other UIEvent specs \[DELETE]
-
- This section will be deleted.
-
- Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
- beforeinput
- keydown
- keyup
- input
-
-
Things defined in other sections
-
Activation triggers and behavior
-
Default actions and cancelable events
-
Event dispatch and DOM event flow
-
Web browsers and other dynamic or interactive user agents
-
Authoring tools
-
-
Things defined in KeyboardEvents
-
Keyboard events and key values
-
Input Method Editors
-
Key Legends
-
-
Things defined in Changes
-
Changes between different drafts of UI Events
-
-
Glossary \[DELETE]
-
-This section will be deleted.
-
-Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-: activation behavior
-:: The action taken when an event, typically initiated by users through
- an input device, causes an element to fulfill a defined task. The task MAY
- be defined for that element by the host language, or by
- author-defined variables, or both. The default task for any given element
- MAY be a generic action, or MAY be unique to that element. For example, the
- activation behavior of an HTML or SVG <a> element is to
- cause the user agent to traverse the link specified in the
- href attribute, with the further optional parameter of
- specifying the browsing context for the traversal (such as the current
- window or tab, a named window, or a new window). The activation behavior of
- an HTML <input> element with the type
- attribute value submit is be to send the values of the form
- elements to an author-defined IRI by the author-defined HTTP method. See
- [[#event-flow-activation]] for more details.
-
-: activation trigger
-:: An event which is defined to initiate an activation behavior. Refer
- to [[#event-flow-activation]] for more details.
-
-: default action
-:: A default action is an OPTIONAL supplementary behavior that an
- implementation MUST perform in combination with the dispatch of the event
- object. Each event type definition, and each specification, defines the
- default action for that event type, if it has one. An instance of an
- event MAY have more than one default action under some circumstances,
- such as when associated with an activation trigger. A default
- action MAY be cancelled through the invocation of the
- {{Event/preventDefault()}} method. For more details, see
- [[#event-flow-default-cancel]].
-
-: empty string
-:: The empty string is a value of type DOMString of length
- 0, i.e., a string which contains no characters (neither
- printing nor control characters).
-
-: event
-:: An event is the representation of some occurrence (such as a mouse click on
- the presentation of an element, the removal of child node from an element,
- or any number of other possibilities) which is associated with its event
- target. Each event is an instantiation of one specific event
- type.
-
-: event target
-:: The object to which an event is targeted using the [[#event-flow]].
- The event target is the value of the {{Event/target}} attribute.
-
-: host language
-:: Any language which integrates the features of another language or API
- specification, while normatively referencing the origin specification rather
- than redefining those features, and extending those features only in ways
- defined by the origin specification. An origin specification typically is
- only intended to be implemented in the context of one or more host
- languages, not as a standalone language. For example, XHTML, HTML, and SVG
- are host languages for UI Events, and they integrate and extend the objects
- and models defined in this specification.
-
-: IME
-: input method editor
-:: An input method editor (IME), also known as a front end
- processor, is an application that performs the conversion between
- keystrokes and ideographs or other characters, usually by user-guided
- dictionary lookup, often used in East Asian languages (e.g., Chinese,
- Japanese, Korean). An IME MAY also be used for dictionary-based word
- completion, such as on mobile devices. See [[#keys-IME]] for treatment of
- IMEs in this specification. See also text composition system.
-
-: text composition system
-:: A software component that interprets some form of alternate input (such as a
- input method editor, a speech processor, or a handwriting recognition
- system) and converts it to text.
-
-: un-initialized value
-:: The value of any event attribute (such as {{Event/bubbles}} or
- {{Event/currentTarget}}) before the event has been initialized with
- {{Event/initEvent()}}. The un-initialized values of an event apply
- immediately after a new event has been created using the method
- {{Document/createEvent()}}.
-
-: user agent
-:: A program, such as a browser or content authoring tool, normally running on
- a client machine, which acts on a user's behalf in retrieving, interpreting,
- executing, presenting, or creating content. Users MAY act on the content
- using different user agents at different times, for different purposes. See
- the [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the
- requirements for a conforming user agent.
-
-: Window
-:: The Window is the object referred to by the current document's
- browsing context's Window Proxy object as defined in
- HTML5
- [[HTML5]].
-
diff --git a/split/focus-events.bs b/split/focus-events.bs
deleted file mode 100644
index 245b646..0000000
--- a/split/focus-events.bs
+++ /dev/null
@@ -1,552 +0,0 @@
-
Focus Events
-
-
-Shortname: focus-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
- *** Focus Events ***
-
- Note: This is an experimental split of the UI Events spec into smaller, event-specific
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
- interface Example {
- // This is an IDL definition.
- };
-
-
-
Focus Events
-
-
- This interface and its associated event types and
- [[#events-focusevent-event-order]]
- were designed in accordance to the concepts and guidelines defined in
- User Agent Accessibility Guidelines 2.0
- [[UAAG20]],
- with particular attention on the
- focus mechanism
- and the terms defined in the
- glossary entry for focus.
-
-
-
Interface FocusEvent
-
-
Introduced in this specification
-
- The {{FocusEvent}} interface provides specific contextual information
- associated with Focus events.
-
- To create an instance of the {{FocusEvent}} interface, use the
- FocusEvent constructor, passing an optional {{FocusEventInit}} dictionary.
-
-
- 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.
-
- The {{FocusEventInit/relatedTarget}} should be initialized to the element
- losing focus (in the case of a focus or focusin
- event) or the element gaining focus (in the case of a blur
- or focusout event).
-
-
-
-
Focus Event Order
-
- The focus events defined in this specification occur in a set order
- relative to one another. The following is the typical sequence of
- events when a focus is shifted between elements (this order assumes
- that no element is initially focused):
-
-
- 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.
-
-
-
- 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.
-
-
-
- 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.
-
-
-
- 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.
-
-
-
- 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.
-
-
-
- A user agent MUST dispatch this event when an event
- target receives focus. The focus MUST be given to the
- element before the dispatch of this event type. This event type
- MUST be dispatched after the event type focus.
-
-
- The DOMFocusIn event type is defined in this
- specification for reference and completeness, but this
- specification deprecates the use of this event type in
- favor of the related event types focus and focusin.
-
-
- A user agent MUST dispatch this event when an event
- target loses focus. The focus MUST be taken from the element
- before the dispatch of this event type. This event type MUST be
- dispatched after the event type blur.
-
-
- The DOMFocusOut event type is defined in this
- specification for reference and completeness, but this
- specification deprecates the use of this event type in
- favor of the related event types blur and focusout.
-
-
-
Legacy FocusEvent event order
-
- The following is the typical sequence of events when a focus is shifted
- between elements, including the deprecated DOMFocusIn and
- DOMFocusOut events. The order shown assumes that no element is
- initially focused.
-
-
-
- TODO - Add specific concerns for this spec
-
-
Acknowledgements
-
- TODO
-
-
Refs to other UIEvent specs \[DELETE]
-
- This section will be deleted.
-
- Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
-
Things defined in other sections
-
-
Activation triggers and behavior
-
Composition Events
-
Default actions and cancelable events
-
Event dispatch and DOM event flow
-
Web browsers and other dynamic or interactive user agents
-
Authoring tools
-
-
Glossary \[DELETE]
-
-This section will be deleted.
-
-Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-: event
-:: An event is the representation of some occurrence (such as a mouse click on
- the presentation of an element, the removal of child node from an element,
- or any number of other possibilities) which is associated with its event
- target. Each event is an instantiation of one specific event
- type.
-
-: event focus
-:: Event focus is a special state of receptivity and concentration on a
- particular element or other event target within a document. Each
- element has different behavior when focused, depending on its functionality,
- such as priming the element for activation (as for a button or hyperlink) or
- toggling state (as for a checkbox), receiving text input (as for a text form
- field), or copying selected text. For more details, see
- [[#events-focusevent-doc-focus]].
-
-: event target
-:: The object to which an event is targeted using the [[#event-flow]].
- The event target is the value of the {{Event/target}} attribute.
-
-: event focus ring
-:: An event focus ring is an ordered set of event focus targets within a
- document. A host language MAY define one or more ways to determine
- the order of targets, such as document order, a numerical index defined per
- focus target, explicit pointers between focus targets, or a hybrid of
- different models. Each document MAY contain multiple focus rings, or
- conditional focus rings. Typically, for document-order or indexed focus
- rings, focus wraps around from the last focus target to the
- first.
-
-: host language
-:: Any language which integrates the features of another language or API
- specification, while normatively referencing the origin specification rather
- than redefining those features, and extending those features only in ways
- defined by the origin specification. An origin specification typically is
- only intended to be implemented in the context of one or more host
- languages, not as a standalone language. For example, XHTML, HTML, and SVG
- are host languages for UI Events, and they integrate and extend the objects
- and models defined in this specification.
-
-: un-initialized value
-:: The value of any event attribute (such as {{Event/bubbles}} or
- {{Event/currentTarget}}) before the event has been initialized with
- {{Event/initEvent()}}. The un-initialized values of an event apply
- immediately after a new event has been created using the method
- {{Document/createEvent()}}.
-
-: user agent
-:: A program, such as a browser or content authoring tool, normally running on
- a client machine, which acts on a user's behalf in retrieving, interpreting,
- executing, presenting, or creating content. Users MAY act on the content
- using different user agents at different times, for different purposes. See
- the [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the
- requirements for a conforming user agent.
-
-: Window
-:: The Window is the object referred to by the current document's
- browsing context's Window Proxy object as defined in
- HTML5
- [[HTML5]].
-
diff --git a/split/focus-events.html b/split/focus-events.html
deleted file mode 100644
index 3985276..0000000
--- a/split/focus-events.html
+++ /dev/null
@@ -1,1782 +0,0 @@
-
-
-
-
- Focus Events
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Note: This is an experimental split of the UI Events spec into smaller, event-specific
-
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
-
Status of this document
-
-
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
-
This document was published by the Web Applications Working Group as an Editors Draft. This document is intended to become a W3C Recommendation.
Publication as an Editors Draft does not imply endorsement by W3C and its Members. This is a draft document and may
- be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite
- this document as other than work in progress.
-
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
The relatedTarget should be initialized to the element
- losing focus (in the case of a focus or focusin event) or the element gaining focus (in the case of a blur or focusout event).
-
-
3.2. Focus Event Order
-
The focus events defined in this specification occur in a set order
- relative to one another. The following is the typical sequence of
- events when a focus is shifted between elements (this order assumes
- that no element is initially focused):
This specification does not define the behavior of focus events when
- interacting with methods such as focus() or blur(). See the relevant specifications where those methods
- are defined for such behavior.
-
3.3. Document Focus and Focus Context
-
This event module includes event types for notification of changes in
- document focus. There are three distinct focus contexts that are
- relevant to this discussion:
-
-
-
The operating system focus context which MAY be on one of
-many different applications currently running on the computer. One
-of these applications with focus can be a browser.
-
-
When the browser has focus, the user can switch (such as with the
-tab key) the application focus context among the different
-browser user interface fields (e.g., the Web site location bar, a
-search field, etc.). One of these user interface fields can be the
-document being shown in a tab.
-
-
When the document itself has focus, the document focus
-context can be set to any of the focusable elements in the
-document.
-
-
The event types defined in this specification deal exclusively with
- document focus, and the event target identified in the event
- details MUST only be part of the document or documents in the window,
- never a part of the browser or operating system, even when switching
- from one focus context to another.
-
Normally, a document always has a focused element (even if it is the
- document element itself) and a persistent focus ring. When
- switching between focus contexts, the document’s currently focused
- element and focus ring normally remain in their current state. For
- example, if a document has three focusable elements, with the second
- element focused, when a user changes operating system focus to another
- application and then back to the browser, the second element will still
- be focused within the document, and tabbing will change the focus to the
- third element. A host language MAY define specific elements
- which might receive focus, the conditions under which an element MAY
- receive focus, the means by which focus MAY be changed, and the order
- in which the focus changes. For example, in some cases an element might
- be given focus by moving a pointer over it, while other circumstances
- might require a mouse click. Some elements might not be focusable at
- all, and some might be focusable only by special means (clicking on the
- element), but not by tabbing to it. Documents MAY contain multiple
- focus rings. Other specifications MAY define a more complex focus model
- than is described in this specification, including allowing multiple
- elements to have the current focus.
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.
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.
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.
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.
A user agent MUST dispatch this event when an event
- target receives focus. The focus MUST be given to the
- element before the dispatch of this event type. This event type
- MUST be dispatched after the event type focus.
-
The DOMFocusIn event type is defined in this
- specification for reference and completeness, but this
- specification deprecates the use of this event type in
- favor of the related event types focus and focusin.
A user agent MUST dispatch this event when an event
- target loses focus. The focus MUST be taken from the element
- before the dispatch of this event type. This event type MUST be
- dispatched after the event type blur.
-
The DOMFocusOut event type is defined in this
- specification for reference and completeness, but this
- specification deprecates the use of this event type in
- favor of the related event types blur and focusout.
-
4.2. Legacy FocusEvent event order
-
The following is the typical sequence of events when a focus is shifted
- between elements, including the deprecated DOMFocusIn and DOMFocusOut events. The order shown assumes that no element is
- initially focused.
Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
7.1. Things defined in other sections
-
7.1.1. Activation triggers and behavior
-
7.1.2. Composition Events
-
7.1.3. Default actions and cancelable events
-
7.1.4. Event dispatch and DOM event flow
-
7.1.5. Web browsers and other dynamic or interactive user agents
-
7.1.6. Authoring tools
-
8. Glossary [DELETE]
-
This section will be deleted.
-
Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-
event
-
-
An event is the representation of some occurrence (such as a mouse click on
-the presentation of an element, the removal of child node from an element,
-or any number of other possibilities) which is associated with its event
-target. Each event is an instantiation of one specific event
-type.
-
event focus
-
-
Event focus is a special state of receptivity and concentration on a
-particular element or other event target within a document. Each
-element has different behavior when focused, depending on its functionality,
-such as priming the element for activation (as for a button or hyperlink) or
-toggling state (as for a checkbox), receiving text input (as for a text form
-field), or copying selected text. For more details, see § 3.3 Document Focus and Focus Context.
An event focus ring is an ordered set of event focus targets within a document. A host language MAY define one or more ways to determine
-the order of targets, such as document order, a numerical index defined per
-focus target, explicit pointers between focus targets, or a hybrid of
-different models. Each document MAY contain multiple focus rings, or
-conditional focus rings. Typically, for document-order or indexed focus
-rings, focus wraps around from the last focus target to the
-first.
-
host language
-
-
Any language which integrates the features of another language or API
-specification, while normatively referencing the origin specification rather
-than redefining those features, and extending those features only in ways
-defined by the origin specification. An origin specification typically is
-only intended to be implemented in the context of one or more host
-languages, not as a standalone language. For example, XHTML, HTML, and SVG
-are host languages for UI Events, and they integrate and extend the objects
-and models defined in this specification.
-
un-initialized value
-
-
The value of any event attribute (such as bubbles or currentTarget) before the event has been initialized with initEvent(). The un-initialized values of an event apply
-immediately after a new event has been created using the method createEvent().
-
user agent
-
-
A program, such as a browser or content authoring tool, normally running on
-a client machine, which acts on a user’s behalf in retrieving, interpreting,
-executing, presenting, or creating content. Users MAY act on the content
-using different user agents at different times, for different purposes. See
-the § 7.1.5 Web browsers and other dynamic or interactive user agents and § 7.1.6 Authoring tools for details on the
-requirements for a conforming user agent.
-
Window
-
-
The Window is the object referred to by the current document’s
-browsing context’s Window Proxy object as defined in HTML5[HTML5].
-
-
-
-
Conformance
-
Document conventions
-
Conformance requirements are expressed
- with a combination of descriptive assertions
- and RFC 2119 terminology.
- The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”
- in the normative parts of this document
- are to be interpreted as described in RFC 2119.
- However, for readability,
- these words do not appear in all uppercase letters in this specification.
-
All of the text of this specification is normative
- except sections explicitly marked as non-normative, examples, and notes. [RFC2119]
-
Examples in this specification are introduced with the words “for example”
- or are set apart from the normative text
- with class="example",
- like this:
-
-
-
This is an example of an informative example.
-
-
Informative notes begin with the word “Note”
- and are set apart from the normative text
- with class="note",
- like this:
-
Note, this is an informative note.
-
-
Conformant Algorithms
-
Requirements phrased in the imperative as part of algorithms
- (such as "strip any leading space characters"
- or "return false and abort these steps")
- are to be interpreted with the meaning of the key word
- ("must", "should", "may", etc)
- used in introducing the algorithm.
-
Conformance requirements phrased as algorithms or specific steps
- can be implemented in any manner,
- so long as the end result is equivalent.
- In particular, the algorithms defined in this specification
- are intended to be easy to understand
- and are not intended to be performant.
- Implementers are encouraged to optimize.
-
-
-
\ No newline at end of file
diff --git a/split/focus-events.txt b/split/focus-events.txt
deleted file mode 100644
index 3e4cdee..0000000
--- a/split/focus-events.txt
+++ /dev/null
@@ -1,586 +0,0 @@
-
Focus Events
-
-
-Shortname: focus-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
- *** Focus Events ***
-
- Note: This is an experimental split of the UI Events spec into smaller, event-specific
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
- interface Example {
- // This is an IDL definition.
- };
-
-
-
Focus Events
-
-
- This interface and its associated event types and
- [[#events-focusevent-event-order]]
- were designed in accordance to the concepts and guidelines defined in
- User Agent Accessibility Guidelines 2.0
- [[UAAG20]],
- with particular attention on the
- focus mechanism
- and the terms defined in the
- glossary entry for focus.
-
-
-
Interface FocusEvent
-
-
Introduced in this specification
-
- The {{FocusEvent}} interface provides specific contextual information
- associated with Focus events.
-
- To create an instance of the {{FocusEvent}} interface, use the
- FocusEvent constructor, passing an optional {{FocusEventInit}} dictionary.
-
-
- 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.
-
- 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.
-
-
|
- ++------------------+--------------------------------------------------------------------------------------+
-
- 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.
-
-
|
- ++------------------+--------------------------------------------------------------------------------------+
-
- 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.
-
-
|
- ++------------------+--------------------------------------------------------------------------------------+
-
- 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.
-
-
|
- ++------------------+--------------------------------------------------------------------------------------+
-
- 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.
-
-
-
- A user agent MUST dispatch this event when an event
- target receives focus. The focus MUST be given to the
- element before the dispatch of this event type. This event type
- MUST be dispatched after the event type EVENT{focus}.
-
-
- The EVENT{DOMFocusIn} event type is defined in this
- specification for reference and completeness, but this
- specification deprecates the use of this event type in
- favor of the related event types EVENT{focus} and EVENT{focusin}.
-
-
- A user agent MUST dispatch this event when an event
- target loses focus. The focus MUST be taken from the element
- before the dispatch of this event type. This event type MUST be
- dispatched after the event type EVENT{blur}.
-
-
- The EVENT{DOMFocusOut} event type is defined in this
- specification for reference and completeness, but this
- specification deprecates the use of this event type in
- favor of the related event types EVENT{blur} and EVENT{focusout}.
-
-
-
Legacy FocusEvent event order
-
- The following is the typical sequence of events when a focus is shifted
- between elements, including the deprecated EVENT{DOMFocusIn} and
- EVENT{DOMFocusOut} events. The order shown assumes that no element is
- initially focused.
-
- ++---+-------------+---------------------------------------------------+
- =| # | Event Type | Notes |
- +---+-------------+---------------------------------------------------+
- +| | | User shifts focus |
- +| 1 | focusin | Sent before first target element receives focus |
- +| 2 | focus | Sent after first target element receives focus |
- +| 3 | DOMFocusIn | If supported |
- +| | | User shifts focus |
- +| 4 | focusout | Sent before first target element loses focus |
- +| 5 | focusin | Sent before second target element receives focus |
- +| 6 | blur | Sent after first target element loses focus |
- +| 7 | DOMFocusOut | If supported |
- +| 8 | focus | Sent after second target element receives focus |
- +| 9 | DOMFocusIn | If supported |
- ++---+-------------+---------------------------------------------------+
-
-
Security Considerations
-
- TODO - Add specific concerns for this spec
-
-
Acknowledgements
-
- TODO
-
-
Refs to other UIEvent specs \[DELETE]
-
- This section will be deleted.
-
- Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
-
Things defined in other sections
-
-
Activation triggers and behavior
-
Composition Events
-
Default actions and cancelable events
-
Event dispatch and DOM event flow
-
Web browsers and other dynamic or interactive user agents
-
Authoring tools
-
-
Glossary \[DELETE]
-
-This section will be deleted.
-
-Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-: event
-:: An event is the representation of some occurrence (such as a mouse click on
- the presentation of an element, the removal of child node from an element,
- or any number of other possibilities) which is associated with its event
- target. Each event is an instantiation of one specific event
- type.
-
-: event focus
-:: Event focus is a special state of receptivity and concentration on a
- particular element or other event target within a document. Each
- element has different behavior when focused, depending on its functionality,
- such as priming the element for activation (as for a button or hyperlink) or
- toggling state (as for a checkbox), receiving text input (as for a text form
- field), or copying selected text. For more details, see
- [[#events-focusevent-doc-focus]].
-
-: event target
-:: The object to which an event is targeted using the [[#event-flow]].
- The event target is the value of the {{Event/target}} attribute.
-
-: event focus ring
-:: An event focus ring is an ordered set of event focus targets within a
- document. A host language MAY define one or more ways to determine
- the order of targets, such as document order, a numerical index defined per
- focus target, explicit pointers between focus targets, or a hybrid of
- different models. Each document MAY contain multiple focus rings, or
- conditional focus rings. Typically, for document-order or indexed focus
- rings, focus wraps around from the last focus target to the
- first.
-
-: host language
-:: Any language which integrates the features of another language or API
- specification, while normatively referencing the origin specification rather
- than redefining those features, and extending those features only in ways
- defined by the origin specification. An origin specification typically is
- only intended to be implemented in the context of one or more host
- languages, not as a standalone language. For example, XHTML, HTML, and SVG
- are host languages for UI Events, and they integrate and extend the objects
- and models defined in this specification.
-
-: un-initialized value
-:: The value of any event attribute (such as {{Event/bubbles}} or
- {{Event/currentTarget}}) before the event has been initialized with
- {{Event/initEvent()}}. The un-initialized values of an event apply
- immediately after a new event has been created using the method
- {{Document/createEvent()}}.
-
-: user agent
-:: A program, such as a browser or content authoring tool, normally running on
- a client machine, which acts on a user's behalf in retrieving, interpreting,
- executing, presenting, or creating content. Users MAY act on the content
- using different user agents at different times, for different purposes. See
- the [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the
- requirements for a conforming user agent.
-
-: Window
-:: The Window is the object referred to by the current document's
- browsing context's Window Proxy object as defined in
- HTML5
- [[HTML5]].
-
diff --git a/split/input-events.bs b/split/input-events.bs
deleted file mode 100644
index 2097322..0000000
--- a/split/input-events.bs
+++ /dev/null
@@ -1,312 +0,0 @@
-
Input Events
-
-
-Shortname: input-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
- *** Input Events ***
-
- Note: This is an experimental split of the UI Events spec into smaller, event-specific
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
- interface Example {
- // This is an IDL definition.
- };
-
-
-
Input Events
-
- Input events are sent as notifications whenever the DOM is being updated (or about
- to be updated) as a direct result of a user action (e.g., keyboard input in an editable
- region, deleting or formatting text, ...).
-
-
- data holds the value of the characters generated by
- an input method. This MAY be a single Unicode character or a
- non-empty sequence of Unicode characters [[Unicode]]. Characters
- SHOULD be normalized as defined by the Unicode normalization
- form NFC, defined in [[UAX15]].
- This attribute MAY contain the empty string.
-
- The un-initialized value of this attribute MUST be
- null.
-
-
-
isComposing
-
- true if the input event occurs as part of a
- composition session, i.e., after a compositionstart event
- and before the corresponding compositionend event.
-
- The un-initialized value of this attribute MUST be
- false.
-
-
-
inputType
-
- inputType contains a string that identifies the type
- of input associated with the event.
-
- For a list of valid values for this attribute, refer to the
- [[Input-Events]] specification.
-
- The un-initialized value of this attribute MUST be
- the empty string "".
-
{{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
-
-
-
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
{{InputEvent}}.{{InputEvent/data}} : the string containing the data that has been added to the element, which MAY be the empty string if the content has been deleted
{{InputEvent}}.{{InputEvent/isComposing}} : true if this event is dispatched during a dead key sequence or while an input method editor is active (such that composition events are being dispatched); false otherwise.
-
-
- A user agent MUST dispatch this event immediately after the
- DOM has been updated.
-
-
Security Considerations
-
- TODO - Add specific concerns for this spec
-
-
Acknowledgements
-
- TODO
-
- Note: Include people from Editing/Input who have contributed.
-
-
Refs to other UIEvent specs \[DELETE]
-
- This section will be deleted.
-
- Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
- compositionend
- compositionstart
-
-
Things defined in other sections
-
-
Activation triggers and behavior
-
Composition Events
-
Default actions and cancelable events
-
Event dispatch and DOM event flow
-
Web browsers and other dynamic or interactive user agents
-
Authoring tools
-
-
Things defined in KeyboardEvents
-
Dead keys
-
Input Method Editors
-
-
Glossary \[DELETE]
-
-This section will be deleted.
-
-Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-: empty string
-:: The empty string is a value of type DOMString of length
- 0, i.e., a string which contains no characters (neither
- printing nor control characters).
-
-: event
-:: An event is the representation of some occurrence (such as a mouse click on
- the presentation of an element, the removal of child node from an element,
- or any number of other possibilities) which is associated with its event
- target. Each event is an instantiation of one specific event
- type.
-
-: event target
-:: The object to which an event is targeted using the [[#event-flow]].
- The event target is the value of the {{Event/target}} attribute.
-
-: IME
-: input method editor
-:: An input method editor (IME), also known as a front end
- processor, is an application that performs the conversion between
- keystrokes and ideographs or other characters, usually by user-guided
- dictionary lookup, often used in East Asian languages (e.g., Chinese,
- Japanese, Korean). An IME MAY also be used for dictionary-based word
- completion, such as on mobile devices. See [[#keys-IME]] for treatment of
- IMEs in this specification. See also text composition system.
-
-: text composition system
-:: A software component that interprets some form of alternate input (such as a
- input method editor, a speech processor, or a handwriting recognition
- system) and converts it to text.
-
-: un-initialized value
-:: The value of any event attribute (such as {{Event/bubbles}} or
- {{Event/currentTarget}}) before the event has been initialized with
- {{Event/initEvent()}}. The un-initialized values of an event apply
- immediately after a new event has been created using the method
- {{Document/createEvent()}}.
-
-: user agent
-:: A program, such as a browser or content authoring tool, normally running on
- a client machine, which acts on a user's behalf in retrieving, interpreting,
- executing, presenting, or creating content. Users MAY act on the content
- using different user agents at different times, for different purposes. See
- the [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the
- requirements for a conforming user agent.
-
-: Window
-:: The Window is the object referred to by the current document's
- browsing context's Window Proxy object as defined in
- HTML5
- [[HTML5]].
-
diff --git a/split/input-events.html b/split/input-events.html
deleted file mode 100644
index d482a0f..0000000
--- a/split/input-events.html
+++ /dev/null
@@ -1,1513 +0,0 @@
-
-
-
-
- Input Events
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Note: This is an experimental split of the UI Events spec into smaller, event-specific
-
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
-
Status of this document
-
-
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
-
This document was published by the Web Applications Working Group as an Editors Draft. This document is intended to become a W3C Recommendation.
Publication as an Editors Draft does not imply endorsement by W3C and its Members. This is a draft document and may
- be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite
- this document as other than work in progress.
-
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
interface Example {
- // This is an IDL definition.
-};
-
-
3. Input Events
-
Input events are sent as notifications whenever the DOM is being updated (or about
- to be updated) as a direct result of a user action (e.g., keyboard input in an editable
- region, deleting or formatting text, ...).
- 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.
-
- true if the input event occurs as part of a
- composition session, i.e., after a compositionstart event
- and before the corresponding compositionend event.
-
A user agent MUST dispatch this event immediately after the
- DOM has been updated.
-
4. Security Considerations
-
TODO - Add specific concerns for this spec
-
5. Acknowledgements
-
TODO
-
Note: Include people from Editing/Input who have contributed.
-
6. Refs to other UIEvent specs [DELETE]
-
This section will be deleted.
-
Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
compositionend compositionstart
-
6.1. Things defined in other sections
-
6.1.1. Activation triggers and behavior
-
6.1.2. Composition Events
-
6.1.3. Default actions and cancelable events
-
6.1.4. Event dispatch and DOM event flow
-
6.1.5. Web browsers and other dynamic or interactive user agents
-
6.1.6. Authoring tools
-
6.2. Things defined in KeyboardEvents
-
6.2.1. Dead keys
-
6.2.2. Input Method Editors
-
7. Glossary [DELETE]
-
This section will be deleted.
-
Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-
empty string
-
-
The empty string is a value of type DOMString of length 0, i.e., a string which contains no characters (neither
-printing nor control characters).
-
event
-
-
An event is the representation of some occurrence (such as a mouse click on
-the presentation of an element, the removal of child node from an element,
-or any number of other possibilities) which is associated with its event
-target. Each event is an instantiation of one specific event
-type.
An input method editor (IME), also known as a front end
-processor, is an application that performs the conversion between
-keystrokes and ideographs or other characters, usually by user-guided
-dictionary lookup, often used in East Asian languages (e.g., Chinese,
-Japanese, Korean). An IME MAY also be used for dictionary-based word
-completion, such as on mobile devices. See § 6.2.2 Input Method Editors for treatment of
-IMEs in this specification. See also text composition system.
-
text composition system
-
-
A software component that interprets some form of alternate input (such as a input method editor, a speech processor, or a handwriting recognition
-system) and converts it to text.
-
un-initialized value
-
-
The value of any event attribute (such as bubbles or currentTarget) before the event has been initialized with initEvent(). The un-initialized values of an event apply
-immediately after a new event has been created using the method createEvent().
-
user agent
-
-
A program, such as a browser or content authoring tool, normally running on
-a client machine, which acts on a user’s behalf in retrieving, interpreting,
-executing, presenting, or creating content. Users MAY act on the content
-using different user agents at different times, for different purposes. See
-the § 6.1.5 Web browsers and other dynamic or interactive user agents and § 6.1.6 Authoring tools for details on the
-requirements for a conforming user agent.
-
Window
-
-
The Window is the object referred to by the current document’s
-browsing context’s Window Proxy object as defined in HTML5[HTML5].
-
-
-
-
Conformance
-
Document conventions
-
Conformance requirements are expressed
- with a combination of descriptive assertions
- and RFC 2119 terminology.
- The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”
- in the normative parts of this document
- are to be interpreted as described in RFC 2119.
- However, for readability,
- these words do not appear in all uppercase letters in this specification.
-
All of the text of this specification is normative
- except sections explicitly marked as non-normative, examples, and notes. [RFC2119]
-
Examples in this specification are introduced with the words “for example”
- or are set apart from the normative text
- with class="example",
- like this:
-
-
-
This is an example of an informative example.
-
-
Informative notes begin with the word “Note”
- and are set apart from the normative text
- with class="note",
- like this:
-
Note, this is an informative note.
-
-
Conformant Algorithms
-
Requirements phrased in the imperative as part of algorithms
- (such as "strip any leading space characters"
- or "return false and abort these steps")
- are to be interpreted with the meaning of the key word
- ("must", "should", "may", etc)
- used in introducing the algorithm.
-
Conformance requirements phrased as algorithms or specific steps
- can be implemented in any manner,
- so long as the end result is equivalent.
- In particular, the algorithms defined in this specification
- are intended to be easy to understand
- and are not intended to be performant.
- Implementers are encouraged to optimize.
-
-
-
\ No newline at end of file
diff --git a/split/input-events.txt b/split/input-events.txt
deleted file mode 100644
index 7dfa98a..0000000
--- a/split/input-events.txt
+++ /dev/null
@@ -1,345 +0,0 @@
-
Input Events
-
-
-Shortname: input-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
- *** Input Events ***
-
- Note: This is an experimental split of the UI Events spec into smaller, event-specific
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
- interface Example {
- // This is an IDL definition.
- };
-
-
-
Input Events
-
- Input events are sent as notifications whenever the DOM is being updated (or about
- to be updated) as a direct result of a user action (e.g., keyboard input in an editable
- region, deleting or formatting text, ...).
-
-
- 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 "".
-
- 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
{{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
{{InputEvent}}.{{InputEvent/data}} : the string containing the data that has |
- | | been added to the element, which MAY be the empty string if the content |
- | | has been deleted
|
- | |
{{InputEvent}}.{{InputEvent/isComposing}} : true if this event is |
- | | dispatched during a dead key sequence or while an |
- | | input method editor is active (such that |
- | | composition events are being dispatched);|
- | | false otherwise.
|
- | |
|
- ++------------------+--------------------------------------------------------------------------------------+
-
- A user agent MUST dispatch this event immediately after the
- DOM has been updated.
-
-
Security Considerations
-
- TODO - Add specific concerns for this spec
-
-
Acknowledgements
-
- TODO
-
- Note: Include people from Editing/Input who have contributed.
-
-
Refs to other UIEvent specs \[DELETE]
-
- This section will be deleted.
-
- Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
- compositionend
- compositionstart
-
-
Things defined in other sections
-
-
Activation triggers and behavior
-
Composition Events
-
Default actions and cancelable events
-
Event dispatch and DOM event flow
-
Web browsers and other dynamic or interactive user agents
-
Authoring tools
-
-
Things defined in KeyboardEvents
-
Dead keys
-
Input Method Editors
-
-
Glossary \[DELETE]
-
-This section will be deleted.
-
-Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-: empty string
-:: The empty string is a value of type DOMString of length
- 0, i.e., a string which contains no characters (neither
- printing nor control characters).
-
-: event
-:: An event is the representation of some occurrence (such as a mouse click on
- the presentation of an element, the removal of child node from an element,
- or any number of other possibilities) which is associated with its event
- target. Each event is an instantiation of one specific event
- type.
-
-: event target
-:: The object to which an event is targeted using the [[#event-flow]].
- The event target is the value of the {{Event/target}} attribute.
-
-: IME
-: input method editor
-:: An input method editor (IME), also known as a front end
- processor, is an application that performs the conversion between
- keystrokes and ideographs or other characters, usually by user-guided
- dictionary lookup, often used in East Asian languages (e.g., Chinese,
- Japanese, Korean). An IME MAY also be used for dictionary-based word
- completion, such as on mobile devices. See [[#keys-IME]] for treatment of
- IMEs in this specification. See also text composition system.
-
-: text composition system
-:: A software component that interprets some form of alternate input (such as a
- input method editor, a speech processor, or a handwriting recognition
- system) and converts it to text.
-
-: un-initialized value
-:: The value of any event attribute (such as {{Event/bubbles}} or
- {{Event/currentTarget}}) before the event has been initialized with
- {{Event/initEvent()}}. The un-initialized values of an event apply
- immediately after a new event has been created using the method
- {{Document/createEvent()}}.
-
-: user agent
-:: A program, such as a browser or content authoring tool, normally running on
- a client machine, which acts on a user's behalf in retrieving, interpreting,
- executing, presenting, or creating content. Users MAY act on the content
- using different user agents at different times, for different purposes. See
- the [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the
- requirements for a conforming user agent.
-
-: Window
-:: The Window is the object referred to by the current document's
- browsing context's Window Proxy object as defined in
- HTML5
- [[HTML5]].
-
diff --git a/split/keyboard-events.bs b/split/keyboard-events.bs
deleted file mode 100644
index 32266a9..0000000
--- a/split/keyboard-events.bs
+++ /dev/null
@@ -1,2282 +0,0 @@
-
Keyboard Events
-
-
-Shortname: keyboard-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
- *** Keyboard Events ***
-
- Note: This is an experimental split of the UI Events spec into smaller, event-specific
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
-{
- "DWW95": {
- "title": "Developing International Software for Windows 95 and Windows NT: A Handbook for International Software Design",
- "authors": [ "N. Kano" ],
- "publisher": "Microsoft Press",
- "date": "1995",
- "isbn": "1-55615-840-8"
- },
- "US-ASCII": {
- "title": "Coded Character Set - 7-Bit American Standard Code for Information Interchange",
- "publisher": "Standard ANSI X3.4-1986",
- "date": "1986"
- },
- "WIN1252": {
- "title": "Windows 1252 a Coded Character Set - 8-Bit",
- "href": "https://www.microsoft.com/globaldev/reference/sbcs/1252.htm",
- "publisher": "Microsoft Corporation"
- }
-}
-
-
-
Introduction
-
-
Overview
-
- TODO.
-
-
Conformance
-
- Boilerplate?
-
-
Stylistic Conventions
-
-This specification follows the
-Proposed W3C Specification Conventions,
-with the following supplemental additions:
-
-* The key cap printed on a key is shown as
- ↓, = or Q. This is used to refer to a
- key from the user's perspective without regard for the
- {{KeyboardEvent/key}} and {{KeyboardEvent/code}} values in the
- generated {{KeyboardEvent}}.
-
-* Glyphs representing character are shown as: "𣧂".
-
-* Unicode character encodings are shown as: U+003d.
-
-* Names of key values generated by a key press (i.e., the value of
- {{KeyboardEvent}}.{{KeyboardEvent/key}}) are shown as:
- "ArrowDown", "=", "q" or "Q".
-
-* Names of key codes associated with the physical keys (i.e., the
- value of {{KeyboardEvent}}.{{KeyboardEvent/code}}) are shown as:
- "ArrowDown", "Equal" or "KeyQ".
-
-
-In addition, certain terms are used in this specification with particular
-meanings. The term implementation applies to a browser, content
-authoring tool, or other user agent that implements this specification,
-while a content author is a person who writes script or code that takes
-advantage of the interfaces, methods, attributes, events, and other features
-described in this specification in order to make Web applications, and a user is
-the person who uses those Web applications in an implementation.
-
-And finally:
-
-
This is a note.
-
-
-
-
This is an open issue.
-
-
This is a warning.
-
-
- interface Example {
- // This is an IDL definition.
- };
-
-
-
Keyboard Events
-
- Keyboard events are device dependent, i.e., they rely on the capabilities of
- the input devices and how they are mapped in the operating systems. Refer to
- Keyboard events and key values for more details,
- including examples on how Keyboard Events are used in combination with
- Composition Events. Depending on the character generation device, keyboard
- events might not be generated.
-
-
- Keyboard events are only one modality of providing textual input. For
- editing scenarios, consider also using the {{InputEvent}} as an alternate to
- (or in addition to) keyboard events.
-
-
-
Interface KeyboardEvent
-
-
Introduced in this specification
-
- The {{KeyboardEvent}} interface provides specific contextual information
- associated with keyboard devices. Each keyboard event references a key
- using a value. Keyboard events are commonly directed at the element that
- has the focus.
-
- The {{KeyboardEvent}} interface provides convenient attributes for some
- common modifiers keys: {{KeyboardEvent/ctrlKey}},
- {{KeyboardEvent/shiftKey}}, {{KeyboardEvent/altKey}},
- {{KeyboardEvent/metaKey}}. These attributes are equivalent to using the
- method {{KeyboardEvent/getModifierState()}} with Control,
- Shift, Alt, or Meta respectively.
-
- To create an instance of the {{KeyboardEvent}} interface, use the
- {{KeyboardEvent}} constructor, passing an optional
- {{KeyboardEventInit}} dictionary.
-
-
- The key activation MUST NOT be distinguished as the left or
- right version of the key, and (other than the NumLock
- key) did not originate from the numeric keypad (or did not
- originate with a virtual key corresponding to the numeric
- keypad).
-
-
- The Q key on a PC 101 Key US keyboard.
- The NumLock key on a PC 101 Key US keyboard.
- The 1 key on a PC 101 Key US keyboard located in the
- main section of the keyboard.
-
-
-
-
DOM_KEY_LOCATION_LEFT
-
- The key activated originated from the left key location (when
- there is more than one possible location for this key).
-
-
- The left Control key on a PC 101 Key US keyboard.
-
-
-
-
DOM_KEY_LOCATION_RIGHT
-
- The key activation originated from the right key location (when
- there is more than one possible location for this key).
-
-
- The right Shift key on a PC 101 Key US keyboard.
-
-
-
-
DOM_KEY_LOCATION_NUMPAD
-
- The key activation originated on the numeric keypad or with a
- virtual key corresponding to the numeric keypad (when there is
- more than one possible location for this key). Note that the
- NumLock key should always be encoded with a
- {{KeyboardEvent/location}} of
- {{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}}.
-
-
- The 1 key on a PC 101 Key US keyboard located on the
- numeric pad.
-
-
-
-
key
-
- key holds a [=key attribute value=] corresponding to
- the key pressed.
-
-
- The key attribute is not related to the legacy
- keyCode attribute and does not have the same set of
- values.
-
-
- The un-initialized value of this attribute MUST be
- "" (the empty string).
-
-
-
code
-
- code holds a string that identifies the physical
- key being pressed. The value is not affected by the current
- keyboard layout or modifier state, so a particular key will
- always return the same value.
-
- The un-initialized value of this attribute MUST be
- "" (the empty string).
-
-
-
location
-
- The {{KeyboardEvent/location}} attribute contains an indication
- of the logical location of the key on the device.
-
- This attribute MUST be set to one of the DOM_KEY_LOCATION
- constants to indicate the location of a key on the device.
-
- If a user agent allows keys to be remapped, then the
- {{KeyboardEvent/location}} value for a remapped key MUST be set
- to a value which is appropriate for the new key. For example, if
- the "ControlLeft" key is mapped to the "KeyQ" key, then
- the {{KeyboardEvent/location}} attribute MUST be set to
- {{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}}. Conversely, if the
- "KeyQ" key is remapped to one of the Control keys,
- then the {{KeyboardEvent/location}} attribute MUST be set to
- either {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} or
- {{KeyboardEvent/DOM_KEY_LOCATION_RIGHT}}.
-
- The un-initialized value of this attribute MUST be
- 0.
-
-
-
ctrlKey
-
- true if the Control (control) key modifier
- was active.
-
- The un-initialized value of this attribute MUST be
- false.
-
-
-
shiftKey
-
- true if the shift (Shift) key modifier was
- active.
-
- The un-initialized value of this attribute MUST be
- false.
-
-
-
altKey
-
- true if the Alt (alternative) (or
- "Option") key modifier was active.
-
- The un-initialized value of this attribute MUST be
- false.
-
-
-
metaKey
-
- true if the meta (Meta) key modifier was
- active.
-
-
- The "Command" ("⌘") key modifier on Macintosh
- systems is represented using this key modifier.
-
- true if the key has been pressed in a sustained
- manner. Holding down a key MUST result in the repeating the
- events keydown, beforeinput, input in this
- order, at a rate determined by the system configuration. For
- mobile devices which have long-key-press behavior, the
- first key event with a {{KeyboardEvent/repeat}} attribute value
- of true MUST serve as an indication of a
- long-key-press. The length of time that the key MUST be
- pressed in order to begin repeating is configuration-dependent.
-
- The un-initialized value of this attribute MUST be
- false.
-
-
-
isComposing
-
- true if the key event occurs as part of a
- composition session, i.e., after a compositionstart event
- and before the corresponding compositionend event.
-
- The un-initialized value of this attribute MUST be
- false.
-
-
-
getModifierState(keyArg)
-
- Queries the state of a modifier using a key value.
-
- Returns true if it is a modifier key and
- the modifier is activated, false otherwise.
-
-
-
DOMString keyArg
-
- A modifier key value. Valid [=modifier keys=] are defined
- in the [=Modifier Keys table=] in [[UIEvents-Key]].
-
-
- If an application wishes to distinguish between right
- and left modifiers, this information could be deduced
- using keyboard events and {{KeyboardEvent/location}}.
-
- Initializes the key attribute of the KeyboardEvent
- object to the unicode character string representing the meaning
- of a key after taking into account all keyboard modifiers
- (such as shift-state). This value is the final effective value
- of the key. If the key is not a printable character, then it
- should be one of the key values defined in [[UIEvents-Key]].
-
-
-
code
-
- Initializes the code attribute of the KeyboardEvent
- object to the unicode character string representing the key that
- was pressed, ignoring any keyboard modifications such as
- keyboard layout. This value should be one of the code values
- defined in [[UIEvents-Code]].
-
-
-
location
-
- Initializes the {{KeyboardEvent/location}} attribute of the
- KeyboardEvent object to one of the following location numerical
- constants:
-
- * {{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}} (numerical value 0)
- * {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} (numerical value 1)
- * {{KeyboardEvent/DOM_KEY_LOCATION_RIGHT}} (numerical value 2)
- * {{KeyboardEvent/DOM_KEY_LOCATION_NUMPAD}} (numerical value 3)
-
-
-
repeat
-
- Initializes the repeat attribute of the
- KeyboardEvent object. This attribute should be set to
- true if the the current KeyboardEvent is considered
- part of a repeating sequence of similar events caused by the
- long depression of any single key, false otherwise.
-
-
-
isComposing
-
- Initializes the isComposing attribute of the
- KeyboardEvent object. This attribute should be set to
- true if the event being constructed occurs as part
- of a composition sequence, false otherwise.
-
-
-
-
- Legacy keyboard event implementations include three additional attributes,
- keyCode, charCode, and which. The
- keyCode attribute indicates a numeric value associated with a
- particular key on a computer keyboard, while the charCode
- attribute indicates the ASCII value of the character associated
- with that key (which might be the same as the keyCode value)
- and is applicable only to keys that produce a character value.
-
- In practice, keyCode and charCode are inconsistent
- across platforms and even the same implementation on different operating
- systems or using different localizations. This specification does not define
- values for either keyCode or charCode, or behavior
- for charCode. In conforming UI Events implementations, content
- authors can instead use {{KeyboardEvent/key}} and {{KeyboardEvent/code}}.
-
- For more information, see the informative appendix on
- Legacy key attributes.
-
-
-
- For compatibility with existing content, virtual keyboards, such as software
- keyboards on screen-based input devices, are expected to produce the normal
- range of keyboard events, even though they do not possess physical keys.
-
-
-
- In some implementations or system configurations, some key events, or their
- values, might be suppressed by the IME in use.
-
-
-
Keyboard Event Key Location
-
- The {{KeyboardEvent/location}} attribute can be used to disambiguate
- between {{KeyboardEvent/key}} values that can be generated by different
- physical keys on the keyboard, for example, the left and right
- Shift key or the physical arrow keys vs. the numpad arrow keys
- (when NumLock is off).
-
- The following table defines the valid {{KeyboardEvent/location}} values
- for the special keys that have more than one location on the keyboard:
-
-
-
- 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:
-
-
- Typically, any default actions associated with any particular key
- are completed before the keyup event is dispatched. This might
- delay the keyup event slightly (though this is not likely to be a
- perceptible delay).
-
-
- The event target of a key event is the currently focused element
- which is processing the keyboard activity. This is often an HTML
- input element or a textual element which is editable, but
- MAY be an element defined by the host language to accept keyboard
- input for non-text purposes, such as the activation of an accelerator
- key or trigger of some other behavior. If no suitable element is in
- focus, the event target will be the HTML body element if
- available, otherwise the root element.
-
-
- The event target might change between different key events. For
- example, a keydown event for the Tab key will likely have
- a different event target than the keyup event on the same
- keystroke.
-
-
{{Event}}.{{Event/target}} : focused element processing the key event or if no element focused, then the body element if available, otherwise the root element
{{KeyboardEvent}}.{{KeyboardEvent/key}} : the key value of the key pressed.
{{KeyboardEvent}}.{{KeyboardEvent/code}} : the code value associated with the key's physical placement on the keyboard.
{{KeyboardEvent}}.{{KeyboardEvent/location}} : the location of the key on the device.
{{KeyboardEvent}}.{{KeyboardEvent/altKey}} : true if Alt modifier was active, otherwise false
{{KeyboardEvent}}.{{KeyboardEvent/shiftKey}} : true if Shift modifier was active, otherwise false
{{KeyboardEvent}}.{{KeyboardEvent/ctrlKey}} : true if Control modifier was active, otherwise false
{{KeyboardEvent}}.{{KeyboardEvent/metaKey}} : true if Meta modifier was active, otherwise false
{{KeyboardEvent}}.{{KeyboardEvent/repeat}} : true if a key has been depressed long enough to trigger key repetition, otherwise false
{{KeyboardEvent}}.{{KeyboardEvent/isComposing}} : true if the key event occurs as part of a composition session, otherwise false
-
-
- A user agent MUST dispatch this event when a key is pressed
- down. The keydown event type is device dependent and relies
- on the capabilities of the input devices and how they are mapped in
- the operating system. This event type MUST be generated after the
- key mapping. This event type MUST be dispatched before the
- beforeinput, input, and keyup events associated
- with the same key.
-
- The default action of the keydown event depends upon the key:
-
- * If the key is associated with a character, the default action
- MUST be to dispatch a beforeinput event followed by an
- input event. In the case where the key which is
- associated with multiple characters (such as with a macro or
- certain sequences of dead keys), the default action MUST be to
- dispatch one set of beforeinput / input events for
- each character
-
- * If the key is associated with a text composition system,
- the default action MUST be to launch that system
-
- * If the key is the Tab key, the default action MUST be
- to shift the document focus from the currently focused element
- (if any) to the new focused element, as described in
- Focus Event Types
-
- * If the key is the Enter or (Space) key and the
- current focus is on a state-changing element, the default action
- MUST be to dispatch a click event, and a
- DOMActivate event if that event type is supported by the
- user agent (refer to [[#event-flow-activation]] for more
- details)
-
- If this event is canceled, the associated event types MUST NOT be
- dispatched, and the associated actions MUST NOT be performed.
-
-
- The keydown and keyup events are traditionally
- associated with detecting any key, not just those which produce a
- character value.
-
-
-
keyup
-
-
-
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
{{KeyboardEvent}}.{{KeyboardEvent/key}} : the key value of the key pressed.
{{KeyboardEvent}}.{{KeyboardEvent/code}} : the code value associated with the key's physical placement on the keyboard.
{{KeyboardEvent}}.{{KeyboardEvent/location}} : the location of the key on the device.
{{KeyboardEvent}}.{{KeyboardEvent/altKey}} : true if Alt modifier was active, otherwise false
{{KeyboardEvent}}.{{KeyboardEvent/shiftKey}} : true if Shift modifier was active, otherwise false
{{KeyboardEvent}}.{{KeyboardEvent/ctrlKey}} : true if Control modifier was active, otherwise false
{{KeyboardEvent}}.{{KeyboardEvent/metaKey}} : true if Meta modifier was active, otherwise false
{{KeyboardEvent}}.{{KeyboardEvent/repeat}} : true if a key has been depressed long enough to trigger key repetition, otherwise false
{{KeyboardEvent}}.{{KeyboardEvent/isComposing}} : true if the key event occurs as part of a composition session, otherwise false
-
-
- A user agent MUST dispatch this event when a key is released.
- The keyup event type is device dependent and relies on the
- capabilities of the input devices and how they are mapped in the
- operating system. This event type MUST be generated after the key
- mapping. This event type MUST be dispatched after the
- keydown, beforeinput, and input events
- associated with the same key.
-
-
- The keydown and keyup events are traditionally
- associated with detecting any key, not just those which produce a
- character value.
-
-
-
-
Keyboard events and key values
-
- This section contains necessary information regarding keyboard events:
-
- * Explanation of keyboard layout, mapping, and key values.
- * Relations between keys, such as dead keys or modifiers keys.
- * Relations between keyboard events and their default actions.
- * The set of key values, and guidelines on how to extend this set.
-
-
- This section uses Serbian and Kanji characters which could be misrepresented or
- unavailable in the PDF version or printed version of this specification.
-
-
-
Keyboard Input
-
- This section is non-normative
-
- The relationship of each key to the complete keyboard has three separate
- aspects, each of which vary among different models and configurations of
- keyboards, particularly for locale-specific reasons:
-
- * Mechanical layout: the dimensions, size, and placement
- of the physical keys on the keyboard
- * Visual markings: the labels (or legends) that
- mark each key
- * Functional mapping: the abstract key-value association
- of each key.
-
- This specification only defines the functional mapping, in terms of
- key values and
- code values,
- but briefly describes key legends
- for background.
-
-
Key Legends
-
- This section is informative
-
- The key legend is the visual marking that is printed or embossed on the
- key cap (the rectangular "cap" that covers the mechanical
- switch for the key). These markings normally consist of one or more
- characters that a keystroke on that key will produce (such as "G",
- "8", or "ш"), or names or symbols which indicate that key's
- function (such as an upward-pointing arrow "⇧" indicating
- Shift, or the string "Enter"). Keys are often
- referred to by this marking (e.g., Press the "Shift" and
- "G" keys.). Note, however, that the visual appearance
- of the key has no bearing on its digital representation, and in many
- configurations may be completely inaccurate. Even the control and
- function keys, such as Enter, may be mapped to different
- functionality, or even mapped as character keys.
-
-
- Many keyboards contain keys that do not normally produce any characters,
- even though the symbol might have a Unicode equivalent. For example, the
- Shift key might bear the symbol "⇧", which has the
- Unicode code point U+21E7, but
- pressing the Shift key will not produce this character value,
- and there is no Unicode code point for Shift.
-
-
-
Key codes
-
- A key {{KeyboardEvent/code}} is an attribute of a keyboard event that can be
- used to identify the physical key associated with the keyboard event. It is
- similar to USB Usage IDs in that it provides a low-level value (similar to a
- scancode) that is vendor-neutral.
-
- The primary purpose of the {{KeyboardEvent/code}} attribute is to provide a
- consistent and coherent way to identify keys based on their physical
- location. In addition, it also provides a stable name (unaffected by the
- current keyboard state) that uniquely identifies each key on the keyboard.
-
- The list of valid {{KeyboardEvent/code}} values is defined in the
- [[!UIEvents-Code]].
-
-
Motivation for the {{KeyboardEvent/code}} Attribute
-
- The standard PC keyboard has a set of keys (which we refer to as
- writing system keys) that generate different
- {{KeyboardEvent/key}} values based on the current keyboard layout
- selected by the user. This situation makes it difficult to write code
- that detects keys based on their physical location since the code would
- need to know which layout is in effect in order to know which
- {{KeyboardEvent/key}} values to check for. A real-world example of this
- is a game that wants to use the "W", "A", "S" and
- "D" keys to control player movement. The {{KeyboardEvent/code}}
- attribute solves this problem by providing a stable value to check that
- is not affected by the current keyboard layout.
-
- In addition, the values in the {{KeyboardEvent/key}} attribute depend as
- well on the current keyboard state. Because of this, the order in which
- keys are pressed and released in relation to modifier keys can affect
- the values stored in the {{KeyboardEvent/key}} attribute. The
- {{KeyboardEvent/code}} attribute solves this problem by providing a
- stable value that is not affected by the current keyboard state.
-
-
The Relationship Between {{KeyboardEvent/key}} and {{KeyboardEvent/code}}
-
-
-
{{KeyboardEvent/key}}
-
The {{KeyboardEvent/key}} attribute is intended for users who
- are interested in the meaning of the key being pressed, taking
- into account the current keyboard layout (and IME;
- dead keys are given a unique
- {{KeyboardEvent/key}} value). Example use case: Detecting
- modified keys or bare modifier keys (e.g., to perform an action
- in response to a keyboard shortcut).
-
-
-
{{KeyboardEvent/code}}
-
The {{KeyboardEvent/code}} attribute is intended for users who
- are interested in the key that was pressed by the user, without
- any layout modifications applied. Example use case: Detecting
- WASD keys (e.g., for movement controls in a game) or trapping
- all keys (e.g., in a remote desktop client to send all keys to
- the remote host).
-
-
- In this example, checking the {{KeyboardEvent/key}} attribute permits
- matching Alt without worrying about which Alt key (left or
- right) was pressed. Checking the {{KeyboardEvent/code}} attribute
- permits matching the right Alt key ("AltRight") without worrying
- about which layout is currently in effect.
-
- Note that, in the French example, the Alt and AltGraph keys
- retain their left and right location, even though there is only one of
- each key.
-
-
- This example shows how dead key values are encoded in the
- attributes. The {{KeyboardEvent/key}} values vary based on the
- current locale, whereas the {{KeyboardEvent/code}} attribute returns
- a consistent value.
-
-
-
- Handling the "2" Key (with and without Shift pressed) on
- various keyboard layouts.
-
-
-
- Regardless of the current locale or the modifier key state, pressing
- the key labelled "2" on a US keyboard always results in
- "Digit2" in the {{KeyboardEvent/code}} attribute.
-
-
-
-
- Sequence of Keyboard Events : Shift and 2
-
-
- Compare the attribute values in the following two key event
- sequences. They both produce the "@" character on a US
- keyboard, but differ in the order in which the keys are released. In
- the first sequence, the order is: Shift (down), 2
- (down), 2 (up), Shift (up).
-
-
-
- In the second sequence, the Shift is released before the 2,
- resulting in the following event order: Shift (down),
- 2 (down), Shift (up), 2 (up).
-
-
-
- Note that the values contained in the {{KeyboardEvent/key}}
- attribute does not match between the keydown and keyup events for
- the "2" key. The {{KeyboardEvent/code}} attribute provides a
- consistent value that is not affected by the current modifier state.
-
-
-
-
{{KeyboardEvent/code}} and Virtual Keyboards
-
- The usefulness of the {{KeyboardEvent/code}} attribute is less obvious
- for virtual keyboards (and also for remote controls and chording
- keyboards). In general, if a virtual (or remote control) keyboard is
- mimicking the layout and functionality of a standard keyboard, then it
- MUST also set the {{KeyboardEvent/code}} attribute as appropriate. For
- keyboards which are not mimicking the layout of a standard keyboard,
- then the {{KeyboardEvent/code}} attribute MAY be set to the closest
- match on a standard keyboard or it MAY be left undefined.
-
- For virtual keyboards with keys that produce different values based on
- some modifier state, the {{KeyboardEvent/code}} value should be the
- {{KeyboardEvent/key}} value generated when the button is pressed while
- the device is in its factory-reset state.
-
-
Keyboard Event key Values
-
- A key value is a DOMString that can be used to indicate any
- given key on a keyboard, regardless of position or state, by the value it
- produces. These key values MAY be used as return values for keyboard events
- generated by the implementation, or as input values by the content author to
- specify desired input (such as for keyboard shortcuts).
-
- The list of valid key values is defined in [[!UIEvents-Key]].
-
- Key values can be used to detect the value of a key which has been pressed,
- using the {{KeyboardEvent/key}} attribute. Content authors can retrieve the
- character value of upper- or lower-case letters, number, symbols, or
- other character-producing keys, and also the key value of control
- keys, modifier keys, function keys, or other keys that do not generate
- characters. These values can be used for monitoring particular input
- strings, for detecting and acting on modifier key input in combination with
- other inputs (such as a mouse), for creating virtual keyboards, or for any
- number of other purposes.
-
- Key values can also be used by content authors in string comparisons, as
- values for markup attributes (such as the HTML accesskey) in
- conforming host languages, or for other related purposes. A
- conforming host language SHOULD allow content authors to use either
- of the two equivalent string values for a key value: the character
- value, or the key value.
-
-
- While implementations will use the most relevant value for a key
- independently of the platform or keyboard layout mappings, content authors
- can not make assumptions on the ability of keyboard devices to generate
- them. When using keyboard events and key values for shortcut-key
- combinations, content authors can consider using numbers and function
- keys (F4, F5, and so on) instead of letters ([[DWW95]])
- given that most keyboard layouts will provide keys for those.
-
-
- A key value does not indicate a specific key on the physical keyboard, nor
- does it reflect the character printed on the key. A key value indicates the
- current value of the event with consideration to the current state of all
- active keys and key input modes (including shift modes), as reflected in the
- operating-system mapping of the keyboard and reported to the implementation.
- In other words, the key value for the key labeled O on a
- QWERTY keyboard has the key value "o" in an unshifted state and
- "O" in a shifted state. Because a user can map their keyboard to an
- arbitrary custom configuration, the content author is encouraged not to
- assume that a relationship exists between the shifted and unshifted states
- of a key and the majuscule form (uppercase or capital letters) and minuscule
- form (lowercase or small letters) of a character representation, but is
- encouraged instead to use the value of the {{KeyboardEvent/key}} attribute.
- For example, the Standard "102" Keyboard layout depicted in [[UIEvents-Code]]
- illustrates one possible set of key mappings on one possible keyboard
- layout. Many others exist, both standard and idiosyncratic.
-
-
- To simplify dead key support, when the operating-system mapping of
- the keyboard is handling a dead key state, the current state of the
- dead key sequence is not reported via the {{KeyboardEvent/key}} attribute.
- Rather, a key value of "Dead" is reported. Instead, implementations
- generate composition events which
- contain the intermediate state of the dead key sequence reported via the
- {{CompositionEvent/data}} attribute. As in the previous example, the key
- value for the key marked O on a QWERTY keyboard has a
- {{CompositionEvent/data}} value of "ö" in an
- unshifted state during a dead-key operation to add an umlaut diacritic, and
- "Ö" in a shifted state during a dead-key
- operation to add an umlaut diacritic.
-
-
- It is also important to note that there is not a one-to-one relationship
- between key event states and key values. A particular key value might be
- associated with multiple keys. For example, many standard keyboards contain
- more than one key with the Shift key value (normally distinguished
- by the {{KeyboardEvent/location}} values
- {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} and
- {{KeyboardEvent/DOM_KEY_LOCATION_RIGHT}}) or 8 key value (normally
- distinguished by the {{KeyboardEvent/location}} values
- {{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}} and
- {{KeyboardEvent/DOM_KEY_LOCATION_NUMPAD}}), and user-configured custom
- keyboard layouts MAY duplicate any key value in multiple key-state scenarios
- (note that {{KeyboardEvent/location}} is intended for standard keyboard
- layouts, and cannot always indicate a meaningful distinction).
-
- Finally, the meaning of any given character representation is
- context-dependent and complex. For example, in some contexts, the asterisk
- (star) glyph ("*") represents a footnote or
- emphasis (when bracketing a passage of text). However, in some documents or
- executable programs it is equivalent to the mathematical multiplication
- operation, while in other documents or executable programs, that function is
- reserved for the multiplication symbol ("×", Unicode value
- U+00D7) or the Latin small letter "x"
- (due to the lack of a multiplication key on many keyboards and the
- superficial resemblance of the glyphs "×" and "x"). Thus,
- the semantic meaning or function of character representations is outside the
- scope of this specification.
-
-
Modifier keys
-
- Keyboard input uses modifier keys to change the normal behavior of a
- key. Like other keys, modifier keys generate keydown and
- keyup events, as shown in the example below. Some modifiers are
- activated while the key is being pressed down or maintained pressed such
- as Alt, Control, Shift, AltGraph, or
- Meta. Other modifiers are activated depending on their state
- such as CapsLock, NumLock, or ScrollLock. Change
- in the state happens when the modifier key is being pressed down. The
- {{KeyboardEvent}} interface provides convenient attributes for some
- common modifiers keys: {{KeyboardEvent/ctrlKey}},
- {{KeyboardEvent/shiftKey}}, {{KeyboardEvent/altKey}},
- {{KeyboardEvent/metaKey}}. Some operating systems simulate the
- AltGraph modifier key with the combination of the Alt
- and Control modifier keys. Implementations are encouraged to use
- the AltGraph modifier key.
-
-
- This example describes a possible sequence of events
- associated with the generation of the Unicode character Q (Latin
- Capital Letter Q, Unicode code point U+0051) on a US
- keyboard using a US mapping:
-
-
- Th example describes an alternate sequence of keys to the
- example above, where the Shift key is released before the
- Q key. The key value for the Q key will revert to its
- unshifted value for the keyup event:
-
-
- The following example describes a possible sequence of keys that
- does not generate a Unicode character (using the same configuration
- as the previous example):
-
-
- For non-US keyboard layouts, the sequence of events is the same, but
- the value of the key is based on the current keyboard layout. This
- example shows a sequence of events when an Arabic keyboard layout is
- used:
-
-
- The value in the keydown and keyup events varies based on
- the current keyboard layout in effect when the key is pressed. This
- means that the v key on a US layout and the ر key on an
- Arabic layout will generate different events even though they are the
- same physical key. To identify these events as coming from the same
- physical key, you will need to make use of the {{KeyboardEvent/code}}
- attribute.
-
-
- In some cases, modifier keys change the {{KeyboardEvent/key}}
- value for a key event. For example, on some MacOS keyboards, the key
- labeled "delete" functions the same as the Backspace key on the
- Windows OS when unmodified, but when modified by the Fn key,
- acts as the Delete key, and the value of {{KeyboardEvent/key}}
- will match the most appropriate function of the key in its current
- modified state.
-
-
Dead keys
-
- Some keyboard input uses dead keys for the input of composed
- character sequences. Unlike the handwriting sequence, in which users
- enter the base character first, keyboard input requires to enter a
- special state when a dead key is pressed and emit the
- character(s) only when one of a limited number of legal base
- character is entered.
-
-
- The MacOS and Linux operating systems use input methods to process
- dead keys.
-
-
- The dead keys (across all keyboard layouts and mappings) are
- represented by the key value Dead. In response to any dead key
- press, composition events must
- be dispatched by the user agent and the compositionupdate event's
- {{CompositionEvent/data}} value must be the character value of the
- current state of the dead key combining sequence.
-
- While Unicode combining characters always follow the handwriting
- sequence, with the combining character trailing the corresponding
- letter, typical dead key input MAY reverse the sequence, with the
- combining character before the corresponding letter. For example, the
- word naïve, using the combining diacritic ¨, would be
- represented sequentially in Unicode as nai¨ve, but MAY be typed
- na¨ive. The sequence of keystrokes U+0302 (Combining
- Circumflex Accent key) and U+0065 (key marked with the Latin Small
- Letter E) will likely produce (on a French keyboard using a french
- mapping and without any modifier activated) the Unicode character
- "ê" (Latin Small Letter E With Circumflex), as preferred by
- the Unicode Normalization Form NFC.
-
-
- In the second keydown event (step 5), the key value (assuming the
- event is not suppressed) will not be "e" (Latin Small
- Letter E key) under normal circumstances because the value delivered to
- the user agent will already be modified by the dead key operation.
-
-
- This process might be aborted when a user types an unsupported base
- character (that is, a base character for which the active
- diacritical mark is not available) after pressing a dead key:
-
-
-
- This specification includes a model for input method editors
- (IMEs), through the {{CompositionEvent}} interface and events.
- However, Composition Events and Keyboard Events do not necessarily map
- as a one-to-one relationship. As an example, receiving a keydown
- for the Accept key value does not necessarily imply that the
- text currently selected in the IME is being accepted, but
- indicates only that a keystroke happened, disconnected from the
- IME Accept functionality (which would normally result in a
- compositionend event in most IME systems). Keyboard
- events cannot be used to determine the current state of the input method
- editor, which can be obtained through the {{CompositionEvent/data}}
- attribute of the {{CompositionEvent}} interface. Additionally,
- IME systems and devices vary in their functionality, and in which
- keys are used for activating that functionality, such that the
- Convert and Accept keys MAY be represented by other
- available keys. Keyboard events correspond to the events generated by
- the input device after the keyboard layout mapping.
-
-
- In some implementations or system configurations, some key events, or
- their values, might be suppressed by the IME in use.
-
-
- The following example describes a possible sequence of keys to generate
- the Unicode character "市" (Kanji character, part of CJK
- Unified Ideographs) using Japanese input methods. This example assumes
- that the input method editor is activated and in the Japanese-Romaji
- input mode. The keys Convert and Accept MAY be replaced
- by others depending on the input device in use and the configuration of
- the IME, e.g., it can be respectively U+0020 (Space key) and
- Enter.
-
-
- "詩" (poem) and "市" (city) are
- homophones, both pronounced し (shi/si), so the user
- needs to use the Convert key to select the proper option.
-
-
- IME composition can also be canceled as in the following example, with
- conditions identical to the previous example. The key Cancel
- might also be replaced by others depending on the input device in use
- and the configuration of the IME, e.g., it could be U+001B (Escape
- key).
-
-
- Some input method editors (such as on the MacOS operating system)
- might set an empty string to the composition data attribute
- before canceling a composition.
-
-
-
Input Method Editor mode keys
-
- Some keys on certain devices are intended to activate input
- method editor functionality, or to change the mode of an active
- input method editor. Custom keys for this purpose can be
- defined for different devices or language modes. The keys defined in
- this specification for this purpose are: "Alphanumeric",
- "CodeInput", "FinalMode", "HangulMode", "HanjaMode",
- "Hiragana", "JunjaMode", "KanaMode", "KanjiMode",
- "Katakana", and "Romaji". When one of these keys is
- pressed, and no IME is currently active, the appropriate
- IME is expected to be activated in the mode indicated by the
- key (if available). If an IME is already active when the key
- is pressed, the active IME might change to the indicated
- mode, or a different IME might be launched, or the might MAY
- be ignored, on a device- and application-specific basis.
-
- This specification also defines other keys which are intended for
- operation specifically with input method editors:
- "Accept", "AllCandidates", "Cancel", "Convert",
- "Compose", "Zenkaku" (FullWidth), "Hankaku" (HalfWidth), "NextCandidate",
- "NonConvert", and "PreviousCandidate". The functions of these
- keys are not defined in this specification — refer to other
- resources for details on input method editor functionality.
-
-
- Keys with input method editor functions are not restricted to
- that purpose, and can have other device- or implementation-specific
- purposes.
-
-
-
Default actions and cancelable keyboard events
-
- Canceling the default action of a keydown event MUST NOT
- affect its respective keyup event, but it MUST prevent the
- respective beforeinput and input (and keypress if
- supported) events from being generated. The following example describes
- a possible sequence of keys to generate the Unicode character Q (Latin
- Capital Letter Q) on a US keyboard using a US mapping:
-
-
-
- If the key is a modifier key, the keystroke MUST still be taken into
- account for the modifiers states. The following example describes a
- possible sequence of keys to generate the Unicode character Q (Latin
- Capital Letter Q) on a US keyboard using a US mapping:
-
-
-
- If the key is part of a sequence of several keystrokes, whether it is a
- dead key or it is contributing to an Input Method Editor
- sequence, the keystroke MUST be ignored (not taken into account) only if
- the default action is canceled on the keydown event.
- Canceling a dead key on a keyup event has no effect on
- beforeinput or input events. The following example uses
- the dead key "Dead" (U+0302 Combining Circumflex Accent key) and
- "e" (U+0065, Latin Small Letter E key) on a French
- keyboard using a French mapping and without any modifier activated:
-
-
-
- Generally, when a constructor of an {{Event}} interface, or of an interface
- inherited from the {{Event}} interface, is invoked, the steps described in
- [[!DOM]] should be followed. However the {{KeyboardEvent}} and
- {{MouseEvent}} interfaces provide additional dictionary members for
- initializing the internal state of the {{Event}} object's key modifiers:
- specifically, the internal state queried for using the
- {{KeyboardEvent/getModifierState()}} and {{MouseEvent/getModifierState()}}
- methods. This section supplements the DOM4 steps for intializing a new
- {{Event}} object with these optional modifier states.
-
- For the purposes of constructing a {{KeyboardEvent}}, {{MouseEvent}}, or
- object derived from these objects using the algorithm below, all
- {{KeyboardEvent}}, {{MouseEvent}}, and derived objects have
- internal key modifier state which can be set and
- retrieved using the key modifier names
- described in the
- Modifier Keys table
- in [[UIEvents-Key]].
-
- The following steps supplement the algorithm defined for constructing
- events in DOM4:
-
- * If the {{Event}} being constructed is a {{KeyboardEvent}} or
- {{MouseEvent}} object or an object that derives from either of these,
- and a {{EventModifierInit}} argument was provided to the constructor,
- then run the following sub-steps:
-
- * For each {{EventModifierInit}} argument, if the dictionary member
- begins with the string "modifier", then let the
- key modifier name be the
- dictionary member's name excluding the prefix
- "modifier", and set the {{Event}} object's
- internal key modifier state
- that matches the key modifier name
- to the corresponding value.
-
-
Legacy {{KeyboardEvent}} events
-
- The keypress event is the traditional method for capturing key events
- and processing them before the DOM is updated with the effects of the key
- press. Code that makes use of the keypress event typically relies on
- the legacy {{KeyboardEvent/charCode}}, {{KeyboardEvent/keyCode}}, and
- {{UIEvent/which}} attributes.
-
- Note that the keypress event is specific to key events, and has been
- replaced by the more general event sequence of beforeinput and
- input events. These new input events are not specific to
- keyboard actions and can be used to capture user input regardless of the
- original source.
-
-
{{Event}}.{{Event/target}} :
- focused element processing the key event or if no element focused, then the
- body element if available, otherwise the
- root element
{{KeyboardEvent}}.{{KeyboardEvent/isComposing}} :
- true if the key event occurs as part of a composition session, otherwise false
-
-
-
-
-
- If supported by a user agent, this event MUST be dispatched
- when a key is pressed down, if and only if that key normally
- produces a character value. The keypress event type is
- device dependent and relies on the capabilities of the input devices
- and how they are mapped in the operating system.
-
- This event type MUST be generated after the key mapping. It
- MUST NOT be fired when using an input method editor.
-
- If this event is canceled, it should prevent the input event
- from firing, in addition to canceling the default action.
-
- Authors SHOULD use the beforeinput event instead of the
- keypress event.
-
-
- The keypress event is traditionally associated with detecting
- a character value rather than a physical key, and might not
- be available on all keys in some configurations.
-
-
-
- The keypress event type is defined in this specification for
- reference and completeness, but this specification deprecates
- the use of this event type. When in editing contexts, authors can
- subscribe to the beforeinput event instead.
-
-
- The keypress event type MUST be dispatched after the
- keydown event and before the keyup event associated with
- the same key.
-
- The keypress event type MUST be dispatched after the
- beforeinput event and before the input event associated
- with the same key.
-
- The sequence of key events for user-agents the support the
- keypress event is demonstrated in the following example:
-
-
-
- This section is normative.
-
- The following features are obsolete and should only be implemented by
- user agents that require compatibility with legacy software.
-
- Early versions of this specification included an initialization method on
- the interface (for example initMouseEvent) that required a long
- list of parameters that, in most cases, did not fully initialize all
- attributes of the event object. Because of this, event interfaces which were
- derived from the basic {{Event}} interface required that the initializer of
- each of the derived interfaces be called explicitly in order to
- fully initialize an event.
-
-
- Initializing all the attributes of a MutationEvent requires calls to two
- initializer methods: initEvent and
- initMutationEvent.
-
-
- Due in part to the length of time in the development of this standard, some
- implementations MAY have taken a dependency on these (now deprecated)
- initializer methods. For completeness, these legacy event initializers are
- described in this section.
-
-
Initializers for interface KeyboardEvent
-
- This section is informative
-
-
- The argument list to this legacy KeyboardEvent initializer does not
- include the detailArg (present in other initializers) and
- adds the locale argument (see [[#changes-drafts]]); it is
- necessary to preserve this inconsistency for compatibility with existing
- implementations.
-
- Initializes attributes of a {{KeyboardEvent}} object. This
- method has the same behavior as UIEvent.initUIEvent().
- The value of {{UIEvent/detail}} remains undefined.
-
-
- The initKeyboardEvent method is deprecated.
-
-
-
-
DOMString typeArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
boolean bubblesArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
boolean cancelableArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
Window? viewArg
-
- Specifies {{UIEvent/view}}. This value MAY be null.
-
-
-
DOMString keyArg
-
- Specifies {{KeyboardEvent/key}}.
-
-
-
unsigned long locationArg
-
- Specifies {{KeyboardEvent/location}}.
-
-
-
boolean ctrlKey
-
- Specifies whether the Control key modifier is active.
-
-
-
boolean altKey
-
- Specifies whether the Alt key modifier is active.
-
-
-
boolean shiftKey
-
- Specifies whether the Shift key modifier is active.
-
-
-
boolean metaKey
-
- Specifies whether the Meta key modifier is active.
-
-
-
-
-
-
Legacy Key & Mouse Event Attributes
-
- This section is non-normative. The following attributes are obsolete and should
- only be implemented by user agents that require compatibility with legacy
- software that requires these keyboard events.
-
- These features were never formally specified and the current browser
- implementations vary in significant ways.
-
-
Legacy {{KeyboardEvent}} supplemental interface
-
- This section is non-normative
-
- Browser support for keyboards has traditionally relied on three ad-hoc
- attributes, {{KeyboardEvent/keyCode}}, {{KeyboardEvent/charCode}}, and
- {{UIEvent}}'s {{UIEvent/which}}.
-
- All three of these attributes return a numerical code that represents some
- aspect of the key pressed: {{KeyboardEvent/keyCode}} is an index of the key
- itself. {{KeyboardEvent/charCode}} is the ASCII value of the character keys.
- {{UIEvent/which}} is the character value where available and otherwise
- the key index. The values for these attributes, and the availability of the
- attribute, is inconsistent across platforms, keyboard languages and layouts,
- user agents, versions, and even event types.
-
-
Interface KeyboardEvent (supplemental)
-
- The partial {{KeyboardEvent}} interface is an informative extension of
- the {{KeyboardEvent}} interface, which adds the
- {{KeyboardEvent/charCode}} and {{KeyboardEvent/keyCode}} attributes.
-
- The partial {{KeyboardEvent}} interface can be obtained by using the
- {{Document/createEvent()}} method call in
- implementations that support this extension.
-
-
- partial interface KeyboardEvent {
- // The following support legacy user agents
- readonly attribute unsigned long charCode;
- readonly attribute unsigned long keyCode;
- };
-
-
-
-
charCode
-
- {{KeyboardEvent/charCode}} holds a character value, for
- keypress events which generate character input. The value
- is the Unicode reference number (code point) of that character
- (e.g. event.charCode = event.key.charCodeAt(0) for
- printable characters). For keydown or keyup
- events, the value of {{KeyboardEvent/charCode}} is
- 0.
-
-
-
keyCode
-
- {{KeyboardEvent/keyCode}} holds a system- and
- implementation-dependent numerical code signifying the
- unmodified identifier associated with the key pressed. Unlike
- the {{KeyboardEvent/key}} attribute, the set of possible values
- are not normatively defined in this specification. Typically,
- these value of the {{KeyboardEvent/keyCode}} SHOULD represent
- the decimal codepoint in ASCII [[RFC20]][[US-ASCII]] or Windows
- 1252 [[WIN1252]], but MAY be drawn from a different appropriate
- character set. Implementations that are unable to identify a key
- use the key value 0.
-
- See [[#legacy-key-models]] for more details on how to determine
- the values for {{KeyboardEvent/keyCode}}.
-
-
-
-
Interface KeyboardEventInit (supplemental)
-
- Browsers that include support for {{KeyboardEvent/keyCode}}
- and {{KeyboardEvent/charCode}} in
- {{KeyboardEvent}} should also add the following members to the
- {{KeyboardEventInit}} dictionary.
-
- The partial {{KeyboardEventInit}} dictionary is an informative extension
- of the {{KeyboardEventInit}} dictionary, which adds
- {{KeyboardEvent/charCode}} and {{KeyboardEvent/keyCode}}
- members to initialize the corresponding
- {{KeyboardEvent}} attributes.
-
-
- partial dictionary KeyboardEventInit {
- // The following support legacy user agents
- unsigned long charCode = 0;
- unsigned long keyCode = 0;
- };
-
-
-
-
charCode
-
- Initializes the {{KeyboardEvent/charCode}} attribute of the
- {{KeyboardEvent}} to the Unicode code point for the event's
- character.
-
-
-
keyCode
-
- Initializes the {{KeyboardEvent/keyCode}} attribute of the
- {{KeyboardEvent}} to the system- and implementation-dependent
- numerical code signifying the unmodified identifier associated
- with the key pressed.
-
-
-
-
Legacy key models
-
- This section is non-normative
-
- Implementations differ on which values are exposed on these attributes for
- different event types. An implementation MAY choose to expose both virtual
- key codes and character codes in the {{KeyboardEvent/keyCode}} property
- (conflated model), or report separate {{KeyboardEvent/keyCode}} and
- {{KeyboardEvent/charCode}} properties (split model).
-
-
How to determine {{KeyboardEvent/keyCode}} for keydown and keyup events
-
- The {{KeyboardEvent/keyCode}} for keydown or keyup events
- is calculated as follows:
-
- * Read the virtual key code from the operating system's event
- information, if such information is available.
-
- * If an Input Method Editor is processing key input and the event is
- keydown, return 229.
-
- * If input key when pressed without modifiers would insert a numerical
- character (0-9), return the ASCII code of that numerical character.
-
- * If input key when pressed without modifiers would insert a lower
- case character in the a-z alphabetical range, return the ASCII code
- of the upper case equivalent.
-
- * If the implementation supports a key code conversion table for the
- operating system and platform, look up the value. If the conversion
- table specifies an alternate virtual key value for the given input,
- return the specified value.
-
- * If the key's function, as determined in an implementation-specific
- way, corresponds to one of the keys in the
- [[#fixed-virtual-key-codes]] table, return the corresponding key
- code.
-
- * Return the virtual key code from the operating system.
-
- * If no key code was found, return 0.
-
-
How to determine {{KeyboardEvent/keyCode}} for keypress events
-
- The {{KeyboardEvent/keyCode}} for keypress events is calculated
- as follows:
-
- * If the implementation supports a conflated model, set
- {{KeyboardEvent/keyCode}} to the Unicode code point of the character
- being entered.
-
- * If the implementation supports a split model, set
- {{KeyboardEvent/keyCode}} to 0.
-
-
Fixed virtual key codes
-
- The virtual key codes for the following keys do not usually change with
- keyboard layouts on desktop systems:
-
-
-
Key
Virtual Key Code
Notes
-
Backspace
8
-
Tab
9
-
Enter
13
-
Shift
16
-
Control
17
-
Alt
18
-
CapsLock
20
-
Escape
27
Esc
-
Space
32
-
PageUp
33
-
PageDown
34
-
End
35
-
Home
36
-
ArrowLeft
37
-
ArrowUp
38
-
ArrowRight
39
-
ArrowDown
40
-
Delete
46
Del
-
-
-
Optionally fixed virtual key codes
-
- The following punctuation characters MAY change virtual codes between
- keyboard layouts, but reporting these values will likely be more
- compatible with legacy content expecting US-English keyboard layout:
-
-
-
Key
Character
Virtual Key Code
-
Semicolon
";"
186
-
Colon
":"
186
-
Equals sign
"="
187
-
Plus
"+"
187
-
Comma
","
188
-
Less than sign
"<"
188
-
Minus
"-"
189
-
Underscore
"_"
189
-
Period
"."
190
-
Greater than sign
">"
190
-
Forward slash
"/"
191
-
Question mark
"?"
191
-
Backtick
"`"
192
-
Tilde
"~"
192
-
Opening squace bracket
"["
219
-
Opening curly brace
"{"
219
-
Backslash
"\"
220
-
Pipe
"|"
220
-
Closing square bracket
"]"
221
-
Closing curly brace
"}"
221
-
Single quote
"'"
222
-
Double quote
"""
222
-
-
-
Legacy Event Types
-
- This section is normative. The following event types are obsolete and should
- only be implemented by user agents that require compatibility with legacy
- software.
-
-
Legacy {{KeyboardEvent}} events
-
- The keypress event is the traditional method for capturing key events
- and processing them before the DOM is updated with the effects of the key
- press. Code that makes use of the keypress event typically relies on
- the legacy {{KeyboardEvent/charCode}}, {{KeyboardEvent/keyCode}}, and
- {{UIEvent/which}} attributes.
-
- Note that the keypress event is specific to key events, and has been
- replaced by the more general event sequence of beforeinput and
- input events. These new input events are not specific to
- keyboard actions and can be used to capture user input regardless of the
- original source.
-
-
{{Event}}.{{Event/target}} :
- focused element processing the key event or if no element focused, then the
- body element if available, otherwise the
- root element
{{KeyboardEvent}}.{{KeyboardEvent/isComposing}} :
- true if the key event occurs as part of a composition session, otherwise false
-
-
-
-
-
- If supported by a user agent, this event MUST be dispatched
- when a key is pressed down, if and only if that key normally
- produces a character value. The keypress event type is
- device dependent and relies on the capabilities of the input devices
- and how they are mapped in the operating system.
-
- This event type MUST be generated after the key mapping. It
- MUST NOT be fired when using an input method editor.
-
- If this event is canceled, it should prevent the input event
- from firing, in addition to canceling the default action.
-
- Authors SHOULD use the beforeinput event instead of the
- keypress event.
-
-
- The keypress event is traditionally associated with detecting
- a character value rather than a physical key, and might not
- be available on all keys in some configurations.
-
-
-
- The keypress event type is defined in this specification for
- reference and completeness, but this specification deprecates
- the use of this event type. When in editing contexts, authors can
- subscribe to the beforeinput event instead.
-
-
- The keypress event type MUST be dispatched after the
- keydown event and before the keyup event associated with
- the same key.
-
- The keypress event type MUST be dispatched after the
- beforeinput event and before the input event associated
- with the same key.
-
- The sequence of key events for user-agents the support the
- keypress event is demonstrated in the following example:
-
-
-
- TODO - Add specific concerns for this spec
-
-
Acknowledgements
-
- TODO
-
-
Refs to other UIEvent specs \[DELETE]
-
- This section will be deleted.
-
- Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
- beforeinput
- blur
- click
- compositionend
- compositionstart
- compositionupdate
- DOMActivate
- input
-
-
Things defined in other sections
-
-
Activation triggers and behavior
-
Default actions and cancelable events
-
Event dispatch and DOM event flow
-
Focus Events
-
Web browsers and other dynamic or interactive user agents
-
Authoring tools
-
-
Things defined in CompositionEvents
-
Composition Events
-
-
Things defined in Changes
-
Changes between different drafts of UI Events
-
-
Glossary \[DELETE]
-
-This section will be deleted.
-
-Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-: activation behavior
-:: The action taken when an event, typically initiated by users through
- an input device, causes an element to fulfill a defined task. The task MAY
- be defined for that element by the host language, or by
- author-defined variables, or both. The default task for any given element
- MAY be a generic action, or MAY be unique to that element. For example, the
- activation behavior of an HTML or SVG <a> element is to
- cause the user agent to traverse the link specified in the
- href attribute, with the further optional parameter of
- specifying the browsing context for the traversal (such as the current
- window or tab, a named window, or a new window). The activation behavior of
- an HTML <input> element with the type
- attribute value submit is be to send the values of the form
- elements to an author-defined IRI by the author-defined HTTP method. See
- [[#event-flow-activation]] for more details.
-
-: activation trigger
-:: An event which is defined to initiate an activation behavior. Refer
- to [[#event-flow-activation]] for more details.
-
-: body element
-:: In HTML or XHTML documents, the body element represents the contents of the
- document. In a well-formed HTML document, the body element is a first
- descendant of the root element.
-
-: character value
-:: In the context of key values, a character value is a string representing one
- or more Unicode characters, such as a letter or symbol, or a set of letters, each
- belonging to the set of valid Unicode character categories.
- In this specification, character values are denoted as a unicode string
- (e.g., U+0020) or a glyph representation of the same code point (e.g.,
- " "), and are color coded to help distinguish these two representations.
-
-
- In source code, some key values, such as non-graphic characters, can be
- represented using the character escape syntax of the programming language in
- use.
-
-
-: dead key
-:: A dead key is a key or combination of keys which produces no character by
- itself, but which in combination or sequence with another key produces a
- modified character, such as a character with diacritical marks (e.g.,
- "ö", "é", "â").
-
-: default action
-:: A default action is an OPTIONAL supplementary behavior that an
- implementation MUST perform in combination with the dispatch of the event
- object. Each event type definition, and each specification, defines the
- default action for that event type, if it has one. An instance of an
- event MAY have more than one default action under some circumstances,
- such as when associated with an activation trigger. A default
- action MAY be cancelled through the invocation of the
- {{Event/preventDefault()}} method. For more details, see
- [[#event-flow-default-cancel]].
-
-: deprecated
-:: Features marked as deprecated are included in the specification as reference
- to older implementations or specifications, but are OPTIONAL and
- discouraged. Only features which have existing or in-progress replacements
- MUST be deprecated in this specification. Implementations which do not
- already include support for the feature MAY implement deprecated features
- for reasons of backwards compatibility with existing content, but content
- authors creating content SHOULD NOT use deprecated features, unless there is
- no other way to solve a use case. Other specifications which reference this
- specification SHOULD NOT use deprecated features, but SHOULD point instead
- to the replacements of which the feature is deprecated in favor. Features
- marked as deprecated in this specification are expected to be dropped from
- future specifications.
-
-: empty string
-:: The empty string is a value of type DOMString of length
- 0, i.e., a string which contains no characters (neither
- printing nor control characters).
-
-: event
-:: An event is the representation of some occurrence (such as a mouse click on
- the presentation of an element, the removal of child node from an element,
- or any number of other possibilities) which is associated with its event
- target. Each event is an instantiation of one specific event
- type.
-
-: event target
-:: The object to which an event is targeted using the [[#event-flow]].
- The event target is the value of the {{Event/target}} attribute.
-
-: host language
-:: Any language which integrates the features of another language or API
- specification, while normatively referencing the origin specification rather
- than redefining those features, and extending those features only in ways
- defined by the origin specification. An origin specification typically is
- only intended to be implemented in the context of one or more host
- languages, not as a standalone language. For example, XHTML, HTML, and SVG
- are host languages for UI Events, and they integrate and extend the objects
- and models defined in this specification.
-
-: IME
-: input method editor
-:: An input method editor (IME), also known as a front end
- processor, is an application that performs the conversion between
- keystrokes and ideographs or other characters, usually by user-guided
- dictionary lookup, often used in East Asian languages (e.g., Chinese,
- Japanese, Korean). An IME MAY also be used for dictionary-based word
- completion, such as on mobile devices. See [[#keys-IME]] for treatment of
- IMEs in this specification. See also text composition system.
-
-: key mapping
-:: Key mapping is the process of assigning a key value to a particular key, and
- is the result of a combination of several factors, including the operating
- system and the keyboard layout (e.g., QWERTY, Dvorak, Spanish,
- InScript, Chinese, etc.), and after taking into account all modifier
- key (Shift, Alt, et al.) and dead key states.
-
-: key value
-:: A key value is a character value or multi-character string (such as
- "Enter", "Tab", or "MediaTrackNext") associated with a key in a
- particular state. Every key has a key value, whether or not it has a
- character value. This includes control keys, function keys,
- modifier keys, dead keys, and any other key. The key value of
- any given key at any given time depends upon the key mapping.
-
-: modifier key
-:: A modifier key changes the normal behavior of a key, such as to produce a
- character of a different case (as with the Shift key), or to alter
- what functionality the key triggers (as with the Fn or Alt
- keys). See [[#keys-modifiers]] for more information about modifier keys and
- refer to the [=Modifier Keys table=] in [[UIEvents-Key]] for a list
- of valid modifier keys.
-
-: QWERTY
-:: QWERTY (pronounced ˈkwɜrti) is a common keyboard layout,
- so named because the first five character keys on the top row of letter keys
- are Q, W, E, R, T, and Y. There are many other popular keyboard layouts
- (including the Dvorak and Colemak layouts), most designed for localization
- or ergonomics.
-
-: text composition system
-:: A software component that interprets some form of alternate input (such as a
- input method editor, a speech processor, or a handwriting recognition
- system) and converts it to text.
-
-: Unicode character categories
-:: A subset of the General Category values that are defined for each Unicode
- code point. This subset contains all the
- Letter (Ll,
- Lm,
- Lo,
- Lt,
- Lu),
- Number (Nd,
- Nl,
- No),
- Punctuation (Pc,
- Pd,
- Pe,
- Pf,
- Pi,
- Po,
- Ps)
- and Symbol (Sc,
- Sk,
- Sm,
- So)
- category values.
-
-: un-initialized value
-:: The value of any event attribute (such as {{Event/bubbles}} or
- {{Event/currentTarget}}) before the event has been initialized with
- {{Event/initEvent()}}. The un-initialized values of an event apply
- immediately after a new event has been created using the method
- {{Document/createEvent()}}.
-
-: user agent
-:: A program, such as a browser or content authoring tool, normally running on
- a client machine, which acts on a user's behalf in retrieving, interpreting,
- executing, presenting, or creating content. Users MAY act on the content
- using different user agents at different times, for different purposes. See
- the [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the
- requirements for a conforming user agent.
-
-: Window
-:: The Window is the object referred to by the current document's
- browsing context's Window Proxy object as defined in
- HTML5
- [[HTML5]].
-
diff --git a/split/keyboard-events.html b/split/keyboard-events.html
deleted file mode 100644
index b2e1e45..0000000
--- a/split/keyboard-events.html
+++ /dev/null
@@ -1,4109 +0,0 @@
-
-
-
-
- Keyboard Events
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Note: This is an experimental split of the UI Events spec into smaller, event-specific
-
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
-
Status of this document
-
-
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
-
This document was published by the Web Applications Working Group as an Editors Draft. This document is intended to become a W3C Recommendation.
Publication as an Editors Draft does not imply endorsement by W3C and its Members. This is a draft document and may
- be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite
- this document as other than work in progress.
-
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
The key cap printed on a key is shown as ↓, = or Q. This is used to refer to a
-key from the user’s perspective without regard for the key and code values in the
-generated KeyboardEvent.
-
-
Glyphs representing character are shown as: "𣧂".
-
-
Unicode character encodings are shown as: U+003d.
-
-
Names of key values generated by a key press (i.e., the value of KeyboardEvent.key) are shown as: "ArrowDown", "=", "q" or "Q".
In addition, certain terms are used in this specification with particular
-meanings. The term implementation applies to a browser, content
-authoring tool, or other user agent that implements this specification,
-while a content author is a person who writes script or code that takes
-advantage of the interfaces, methods, attributes, events, and other features
-described in this specification in order to make Web applications, and a user is
-the person who uses those Web applications in an implementation.
-
And finally:
-
This is a note.
-
This is an open issue.
-
This is a warning.
-
interface Example {
- // This is an IDL definition.
-};
-
-
3. Keyboard Events
-
Keyboard events are device dependent, i.e., they rely on the capabilities of
- the input devices and how they are mapped in the operating systems. Refer to Keyboard events and key values for more details,
- including examples on how Keyboard Events are used in combination with
- Composition Events. Depending on the character generation device, keyboard
- events might not be generated.
-
Keyboard events are only one modality of providing textual input. For
- editing scenarios, consider also using the InputEvent as an alternate to
- (or in addition to) keyboard events.
-
3.1. Interface KeyboardEvent
-
Introduced in this specification
-
The KeyboardEvent interface provides specific contextual information
- associated with keyboard devices. Each keyboard event references a key
- using a value. Keyboard events are commonly directed at the element that
- has the focus.
-
The KeyboardEvent interface provides convenient attributes for some
- common modifiers keys: ctrlKey, shiftKey, altKey, metaKey. These attributes are equivalent to using the
- method getModifierState() with Control, Shift, Alt, or Meta respectively.
- The key activation MUST NOT be distinguished as the left or
- right version of the key, and (other than the NumLock key) did not originate from the numeric keypad (or did not
- originate with a virtual key corresponding to the numeric
- keypad).
-
The Q key on a PC 101 Key US keyboard. The NumLock key on a PC 101 Key US keyboard. The 1 key on a PC 101 Key US keyboard located in the
- main section of the keyboard.
-
DOM_KEY_LOCATION_LEFT
-
- The key activated originated from the left key location (when
- there is more than one possible location for this key).
-
The left Control key on a PC 101 Key US keyboard.
-
DOM_KEY_LOCATION_RIGHT
-
- The key activation originated from the right key location (when
- there is more than one possible location for this key).
-
The right Shift key on a PC 101 Key US keyboard.
-
DOM_KEY_LOCATION_NUMPAD
-
- The key activation originated on the numeric keypad or with a
- virtual key corresponding to the numeric keypad (when there is
- more than one possible location for this key). Note that the NumLock key should always be encoded with a location of DOM_KEY_LOCATION_STANDARD.
-
The 1 key on a PC 101 Key US keyboard located on the
- numeric pad.
- 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.
-
- true if the key has been pressed in a sustained
- manner. Holding down a key MUST result in the repeating the
- events keydown, beforeinput, input in this
- order, at a rate determined by the system configuration. For
- mobile devices which have long-key-press behavior, the
- first key event with a repeat attribute value
- of true MUST serve as an indication of a long-key-press. The length of time that the key MUST be
- pressed in order to begin repeating is configuration-dependent.
-
- true if the key event occurs as part of a
- composition session, i.e., after a compositionstart event
- and before the corresponding compositionend event.
-
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].
-
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].
-
Initializes the repeat attribute of the
- KeyboardEvent object. This attribute should be set to true if the the current KeyboardEvent is considered
- part of a repeating sequence of similar events caused by the
- long depression of any single key, false otherwise.
-
isComposing, of type boolean, defaulting to false
-
Initializes the isComposing attribute of the
- KeyboardEvent object. This attribute should be set to true if the event being constructed occurs as part
- of a composition sequence, false otherwise.
-
-
- Legacy keyboard event implementations include three additional attributes, keyCode, charCode, and which. The keyCode attribute indicates a numeric value associated with a
- particular key on a computer keyboard, while the charCode attribute indicates the ASCII value of the character associated
- with that key (which might be the same as the keyCode value)
- and is applicable only to keys that produce a character value.
-
In practice, keyCode and charCode are inconsistent
- across platforms and even the same implementation on different operating
- systems or using different localizations. This specification does not define
- values for either keyCode or charCode, or behavior
- for charCode. In conforming UI Events implementations, content
- authors can instead use key and code.
For compatibility with existing content, virtual keyboards, such as software
- keyboards on screen-based input devices, are expected to produce the normal
- range of keyboard events, even though they do not possess physical keys.
-
In some implementations or system configurations, some key events, or their
- values, might be suppressed by the IME in use.
-
3.2. Keyboard Event Key Location
-
The location attribute can be used to disambiguate
- between key values that can be generated by different
- physical keys on the keyboard, for example, the left and right Shift key or the physical arrow keys vs. the numpad arrow keys
- (when NumLock is off).
-
The following table defines the valid location values
- for the special keys that have more than one location on the keyboard:
Typically, any default actions associated with any particular key
- are completed before the keyup event is dispatched. This might
- delay the keyup event slightly (though this is not likely to be a
- perceptible delay).
-
The event target of a key event is the currently focused element
- which is processing the keyboard activity. This is often an HTML input element or a textual element which is editable, but
- MAY be an element defined by the host language to accept keyboard
- input for non-text purposes, such as the activation of an accelerator
- key or trigger of some other behavior. If no suitable element is in
- focus, the event target will be the HTML body element if
- available, otherwise the root element.
-
The event target might change between different key events. For
- example, a keydown event for the Tab key will likely have
- a different event target than the keyup event on the same
- keystroke.
KeyboardEvent.repeat : true if a key has been depressed long enough to trigger key repetition, otherwise false
-
KeyboardEvent.isComposing : true if the key event occurs as part of a composition session, otherwise false
-
-
-
A user agent MUST dispatch this event when a key is pressed
- down. The keydown event type is device dependent and relies
- on the capabilities of the input devices and how they are mapped in
- the operating system. This event type MUST be generated after the key mapping. This event type MUST be dispatched before the beforeinput, input, and keyup events associated
- with the same key.
-
The default action of the keydown event depends upon the key:
-
-
-
If the key is associated with a character, the default action
-MUST be to dispatch a beforeinput event followed by an input event. In the case where the key which is
-associated with multiple characters (such as with a macro or
-certain sequences of dead keys), the default action MUST be to
-dispatch one set of beforeinput / input events for
-each character
-
-
If the key is associated with a text composition system,
-the default action MUST be to launch that system
-
-
If the key is the Tab key, the default action MUST be
-to shift the document focus from the currently focused element
-(if any) to the new focused element, as described in Focus Event Types
-
-
If the key is the Enter or (Space) key and the
-current focus is on a state-changing element, the default action
-MUST be to dispatch a click event, and a DOMActivate event if that event type is supported by the user agent (refer to § 9.1.1 Activation triggers and behavior for more
-details)
-
-
If this event is canceled, the associated event types MUST NOT be
- dispatched, and the associated actions MUST NOT be performed.
-
The keydown and keyup events are traditionally
- associated with detecting any key, not just those which produce a character value.
KeyboardEvent.repeat : true if a key has been depressed long enough to trigger key repetition, otherwise false
-
KeyboardEvent.isComposing : true if the key event occurs as part of a composition session, otherwise false
-
-
-
A user agent MUST dispatch this event when a key is released.
- The keyup event type is device dependent and relies on the
- capabilities of the input devices and how they are mapped in the
- operating system. This event type MUST be generated after the key
- mapping. This event type MUST be dispatched after the keydown, beforeinput, and input events
- associated with the same key.
-
The keydown and keyup events are traditionally
- associated with detecting any key, not just those which produce a character value.
-
4. Keyboard events and key values
-
This section contains necessary information regarding keyboard events:
-
-
-
Explanation of keyboard layout, mapping, and key values.
-
-
Relations between keys, such as dead keys or modifiers keys.
-
-
Relations between keyboard events and their default actions.
-
-
The set of key values, and guidelines on how to extend this set.
-
-
This section uses Serbian and Kanji characters which could be misrepresented or
- unavailable in the PDF version or printed version of this specification.
-
4.1. Keyboard Input
-
This section is non-normative
-
The relationship of each key to the complete keyboard has three separate
- aspects, each of which vary among different models and configurations of
- keyboards, particularly for locale-specific reasons:
-
-
-
Mechanical layout: the dimensions, size, and placement
-of the physical keys on the keyboard
-
-
Visual markings: the labels (or legends) that
-mark each key
-
-
Functional mapping: the abstract key-value association
-of each key.
-
-
This specification only defines the functional mapping, in terms of key values and code values,
- but briefly describes key legends for background.
-
4.1.1. Key Legends
-
This section is informative
-
The key legend is the visual marking that is printed or embossed on the key cap (the rectangular "cap" that covers the mechanical
- switch for the key). These markings normally consist of one or more
- characters that a keystroke on that key will produce (such as "G", "8", or "ш"), or names or symbols which indicate that key’s
- function (such as an upward-pointing arrow "⇧" indicating Shift, or the string "Enter"). Keys are often
- referred to by this marking (e.g., Press the "Shift" and "G" keys.). Note, however, that the visual appearance
- of the key has no bearing on its digital representation, and in many
- configurations may be completely inaccurate. Even the control and
- function keys, such as Enter, may be mapped to different
- functionality, or even mapped as character keys.
-
Many keyboards contain keys that do not normally produce any characters,
- even though the symbol might have a Unicode equivalent. For example, the Shift key might bear the symbol "⇧", which has the
- Unicode code point U+21E7, but
- pressing the Shift key will not produce this character value,
- and there is no Unicode code point for Shift.
-
4.2. Key codes
-
A key code is an attribute of a keyboard event that can be
- used to identify the physical key associated with the keyboard event. It is
- similar to USB Usage IDs in that it provides a low-level value (similar to a
- scancode) that is vendor-neutral.
-
The primary purpose of the code attribute is to provide a
- consistent and coherent way to identify keys based on their physical
- location. In addition, it also provides a stable name (unaffected by the
- current keyboard state) that uniquely identifies each key on the keyboard.
The standard PC keyboard has a set of keys (which we refer to as writing system keys) that generate different key values based on the current keyboard layout
- selected by the user. This situation makes it difficult to write code
- that detects keys based on their physical location since the code would
- need to know which layout is in effect in order to know which key values to check for. A real-world example of this
- is a game that wants to use the "W", "A", "S" and "D" keys to control player movement. The code attribute solves this problem by providing a stable value to check that
- is not affected by the current keyboard layout.
-
In addition, the values in the key attribute depend as
- well on the current keyboard state. Because of this, the order in which
- keys are pressed and released in relation to modifier keys can affect
- the values stored in the key attribute. The code attribute solves this problem by providing a
- stable value that is not affected by the current keyboard state.
The key attribute is intended for users who
- are interested in the meaning of the key being pressed, taking
- into account the current keyboard layout (and IME; dead keys are given a unique key value). Example use case: Detecting
- modified keys or bare modifier keys (e.g., to perform an action
- in response to a keyboard shortcut).
-
The code attribute is intended for users who
- are interested in the key that was pressed by the user, without
- any layout modifications applied. Example use case: Detecting
- WASD keys (e.g., for movement controls in a game) or trapping
- all keys (e.g., in a remote desktop client to send all keys to
- the remote host).
-
In this example, checking the key attribute permits
- matching Alt without worrying about which Alt key (left or
- right) was pressed. Checking the code attribute
- permits matching the right Alt key ("AltRight") without worrying
- about which layout is currently in effect.
-
Note that, in the French example, the Alt and AltGraph keys
- retain their left and right location, even though there is only one of
- each key.
This example shows how dead key values are encoded in the
- attributes. The key values vary based on the
- current locale, whereas the code attribute returns
- a consistent value.
-
-
- Handling the "2" Key (with and without Shift pressed) on
- various keyboard layouts.
-
Regardless of the current locale or the modifier key state, pressing
- the key labelled "2" on a US keyboard always results in "Digit2" in the code attribute.
-
-
- Sequence of Keyboard Events : Shift and 2
-
Compare the attribute values in the following two key event
- sequences. They both produce the "@" character on a US
- keyboard, but differ in the order in which the keys are released. In
- the first sequence, the order is: Shift (down), 2 (down), 2 (up), Shift (up).
Note that the values contained in the key attribute does not match between the keydown and keyup events for
- the "2" key. The code attribute provides a
- consistent value that is not affected by the current modifier state.
The usefulness of the code attribute is less obvious
- for virtual keyboards (and also for remote controls and chording
- keyboards). In general, if a virtual (or remote control) keyboard is
- mimicking the layout and functionality of a standard keyboard, then it
- MUST also set the code attribute as appropriate. For
- keyboards which are not mimicking the layout of a standard keyboard,
- then the code attribute MAY be set to the closest
- match on a standard keyboard or it MAY be left undefined.
-
For virtual keyboards with keys that produce different values based on
- some modifier state, the code value should be the key value generated when the button is pressed while
- the device is in its factory-reset state.
-
4.3. Keyboard Event key Values
-
A key value is a DOMString that can be used to indicate any
- given key on a keyboard, regardless of position or state, by the value it
- produces. These key values MAY be used as return values for keyboard events
- generated by the implementation, or as input values by the content author to
- specify desired input (such as for keyboard shortcuts).
-
The list of valid key values is defined in [UIEvents-Key].
-
Key values can be used to detect the value of a key which has been pressed,
- using the key attribute. Content authors can retrieve the character value of upper- or lower-case letters, number, symbols, or
- other character-producing keys, and also the key value of control
- keys, modifier keys, function keys, or other keys that do not generate
- characters. These values can be used for monitoring particular input
- strings, for detecting and acting on modifier key input in combination with
- other inputs (such as a mouse), for creating virtual keyboards, or for any
- number of other purposes.
-
Key values can also be used by content authors in string comparisons, as
- values for markup attributes (such as the HTML accesskey) in
- conforming host languages, or for other related purposes. A
- conforming host language SHOULD allow content authors to use either
- of the two equivalent string values for a key value: the character
- value, or the key value.
-
While implementations will use the most relevant value for a key
- independently of the platform or keyboard layout mappings, content authors
- can not make assumptions on the ability of keyboard devices to generate
- them. When using keyboard events and key values for shortcut-key
- combinations, content authors can consider using numbers and function
- keys (F4, F5, and so on) instead of letters ([DWW95])
- given that most keyboard layouts will provide keys for those.
-
A key value does not indicate a specific key on the physical keyboard, nor
- does it reflect the character printed on the key. A key value indicates the
- current value of the event with consideration to the current state of all
- active keys and key input modes (including shift modes), as reflected in the
- operating-system mapping of the keyboard and reported to the implementation.
- In other words, the key value for the key labeled O on a QWERTY keyboard has the key value "o" in an unshifted state and "O" in a shifted state. Because a user can map their keyboard to an
- arbitrary custom configuration, the content author is encouraged not to
- assume that a relationship exists between the shifted and unshifted states
- of a key and the majuscule form (uppercase or capital letters) and minuscule
- form (lowercase or small letters) of a character representation, but is
- encouraged instead to use the value of the key attribute.
- For example, the Standard "102" Keyboard layout depicted in [UIEvents-Code] illustrates one possible set of key mappings on one possible keyboard
- layout. Many others exist, both standard and idiosyncratic.
-
To simplify dead key support, when the operating-system mapping of
- the keyboard is handling a dead key state, the current state of the
- dead key sequence is not reported via the key attribute.
- Rather, a key value of "Dead" is reported. Instead, implementations
- generate composition events which
- contain the intermediate state of the dead key sequence reported via the data attribute. As in the previous example, the key
- value for the key marked O on a QWERTY keyboard has a data value of "ö" in an
- unshifted state during a dead-key operation to add an umlaut diacritic, and "Ö" in a shifted state during a dead-key
- operation to add an umlaut diacritic.
-
It is also important to note that there is not a one-to-one relationship
- between key event states and key values. A particular key value might be
- associated with multiple keys. For example, many standard keyboards contain
- more than one key with the Shift key value (normally distinguished
- by the location values DOM_KEY_LOCATION_LEFT and DOM_KEY_LOCATION_RIGHT) or 8 key value (normally
- distinguished by the location values DOM_KEY_LOCATION_STANDARD and DOM_KEY_LOCATION_NUMPAD), and user-configured custom
- keyboard layouts MAY duplicate any key value in multiple key-state scenarios
- (note that location is intended for standard keyboard
- layouts, and cannot always indicate a meaningful distinction).
-
Finally, the meaning of any given character representation is
- context-dependent and complex. For example, in some contexts, the asterisk
- (star) glyph ("*") represents a footnote or
- emphasis (when bracketing a passage of text). However, in some documents or
- executable programs it is equivalent to the mathematical multiplication
- operation, while in other documents or executable programs, that function is
- reserved for the multiplication symbol ("×", Unicode value U+00D7) or the Latin small letter "x" (due to the lack of a multiplication key on many keyboards and the
- superficial resemblance of the glyphs "×" and "x"). Thus,
- the semantic meaning or function of character representations is outside the
- scope of this specification.
-
4.3.1. Modifier keys
-
Keyboard input uses modifier keys to change the normal behavior of a
- key. Like other keys, modifier keys generate keydown and keyup events, as shown in the example below. Some modifiers are
- activated while the key is being pressed down or maintained pressed such
- as Alt, Control, Shift, AltGraph, or Meta. Other modifiers are activated depending on their state
- such as CapsLock, NumLock, or ScrollLock. Change
- in the state happens when the modifier key is being pressed down. The KeyboardEvent interface provides convenient attributes for some
- common modifiers keys: ctrlKey, shiftKey, altKey, metaKey. Some operating systems simulate the AltGraph modifier key with the combination of the Alt and Control modifier keys. Implementations are encouraged to use
- the AltGraph modifier key.
-
- This example describes a possible sequence of events
- associated with the generation of the Unicode character Q (Latin
- Capital Letter Q, Unicode code point U+0051) on a US
- keyboard using a US mapping:
-
- Th example describes an alternate sequence of keys to the
- example above, where the Shift key is released before the Q key. The key value for the Q key will revert to its
- unshifted value for the keyup event:
-
- The following example describes a possible sequence of keys that
- does not generate a Unicode character (using the same configuration
- as the previous example):
-
- For non-US keyboard layouts, the sequence of events is the same, but
- the value of the key is based on the current keyboard layout. This
- example shows a sequence of events when an Arabic keyboard layout is
- used:
-
The value in the keydown and keyup events varies based on
- the current keyboard layout in effect when the key is pressed. This
- means that the v key on a US layout and the ر key on an
- Arabic layout will generate different events even though they are the
- same physical key. To identify these events as coming from the same
- physical key, you will need to make use of the code attribute.
-
In some cases, modifier keys change the key value for a key event. For example, on some MacOS keyboards, the key
- labeled "delete" functions the same as the Backspace key on the
- Windows OS when unmodified, but when modified by the Fn key,
- acts as the Delete key, and the value of key will match the most appropriate function of the key in its current
- modified state.
-
4.3.2. Dead keys
-
Some keyboard input uses dead keys for the input of composed
- character sequences. Unlike the handwriting sequence, in which users
- enter the base character first, keyboard input requires to enter a
- special state when a dead key is pressed and emit the
- character(s) only when one of a limited number of legal base
- character is entered.
-
The MacOS and Linux operating systems use input methods to process dead keys.
-
The dead keys (across all keyboard layouts and mappings) are
- represented by the key value Dead. In response to any dead key
- press, composition events must
- be dispatched by the user agent and the compositionupdate event’s data value must be the character value of the
- current state of the dead key combining sequence.
-
While Unicode combining characters always follow the handwriting
- sequence, with the combining character trailing the corresponding
- letter, typical dead key input MAY reverse the sequence, with the
- combining character before the corresponding letter. For example, the
- word naïve, using the combining diacritic ¨, would be
- represented sequentially in Unicode as nai¨ve, but MAY be typed na¨ive. The sequence of keystrokes U+0302 (Combining
- Circumflex Accent key) and U+0065 (key marked with the Latin Small
- Letter E) will likely produce (on a French keyboard using a french
- mapping and without any modifier activated) the Unicode character "ê" (Latin Small Letter E With Circumflex), as preferred by
- the Unicode Normalization Form NFC.
In the second keydown event (step 5), the key value (assuming the
- event is not suppressed) will not be "e" (Latin Small
- Letter E key) under normal circumstances because the value delivered to
- the user agent will already be modified by the dead key operation.
-
This process might be aborted when a user types an unsupported base
- character (that is, a base character for which the active
- diacritical mark is not available) after pressing a dead key:
This specification includes a model for input method editors (IMEs), through the CompositionEvent interface and events.
- However, Composition Events and Keyboard Events do not necessarily map
- as a one-to-one relationship. As an example, receiving a keydown for the Accept key value does not necessarily imply that the
- text currently selected in the IME is being accepted, but
- indicates only that a keystroke happened, disconnected from the IME Accept functionality (which would normally result in a compositionend event in most IME systems). Keyboard
- events cannot be used to determine the current state of the input method
- editor, which can be obtained through the data attribute of the CompositionEvent interface. Additionally, IME systems and devices vary in their functionality, and in which
- keys are used for activating that functionality, such that the Convert and Accept keys MAY be represented by other
- available keys. Keyboard events correspond to the events generated by
- the input device after the keyboard layout mapping.
-
In some implementations or system configurations, some key events, or
- their values, might be suppressed by the IME in use.
-
The following example describes a possible sequence of keys to generate
- the Unicode character "市" (Kanji character, part of CJK
- Unified Ideographs) using Japanese input methods. This example assumes
- that the input method editor is activated and in the Japanese-Romaji
- input mode. The keys Convert and Accept MAY be replaced
- by others depending on the input device in use and the configuration of
- the IME, e.g., it can be respectively U+0020 (Space key) and Enter.
-
"詩" (poem) and "市" (city) are
- homophones, both pronounced し (shi/si), so the user
- needs to use the Convert key to select the proper option.
IME composition can also be canceled as in the following example, with
- conditions identical to the previous example. The key Cancel might also be replaced by others depending on the input device in use
- and the configuration of the IME, e.g., it could be U+001B (Escape
- key).
Some input method editors (such as on the MacOS operating system)
- might set an empty string to the composition data attribute
- before canceling a composition.
-
4.3.3.1. Input Method Editor mode keys
-
Some keys on certain devices are intended to activate input
- method editor functionality, or to change the mode of an active input method editor. Custom keys for this purpose can be
- defined for different devices or language modes. The keys defined in
- this specification for this purpose are: "Alphanumeric", "CodeInput", "FinalMode", "HangulMode", "HanjaMode", "Hiragana", "JunjaMode", "KanaMode", "KanjiMode", "Katakana", and "Romaji". When one of these keys is
- pressed, and no IME is currently active, the appropriate IME is expected to be activated in the mode indicated by the
- key (if available). If an IME is already active when the key
- is pressed, the active IME might change to the indicated
- mode, or a different IME might be launched, or the might MAY
- be ignored, on a device- and application-specific basis.
Keys with input method editor functions are not restricted to
- that purpose, and can have other device- or implementation-specific
- purposes.
-
4.3.4. Default actions and cancelable keyboard events
-
Canceling the default action of a keydown event MUST NOT
- affect its respective keyup event, but it MUST prevent the
- respective beforeinput and input (and keypress if
- supported) events from being generated. The following example describes
- a possible sequence of keys to generate the Unicode character Q (Latin
- Capital Letter Q) on a US keyboard using a US mapping:
If the key is a modifier key, the keystroke MUST still be taken into
- account for the modifiers states. The following example describes a
- possible sequence of keys to generate the Unicode character Q (Latin
- Capital Letter Q) on a US keyboard using a US mapping:
If the key is part of a sequence of several keystrokes, whether it is a dead key or it is contributing to an Input Method Editor
- sequence, the keystroke MUST be ignored (not taken into account) only if
- the default action is canceled on the keydown event.
- Canceling a dead key on a keyup event has no effect on beforeinput or input events. The following example uses
- the dead key "Dead" (U+0302 Combining Circumflex Accent key) and "e" (U+0065, Latin Small Letter E key) on a French
- keyboard using a French mapping and without any modifier activated:
Generally, when a constructor of an Event interface, or of an interface
- inherited from the Event interface, is invoked, the steps described in [DOM] should be followed. However the KeyboardEvent and MouseEvent interfaces provide additional dictionary members for
- initializing the internal state of the Event object’s key modifiers:
- specifically, the internal state queried for using the getModifierState() and getModifierState() methods. This section supplements the DOM4 steps for intializing a new Event object with these optional modifier states.
The following steps supplement the algorithm defined for constructing
- events in DOM4:
-
-
-
If the Event being constructed is a KeyboardEvent or MouseEvent object or an object that derives from either of these,
-and a EventModifierInit argument was provided to the constructor,
-then run the following sub-steps:
-
-
-
For each EventModifierInit argument, if the dictionary member
-begins with the string "modifier", then let the key modifier name be the
-dictionary member’s name excluding the prefix "modifier", and set the Event object’s internal key modifier state that matches the key modifier name to the corresponding value.
-
-
-
6. Legacy Event Initializers
-
This section is normative.
-
The following features are obsolete and should only be implemented by user agents that require compatibility with legacy software.
-
Early versions of this specification included an initialization method on
- the interface (for example initMouseEvent) that required a long
- list of parameters that, in most cases, did not fully initialize all
- attributes of the event object. Because of this, event interfaces which were
- derived from the basic Event interface required that the initializer of each of the derived interfaces be called explicitly in order to
- fully initialize an event.
-
Initializing all the attributes of a MutationEvent requires calls to two
- initializer methods: initEvent and initMutationEvent.
-
Due in part to the length of time in the development of this standard, some
- implementations MAY have taken a dependency on these (now deprecated)
- initializer methods. For completeness, these legacy event initializers are
- described in this section.
-
6.1. Initializers for interface KeyboardEvent
-
This section is informative
-
The argument list to this legacy KeyboardEvent initializer does not
- include the detailArg (present in other initializers) and
- adds the locale argument (see § 9.3.1 Changes between different drafts of UI Events); it is
- necessary to preserve this inconsistency for compatibility with existing
- implementations.
- Initializes attributes of a KeyboardEvent object. This
- method has the same behavior as UIEvent.initUIEvent().
- The value of detail remains undefined.
-
The initKeyboardEvent method is deprecated.
-
-
DOMString typeArg
-
Refer to the initEvent() method for a description of this parameter.
-
boolean bubblesArg
-
Refer to the initEvent() method for a description of this parameter.
-
boolean cancelableArg
-
Refer to the initEvent() method for a description of this parameter.
-
Specifies whether the Control key modifier is active.
-
boolean altKey
-
Specifies whether the Alt key modifier is active.
-
boolean shiftKey
-
Specifies whether the Shift key modifier is active.
-
boolean metaKey
-
Specifies whether the Meta key modifier is active.
-
-
-
7. Legacy Key & Mouse Event Attributes
-
This section is non-normative. The following attributes are obsolete and should
- only be implemented by user agents that require compatibility with legacy
- software that requires these keyboard events.
-
These features were never formally specified and the current browser
- implementations vary in significant ways.
Browser support for keyboards has traditionally relied on three ad-hoc
- attributes, keyCode, charCode, and UIEvent's which.
-
All three of these attributes return a numerical code that represents some
- aspect of the key pressed: keyCode is an index of the key
- itself. charCode is the ASCII value of the character keys. which is the character value where available and otherwise
- the key index. The values for these attributes, and the availability of the
- attribute, is inconsistent across platforms, keyboard languages and layouts, user agents, versions, and even event types.
charCode holds a character value, for keypress events which generate character input. The value
- is the Unicode reference number (code point) of that character
- (e.g. event.charCode = event.key.charCodeAt(0) for
- printable characters). For keydown or keyup events, the value of charCode is 0.
-
- keyCode holds a system- and
- implementation-dependent numerical code signifying the
- unmodified identifier associated with the key pressed. Unlike
- the key attribute, the set of possible values
- are not normatively defined in this specification. Typically,
- these value of the keyCode SHOULD represent
- the decimal codepoint in ASCII [RFC20][US-ASCII] or Windows
- 1252 [WIN1252], but MAY be drawn from a different appropriate
- character set. Implementations that are unable to identify a key
- use the key value 0.
-
Initializes the keyCode attribute of the KeyboardEvent to the system- and implementation-dependent
- numerical code signifying the unmodified identifier associated
- with the key pressed.
-
-
7.2. Legacy key models
-
This section is non-normative
-
Implementations differ on which values are exposed on these attributes for
- different event types. An implementation MAY choose to expose both virtual
- key codes and character codes in the keyCode property
- (conflated model), or report separate keyCode and charCode properties (split model).
Read the virtual key code from the operating system’s event
-information, if such information is available.
-
-
If an Input Method Editor is processing key input and the event is keydown, return 229.
-
-
If input key when pressed without modifiers would insert a numerical
-character (0-9), return the ASCII code of that numerical character.
-
-
If input key when pressed without modifiers would insert a lower
-case character in the a-z alphabetical range, return the ASCII code
-of the upper case equivalent.
-
-
If the implementation supports a key code conversion table for the
-operating system and platform, look up the value. If the conversion
-table specifies an alternate virtual key value for the given input,
-return the specified value.
-
-
If the key’s function, as determined in an implementation-specific
-way, corresponds to one of the keys in the § 7.2.3 Fixed virtual key codes table, return the corresponding key
-code.
-
-
Return the virtual key code from the operating system.
If the implementation supports a conflated model, set keyCode to the Unicode code point of the character
-being entered.
-
-
If the implementation supports a split model, set keyCode to 0.
-
-
7.2.3. Fixed virtual key codes
-
The virtual key codes for the following keys do not usually change with
- keyboard layouts on desktop systems:
-
-
-
-
Key
-
Virtual Key Code
-
Notes
-
-
-
Backspace
-
8
-
-
-
Tab
-
9
-
-
-
Enter
-
13
-
-
-
Shift
-
16
-
-
-
Control
-
17
-
-
-
Alt
-
18
-
-
-
CapsLock
-
20
-
-
-
Escape
-
27
-
Esc
-
-
Space
-
32
-
-
-
PageUp
-
33
-
-
-
PageDown
-
34
-
-
-
End
-
35
-
-
-
Home
-
36
-
-
-
ArrowLeft
-
37
-
-
-
ArrowUp
-
38
-
-
-
ArrowRight
-
39
-
-
-
ArrowDown
-
40
-
-
-
Delete
-
46
-
Del
-
-
7.2.4. Optionally fixed virtual key codes
-
The following punctuation characters MAY change virtual codes between
- keyboard layouts, but reporting these values will likely be more
- compatible with legacy content expecting US-English keyboard layout:
-
-
-
-
Key
-
Character
-
Virtual Key Code
-
-
-
Semicolon
-
";"
-
186
-
-
Colon
-
":"
-
186
-
-
Equals sign
-
"="
-
187
-
-
Plus
-
"+"
-
187
-
-
Comma
-
","
-
188
-
-
Less than sign
-
"<"
-
188
-
-
Minus
-
"-"
-
189
-
-
Underscore
-
"_"
-
189
-
-
Period
-
"."
-
190
-
-
Greater than sign
-
">"
-
190
-
-
Forward slash
-
"/"
-
191
-
-
Question mark
-
"?"
-
191
-
-
Backtick
-
"`"
-
192
-
-
Tilde
-
"~"
-
192
-
-
Opening squace bracket
-
"["
-
219
-
-
Opening curly brace
-
"{"
-
219
-
-
Backslash
-
"\"
-
220
-
-
Pipe
-
"|"
-
220
-
-
Closing square bracket
-
"]"
-
221
-
-
Closing curly brace
-
"}"
-
221
-
-
Single quote
-
"'"
-
222
-
-
Double quote
-
"""
-
222
-
-
8. Legacy Event Types
-
This section is normative. The following event types are obsolete and should
- only be implemented by user agents that require compatibility with legacy
- software.
The keypress event is the traditional method for capturing key events
- and processing them before the DOM is updated with the effects of the key
- press. Code that makes use of the keypress event typically relies on
- the legacy charCode, keyCode, and which attributes.
-
Note that the keypress event is specific to key events, and has been
- replaced by the more general event sequence of beforeinput and input events. These new input events are not specific to
- keyboard actions and can be used to capture user input regardless of the
- original source.
KeyboardEvent.isComposing : true if the key event occurs as part of a composition session, otherwise false
-
-
-
If supported by a user agent, this event MUST be dispatched
- when a key is pressed down, if and only if that key normally
- produces a character value. The keypress event type is
- device dependent and relies on the capabilities of the input devices
- and how they are mapped in the operating system.
The keypress event is traditionally associated with detecting
- a character value rather than a physical key, and might not
- be available on all keys in some configurations.
-
The keypress event type is defined in this specification for
- reference and completeness, but this specification deprecates the use of this event type. When in editing contexts, authors can
- subscribe to the beforeinput event instead.
Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
9.1.5. Web browsers and other dynamic or interactive user agents
-
9.1.6. Authoring tools
-
9.2. Things defined in CompositionEvents
-
9.2.1. Composition Events
-
9.3. Things defined in Changes
-
9.3.1. Changes between different drafts of UI Events
-
10. Glossary [DELETE]
-
This section will be deleted.
-
Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-
activation behavior
-
-
The action taken when an event, typically initiated by users through
-an input device, causes an element to fulfill a defined task. The task MAY
-be defined for that element by the host language, or by
-author-defined variables, or both. The default task for any given element
-MAY be a generic action, or MAY be unique to that element. For example, the
-activation behavior of an HTML or SVG <a> element is to
-cause the user agent to traverse the link specified in the href attribute, with the further optional parameter of
-specifying the browsing context for the traversal (such as the current
-window or tab, a named window, or a new window). The activation behavior of
-an HTML <input> element with the type attribute value submit is be to send the values of the form
-elements to an author-defined IRI by the author-defined HTTP method. See § 9.1.1 Activation triggers and behavior for more details.
In HTML or XHTML documents, the body element represents the contents of the
-document. In a well-formed HTML document, the body element is a first
-descendant of the root element.
-
character value
-
-
In the context of key values, a character value is a string representing one
-or more Unicode characters, such as a letter or symbol, or a set of letters, each
-belonging to the set of valid Unicode character categories.
-In this specification, character values are denoted as a unicode string
-(e.g., U+0020) or a glyph representation of the same code point (e.g., " "), and are color coded to help distinguish these two representations.
-
In source code, some key values, such as non-graphic characters, can be
-represented using the character escape syntax of the programming language in
-use.
-
dead key
-
-
A dead key is a key or combination of keys which produces no character by
-itself, but which in combination or sequence with another key produces a
-modified character, such as a character with diacritical marks (e.g., "ö", "é", "â").
-
default action
-
-
A default action is an OPTIONAL supplementary behavior that an
-implementation MUST perform in combination with the dispatch of the event
-object. Each event type definition, and each specification, defines the default action for that event type, if it has one. An instance of an
-event MAY have more than one default action under some circumstances,
-such as when associated with an activation trigger. A default
-action MAY be cancelled through the invocation of the preventDefault() method. For more details, see § 9.1.2 Default actions and cancelable events.
-
deprecated
-
-
Features marked as deprecated are included in the specification as reference
-to older implementations or specifications, but are OPTIONAL and
-discouraged. Only features which have existing or in-progress replacements
-MUST be deprecated in this specification. Implementations which do not
-already include support for the feature MAY implement deprecated features
-for reasons of backwards compatibility with existing content, but content
-authors creating content SHOULD NOT use deprecated features, unless there is
-no other way to solve a use case. Other specifications which reference this
-specification SHOULD NOT use deprecated features, but SHOULD point instead
-to the replacements of which the feature is deprecated in favor. Features
-marked as deprecated in this specification are expected to be dropped from
-future specifications.
-
empty string
-
-
The empty string is a value of type DOMString of length 0, i.e., a string which contains no characters (neither
-printing nor control characters).
-
event
-
-
An event is the representation of some occurrence (such as a mouse click on
-the presentation of an element, the removal of child node from an element,
-or any number of other possibilities) which is associated with its event
-target. Each event is an instantiation of one specific event
-type.
Any language which integrates the features of another language or API
-specification, while normatively referencing the origin specification rather
-than redefining those features, and extending those features only in ways
-defined by the origin specification. An origin specification typically is
-only intended to be implemented in the context of one or more host
-languages, not as a standalone language. For example, XHTML, HTML, and SVG
-are host languages for UI Events, and they integrate and extend the objects
-and models defined in this specification.
-
IME
-
input method editor
-
-
An input method editor (IME), also known as a front end
-processor, is an application that performs the conversion between
-keystrokes and ideographs or other characters, usually by user-guided
-dictionary lookup, often used in East Asian languages (e.g., Chinese,
-Japanese, Korean). An IME MAY also be used for dictionary-based word
-completion, such as on mobile devices. See § 4.3.3 Input Method Editors for treatment of
-IMEs in this specification. See also text composition system.
-
key mapping
-
-
Key mapping is the process of assigning a key value to a particular key, and
-is the result of a combination of several factors, including the operating
-system and the keyboard layout (e.g., QWERTY, Dvorak, Spanish,
-InScript, Chinese, etc.), and after taking into account all modifier
-key (Shift, Alt, et al.) and dead key states.
-
key value
-
-
A key value is a character value or multi-character string (such as "Enter", "Tab", or "MediaTrackNext") associated with a key in a
-particular state. Every key has a key value, whether or not it has a character value. This includes control keys, function keys, modifier keys, dead keys, and any other key. The key value of
-any given key at any given time depends upon the key mapping.
-
modifier key
-
-
A modifier key changes the normal behavior of a key, such as to produce a
-character of a different case (as with the Shift key), or to alter
-what functionality the key triggers (as with the Fn or Alt keys). See § 4.3.1 Modifier keys for more information about modifier keys and
-refer to the Modifier Keys table in [UIEvents-Key] for a list
-of valid modifier keys.
-
QWERTY
-
-
QWERTY (pronounced ˈkwɜrti) is a common keyboard layout,
-so named because the first five character keys on the top row of letter keys
-are Q, W, E, R, T, and Y. There are many other popular keyboard layouts
-(including the Dvorak and Colemak layouts), most designed for localization
-or ergonomics.
-
text composition system
-
-
A software component that interprets some form of alternate input (such as a input method editor, a speech processor, or a handwriting recognition
-system) and converts it to text.
-
Unicode character categories
-
-
A subset of the General Category values that are defined for each Unicode
-code point. This subset contains all the
-Letter (Ll, Lm, Lo, Lt, Lu),
-Number (Nd, Nl, No),
-Punctuation (Pc, Pd, Pe, Pf, Pi, Po, Ps)
-and Symbol (Sc, Sk, Sm, So)
-category values.
-
un-initialized value
-
-
The value of any event attribute (such as bubbles or currentTarget) before the event has been initialized with initEvent(). The un-initialized values of an event apply
-immediately after a new event has been created using the method createEvent().
-
user agent
-
-
A program, such as a browser or content authoring tool, normally running on
-a client machine, which acts on a user’s behalf in retrieving, interpreting,
-executing, presenting, or creating content. Users MAY act on the content
-using different user agents at different times, for different purposes. See
-the § 9.1.5 Web browsers and other dynamic or interactive user agents and § 9.1.6 Authoring tools for details on the
-requirements for a conforming user agent.
-
Window
-
-
The Window is the object referred to by the current document’s
-browsing context’s Window Proxy object as defined in HTML5[HTML5].
-
-
-
-
Conformance
-
Document conventions
-
Conformance requirements are expressed
- with a combination of descriptive assertions
- and RFC 2119 terminology.
- The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”
- in the normative parts of this document
- are to be interpreted as described in RFC 2119.
- However, for readability,
- these words do not appear in all uppercase letters in this specification.
-
All of the text of this specification is normative
- except sections explicitly marked as non-normative, examples, and notes. [RFC2119]
-
Examples in this specification are introduced with the words “for example”
- or are set apart from the normative text
- with class="example",
- like this:
-
-
-
This is an example of an informative example.
-
-
Informative notes begin with the word “Note”
- and are set apart from the normative text
- with class="note",
- like this:
-
Note, this is an informative note.
-
-
Conformant Algorithms
-
Requirements phrased in the imperative as part of algorithms
- (such as "strip any leading space characters"
- or "return false and abort these steps")
- are to be interpreted with the meaning of the key word
- ("must", "should", "may", etc)
- used in introducing the algorithm.
-
Conformance requirements phrased as algorithms or specific steps
- can be implemented in any manner,
- so long as the end result is equivalent.
- In particular, the algorithms defined in this specification
- are intended to be easy to understand
- and are not intended to be performant.
- Implementers are encouraged to optimize.
-
-
-
\ No newline at end of file
diff --git a/split/keyboard-events.txt b/split/keyboard-events.txt
deleted file mode 100644
index 6631428..0000000
--- a/split/keyboard-events.txt
+++ /dev/null
@@ -1,2427 +0,0 @@
-
Keyboard Events
-
-
-Shortname: keyboard-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
- *** Keyboard Events ***
-
- Note: This is an experimental split of the UI Events spec into smaller, event-specific
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
-{
- "DWW95": {
- "title": "Developing International Software for Windows 95 and Windows NT: A Handbook for International Software Design",
- "authors": [ "N. Kano" ],
- "publisher": "Microsoft Press",
- "date": "1995",
- "isbn": "1-55615-840-8"
- },
- "US-ASCII": {
- "title": "Coded Character Set - 7-Bit American Standard Code for Information Interchange",
- "publisher": "Standard ANSI X3.4-1986",
- "date": "1986"
- },
- "WIN1252": {
- "title": "Windows 1252 a Coded Character Set - 8-Bit",
- "href": "https://www.microsoft.com/globaldev/reference/sbcs/1252.htm",
- "publisher": "Microsoft Corporation"
- }
-}
-
-
-
Introduction
-
-
Overview
-
- TODO.
-
-
Conformance
-
- Boilerplate?
-
-
Stylistic Conventions
-
-This specification follows the
-Proposed W3C Specification Conventions,
-with the following supplemental additions:
-
-* The key cap printed on a key is shown as
- KEYCAP{↓}, KEYCAP{=} or KEYCAP{Q}. This is used to refer to a
- key from the user's perspective without regard for the
- {{KeyboardEvent/key}} and {{KeyboardEvent/code}} values in the
- generated {{KeyboardEvent}}.
-
-* Glyphs representing character are shown as: GLYPH{𣧂}.
-
-* Unicode character encodings are shown as: UNI{U+003d}.
-
-* Names of key values generated by a key press (i.e., the value of
- {{KeyboardEvent}}.{{KeyboardEvent/key}}) are shown as:
- KEY{ArrowDown}, KEY_NOLINK{=}, KEY_NOLINK{q} or KEY_NOLINK{Q}.
-
-* Names of key codes associated with the physical keys (i.e., the
- value of {{KeyboardEvent}}.{{KeyboardEvent/code}}) are shown as:
- CODE{ArrowDown}, CODE{Equal} or CODE{KeyQ}.
-
-
-In addition, certain terms are used in this specification with particular
-meanings. The term implementation applies to a browser, content
-authoring tool, or other user agent that implements this specification,
-while a content author is a person who writes script or code that takes
-advantage of the interfaces, methods, attributes, events, and other features
-described in this specification in order to make Web applications, and a user is
-the person who uses those Web applications in an implementation.
-
-And finally:
-
-
This is a note.
-
-
-
-
This is an open issue.
-
-
This is a warning.
-
-
- interface Example {
- // This is an IDL definition.
- };
-
-
-
Keyboard Events
-
- Keyboard events are device dependent, i.e., they rely on the capabilities of
- the input devices and how they are mapped in the operating systems. Refer to
- Keyboard events and key values for more details,
- including examples on how Keyboard Events are used in combination with
- Composition Events. Depending on the character generation device, keyboard
- events might not be generated.
-
-
- Keyboard events are only one modality of providing textual input. For
- editing scenarios, consider also using the {{InputEvent}} as an alternate to
- (or in addition to) keyboard events.
-
-
-
Interface KeyboardEvent
-
-
Introduced in this specification
-
- The {{KeyboardEvent}} interface provides specific contextual information
- associated with keyboard devices. Each keyboard event references a key
- using a value. Keyboard events are commonly directed at the element that
- has the focus.
-
- The {{KeyboardEvent}} interface provides convenient attributes for some
- common modifiers keys: {{KeyboardEvent/ctrlKey}},
- {{KeyboardEvent/shiftKey}}, {{KeyboardEvent/altKey}},
- {{KeyboardEvent/metaKey}}. These attributes are equivalent to using the
- method {{KeyboardEvent/getModifierState()}} with KEYCAP{Control},
- KEYCAP{Shift}, KEYCAP{Alt}, or KEYCAP{Meta} respectively.
-
- To create an instance of the {{KeyboardEvent}} interface, use the
- {{KeyboardEvent}} constructor, passing an optional
- {{KeyboardEventInit}} dictionary.
-
-
- 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.
-
- 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}}.
-
- 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.
-
-
{{Event}}.{{Event/target}} : focused element processing the key event or if no |
- | | element focused, then the body element if available, otherwise the |
- | | root element
{{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.
-
{{Event}}.{{Event/target}} : focused element processing the key event or if no |
- | | element focused, then the body element if available, otherwise the |
- | | root element
{{KeyboardEvent}}.{{KeyboardEvent/key}} : the key value of the key pressed.
|
- | |
{{KeyboardEvent}}.{{KeyboardEvent/code}} : the code value associated with the |
- | | key's physical placement on the keyboard.
|
- | |
{{KeyboardEvent}}.{{KeyboardEvent/location}} : the location of the key on the |
- | | device.
|
- | |
{{KeyboardEvent}}.{{KeyboardEvent/altKey}} : true if KEYCAP{Alt} |
- | | modifier was active, otherwise false
|
- | |
{{KeyboardEvent}}.{{KeyboardEvent/shiftKey}} : true if KEYCAP{Shift}|
- | | modifier was active, otherwise false
|
- | |
{{KeyboardEvent}}.{{KeyboardEvent/ctrlKey}} : true if KEYCAP{Control}|
- | | modifier was active, otherwise false
|
- | |
{{KeyboardEvent}}.{{KeyboardEvent/metaKey}} : true if KEYCAP{Meta} |
- | | modifier was active, otherwise false
|
- | |
{{KeyboardEvent}}.{{KeyboardEvent/repeat}} : true if a key has been |
- | | depressed long enough to trigger key repetition, otherwise false
|
- | |
{{KeyboardEvent}}.{{KeyboardEvent/isComposing}} : true if the key |
- | | event occurs as part of a composition session, otherwise false
|
- | |
|
- ++------------------+--------------------------------------------------------------------------------------+
-
- A user agent MUST dispatch this event when a key is released.
- The EVENT{keyup} event type is device dependent and relies on the
- capabilities of the input devices and how they are mapped in the
- operating system. This event type MUST be generated after the key
- mapping. This event type MUST be dispatched after the
- EVENT{keydown}, EVENT{beforeinput}, and EVENT{input} events
- associated with the same key.
-
-
- The EVENT{keydown} and EVENT{keyup} events are traditionally
- associated with detecting any key, not just those which produce a
- character value.
-
-
-
-
Keyboard events and key values
-
- This section contains necessary information regarding keyboard events:
-
- * Explanation of keyboard layout, mapping, and key values.
- * Relations between keys, such as dead keys or modifiers keys.
- * Relations between keyboard events and their default actions.
- * The set of key values, and guidelines on how to extend this set.
-
-
- This section uses Serbian and Kanji characters which could be misrepresented or
- unavailable in the PDF version or printed version of this specification.
-
-
-
Keyboard Input
-
- This section is non-normative
-
- The relationship of each key to the complete keyboard has three separate
- aspects, each of which vary among different models and configurations of
- keyboards, particularly for locale-specific reasons:
-
- * Mechanical layout: the dimensions, size, and placement
- of the physical keys on the keyboard
- * Visual markings: the labels (or legends) that
- mark each key
- * Functional mapping: the abstract key-value association
- of each key.
-
- This specification only defines the functional mapping, in terms of
- key values and
- code values,
- but briefly describes key legends
- for background.
-
-
Key Legends
-
- This section is informative
-
- The key legend is the visual marking that is printed or embossed on the
- key cap (the rectangular "cap" that covers the mechanical
- switch for the key). These markings normally consist of one or more
- characters that a keystroke on that key will produce (such as GLYPH{G},
- GLYPH{8}, or GLYPH{ш}), or names or symbols which indicate that key's
- function (such as an upward-pointing arrow GLYPH{⇧} indicating
- KEYCAP{Shift}, or the string "Enter"). Keys are often
- referred to by this marking (e.g., Press the "Shift" and
- "G" keys.). Note, however, that the visual appearance
- of the key has no bearing on its digital representation, and in many
- configurations may be completely inaccurate. Even the control and
- function keys, such as KEYCAP{Enter}, may be mapped to different
- functionality, or even mapped as character keys.
-
-
- Many keyboards contain keys that do not normally produce any characters,
- even though the symbol might have a Unicode equivalent. For example, the
- KEYCAP{Shift} key might bear the symbol GLYPH{⇧}, which has the
- Unicode code point UNI{U+21E7}, but
- pressing the KEYCAP{Shift} key will not produce this character value,
- and there is no Unicode code point for KEYCAP{Shift}.
-
-
-
Key codes
-
- A key {{KeyboardEvent/code}} is an attribute of a keyboard event that can be
- used to identify the physical key associated with the keyboard event. It is
- similar to USB Usage IDs in that it provides a low-level value (similar to a
- scancode) that is vendor-neutral.
-
- The primary purpose of the {{KeyboardEvent/code}} attribute is to provide a
- consistent and coherent way to identify keys based on their physical
- location. In addition, it also provides a stable name (unaffected by the
- current keyboard state) that uniquely identifies each key on the keyboard.
-
- The list of valid {{KeyboardEvent/code}} values is defined in the
- [[!UIEvents-Code]].
-
-
Motivation for the {{KeyboardEvent/code}} Attribute
-
- The standard PC keyboard has a set of keys (which we refer to as
- writing system keys) that generate different
- {{KeyboardEvent/key}} values based on the current keyboard layout
- selected by the user. This situation makes it difficult to write code
- that detects keys based on their physical location since the code would
- need to know which layout is in effect in order to know which
- {{KeyboardEvent/key}} values to check for. A real-world example of this
- is a game that wants to use the GLYPH{W}, GLYPH{A}, GLYPH{S} and
- GLYPH{D} keys to control player movement. The {{KeyboardEvent/code}}
- attribute solves this problem by providing a stable value to check that
- is not affected by the current keyboard layout.
-
- In addition, the values in the {{KeyboardEvent/key}} attribute depend as
- well on the current keyboard state. Because of this, the order in which
- keys are pressed and released in relation to modifier keys can affect
- the values stored in the {{KeyboardEvent/key}} attribute. The
- {{KeyboardEvent/code}} attribute solves this problem by providing a
- stable value that is not affected by the current keyboard state.
-
-
The Relationship Between {{KeyboardEvent/key}} and {{KeyboardEvent/code}}
-
-
-
{{KeyboardEvent/key}}
-
The {{KeyboardEvent/key}} attribute is intended for users who
- are interested in the meaning of the key being pressed, taking
- into account the current keyboard layout (and IME;
- dead keys are given a unique
- {{KeyboardEvent/key}} value). Example use case: Detecting
- modified keys or bare modifier keys (e.g., to perform an action
- in response to a keyboard shortcut).
-
-
-
{{KeyboardEvent/code}}
-
The {{KeyboardEvent/code}} attribute is intended for users who
- are interested in the key that was pressed by the user, without
- any layout modifications applied. Example use case: Detecting
- WASD keys (e.g., for movement controls in a game) or trapping
- all keys (e.g., in a remote desktop client to send all keys to
- the remote host).
-
-
-
-
code Examples
-
-
- Handling the Left and Right Alt Keys
-
- ++----------+----------------------+----------------------+------------------------------------------+
- =| Keyboard |{{KeyboardEvent}} |{{KeyboardEvent}} | Notes |
- | Layout |{{KeyboardEvent/key}} |{{KeyboardEvent/code}}| |
- +----------+----------o-----------+----------o-----------+------------------------------------------+
- +| US | KEY{Alt} | CODE{AltLeft} | {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} |
- +| French | KEY{Alt} | CODE{AltLeft} | {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} |
- +| US | KEY{Alt} | CODE{AltRight} | {{KeyboardEvent/DOM_KEY_LOCATION_RIGHT}} |
- +| French | KEY{AltGraph} | CODE{AltRight} | {{KeyboardEvent/DOM_KEY_LOCATION_RIGHT}} |
- ++----------+----------------------+----------------------+------------------------------------------+
-
- In this example, checking the {{KeyboardEvent/key}} attribute permits
- matching KEYCAP{Alt} without worrying about which Alt key (left or
- right) was pressed. Checking the {{KeyboardEvent/code}} attribute
- permits matching the right Alt key (CODE{AltRight}) without worrying
- about which layout is currently in effect.
-
- Note that, in the French example, the KEYCAP{Alt} and KEYCAP{AltGraph} keys
- retain their left and right location, even though there is only one of
- each key.
-
-
-
- Handling the Single Quote Key
-
- ++----------+----------------------+----------------------+--------+
- =| Keyboard |{{KeyboardEvent}} |{{KeyboardEvent}} | Notes |
- | Layout |{{KeyboardEvent/key}} |{{KeyboardEvent/code}}| |
- +----------+----------o-----------+-----------o----------+--------+
- +| US | KEY_NOLINK{'} | CODE{Quote} | |
- +| Japanese | KEY_NOLINK{:} | CODE{Quote} | |
- +| US Intl | KEY{Dead} | CODE{Quote} | |
- ++----------+----------------------+----------------------+--------+
-
- This example shows how dead key values are encoded in the
- attributes. The {{KeyboardEvent/key}} values vary based on the
- current locale, whereas the {{KeyboardEvent/code}} attribute returns
- a consistent value.
-
-
-
- Handling the GLYPH{2} Key (with and without Shift pressed) on
- various keyboard layouts.
-
- ++----------+----------------------+----------------------+----------------------------+
- =| Keyboard |{{KeyboardEvent}} |{{KeyboardEvent}} | Notes |
- | Layout |{{KeyboardEvent/key}} |{{KeyboardEvent/code}}| |
- +----------+----------o-----------+----------o-----------+----------------------------+
- +| US | KEY_NOLINK{2} | CODE{Digit2} | |
- +| US | KEY_NOLINK{@} | CODE{Digit2} | {{KeyboardEvent/shiftKey}} |
- +| UK | KEY_NOLINK{2} | CODE{Digit2} | |
- +| UK | KEY_NOLINK{"} | CODE{Digit2} | {{KeyboardEvent/shiftKey}} |
- +| French | KEY_NOLINK{é} | CODE{Digit2} | |
- +| French | KEY_NOLINK{2} | CODE{Digit2} | {{KeyboardEvent/shiftKey}} |
- ++----------+----------------------+----------------------+----------------------------+
-
- Regardless of the current locale or the modifier key state, pressing
- the key labelled GLYPH{2} on a US keyboard always results in
- CODE{Digit2} in the {{KeyboardEvent/code}} attribute.
-
-
-
-
- Sequence of Keyboard Events : KEYCAP{Shift} and KEYCAP{2}
-
-
- Compare the attribute values in the following two key event
- sequences. They both produce the GLYPH{@} character on a US
- keyboard, but differ in the order in which the keys are released. In
- the first sequence, the order is: KEYCAP{Shift} (down), KEYCAP{2}
- (down), KEYCAP{2} (up), KEYCAP{Shift} (up).
-
- ++---+----------+----------------------+----------------------+-----------------------------------------+
- =| # | Event |{{KeyboardEvent}} |{{KeyboardEvent}} | Notes |
- | | Type |{{KeyboardEvent/key}} |{{KeyboardEvent/code}}| |
- +---+----------+----------o-----------+----------o-----------+-----------------------------------------+
- +| 1 | keydown | KEY{Shift} | CODE{ShiftLeft} | {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} |
- +| 2 | keydown | KEY_NOLINK{@} | CODE{Digit2} | {{KeyboardEvent/shiftKey}} |
- +| 3 | keypress | KEY_NOLINK{@} | CODE{Digit2} | (if supported) |
- +| 4 | keyup | KEY_NOLINK{@} | CODE{Digit2} | {{KeyboardEvent/shiftKey}} |
- +| 5 | keyup | KEY{Shift} | CODE{ShiftLeft} | {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} |
- ++---+----------+----------------------+----------------------+-----------------------------------------+
-
- In the second sequence, the Shift is released before the 2,
- resulting in the following event order: KEYCAP{Shift} (down),
- KEYCAP{2} (down), KEYCAP{Shift} (up), KEYCAP{2} (up).
-
- ++---+----------+----------------------+----------------------+-----------------------------------------+
- =| # | Event |{{KeyboardEvent}} |{{KeyboardEvent}} | Notes |
- | | Type |{{KeyboardEvent/key}} |{{KeyboardEvent/code}}| |
- +---+----------+----------o-----------+----------o-----------+-----------------------------------------+
- +| 1 | keydown | KEY{Shift} | CODE{ShiftLeft} | {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} |
- +| 2 | keydown | KEY_NOLINK{@} | CODE{Digit2} | {{KeyboardEvent/shiftKey}} |
- +| 3 | keypress | KEY_NOLINK{@} | CODE{Digit2} | (if supported) |
- +| 4 | keyup | KEY{Shift} | CODE{ShiftLeft} | {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} |
- +| 5 | keyup | KEY_NOLINK{2} | CODE{Digit2} | |
- ++---+----------+----------------------+----------------------+-----------------------------------------+
-
- Note that the values contained in the {{KeyboardEvent/key}}
- attribute does not match between the keydown and keyup events for
- the GLYPH{2} key. The {{KeyboardEvent/code}} attribute provides a
- consistent value that is not affected by the current modifier state.
-
-
-
-
{{KeyboardEvent/code}} and Virtual Keyboards
-
- The usefulness of the {{KeyboardEvent/code}} attribute is less obvious
- for virtual keyboards (and also for remote controls and chording
- keyboards). In general, if a virtual (or remote control) keyboard is
- mimicking the layout and functionality of a standard keyboard, then it
- MUST also set the {{KeyboardEvent/code}} attribute as appropriate. For
- keyboards which are not mimicking the layout of a standard keyboard,
- then the {{KeyboardEvent/code}} attribute MAY be set to the closest
- match on a standard keyboard or it MAY be left undefined.
-
- For virtual keyboards with keys that produce different values based on
- some modifier state, the {{KeyboardEvent/code}} value should be the
- {{KeyboardEvent/key}} value generated when the button is pressed while
- the device is in its factory-reset state.
-
-
Keyboard Event key Values
-
- A key value is a DOMString that can be used to indicate any
- given key on a keyboard, regardless of position or state, by the value it
- produces. These key values MAY be used as return values for keyboard events
- generated by the implementation, or as input values by the content author to
- specify desired input (such as for keyboard shortcuts).
-
- The list of valid key values is defined in [[!UIEvents-Key]].
-
- Key values can be used to detect the value of a key which has been pressed,
- using the {{KeyboardEvent/key}} attribute. Content authors can retrieve the
- character value of upper- or lower-case letters, number, symbols, or
- other character-producing keys, and also the key value of control
- keys, modifier keys, function keys, or other keys that do not generate
- characters. These values can be used for monitoring particular input
- strings, for detecting and acting on modifier key input in combination with
- other inputs (such as a mouse), for creating virtual keyboards, or for any
- number of other purposes.
-
- Key values can also be used by content authors in string comparisons, as
- values for markup attributes (such as the HTML accesskey) in
- conforming host languages, or for other related purposes. A
- conforming host language SHOULD allow content authors to use either
- of the two equivalent string values for a key value: the character
- value, or the key value.
-
-
- While implementations will use the most relevant value for a key
- independently of the platform or keyboard layout mappings, content authors
- can not make assumptions on the ability of keyboard devices to generate
- them. When using keyboard events and key values for shortcut-key
- combinations, content authors can consider using numbers and function
- keys (KEYCAP{F4}, KEYCAP{F5}, and so on) instead of letters ([[DWW95]])
- given that most keyboard layouts will provide keys for those.
-
-
- A key value does not indicate a specific key on the physical keyboard, nor
- does it reflect the character printed on the key. A key value indicates the
- current value of the event with consideration to the current state of all
- active keys and key input modes (including shift modes), as reflected in the
- operating-system mapping of the keyboard and reported to the implementation.
- In other words, the key value for the key labeled KEYCAP{O} on a
- QWERTY keyboard has the key value KEY_NOLINK{o} in an unshifted state and
- KEY_NOLINK{O} in a shifted state. Because a user can map their keyboard to an
- arbitrary custom configuration, the content author is encouraged not to
- assume that a relationship exists between the shifted and unshifted states
- of a key and the majuscule form (uppercase or capital letters) and minuscule
- form (lowercase or small letters) of a character representation, but is
- encouraged instead to use the value of the {{KeyboardEvent/key}} attribute.
- For example, the Standard "102" Keyboard layout depicted in [[UIEvents-Code]]
- illustrates one possible set of key mappings on one possible keyboard
- layout. Many others exist, both standard and idiosyncratic.
-
-
- To simplify dead key support, when the operating-system mapping of
- the keyboard is handling a dead key state, the current state of the
- dead key sequence is not reported via the {{KeyboardEvent/key}} attribute.
- Rather, a key value of KEY{Dead} is reported. Instead, implementations
- generate composition events which
- contain the intermediate state of the dead key sequence reported via the
- {{CompositionEvent/data}} attribute. As in the previous example, the key
- value for the key marked KEYCAP{O} on a QWERTY keyboard has a
- {{CompositionEvent/data}} value of "ö" in an
- unshifted state during a dead-key operation to add an umlaut diacritic, and
- "Ö" in a shifted state during a dead-key
- operation to add an umlaut diacritic.
-
-
- It is also important to note that there is not a one-to-one relationship
- between key event states and key values. A particular key value might be
- associated with multiple keys. For example, many standard keyboards contain
- more than one key with the KEYCAP{Shift} key value (normally distinguished
- by the {{KeyboardEvent/location}} values
- {{KeyboardEvent/DOM_KEY_LOCATION_LEFT}} and
- {{KeyboardEvent/DOM_KEY_LOCATION_RIGHT}}) or KEYCAP{8} key value (normally
- distinguished by the {{KeyboardEvent/location}} values
- {{KeyboardEvent/DOM_KEY_LOCATION_STANDARD}} and
- {{KeyboardEvent/DOM_KEY_LOCATION_NUMPAD}}), and user-configured custom
- keyboard layouts MAY duplicate any key value in multiple key-state scenarios
- (note that {{KeyboardEvent/location}} is intended for standard keyboard
- layouts, and cannot always indicate a meaningful distinction).
-
- Finally, the meaning of any given character representation is
- context-dependent and complex. For example, in some contexts, the asterisk
- (star) glyph (GLYPH{*}) represents a footnote or
- emphasis (when bracketing a passage of text). However, in some documents or
- executable programs it is equivalent to the mathematical multiplication
- operation, while in other documents or executable programs, that function is
- reserved for the multiplication symbol (GLYPH{×}, Unicode value
- UNI{U+00D7}) or the Latin small letter "x"
- (due to the lack of a multiplication key on many keyboards and the
- superficial resemblance of the glyphs GLYPH{×} and GLYPH{x}). Thus,
- the semantic meaning or function of character representations is outside the
- scope of this specification.
-
-
Modifier keys
-
- Keyboard input uses modifier keys to change the normal behavior of a
- key. Like other keys, modifier keys generate EVENT{keydown} and
- EVENT{keyup} events, as shown in the example below. Some modifiers are
- activated while the key is being pressed down or maintained pressed such
- as KEYCAP{Alt}, KEYCAP{Control}, KEYCAP{Shift}, KEYCAP{AltGraph}, or
- KEYCAP{Meta}. Other modifiers are activated depending on their state
- such as KEYCAP{CapsLock}, KEYCAP{NumLock}, or KEYCAP{ScrollLock}. Change
- in the state happens when the modifier key is being pressed down. The
- {{KeyboardEvent}} interface provides convenient attributes for some
- common modifiers keys: {{KeyboardEvent/ctrlKey}},
- {{KeyboardEvent/shiftKey}}, {{KeyboardEvent/altKey}},
- {{KeyboardEvent/metaKey}}. Some operating systems simulate the
- KEYCAP{AltGraph} modifier key with the combination of the KEYCAP{Alt}
- and KEYCAP{Control} modifier keys. Implementations are encouraged to use
- the KEYCAP{AltGraph} modifier key.
-
-
- This example describes a possible sequence of events
- associated with the generation of the Unicode character Q (Latin
- Capital Letter Q, Unicode code point UNI{U+0051}) on a US
- keyboard using a US mapping:
-
- ++---+-------------+----------------------+----------------------------+------------------------+
- =| # | Event Type |{{KeyboardEvent}} | Modifiers | Notes |
- | | |{{KeyboardEvent/key}} | | |
- +---+-------------+----------o-----------+-------------o--------------+------------------------+
- +| 1 | keydown | KEY{Shift} | {{KeyboardEvent/shiftKey}} | |
- +| 2 | keydown | KEY_NOLINK{Q} | {{KeyboardEvent/shiftKey}} | Latin Capital Letter Q |
- +| 3 | beforeinput | | | |
- +| 4 | input | | | |
- +| 5 | keyup | KEY_NOLINK{Q} | {{KeyboardEvent/shiftKey}} | |
- +| 6 | keyup | KEY{Shift} | | |
- ++---+-------------+----------------------+----------------------------+------------------------+
-
-
-
- Th example describes an alternate sequence of keys to the
- example above, where the KEYCAP{Shift} key is released before the
- KEYCAP{Q} key. The key value for the KEYCAP{Q} key will revert to its
- unshifted value for the EVENT{keyup} event:
-
- ++---+-------------+----------------------+----------------------------+------------------------+
- =| # | Event Type |{{KeyboardEvent}} | Modifiers | Notes |
- | | |{{KeyboardEvent/key}} | | |
- +---+-------------+----------o-----------+-------------o--------------+------------------------+
- +| 1 | keydown | KEY{Shift} | {{KeyboardEvent/shiftKey}} | |
- +| 2 | keydown | KEY_NOLINK{Q} | {{KeyboardEvent/shiftKey}} | Latin Capital Letter Q |
- +| 3 | beforeinput | | | |
- +| 4 | input | | | |
- +| 5 | keyup | KEY{Shift} | | |
- +| 6 | keyup | KEY_NOLINK{q} | | Latin Small Letter Q |
- ++---+-------------+----------------------+----------------------------+------------------------+
-
-
-
- The following example describes a possible sequence of keys that
- does not generate a Unicode character (using the same configuration
- as the previous example):
-
- ++---+-------------+----------------------+----------------------------+----------------------------+
- =| # | Event Type |{{KeyboardEvent}} | Modifiers | Notes |
- | | |{{KeyboardEvent/key}} | | |
- +---+-------------+----------o-----------+-------------o--------------+----------------------------+
- +| 1 | keydown | KEY{Control} | {{KeyboardEvent/ctrlKey}} | |
- +| 2 | keydown | KEY_NOLINK{v} | {{KeyboardEvent/ctrlKey}} | Latin Small Letter V |
- +| | | | | No EVENT{beforeinput} |
- | | | | | or EVENT{input} events are |
- | | | | | generated. |
- +| 3 | keyup | KEY_NOLINK{v} | {{KeyboardEvent/ctrlKey}} | Latin Small Letter V |
- +| 4 | keyup | KEY{Control} | | |
- ++---+-------------+----------------------+----------------------------+----------------------------+
-
-
-
- The following example shows the sequence of events when both KEYCAP{Shift} and
- KEYCAP{Control} are pressed:
-
- ++---+-------------+----------------------+----------------------------+----------------------------+
- =| # | Event Type |{{KeyboardEvent}} | Modifiers | Notes |
- | | |{{KeyboardEvent/key}} | | |
- +---+-------------+----------o-----------+-------------o--------------+----------------------------+
- +| 1 | keydown | KEY{Control} | {{KeyboardEvent/ctrlKey}} | |
- +| 2 | keydown | KEY{Shift} | {{KeyboardEvent/ctrlKey}}, | |
- | | | | {{KeyboardEvent/shiftKey}} | |
- +| 3 | keydown | KEY_NOLINK{V} | {{KeyboardEvent/ctrlKey}}, | Latin Capital Letter V |
- | | | | {{KeyboardEvent/shiftKey}} | |
- +| | | | | No EVENT{beforeinput} |
- | | | | | or EVENT{input} events are |
- | | | | | generated. |
- +| 4 | keyup | KEY_NOLINK{V} | {{KeyboardEvent/ctrlKey}}, | Latin Capital Letter V |
- | | | | {{KeyboardEvent/shiftKey}} | |
- +| 5 | keyup | KEY{Shift} | {{KeyboardEvent/ctrlKey}} | |
- +| 6 | keyup | KEY{Control} | | |
- ++---+-------------+----------------------+----------------------------+----------------------------+
-
-
-
- For non-US keyboard layouts, the sequence of events is the same, but
- the value of the key is based on the current keyboard layout. This
- example shows a sequence of events when an Arabic keyboard layout is
- used:
-
- ++---+-------------+----------------------+----------------------------+----------------------------+
- =| # | Event Type |{{KeyboardEvent}} | Modifiers | Notes |
- | | |{{KeyboardEvent/key}} | | |
- +---+-------------+----------o-----------+-------------o--------------+----------------------------+
- +| 1 | keydown | KEY{Control} | {{KeyboardEvent/ctrlKey}} | |
- +| 2 | keydown | KEY_NOLINK{ر} | {{KeyboardEvent/ctrlKey}} | Arabic Letter Reh |
- +| | | | | No EVENT{beforeinput} |
- | | | | | or EVENT{input} events are |
- | | | | | generated. |
- +| 3 | keyup | KEY_NOLINK{ر} | {{KeyboardEvent/ctrlKey}} | Arabic Letter Reh |
- +| 4 | keyup | KEY{Control} | | |
- ++---+-------------+----------------------+----------------------------+----------------------------+
-
-
-
- The value in the EVENT{keydown} and EVENT{keyup} events varies based on
- the current keyboard layout in effect when the key is pressed. This
- means that the KEYCAP{v} key on a US layout and the KEYCAP{ر} key on an
- Arabic layout will generate different events even though they are the
- same physical key. To identify these events as coming from the same
- physical key, you will need to make use of the {{KeyboardEvent/code}}
- attribute.
-
-
- In some cases, modifier keys change the {{KeyboardEvent/key}}
- value for a key event. For example, on some MacOS keyboards, the key
- labeled "delete" functions the same as the KEYCAP{Backspace} key on the
- Windows OS when unmodified, but when modified by the KEYCAP{Fn} key,
- acts as the KEYCAP{Delete} key, and the value of {{KeyboardEvent/key}}
- will match the most appropriate function of the key in its current
- modified state.
-
-
Dead keys
-
- Some keyboard input uses dead keys for the input of composed
- character sequences. Unlike the handwriting sequence, in which users
- enter the base character first, keyboard input requires to enter a
- special state when a dead key is pressed and emit the
- character(s) only when one of a limited number of legal base
- character is entered.
-
-
- The MacOS and Linux operating systems use input methods to process
- dead keys.
-
-
- The dead keys (across all keyboard layouts and mappings) are
- represented by the key value KEYCAP{Dead}. In response to any dead key
- press, composition events must
- be dispatched by the user agent and the EVENT{compositionupdate} event's
- {{CompositionEvent/data}} value must be the character value of the
- current state of the dead key combining sequence.
-
- While Unicode combining characters always follow the handwriting
- sequence, with the combining character trailing the corresponding
- letter, typical dead key input MAY reverse the sequence, with the
- combining character before the corresponding letter. For example, the
- word naïve, using the combining diacritic ¨, would be
- represented sequentially in Unicode as nai¨ve, but MAY be typed
- na¨ive. The sequence of keystrokes UNI{U+0302} (Combining
- Circumflex Accent key) and UNI{U+0065} (key marked with the Latin Small
- Letter E) will likely produce (on a French keyboard using a french
- mapping and without any modifier activated) the Unicode character
- GLYPH{ê} (Latin Small Letter E With Circumflex), as preferred by
- the Unicode Normalization Form NFC.
-
-
- In the second EVENT{keydown} event (step 5), the key value (assuming the
- event is not suppressed) will not be KEY_NOLINK{e} (Latin Small
- Letter E key) under normal circumstances because the value delivered to
- the user agent will already be modified by the dead key operation.
-
-
- This process might be aborted when a user types an unsupported base
- character (that is, a base character for which the active
- diacritical mark is not available) after pressing a dead key:
-
-
-
- This specification includes a model for input method editors
- (IMEs), through the {{CompositionEvent}} interface and events.
- However, Composition Events and Keyboard Events do not necessarily map
- as a one-to-one relationship. As an example, receiving a EVENT{keydown}
- for the KEYCAP{Accept} key value does not necessarily imply that the
- text currently selected in the IME is being accepted, but
- indicates only that a keystroke happened, disconnected from the
- IME Accept functionality (which would normally result in a
- EVENT{compositionend} event in most IME systems). Keyboard
- events cannot be used to determine the current state of the input method
- editor, which can be obtained through the {{CompositionEvent/data}}
- attribute of the {{CompositionEvent}} interface. Additionally,
- IME systems and devices vary in their functionality, and in which
- keys are used for activating that functionality, such that the
- KEYCAP{Convert} and KEYCAP{Accept} keys MAY be represented by other
- available keys. Keyboard events correspond to the events generated by
- the input device after the keyboard layout mapping.
-
-
- In some implementations or system configurations, some key events, or
- their values, might be suppressed by the IME in use.
-
-
- The following example describes a possible sequence of keys to generate
- the Unicode character GLYPH{市} (Kanji character, part of CJK
- Unified Ideographs) using Japanese input methods. This example assumes
- that the input method editor is activated and in the Japanese-Romaji
- input mode. The keys KEYCAP{Convert} and KEYCAP{Accept} MAY be replaced
- by others depending on the input device in use and the configuration of
- the IME, e.g., it can be respectively UNI{U+0020} (Space key) and
- KEYCAP{Enter}.
-
-
- GLYPH{詩} (poem) and GLYPH{市} (city) are
- homophones, both pronounced し (shi/si), so the user
- needs to use the KEYCAP{Convert} key to select the proper option.
-
-
- IME composition can also be canceled as in the following example, with
- conditions identical to the previous example. The key KEYCAP{Cancel}
- might also be replaced by others depending on the input device in use
- and the configuration of the IME, e.g., it could be UNI{U+001B} (Escape
- key).
-
-
- Some input method editors (such as on the MacOS operating system)
- might set an empty string to the composition data attribute
- before canceling a composition.
-
-
-
Input Method Editor mode keys
-
- Some keys on certain devices are intended to activate input
- method editor functionality, or to change the mode of an active
- input method editor. Custom keys for this purpose can be
- defined for different devices or language modes. The keys defined in
- this specification for this purpose are: KEY{Alphanumeric},
- KEY{CodeInput}, KEY{FinalMode}, KEY{HangulMode}, KEY{HanjaMode},
- KEY{Hiragana}, KEY{JunjaMode}, KEY{KanaMode}, KEY{KanjiMode},
- KEY{Katakana}, and KEY{Romaji}. When one of these keys is
- pressed, and no IME is currently active, the appropriate
- IME is expected to be activated in the mode indicated by the
- key (if available). If an IME is already active when the key
- is pressed, the active IME might change to the indicated
- mode, or a different IME might be launched, or the might MAY
- be ignored, on a device- and application-specific basis.
-
- This specification also defines other keys which are intended for
- operation specifically with input method editors:
- KEY{Accept}, KEY{AllCandidates}, KEY{Cancel}, KEY{Convert},
- KEY{Compose}, KEY{Zenkaku} (FullWidth), KEY{Hankaku} (HalfWidth), KEY{NextCandidate},
- KEY{NonConvert}, and KEY{PreviousCandidate}. The functions of these
- keys are not defined in this specification — refer to other
- resources for details on input method editor functionality.
-
-
- Keys with input method editor functions are not restricted to
- that purpose, and can have other device- or implementation-specific
- purposes.
-
-
-
Default actions and cancelable keyboard events
-
- Canceling the default action of a EVENT{keydown} event MUST NOT
- affect its respective EVENT{keyup} event, but it MUST prevent the
- respective EVENT{beforeinput} and EVENT{input} (and EVENT{keypress} if
- supported) events from being generated. The following example describes
- a possible sequence of keys to generate the Unicode character Q (Latin
- Capital Letter Q) on a US keyboard using a US mapping:
-
-
-
- If the key is a modifier key, the keystroke MUST still be taken into
- account for the modifiers states. The following example describes a
- possible sequence of keys to generate the Unicode character Q (Latin
- Capital Letter Q) on a US keyboard using a US mapping:
-
-
-
- If the key is part of a sequence of several keystrokes, whether it is a
- dead key or it is contributing to an Input Method Editor
- sequence, the keystroke MUST be ignored (not taken into account) only if
- the default action is canceled on the EVENT{keydown} event.
- Canceling a dead key on a EVENT{keyup} event has no effect on
- EVENT{beforeinput} or EVENT{input} events. The following example uses
- the dead key KEY{Dead} (UNI{U+0302} Combining Circumflex Accent key) and
- KEY_NOLINK{e} (UNI{U+0065}, Latin Small Letter E key) on a French
- keyboard using a French mapping and without any modifier activated:
-
-
-
- Generally, when a constructor of an {{Event}} interface, or of an interface
- inherited from the {{Event}} interface, is invoked, the steps described in
- [[!DOM]] should be followed. However the {{KeyboardEvent}} and
- {{MouseEvent}} interfaces provide additional dictionary members for
- initializing the internal state of the {{Event}} object's key modifiers:
- specifically, the internal state queried for using the
- {{KeyboardEvent/getModifierState()}} and {{MouseEvent/getModifierState()}}
- methods. This section supplements the DOM4 steps for intializing a new
- {{Event}} object with these optional modifier states.
-
- For the purposes of constructing a {{KeyboardEvent}}, {{MouseEvent}}, or
- object derived from these objects using the algorithm below, all
- {{KeyboardEvent}}, {{MouseEvent}}, and derived objects have
- internal key modifier state which can be set and
- retrieved using the key modifier names
- described in the
- Modifier Keys table
- in [[UIEvents-Key]].
-
- The following steps supplement the algorithm defined for constructing
- events in DOM4:
-
- * If the {{Event}} being constructed is a {{KeyboardEvent}} or
- {{MouseEvent}} object or an object that derives from either of these,
- and a {{EventModifierInit}} argument was provided to the constructor,
- then run the following sub-steps:
-
- * For each {{EventModifierInit}} argument, if the dictionary member
- begins with the string "modifier", then let the
- key modifier name be the
- dictionary member's name excluding the prefix
- "modifier", and set the {{Event}} object's
- internal key modifier state
- that matches the key modifier name
- to the corresponding value.
-
-
Legacy {{KeyboardEvent}} events
-
- The EVENT{keypress} event is the traditional method for capturing key events
- and processing them before the DOM is updated with the effects of the key
- press. Code that makes use of the EVENT{keypress} event typically relies on
- the legacy {{KeyboardEvent/charCode}}, {{KeyboardEvent/keyCode}}, and
- {{UIEvent/which}} attributes.
-
- Note that the EVENT{keypress} event is specific to key events, and has been
- replaced by the more general event sequence of EVENT{beforeinput} and
- EVENT{input} events. These new input events are not specific to
- keyboard actions and can be used to capture user input regardless of the
- original source.
-
-
Legacy {{KeyboardEvent}} event types
-
-
keypress
-
-
-
-
Type
-
keypress
-
-
-
Interface
-
{{KeyboardEvent}}
-
-
-
Sync / Async
-
Sync
-
-
-
Bubbles
-
Yes
-
-
-
Trusted Targets
-
Element
-
-
-
Cancelable
-
Yes
-
-
-
Composed
-
Yes
-
-
-
Default action
-
Varies:
- launch text composition system;
- EVENT{blur} and EVENT{focus} events;
- EVENT{DOMActivate} event;
- other event
-
-
-
Context (trusted events)
-
-
-
{{Event}}.{{Event/target}} :
- focused element processing the key event or if no element focused, then the
- body element if available, otherwise the
- root element
{{KeyboardEvent}}.{{KeyboardEvent/isComposing}} :
- true if the key event occurs as part of a composition session, otherwise false
-
-
-
-
-
- If supported by a user agent, this event MUST be dispatched
- when a key is pressed down, if and only if that key normally
- produces a character value. The EVENT{keypress} event type is
- device dependent and relies on the capabilities of the input devices
- and how they are mapped in the operating system.
-
- This event type MUST be generated after the key mapping. It
- MUST NOT be fired when using an input method editor.
-
- If this event is canceled, it should prevent the EVENT{input} event
- from firing, in addition to canceling the default action.
-
- Authors SHOULD use the EVENT{beforeinput} event instead of the
- EVENT{keypress} event.
-
-
- The EVENT{keypress} event is traditionally associated with detecting
- a character value rather than a physical key, and might not
- be available on all keys in some configurations.
-
-
-
- The EVENT{keypress} event type is defined in this specification for
- reference and completeness, but this specification deprecates
- the use of this event type. When in editing contexts, authors can
- subscribe to the EVENT{beforeinput} event instead.
-
-
-
EVENT{keypress} event order
-
- The EVENT{keypress} event type MUST be dispatched after the
- EVENT{keydown} event and before the EVENT{keyup} event associated with
- the same key.
-
- The EVENT{keypress} event type MUST be dispatched after the
- EVENT{beforeinput} event and before the EVENT{input} event associated
- with the same key.
-
- The sequence of key events for user-agents the support the
- EVENT{keypress} event is demonstrated in the following example:
-
-
-
- This section is normative.
-
- The following features are obsolete and should only be implemented by
- user agents that require compatibility with legacy software.
-
- Early versions of this specification included an initialization method on
- the interface (for example initMouseEvent) that required a long
- list of parameters that, in most cases, did not fully initialize all
- attributes of the event object. Because of this, event interfaces which were
- derived from the basic {{Event}} interface required that the initializer of
- each of the derived interfaces be called explicitly in order to
- fully initialize an event.
-
-
- Initializing all the attributes of a MutationEvent requires calls to two
- initializer methods: initEvent and
- initMutationEvent.
-
-
- Due in part to the length of time in the development of this standard, some
- implementations MAY have taken a dependency on these (now deprecated)
- initializer methods. For completeness, these legacy event initializers are
- described in this section.
-
-
Initializers for interface KeyboardEvent
-
- This section is informative
-
-
- The argument list to this legacy KeyboardEvent initializer does not
- include the detailArg (present in other initializers) and
- adds the locale argument (see [[#changes-drafts]]); it is
- necessary to preserve this inconsistency for compatibility with existing
- implementations.
-
- Initializes attributes of a {{KeyboardEvent}} object. This
- method has the same behavior as UIEvent.initUIEvent().
- The value of {{UIEvent/detail}} remains undefined.
-
-
- The initKeyboardEvent method is deprecated.
-
-
-
-
DOMString typeArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
boolean bubblesArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
boolean cancelableArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
Window? viewArg
-
- Specifies {{UIEvent/view}}. This value MAY be null.
-
-
-
DOMString keyArg
-
- Specifies {{KeyboardEvent/key}}.
-
-
-
unsigned long locationArg
-
- Specifies {{KeyboardEvent/location}}.
-
-
-
boolean ctrlKey
-
- Specifies whether the Control key modifier is active.
-
-
-
boolean altKey
-
- Specifies whether the Alt key modifier is active.
-
-
-
boolean shiftKey
-
- Specifies whether the Shift key modifier is active.
-
-
-
boolean metaKey
-
- Specifies whether the Meta key modifier is active.
-
-
-
-
-
-
Legacy Key & Mouse Event Attributes
-
- This section is non-normative. The following attributes are obsolete and should
- only be implemented by user agents that require compatibility with legacy
- software that requires these keyboard events.
-
- These features were never formally specified and the current browser
- implementations vary in significant ways.
-
-
Legacy {{KeyboardEvent}} supplemental interface
-
- This section is non-normative
-
- Browser support for keyboards has traditionally relied on three ad-hoc
- attributes, {{KeyboardEvent/keyCode}}, {{KeyboardEvent/charCode}}, and
- {{UIEvent}}'s {{UIEvent/which}}.
-
- All three of these attributes return a numerical code that represents some
- aspect of the key pressed: {{KeyboardEvent/keyCode}} is an index of the key
- itself. {{KeyboardEvent/charCode}} is the ASCII value of the character keys.
- {{UIEvent/which}} is the character value where available and otherwise
- the key index. The values for these attributes, and the availability of the
- attribute, is inconsistent across platforms, keyboard languages and layouts,
- user agents, versions, and even event types.
-
-
Interface KeyboardEvent (supplemental)
-
- The partial {{KeyboardEvent}} interface is an informative extension of
- the {{KeyboardEvent}} interface, which adds the
- {{KeyboardEvent/charCode}} and {{KeyboardEvent/keyCode}} attributes.
-
- The partial {{KeyboardEvent}} interface can be obtained by using the
- {{Document/createEvent()}} method call in
- implementations that support this extension.
-
-
- partial interface KeyboardEvent {
- // The following support legacy user agents
- readonly attribute unsigned long charCode;
- readonly attribute unsigned long keyCode;
- };
-
-
-
-
charCode
-
- {{KeyboardEvent/charCode}} holds a character value, for
- EVENT{keypress} events which generate character input. The value
- is the Unicode reference number (code point) of that character
- (e.g. event.charCode = event.key.charCodeAt(0) for
- printable characters). For EVENT{keydown} or EVENT{keyup}
- events, the value of {{KeyboardEvent/charCode}} is
- 0.
-
-
-
keyCode
-
- {{KeyboardEvent/keyCode}} holds a system- and
- implementation-dependent numerical code signifying the
- unmodified identifier associated with the key pressed. Unlike
- the {{KeyboardEvent/key}} attribute, the set of possible values
- are not normatively defined in this specification. Typically,
- these value of the {{KeyboardEvent/keyCode}} SHOULD represent
- the decimal codepoint in ASCII [[RFC20]][[US-ASCII]] or Windows
- 1252 [[WIN1252]], but MAY be drawn from a different appropriate
- character set. Implementations that are unable to identify a key
- use the key value KEYCAP{0}.
-
- See [[#legacy-key-models]] for more details on how to determine
- the values for {{KeyboardEvent/keyCode}}.
-
-
-
-
Interface KeyboardEventInit (supplemental)
-
- Browsers that include support for {{KeyboardEvent/keyCode}}
- and {{KeyboardEvent/charCode}} in
- {{KeyboardEvent}} should also add the following members to the
- {{KeyboardEventInit}} dictionary.
-
- The partial {{KeyboardEventInit}} dictionary is an informative extension
- of the {{KeyboardEventInit}} dictionary, which adds
- {{KeyboardEvent/charCode}} and {{KeyboardEvent/keyCode}}
- members to initialize the corresponding
- {{KeyboardEvent}} attributes.
-
-
- partial dictionary KeyboardEventInit {
- // The following support legacy user agents
- unsigned long charCode = 0;
- unsigned long keyCode = 0;
- };
-
-
-
-
charCode
-
- Initializes the {{KeyboardEvent/charCode}} attribute of the
- {{KeyboardEvent}} to the Unicode code point for the event's
- character.
-
-
-
keyCode
-
- Initializes the {{KeyboardEvent/keyCode}} attribute of the
- {{KeyboardEvent}} to the system- and implementation-dependent
- numerical code signifying the unmodified identifier associated
- with the key pressed.
-
-
-
-
Legacy key models
-
- This section is non-normative
-
- Implementations differ on which values are exposed on these attributes for
- different event types. An implementation MAY choose to expose both virtual
- key codes and character codes in the {{KeyboardEvent/keyCode}} property
- (conflated model), or report separate {{KeyboardEvent/keyCode}} and
- {{KeyboardEvent/charCode}} properties (split model).
-
-
How to determine {{KeyboardEvent/keyCode}} for EVENT{keydown} and EVENT{keyup} events
-
- The {{KeyboardEvent/keyCode}} for EVENT{keydown} or EVENT{keyup} events
- is calculated as follows:
-
- * Read the virtual key code from the operating system's event
- information, if such information is available.
-
- * If an Input Method Editor is processing key input and the event is
- EVENT{keydown}, return 229.
-
- * If input key when pressed without modifiers would insert a numerical
- character (0-9), return the ASCII code of that numerical character.
-
- * If input key when pressed without modifiers would insert a lower
- case character in the a-z alphabetical range, return the ASCII code
- of the upper case equivalent.
-
- * If the implementation supports a key code conversion table for the
- operating system and platform, look up the value. If the conversion
- table specifies an alternate virtual key value for the given input,
- return the specified value.
-
- * If the key's function, as determined in an implementation-specific
- way, corresponds to one of the keys in the
- [[#fixed-virtual-key-codes]] table, return the corresponding key
- code.
-
- * Return the virtual key code from the operating system.
-
- * If no key code was found, return 0.
-
-
How to determine {{KeyboardEvent/keyCode}} for EVENT{keypress} events
-
- The {{KeyboardEvent/keyCode}} for EVENT{keypress} events is calculated
- as follows:
-
- * If the implementation supports a conflated model, set
- {{KeyboardEvent/keyCode}} to the Unicode code point of the character
- being entered.
-
- * If the implementation supports a split model, set
- {{KeyboardEvent/keyCode}} to 0.
-
-
-
- This section is normative. The following event types are obsolete and should
- only be implemented by user agents that require compatibility with legacy
- software.
-
-
Legacy {{KeyboardEvent}} events
-
- The EVENT{keypress} event is the traditional method for capturing key events
- and processing them before the DOM is updated with the effects of the key
- press. Code that makes use of the EVENT{keypress} event typically relies on
- the legacy {{KeyboardEvent/charCode}}, {{KeyboardEvent/keyCode}}, and
- {{UIEvent/which}} attributes.
-
- Note that the EVENT{keypress} event is specific to key events, and has been
- replaced by the more general event sequence of EVENT{beforeinput} and
- EVENT{input} events. These new input events are not specific to
- keyboard actions and can be used to capture user input regardless of the
- original source.
-
-
Legacy {{KeyboardEvent}} event types
-
-
keypress
-
-
-
-
Type
-
keypress
-
-
-
Interface
-
{{KeyboardEvent}}
-
-
-
Sync / Async
-
Sync
-
-
-
Bubbles
-
Yes
-
-
-
Trusted Targets
-
Element
-
-
-
Cancelable
-
Yes
-
-
-
Composed
-
Yes
-
-
-
Default action
-
Varies:
- launch text composition system;
- EVENT{blur} and EVENT{focus} events;
- EVENT{DOMActivate} event;
- other event
-
-
-
Context (trusted events)
-
-
-
{{Event}}.{{Event/target}} :
- focused element processing the key event or if no element focused, then the
- body element if available, otherwise the
- root element
{{KeyboardEvent}}.{{KeyboardEvent/isComposing}} :
- true if the key event occurs as part of a composition session, otherwise false
-
-
-
-
-
- If supported by a user agent, this event MUST be dispatched
- when a key is pressed down, if and only if that key normally
- produces a character value. The EVENT{keypress} event type is
- device dependent and relies on the capabilities of the input devices
- and how they are mapped in the operating system.
-
- This event type MUST be generated after the key mapping. It
- MUST NOT be fired when using an input method editor.
-
- If this event is canceled, it should prevent the EVENT{input} event
- from firing, in addition to canceling the default action.
-
- Authors SHOULD use the EVENT{beforeinput} event instead of the
- EVENT{keypress} event.
-
-
- The EVENT{keypress} event is traditionally associated with detecting
- a character value rather than a physical key, and might not
- be available on all keys in some configurations.
-
-
-
- The EVENT{keypress} event type is defined in this specification for
- reference and completeness, but this specification deprecates
- the use of this event type. When in editing contexts, authors can
- subscribe to the EVENT{beforeinput} event instead.
-
-
-
EVENT{keypress} event order
-
- The EVENT{keypress} event type MUST be dispatched after the
- EVENT{keydown} event and before the EVENT{keyup} event associated with
- the same key.
-
- The EVENT{keypress} event type MUST be dispatched after the
- EVENT{beforeinput} event and before the EVENT{input} event associated
- with the same key.
-
- The sequence of key events for user-agents the support the
- EVENT{keypress} event is demonstrated in the following example:
-
-
-
- TODO - Add specific concerns for this spec
-
-
Acknowledgements
-
- TODO
-
-
Refs to other UIEvent specs \[DELETE]
-
- This section will be deleted.
-
- Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
- beforeinput
- blur
- click
- compositionend
- compositionstart
- compositionupdate
- DOMActivate
- input
-
-
Things defined in other sections
-
-
Activation triggers and behavior
-
Default actions and cancelable events
-
Event dispatch and DOM event flow
-
Focus Events
-
Web browsers and other dynamic or interactive user agents
-
Authoring tools
-
-
Things defined in CompositionEvents
-
Composition Events
-
-
Things defined in Changes
-
Changes between different drafts of UI Events
-
-
Glossary \[DELETE]
-
-This section will be deleted.
-
-Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-: activation behavior
-:: The action taken when an event, typically initiated by users through
- an input device, causes an element to fulfill a defined task. The task MAY
- be defined for that element by the host language, or by
- author-defined variables, or both. The default task for any given element
- MAY be a generic action, or MAY be unique to that element. For example, the
- activation behavior of an HTML or SVG <a> element is to
- cause the user agent to traverse the link specified in the
- href attribute, with the further optional parameter of
- specifying the browsing context for the traversal (such as the current
- window or tab, a named window, or a new window). The activation behavior of
- an HTML <input> element with the type
- attribute value submit is be to send the values of the form
- elements to an author-defined IRI by the author-defined HTTP method. See
- [[#event-flow-activation]] for more details.
-
-: activation trigger
-:: An event which is defined to initiate an activation behavior. Refer
- to [[#event-flow-activation]] for more details.
-
-: body element
-:: In HTML or XHTML documents, the body element represents the contents of the
- document. In a well-formed HTML document, the body element is a first
- descendant of the root element.
-
-: character value
-:: In the context of key values, a character value is a string representing one
- or more Unicode characters, such as a letter or symbol, or a set of letters, each
- belonging to the set of valid Unicode character categories.
- In this specification, character values are denoted as a unicode string
- (e.g., UNI{U+0020}) or a glyph representation of the same code point (e.g.,
- GLYPH{ }), and are color coded to help distinguish these two representations.
-
-
- In source code, some key values, such as non-graphic characters, can be
- represented using the character escape syntax of the programming language in
- use.
-
-
-: dead key
-:: A dead key is a key or combination of keys which produces no character by
- itself, but which in combination or sequence with another key produces a
- modified character, such as a character with diacritical marks (e.g.,
- GLYPH{ö}, GLYPH{é}, GLYPH{â}).
-
-: default action
-:: A default action is an OPTIONAL supplementary behavior that an
- implementation MUST perform in combination with the dispatch of the event
- object. Each event type definition, and each specification, defines the
- default action for that event type, if it has one. An instance of an
- event MAY have more than one default action under some circumstances,
- such as when associated with an activation trigger. A default
- action MAY be cancelled through the invocation of the
- {{Event/preventDefault()}} method. For more details, see
- [[#event-flow-default-cancel]].
-
-: deprecated
-:: Features marked as deprecated are included in the specification as reference
- to older implementations or specifications, but are OPTIONAL and
- discouraged. Only features which have existing or in-progress replacements
- MUST be deprecated in this specification. Implementations which do not
- already include support for the feature MAY implement deprecated features
- for reasons of backwards compatibility with existing content, but content
- authors creating content SHOULD NOT use deprecated features, unless there is
- no other way to solve a use case. Other specifications which reference this
- specification SHOULD NOT use deprecated features, but SHOULD point instead
- to the replacements of which the feature is deprecated in favor. Features
- marked as deprecated in this specification are expected to be dropped from
- future specifications.
-
-: empty string
-:: The empty string is a value of type DOMString of length
- 0, i.e., a string which contains no characters (neither
- printing nor control characters).
-
-: event
-:: An event is the representation of some occurrence (such as a mouse click on
- the presentation of an element, the removal of child node from an element,
- or any number of other possibilities) which is associated with its event
- target. Each event is an instantiation of one specific event
- type.
-
-: event target
-:: The object to which an event is targeted using the [[#event-flow]].
- The event target is the value of the {{Event/target}} attribute.
-
-: host language
-:: Any language which integrates the features of another language or API
- specification, while normatively referencing the origin specification rather
- than redefining those features, and extending those features only in ways
- defined by the origin specification. An origin specification typically is
- only intended to be implemented in the context of one or more host
- languages, not as a standalone language. For example, XHTML, HTML, and SVG
- are host languages for UI Events, and they integrate and extend the objects
- and models defined in this specification.
-
-: IME
-: input method editor
-:: An input method editor (IME), also known as a front end
- processor, is an application that performs the conversion between
- keystrokes and ideographs or other characters, usually by user-guided
- dictionary lookup, often used in East Asian languages (e.g., Chinese,
- Japanese, Korean). An IME MAY also be used for dictionary-based word
- completion, such as on mobile devices. See [[#keys-IME]] for treatment of
- IMEs in this specification. See also text composition system.
-
-: key mapping
-:: Key mapping is the process of assigning a key value to a particular key, and
- is the result of a combination of several factors, including the operating
- system and the keyboard layout (e.g., QWERTY, Dvorak, Spanish,
- InScript, Chinese, etc.), and after taking into account all modifier
- key (KEYCAP{Shift}, KEYCAP{Alt}, et al.) and dead key states.
-
-: key value
-:: A key value is a character value or multi-character string (such as
- KEY{Enter}, KEY{Tab}, or KEY{MediaTrackNext}) associated with a key in a
- particular state. Every key has a key value, whether or not it has a
- character value. This includes control keys, function keys,
- modifier keys, dead keys, and any other key. The key value of
- any given key at any given time depends upon the key mapping.
-
-: modifier key
-:: A modifier key changes the normal behavior of a key, such as to produce a
- character of a different case (as with the KEYCAP{Shift} key), or to alter
- what functionality the key triggers (as with the KEYCAP{Fn} or KEYCAP{Alt}
- keys). See [[#keys-modifiers]] for more information about modifier keys and
- refer to the [=Modifier Keys table=] in [[UIEvents-Key]] for a list
- of valid modifier keys.
-
-: QWERTY
-:: QWERTY (pronounced ˈkwɜrti) is a common keyboard layout,
- so named because the first five character keys on the top row of letter keys
- are Q, W, E, R, T, and Y. There are many other popular keyboard layouts
- (including the Dvorak and Colemak layouts), most designed for localization
- or ergonomics.
-
-: text composition system
-:: A software component that interprets some form of alternate input (such as a
- input method editor, a speech processor, or a handwriting recognition
- system) and converts it to text.
-
-: Unicode character categories
-:: A subset of the General Category values that are defined for each Unicode
- code point. This subset contains all the
- Letter (Ll,
- Lm,
- Lo,
- Lt,
- Lu),
- Number (Nd,
- Nl,
- No),
- Punctuation (Pc,
- Pd,
- Pe,
- Pf,
- Pi,
- Po,
- Ps)
- and Symbol (Sc,
- Sk,
- Sm,
- So)
- category values.
-
-: un-initialized value
-:: The value of any event attribute (such as {{Event/bubbles}} or
- {{Event/currentTarget}}) before the event has been initialized with
- {{Event/initEvent()}}. The un-initialized values of an event apply
- immediately after a new event has been created using the method
- {{Document/createEvent()}}.
-
-: user agent
-:: A program, such as a browser or content authoring tool, normally running on
- a client machine, which acts on a user's behalf in retrieving, interpreting,
- executing, presenting, or creating content. Users MAY act on the content
- using different user agents at different times, for different purposes. See
- the [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the
- requirements for a conforming user agent.
-
-: Window
-:: The Window is the object referred to by the current document's
- browsing context's Window Proxy object as defined in
- HTML5
- [[HTML5]].
-
diff --git a/split/mouse-events.bs b/split/mouse-events.bs
deleted file mode 100644
index 5755770..0000000
--- a/split/mouse-events.bs
+++ /dev/null
@@ -1,1555 +0,0 @@
-
Mouse Events
-
-
-Shortname: mouse-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
- *** Mouse Events ***
-
- Note: This is an experimental split of the UI Events spec into smaller, event-specific
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
- interface Example {
- // This is an IDL definition.
- };
-
-
-
Mouse Events
-
- The mouse event module originates from the [[HTML401]] onclick,
- ondblclick, onmousedown, onmouseup,
- onmouseover, onmousemove, and
- onmouseout attributes. This event module is specifically
- designed for use with pointing input devices, such as a mouse or a trackball.
-
-
Interface MouseEvent
-
-
Introduced in DOM Level 2, modified in this
- specification
-
-
- The {{MouseEvent}} interface provides specific contextual information
- associated with Mouse events.
-
- In the case of nested elements, mouse events are always targeted at the
- most deeply nested element.
-
-
- Ancestors of the targeted element can use event bubbling to obtain
- notifications of mouse events which occur within their descendent
- elements.
-
-
- To create an instance of the {{MouseEvent}} interface, use the
- {{MouseEvent}} constructor, passing an optional {{MouseEventInit}}
- dictionary.
-
-
- When initializing {{MouseEvent}} objects using initMouseEvent,
- implementations can use the client coordinates {{MouseEvent/clientX}}
- and {{MouseEvent/clientY}} for calculation of other coordinates (such
- as target coordinates exposed by DOM Level 0 implementations or
- other proprietary attributes, e.g., pageX).
-
- 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.
-
- 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.
-
- During any mouse events, {{MouseEvent/buttons}} MUST be used to
- indicate which combination of mouse buttons are currently being
- pressed, expressed as a bitmask.
-
-
- Though similarly named, the values for the
- {{MouseEvent/buttons}} attribute and the {{MouseEvent/button}}
- attribute are very different. The value of {{MouseEvent/button}}
- is assumed to be valid during mousedown / mouseup
- event handlers, whereas the {{MouseEvent/buttons}} attribute
- reflects the state of the mouse's buttons for any trusted
- {{MouseEvent}} object (while it is being dispatched), because it
- can represent the "no button currently active" state (0).
-
-
- The value of the {{MouseEvent/buttons}}
- attribute MUST be as follows:
-
- * 0 MUST indicate no button is currently active.
- * 1 MUST indicate the primary button of the device
- (in general, the left button or the only button on single-button devices,
- used to activate a user interface control or select text).
- * 2 MUST indicate the secondary button
- (in general, the right button, often used to display a context menu), if present.
- * 4 MUST indicate the auxiliary button
- (in general, the middle button, often combined with a mouse wheel).
-
- Some pointing devices provide or simulate more buttons. To
- represent such buttons, the value MUST be doubled for each
- successive button (in the binary series 8,
- 16, 32, ... ).
-
-
- Because the sum of any set of button values is a unique number,
- a content author can use a bitwise operation to determine how
- many buttons are currently being pressed and which buttons they
- are, for an arbitrary number of mouse buttons on a device. For
- example, the value 3 indicates that the left and
- right button are currently both pressed, while the value
- 5 indicates that the left and middle button are
- currently both pressed.
-
-
- 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.
-
-
- Initializes the ctrlKey attribute of the
- {{MouseEvent}} or {{KeyboardEvent}}
- objects to true if the Control
- key modifier is to be considered active,
- false otherwise.
-
- When true, implementations must also initialize the event object's key modifier
- state such that calls to the
- {{MouseEvent/getModifierState()}} or
- {{KeyboardEvent/getModifierState()}}
- when provided with the parameter Control
- must return true.
-
-
-
shiftKey
-
- Initializes the shiftKey attribute of the
- {{MouseEvent}} or {{KeyboardEvent}}
- objects to true if the Shift
- key modifier is to be considered active, false otherwise.
-
- When true, implementations must also initialize the event object's key modifier
- state such that calls to the
- {{MouseEvent/getModifierState()}} or
- {{KeyboardEvent/getModifierState()}}
- when provided with the parameter Shift must
- return true.
-
-
-
altKey
-
- Initializes the altKey attribute of the
- {{MouseEvent}} or {{KeyboardEvent}}
- objects to true if the Alt
- (alternative) (or Option) key modifier
- is to be considered active, false otherwise.
-
- When true, implementations must also initialize the event object's key modifier
- state such that calls to the
- {{MouseEvent/getModifierState()}} or
- {{KeyboardEvent/getModifierState()}}
- when provided with the parameter Alt must
- return true.
-
-
-
metaKey
-
- Initializes the metaKey attribute of the
- {{MouseEvent}} or {{KeyboardEvent}}
- objects to true if the Meta
- key modifier is to be considered active, false otherwise.
-
- When true, implementations must also initialize the event object's
- key modifier state such that calls to the
- {{MouseEvent/getModifierState()}} or
- {{KeyboardEvent/getModifierState()}}
- when provided with either the parameter Meta
- must return true.
-
-
-
modifierAltGraph
-
- Initializes the event object's key modifier state such that calls to the
- {{MouseEvent/getModifierState()}} or
- {{KeyboardEvent/getModifierState()}}
- when provided with the parameter AltGraph must
- return true.
-
-
-
modifierCapsLock
-
- Initializes the event object's key modifier state such that calls to the
- {{MouseEvent/getModifierState()}} or
- {{KeyboardEvent/getModifierState()}}
- when provided with the parameter CapsLock must
- return true.
-
-
-
modifierFn
-
- Initializes the event object's key modifier state such that calls to the
- {{MouseEvent/getModifierState()}} or
- {{KeyboardEvent/getModifierState()}}
- when provided with the parameter Fn must
- return true.
-
-
-
modifierFnLock
-
- Initializes the event object's key modifier state such that calls to the
- {{MouseEvent/getModifierState()}} or
- {{KeyboardEvent/getModifierState()}}
- when provided with the parameter FnLock must
- return true.
-
-
-
modifierHyper
-
- Initializes the event object's key modifier state such that calls to the
- {{MouseEvent/getModifierState()}} or
- {{KeyboardEvent/getModifierState()}}
- when provided with the parameter Hyper must
- return true.
-
-
-
modifierNumLock
-
- Initializes the event object's key modifier state such that calls to the
- {{MouseEvent/getModifierState()}} or
- {{KeyboardEvent/getModifierState()}}
- when provided with the parameter NumLock must
- return true.
-
-
-
modifierScrollLock
-
- Initializes the event object's key modifier state such that calls to the
- {{MouseEvent/getModifierState()}} or
- {{KeyboardEvent/getModifierState()}}
- when provided with the parameter ScrollLock must
- return true.
-
-
-
modifierSuper
-
- Initializes the event object's key modifier state such that calls to the
- {{MouseEvent/getModifierState()}} or
- {{KeyboardEvent/getModifierState()}}
- when provided with the parameter Super must
- return true.
-
-
-
modifierSymbol
-
- Initializes the event object's key modifier state such that calls to the
- {{MouseEvent/getModifierState()}} or
- {{KeyboardEvent/getModifierState()}}
- when provided with the parameter Symbol must
- return true.
-
-
-
modifierSymbolLock
-
- Initializes the event object's key modifier state such that calls to the
- {{MouseEvent/getModifierState()}} or
- {{KeyboardEvent/getModifierState()}}
- when provided with the parameter SymbolLock must
- return true.
-
-
-
-
Mouse Event Order
-
- Certain mouse events defined in this specification MUST occur in a set
- order relative to one another. The following shows the event sequence
- that MUST occur when a pointing device's cursor is moved over an element:
-
-
-
- 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:
-
-
-
- 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, 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:
-
-
-
- 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:
-
-
- The lag time, degree, distance, and number of mousemove events
- allowed between the mousedown and mouseup events while
- still firing a click or dblclick event will be
- implementation-, device-, and platform-specific. This tolerance can aid
- users that have physical disabilities like unsteady hands when these
- users interact with a pointing device.
-
-
- Each implementation will determine the appropriate hysteresis
- tolerance, but in general SHOULD fire click and dblclick
- events when the event target of the associated mousedown and
- mouseup events is the same element with no mouseout or
- mouseleave events intervening, and SHOULD fire click and
- dblclick events on the nearest common inclusive ancestor when the
- associated mousedown and mouseup event targets are
- different.
-
-
- If a mousedown event was targeted at an HTML document's body
- element, and the corresponding mouseup event was targeted at
- the root element, then the click event will be dispatched
- to the root element, since it is the nearest common inclusive
- ancestor.
-
-
- If the event target (e.g. the target element) is removed from the
- DOM during the mouse events sequence, the remaining events of the
- sequence MUST NOT be fired on that element.
-
-
- If the target element is removed from the DOM as the result of a
- mousedown event, no events for that element will be dispatched
- for mouseup, click, or dblclick, nor any default
- activation events. However, the mouseup event will still be
- dispatched on the element that is exposed to the mouse after the removal
- of the initial target element. Similarly, if the target element is
- removed from the DOM during the dispatch of a mouseup event, the
- click and subsequent events will not be dispatched.
-
-
-
Mouse Event Types
-
- The Mouse event types are listed below. In the case of nested elements,
- mouse event types are always targeted at the most deeply nested element.
- Ancestors of the targeted element MAY use bubbling to obtain
- notification of mouse events which occur within its descendent elements.
-
-
{{UIEvent}}.{{UIEvent/detail}} : indicates the current click count; the attribute value MUST be 1 when the user begins this action and increments by 1 for each click.
{{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen
{{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen
{{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport
{{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport
{{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element
{{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element
{{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed
{{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed, 0 if no buttons pressed
For {{PointerEvent}} specific attributes, see the [[!pointerevents3]] spec.
-
-
- The auxclick event type MUST be dispatched on the topmost
- event target indicated by the pointer, when the user presses
- down and releases the non-primary pointer button, or otherwise activates
- the pointer in a manner that simulates such an action. The actuation
- method of the mouse button depends upon the pointer device and the
- environment configuration, e.g., it MAY depend on the screen
- location or the delay between the press and release of the pointing
- device button.
-
- The auxclick event should only be fired for the non-primary pointer
- buttons (i.e., when {{MouseEvent/button}} value is not 0,
- {{MouseEvent/buttons}} value is greater than 1). The primary button
- (like the left button on a standard mouse) MUST NOT fire
- auxclick events. See click for a corresponding event that
- is associated with the primary button.
-
- The auxclick event MAY be preceded by the mousedown and
- mouseup events on the same element, disregarding changes
- between other node types (e.g., text nodes). Depending upon the
- environment configuration, the auxclick event MAY be dispatched
- if one or more of the event types mouseover,
- mousemove, and mouseout occur between the press and
- release of the pointing device button.
-
- The default action of the auxclick event type varies
- based on the event target of the event and the value of the
- {{MouseEvent/button}} or {{MouseEvent/buttons}} attributes. Typical
- default actions of the auxclick event type are as follows:
-
- * If the event target has associated activation behavior,
- the default action MUST be to execute that activation
- behavior (see [[#event-flow-activation]]).
-
-
- Receiving and handling auxclick for the middle button.
-myLink.addEventListener("auxclick", function(e) {
- if (e.button === 1) {
- // This would prevent the default behavior which is for example
- // opening a new tab when middle clicking on a link.
- e.preventDefault();
- // Do something else to handle middle button click like taking
- // care of opening link or non-link buttons in new tabs in a way
- // that fits the app. Other actions like closing a tab in a tab-strip
- // which should be done on the click action can be done here too.
- }
- });
-
-
-
-
- In the case of right button, the auxclick event is dispatched after
- any contextmenu event. Note that some user agents swallow all input
- events while a context menu is being displayed, so auxclick may not be
- available to applications in such scenarios.
- See this example for more clarification.
-
-
-
- Receiving and handling auxclick for the right button
-myDiv.addEventListener("contextmenu", function(e) {
- // This call makes sure no context menu is shown
- // to interfere with page receiving the events.
- e.preventDefault();
- });
- myDiv.addEventListener("auxclick", function(e) {
- if (e.button === 2) {
- // Do something else to handle right button click like opening a
- // customized context menu inside the app.
- }
- });
-
-
{{UIEvent}}.{{UIEvent/detail}} : indicates the current click count; the attribute value MUST be 1 when the user begins this action and increments by 1 for each click.
{{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen
{{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen
{{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport
{{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport
{{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element
{{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element
{{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed
{{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed, 0 if no buttons pressed
For {{PointerEvent}} specific attributes, see the [[!pointerevents3]] spec.
-
-
- The click event type MUST be dispatched on the topmost
- event target indicated by the pointer, when the user presses
- down and releases the primary pointer button, or otherwise activates
- the pointer in a manner that simulates such an action. The actuation
- method of the mouse button depends upon the pointer device and the
- environment configuration, e.g., it MAY depend on the screen
- location or the delay between the press and release of the pointing
- device button.
-
- The click event should only be fired for the primary pointer
- button (i.e., when {{MouseEvent/button}} value is 0,
- {{MouseEvent/buttons}} value is 1). Secondary buttons
- (like the middle or right button on a standard mouse) MUST NOT fire
- click events. See auxclick for a corresponding event that
- is associated with the non-primary buttons.
-
- The click event MAY be preceded by the mousedown and
- mouseup events on the same element, disregarding changes
- between other node types (e.g., text nodes). Depending upon the
- environment configuration, the click event MAY be dispatched
- if one or more of the event types mouseover,
- mousemove, and mouseout occur between the press and
- release of the pointing device button. The click event MAY
- also be followed by the dblclick event.
-
-
- If a user mouses down on a text node child of a
- <p> element which has been styled with a large
- line-height, shifts the mouse slightly such that it is no longer
- over an area containing text but is still within the containing
- block of that <p> element (i.e., the pointer is
- between lines of the same text block, but not over the text node per
- se), then subsequently mouses up, this will likely still trigger a
- click event (if it falls within the normal temporal
- hysteresis for a click), since the user has stayed
- within the scope of the same element. Note that user-agent-generated
- mouse events are not dispatched on text nodes.
-
-
- In addition to being associated with pointer devices, the
- click event type MUST be dispatched as part of an element
- activation, as described in [[#event-flow-activation]].
-
-
- For maximum accessibility, content authors are encouraged to use the
- click event type when defining activation behavior for custom
- controls, rather than other pointing-device event types such as
- mousedown or mouseup, which are more device-specific.
- Though the click event type has its origins in pointer
- devices (e.g., a mouse), subsequent implementation enhancements have
- extended it beyond that association, and it can be considered a
- device-independent event type for element activation.
-
-
- The default action of the click event type varies
- based on the event target of the event and the value of the
- {{MouseEvent/button}} or {{MouseEvent/buttons}} attributes. Typical
- default actions of the click event type are as follows:
-
- * If the event target has associated activation behavior,
- the default action MUST be to execute that activation
- behavior (see [[#event-flow-activation]]).
-
- * If the event target is focusable, the default
- action MUST be to give that element document focus.
-
-
-
- A user agent MUST dispatch this event before invoking a context menu.
-
- When the contextmenu event is triggered by right mouse button, the
- contextmenu event MUST be dispatched after the mousedown event.
-
-
- Depending on the platform, the contextmenu event may be dispatched
- before or after the mouseup event.
-
-
- A user agent MUST dispatch this event when the primary button
- of a pointing device is clicked twice over an element. The
- definition of a double click depends on the environment
- configuration, except that the event target MUST be the same between
- mousedown, mouseup, and dblclick. This event
- type MUST be dispatched after the event type click if a click
- and double click occur simultaneously, and after the event type
- mouseup otherwise.
-
- As with the click event, the dblclick event should
- only be fired for the primary pointer button. Secondary buttons MUST
- NOT fire dblclick events.
-
-
- Canceling the click event does not affect the firing of a
- dblclick event.
-
-
- As with the click event type, the default action of
- the dblclick event type varies based on the event
- target of the event and the value of the {{MouseEvent/button}}
- or {{MouseEvent/buttons}} attributes. The typical
- default actions of the dblclick event type match those
- of the click event type.
-
-
mousedown
-
-
-
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)
{{UIEvent}}.{{UIEvent/detail}} : indicates the current click count incremented by one. For example, if no click happened before the mousedown, {{UIEvent/detail}} will contain the value 1
{{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen
{{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen
{{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport
{{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport
{{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element
{{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element
{{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed
{{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed, 0 if no buttons pressed
-
- A user agent MUST dispatch this event when a pointing device
- button is pressed over an element.
-
-
- Many implementations use the mousedown event to begin a
- variety of contextually dependent default actions. These
- default actions can be prevented if this event is canceled. Some of
- these default actions could include: beginning a drag/drop
- interaction with an image or link, starting text selection, etc.
- Additionally, some implementations provide a mouse-driven panning
- feature that is activated when the middle mouse button is pressed at
- the time the mousedown event is dispatched.
-
{{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen
{{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen
{{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport
{{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport
{{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element
{{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element
{{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/button}} : 0
{{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed, 0 if no buttons pressed
{{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the event target a pointing device is exiting, if any.
-
-
- A user agent MUST dispatch this event when a pointing device
- is moved onto the boundaries of an element or one of its descendent
- elements. A user agent MUST also dispatch this event when the
- element or one of its descendants moves to be underneath the primary
- pointing device. This event type is similar to mouseover, but
- differs in that it does not bubble, and MUST NOT be dispatched when
- the pointer device moves from an element onto the boundaries of one
- of its descendent elements.
-
-
- There are similarities between this event type and the CSS
- :hover pseudo-class [[CSS2]].
- See also the mouseleave event type.
-
{{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen
{{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen
{{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport
{{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport
{{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element
{{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element
{{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/button}} : 0
{{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed, 0 if no buttons pressed
{{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the event target a pointing device is exiting, if any.
-
-
- A user agent MUST dispatch this event when a pointing device
- is moved off of the boundaries of an element and all of its
- descendent elements. A user agent MUST also dispatch this event
- when the element or one of its descendants moves to be no longer underneath
- the primary pointing device. This event type is similar to mouseout,
- but differs in that does not bubble, and that it MUST NOT be
- dispatched until the pointing device has left the boundaries of the
- element and the boundaries of all of its children.
-
-
- There are similarities between this event type and the CSS
- :hover pseudo-class [[CSS2]].
- See also the mouseenter event type.
-
-
- A user agent MUST dispatch this event when a pointing device
- is moved while it is over an element. The frequency rate of events
- while the pointing device is moved is implementation-, device-, and
- platform-specific, but multiple consecutive mousemove events
- SHOULD be fired for sustained pointer-device movement, rather than a
- single event for each instance of mouse movement. Implementations
- are encouraged to determine the optimal frequency rate to balance
- responsiveness with performance.
-
-
- In some implementation environments, such as a browser,
- mousemove events can continue to fire if the user began a
- drag operation (e.g., a mouse button is pressed) and the pointing
- device has left the boundary of the user agent.
-
-
-
- This event was formerly specified to be non-cancelable in DOM Level
- 2 Events, but was changed to reflect existing interoperability between
- user agents.
-
{{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen
{{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen
{{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport
{{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport
{{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element
{{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element
{{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/button}} : 0
{{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed, 0 if no buttons pressed
{{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the event target a pointing device is entering, if any.
-
-
- A user agent MUST dispatch this event when a pointing device
- is moved off of the boundaries of an element or when the element is
- moved to be no longer underneath the primary pointing device.
- This event type is similar to mouseleave, but differs in that
- does bubble, and that it MUST be dispatched when the pointer device
- moves from an element onto the boundaries of one of its descendent elements.
-
-
{{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen
{{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen
{{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport
{{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport
{{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element
{{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element
{{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/button}} : 0
{{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed, 0 if no buttons pressed
{{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the event target a pointing device is entering, if any.
-
-
- A user agent MUST dispatch this event when a pointing device
- is moved onto the boundaries of an element or when the element is
- moved to be underneath the primary pointing device.
- This event type is similar to mouseenter, but differs in
- that it bubbles, and that it MUST be dispatched when the pointer device moves onto the
- boundaries of an element whose ancestor element is the event
- target for the same event listener instance.
-
-
-
- A user agent MUST dispatch this event when a pointing device
- button is released over an element.
-
-
- In some implementation environments, such as a browser, a
- mouseup event can be dispatched even if the pointing device
- has left the boundary of the user agent, e.g., if the user began a
- drag operation with a mouse button pressed.
-
-
-
Constructing Mouse and Keyboard Events
-
- Generally, when a constructor of an {{Event}} interface, or of an interface
- inherited from the {{Event}} interface, is invoked, the steps described in
- [[!DOM]] should be followed. However the {{KeyboardEvent}} and
- {{MouseEvent}} interfaces provide additional dictionary members for
- initializing the internal state of the {{Event}} object's key modifiers:
- specifically, the internal state queried for using the
- {{KeyboardEvent/getModifierState()}} and {{MouseEvent/getModifierState()}}
- methods. This section supplements the DOM4 steps for intializing a new
- {{Event}} object with these optional modifier states.
-
- For the purposes of constructing a {{KeyboardEvent}}, {{MouseEvent}}, or
- object derived from these objects using the algorithm below, all
- {{KeyboardEvent}}, {{MouseEvent}}, and derived objects have
- internal key modifier state which can be set and
- retrieved using the key modifier names
- described in the
- Modifier Keys table
- in [[UIEvents-Key]].
-
- The following steps supplement the algorithm defined for constructing
- events in DOM4:
-
- * If the {{Event}} being constructed is a {{KeyboardEvent}} or
- {{MouseEvent}} object or an object that derives from either of these,
- and a {{EventModifierInit}} argument was provided to the constructor,
- then run the following sub-steps:
-
- * For each {{EventModifierInit}} argument, if the dictionary member
- begins with the string "modifier", then let the
- key modifier name be the
- dictionary member's name excluding the prefix
- "modifier", and set the {{Event}} object's
- internal key modifier state
- that matches the key modifier name
- to the corresponding value.
-
-
Legacy Event Initializers
-
- This section is normative.
-
- The following features are obsolete and should only be implemented by
- user agents that require compatibility with legacy software.
-
- Early versions of this specification included an initialization method on
- the interface (for example initMouseEvent) that required a long
- list of parameters that, in most cases, did not fully initialize all
- attributes of the event object. Because of this, event interfaces which were
- derived from the basic {{Event}} interface required that the initializer of
- each of the derived interfaces be called explicitly in order to
- fully initialize an event.
-
-
- Initializing all the attributes of a MutationEvent requires calls to two
- initializer methods: initEvent and
- initMutationEvent.
-
-
- Due in part to the length of time in the development of this standard, some
- implementations MAY have taken a dependency on these (now deprecated)
- initializer methods. For completeness, these legacy event initializers are
- described in this section.
-
-
- Initializes attributes of a {{MouseEvent}} object. This
- method has the same behavior as UIEvent.initUIEvent().
-
-
- The initMouseEvent method is deprecated, but
- supported for backwards-compatibility with widely-deployed
- implementations.
-
-
-
-
DOMString typeArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
boolean bubblesArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
boolean cancelableArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
Window? viewArg
-
- Specifies {{UIEvent/view}}. This value MAY be null.
-
-
-
long detailArg
-
- Specifies {{UIEvent/detail}}.
-
-
-
long screenXArg
-
- Specifies {{MouseEvent/screenX}}.
-
-
-
long screenYArg
-
- Specifies {{MouseEvent/screenY}}.
-
-
-
long clientXArg
-
- Specifies {{MouseEvent/clientX}}.
-
-
-
long clientYArg
-
- Specifies {{MouseEvent/clientY}}.
-
-
-
boolean ctrlKeyArg
-
- Specifies {{MouseEvent/ctrlKey}}.
-
-
-
boolean altKeyArg
-
- Specifies {{MouseEvent/altKey}}.
-
-
-
boolean shiftKeyArg
-
- Specifies {{MouseEvent/shiftKey}}.
-
-
-
boolean metaKeyArg
-
- Specifies {{MouseEvent/metaKey}}.
-
-
-
short buttonArg
-
- Specifies {{MouseEvent/button}}.
-
-
-
EventTarget? relatedTargetArg
-
- Specifies {{MouseEvent/relatedTarget}}. This value MAY
- be null.
-
-
-
-
-
-
Security Considerations
-
- TODO - Add specific concerns for this spec
-
-
Acknowledgements
-
- TODO
-
-
Refs to other UIEvent specs \[DELETE]
-
- This section will be deleted.
-
- Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
-
Things defined in other sections
-
-
Activation triggers and behavior
-
Composition Events
-
Default actions and cancelable events
-
Event dispatch and DOM event flow
-
Web browsers and other dynamic or interactive user agents
-
Authoring tools
-
-
Things defined in KeyboardEvents
-
Modifier keys
-
-
Glossary \[DELETE]
-
-This section will be deleted.
-
-Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-: activation behavior
-:: The action taken when an event, typically initiated by users through
- an input device, causes an element to fulfill a defined task. The task MAY
- be defined for that element by the host language, or by
- author-defined variables, or both. The default task for any given element
- MAY be a generic action, or MAY be unique to that element. For example, the
- activation behavior of an HTML or SVG <a> element is to
- cause the user agent to traverse the link specified in the
- href attribute, with the further optional parameter of
- specifying the browsing context for the traversal (such as the current
- window or tab, a named window, or a new window). The activation behavior of
- an HTML <input> element with the type
- attribute value submit is be to send the values of the form
- elements to an author-defined IRI by the author-defined HTTP method. See
- [[#event-flow-activation]] for more details.
-
-: activation trigger
-:: An event which is defined to initiate an activation behavior. Refer
- to [[#event-flow-activation]] for more details.
-
-: body element
-:: In HTML or XHTML documents, the body element represents the contents of the
- document. In a well-formed HTML document, the body element is a first
- descendant of the root element.
-
-: DOM Level 0
-:: The term DOM Level 0 refers to a mix of HTML document functionalities,
- often not formally specified but traditionally supported as de facto
- standards, implemented originally by Netscape Navigator version 3.0 or
- Microsoft Internet Explorer version 3.0. In many cases, attributes or
- methods have been included for reasons of backward compatibility with DOM
- Level 0.
-
-: default action
-:: A default action is an OPTIONAL supplementary behavior that an
- implementation MUST perform in combination with the dispatch of the event
- object. Each event type definition, and each specification, defines the
- default action for that event type, if it has one. An instance of an
- event MAY have more than one default action under some circumstances,
- such as when associated with an activation trigger. A default
- action MAY be cancelled through the invocation of the
- {{Event/preventDefault()}} method. For more details, see
- [[#event-flow-default-cancel]].
-
-: event
-:: An event is the representation of some occurrence (such as a mouse click on
- the presentation of an element, the removal of child node from an element,
- or any number of other possibilities) which is associated with its event
- target. Each event is an instantiation of one specific event
- type.
-
-: event target
-:: The object to which an event is targeted using the [[#event-flow]].
- The event target is the value of the {{Event/target}} attribute.
-
-: host language
-:: Any language which integrates the features of another language or API
- specification, while normatively referencing the origin specification rather
- than redefining those features, and extending those features only in ways
- defined by the origin specification. An origin specification typically is
- only intended to be implemented in the context of one or more host
- languages, not as a standalone language. For example, XHTML, HTML, and SVG
- are host languages for UI Events, and they integrate and extend the objects
- and models defined in this specification.
-
-: hysteresis
-:: A feature of human interface design to accept input values within a certain
- range of location or time, in order to improve the user experience. For
- example, allowing for small deviation in the time it takes for a user to
- double-click a mouse button is temporal hysteresis, and not immediately
- closing a nested menu if the user mouses out from the parent window when
- transitioning to the child menu is locative hysteresis.
-
-: topmost event target
-:: The topmost event target MUST be the element highest in the rendering
- order which is capable of being an event target. In graphical user
- interfaces this is the element under the user's pointing device. A user
- interface's hit testing facility is used to determine the target. For
- specific details regarding hit testing and stacking order, refer to the
- host language.
-
-: un-initialized value
-:: The value of any event attribute (such as {{Event/bubbles}} or
- {{Event/currentTarget}}) before the event has been initialized with
- {{Event/initEvent()}}. The un-initialized values of an event apply
- immediately after a new event has been created using the method
- {{Document/createEvent()}}.
-
-: user agent
-:: A program, such as a browser or content authoring tool, normally running on
- a client machine, which acts on a user's behalf in retrieving, interpreting,
- executing, presenting, or creating content. Users MAY act on the content
- using different user agents at different times, for different purposes. See
- the [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the
- requirements for a conforming user agent.
-
-: Window
-:: The Window is the object referred to by the current document's
- browsing context's Window Proxy object as defined in
- HTML5
- [[HTML5]].
-
diff --git a/split/mouse-events.html b/split/mouse-events.html
deleted file mode 100644
index da281b1..0000000
--- a/split/mouse-events.html
+++ /dev/null
@@ -1,3121 +0,0 @@
-
-
-
-
- Mouse Events
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Note: This is an experimental split of the UI Events spec into smaller, event-specific
-
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
-
Status of this document
-
-
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
-
This document was published by the Web Applications Working Group as an Editors Draft. This document is intended to become a W3C Recommendation.
Publication as an Editors Draft does not imply endorsement by W3C and its Members. This is a draft document and may
- be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite
- this document as other than work in progress.
-
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
interface Example {
- // This is an IDL definition.
-};
-
-
3. Mouse Events
-
The mouse event module originates from the [HTML401]onclick, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, and onmouseout attributes. This event module is specifically
- designed for use with pointing input devices, such as a mouse or a trackball.
-
3.1. Interface MouseEvent
-
Introduced in DOM Level 2, modified in this
- specification
-
The MouseEvent interface provides specific contextual information
- associated with Mouse events.
-
In the case of nested elements, mouse events are always targeted at the
- most deeply nested element.
-
Ancestors of the targeted element can use event bubbling to obtain
- notifications of mouse events which occur within their descendent
- elements.
When initializing MouseEvent objects using initMouseEvent,
- implementations can use the client coordinates clientX and clientY for calculation of other coordinates (such
- as target coordinates exposed by DOM Level 0 implementations or
- other proprietary attributes, e.g., pageX).
- During mouse events caused by the depression or release of a mouse button, button MUST be used to indicate which pointer device button
- changed state.
-
The value of the button attribute MUST be as follows:
-
-
-
0 MUST indicate the primary button of the device
-(in general, the left button or the only button on single-button devices,
-used to activate a user interface control or select text) or the
-un-initialized value.
-
-
1 MUST indicate the auxiliary button
-(in general, the middle button, often combined with a mouse wheel).
-
-
2 MUST indicate the secondary button
-(in general, the right button, often used to display a context menu).
-
-
3 MUST indicate the X1 (back) button.
-
-
4 MUST indicate the X2 (forward) button.
-
-
Some pointing devices provide or simulate more button states, and values higher than 2 or lower than 0 MAY be used to represent such buttons.
-
The value of button is not updated for events not caused by the
- depression/release of a mouse button.
- In these scenarios, take care not to interpret the value 0 as the
- left button, but rather as the un-initialized value.
- During any mouse events, buttons MUST be used to
- indicate which combination of mouse buttons are currently being
- pressed, expressed as a bitmask.
-
Though similarly named, the values for the buttons attribute and the button attribute are very different. The value of button is assumed to be valid during mousedown / mouseup event handlers, whereas the buttons attribute
- reflects the state of the mouse’s buttons for any trusted MouseEvent object (while it is being dispatched), because it
- can represent the "no button currently active" state (0).
-
The value of the buttons attribute MUST be as follows:
-
-
-
0 MUST indicate no button is currently active.
-
-
1 MUST indicate the primary button of the device
-(in general, the left button or the only button on single-button devices,
-used to activate a user interface control or select text).
-
-
2 MUST indicate the secondary button
-(in general, the right button, often used to display a context menu), if present.
-
-
4 MUST indicate the auxiliary button
-(in general, the middle button, often combined with a mouse wheel).
-
-
Some pointing devices provide or simulate more buttons. To
- represent such buttons, the value MUST be doubled for each
- successive button (in the binary series 8, 16, 32, ... ).
-
Because the sum of any set of button values is a unique number,
- a content author can use a bitwise operation to determine how
- many buttons are currently being pressed and which buttons they
- are, for an arbitrary number of mouse buttons on a device. For
- example, the value 3 indicates that the left and
- right button are currently both pressed, while the value 5 indicates that the left and middle button are
- currently both pressed.
- Initializes the screenX attribute of the MouseEvent object to the desired horizontal relative position of the mouse
- pointer on the user’s screen.
-
Initializing the event object to the given mouse position must
- not move the user’s mouse pointer to the initialized position.
- Initializes the clientX attribute of the MouseEvent object to the desired horizontal position of the mouse pointer
- relative to the client window of the user’s browser.
-
Initializing the event object to the given mouse position must
- not move the user’s mouse pointer to the initialized position.
- Initializes the clientY attribute of the MouseEvent object to the desired vertical position of the mouse pointer
- relative to the client window of the user’s browser.
-
Initializing the event object to the given mouse position must
- not move the user’s mouse pointer to the initialized position.
- Initializes the button attribute of the MouseEvent object to a number representing the desired state of the button(s)
- of the mouse.
-
The value 0 is used to represent
- the primary mouse button, 1 is used to represent the auxiliary/middle
- mouse button, and 2 to represent the right mouse button.
- Numbers greater than 2 are also possible, but are not specified
- in this document.
- Initializes the buttons attribute of the MouseEvent object to a number representing one or more of the button(s) of the mouse
- that are to be considered active.
-
The buttons attribute is a bit-field. If a mask value of 1 is true when applied to
- the value of the bit field, then the primary mouse button is down. If a
- mask value of 2 is true when applied to the value of the bit field, then
- the right mouse button is down. If a mask value of 4 is true when applied
- to the value of the bit field, then the auxiliary/middle button is down.
-
In JavaScript, to initialize the buttons attribute as if the right (2) and middle
- button (4) were being pressed simultaneously, the buttons value
- can be assigned as either: { buttons: 2 | 4 } or: { buttons: 6 }
-
relatedTarget, of type EventTarget, nullable, defaulting to null
-
The relatedTarget should be initialized to the element
- whose bounds the mouse pointer just left (in the case of a mouseover or mouseenter event) or the element
- whose bounds the mouse pointer is entering (in the case of a mouseout or mouseleave or focusout event). For other events, this value need not
- be assigned (and will default to null).
-
-
Implementations MUST maintain the current
- click count when generating mouse events. This MUST be a non-negative
- integer indicating the number of consecutive clicks of a pointing device
- button within a specific time. The delay after which the count resets is
- specific to the environment configuration.
-
3.2. Event Modifier Initializers
-
The MouseEvent and KeyboardEvent interfaces share a set of
- keyboard modifier attributes and support a mechanism for retrieving
- additional modifier states. The following dictionary enables authors to
- initialize keyboard modifier attributes of the MouseEvent and KeyboardEvent interfaces, as well as the additional modifier states
- queried via getModifierState(). The steps for
- constructing events using this dictionary are defined in the event constructors section.
- Initializes the ctrlKey attribute of the MouseEvent or KeyboardEvent objects to true if the Control key modifier is to be considered active, false otherwise.
-
When true, implementations must also initialize the event object’s key modifier
- state such that calls to the getModifierState() or getModifierState() when provided with the parameter Control must return true.
- Initializes the shiftKey attribute of the MouseEvent or KeyboardEvent objects to true if the Shift key modifier is to be considered active, false otherwise.
-
When true, implementations must also initialize the event object’s key modifier
- state such that calls to the getModifierState() or getModifierState() when provided with the parameter Shift must
- return true.
- Initializes the altKey attribute of the MouseEvent or KeyboardEvent objects to true if the Alt (alternative) (or Option) key modifier
- is to be considered active, false otherwise.
-
When true, implementations must also initialize the event object’s key modifier
- state such that calls to the getModifierState() or getModifierState() when provided with the parameter Alt must
- return true.
- Initializes the metaKey attribute of the MouseEvent or KeyboardEvent objects to true if the Meta key modifier is to be considered active, false otherwise.
-
When true, implementations must also initialize the event object’s
- key modifier state such that calls to the getModifierState() or getModifierState() when provided with either the parameter Meta must return true.
-
modifierAltGraph, of type boolean, defaulting to false
-
Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter AltGraph must
- return true.
-
modifierCapsLock, of type boolean, defaulting to false
-
Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter CapsLock must
- return true.
-
modifierFn, of type boolean, defaulting to false
-
Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter Fn must
- return true.
-
modifierFnLock, of type boolean, defaulting to false
-
Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter FnLock must
- return true.
-
modifierHyper, of type boolean, defaulting to false
-
Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter Hyper must
- return true.
-
modifierNumLock, of type boolean, defaulting to false
-
Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter NumLock must
- return true.
-
modifierScrollLock, of type boolean, defaulting to false
-
Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter ScrollLock must
- return true.
-
modifierSuper, of type boolean, defaulting to false
-
Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter Super must
- return true.
-
modifierSymbol, of type boolean, defaulting to false
-
Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter Symbol must
- return true.
-
modifierSymbolLock, of type boolean, defaulting to false
-
Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter SymbolLock must
- return true.
-
-
3.3. Mouse Event Order
-
Certain mouse events defined in this specification MUST occur in a set
- order relative to one another. The following shows the event sequence
- that MUST occur when a pointing device’s cursor is moved over an element:
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:
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, 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:
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:
The lag time, degree, distance, and number of mousemove events
- allowed between the mousedown and mouseup events while
- still firing a click or dblclick event will be
- implementation-, device-, and platform-specific. This tolerance can aid
- users that have physical disabilities like unsteady hands when these
- users interact with a pointing device.
-
Each implementation will determine the appropriate hysteresis tolerance, but in general SHOULD fire click and dblclick events when the event target of the associated mousedown and mouseup events is the same element with no mouseout or mouseleave events intervening, and SHOULD fire click and dblclick events on the nearest common inclusive ancestor when the
- associated mousedown and mouseup event targets are
- different.
-
If a mousedown event was targeted at an HTML document’s body
- element, and the corresponding mouseup event was targeted at
- the root element, then the click event will be dispatched
- to the root element, since it is the nearest common inclusive
- ancestor.
-
If the event target (e.g. the target element) is removed from the
- DOM during the mouse events sequence, the remaining events of the
- sequence MUST NOT be fired on that element.
-
If the target element is removed from the DOM as the result of a mousedown event, no events for that element will be dispatched
- for mouseup, click, or dblclick, nor any default
- activation events. However, the mouseup event will still be
- dispatched on the element that is exposed to the mouse after the removal
- of the initial target element. Similarly, if the target element is
- removed from the DOM during the dispatch of a mouseup event, the click and subsequent events will not be dispatched.
-
3.4. Mouse Event Types
-
The Mouse event types are listed below. In the case of nested elements,
- mouse event types are always targeted at the most deeply nested element.
- Ancestors of the targeted element MAY use bubbling to obtain
- notification of mouse events which occur within its descendent elements.
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.screenX : value based on the pointer position on the screen
-
MouseEvent.screenY : value based on the pointer position on the screen
-
MouseEvent.clientX : value based on the pointer position within the viewport
-
MouseEvent.clientY : value based on the pointer position within the viewport
-
MouseEvent.layerX : value based on the pointer position within the containing element
-
MouseEvent.layerY : value based on the pointer position within the containing element
-
MouseEvent.altKey : true if Alt modifier was active, otherwise false
-
MouseEvent.ctrlKey : true if Control modifier was active, otherwise false
-
MouseEvent.shiftKey : true if Shift modifier was active, otherwise false
-
MouseEvent.metaKey : true if Meta modifier was active, otherwise false
-
The auxclick event type MUST be dispatched on the topmost
- event target indicated by the pointer, when the user presses
- down and releases the non-primary pointer button, or otherwise activates
- the pointer in a manner that simulates such an action. The actuation
- method of the mouse button depends upon the pointer device and the
- environment configuration, e.g., it MAY depend on the screen
- location or the delay between the press and release of the pointing
- device button.
-
The auxclick event should only be fired for the non-primary pointer
- buttons (i.e., when button value is not 0, buttons value is greater than 1). The primary button
- (like the left button on a standard mouse) MUST NOT fire auxclick events. See click for a corresponding event that
- is associated with the primary button.
-
The auxclick event MAY be preceded by the mousedown and mouseup events on the same element, disregarding changes
- between other node types (e.g., text nodes). Depending upon the
- environment configuration, the auxclick event MAY be dispatched
- if one or more of the event types mouseover, mousemove, and mouseout occur between the press and
- release of the pointing device button.
Receiving and handling auxclick for the middle button. myLink.addEventListener("auxclick", function(e) {
- if (e.button === 1) {
- // This would prevent the default behavior which is for example
- // opening a new tab when middle clicking on a link.
- e.preventDefault();
- // Do something else to handle middle button click like taking
- // care of opening link or non-link buttons in new tabs in a way
- // that fits the app. Other actions like closing a tab in a tab-strip
- // which should be done on the click action can be done here too.
- }
- });
-
In the case of right button, the auxclick event is dispatched after
- any contextmenu event. Note that some user agents swallow all input
- events while a context menu is being displayed, so auxclick may not be
- available to applications in such scenarios.
- See this example for more clarification.
-
Receiving and handling auxclick for the right button myDiv.addEventListener("contextmenu", function(e) {
- // This call makes sure no context menu is shown
- // to interfere with page receiving the events.
- e.preventDefault();
- });
- myDiv.addEventListener("auxclick", function(e) {
- if (e.button === 2) {
- // Do something else to handle right button click like opening a
- // customized context menu inside the app.
- }
- });
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.screenX : value based on the pointer position on the screen
-
MouseEvent.screenY : value based on the pointer position on the screen
-
MouseEvent.clientX : value based on the pointer position within the viewport
-
MouseEvent.clientY : value based on the pointer position within the viewport
-
MouseEvent.layerX : value based on the pointer position within the containing element
-
MouseEvent.layerY : value based on the pointer position within the containing element
-
MouseEvent.altKey : true if Alt modifier was active, otherwise false
-
MouseEvent.ctrlKey : true if Control modifier was active, otherwise false
-
MouseEvent.shiftKey : true if Shift modifier was active, otherwise false
-
MouseEvent.metaKey : true if Meta modifier was active, otherwise false
-
The click event type MUST be dispatched on the topmost
- event target indicated by the pointer, when the user presses
- down and releases the primary pointer button, or otherwise activates
- the pointer in a manner that simulates such an action. The actuation
- method of the mouse button depends upon the pointer device and the
- environment configuration, e.g., it MAY depend on the screen
- location or the delay between the press and release of the pointing
- device button.
-
The click event should only be fired for the primary pointer
- button (i.e., when button value is 0, buttons value is 1). Secondary buttons
- (like the middle or right button on a standard mouse) MUST NOT fire click events. See auxclick for a corresponding event that
- is associated with the non-primary buttons.
-
The click event MAY be preceded by the mousedown and mouseup events on the same element, disregarding changes
- between other node types (e.g., text nodes). Depending upon the
- environment configuration, the click event MAY be dispatched
- if one or more of the event types mouseover, mousemove, and mouseout occur between the press and
- release of the pointing device button. The click event MAY
- also be followed by the dblclick event.
-
If a user mouses down on a text node child of a <p> element which has been styled with a large
- line-height, shifts the mouse slightly such that it is no longer
- over an area containing text but is still within the containing
- block of that <p> element (i.e., the pointer is
- between lines of the same text block, but not over the text node per
- se), then subsequently mouses up, this will likely still trigger a click event (if it falls within the normal temporal hysteresis for a click), since the user has stayed
- within the scope of the same element. Note that user-agent-generated
- mouse events are not dispatched on text nodes.
-
In addition to being associated with pointer devices, the click event type MUST be dispatched as part of an element
- activation, as described in § 8.1.1 Activation triggers and behavior.
-
For maximum accessibility, content authors are encouraged to use the click event type when defining activation behavior for custom
- controls, rather than other pointing-device event types such as mousedown or mouseup, which are more device-specific.
- Though the click event type has its origins in pointer
- devices (e.g., a mouse), subsequent implementation enhancements have
- extended it beyond that association, and it can be considered a
- device-independent event type for element activation.
A user agent MUST dispatch this event when the primary button
- of a pointing device is clicked twice over an element. The
- definition of a double click depends on the environment
- configuration, except that the event target MUST be the same between mousedown, mouseup, and dblclick. This event
- type MUST be dispatched after the event type click if a click
- and double click occur simultaneously, and after the event type mouseup otherwise.
-
As with the click event, the dblclick event should
- only be fired for the primary pointer button. Secondary buttons MUST
- NOT fire dblclick events.
-
Canceling the click event does not affect the firing of a dblclick event.
Varies: Start a drag/drop operation; start a text selection; start a scroll/pan interaction (in combination with the middle mouse button, if supported)
-
A user agent MUST dispatch this event when a pointing device
- button is pressed over an element.
-
Many implementations use the mousedown event to begin a
- variety of contextually dependent default actions. These
- default actions can be prevented if this event is canceled. Some of
- these default actions could include: beginning a drag/drop
- interaction with an image or link, starting text selection, etc.
- Additionally, some implementations provide a mouse-driven panning
- feature that is activated when the middle mouse button is pressed at
- the time the mousedown event is dispatched.
A user agent MUST dispatch this event when a pointing device
- is moved onto the boundaries of an element or one of its descendent
- elements. A user agent MUST also dispatch this event when the
- element or one of its descendants moves to be underneath the primary
- pointing device. This event type is similar to mouseover, but
- differs in that it does not bubble, and MUST NOT be dispatched when
- the pointer device moves from an element onto the boundaries of one
- of its descendent elements.
A user agent MUST dispatch this event when a pointing device
- is moved off of the boundaries of an element and all of its
- descendent elements. A user agent MUST also dispatch this event
- when the element or one of its descendants moves to be no longer underneath
- the primary pointing device. This event type is similar to mouseout,
- but differs in that does not bubble, and that it MUST NOT be
- dispatched until the pointing device has left the boundaries of the
- element and the boundaries of all of its children.
A user agent MUST dispatch this event when a pointing device
- is moved while it is over an element. The frequency rate of events
- while the pointing device is moved is implementation-, device-, and
- platform-specific, but multiple consecutive mousemove events
- SHOULD be fired for sustained pointer-device movement, rather than a
- single event for each instance of mouse movement. Implementations
- are encouraged to determine the optimal frequency rate to balance
- responsiveness with performance.
-
In some implementation environments, such as a browser, mousemove events can continue to fire if the user began a
- drag operation (e.g., a mouse button is pressed) and the pointing
- device has left the boundary of the user agent.
-
This event was formerly specified to be non-cancelable in DOM Level
- 2 Events, but was changed to reflect existing interoperability between
- user agents.
A user agent MUST dispatch this event when a pointing device
- is moved off of the boundaries of an element or when the element is
- moved to be no longer underneath the primary pointing device.
- This event type is similar to mouseleave, but differs in that
- does bubble, and that it MUST be dispatched when the pointer device
- moves from an element onto the boundaries of one of its descendent elements.
A user agent MUST dispatch this event when a pointing device
- is moved onto the boundaries of an element or when the element is
- moved to be underneath the primary pointing device.
- This event type is similar to mouseenter, but differs in
- that it bubbles, and that it MUST be dispatched when the pointer device moves onto the
- boundaries of an element whose ancestor element is the event
- target for the same event listener instance.
A user agent MUST dispatch this event when a pointing device
- button is released over an element.
-
In some implementation environments, such as a browser, a mouseup event can be dispatched even if the pointing device
- has left the boundary of the user agent, e.g., if the user began a
- drag operation with a mouse button pressed.
-
4. Constructing Mouse and Keyboard Events
-
Generally, when a constructor of an Event interface, or of an interface
- inherited from the Event interface, is invoked, the steps described in [DOM] should be followed. However the KeyboardEvent and MouseEvent interfaces provide additional dictionary members for
- initializing the internal state of the Event object’s key modifiers:
- specifically, the internal state queried for using the getModifierState() and getModifierState() methods. This section supplements the DOM4 steps for intializing a new Event object with these optional modifier states.
The following steps supplement the algorithm defined for constructing
- events in DOM4:
-
-
-
If the Event being constructed is a KeyboardEvent or MouseEvent object or an object that derives from either of these,
-and a EventModifierInit argument was provided to the constructor,
-then run the following sub-steps:
-
-
-
For each EventModifierInit argument, if the dictionary member
-begins with the string "modifier", then let the key modifier name be the
-dictionary member’s name excluding the prefix "modifier", and set the Event object’s internal key modifier state that matches the key modifier name to the corresponding value.
-
-
-
5. Legacy Event Initializers
-
This section is normative.
-
The following features are obsolete and should only be implemented by user agents that require compatibility with legacy software.
-
Early versions of this specification included an initialization method on
- the interface (for example initMouseEvent) that required a long
- list of parameters that, in most cases, did not fully initialize all
- attributes of the event object. Because of this, event interfaces which were
- derived from the basic Event interface required that the initializer of each of the derived interfaces be called explicitly in order to
- fully initialize an event.
-
Initializing all the attributes of a MutationEvent requires calls to two
- initializer methods: initEvent and initMutationEvent.
-
Due in part to the length of time in the development of this standard, some
- implementations MAY have taken a dependency on these (now deprecated)
- initializer methods. For completeness, these legacy event initializers are
- described in this section.
Specifies relatedTarget. This value MAY
- be null.
-
-
-
6. Security Considerations
-
TODO - Add specific concerns for this spec
-
7. Acknowledgements
-
TODO
-
8. Refs to other UIEvent specs [DELETE]
-
This section will be deleted.
-
Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
8.1. Things defined in other sections
-
8.1.1. Activation triggers and behavior
-
8.1.2. Composition Events
-
8.1.3. Default actions and cancelable events
-
8.1.4. Event dispatch and DOM event flow
-
8.1.5. Web browsers and other dynamic or interactive user agents
-
8.1.6. Authoring tools
-
8.2. Things defined in KeyboardEvents
-
8.2.1. Modifier keys
-
9. Glossary [DELETE]
-
This section will be deleted.
-
Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-
activation behavior
-
-
The action taken when an event, typically initiated by users through
-an input device, causes an element to fulfill a defined task. The task MAY
-be defined for that element by the host language, or by
-author-defined variables, or both. The default task for any given element
-MAY be a generic action, or MAY be unique to that element. For example, the
-activation behavior of an HTML or SVG <a> element is to
-cause the user agent to traverse the link specified in the href attribute, with the further optional parameter of
-specifying the browsing context for the traversal (such as the current
-window or tab, a named window, or a new window). The activation behavior of
-an HTML <input> element with the type attribute value submit is be to send the values of the form
-elements to an author-defined IRI by the author-defined HTTP method. See § 8.1.1 Activation triggers and behavior for more details.
In HTML or XHTML documents, the body element represents the contents of the
-document. In a well-formed HTML document, the body element is a first
-descendant of the root element.
-
DOM Level 0
-
-
The term DOM Level 0 refers to a mix of HTML document functionalities,
-often not formally specified but traditionally supported as de facto
-standards, implemented originally by Netscape Navigator version 3.0 or
-Microsoft Internet Explorer version 3.0. In many cases, attributes or
-methods have been included for reasons of backward compatibility with DOM
-Level 0.
-
default action
-
-
A default action is an OPTIONAL supplementary behavior that an
-implementation MUST perform in combination with the dispatch of the event
-object. Each event type definition, and each specification, defines the default action for that event type, if it has one. An instance of an
-event MAY have more than one default action under some circumstances,
-such as when associated with an activation trigger. A default
-action MAY be cancelled through the invocation of the preventDefault() method. For more details, see § 8.1.3 Default actions and cancelable events.
-
event
-
-
An event is the representation of some occurrence (such as a mouse click on
-the presentation of an element, the removal of child node from an element,
-or any number of other possibilities) which is associated with its event
-target. Each event is an instantiation of one specific event
-type.
Any language which integrates the features of another language or API
-specification, while normatively referencing the origin specification rather
-than redefining those features, and extending those features only in ways
-defined by the origin specification. An origin specification typically is
-only intended to be implemented in the context of one or more host
-languages, not as a standalone language. For example, XHTML, HTML, and SVG
-are host languages for UI Events, and they integrate and extend the objects
-and models defined in this specification.
-
hysteresis
-
-
A feature of human interface design to accept input values within a certain
-range of location or time, in order to improve the user experience. For
-example, allowing for small deviation in the time it takes for a user to
-double-click a mouse button is temporal hysteresis, and not immediately
-closing a nested menu if the user mouses out from the parent window when
-transitioning to the child menu is locative hysteresis.
-
topmost event target
-
-
The topmost event target MUST be the element highest in the rendering
-order which is capable of being an event target. In graphical user
-interfaces this is the element under the user’s pointing device. A user
-interface’s hit testing facility is used to determine the target. For
-specific details regarding hit testing and stacking order, refer to the host language.
-
un-initialized value
-
-
The value of any event attribute (such as bubbles or currentTarget) before the event has been initialized with initEvent(). The un-initialized values of an event apply
-immediately after a new event has been created using the method createEvent().
-
user agent
-
-
A program, such as a browser or content authoring tool, normally running on
-a client machine, which acts on a user’s behalf in retrieving, interpreting,
-executing, presenting, or creating content. Users MAY act on the content
-using different user agents at different times, for different purposes. See
-the § 8.1.5 Web browsers and other dynamic or interactive user agents and § 8.1.6 Authoring tools for details on the
-requirements for a conforming user agent.
-
Window
-
-
The Window is the object referred to by the current document’s
-browsing context’s Window Proxy object as defined in HTML5[HTML5].
-
-
-
-
Conformance
-
Document conventions
-
Conformance requirements are expressed
- with a combination of descriptive assertions
- and RFC 2119 terminology.
- The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”
- in the normative parts of this document
- are to be interpreted as described in RFC 2119.
- However, for readability,
- these words do not appear in all uppercase letters in this specification.
-
All of the text of this specification is normative
- except sections explicitly marked as non-normative, examples, and notes. [RFC2119]
-
Examples in this specification are introduced with the words “for example”
- or are set apart from the normative text
- with class="example",
- like this:
-
-
-
This is an example of an informative example.
-
-
Informative notes begin with the word “Note”
- and are set apart from the normative text
- with class="note",
- like this:
-
Note, this is an informative note.
-
-
Conformant Algorithms
-
Requirements phrased in the imperative as part of algorithms
- (such as "strip any leading space characters"
- or "return false and abort these steps")
- are to be interpreted with the meaning of the key word
- ("must", "should", "may", etc)
- used in introducing the algorithm.
-
Conformance requirements phrased as algorithms or specific steps
- can be implemented in any manner,
- so long as the end result is equivalent.
- In particular, the algorithms defined in this specification
- are intended to be easy to understand
- and are not intended to be performant.
- Implementers are encouraged to optimize.
-
-
-
\ No newline at end of file
diff --git a/split/mouse-events.txt b/split/mouse-events.txt
deleted file mode 100644
index 34ad7bf..0000000
--- a/split/mouse-events.txt
+++ /dev/null
@@ -1,1916 +0,0 @@
-
Mouse Events
-
-
-Shortname: mouse-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
- *** Mouse Events ***
-
- Note: This is an experimental split of the UI Events spec into smaller, event-specific
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
- interface Example {
- // This is an IDL definition.
- };
-
-
-
Mouse Events
-
- The mouse event module originates from the [[HTML401]] onclick,
- ondblclick, onmousedown, onmouseup,
- onmouseover, onmousemove, and
- onmouseout attributes. This event module is specifically
- designed for use with pointing input devices, such as a mouse or a trackball.
-
-
Interface MouseEvent
-
-
Introduced in DOM Level 2, modified in this
- specification
-
-
- The {{MouseEvent}} interface provides specific contextual information
- associated with Mouse events.
-
- In the case of nested elements, mouse events are always targeted at the
- most deeply nested element.
-
-
- Ancestors of the targeted element can use event bubbling to obtain
- notifications of mouse events which occur within their descendent
- elements.
-
-
- To create an instance of the {{MouseEvent}} interface, use the
- {{MouseEvent}} constructor, passing an optional {{MouseEventInit}}
- dictionary.
-
-
- When initializing {{MouseEvent}} objects using initMouseEvent,
- implementations can use the client coordinates {{MouseEvent/clientX}}
- and {{MouseEvent/clientY}} for calculation of other coordinates (such
- as target coordinates exposed by DOM Level 0 implementations or
- other proprietary attributes, e.g., pageX).
-
- 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.
-
- 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.
-
- 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.
-
- 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.
-
-
- 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, 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.
-
-
{{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
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.
- }
- });
-
-
{{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
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.
-
-
|
- ++------------------+--------------------------------------------------------------------------------------+
-
- 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.
-
|
- ++------------------+--------------------------------------------------------------------------------------+
-
- 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 |
{{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
|
- ++------------------+--------------------------------------------------------------------------------------+
-
- 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.
-
{{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.
-
{{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.
-
|
- ++------------------+--------------------------------------------------------------------------------------+
-
- 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.
-
{{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.
-
-
{{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.
-
-
|
- ++------------------+--------------------------------------------------------------------------------------+
-
- A user agent MUST dispatch this event when a pointing device
- button is released over an element.
-
-
- In some implementation environments, such as a browser, a
- EVENT{mouseup} event can be dispatched even if the pointing device
- has left the boundary of the user agent, e.g., if the user began a
- drag operation with a mouse button pressed.
-
-
-
Constructing Mouse and Keyboard Events
-
- Generally, when a constructor of an {{Event}} interface, or of an interface
- inherited from the {{Event}} interface, is invoked, the steps described in
- [[!DOM]] should be followed. However the {{KeyboardEvent}} and
- {{MouseEvent}} interfaces provide additional dictionary members for
- initializing the internal state of the {{Event}} object's key modifiers:
- specifically, the internal state queried for using the
- {{KeyboardEvent/getModifierState()}} and {{MouseEvent/getModifierState()}}
- methods. This section supplements the DOM4 steps for intializing a new
- {{Event}} object with these optional modifier states.
-
- For the purposes of constructing a {{KeyboardEvent}}, {{MouseEvent}}, or
- object derived from these objects using the algorithm below, all
- {{KeyboardEvent}}, {{MouseEvent}}, and derived objects have
- internal key modifier state which can be set and
- retrieved using the key modifier names
- described in the
- Modifier Keys table
- in [[UIEvents-Key]].
-
- The following steps supplement the algorithm defined for constructing
- events in DOM4:
-
- * If the {{Event}} being constructed is a {{KeyboardEvent}} or
- {{MouseEvent}} object or an object that derives from either of these,
- and a {{EventModifierInit}} argument was provided to the constructor,
- then run the following sub-steps:
-
- * For each {{EventModifierInit}} argument, if the dictionary member
- begins with the string "modifier", then let the
- key modifier name be the
- dictionary member's name excluding the prefix
- "modifier", and set the {{Event}} object's
- internal key modifier state
- that matches the key modifier name
- to the corresponding value.
-
-
Legacy Event Initializers
-
- This section is normative.
-
- The following features are obsolete and should only be implemented by
- user agents that require compatibility with legacy software.
-
- Early versions of this specification included an initialization method on
- the interface (for example initMouseEvent) that required a long
- list of parameters that, in most cases, did not fully initialize all
- attributes of the event object. Because of this, event interfaces which were
- derived from the basic {{Event}} interface required that the initializer of
- each of the derived interfaces be called explicitly in order to
- fully initialize an event.
-
-
- Initializing all the attributes of a MutationEvent requires calls to two
- initializer methods: initEvent and
- initMutationEvent.
-
-
- Due in part to the length of time in the development of this standard, some
- implementations MAY have taken a dependency on these (now deprecated)
- initializer methods. For completeness, these legacy event initializers are
- described in this section.
-
-
- Initializes attributes of a {{MouseEvent}} object. This
- method has the same behavior as UIEvent.initUIEvent().
-
-
- The initMouseEvent method is deprecated, but
- supported for backwards-compatibility with widely-deployed
- implementations.
-
-
-
-
DOMString typeArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
boolean bubblesArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
boolean cancelableArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
Window? viewArg
-
- Specifies {{UIEvent/view}}. This value MAY be null.
-
-
-
long detailArg
-
- Specifies {{UIEvent/detail}}.
-
-
-
long screenXArg
-
- Specifies {{MouseEvent/screenX}}.
-
-
-
long screenYArg
-
- Specifies {{MouseEvent/screenY}}.
-
-
-
long clientXArg
-
- Specifies {{MouseEvent/clientX}}.
-
-
-
long clientYArg
-
- Specifies {{MouseEvent/clientY}}.
-
-
-
boolean ctrlKeyArg
-
- Specifies {{MouseEvent/ctrlKey}}.
-
-
-
boolean altKeyArg
-
- Specifies {{MouseEvent/altKey}}.
-
-
-
boolean shiftKeyArg
-
- Specifies {{MouseEvent/shiftKey}}.
-
-
-
boolean metaKeyArg
-
- Specifies {{MouseEvent/metaKey}}.
-
-
-
short buttonArg
-
- Specifies {{MouseEvent/button}}.
-
-
-
EventTarget? relatedTargetArg
-
- Specifies {{MouseEvent/relatedTarget}}. This value MAY
- be null.
-
-
-
-
-
-
Security Considerations
-
- TODO - Add specific concerns for this spec
-
-
Acknowledgements
-
- TODO
-
-
Refs to other UIEvent specs \[DELETE]
-
- This section will be deleted.
-
- Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
-
Things defined in other sections
-
-
Activation triggers and behavior
-
Composition Events
-
Default actions and cancelable events
-
Event dispatch and DOM event flow
-
Web browsers and other dynamic or interactive user agents
-
Authoring tools
-
-
Things defined in KeyboardEvents
-
Modifier keys
-
-
Glossary \[DELETE]
-
-This section will be deleted.
-
-Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-: activation behavior
-:: The action taken when an event, typically initiated by users through
- an input device, causes an element to fulfill a defined task. The task MAY
- be defined for that element by the host language, or by
- author-defined variables, or both. The default task for any given element
- MAY be a generic action, or MAY be unique to that element. For example, the
- activation behavior of an HTML or SVG <a> element is to
- cause the user agent to traverse the link specified in the
- href attribute, with the further optional parameter of
- specifying the browsing context for the traversal (such as the current
- window or tab, a named window, or a new window). The activation behavior of
- an HTML <input> element with the type
- attribute value submit is be to send the values of the form
- elements to an author-defined IRI by the author-defined HTTP method. See
- [[#event-flow-activation]] for more details.
-
-: activation trigger
-:: An event which is defined to initiate an activation behavior. Refer
- to [[#event-flow-activation]] for more details.
-
-: body element
-:: In HTML or XHTML documents, the body element represents the contents of the
- document. In a well-formed HTML document, the body element is a first
- descendant of the root element.
-
-: DOM Level 0
-:: The term DOM Level 0 refers to a mix of HTML document functionalities,
- often not formally specified but traditionally supported as de facto
- standards, implemented originally by Netscape Navigator version 3.0 or
- Microsoft Internet Explorer version 3.0. In many cases, attributes or
- methods have been included for reasons of backward compatibility with DOM
- Level 0.
-
-: default action
-:: A default action is an OPTIONAL supplementary behavior that an
- implementation MUST perform in combination with the dispatch of the event
- object. Each event type definition, and each specification, defines the
- default action for that event type, if it has one. An instance of an
- event MAY have more than one default action under some circumstances,
- such as when associated with an activation trigger. A default
- action MAY be cancelled through the invocation of the
- {{Event/preventDefault()}} method. For more details, see
- [[#event-flow-default-cancel]].
-
-: event
-:: An event is the representation of some occurrence (such as a mouse click on
- the presentation of an element, the removal of child node from an element,
- or any number of other possibilities) which is associated with its event
- target. Each event is an instantiation of one specific event
- type.
-
-: event target
-:: The object to which an event is targeted using the [[#event-flow]].
- The event target is the value of the {{Event/target}} attribute.
-
-: host language
-:: Any language which integrates the features of another language or API
- specification, while normatively referencing the origin specification rather
- than redefining those features, and extending those features only in ways
- defined by the origin specification. An origin specification typically is
- only intended to be implemented in the context of one or more host
- languages, not as a standalone language. For example, XHTML, HTML, and SVG
- are host languages for UI Events, and they integrate and extend the objects
- and models defined in this specification.
-
-: hysteresis
-:: A feature of human interface design to accept input values within a certain
- range of location or time, in order to improve the user experience. For
- example, allowing for small deviation in the time it takes for a user to
- double-click a mouse button is temporal hysteresis, and not immediately
- closing a nested menu if the user mouses out from the parent window when
- transitioning to the child menu is locative hysteresis.
-
-: topmost event target
-:: The topmost event target MUST be the element highest in the rendering
- order which is capable of being an event target. In graphical user
- interfaces this is the element under the user's pointing device. A user
- interface's hit testing facility is used to determine the target. For
- specific details regarding hit testing and stacking order, refer to the
- host language.
-
-: un-initialized value
-:: The value of any event attribute (such as {{Event/bubbles}} or
- {{Event/currentTarget}}) before the event has been initialized with
- {{Event/initEvent()}}. The un-initialized values of an event apply
- immediately after a new event has been created using the method
- {{Document/createEvent()}}.
-
-: user agent
-:: A program, such as a browser or content authoring tool, normally running on
- a client machine, which acts on a user's behalf in retrieving, interpreting,
- executing, presenting, or creating content. Users MAY act on the content
- using different user agents at different times, for different purposes. See
- the [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the
- requirements for a conforming user agent.
-
-: Window
-:: The Window is the object referred to by the current document's
- browsing context's Window Proxy object as defined in
- HTML5
- [[HTML5]].
-
diff --git a/split/ui-events.bs b/split/ui-events.bs
deleted file mode 100644
index b66cde1..0000000
--- a/split/ui-events.bs
+++ /dev/null
@@ -1,884 +0,0 @@
-
UI Events
-
-
-Shortname: uievents-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
- *** UI Events (core) ***
-
- Note: This is an experimental split of the UI Events spec into smaller, event-specific
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
- interface Example {
- // This is an IDL definition.
- };
-
-
-
User Interface Events
-
- The User Interface event module contains basic event types associated with
- user interfaces and document manipulation.
-
-
Interface UIEvent
-
-
Introduced in DOM Level 2
-
- The {{UIEvent}} interface provides specific contextual information
- associated with User Interface events.
-
- To create an instance of the {{UIEvent}} interface, use the UIEvent
- constructor, passing an optional {{UIEventInit}} dictionary.
-
-
- For newly defined events, you don't have to inherit {{UIEvent}} interface just
- because they are related to user interface. Inherit only when members of
- {{UIEventInit}} make sense to those events.
-
- 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.
-
- 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
-
-
-
Type
load
-
Interface
{{UIEvent}} if generated from a user interface, {{Event}} otherwise.
-
- A user agent MUST dispatch this event when the DOM
- implementation finishes loading the resource (such as the document)
- and any dependent resources (such as images, style sheets, or
- scripts). Dependent resources that fail to load MUST NOT prevent
- this event from firing if the resource that loaded them is still
- accessible via the DOM. If this event type is dispatched,
- implementations are REQUIRED to dispatch this event at least on the
- Document node.
-
-
- For legacy reasons, load events for resources inside the
- document (e.g., images) do not include the Window in the
- propagation path in HTML implementations. See [[HTML5]] for more
- information.
-
-
-
unload
-
-
-
Type
unload
-
Interface
{{UIEvent}} if generated from a user interface, {{Event}} otherwise.
-
- 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
-
-
-
Type
abort
-
Interface
{{UIEvent}} if generated from a user interface, {{Event}} otherwise.
-
- 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
-
-
-
Type
error
-
Interface
{{UIEvent}} if generated from a user interface, {{Event}} otherwise.
-
- 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
-
-
-
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
-
- A user agent MUST dispatch this event when a user selects
- some text. This event is dispatched after the selection has occurred.
-
- This specification does not provide contextual information to access
- the selected text. Where applicable, a host language SHOULD
- define rules for how a user MAY select content (with consideration
- for international language conventions), at what point the
- select event is dispatched, and how a content author MAY
- access the user-selected content.
-
-
- In order to access to user-selected content, content authors will
- use native capabilities of the host languages, such as the
- Document.getSelection() method of the HTML Editing APIs
- [[Editing]].
-
-
-
- The select event might not be available for all elements in
- all languages. For example, in [[HTML5]], select events can
- be dispatched only on form <{input}> and <{textarea}> elements.
- Implementations can dispatch select events in any context
- deemed appropriate, including text selections outside of form
- controls, or image or markup selections such as in SVG.
-
-
-
Extending Events
-
-
-This section is non-normative
-
-
Introduction
-
- This specification defines several interfaces and many events, however, this
- is not an exhaustive set of events for all purposes. To allow content
- authors and implementers to add desired functionality, this specification
- provides two mechanisms for extend this set of interfaces and events without
- creating conflicts: custom
- events and implementation-specific
- extensions.
-
-
Custom Events
-
- A script author MAY wish to define an application in terms of functional
- components, with event types that are meaningful to the application
- architecture. The content author can use the {{CustomEvent}} interface to
- create their own events appropriate to the level of abstraction they are
- using.
-
-
- A content author might have created an application which features a
- dynamically generated bar chart. This bar chart is meant to be updated every
- 5 minutes, or when a feed shows new information, or when the user refreshes
- it manually by clicking a button. There are several handlers that have to be
- called when the chart needs to be updated: the application has to fetch the
- most recent data, show an icon to the user that the event is being updated,
- and rebuild the chart. To manage this, the content author can choose to
- create a custom updateChart event, which is fired whenever one of the
- trigger conditions is met:
-
-
-
- While a new event is being designed and prototyped, or when an event is
- intended for implementation-specific functionality, it is desirable to
- distinguish it from standardized events. Implementors SHOULD prefix event
- types specific to their implementations with a short string to distinguish
- it from the same event in other implementations and from standardized
- events. This is similar to the
- vendor-specific keyword prefixes
- in CSS, though without the dashes ("-") used in CSS, since that
- can cause problems when used as an attribute name in Javascript.
-
-
- A particular browser vendor, FooCorp, might wish to introduce a
- new event, jump. This vendor implements
- fooJump in their browser, using their
- vendor-specific prefix: "foo". Early adopters start
- experimenting with the event, using
- someElement.addEventListener("fooJump", doJump, false ),
- and provide feedback to FooCorp, who change the behavior of fooJump accordingly.
-
- After some time, another vendor, BarOrg, decides they also want
- the functionality, but implement it slightly differently, so they use
- their own vendor-specific prefix, "bar" in their event type
- name: barJump. Content authors
- experimenting with this version of the jump event type register events with BarOrg's
- event type name. Content authors who wish to write code that accounts
- for both browsers can either register each event type separately with
- specific handlers, or use the same handler and switch on the name of the
- event type. Thus, early experiments in different codebases do not
- conflict, and the early adopter is able to write easily-maintained code
- for multiple implementations.
-
- Eventually, as the feature matures, the behavior of both browsers
- stabilizes and might converge due to content author and user feedback or
- through formal standardization. As this stabilization occurs, and risk
- of conflicts decrease, content authors can remove the forked code, and
- use the jump event type name (even before
- it is formally standardized) using the same event handler and the more
- generic registration method someElement.addEventListener( "jump",
- doJump, false).
-
-
-
Known Implementation-Specific Prefixes
-
- At the time of writing, the following event-type name prefixes are known to exist:
-
-
-
Prefix
Web Engine
Organization
-
moz, Moz
Gecko
Mozilla
-
ms, MS
Trident
Microsoft
-
o, O
Presto
Opera Software
-
webkit
WebKit
Apple, Google, others
-
-
-
Legacy {{UIEvent}} events
-
-
Legacy {{UIEvent}} event types
-
-
DOMActivate
-
-
-
-
Type
-
DOMActivate
-
-
-
Interface
-
{{UIEvent}}
-
-
-
Sync / Async
-
Sync
-
-
-
Bubbles
-
Yes
-
-
-
Trusted Targets
-
Element
-
-
-
Cancelable
-
Yes
-
-
-
Composed
-
Yes
-
-
-
Default action
-
None
-
-
-
Context (trusted events)
-
-
-
{{Event}}.{{Event/target}} :
- element being activated
-
- A user agent MUST dispatch this event when a button, link, or
- other state-changing element is activated. Refer to
- [[#event-flow-activation]] for more details.
-
-
- The DOMActivateevent type is defined in this
- specification for reference and completeness, but this specification
- deprecates the use of this event type in favor of the related
- event typeclick. Other specifications MAY define and
- maintain their own DOMActivateevent type for backwards
- compatibility.
-
-
-
- While DOMActivate and click are not completely equivalent,
- implemented behavior for the clickevent type has
- developed to encompass the most critical accessibility aspects for which
- the DOMActivateevent type was designed, and is more
- widely implemented. Content authors are encouraged to use the
- clickevent type rather than the related mousedown
- or mouseupevent type to ensure maximum accessibility.
-
- The DOMActivateevent type is REQUIRED to be supported for
- XForms [[XFORMS11]], which is intended for implementation within a host
- language. In a scenario where a plugin or script-based
- implementation of XForms is intended for installation in a native
- implementation of this specification which does not support the
- DOMActivateevent type, the XForms user agent has
- to synthesize and dispatch its own DOMActivate events based on
- the appropriate activation triggers.
-
- Don't rely upon the interoperable support of DOMActivate in many
- user agents. Instead, the clickevent type should
- be used since it will provide more accessible behavior due to broader
- implementation support.
-
-
- If the DOMActivate event is supported by the user
- agent, then the events MUST be dispatched in a set order relative to
- each other: (with only pertinent events listed):
-
-
-
- If the focused element is activated by a key event, then the following
- shows the typical sequence of events (with only pertinent events listed):
-
-
-
- This section is normative.
-
- The following features are obsolete and should only be implemented by
- user agents that require compatibility with legacy software.
-
- Early versions of this specification included an initialization method on
- the interface (for example initMouseEvent) that required a long
- list of parameters that, in most cases, did not fully initialize all
- attributes of the event object. Because of this, event interfaces which were
- derived from the basic {{Event}} interface required that the initializer of
- each of the derived interfaces be called explicitly in order to
- fully initialize an event.
-
-
- Initializing all the attributes of a UIEvent requires calls to two
- initializer methods: initEvent and
- initUIEvent.
-
-
- Due in part to the length of time in the development of this standard, some
- implementations MAY have taken a dependency on these (now deprecated)
- initializer methods. For completeness, these legacy event initializers are
- described in this section.
-
-
- Initializes attributes of an {{UIEvent}} object.
- This method has the same behavior as {{Event/initEvent()}}.
-
-
- The initUIEvent method is deprecated, but
- supported for backwards-compatibility with widely-deployed
- implementations.
-
-
-
-
DOMString typeArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
boolean bubblesArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
boolean cancelableArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
Window? viewArg
-
- Specifies {{UIEvent/view}}. This value MAY be null.
-
-
-
long detailArg
-
- Specifies {{UIEvent/detail}}.
-
-
-
-
-
-
Security Considerations
-
- This appendix discusses security considerations for UI Events implementations.
- The discussion is limited to security issues that arise directly from
- implementation of the event model, APIs and events defined in this
- specification. Implementations typically support other features like scripting
- languages, other APIs and additional events not defined in this document. These
- features constitute an unknown factor and are out of scope of this document.
- Implementers SHOULD consult the specifications of such features for their
- respective security considerations.
-
- Many of the event types defined in this specification are dispatched in response
- to user actions. This allows malicious event listeners to gain access to
- information users would typically consider confidential, e.g., typos they might
- have made when filling out a form, if they reconsider their answer to a multiple
- choice question shortly before submitting a form, their typing rate or primary
- input mechanism. In the worst case, malicious event listeners could capture all
- user interactions and submit them to a third party through means (not defined in
- this specification) that are generally available in DOM implementations, such as
- the XMLHttpRequest interface.
-
- In DOM implementations that support facilities to load external data, events
- like the error event can provide access to sensitive information about
- the environment of the computer system or network. An example would be a
- malicious HTML document that attempts to embed a resource on the local network
- or the localhost on different ports. An embedded DOM application could
- then listen for error and load events to determine which other
- computers in a network are accessible from the local system or which ports are
- open on the system to prepare further attacks.
-
- An implementation of UI Events alone is generally insufficient to perform
- attacks of this kind and the security considerations of the facilities that
- possibly support such attacks apply. For conformance with this specification,
- DOM implementations MAY take reasonable steps to ensure that DOM
- applications do not get access to confidential or sensitive information. For
- example, they might choose not to dispatch load events to nodes that
- attempt to embed resources on the local network.
-
-
Acknowledgements
-
- Many people contributed to the DOM specifications (Level 1, 2 or 3),
- including participants of the DOM Working Group, the DOM Interest Group,
- the WebAPI Working Group, and the WebApps Working Group.
-
- We especially thank the following:
- Andrew Watson (Object Management Group),
- Andy Heninger (IBM),
- Angel Diaz (IBM),
- Anne van Kesteren (Opera Software),
- Arnaud Le Hors (W3C and IBM),
- Arun Ranganathan (AOL),
- Ashok Malhotra (IBM and Microsoft),
- Ben Chang (Oracle),
- Bill Shea (Merrill Lynch),
- Bill Smith (Sun),
- Björn Höhrmann,
- Bob Sutor (IBM),
- Charles McCathie-Nevile (Opera Software, Co-Chair),
- Chris Lovett (Microsoft),
- Chris Wilson (Microsoft),
- Christophe Jolif (ILOG),
- David Brownell (Sun),
- David Ezell (Hewlett-Packard Company),
- David Singer (IBM),
- Dean Jackson (W3C, W3C Team Contact),
- Dimitris Dimitriadis (Improve AB and invited expert),
- Don Park (invited),
- Doug Schepers (Vectoreal),
- Elena Litani (IBM),
- Eric Vasilik (Microsoft),
- Gavin Nicol (INSO),
- Gorm Haug Eriksen (Opera Software),
- Ian Davis (Talis Information Limited),
- Ian Hickson (Google),
- Ian Jacobs (W3C),
- James Clark (invited),
- James Davidson (Sun),
- Jared Sorensen (Novell),
- Jeroen van Rotterdam (X-Hive Corporation),
- Joe Kesselman (IBM),
- Joe Lapp (webMethods),
- Joe Marini (Macromedia),
- John Robinson (AOL),
- Johnny Stenback (Netscape/AOL),
- Jon Ferraiolo (Adobe),
- Jonas Sicking (Mozilla Foundation),
- Jonathan Marsh (Microsoft),
- Jonathan Robie (Texcel Research and Software AG),
- Kim Adamson-Sharpe (SoftQuad Software Inc.),
- Lauren Wood (SoftQuad Software Inc., former Chair),
- Laurence Cable (Sun),
- Luca Mascaro (HTML Writers Guild),
- Maciej Stachowiak (Apple Computer),
- Marc Hadley (Sun Microsystems),
- Mark Davis (IBM),
- Mark Scardina (Oracle),
- Martin Dürst (W3C),
- Mary Brady (NIST),
- Michael Shenfield (Research In Motion),
- Mick Goulish (Software AG),
- Mike Champion (Arbortext and Software AG),
- Miles Sabin (Cromwell Media),
- Patti Lutsky (Arbortext),
- Paul Grosso (Arbortext),
- Peter Sharpe (SoftQuad Software Inc.),
- Phil Karlton (Netscape),
- Philippe Le Hégaret (W3C, W3C Team Contact and former Chair),
- Ramesh Lekshmynarayanan (Merrill Lynch),
- Ray Whitmer (iMall, Excite@Home, and Netscape/AOL, Chair),
- Rezaur Rahman (Intel),
- Rich Rollman (Microsoft),
- Rick Gessner (Netscape),
- Rick Jelliffe (invited),
- Rob Relyea (Microsoft),
- Robin Berjon (Expway, Co-Chair),
- Scott Hayman (Research In Motion),
- Scott Isaacs (Microsoft),
- Sharon Adler (INSO),
- Stéphane Sire (IntuiLab),
- Steve Byrne (JavaSoft),
- Tim Bray (invited),
- Tim Yu (Oracle),
- Tom Pixley (Netscape/AOL),
- T.V. Raman (Google).
- Vidur Apparao (Netscape) and
- Vinod Anupam (Lucent).
-
- Former editors:
- Tom Pixley (Netscape Communications Corporation) until July 2002;
- Philippe Le Hégaret (W3C) until November 2003;
- Björn Höhrmann (Invited Expert) until January 2008;
- and Jacob Rossi (Microsoft) from March 2011 to October 2011.
-
- Contributors:
- In the WebApps Working Group, the following people made substantial
- material contributions in the process of refining and revising this
- specification:
- Bob Lund (Cable Laboratories),
- Cameron McCormack (Invited Expert / Mozilla),
- Daniel Danilatos (Google),
- Gary Kacmarcik (Google),
- Glenn Adams (Samsung),
- Hallvord R. M. Steen (Opera),
- Hironori Bono (Google),
- Mark Vickers (Comcast),
- Masayuki Nakano (Mozilla),
- Olli Pettay (Mozilla),
- Takayoshi Kochi (Google) and
- Travis Leithead (Microsoft).
-
- Glossary contributors:
- Arnaud Le Hors (W3C) and
- Robert S. Sutor (IBM Research).
-
- Test suite contributors:
- Carmelo Montanez (NIST),
- Fred Drake,
- Mary Brady (NIST),
- Neil Delima (IBM),
- Rick Rivello (NIST),
- Robert Clary (Netscape),
- with a special mention to Curt Arnold.
-
- Thanks to all those who have helped to improve this specification by
- sending suggestions and corrections (please, keep bugging us with your
- issues!), or writing informative books or Web sites:
- Al Gilman,
- Alex Russell,
- Alexander J. Vincent,
- Alexey Proskuryakov,
- Arkadiusz Michalski,
- Brad Pettit,
- Cameron McCormack,
- Chris Rebert,
- Curt Arnold,
- David Flanagan,
- Dylan Schiemann,
- Erik Arvidsson,
- Garrett Smith,
- Giuseppe Pascale,
- James Su,
- Jan Goyvaerts (regular-expressions.info),
- Jorge Chamorro,
- Kazuyuki Ashimura,
- Ken Rehor,
- Magnus Kristiansen,
- Martijn Wargers,
- Martin Dürst,
- Michael B. Allen,
- Mike Taylor,
- Misha Wolf,
- Ojan Vafai,
- Oliver Hunt,
- Paul Irish,
- Peter-Paul Koch,
- Richard Ishida,
- Sean Hogan,
- Sergey Ilinsky,
- Sigurd Lerstad,
- Steven Pemberton,
- Tony Chang,
- William Edney and
- Øistein E. Andersen.
-
-
Refs to other UIEvent specs \[DELETE]
-
- This section will be deleted.
-
- Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
-
Things defined in other sections
-
-
Activation triggers and behavior
-
Composition Events
-
Default actions and cancelable events
-
Event dispatch and DOM event flow
-
Focus Events
-
Web browsers and other dynamic or interactive user agents
-
Authoring tools
-
- Add references to these events so that the linker doesn't complain about exporting them.
-
- unload, load, abort, error
-
-
-
Glossary \[DELETE]
-
-This section will be deleted.
-
-Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-: host language
-:: Any language which integrates the features of another language or API
- specification, while normatively referencing the origin specification rather
- than redefining those features, and extending those features only in ways
- defined by the origin specification. An origin specification typically is
- only intended to be implemented in the context of one or more host
- languages, not as a standalone language. For example, XHTML, HTML, and SVG
- are host languages for UI Events, and they integrate and extend the objects
- and models defined in this specification.
-
-: un-initialized value
-:: The value of any event attribute (such as {{Event/bubbles}} or
- {{Event/currentTarget}}) before the event has been initialized with
- {{Event/initEvent()}}. The un-initialized values of an event apply
- immediately after a new event has been created using the method
- {{Document/createEvent()}}.
-
-: user agent
-:: A program, such as a browser or content authoring tool, normally running on
- a client machine, which acts on a user's behalf in retrieving, interpreting,
- executing, presenting, or creating content. Users MAY act on the content
- using different user agents at different times, for different purposes. See
- the [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the
- requirements for a conforming user agent.
-
-: Window
-:: The Window is the object referred to by the current document's
- browsing context's Window Proxy object as defined in
- HTML5
- [[HTML5]].
-
diff --git a/split/ui-events.html b/split/ui-events.html
deleted file mode 100644
index e03e827..0000000
--- a/split/ui-events.html
+++ /dev/null
@@ -1,1615 +0,0 @@
-
-
-
-
- UI Events
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Note: This is an experimental split of the UI Events spec into smaller, event-specific
-
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
-
Status of this document
-
-
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
-
This document was published by the Web Applications Working Group as an Editors Draft. This document is intended to become a W3C Recommendation.
Publication as an Editors Draft does not imply endorsement by W3C and its Members. This is a draft document and may
- be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite
- this document as other than work in progress.
-
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
interface Example {
- // This is an IDL definition.
-};
-
-
5. User Interface Events
-
The User Interface event module contains basic event types associated with
- user interfaces and document manipulation.
-
5.1. Interface UIEvent
-
Introduced in DOM Level 2
-
The UIEvent interface provides specific contextual information
- associated with User Interface events.
-
To create an instance of the UIEvent interface, use the UIEvent
- constructor, passing an optional UIEventInit dictionary.
-
For newly defined events, you don’t have to inherit UIEvent interface just
- because they are related to user interface. Inherit only when members of UIEventInit make sense to those events.
Should be initialized to the Window object of the global
- environment in which this event will be dispatched. If this
- event will be dispatched to an element, the view property should
- be set to the Window object containing the element’s ownerDocument.
-
UIEventInit . detail
-
This value is initialized to a number that is
- application-specific.
-
-
5.2. UI Event Types
-
The User Interface event types are listed below. Some of these events
- use the UIEvent interface if generated from a user interface, but
- the Event interface otherwise, as detailed in each event.
-
5.2.1. load
-
-
-
-
Type
-
load
-
-
Interface
-
UIEvent if generated from a user interface, Event otherwise.
-
A user agent MUST dispatch this event when the DOM
- implementation finishes loading the resource (such as the document)
- and any dependent resources (such as images, style sheets, or
- scripts). Dependent resources that fail to load MUST NOT prevent
- this event from firing if the resource that loaded them is still
- accessible via the DOM. If this event type is dispatched,
- implementations are REQUIRED to dispatch this event at least on the Document node.
-
-
For legacy reasons, load events for resources inside the
- document (e.g., images) do not include the Window in the
- propagation path in HTML implementations. See [HTML5] for more
- information.
-
5.2.2. unload
-
-
-
-
Type
-
unload
-
-
Interface
-
UIEvent if generated from a user interface, Event otherwise.
-
A user agent MUST dispatch this event when the DOM
- Implementation removes from the environment the resource (such as
- the document) or any dependent resources (such as images, style
- sheets, scripts). The document MUST be unloaded after the dispatch
- of this event type. If this event type is dispatched,
- implementations are REQUIRED to dispatch this event at least on
- the Document node.
-
5.2.3. abort
-
-
-
-
Type
-
abort
-
-
Interface
-
UIEvent if generated from a user interface, Event otherwise.
-
A user agent MUST dispatch this event when the loading of a
- resource has been aborted, such as by a user canceling the load
- while it is still in progress.
-
5.2.4. error
-
-
-
-
Type
-
error
-
-
Interface
-
UIEvent if generated from a user interface, Event otherwise.
-
A user agent MUST dispatch this event when a resource failed
- to load, or has been loaded but cannot be interpreted according to
- its semantics, such as an invalid image, a script execution error,
- or non-well-formed XML.
-
5.2.5. select
-
-
-
-
Type
-
select
-
-
Interface
-
UIEvent if generated from a user interface, Event otherwise.
-
-
Sync / Async
-
Sync
-
-
Bubbles
-
Yes
-
-
Trusted Targets
-
Element
-
-
Cancelable
-
No
-
-
Default action
-
None
-
-
Context (trusted events)
-
-
-
Event.target : element whose text content has been selected
-
A user agent MUST dispatch this event when a user selects
- some text. This event is dispatched after the selection has occurred.
-
This specification does not provide contextual information to access
- the selected text. Where applicable, a host language SHOULD
- define rules for how a user MAY select content (with consideration
- for international language conventions), at what point the select event is dispatched, and how a content author MAY
- access the user-selected content.
-
In order to access to user-selected content, content authors will
- use native capabilities of the host languages, such as the Document.getSelection() method of the HTML Editing APIs [Editing].
-
The select event might not be available for all elements in
- all languages. For example, in [HTML5], select events can
- be dispatched only on form input and textarea elements.
- Implementations can dispatch select events in any context
- deemed appropriate, including text selections outside of form
- controls, or image or markup selections such as in SVG.
-
6. Legacy Event Initializers
-
This section is normative.
-
The following features are obsolete and should only be implemented by user agents that require compatibility with legacy software.
-
Early versions of this specification included an initialization method on
- the interface (for example initMouseEvent) that required a long
- list of parameters that, in most cases, did not fully initialize all
- attributes of the event object. Because of this, event interfaces which were
- derived from the basic Event interface required that the initializer of each of the derived interfaces be called explicitly in order to
- fully initialize an event.
-
Initializing all the attributes of a MutationEvent requires calls to two
- initializer methods: initEvent and initMutationEvent.
-
Due in part to the length of time in the development of this standard, some
- implementations MAY have taken a dependency on these (now deprecated)
- initializer methods. For completeness, these legacy event initializers are
- described in this section.
Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
7.1. Things defined in other sections
-
7.1.1. Activation triggers and behavior
-
7.1.2. Composition Events
-
7.1.3. Default actions and cancelable events
-
7.1.4. Event dispatch and DOM event flow
-
7.1.5. Focus Events
-
7.1.6. Web browsers and other dynamic or interactive user agents
-
7.1.7. Authoring tools
-
Add references to these events so that the linker doesn’t complain about exporting them.
Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-
host language
-
-
Any language which integrates the features of another language or API
-specification, while normatively referencing the origin specification rather
-than redefining those features, and extending those features only in ways
-defined by the origin specification. An origin specification typically is
-only intended to be implemented in the context of one or more host
-languages, not as a standalone language. For example, XHTML, HTML, and SVG
-are host languages for UI Events, and they integrate and extend the objects
-and models defined in this specification.
-
un-initialized value
-
-
The value of any event attribute (such as bubbles or currentTarget) before the event has been initialized with initEvent(). The un-initialized values of an event apply
-immediately after a new event has been created using the method createEvent().
-
user agent
-
-
A program, such as a browser or content authoring tool, normally running on
-a client machine, which acts on a user’s behalf in retrieving, interpreting,
-executing, presenting, or creating content. Users MAY act on the content
-using different user agents at different times, for different purposes. See
-the § 7.1.6 Web browsers and other dynamic or interactive user agents and § 7.1.7 Authoring tools for details on the
-requirements for a conforming user agent.
-
Window
-
-
The Window is the object referred to by the current document’s
-browsing context’s Window Proxy object as defined in HTML5[HTML5].
-
-
-
-
Conformance
-
Document conventions
-
Conformance requirements are expressed
- with a combination of descriptive assertions
- and RFC 2119 terminology.
- The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”
- in the normative parts of this document
- are to be interpreted as described in RFC 2119.
- However, for readability,
- these words do not appear in all uppercase letters in this specification.
-
All of the text of this specification is normative
- except sections explicitly marked as non-normative, examples, and notes. [RFC2119]
-
Examples in this specification are introduced with the words “for example”
- or are set apart from the normative text
- with class="example",
- like this:
-
-
-
This is an example of an informative example.
-
-
Informative notes begin with the word “Note”
- and are set apart from the normative text
- with class="note",
- like this:
-
Note, this is an informative note.
-
-
Conformant Algorithms
-
Requirements phrased in the imperative as part of algorithms
- (such as "strip any leading space characters"
- or "return false and abort these steps")
- are to be interpreted with the meaning of the key word
- ("must", "should", "may", etc)
- used in introducing the algorithm.
-
Conformance requirements phrased as algorithms or specific steps
- can be implemented in any manner,
- so long as the end result is equivalent.
- In particular, the algorithms defined in this specification
- are intended to be easy to understand
- and are not intended to be performant.
- Implementers are encouraged to optimize.
-
-
-
\ No newline at end of file
diff --git a/split/ui-events.txt b/split/ui-events.txt
deleted file mode 100644
index 3b07f1c..0000000
--- a/split/ui-events.txt
+++ /dev/null
@@ -1,1658 +0,0 @@
-
UI Events
-
-
-Shortname: uievents-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
- *** UI Events (core) ***
-
- Note: This is an experimental split of the UI Events spec into smaller, event-specific
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
- interface Example {
- // This is an IDL definition.
- };
-
-
-
User Interface Events
-
- The User Interface event module contains basic event types associated with
- user interfaces and document manipulation.
-
-
Interface UIEvent
-
-
Introduced in DOM Level 2
-
- The {{UIEvent}} interface provides specific contextual information
- associated with User Interface events.
-
- To create an instance of the {{UIEvent}} interface, use the UIEvent
- constructor, passing an optional {{UIEventInit}} dictionary.
-
-
- For newly defined events, you don't have to inherit {{UIEvent}} interface just
- because they are related to user interface. Inherit only when members of
- {{UIEventInit}} make sense to those events.
-
- 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.
-
- 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
|
- ++------------------+--------------------------------------------------------------------------------------+
-
- 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
|
- ++------------------+--------------------------------------------------------------------------------------+
-
- 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
|
- ++------------------+--------------------------------------------------------------------------------------+
-
- 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
|
- ++------------------+--------------------------------------------------------------------------------------+
-
- 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
|
- ++------------------+--------------------------------------------------------------------------------------+
-
- A user agent MUST dispatch this event when a user selects
- some text. This event is dispatched after the selection has occurred.
-
- This specification does not provide contextual information to access
- the selected text. Where applicable, a host language SHOULD
- define rules for how a user MAY select content (with consideration
- for international language conventions), at what point the
- EVENT{select} event is dispatched, and how a content author MAY
- access the user-selected content.
-
-
- In order to access to user-selected content, content authors will
- use native capabilities of the host languages, such as the
- Document.getSelection() method of the HTML Editing APIs
- [[Editing]].
-
-
-
- The EVENT{select} event might not be available for all elements in
- all languages. For example, in [[HTML5]], EVENT{select} events can
- be dispatched only on form <{input}> and <{textarea}> elements.
- Implementations can dispatch EVENT{select} events in any context
- deemed appropriate, including text selections outside of form
- controls, or image or markup selections such as in SVG.
-
-
-
Extending Events
-
-
-This section is non-normative
-
-
Introduction
-
- This specification defines several interfaces and many events, however, this
- is not an exhaustive set of events for all purposes. To allow content
- authors and implementers to add desired functionality, this specification
- provides two mechanisms for extend this set of interfaces and events without
- creating conflicts: custom
- events and implementation-specific
- extensions.
-
-
Custom Events
-
- A script author MAY wish to define an application in terms of functional
- components, with event types that are meaningful to the application
- architecture. The content author can use the {{CustomEvent}} interface to
- create their own events appropriate to the level of abstraction they are
- using.
-
-
- A content author might have created an application which features a
- dynamically generated bar chart. This bar chart is meant to be updated every
- 5 minutes, or when a feed shows new information, or when the user refreshes
- it manually by clicking a button. There are several handlers that have to be
- called when the chart needs to be updated: the application has to fetch the
- most recent data, show an icon to the user that the event is being updated,
- and rebuild the chart. To manage this, the content author can choose to
- create a custom updateChart event, which is fired whenever one of the
- trigger conditions is met:
-
-
-
- While a new event is being designed and prototyped, or when an event is
- intended for implementation-specific functionality, it is desirable to
- distinguish it from standardized events. Implementors SHOULD prefix event
- types specific to their implementations with a short string to distinguish
- it from the same event in other implementations and from standardized
- events. This is similar to the
- vendor-specific keyword prefixes
- in CSS, though without the dashes ("-") used in CSS, since that
- can cause problems when used as an attribute name in Javascript.
-
-
- A particular browser vendor, FooCorp, might wish to introduce a
- new event, jump. This vendor implements
- fooJump in their browser, using their
- vendor-specific prefix: "foo". Early adopters start
- experimenting with the event, using
- someElement.addEventListener("fooJump", doJump, false ),
- and provide feedback to FooCorp, who change the behavior of fooJump accordingly.
-
- After some time, another vendor, BarOrg, decides they also want
- the functionality, but implement it slightly differently, so they use
- their own vendor-specific prefix, "bar" in their event type
- name: barJump. Content authors
- experimenting with this version of the jump event type register events with BarOrg's
- event type name. Content authors who wish to write code that accounts
- for both browsers can either register each event type separately with
- specific handlers, or use the same handler and switch on the name of the
- event type. Thus, early experiments in different codebases do not
- conflict, and the early adopter is able to write easily-maintained code
- for multiple implementations.
-
- Eventually, as the feature matures, the behavior of both browsers
- stabilizes and might converge due to content author and user feedback or
- through formal standardization. As this stabilization occurs, and risk
- of conflicts decrease, content authors can remove the forked code, and
- use the jump event type name (even before
- it is formally standardized) using the same event handler and the more
- generic registration method someElement.addEventListener( "jump",
- doJump, false).
-
-
-
Known Implementation-Specific Prefixes
-
- At the time of writing, the following event-type name prefixes are known to exist:
-
- ++---------------------+------------+-----------------------+
- =| Prefix | Web Engine | Organization |
- +---------------------+------------+-----------------------+
- +| moz, | Gecko | Mozilla |
- | Moz | | |
- +| ms, | Trident | Microsoft |
- | MS | | |
- +| o, | Presto | Opera Software |
- | O | | |
- +| webkit | WebKit | Apple, Google, others |
- ++---------------------+------------+-----------------------+
-
-
Legacy {{UIEvent}} events
-
-
Legacy {{UIEvent}} event types
-
-
DOMActivate
-
-
-
-
Type
-
DOMActivate
-
-
-
Interface
-
{{UIEvent}}
-
-
-
Sync / Async
-
Sync
-
-
-
Bubbles
-
Yes
-
-
-
Trusted Targets
-
Element
-
-
-
Cancelable
-
Yes
-
-
-
Composed
-
Yes
-
-
-
Default action
-
None
-
-
-
Context (trusted events)
-
-
-
{{Event}}.{{Event/target}} :
- element being activated
-
- A user agent MUST dispatch this event when a button, link, or
- other state-changing element is activated. Refer to
- [[#event-flow-activation]] for more details.
-
-
- The EVENT{DOMActivate} event type is defined in this
- specification for reference and completeness, but this specification
- deprecates the use of this event type in favor of the related
- event type EVENT{click}. Other specifications MAY define and
- maintain their own EVENT{DOMActivate} event type for backwards
- compatibility.
-
-
-
- While EVENT{DOMActivate} and EVENT{click} are not completely equivalent,
- implemented behavior for the EVENT{click} event type has
- developed to encompass the most critical accessibility aspects for which
- the EVENT{DOMActivate} event type was designed, and is more
- widely implemented. Content authors are encouraged to use the
- EVENT{click} event type rather than the related EVENT{mousedown}
- or EVENT{mouseup} event type to ensure maximum accessibility.
-
-
- Implementations which support the EVENT{DOMActivate} event type
- SHOULD also dispatch a EVENT{DOMActivate} event as a default
- action of a EVENT{click} event which is associated with an
- activation trigger. However, such implementations SHOULD only
- initiate the associated activation behavior once for any given
- occurrence of an activation trigger.
-
-
-
- The EVENT{DOMActivate} event type is REQUIRED to be supported for
- XForms [[XFORMS11]], which is intended for implementation within a host
- language. In a scenario where a plugin or script-based
- implementation of XForms is intended for installation in a native
- implementation of this specification which does not support the
- EVENT{DOMActivate} event type, the XForms user agent has
- to synthesize and dispatch its own EVENT{DOMActivate} events based on
- the appropriate activation triggers.
-
-
-
- Thus, when a EVENT{click} event is dispatched by a user agent
- conforming to UI Events, the XForms user agent has to determine
- whether to synthesize a EVENT{DOMActivate} event with the same relevant
- properties as a default action of that EVENT{click} event.
- Appropriate cues might be whether the EVENT{click} event is trusted, or whether its event target
- has a EVENT{DOMActivate} event listener registered.
-
-
-
-
- Don't rely upon the interoperable support of EVENT{DOMActivate} in many
- user agents. Instead, the EVENT{click} event type should
- be used since it will provide more accessible behavior due to broader
- implementation support.
-
-
-
- The EVENT{DOMActivate} event type is deprecated in this
- specification.
-
-
-
Activation event order
-
- If the DOMActivate event is supported by the user
- agent, then the events MUST be dispatched in a set order relative to
- each other: (with only pertinent events listed):
-
- ++---+-------------+---------------------------------------------------+
- =| # | Event Type | Notes |
- +---+-------------+---------------------------------------------------+
- +| 1 | click | |
- +| 2 | DOMActivate | default action, if supported by the |
- | | | user agent; synthesized; |
- | | | isTrusted="true" |
- +| 3 | | All other default actions, |
- | | | including the activation behavior |
- ++---+-------------+---------------------------------------------------+
-
- If the focused element is activated by a key event, then the following
- shows the typical sequence of events (with only pertinent events listed):
-
- ++---+-------------+---------------------------------------------------+
- =| # | Event Type | Notes |
- +---+-------------+---------------------------------------------------+
- +| 1 | keydown | MUST be a key which can activate the element, |
- | | | such as the KEYCAP{Enter} or KEYCAP{ } |
- | | | (spacebar) key, or the element is not activated |
- +| 2 | click | default action; synthesized; |
- | | | isTrusted="true" |
- +| 3 | DOMActivate | default action, if supported by the |
- | | | user agent; synthesized; |
- | | | isTrusted="true" |
- +| 4 | | All other default actions, |
- | | | including the activation behavior |
- ++---+-------------+---------------------------------------------------+
-
-
Legacy {{MutationEvent}} events
-
- The mutation and mutation name event modules are designed to allow
- notification of any changes to the structure of a document, including
- attribute, text, or name modifications.
-
-
- None of the event types associated with the {{MutationEvent}} interface are
- designated as cancelable. This stems from the fact that it is very difficult
- to make use of existing DOM interfaces which cause document modifications if
- any change to the document might or might not take place due to cancelation
- of the resulting event. Although this is still a desired capability, it was
- decided that it would be better left until the addition of transactions into
- the DOM.
-
-
- Many single modifications of the tree can cause multiple mutation events to
- be dispatched. Rather than attempt to specify the ordering of mutation
- events due to every possible modification of the tree, the ordering of these
- events is left to the implementation.
-
-
-
- The {{MutationEvent}} interface was introduced in DOM Level 2 Events, but
- has not yet been completely and interoperably implemented across user
- agents. In addition, there have been critiques that the interface, as
- designed, introduces a performance and implementation challenge.
-
-
- DOM4 [[!DOM]] provides a new mechanism using a
- MutationObserver interface which addresses the use cases that
- mutation events solve, but in a more performant manner. Thus, this
- specification describes mutation events for reference and completeness of
- legacy behavior, but deprecates the use of the {{MutationEvent}}
- interface.
-
-
-
-
Interface MutationEvent
-
-
Introduced in DOM Level 2, deprecated in this
- specification
-
- The MutationEvent interface provides specific contextual
- information associated with Mutation events.
-
- To create an instance of the MutationEvent interface, use
- the {{Document/createEvent()}} method call.
-
-
- relatedNode MUST be used to identify a secondary
- node related to a mutation event. For example, if a mutation
- event is dispatched to a node indicating that its parent has
- changed, the relatedNode will be the changed
- parent. If an event is instead dispatched to a subtree
- indicating a node was changed within it, the
- relatedNode MUST be the changed node. In the case
- of the EVENT{DOMAttrModified} event, it indicates the
- Attr node which was modified, added, or removed.
-
- The un-initialized value of this attribute MUST be
- null.
-
-
-
prevValue
-
- prevValue indicates the previous value of the
- Attr node in EVENT{DOMAttrModified} events, and of
- the CharacterData node in
- EVENT{DOMCharacterDataModified} events.
-
- The un-initialized value of this attribute MUST be
- "" (the empty string).
-
-
-
newValue
-
- newValue indicates the new value of the
- Attr node in EVENT{DOMAttrModified} events, and of
- the CharacterData node in
- EVENT{DOMCharacterDataModified} events.
-
- The un-initialized value of this attribute MUST be
- "" (the empty string).
-
-
-
attrName
-
- attrName indicates the name of the changed
- Attr node in a EVENT{DOMAttrModified} event.
-
- The un-initialized value of this attribute MUST be
- "" (the empty string).
-
-
-
attrChange
-
- attrChange indicates the type of change which
- triggered the EVENT{DOMAttrModified} event. The values can be
- MODIFICATION, ADDITION, or
- REMOVAL.
-
- The un-initialized value of this attribute MUST be
- 0.
-
-
- There is no defined constant for the attrChange value of 0 (the
- un-initialized value).
-
-
-
-
initMutationEvent(typeArg)
-
- Initializes attributes of a MutationEvent object.
- This method has the same behavior as {{Event/initEvent()}}.
-
-
-
DOMString typeArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
boolean bubblesArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
boolean cancelableArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
Node? relatedNodeArg
-
- Specifies {{MutationEvent}}.relatedNode.
-
-
-
DOMString prevValueArg
-
- Specifies {{MutationEvent}}.prevValue. This value MAY be the empty string.
-
-
-
DOMString newValueArg
-
- Specifies {{MutationEvent}}.newValue.
- This value MAY be the empty string.
-
-
-
DOMString attrNameArg
-
- Specifies {{MutationEvent}}.attrName.
- This value MAY be the empty string.
-
-
-
unsigned short attrChangeArg
-
- Specifies {{MutationEvent}}.attrChange.
- This value MAY be 0.
-
-
-
-
-
-
Legacy {{MutationEvent}} event types
-
- The mutation event types are listed below.
-
-
DOMAttrModified
-
-
-
-
Type
-
DOMAttrModified
-
-
-
Interface
-
{{MutationEvent}}
-
-
-
Sync / Async
-
Sync
-
-
-
Bubbles
-
Yes
-
-
-
Trusted Targets
-
Element
-
-
-
Cancelable
-
No
-
-
-
Composed
-
No
-
-
-
Default action
-
None
-
-
-
Context (trusted events)
-
-
-
{{Event}}.{{Event/target}} :
- element whose attribute is being modified
-
{{MutationEvent}}.attrName :
- the name of the changed Attr node
-
{{MutationEvent}}.attrChange :
- the numerical code corresponding to the most applicable attrChangeType
-
{{MutationEvent}}.relatedNode :
- the Attr node that has been modified, added, or removed.
-
{{MutationEvent}}.newValue :
- new value of the attribute, if the Attr node has been added or modified
-
{{MutationEvent}}.prevValue :
- previous value of the attribute, if the Attr node has been removed or modified
-
-
-
-
-
- A user agent MUST dispatch this event after an
- Attr.value has been modified and after an
- Attr node has been added to or removed from an
- Element. The event target of this event MUST be
- the Element node where the change occurred. It is
- implementation dependent whether this event type occurs when the
- children of the Attr node are changed in ways that do
- not affect the value of Attr.value.
-
-
- The EVENT{DOMAttrModified} event type is defined in this
- specification for reference and completeness, but this specification
- deprecates the use of this event type.
-
-
-
DOMCharacterDataModified
-
-
-
-
Type
-
DOMCharacterDataModified
-
-
-
Interface
-
{{MutationEvent}}
-
-
-
Sync / Async
-
Sync
-
-
-
Bubbles
-
Yes
-
-
-
Trusted Targets
-
Text, Comment, ProcessingInstruction
-
-
-
Cancelable
-
No
-
-
-
Composed
-
No
-
-
-
Default action
-
None
-
-
-
Context (trusted events)
-
-
-
{{Event}}.{{Event/target}} :
- object whose content is being modified
{{MutationEvent}}.relatedNode :
- parent node of the object whose content is being modified
-
{{MutationEvent}}.newValue :
- new value of the object
-
{{MutationEvent}}.prevValue :
- previous value of the object
-
-
-
-
-
- A user agent MUST dispatch this event after
- CharacterData.data or
- ProcessingInstruction.data have been modified, but the
- node itself has not been inserted or deleted. The event
- target of this event MUST be the CharacterData node
- or the ProcessingInstruction node.
-
-
- The EVENT{DOMCharacterDataModified} event type is defined in this
- specification for reference and completeness, but this specification
- deprecates the use of this event type.
-
-
- A user agent MUST dispatch this event type when a node other
- than an Attr node has been added as a child of another
- node. A user agent MAY dispatch this event when an
- Attr node has been added to an Element
- node (see note below). This
- event MUST be dispatched after the insertion has taken place. The
- event target of this event MUST be the node being inserted.
-
-
- For detecting attribute insertion, use the EVENT{DOMAttrModified}
- event type instead.
-
-
-
- The EVENT{DOMNodeInserted} event type is defined in this
- specification for reference and completeness, but this specification
- deprecates the use of this event type.
-
-
- A user agent MUST dispatch this event when a node has been
- inserted into a document, either through direct insertion of the
- node or insertion of a subtree in which it is contained. A user
- agent MAY treat an Attr node as part of an
- Element's subtree. This event MUST be dispatched after
- the insertion has taken place. The event target of this event
- MUST be the node being inserted. If the node is being directly
- inserted, the event type EVENT{DOMNodeInserted} MUST occur before
- this event type.
-
-
- The EVENT{DOMNodeInsertedIntoDocument} event type is defined in this
- specification for reference and completeness, but this specification
- deprecates the use of this event type.
-
-
- A user agent MUST dispatch this event when a node other than
- an Attr node is being removed from its parent node. A
- user agent MAY dispatch this event when an Attr
- node is being removed from its ownerElement (see note below). This event MUST be
- dispatched before the removal takes place. The event target
- of this event MUST be the node being removed.
-
-
- For reliably detecting attribute removal, use the
- EVENT{DOMAttrModified} event type instead.
-
-
-
- The EVENT{DOMNodeRemoved} event type is defined in this
- specification for reference and completeness, but this specification
- deprecates the use of this event type.
-
-
- A user agent MUST dispatch this event when a node is being
- removed from a document, either through direct removal of the node
- or removal of a subtree in which it is contained. A user
- agent MAY treat an Attr node as part of an
- Element's subtree. This event MUST be dispatched before
- the removal takes place. The event target of this event type
- MUST be the node being removed. If the node is being directly
- removed, the event type EVENT{DOMNodeRemoved} MUST occur before this
- event type.
-
-
- For reliably detecting attribute removal, use the
- EVENT{DOMAttrModified} event type instead.
-
-
-
- The EVENT{DOMNodeRemovedFromDocument} event type is defined in this
- specification for reference and completeness, but this specification
- deprecates the use of this event type.
-
-
- This is a general event for notification of all changes to the
- document. It can be used instead of the more specific mutation and
- mutation name events. It MAY be dispatched after a single
- modification to the document or, at the implementation's discretion,
- after multiple changes have occurred. The latter case SHOULD
- generally be used to accommodate multiple changes which occur either
- simultaneously or in rapid succession. The target of this event MUST
- be the lowest common parent of the changes which have taken place.
- This event MUST be dispatched after any other events caused by the
- mutation(s) have occurred.
-
-
- The EVENT{DOMSubtreeModified} event type is defined in this
- specification for reference and completeness, but this specification
- deprecates the use of this event type.
-
-
-
Legacy Event Initializers
-
- This section is normative.
-
- The following features are obsolete and should only be implemented by
- user agents that require compatibility with legacy software.
-
- Early versions of this specification included an initialization method on
- the interface (for example initMouseEvent) that required a long
- list of parameters that, in most cases, did not fully initialize all
- attributes of the event object. Because of this, event interfaces which were
- derived from the basic {{Event}} interface required that the initializer of
- each of the derived interfaces be called explicitly in order to
- fully initialize an event.
-
-
- Initializing all the attributes of a MutationEvent requires calls to two
- initializer methods: initEvent and
- initMutationEvent.
-
-
- Due in part to the length of time in the development of this standard, some
- implementations MAY have taken a dependency on these (now deprecated)
- initializer methods. For completeness, these legacy event initializers are
- described in this section.
-
-
- Initializes attributes of an {{UIEvent}} object.
- This method has the same behavior as {{Event/initEvent()}}.
-
-
- The initUIEvent method is deprecated, but
- supported for backwards-compatibility with widely-deployed
- implementations.
-
-
-
-
DOMString typeArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
boolean bubblesArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
boolean cancelableArg
-
- Refer to the {{Event/initEvent()}} method for a description of this parameter.
-
-
-
Window? viewArg
-
- Specifies {{UIEvent/view}}. This value MAY be null.
-
-
-
long detailArg
-
- Specifies {{UIEvent/detail}}.
-
-
-
-
-
-
Security Considerations
-
- This appendix discusses security considerations for UI Events implementations.
- The discussion is limited to security issues that arise directly from
- implementation of the event model, APIs and events defined in this
- specification. Implementations typically support other features like scripting
- languages, other APIs and additional events not defined in this document. These
- features constitute an unknown factor and are out of scope of this document.
- Implementers SHOULD consult the specifications of such features for their
- respective security considerations.
-
- Many of the event types defined in this specification are dispatched in response
- to user actions. This allows malicious event listeners to gain access to
- information users would typically consider confidential, e.g., typos they might
- have made when filling out a form, if they reconsider their answer to a multiple
- choice question shortly before submitting a form, their typing rate or primary
- input mechanism. In the worst case, malicious event listeners could capture all
- user interactions and submit them to a third party through means (not defined in
- this specification) that are generally available in DOM implementations, such as
- the XMLHttpRequest interface.
-
- In DOM implementations that support facilities to load external data, events
- like the EVENT{error} event can provide access to sensitive information about
- the environment of the computer system or network. An example would be a
- malicious HTML document that attempts to embed a resource on the local network
- or the localhost on different ports. An embedded DOM application could
- then listen for EVENT{error} and EVENT{load} events to determine which other
- computers in a network are accessible from the local system or which ports are
- open on the system to prepare further attacks.
-
- An implementation of UI Events alone is generally insufficient to perform
- attacks of this kind and the security considerations of the facilities that
- possibly support such attacks apply. For conformance with this specification,
- DOM implementations MAY take reasonable steps to ensure that DOM
- applications do not get access to confidential or sensitive information. For
- example, they might choose not to dispatch EVENT{load} events to nodes that
- attempt to embed resources on the local network.
-
-
Acknowledgements
-
- Many people contributed to the DOM specifications (Level 1, 2 or 3),
- including participants of the DOM Working Group, the DOM Interest Group,
- the WebAPI Working Group, and the WebApps Working Group.
-
- We especially thank the following:
- Andrew Watson (Object Management Group),
- Andy Heninger (IBM),
- Angel Diaz (IBM),
- Anne van Kesteren (Opera Software),
- Arnaud Le Hors (W3C and IBM),
- Arun Ranganathan (AOL),
- Ashok Malhotra (IBM and Microsoft),
- Ben Chang (Oracle),
- Bill Shea (Merrill Lynch),
- Bill Smith (Sun),
- Björn Höhrmann,
- Bob Sutor (IBM),
- Charles McCathie-Nevile (Opera Software, Co-Chair),
- Chris Lovett (Microsoft),
- Chris Wilson (Microsoft),
- Christophe Jolif (ILOG),
- David Brownell (Sun),
- David Ezell (Hewlett-Packard Company),
- David Singer (IBM),
- Dean Jackson (W3C, W3C Team Contact),
- Dimitris Dimitriadis (Improve AB and invited expert),
- Don Park (invited),
- Doug Schepers (Vectoreal),
- Elena Litani (IBM),
- Eric Vasilik (Microsoft),
- Gavin Nicol (INSO),
- Gorm Haug Eriksen (Opera Software),
- Ian Davis (Talis Information Limited),
- Ian Hickson (Google),
- Ian Jacobs (W3C),
- James Clark (invited),
- James Davidson (Sun),
- Jared Sorensen (Novell),
- Jeroen van Rotterdam (X-Hive Corporation),
- Joe Kesselman (IBM),
- Joe Lapp (webMethods),
- Joe Marini (Macromedia),
- John Robinson (AOL),
- Johnny Stenback (Netscape/AOL),
- Jon Ferraiolo (Adobe),
- Jonas Sicking (Mozilla Foundation),
- Jonathan Marsh (Microsoft),
- Jonathan Robie (Texcel Research and Software AG),
- Kim Adamson-Sharpe (SoftQuad Software Inc.),
- Lauren Wood (SoftQuad Software Inc., former Chair),
- Laurence Cable (Sun),
- Luca Mascaro (HTML Writers Guild),
- Maciej Stachowiak (Apple Computer),
- Marc Hadley (Sun Microsystems),
- Mark Davis (IBM),
- Mark Scardina (Oracle),
- Martin Dürst (W3C),
- Mary Brady (NIST),
- Michael Shenfield (Research In Motion),
- Mick Goulish (Software AG),
- Mike Champion (Arbortext and Software AG),
- Miles Sabin (Cromwell Media),
- Patti Lutsky (Arbortext),
- Paul Grosso (Arbortext),
- Peter Sharpe (SoftQuad Software Inc.),
- Phil Karlton (Netscape),
- Philippe Le Hégaret (W3C, W3C Team Contact and former Chair),
- Ramesh Lekshmynarayanan (Merrill Lynch),
- Ray Whitmer (iMall, Excite@Home, and Netscape/AOL, Chair),
- Rezaur Rahman (Intel),
- Rich Rollman (Microsoft),
- Rick Gessner (Netscape),
- Rick Jelliffe (invited),
- Rob Relyea (Microsoft),
- Robin Berjon (Expway, Co-Chair),
- Scott Hayman (Research In Motion),
- Scott Isaacs (Microsoft),
- Sharon Adler (INSO),
- Stéphane Sire (IntuiLab),
- Steve Byrne (JavaSoft),
- Tim Bray (invited),
- Tim Yu (Oracle),
- Tom Pixley (Netscape/AOL),
- T.V. Raman (Google).
- Vidur Apparao (Netscape) and
- Vinod Anupam (Lucent).
-
- Former editors:
- Tom Pixley (Netscape Communications Corporation) until July 2002;
- Philippe Le Hégaret (W3C) until November 2003;
- Björn Höhrmann (Invited Expert) until January 2008;
- and Jacob Rossi (Microsoft) from March 2011 to October 2011.
-
- Contributors:
- In the WebApps Working Group, the following people made substantial
- material contributions in the process of refining and revising this
- specification:
- Bob Lund (Cable Laboratories),
- Cameron McCormack (Invited Expert / Mozilla),
- Daniel Danilatos (Google),
- Gary Kacmarcik (Google),
- Glenn Adams (Samsung),
- Hallvord R. M. Steen (Opera),
- Hironori Bono (Google),
- Mark Vickers (Comcast),
- Masayuki Nakano (Mozilla),
- Olli Pettay (Mozilla),
- Takayoshi Kochi (Google) and
- Travis Leithead (Microsoft).
-
- Glossary contributors:
- Arnaud Le Hors (W3C) and
- Robert S. Sutor (IBM Research).
-
- Test suite contributors:
- Carmelo Montanez (NIST),
- Fred Drake,
- Mary Brady (NIST),
- Neil Delima (IBM),
- Rick Rivello (NIST),
- Robert Clary (Netscape),
- with a special mention to Curt Arnold.
-
- Thanks to all those who have helped to improve this specification by
- sending suggestions and corrections (please, keep bugging us with your
- issues!), or writing informative books or Web sites:
- Al Gilman,
- Alex Russell,
- Alexander J. Vincent,
- Alexey Proskuryakov,
- Arkadiusz Michalski,
- Brad Pettit,
- Cameron McCormack,
- Chris Rebert,
- Curt Arnold,
- David Flanagan,
- Dylan Schiemann,
- Erik Arvidsson,
- Garrett Smith,
- Giuseppe Pascale,
- James Su,
- Jan Goyvaerts (regular-expressions.info),
- Jorge Chamorro,
- Kazuyuki Ashimura,
- Ken Rehor,
- Magnus Kristiansen,
- Martijn Wargers,
- Martin Dürst,
- Michael B. Allen,
- Mike Taylor,
- Misha Wolf,
- Ojan Vafai,
- Oliver Hunt,
- Paul Irish,
- Peter-Paul Koch,
- Richard Ishida,
- Sean Hogan,
- Sergey Ilinsky,
- Sigurd Lerstad,
- Steven Pemberton,
- Tony Chang,
- William Edney and
- Øistein E. Andersen.
-
-
Refs to other UIEvent specs \[DELETE]
-
- This section will be deleted.
-
- Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
-
Things defined in other sections
-
-
Activation triggers and behavior
-
Composition Events
-
Default actions and cancelable events
-
Event dispatch and DOM event flow
-
Focus Events
-
Web browsers and other dynamic or interactive user agents
-
Authoring tools
-
- Add references to these events so that the linker doesn't complain about exporting them.
-
- EVENT{unload}, EVENT{load}, EVENT{abort}, EVENT{error}
-
-
-
Glossary \[DELETE]
-
-This section will be deleted.
-
-Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-: host language
-:: Any language which integrates the features of another language or API
- specification, while normatively referencing the origin specification rather
- than redefining those features, and extending those features only in ways
- defined by the origin specification. An origin specification typically is
- only intended to be implemented in the context of one or more host
- languages, not as a standalone language. For example, XHTML, HTML, and SVG
- are host languages for UI Events, and they integrate and extend the objects
- and models defined in this specification.
-
-: un-initialized value
-:: The value of any event attribute (such as {{Event/bubbles}} or
- {{Event/currentTarget}}) before the event has been initialized with
- {{Event/initEvent()}}. The un-initialized values of an event apply
- immediately after a new event has been created using the method
- {{Document/createEvent()}}.
-
-: user agent
-:: A program, such as a browser or content authoring tool, normally running on
- a client machine, which acts on a user's behalf in retrieving, interpreting,
- executing, presenting, or creating content. Users MAY act on the content
- using different user agents at different times, for different purposes. See
- the [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the
- requirements for a conforming user agent.
-
-: Window
-:: The Window is the object referred to by the current document's
- browsing context's Window Proxy object as defined in
- HTML5
- [[HTML5]].
-
diff --git a/split/wheel-events.bs b/split/wheel-events.bs
deleted file mode 100644
index 322e536..0000000
--- a/split/wheel-events.bs
+++ /dev/null
@@ -1,489 +0,0 @@
-
Wheel Events
-
-
-Shortname: wheel-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
- *** Wheel Events ***
-
- Note: This is an experimental split of the UI Events spec into smaller, event-specific
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
- interface Example {
- // This is an IDL definition.
- };
-
-
-
Wheel Events
-
- Wheels are devices that can be rotated in one or more spatial dimensions, and which can be associated with a pointer device. The coordinate system depends on the
- environment configuration.
-
-
- The user's environment might be configured to associate vertical scrolling
- with rotation along the y-axis, horizontal scrolling with rotation along the
- x-axis, and zooming with rotation along the z-axis.
-
-
- The deltaX, deltaY, and deltaZ attributes of {{WheelEvent}} objects indicate
- a measurement along their respective axes in units of pixels, lines, or
- pages. The reported measurements are provided after an environment-specific
- algorithm translates the actual rotation/movement of the wheel device into
- the appropriate values and units.
-
-
- A user's environment settings can be customized to interpret actual rotation/movement
- of a wheel device in different ways.
- One movement of a common dented mouse wheel can produce a measurement of 162 pixels
- (162 is just an example value, actual values can depend on the current screen
- dimensions of the user-agent).
- But a user can change their default environment settings to speed-up their mouse wheel,
- increasing this number.
- Furthermore, some mouse wheel software can support acceleration (the faster the wheel
- is rotated/moved, the greater the delta of each measurement) or even sub-pixel rotation
- measurements.
- Because of this, authors can not assume a given rotation amount in one user agent will
- produce the same delta value in all user agents.
-
-
- The sign (positive or negative) of the values of the deltaX, deltaY, and deltaZ attributes
- MUST be consistent between multiple dispatches of the
- wheel event while the
- motion of the actual wheel device is rotating/moving in the same direction.
- If a user agent scrolls as the default action of the
- wheel event then the sign
- of the delta SHOULD be given by a right-hand coordinate system where positive X,
- Y, and Z axes are directed towards the right-most edge, bottom-most edge, and farthest
- depth (away from the user) of the document, respectively.
-
-
- Individual user agents can (depending on their environment and hardware configuration)
- interpret the same physical user interaction on the wheel differently.
- For example, a vertical swipe on the edge of a trackpad from top to bottom can be
- interpreted as a wheel action intended to either scroll the
- page down or to pan the page up (i.e., resulting in either a positive or negative
- deltaY value respectively).
-
-
- A user agent MUST create a wheel event transaction when the first wheel event
- is fired, so that all subsequent wheel events within a implementation-specific amount of
- time can be targetted at the same element. A wheel event transaction is series of
- wheel events that are associated with a single user gesture. The
- wheel event transaction MUST have an associated event target that is the
- topmost event target at the time the first wheel event occurs in the group.
-
-
- If a series of wheel events targetted in a scrollable element start above a child element,
- later events for the same user gesture may occur over the child element.
-
-
-
Interface WheelEvent
-
-
Introduced in this specification
-
- The {{WheelEvent}} interface provides specific contextual information
- associated with wheel events.
-
- To create an instance of the {{WheelEvent}} interface, use the {{WheelEvent}} constructor,
- passing an optional {{WheelEventInit}} dictionary.
-
-
- The units of measurement for the delta MUST be pixels.
- This is the most typical case in most operating system and
- implementation configurations.
-
-
-
DOM_DELTA_LINE
-
- The units of measurement for the delta MUST be individual
- lines of text. This is the case for many form controls.
-
-
-
DOM_DELTA_PAGE
-
- The units of measurement for the delta MUST be pages,
- either defined as a single screen or as a demarcated page.
-
-
-
deltaX
-
- In user agents where the default action of the wheel
- event is to scroll, the value MUST be the measurement along the
- x-axis (in pixels, lines, or pages) to be scrolled in the case
- where the event is not cancelled. Otherwise, this is an
- implementation-specific measurement (in pixels, lines, or pages)
- of the movement of a wheel device around the x-axis.
-
- The un-initialized value of this attribute MUST be
- 0.0.
-
-
-
deltaY
-
- In user agents where the default action of the wheel
- event is to scroll, the value MUST be the measurement along the
- y-axis (in pixels, lines, or pages) to be scrolled in the case
- where the event is not cancelled. Otherwise, this is an
- implementation-specific measurement (in pixels, lines, or pages)
- of the movement of a wheel device around the y-axis.
-
- The un-initialized value of this attribute MUST be
- 0.0.
-
-
-
deltaZ
-
- In user agents where the default action of the wheel
- event is to scroll, the value MUST be the measurement along the
- z-axis (in pixels, lines, or pages) to be scrolled in the case
- where the event is not cancelled. Otherwise, this is an
- implementation-specific measurement (in pixels, lines, or pages)
- of the movement of a wheel device around the z-axis.
-
- The un-initialized value of this attribute MUST be
- 0.0.
-
-
-
deltaMode
-
- The deltaMode attribute contains an indication of
- the units of measurement for the delta values. The
- default value is {{WheelEvent/DOM_DELTA_PIXEL}} (pixels).
-
- This attribute MUST be set to one of the DOM_DELTA constants to
- indicate the units of measurement for the delta values.
- The precise measurement is specific to device, operating system,
- and application configurations.
-
- The un-initialized value of this attribute MUST be
- 0.
-
- 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.
-
{{MouseEvent}}.{{MouseEvent/screenX}} : if the wheel is associated with a pointing device, the value based on the pointer position on the screen, otherwise 0
{{MouseEvent}}.{{MouseEvent/screenY}} : if the wheel is associated with a pointing device, the value based on the pointer position on the screen, otherwise 0
{{MouseEvent}}.{{MouseEvent/clientX}} : if the wheel is associated with a pointing device, the value based on the pointer position within the viewport, otherwise 0
{{MouseEvent}}.{{MouseEvent/clientY}} : if the wheel is associated with a pointing device, the value based on the pointer position within the viewport, otherwise 0
{{MouseEvent}}.{{MouseEvent/altKey}} : true if Alt modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/ctrlKey}} : true if Control modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/shiftKey}} : true if Shift modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/metaKey}} : true if Meta modifier was active, otherwise false
{{MouseEvent}}.{{MouseEvent/button}} : if wheel is associated with a pointing device, value based on current button pressed, otherwise 0
{{MouseEvent}}.{{MouseEvent/buttons}} : if wheel is associated with a pointing device, value based on all buttons current depressed, 0 if no buttons pressed
{{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the event target the pointing device is pointing at, if any
{{WheelEvent}}.{{WheelEvent/deltaX}} : expected amount that the page will scroll along the x-axis according to the deltaMode units; or an implementation-specific value of movement of a wheel around the x-axis
{{WheelEvent}}.{{WheelEvent/deltaY}} : expected amount that the page will scroll along the y-axis according to the deltaMode units; or an implementation-specific value of movement of a wheel around the y-axis
{{WheelEvent}}.{{WheelEvent/deltaZ}} : expected amount that the page will scroll along the z-axis according to the deltaMode units; or an implementation-specific value of movement of a wheel around the z-axis
{{WheelEvent}}.{{WheelEvent/deltaMode}} : unit indicator (pixels, lines, or pages) for the deltaX, deltaY, and deltaZ attributes
-
-
- A user agent MUST dispatch this event when a mouse wheel has
- been rotated around any axis, or when an equivalent input device
- (such as a mouse-ball, certain tablets or touchpads, etc.) has
- emulated such an action. Depending on the platform and input device,
- diagonal wheel deltas MAY be delivered either as a single
- wheel event with multiple non-zero axes or as separate
- wheel events for each non-zero axis.
-
- The typical default action of the wheel event type is
- to scroll (or in some cases, zoom) the document by the indicated
- amount. If this event is canceled, the implementation MUST NOT
- scroll or zoom the document (or perform whatever other
- implementation-specific default action is associated with this event
- type).
-
-
- In some user agents, or with some input devices, the speed
- that the wheel has been turned can affect the delta values,
- with a faster speed producing a higher delta value.
-
-
-
cancelability of wheel events
-
- Calling preventDefault on a wheel event can prevent
- or otherwise interrupt scrolling. For maximum scroll performance, a
- user agent may not wait for each wheel event associated with the scroll
- to be processed to see if it will be canceled. In such cases the user
- agent should generate wheel events whose
- cancelable property is false, indicating that
- preventDefault cannot be used to prevent or interrupt
- scrolling. Otherwise cancelable will be true.
-
-
- TODO - Add specific concerns for this spec
-
-
Acknowledgements
-
- TODO
-
-
Refs to other UIEvent specs \[DELETE]
-
- This section will be deleted.
-
- Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
-
Things defined in other sections
-
-
Activation triggers and behavior
-
Composition Events
-
Default actions and cancelable events
-
Event dispatch and DOM event flow
-
Focus Events
-
Web browsers and other dynamic or interactive user agents
-
Authoring tools
-
-
Glossary \[DELETE]
-
-This section will be deleted.
-
-Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-: activation behavior
-:: The action taken when an event, typically initiated by users through
- an input device, causes an element to fulfill a defined task. The task MAY
- be defined for that element by the host language, or by
- author-defined variables, or both. The default task for any given element
- MAY be a generic action, or MAY be unique to that element. For example, the
- activation behavior of an HTML or SVG <a> element is to
- cause the user agent to traverse the link specified in the
- href attribute, with the further optional parameter of
- specifying the browsing context for the traversal (such as the current
- window or tab, a named window, or a new window). The activation behavior of
- an HTML <input> element with the type
- attribute value submit is be to send the values of the form
- elements to an author-defined IRI by the author-defined HTTP method. See
- [[#event-flow-activation]] for more details.
-
-: activation trigger
-:: An event which is defined to initiate an activation behavior. Refer
- to [[#event-flow-activation]] for more details.
-
-: default action
-:: A default action is an OPTIONAL supplementary behavior that an
- implementation MUST perform in combination with the dispatch of the event
- object. Each event type definition, and each specification, defines the
- default action for that event type, if it has one. An instance of an
- event MAY have more than one default action under some circumstances,
- such as when associated with an activation trigger. A default
- action MAY be cancelled through the invocation of the
- {{Event/preventDefault()}} method. For more details, see
- [[#event-flow-default-cancel]].
-
-: delta
-:: The estimated scroll amount (in pixels, lines, or pages) that the user agent
- will scroll or zoom the page in response to the physical movement of an
- input device that supports the {{WheelEvent}} interface (such as a mouse
- wheel or touch pad). The value of a delta (e.g., the
- {{WheelEvent/deltaX}}, {{WheelEvent/deltaY}}, or {{WheelEvent/deltaZ}}
- attributes) is to be interpreted in the context of the current
- {{WheelEvent/deltaMode}} property. The relationship between the physical
- movement of a wheel (or other device) and whether the delta is
- positive or negative is environment and device dependent. However, if a user
- agent scrolls as the default action then the sign of the delta
- is given by a right-hand coordinate system where positive X,Y, and Z axes
- are directed towards the right-most edge, bottom-most edge, and farthest
- depth (away from the user) of the document, respectively.
-
-: event
-:: An event is the representation of some occurrence (such as a mouse click on
- the presentation of an element, the removal of child node from an element,
- or any number of other possibilities) which is associated with its event
- target. Each event is an instantiation of one specific event
- type.
-
-: event target
-:: The object to which an event is targeted using the [[#event-flow]].
- The event target is the value of the {{Event/target}} attribute.
-
-: host language
-:: Any language which integrates the features of another language or API
- specification, while normatively referencing the origin specification rather
- than redefining those features, and extending those features only in ways
- defined by the origin specification. An origin specification typically is
- only intended to be implemented in the context of one or more host
- languages, not as a standalone language. For example, XHTML, HTML, and SVG
- are host languages for UI Events, and they integrate and extend the objects
- and models defined in this specification.
-
-: rotation
-:: An indication of incremental change on an input device using the
- {{WheelEvent}} interface. On some devices this MAY be a literal rotation of
- a wheel, while on others, it MAY be movement along a flat surface, or
- pressure on a particular button.
-
-: topmost event target
-:: The topmost event target MUST be the element highest in the rendering
- order which is capable of being an event target. In graphical user
- interfaces this is the element under the user's pointing device. A user
- interface's hit testing facility is used to determine the target. For
- specific details regarding hit testing and stacking order, refer to the
- host language.
-
-: un-initialized value
-:: The value of any event attribute (such as {{Event/bubbles}} or
- {{Event/currentTarget}}) before the event has been initialized with
- {{Event/initEvent()}}. The un-initialized values of an event apply
- immediately after a new event has been created using the method
- {{Document/createEvent()}}.
-
-: user agent
-:: A program, such as a browser or content authoring tool, normally running on
- a client machine, which acts on a user's behalf in retrieving, interpreting,
- executing, presenting, or creating content. Users MAY act on the content
- using different user agents at different times, for different purposes. See
- the [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the
- requirements for a conforming user agent.
-
-: Window
-:: The Window is the object referred to by the current document's
- browsing context's Window Proxy object as defined in
- HTML5
- [[HTML5]].
-
-
diff --git a/split/wheel-events.html b/split/wheel-events.html
deleted file mode 100644
index b06268c..0000000
--- a/split/wheel-events.html
+++ /dev/null
@@ -1,1640 +0,0 @@
-
-
-
-
- Wheel Events
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Note: This is an experimental split of the UI Events spec into smaller, event-specific
-
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
-
Status of this document
-
-
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
-
This document was published by the Web Applications Working Group as an Editors Draft. This document is intended to become a W3C Recommendation.
Publication as an Editors Draft does not imply endorsement by W3C and its Members. This is a draft document and may
- be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite
- this document as other than work in progress.
-
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
interface Example {
- // This is an IDL definition.
-};
-
-
3. Wheel Events
-
Wheels are devices that can be rotated in one or more spatial dimensions, and which can be associated with a pointer device. The coordinate system depends on the
- environment configuration.
-
The user’s environment might be configured to associate vertical scrolling
- with rotation along the y-axis, horizontal scrolling with rotation along the
- x-axis, and zooming with rotation along the z-axis.
-
The deltaX, deltaY, and deltaZ attributes of WheelEvent objects indicate
- a measurement along their respective axes in units of pixels, lines, or
- pages. The reported measurements are provided after an environment-specific
- algorithm translates the actual rotation/movement of the wheel device into
- the appropriate values and units.
-
A user’s environment settings can be customized to interpret actual rotation/movement
- of a wheel device in different ways.
- One movement of a common dented mouse wheel can produce a measurement of 162 pixels
- (162 is just an example value, actual values can depend on the current screen
- dimensions of the user-agent).
- But a user can change their default environment settings to speed-up their mouse wheel,
- increasing this number.
- Furthermore, some mouse wheel software can support acceleration (the faster the wheel
- is rotated/moved, the greater the delta of each measurement) or even sub-pixel rotation measurements.
- Because of this, authors can not assume a given rotation amount in one user agent will
- produce the same delta value in all user agents.
-
The sign (positive or negative) of the values of the deltaX, deltaY, and deltaZ attributes
- MUST be consistent between multiple dispatches of the wheel event while the
- motion of the actual wheel device is rotating/moving in the same direction.
- If a user agent scrolls as the default action of the wheel event then the sign
- of the delta SHOULD be given by a right-hand coordinate system where positive X,
- Y, and Z axes are directed towards the right-most edge, bottom-most edge, and farthest
- depth (away from the user) of the document, respectively.
-
Individual user agents can (depending on their environment and hardware configuration)
- interpret the same physical user interaction on the wheel differently.
- For example, a vertical swipe on the edge of a trackpad from top to bottom can be
- interpreted as a wheel action intended to either scroll the
- page down or to pan the page up (i.e., resulting in either a positive or negative
- deltaY value respectively).
-
A user agent MUST create a wheel event transaction when the first wheel event
- is fired, so that all subsequent wheel events within a implementation-specific amount of
- time can be targetted at the same element. A wheel event transaction is series of
- wheel events that are associated with a single user gesture. The wheel event transaction MUST have an associated event target that is the topmost event target at the time the first wheel event occurs in the group.
-
If a series of wheel events targetted in a scrollable element start above a child element,
- later events for the same user gesture may occur over the child element.
-
3.1. Interface WheelEvent
-
Introduced in this specification
-
The WheelEvent interface provides specific contextual information
- associated with wheel events.
- In user agents where the default action of the wheel event is to scroll, the value MUST be the measurement along the
- x-axis (in pixels, lines, or pages) to be scrolled in the case
- where the event is not cancelled. Otherwise, this is an
- implementation-specific measurement (in pixels, lines, or pages)
- of the movement of a wheel device around the x-axis.
-
- In user agents where the default action of the wheel event is to scroll, the value MUST be the measurement along the
- y-axis (in pixels, lines, or pages) to be scrolled in the case
- where the event is not cancelled. Otherwise, this is an
- implementation-specific measurement (in pixels, lines, or pages)
- of the movement of a wheel device around the y-axis.
-
- In user agents where the default action of the wheel event is to scroll, the value MUST be the measurement along the
- z-axis (in pixels, lines, or pages) to be scrolled in the case
- where the event is not cancelled. Otherwise, this is an
- implementation-specific measurement (in pixels, lines, or pages)
- of the movement of a wheel device around the z-axis.
-
- The deltaMode attribute contains an indication of
- the units of measurement for the delta values. The
- default value is DOM_DELTA_PIXEL (pixels).
-
This attribute MUST be set to one of the DOM_DELTA constants to
- indicate the units of measurement for the delta values.
- The precise measurement is specific to device, operating system,
- and application configurations.
Initializes the deltaZ attribute of the WheelEvent object. Relative positive values for this attribute (as well as
- the deltaX and deltaY attributes) are
- given by a right-hand coordinate system where the X, Y, and Z
- axes are directed towards the right-most edge, bottom-most edge,
- and farthest depth (away from the user) of the document,
- respectively. Negative relative values are in the respective
- opposite directions.
-
Initializes the deltaMode attribute on the WheelEvent object to the enumerated values 0, 1, or 2, which
- represent the amount of pixels scrolled
- (DOM_DELTA_PIXEL), lines scrolled
- (DOM_DELTA_LINE), or pages scrolled
- (DOM_DELTA_PAGE) if the rotation of the
- wheel would have resulted in scrolling.
-
WheelEvent.deltaX : expected amount that the page will scroll along the x-axis according to the deltaMode units; or an implementation-specific value of movement of a wheel around the x-axis
-
WheelEvent.deltaY : expected amount that the page will scroll along the y-axis according to the deltaMode units; or an implementation-specific value of movement of a wheel around the y-axis
-
WheelEvent.deltaZ : expected amount that the page will scroll along the z-axis according to the deltaMode units; or an implementation-specific value of movement of a wheel around the z-axis
-
WheelEvent.deltaMode : unit indicator (pixels, lines, or pages) for the deltaX, deltaY, and deltaZ attributes
-
-
-
A user agent MUST dispatch this event when a mouse wheel has
- been rotated around any axis, or when an equivalent input device
- (such as a mouse-ball, certain tablets or touchpads, etc.) has
- emulated such an action. Depending on the platform and input device,
- diagonal wheel deltas MAY be delivered either as a single wheel event with multiple non-zero axes or as separate wheel events for each non-zero axis.
-
The typical default action of the wheel event type is
- to scroll (or in some cases, zoom) the document by the indicated
- amount. If this event is canceled, the implementation MUST NOT
- scroll or zoom the document (or perform whatever other
- implementation-specific default action is associated with this event
- type).
-
In some user agents, or with some input devices, the speed
- that the wheel has been turned can affect the delta values,
- with a faster speed producing a higher delta value.
-
3.2.2. cancelability of wheel events
-
Calling preventDefault on a wheel event can prevent
- or otherwise interrupt scrolling. For maximum scroll performance, a
- user agent may not wait for each wheel event associated with the scroll
- to be processed to see if it will be canceled. In such cases the user
- agent should generate wheel events whose cancelable property is false, indicating that preventDefault cannot be used to prevent or interrupt
- scrolling. Otherwise cancelable will be true.
Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
6.1. Things defined in other sections
-
6.1.1. Activation triggers and behavior
-
6.1.2. Composition Events
-
6.1.3. Default actions and cancelable events
-
6.1.4. Event dispatch and DOM event flow
-
6.1.5. Focus Events
-
6.1.6. Web browsers and other dynamic or interactive user agents
-
6.1.7. Authoring tools
-
7. Glossary [DELETE]
-
This section will be deleted.
-
Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-
activation behavior
-
-
The action taken when an event, typically initiated by users through
-an input device, causes an element to fulfill a defined task. The task MAY
-be defined for that element by the host language, or by
-author-defined variables, or both. The default task for any given element
-MAY be a generic action, or MAY be unique to that element. For example, the
-activation behavior of an HTML or SVG <a> element is to
-cause the user agent to traverse the link specified in the href attribute, with the further optional parameter of
-specifying the browsing context for the traversal (such as the current
-window or tab, a named window, or a new window). The activation behavior of
-an HTML <input> element with the type attribute value submit is be to send the values of the form
-elements to an author-defined IRI by the author-defined HTTP method. See § 6.1.1 Activation triggers and behavior for more details.
A default action is an OPTIONAL supplementary behavior that an
-implementation MUST perform in combination with the dispatch of the event
-object. Each event type definition, and each specification, defines the default action for that event type, if it has one. An instance of an
-event MAY have more than one default action under some circumstances,
-such as when associated with an activation trigger. A default
-action MAY be cancelled through the invocation of the preventDefault() method. For more details, see § 6.1.3 Default actions and cancelable events.
-
delta
-
-
The estimated scroll amount (in pixels, lines, or pages) that the user agent
-will scroll or zoom the page in response to the physical movement of an
-input device that supports the WheelEvent interface (such as a mouse
-wheel or touch pad). The value of a delta (e.g., the deltaX, deltaY, or deltaZ attributes) is to be interpreted in the context of the current deltaMode property. The relationship between the physical
-movement of a wheel (or other device) and whether the delta is
-positive or negative is environment and device dependent. However, if a user
-agent scrolls as the default action then the sign of the delta is given by a right-hand coordinate system where positive X,Y, and Z axes
-are directed towards the right-most edge, bottom-most edge, and farthest
-depth (away from the user) of the document, respectively.
-
event
-
-
An event is the representation of some occurrence (such as a mouse click on
-the presentation of an element, the removal of child node from an element,
-or any number of other possibilities) which is associated with its event
-target. Each event is an instantiation of one specific event
-type.
Any language which integrates the features of another language or API
-specification, while normatively referencing the origin specification rather
-than redefining those features, and extending those features only in ways
-defined by the origin specification. An origin specification typically is
-only intended to be implemented in the context of one or more host
-languages, not as a standalone language. For example, XHTML, HTML, and SVG
-are host languages for UI Events, and they integrate and extend the objects
-and models defined in this specification.
-
rotation
-
-
An indication of incremental change on an input device using the WheelEvent interface. On some devices this MAY be a literal rotation of
-a wheel, while on others, it MAY be movement along a flat surface, or
-pressure on a particular button.
-
topmost event target
-
-
The topmost event target MUST be the element highest in the rendering
-order which is capable of being an event target. In graphical user
-interfaces this is the element under the user’s pointing device. A user
-interface’s hit testing facility is used to determine the target. For
-specific details regarding hit testing and stacking order, refer to the host language.
-
un-initialized value
-
-
The value of any event attribute (such as bubbles or currentTarget) before the event has been initialized with initEvent(). The un-initialized values of an event apply
-immediately after a new event has been created using the method createEvent().
-
user agent
-
-
A program, such as a browser or content authoring tool, normally running on
-a client machine, which acts on a user’s behalf in retrieving, interpreting,
-executing, presenting, or creating content. Users MAY act on the content
-using different user agents at different times, for different purposes. See
-the § 6.1.6 Web browsers and other dynamic or interactive user agents and § 6.1.7 Authoring tools for details on the
-requirements for a conforming user agent.
-
Window
-
-
The Window is the object referred to by the current document’s
-browsing context’s Window Proxy object as defined in HTML5[HTML5].
-
-
-
-
Conformance
-
Document conventions
-
Conformance requirements are expressed
- with a combination of descriptive assertions
- and RFC 2119 terminology.
- The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”
- in the normative parts of this document
- are to be interpreted as described in RFC 2119.
- However, for readability,
- these words do not appear in all uppercase letters in this specification.
-
All of the text of this specification is normative
- except sections explicitly marked as non-normative, examples, and notes. [RFC2119]
-
Examples in this specification are introduced with the words “for example”
- or are set apart from the normative text
- with class="example",
- like this:
-
-
-
This is an example of an informative example.
-
-
Informative notes begin with the word “Note”
- and are set apart from the normative text
- with class="note",
- like this:
-
Note, this is an informative note.
-
-
Conformant Algorithms
-
Requirements phrased in the imperative as part of algorithms
- (such as "strip any leading space characters"
- or "return false and abort these steps")
- are to be interpreted with the meaning of the key word
- ("must", "should", "may", etc)
- used in introducing the algorithm.
-
Conformance requirements phrased as algorithms or specific steps
- can be implemented in any manner,
- so long as the end result is equivalent.
- In particular, the algorithms defined in this specification
- are intended to be easy to understand
- and are not intended to be performant.
- Implementers are encouraged to optimize.
-
-
-
\ No newline at end of file
diff --git a/split/wheel-events.txt b/split/wheel-events.txt
deleted file mode 100644
index 52ae103..0000000
--- a/split/wheel-events.txt
+++ /dev/null
@@ -1,534 +0,0 @@
-
Wheel Events
-
-
-Shortname: wheel-events
-Level:
-Group: webapps
-Status: ED
-TR: https://www.w3.org/TR/uievents/
-ED: https://w3c.github.io/uievents/
-Repository: w3c/uievents
-Editor: Gary Kacmarcik 59482, Google, garykac@google.com
-Editor: Travis Leithead 40117, Microsoft, travil@microsoft.com
-Former Editor: Doug Schepers, Mar 2008 - May 2011
-!Tests: web-platform-tests uievents/ (ongoing work)
-Abstract:
- *** Wheel Events ***
-
- Note: This is an experimental split of the UI Events spec into smaller, event-specific
- specs. The split was made from an out-of-date snapshot, so the information here is not
- current, so please focus on the overall structure rather than the specifics of the
- content. If this experiment goes well, then we will split the current spec after all
- outstanding pull requests have been handled.
-
- interface Example {
- // This is an IDL definition.
- };
-
-
-
Wheel Events
-
- Wheels are devices that can be rotated in one or more spatial dimensions, and which can be associated with a pointer device. The coordinate system depends on the
- environment configuration.
-
-
- The user's environment might be configured to associate vertical scrolling
- with rotation along the y-axis, horizontal scrolling with rotation along the
- x-axis, and zooming with rotation along the z-axis.
-
-
- The deltaX, deltaY, and deltaZ attributes of {{WheelEvent}} objects indicate
- a measurement along their respective axes in units of pixels, lines, or
- pages. The reported measurements are provided after an environment-specific
- algorithm translates the actual rotation/movement of the wheel device into
- the appropriate values and units.
-
-
- A user's environment settings can be customized to interpret actual rotation/movement
- of a wheel device in different ways.
- One movement of a common dented mouse wheel can produce a measurement of 162 pixels
- (162 is just an example value, actual values can depend on the current screen
- dimensions of the user-agent).
- But a user can change their default environment settings to speed-up their mouse wheel,
- increasing this number.
- Furthermore, some mouse wheel software can support acceleration (the faster the wheel
- is rotated/moved, the greater the delta of each measurement) or even sub-pixel rotation
- measurements.
- Because of this, authors can not assume a given rotation amount in one user agent will
- produce the same delta value in all user agents.
-
-
- The sign (positive or negative) of the values of the deltaX, deltaY, and deltaZ attributes
- MUST be consistent between multiple dispatches of the
- EVENT{wheel} event while the
- motion of the actual wheel device is rotating/moving in the same direction.
- If a user agent scrolls as the default action of the
- EVENT{wheel} event then the sign
- of the delta SHOULD be given by a right-hand coordinate system where positive X,
- Y, and Z axes are directed towards the right-most edge, bottom-most edge, and farthest
- depth (away from the user) of the document, respectively.
-
-
- Individual user agents can (depending on their environment and hardware configuration)
- interpret the same physical user interaction on the wheel differently.
- For example, a vertical swipe on the edge of a trackpad from top to bottom can be
- interpreted as a wheel action intended to either scroll the
- page down or to pan the page up (i.e., resulting in either a positive or negative
- deltaY value respectively).
-
-
- A user agent MUST create a wheel event transaction when the first wheel event
- is fired, so that all subsequent wheel events within a implementation-specific amount of
- time can be targetted at the same element. A wheel event transaction is series of
- wheel events that are associated with a single user gesture. The
- wheel event transaction MUST have an associated event target that is the
- topmost event target at the time the first wheel event occurs in the group.
-
-
- If a series of wheel events targetted in a scrollable element start above a child element,
- later events for the same user gesture may occur over the child element.
-
-
-
Interface WheelEvent
-
-
Introduced in this specification
-
- The {{WheelEvent}} interface provides specific contextual information
- associated with EVENT{wheel} events.
-
- To create an instance of the {{WheelEvent}} interface, use the {{WheelEvent}} constructor,
- passing an optional {{WheelEventInit}} dictionary.
-
-
- 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.
-
- 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.
-
{{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.
-
-
- TODO - Add specific concerns for this spec
-
-
Acknowledgements
-
- TODO
-
-
Refs to other UIEvent specs \[DELETE]
-
- This section will be deleted.
-
- Temporary place to "define" other referenced UI Events (to make the bikeshed linker happy).
- This will be deleted once we have proper cross-references.
-
-
Things defined in other sections
-
-
Activation triggers and behavior
-
Composition Events
-
Default actions and cancelable events
-
Event dispatch and DOM event flow
-
Focus Events
-
Web browsers and other dynamic or interactive user agents
-
Authoring tools
-
-
Glossary \[DELETE]
-
-This section will be deleted.
-
-Temporary glossary terms (for bikeshed linker).
-Many of these are properly defined elsewhere and should be linked to directly.
-Terms which should be defined in this spec should be defined inline.
-
-: activation behavior
-:: The action taken when an event, typically initiated by users through
- an input device, causes an element to fulfill a defined task. The task MAY
- be defined for that element by the host language, or by
- author-defined variables, or both. The default task for any given element
- MAY be a generic action, or MAY be unique to that element. For example, the
- activation behavior of an HTML or SVG <a> element is to
- cause the user agent to traverse the link specified in the
- href attribute, with the further optional parameter of
- specifying the browsing context for the traversal (such as the current
- window or tab, a named window, or a new window). The activation behavior of
- an HTML <input> element with the type
- attribute value submit is be to send the values of the form
- elements to an author-defined IRI by the author-defined HTTP method. See
- [[#event-flow-activation]] for more details.
-
-: activation trigger
-:: An event which is defined to initiate an activation behavior. Refer
- to [[#event-flow-activation]] for more details.
-
-: default action
-:: A default action is an OPTIONAL supplementary behavior that an
- implementation MUST perform in combination with the dispatch of the event
- object. Each event type definition, and each specification, defines the
- default action for that event type, if it has one. An instance of an
- event MAY have more than one default action under some circumstances,
- such as when associated with an activation trigger. A default
- action MAY be cancelled through the invocation of the
- {{Event/preventDefault()}} method. For more details, see
- [[#event-flow-default-cancel]].
-
-: delta
-:: The estimated scroll amount (in pixels, lines, or pages) that the user agent
- will scroll or zoom the page in response to the physical movement of an
- input device that supports the {{WheelEvent}} interface (such as a mouse
- wheel or touch pad). The value of a delta (e.g., the
- {{WheelEvent/deltaX}}, {{WheelEvent/deltaY}}, or {{WheelEvent/deltaZ}}
- attributes) is to be interpreted in the context of the current
- {{WheelEvent/deltaMode}} property. The relationship between the physical
- movement of a wheel (or other device) and whether the delta is
- positive or negative is environment and device dependent. However, if a user
- agent scrolls as the default action then the sign of the delta
- is given by a right-hand coordinate system where positive X,Y, and Z axes
- are directed towards the right-most edge, bottom-most edge, and farthest
- depth (away from the user) of the document, respectively.
-
-: event
-:: An event is the representation of some occurrence (such as a mouse click on
- the presentation of an element, the removal of child node from an element,
- or any number of other possibilities) which is associated with its event
- target. Each event is an instantiation of one specific event
- type.
-
-: event target
-:: The object to which an event is targeted using the [[#event-flow]].
- The event target is the value of the {{Event/target}} attribute.
-
-: host language
-:: Any language which integrates the features of another language or API
- specification, while normatively referencing the origin specification rather
- than redefining those features, and extending those features only in ways
- defined by the origin specification. An origin specification typically is
- only intended to be implemented in the context of one or more host
- languages, not as a standalone language. For example, XHTML, HTML, and SVG
- are host languages for UI Events, and they integrate and extend the objects
- and models defined in this specification.
-
-: rotation
-:: An indication of incremental change on an input device using the
- {{WheelEvent}} interface. On some devices this MAY be a literal rotation of
- a wheel, while on others, it MAY be movement along a flat surface, or
- pressure on a particular button.
-
-: topmost event target
-:: The topmost event target MUST be the element highest in the rendering
- order which is capable of being an event target. In graphical user
- interfaces this is the element under the user's pointing device. A user
- interface's hit testing facility is used to determine the target. For
- specific details regarding hit testing and stacking order, refer to the
- host language.
-
-: un-initialized value
-:: The value of any event attribute (such as {{Event/bubbles}} or
- {{Event/currentTarget}}) before the event has been initialized with
- {{Event/initEvent()}}. The un-initialized values of an event apply
- immediately after a new event has been created using the method
- {{Document/createEvent()}}.
-
-: user agent
-:: A program, such as a browser or content authoring tool, normally running on
- a client machine, which acts on a user's behalf in retrieving, interpreting,
- executing, presenting, or creating content. Users MAY act on the content
- using different user agents at different times, for different purposes. See
- the [[#conf-interactive-ua]] and [[#conf-author-tools]] for details on the
- requirements for a conforming user agent.
-
-: Window
-:: The Window is the object referred to by the current document's
- browsing context's Window Proxy object as defined in
- HTML5
- [[HTML5]].
-
-
-