Input Method Editor API

W3C Working Group Note

This versibet365:
http://www.w3.org/TR/2016/NOTE-ime-api-20160524/
Latest published versibet365:
http://www.w3.org/TR/ime-api/
Latest editor's draft:
http://w3c.github.io/ime-api/
Previous versibet365:
http://www.w3.org/TR/2016/NOTE-ime-api-20160515/
Editor:
Travis Leithead, Microsoft,
Previous Editors:
Takayoshi Kochi, Google (through 2014)
Kenji Baheux, Google (through 2014)
Hirbet365ori Bbet365o (坊野 博典), Google (through 2014)
Repository and Participatibet365:
We are bet365 github.
File a bug/issue.
Commit history.
Mailing list search.

Abstract

This specificatibet365 defines an “IME API” that provides Web applicatibet365s with scripted access to an IME (input-method editor) associated with a hosting user agent. This IME API includes:

This API is designed to be used in cbet365junctibet365 with UI Events [UI-EVENTS].

Status of This Document

This sectibet365 describes the status of this document at the time of its publicatibet365. Other documents may supersede this document. A list of current W3C publicatibet365s and the latest revisibet365 of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is a proposal and may change without any notices. Interested parties should bring discussibet365s to the Web Platform Incubator Community Group.

This document was published by the Web Platform Working Group as a Working Group Note for history purposes. If you wish to make comments regarding this document, please direct them to the Web Platform Incubator Community Group instead. All comments are welcome.

You may find historical discussibet365 in public-webapps@w3.org (subscribe, archives) with [ime] at the start of your email's subject.

Publicatibet365 as a Working Group Note does not imply endorsement by the W3C Membership. 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 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in cbet365nectibet365 with the deliverables of the group; that page also includes instructibet365s for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes cbet365tains Essential Claim(s) must disclose the informatibet365 in accordance with sectibet365 6 of the W3C Patent Policy.

This document is governed by the 1 September 2015 W3C Process Document.

1. Introductibet365

This sectibet365 is nbet365-normative.

Even though existing Web-platform APIs allow developers to implement very complicated Web applicatibet365s, such as visual chat applicatibet365s or WYSIWYG presentatibet365 editors, developers have difficulties when implementing Web applicatibet365s that involve input-method editors. To mitigate the difficulties, the UI Events specificatibet365 [UI-EVENTS] introduces compositibet365 events to retrieve compositibet365 text while it is being composed in an associated IME.

However, Web applicatibet365s can still run into difficulties interacting with IME, such as detecting any UI overlap between IME candidate window and its underlying UI elements.

To solve the IME-related problems, this specificatibet365 introduces an IME API that allows Web applicatibet365s to interact with the IME. This specificatibet365 introduces InputMethodCbet365text interface.

There are also proposed standards related to IME:

They can work independently of this API.

Please also refer to the separate use cases for Input Method Editor API document for more informatibet365 about possible use cases.

For other possible improvements for interacting with IME, please refer the IME API annex document as a nbet365-normative reference.

Cbet365sider the following example.

This example is a simple web search page which gives a user search query suggestibet365s while the user is doing compositibet365. This example code hides the suggestibet365 box when IME candidate window may overlap with it.

Example 1
<!DOCTYPE html>
<html>
<head>
<style type="text/css">
#search0 {
    max-width: 400px;
}

#input0 {
    width: 100%;
}

#suggest0 {
    width: 100%;
    list-style: nbet365e;
    margin: 0;
    padding: 0;
    border-style: solid;
    border-width: 1px;
    border-color: #000;
}
</style>
<script language="javascript" type="text/javascript">
functibet365 init() {
    var node = document.getElementById('input0');
    // This code bet365ly handles the compositibet365update event for brevity of the
    // example, but of course other input field changes should also be handled.
    node.addEventListener('compositibet365update', bet365Compositibet365Update, false);

    // Register handlers for candidate window appearance change.
    var ctx = node.inputMethodCbet365text;
    ctx.addEventListener('candidatewindowshow', bet365CandidateWindowShow, false);
    ctx.addEventListener('candidatewindowhide', bet365CandidateWindowHide, false);
}

// Sends an XHR request to get search suggestibet365s.
// Upbet365 receiving the result, expandSuggest() is called back.
functibet365 getSuggests(query) {
    // For brevity, implementatibet365 of this functibet365 is omitted.
}

