Keyboard events and composition events 1. Introduction Keyboard input uses dead keys for the input of composed character sequences and IMEs for the input of CJK ideographs. Also, some platforms use voice recognizer and hand-writing recognizers for text input. This document proposes three new events: compositionstart, compositionupdate, and compositionend to help creating web applications which support these input devices. 2. Composition Event Types This module defines the feature CompositionEvents 3.0 and depends on the feature UIEvents 3.0. The composition event module originates from the oncompositionstart and oncompositionend attributes of Firefox 3. This composition event adds another event type compositionUpdate to update the status of input methods. Refer to Appendix A, "Keyboard events and key identifiers", for examples on how text events are used in combination with keyboard events. Interface CompositionEvent (introduced in DOM Level ?) The CompositionEvent interface provides specific contextual information associated with Composition Events. To create an instance of the TextEvent interface, use the DocumentEvent.createEvent("CompositionEvent") method call. IDL Definition interface CompositionEvent : UIEvent { readonly attribute DOMString data; void initTextEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in DOMString dataArg); void initTextEventNS(in DOMString namespaceURIArg, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in DOMString dataArg); }; Attribute data of type DOMString, readonly data holds the value of the characters generated by an input method. This may be a single Unicode character or a non-empty sequence of Unicode characters [Unicode]. Characters should be normalized as defined by the Unicode normalization form NFC, defined in [UAX #15]. This attribute can be null or contain the empty string. Methods initCompositionEvent Initializes attributes of a CompositionEvent object. This method has the same behavior as UIEvent.initUIEvent(). The value of UIEvent.detail remains undefined. Parameters typeArg of type DOMString Refer to the UIEvent.initUIEvent() method for a description of this parameter. canBubbleArg of type boolean Refer to the UIEvent.initUIEvent() method for a description of this parameter. cancelableArg of type boolean Refer to the UIEvent.initUIEvent() method for a description of this parameter. viewArg of type views::AbstractView Refer to the UIEvent.initUIEvent() method for a description of this parameter. dataArg of type DOMString Specifies CompositionEvent.data. No Return Value No Exceptions initCompositionEventNS Initializes attributes of a CompositionEvent object. This method has the same behavior as UIEvent.initUIEventNS(). The value of UIEvent.detail remains undefined. Parameters namespaceURIArg of type DOMString Refer to the UIEvent.initUIEventNS() method for a description of this parameter. typeArg of type DOMString Refer to the UIEvent.initUIEventNS() method for a description of this parameter. canBubbleArg of type boolean Refer to the UIEvent.initUIEventNS() method for a description of this parameter. cancelableArg of type boolean Refer to the UIEvent.initUIEventNS() method for a description of this parameter. viewArg of type views::AbstractView Refer to the UIEvent.initUIEventNS() method for a description of this parameter. dataArg of type DOMString Refer to the CompositionEvent.initTextEvent() method for a description of this parameter. No Return Value No Exceptions The composition event type is listed below. compositionStart Type compositionStart Namespace None Interface CompositionEvent Cancelable ? (To be discussed) Bubbles ? (To be discussed) Target Element Context info UIEvent.view and CompositionEvent.data are in use. An input method or a voice comand starts composing a text. This event type is device-dependent. It also relies on the capabilities of an input method and how they are mapped into the operating system. When we use a keyboard to use an input method, this event type is generated after a keydown event. On the ther hand, a voice recognizer and a hand-writing recognizer may send this event type without keyboard events. compositionUpdate Type compositionUpdate Namespace None Interface CompositionEvent Cancelable ? (To be discussed) Bubbles ? (To be discussed) Target Element Context info UIEvent.view and CompositionEvent.data are in use. An input method updates its text. The characters can originate from ones being processed by an input method, by a voice recognizer, or by a hand-writing recognizer. compositionEnd Type compositionEnd Namespace None Interface CompositionEvent Cancelable ? (To be discussed) Bubbles ? (To be discussed) Target Element Context info UIEvent.view and CompositionEvent.data are in use. An input method finishes composing a text. This event type is almost the same as a TextInput event but this event type is also sent when an input method cancels composing a text. Appendix A Keyboard events, text events, and composition events 1.2. Dead keys For a platform which uses an input methods to input composed characters. It may also sends composition events. (NOTE: Mac and Linux use input methods to process dead-keys.) 1. "keydown": "U+0302" (Combining Circumflex Accent key) 2. “compositionstart”: "" 3. “compositionupdate”: “” (undefined - to be discussed) 4. "keyup": "U+0302" 5. "keydown": "U+0045" (Latin Capital Letter E key) 6. "textInput": "é" 7. “compositionend”: "é" 8. "keyup": "U+0045" When a user types a “illegal” base character after a user pressed a dead key. 1. "keydown": "U+0302" (Combining Circumflex Accent key) 2. “compositionstart”: 3. “compositionupdate”: “” (to be discussed) 4. "keyup": "U+0302" 5. "keydown": "U+0045" (Latin Capital Letter Q key) 6. "textInput": "q" 7. “compositionend”: "" (to be discussed) 8. "keyup": "U+0045" 1.3. Input Method Editors 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 could be respectively "U+0020" (Space key) and "Enter". 1. "keydown": "U+0053" (Latin Capital Letter S key) 2. "compositionstart": "" 3. "keyup": "U+0053" (Latin Capital Letter S key) 4. "keydown": "U+0049" (Latin Capital Letter I key) 5. "keyup": "U+0049" (Latin Capital Letter I key) 6. "keydown": "Convert" 7. "compositionupdate": "詩" 8. "keyup": "Convert" 9. “keydown”: "Convert" 10. "compositionupdate": "市" 11. "keyup”: "Convert" 12. "keydown": "Accept" 13. "textInput": "市" 14. "compositionend": "市" 15. "keyup": "Accept" The following example describes a possible sequence of keys when we cancel generating 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 could be respectively "U+0020" (Space key) and "Enter". The key "Cancel" may 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). 1. "keydown": "U+0053" (Latin Capital Letter S key) 2. "compositionstart": "" 3. "keyup": "U+0053" (Latin Capital Letter S key) 4. "keydown": "U+0049" (Latin Capital Letter I key) 5. "keyup": "U+0049" (Latin Capital Letter I key) 6. "keydown": "Convert" 7. "compositionupdate": "詩" 8. "keyup": "Convert" 9. “keydown”: "Convert" 10. "compositionupdate": "市" 11. "keyup”: "Convert" 12. "keydown": "Cancel" 13. "compositionupdate": "" (Is this needed?) (*1) 14. "compositionend": "" 15. "keyup": "Cancel" NOTE: Mac sets an empty string to the composition node before canceling a composition. 1.4. Hand-writing recognizers The following example describes a possible sequence of events to write a text "text" with a hand-writing recognizer. (NOTE: need more investigation.) 1. "compositionstart": "" 2. "compositionupdate": "test" 3. "compositionupdate": "text" 4. "textInput": "text" 5. "compositionend": "text"