Composition 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:

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

• Glyphs representing character are shown as: "𣧂".

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

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

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

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

And finally:

This is a note.

This is an open issue.

This is a warning.

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

3. Composition Events

Composition Events provide a means for inputing text in a supplementary or alternate manner than by Keyboard Events, in order to allow the use of characters that might not be commonly available on keyboard. For example, Composition Events might be used to add accents to characters despite their absence from standard US keyboards, to build up logograms of many Asian languages from their base components or categories, to select word choices from a combination of key presses on a mobile device keyboard, or to convert voice commands into text using a speech recognition processor. Refer to § 7.2.1 Keyboard events and key values for examples on how Composition Events are used in combination with keyboard events.

Conceptually, a composition session consists of one compositionstart event, one or more compositionupdate events, and one compositionend event, with the value of the data attribute persisting between each stage of this event chain during each session.

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

Not all IME systems or devices expose the necessary data to the DOM, so the active composition string (the Reading Window or candidate selection menu option) might not be available through this interface, in which case the selection MAY be represented by the empty string.

3.1. Interface CompositionEvent

Introduced in this specification

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

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

3.1.1. CompositionEvent

[Exposed=Window]
interface CompositionEvent : UIEvent {
  constructor(DOMString type, optional CompositionEventInit eventInitDict = {});
  readonly attribute USVString data;
};

data, of type USVString, readonly

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

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

3.1.2. CompositionEventInit

dictionary CompositionEventInit : UIEventInit {
  DOMString data = "";
};

data, of type DOMString, defaulting to ""

Initializes the data attribute of the CompositionEvent object to the characters generated by the IME composition.

3.2. Composition Event Order

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

3.3. Handwriting Recognition Systems

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

3.4. Canceling Composition Events

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

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.

3.5. Key Events During Composition

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

3.6. Input Events During Composition

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

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.

3.7. Composition Event Types

3.7.1. compositionstart

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

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

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

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

3.7.2. compositionupdate

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

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

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

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

3.7.3. compositionend

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.

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

4.1. Initializers for interface CompositionEvent

This section is informative

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

partial interface CompositionEvent {
  // Originally introduced (and deprecated) in this specification
  undefined initCompositionEvent(DOMString typeArg,
    optional boolean bubblesArg = false,
    optional boolean cancelableArg = false,
    optional WindowProxy? viewArg = null,
    optional DOMString dataArg = "");
};

initCompositionEvent(typeArg)

Initializes attributes of a CompositionEvent object. This method has the same behavior as UIEvent.initUIEvent(). The value of detail remains undefined.

The initCompositionEvent method is deprecated.

DOMString typeArg

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

boolean bubblesArg

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

boolean cancelableArg

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

Window? viewArg

Specifies view. This value MAY be null.

DOMString dataArg

Specifies data.

5. Security Considerations

TODO - Add specific concerns for this spec

6. Acknowledgements

TODO

7. Refs to other UIEvent specs [DELETE]

This section will be deleted.

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

beforeinput keydown keyup input

7.1. Things defined in other sections

7.1.1. Activation triggers and behavior

7.1.2. Default actions and cancelable events

7.1.3. Event dispatch and DOM event flow

7.1.4. Web browsers and other dynamic or interactive user agents

7.1.5. Authoring tools

7.2. Things defined in KeyboardEvents

7.2.1. Keyboard events and key values

7.2.2. Input Method Editors

7.2.3. Key Legends

7.3. Things defined in Changes

7.3.1. Changes between different drafts of UI Events

8. Glossary [DELETE]

This section will be deleted.

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

activation behavior

The action taken when an event, typically initiated by users through an input device, causes an element to fulfill a defined task. The task MAY be defined for that element by the host language, or by author-defined variables, or both. The default task for any given element MAY be a generic action, or MAY be unique to that element. For example, the activation behavior of an HTML or SVG <a> element is to cause the user agent to traverse the link specified in the href attribute, with the further optional parameter of specifying the browsing context for the traversal (such as the current window or tab, a named window, or a new window). The activation behavior of an HTML <input> element with the type attribute value submit is be to send the values of the form elements to an author-defined IRI by the author-defined HTTP method. See § 7.1.1 Activation triggers and behavior for more details.

activation trigger

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

default action

A default action is an OPTIONAL supplementary behavior that an implementation MUST perform in combination with the dispatch of the event object. Each event type definition, and each specification, defines the default action for that event type, if it has one. An instance of an event MAY have more than one default action under some circumstances, such as when associated with an activation trigger. A default action MAY be cancelled through the invocation of the preventDefault() method. For more details, see § 7.1.2 Default actions and cancelable events.

empty string

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

event

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

event target

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

host language

Any language which integrates the features of another language or API specification, while normatively referencing the origin specification rather than redefining those features, and extending those features only in ways defined by the origin specification. An origin specification typically is only intended to be implemented in the context of one or more host languages, not as a standalone language. For example, XHTML, HTML, and SVG are host languages for UI Events, and they integrate and extend the objects and models defined in this specification.

IME

input method editor

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

text composition system

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

un-initialized value

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

user agent

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

Window

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