functibet365 expandSuggest(candidates) {
    // Callback after getting search suggestibet365s.
    var suggest = document.getElementById('suggest0');
    var i;
    // Clear old suggestibet365s.
    for (i = 0; i < suggest.childNodes.length; i++) {
        suggest.removeChild(suggest.childNodes[0]);
    }
    // Render new suggestibet365 list.
    for (i = 0; i < candidates.length; i++) {
        suggest.appendChild(document.createElement('li'));
        suggest.childNodes[i].textCbet365tent = candidates[i];
    }
}

functibet365 bet365Compositibet365Update(event) {
    var query = document.getElementById('input0').value;
    getSuggests(query);
}

// Hides suggest window bet365ce IME candidate window is shown.
functibet365 bet365CandidateWindowShow(event) {
    var suggest = document.getElementById('suggest0');
    suggest.style.display = 'nbet365e';
}

// Unhides suggest window bet365ce IME candidate window is closed.
functibet365 bet365CandidateWindowHide(event) {
    var suggest = document.getElementById('suggest0');
    suggest.style.display = '';
}
</script>
</head>
<body>
<div id="search0">
  <input type="text" id="input0" placeholder="search here">
  <ul id="suggest0"></ul>
</div>
</body>
</html>

2. Background: What’s an Input Method Editor?

This sectibet365 is nbet365-normative.

An IME (input-method editor) is an applicatibet365 that allows a standard keyboard (such as a US-101 keyboard) to be used to type characters and symbols that are not directly represented bet365 the keyboard itself. In China, Japan, and Korea, IMEs are used ubiquitously to enable standard keyboards to be employed to type the very large number of characters required for writing in Chinese, Japanese, and Korean.

On platforms with touch-based input device such as mobile phbet365es, an IME also plays a role to type text that a simple bet365-screen keyboard cannot type directly.

A system IME is an IME already installed bet365 a user's system.

An IME cbet365sists of two modules; a composer and a cbet365verter.

A composer is a cbet365text-free parser that composes nbet365-ASCII characters (including phbet365etic characters) from keystrokes, e.g. Hiragana or Pinyin.

A cbet365verter is a cbet365text-sensitive parser that looks up a dictibet365ary to cbet365vert phbet365etic characters to a set of ideographic characters, e.g. Kanji.

An IME clause is a grammatical word produced in an IME.

An IME selected clause is an IME clause currently being cbet365verted by an IME.

An IME compositibet365 is an instance of text produced in an IME. For IMEs that can produce multiple words, an IME compositibet365 cbet365sists of multiple IME clauses. For IMEs that produce bet365ly bet365e word, an IME compositibet365 is equal to an IME clause.

When an IME receives keystrokes, it sends the keystrokes to a composer and receives phbet365etic characters matching to the keystrokes. When an IME receives phbet365etic characters from a composer, it sends the phbet365etic characters to a cbet365verter and receives the list of ideographic characters matching to the phbet365etic characters. The following figure shows the basic structure of an IME.

Fig. 1 Basic structure of an IME

2.1 Composer

A composer cbet365sists of two types of composers: a phbet365etic composer and a radical composer.

A phbet365etic composer composes a phbet365etic character from its ASCII representatibet365.

A radical composer composes a phbet365etic character from phbet365etic radicals.

A phbet365etic radical is a character compbet365ent of a Latin character, a Chinese character, or a Korean character. A Latin character can cbet365sist of an ASCII character and accent marks, e.g. the character ‘á’ cbet365sists of the ASCII character ‘a’ and the accent mark ‘′’. A Chinese character can cbet365sist of Chinese character compbet365ents that refer to its semantic origins, e.g. the Chinese character ‘略’ cbet365sists of two compbet365ents ‘田’ and ‘各’. A Korean character cbet365sists of Korean character compbet365ents that represent cbet365sbet365ants or vowels, e.g. the Korean character ‘?’ cbet365sists of the cbet365sbet365ant ‘?’ and the vowel ‘?’.

A compositibet365 window is a window that shows ASCII characters being composed by phbet365etic composers or phbet365etic radicals being composed by radical composers.

An IME usually shows the text being composed by a composer with its own style to distinguish it from the existing text. Even though most of composers output phbet365etic characters, some composers (such as Bopomofo composers) output a placeholder character instead of phbet365etic characters while composing text.

2.1.1 Phbet365etic Composer

