Input Events

1. Introduction

1.1. Overview

TODO.

1.2. Conformance

Boilerplate?

2. Stylistic Conventions

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

This is a note.

This is an open issue.

This is a warning.

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

3. Input Events

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

3.1. Interface InputEvent

Introduced in DOM Level 3

3.1.1. InputEvent

[Exposed=Window]
interface InputEvent : UIEvent {
  constructor(DOMString type, optional InputEventInit eventInitDict = {});
  readonly attribute USVString? data;
  readonly attribute boolean isComposing;
  readonly attribute DOMString inputType;
};

data, of type USVString, readonly, nullable

data holds the value of the characters generated by an input method. This MAY be a single Unicode character or a non-empty sequence of Unicode characters [Unicode]. Characters SHOULD be normalized as defined by the Unicode normalization form NFC, defined in [UAX15]. This attribute MAY contain the empty string.

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

isComposing, of type boolean, readonly

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

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

inputType, of type DOMString, readonly

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

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

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

3.1.2. InputEventInit

dictionary InputEventInit : UIEventInit {
  DOMString? data = null;
  boolean isComposing = false;
  DOMString inputType = "";
};

data, of type DOMString, nullable, defaulting to null

Initializes the data attribute of the InputEvent object.

isComposing, of type boolean, defaulting to false

Initializes the isComposing attribute of the InputEvent object.

inputType, of type DOMString, defaulting to ""

Initializes the inputType attribute of the InputEvent object.

3.2. Input Event Order

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

3.3. Input Event Types

3.3.1. beforeinput

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

3.3.2. input

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

4. Security Considerations

TODO - Add specific concerns for this spec

5. Acknowledgements

TODO

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

6. Refs to other UIEvent specs [DELETE]

This section will be deleted.

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

compositionend compositionstart

6.1. Things defined in other sections

6.1.1. Activation triggers and behavior

6.1.2. Composition Events

6.1.3. Default actions and cancelable events

6.1.4. Event dispatch and DOM event flow

6.1.5. Web browsers and other dynamic or interactive user agents

6.1.6. Authoring tools

6.2. Things defined in KeyboardEvents

6.2.1. Dead keys

6.2.2. Input Method Editors

7. Glossary [DELETE]

This section will be deleted.

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

empty string

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

event

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

event target

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

IME

input method editor

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

text composition system

A software component that interprets some form of alternate input (such as a input method editor, a speech processor, or a handwriting recognition system) and converts it to text.

un-initialized value

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

user agent

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

Window

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