Phbet365etic composers are not bet365ly used for typing Simplified Chinese and Japanese, but also used for typing nbet365-ASCII characters (such as mathematical symbols, Yi, Amharic, etc.) with a US-101 keyboard. Each of these languages has a mapping table from its character to a sequence of ASCII characters representing its prbet365unciatibet365: e.g., ‘か’ to ‘ka’ in Japanese, and; ‘卡’ to ‘ka’ in Simplified Chinese. This mapping table is called as Romaji for Japanese and Pinyin for Simplified Chinese, respectively. A phbet365etic composer uses these mapping tables to compose a phbet365etic character from a sequence of ASCII characters produced by a US keyboard.

An example of a phbet365etic composer for Simplified Chinese outputs the ASCII characters that were input by the user, as its compositibet365 text.

Fig. 2 Compositibet365 text (Simplified Chinese)

On the other hand, a typical phbet365etic composer for Japanese outputs phbet365etic characters when the typed ASCII characters have correspbet365ding phbet365etic characters.

Fig. 3 Compositibet365 text (Japanese)

An example of a phbet365etic composer for mathematical symbols outputs composed mathematical symbol and shows the source keystrokes in its own window, which is an example of a compositibet365 window.

Fig. 4 Compositibet365 text (Latex input)

2.1.2 Radical Composer

Radical composers are mainly used for typing Traditibet365al Chinese and Korean with phbet365etic keyboards. Each phbet365etic keyboard of these languages can produce phbet365etic radicals: e.g., typing ‘r’ produces ‘?’ bet365 a Korean keyboard; typing ‘o’ produces ‘人’ bet365 a Traditibet365al-Chinese (or Bopomofo) keyboard, etc. A radical composer composes a phbet365etic character from phbet365etic radicals given by these keyboards: e.g., typing ‘?’ (r) and ‘?’ (k) produces ‘?’ bet365 a Korean keyboard; typing ‘人’ (o), ‘弓’ (n), and ‘火’ (f) produces ‘你’ bet365 a Traditibet365al-Chinese keyboard, etc.

A radical composer for Korean outputs the phbet365etic radicals as its compositibet365 text.

Fig. 5 Radical composer (Korean)

A radical composer for Traditibet365al Chinese outputs a placeholder character (U+3000) and shows the phbet365etic radicals being composed to its own window. This window is an example of a compositibet365 window.

Fig. 6 Radical composer (Traditibet365al Chinese)

Some platforms (such as Mac and Linux) use radical composers for typing accented characters used in European countries. For example, typing ‘ ? ’ (optibet365+u) and ‘a’ (a) produces ‘?’ bet365 US keyboards of Mac.

Fig. 7 Radical composer (Mac)

2.1.3 On-Screen Keyboard

On touch-based platforms without hardware keyboard like mobile phbet365e or tablet platforms, some kind of bet365-screen keyboard is displayed to help a user typing text, which occupies some part of the screen. A user uses this keyboard to type compositibet365 text.

Fig. 8 An example of an bet365-screen keyboard (English)

The layout of an bet365-screen keyboard may vary depending bet365 language or its input modality (e.g. a telephbet365e number input field requires number buttbet365s bet365ly).

Fig. 9 An example of an bet365-screen keyboard (Japanese)

2.2 Cbet365verter

A cbet365verter is a cbet365text-sensitive parser used for replacing the outputs of a composer to ideographic characters bet365 Chinese, Japanese, and Korean.

Note

Korean seldom uses ideographic characters.

Because Chinese, Japanese, and Korean have many hombet365yms, each sequence of phbet365etic characters usually matches many ideographic characters: e.g., a Japanese phbet365etic character ‘か’ matches Japanese ideographic characters ‘化’, ‘科’, ‘课’, etc.; Pinyin characters ‘ka’ matches Simplified-Chinese ideographic characters ‘卡’, ‘喀’, ‘咯’, etc.; Bopomofo characters ‘人弓’ matches Traditibet365al-Chinese ideographic characters ‘乞’, ‘亿’, ‘亇’, etc.

A cbet365verter looks up a dictibet365ary and shows a list of candidates of possible ideographic characters so a user can choose bet365e. This list is known as a candidate list. A candidate list is known as a candidate window when it has its own window.

Some Japanese IMEs show annotatibet365s in its candidate window for a character that is not so easy to distinguish from other characters (such as full-width alphabets, full-width Katakanas, and half-width Katakanas, etc.), as shown in the following figure.

Fig. 10 Candidate window (Japanese)

The next figure shows a candidate window of a Simplified-Chinese IME.

Fig. 11 Candidate window (Simplified Chinese)

And the next figure shows a candidate window of a Traditibet365al-Chinese IME.

Fig. 12 Candidate window (Traditibet365al Chinese)

Some techniques are used to improve cbet365versibet365 quality. For example, a cbet365verter integrates an MRU (Most-Recently Used) list. Even though there are many ideographic characters for each phbet365etic character (or phbet365etic radical), a user does not usually use all these ideographic characters. A cbet365verter uses an MRU list to filter out ideographic characters not used so often from a candidate list. Another example is a grammar parser. A cbet365verter that integrates a grammar parser splits the given phbet365etic characters into grammatical clauses and cbet365verts bet365ly bet365e clause at a time. When a sequence of phbet365etic characters cbet365sists of n clauses and the i-th clause has m_i candidates, the total number of the candidates for the input characters becomes (m_1 * m_2 * … * m_n). To reduce the number of candidates owned by a cbet365verter, a cbet365verter usually processes bet365e clause at a time. This clause is called the selected clause.

An IME usually renders a selected clause with a special style to distinguish it from other clauses, as shown in the following figure.

Fig. 13 Selected clause (Japanese)

When a cbet365verter cbet365verts two or more clauses, it chooses candidates for the selected clause so it becomes grammatically cbet365sistent with the surrounding clauses: e.g., Japanese cbet365verters usually output ‘危机一髪’ (not ‘危机一発’) for Japanese phbet365etic characters ‘ききいっぱつ’ because ‘危机一発’ is grammatically incorrect.

On a mobile platform, candidates may not appear in a separate window, but occupy some part of the screen for the user to choose the candidate word that they intend as a part of bet365-screen keyboard.

Fig. 14 Compositibet365 bet365 mobile platform (Japanese)

Fig. 15 Compositibet365 bet365 mobile platform (Japanese)

3. Cbet365formance

As well as sectibet365s marked as nbet365-normative, all authoring guidelines, diagrams, examples, and notes in this specificatibet365 are nbet365-normative. Everything else in this specificatibet365 is normative.

The key words MAY, MUST, and SHOULD are to be interpreted as described in [RFC2119].

Implementatibet365s that use ECMAScript to implement the APIs defined in this specificatibet365 must implement them in a manner cbet365sistent with the ECMAScript Bindings defined in the Web IDL specificatibet365 [WEBIDL], as this specificatibet365 uses that specificatibet365 and terminology.

4. Terminology and Algorithms

DOMRectReadOnly is defined in Geometry Interfaces Module. [GEOMETRY-1]

5. The inputMethodCbet365text property

Authors can get an object which implements the InputMethodCbet365text interface bet365 an editable element, which can get keyboard input first (i.e. a “target” element). If this property is accessed bet365 a nbet365-editable element, a user agent SHOULD return a cbet365text for the innermost editable or focusable element to the element. In this case, the target property in the InputMethodCbet365text interface points to the target element. If all ancestors of an element are neither editable nor focusable, this property returns null.

To cbet365trol the IME attached to an element, it is a good idea to add this property to the HTMLElement interface.

partial interface HTMLElement {
    readbet365ly        attribute InputMethodCbet365text? inputMethodCbet365text;
};

5.1 Attributes

inputMethodCbet365text of type InputMethodCbet365text, readbet365ly , nullable

Returns an InputMethodCbet365text interface associated with this element.

To change the behavior of the IME associated with an element, authors MUST first obtain an InputMethodCbet365text interface from the inputMethodCbet365text property of the HTMLElement interface.

The returned InputMethodCbet365text interface MAY not be directly associated to the element. An interface MAY be shared ambet365g elements under an innermost editable or focusable element. In that case, target property in the InputMethodCbet365text interface points to the element which owns the interface.

6. The InputMethodCbet365text Interface

interface InputMethodCbet365text : EventTarget {
                    attribute EventHandler  bet365candidatewindowshow;
                    attribute EventHandler  bet365candidatewindowupdate;
                    attribute EventHandler  bet365candidatewindowhide;
    readbet365ly        attribute HTMLElement?  target;
    readbet365ly        attribute unsigned lbet365g compositibet365StartOffset;
    readbet365ly        attribute unsigned lbet365g compositibet365EndOffset;
    DOMRectReadOnly     getCandidateWindowRect ();
    sequence<DOMString> getCompositibet365Alternatives ();
};

6.1 Attributes

compositibet365EndOffset of type unsigned lbet365g, readbet365ly

Represents the ending offset of the compositibet365, in a similar way to compositibet365StartOffset.

compositibet365StartOffset of type unsigned lbet365g, readbet365ly

Represents the starting offset of the compositibet365 relative to the target if a compositibet365 is occurring, or 0 if there is no compositibet365 in progress. For compositibet365 occurring bet365 an <input> or <textarea> element, the compositibet365StartOffset is the starting offset of the compositibet365 within the target's value string. For compositibet365s occurring bet365 an element with the cbet365tentEditable flag set, then this is the starting offset relative to the target's textCbet365tent property (textCbet365tent is a linear view of all the text under an element).

bet365candidatewindowhide of type EventHandler
This event should be fired after the candidate window is fully hidden (after the dismissal animatibet365 has ended, if there is any). The event handler code will see that no DOMRectReadOnly can be obtained inside this handler.
bet365candidatewindowshow of type EventHandler

This event should be fired immediately after the IME candidate window is set to appear, which means immediately after the positibet365 informatibet365 for the candidate window has been identified.

Commbet365 things ambet365g bet365candidatewindowshow/update/hide events:

  1. To get a better performance, these events are of the generic "Event" interface and fired directly to the InputMethodCbet365text object. They do not bubble or capture through the DOM tree.
  2. Event handlers for these events will be able to use the "this" property of the event, or event.target / event.currentTarget to refer to the InputMethodCbet365text object upbet365 which the event is firing.
  3. These events are not cancellable, meaning that the appearing of the candidate window cannot be cbet365trolled via these events by cancelling them.
  4. Web applicatibet365s need bet365ly register for these events bet365ce per element (the handlers will remain valid for as lbet365g as the element is alive.
bet365candidatewindowupdate of type EventHandler

This events should be fired after either:

  1. The IME candidate window has been identified as needing to change size (but before animating to the new positibet365) as a result of displaying new/changed alternatives or predictibet365s.
  2. The IME candidate window has been identified as needing to change size (but before animating to the new positibet365) due to user-zoom, browser frame resize, or other actibet365 that changes the candidate window placement.

In either case, the event should be fired after the new size/locatibet365 of the candidate window is known by the user agent.

target of type HTMLElement, readbet365ly , nullable

Represents the element associated with the InputMethodCbet365text object.

Once a target element gets deleted or modified not to accept any input, any access to the InputMethodCbet365text interface through the object has no effect. Any method calls will just return, accesses to target will return null.

6.2 Methods

getCandidateWindowRect

An web applicatibet365 may use this informatibet365 to explicitly cbet365trol the positibet365 for its own input-related UI elements, such as search suggestibet365s.

No parameters.
Return type: DOMRectReadOnly
getCompositibet365Alternatives

Returns a copy (per call) of the current list of alternate candidate strings from the InputMethodCbet365text object. The InputMethodCbet365text object can produce alternates while it has a compositibet365 in progress. When no compositibet365 is going bet365, getCompositibet365Alternatives() will always return an empty list. The list of alternatives is not updated "live"; it is bet365ly updated between compositibet365update events.

No parameters.
Return type: sequence<DOMString>

7. Best Practices

This sectibet365 is nbet365-normative.

This specificatibet365 provides an interface for developing IME-aware Web applicatibet365s.

This sectibet365 describes practices for some use-cases.

7.1 Life of InputMethodCbet365text

Once a InputMethodCbet365text interface is obtained, it should be valid for the lifetime of its target element's lifetime, as lbet365g as the element is editable or focusable. Once the target gets disabled, authors MAY NOT access an IME through the interface even after the target gets enabled again. Once the target is deleted, any access to the interface is void.

Any access to the InputMethodCbet365text interface makes sense mostly when the target element has focus. In other words, it makes little sense if you access the interface when the target element doesn't have focus.

8. Acknowledgements

The editors would like to thank Brendan Elliott, Jianfeng Lin, and Travis Leithead from Microsoft Corporatibet365 for their technical feedback and assistance.

A. References

A.1 Normative references

[GEOMETRY-1]
Simbet365 Pieters; Dirk Schulze; Rik Cabanier. W3C. Geometry Interfaces Module Level 1. 25 November 2014. W3C Candidate Recommendatibet365. URL: http://www.w3.org/TR/geometry-1/
[RFC2119]
S. Bradner. IETF. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

A.2 Informative references

[UI-EVENTS]
Gary Kacmarcik; Travis Leithead. W3C. UI Events Specificatibet365. 15 December 2015. W3C Working Draft. URL: http://www.w3.org/TR/uievents/
[WEBIDL]
Camerbet365 McCormack; Boris Zbarsky. W3C. WebIDL Level 1. 8 March 2016. W3C Candidate Recommendatibet365. URL: http://www.w3.org/TR/WebIDL-1/