-
Notifications
You must be signed in to change notification settings - Fork 0
/
Overview.html
684 lines (662 loc) · 33.3 KB
/
Overview.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
<!doctype html>
<html>
<head>
<!-- foo -->
<meta charset="UTF-8">
<title>Input Method Editor API</title>
<style>
body {
counter-reset: figcaption;
counter-reset: example;
}
figcaption {
font-weight: bold;
}
var {
font-weight: bold;
color: green;
padding-left: 2px;
padding-right: 4px;
}
.tocline {
padding-top: 2px;
}
.ed_mailto:before {
content: "<";
}
.ed_mailto:after {
content: ">";
}
</style>
<script class="remove">
function addEllipsis(id) {
document.getElementById(id).childNodes.item(2).textContent = "\n …\n";
}
function removeNodes(nodesToRemove) {
var i, j;
for (i = 0; i < nodesToRemove.length; ++i) {
for (j = 0; j < nodesToRemove[i].length; ++j) {
nodesToRemove[i][j].parentNode.removeChild(nodesToRemove[i][j]);
}
}
}
</script>
<script class="remove">
function getLastModifiedDate() {
var d = new Date(document.lastModified);
return d.toISOString().substring(0,10);
}
</script>
<script type="text/javascript" src="https://www.w3.org/Tools/respec/respec-w3c-common" class="remove"></script>
<script type="text/javascript" class="remove">
var respecConfig = {
specStatus: "ED",
shortName: "ime-api",
edDraftURI: "http://dvcs.w3.org/hg/ime-api/raw-file/default/Overview.html",
prevED: "http://www.w3.org/TR/2013/WD-ime-api-20130404/",
editors: [
{ name: "Takayoshi Kochi",
company: "Google",
mailto: "[email protected]"
},
{ name: "Kenji Baheux",
company: "Google",
mailto: "[email protected]"
},
{ name: "Hironori Bono (坊野 博典)",
company: "previous editor, (formerly) Google",
},
],
wg: "Web Applications Working Group",
wgURI: "http://www.w3.org/2008/webapps/",
wgPublicList: "public-webapps",
wgPatentURI: "http://www.w3.org/2004/01/pp-impl/42538/status",
publishDate: getLastModifiedDate(),
after: function () {
var nodesToRemove = [
document.querySelectorAll("table.parameters"),
document.querySelectorAll("li.tocline > a[href^='#attributes']"),
document.querySelectorAll("li.tocline > a[href^='#methods']"),
];
addEllipsis("idl-def-HTMLElement");
removeNodes(nodesToRemove);
}
}
</script>
</head>
<body>
<section id="abstract">
<p>This specification defines an “IME API” that provides
Web applications with scripted access to an IME
(<a href="#IME">input-method editor</a>) associated with
a hosting user agent. This IME API includes:</p>
<ul>
<li>An <a>InputMethodContext</a> interface, which provides
attributes, events, and methods to interact
with current UI state of IME.
</li>
</ul>
<p>This API is designed to be used in conjunction with DOM events
[[DOM-LEVEL-3-EVENTS]].</a></p>
</section>
<section id="sotd">
<p>
This document is a proposal that is being made available for public
review in order to solicit feedback, particularly from
implementors, with a goal of potential cross-browser implementation
and standardization.
</p>
</section>
<section class="informative" id="introduction">
<h2>Introduction</h2>
<p>Even though existing Web-platform APIs allow developers to implement
very complicated Web applications, such as visual chat applications or
WYSIWYG presentation editors, developers have difficulties when
implementing Web applications that involve
<a href="#IME">input-method editors</a>.
To mitigate the difficulties,
<a href="http://www.w3.org/TR/DOM-Level-3-Events/">the DOM
Level 3 Events specification</a>[[DOM-LEVEL-3-EVENTS]]
introduces <i>composition events</i>
to retrieve <a href="#ime-composition">composition text</a>
while it is being composed in an associated IME.</p>
<p>However, Web applications can still run into difficulties
interarcting with IME, such as detecting any UI overlap between
<a href="#candidate-window">IME candidate window</a> and its
underlying UI elements.</p>
<p>To solve the IME-related problems, this specification introduces
an IME API that allows Web applications to interact with the IME.
This specification introduces <a>InputMethodContext</a> interface.</p>
<p>There are also proposed standards related to IME:
<ul>
<li>Changing IME mode via CSS
(<a href="http://www.w3.org/TR/css3-ui/#ime-mode">ime-mode property
in CSS3 UI</a>)
<li>Controlling generic input modality
(<a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/association-of-controls-and-forms.html#input-modalities:-the-inputmode-attribute">inputmode attribute in HTML spec</a>)
</ul>
They can work independently of this API.
</p>
<p>Please also refer to the separate
<a href="https://dvcs.w3.org/hg/ime-api/raw-file/default/use-cases/Overview.html">use cases for Input Method Editor
API </a>document for more information about possible use cases.</p>
<p>For other possible improvements for interacting with IME, please
refer the <a href="Annex.html">IME API annex</a> document
as a non-normative reference.</p>
<p>Consider the following example.</p>
<p>This example is a simple web search page which gives a user
search query suggestions while the user is doing composition.
This example code hides the suggestion box when IME candidate window
may overlap with it.</p>
<pre class="example highlight" id="ex-ime-suggest-position">
<!DOCTYPE html>
<html>
<head>
<style type="text/css">
#search0 {
max-width: 400px;
}
#input0 {
width: 100%;
}
#suggest0 {
width: 100%;
list-style: none;
margin: 0;
padding: 0;
border-style: solid;
border-width: 1px;
border-color: #000;
}
</style>
<script language="javascript" type="text/javascript">
function init() {
var node = document.getElementById('input0');
// This code only handles the compositionupdate event for brevity of the
// example, but of course other input field changes should also be handled.
node.addEventListener('compositionupdate', onCompositionUpdate, false);
// Register handlers for candidate window appearance change.
var ctx = node.inputMethodContext;
ctx.addEventListener('candidatewindowshow', onCandidateWindowShow, false);
ctx.addEventListener('candidatewindowhide', onCandidateWindowHide, false);
}
// Sends an XHR request to get search suggestions.
// Upon receiving the result, expandSuggest() is called back.
function getSuggests(query) {
// For brevity, implementation of this function is omitted.
}
function expandSuggest(candidates) {
// Callback after getting search suggestions.
var suggest = document.getElementById('suggest0');
var i;
// Clear old suggestions.
for (i = 0; i < suggest.childNodes.length; i++) {
suggest.removeChild(suggest.childNodes[0]);
}
// Render new suggeston list.
for (i = 0; i < candidates.length; i++) {
suggest.appendChild(document.createElement('li'));
suggest.childNodes[i].textContent = candidates[i];
}
}
function onCompositionUpdate(event) {
var query = document.getElementById('input0').value;
getSuggests(query);
}
// Hides suggest window once IME candidate window is shown.
function onCandidateWindowShow(event) {
var suggest = document.getElementById('suggest0');
suggest.style.display = 'none';
}
// Unhides suggest window once IME candidate window is closed.
function onCandidateWindowHide(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>
</pre>
</section>
<section class="informative" id="background">
<h1>Background: What’s an Input Method Editor?</h1>
<p>An <dfn id="IME">IME</dfn> (input-method editor) is an application
that allows a standard keyboard (such as a US-101 keyboard) to be used
to type characters and symbols that are not directly represented on 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.</p>
<p>On platforms with touch-based input device such as mobile phones,
an IME also plays a role to type text that a simple on-screen keyboard
cannot type directly.</p>
<p>A <dfn id="system-ime">system IME</dfn> is an IME already installed
on a user's system.
<p>An IME consists of two modules; a <a href="#composer">composer</a>
and a <a href="#converter">converter</a>.</p>
<p>A <dfn id="composer">composer</dfn> is a context-free parser that
composes non-ASCII characters (including phonetic characters) from
keystrokes, e.g. Hiragana or Pinyin.</p>
<p>A <dfn id="converter">converter</dfn> is a context-sensitive parser
that looks up a dictionary to convert phonetic characters to
a set of ideographic characters, e.g. Kanji.</p>
<p>An <dfn id="ime-clause">IME clause</dfn> is a grammatical word
produced in an IME.</p>
<p>An <dfn id="ime-selected-clause">IME selected clause</dfn> is an
<a href="#ime-clause">IME clause</a> currently being converted by
an IME.</p>
<p>An <dfn id="ime-composition">IME composition</dfn>
is an instance of text produced in an IME. For IMEs that can produce
multiple words, an IME composition consists of multiple IME clauses.
For IMEs that produce only one word, an IME composition is equal to an
IME clause.</p>
<p>When an IME receives keystrokes, it sends the keystrokes to a
composer and receives phonetic characters matching to the keystrokes.
When an IME receives phonetic characters from a composer, it sends the
phonetic characters to a converter and receives the list of ideographic
characters matching to the phonetic characters. The following figure
shows the basic structure of an IME.</p>
<figure id="fig-ime-structure">
<p><img height="199" src="images/image10.png" width="615"></p>
<figcaption>Basic structure of an IME</figcaption>
</figure>
<section id="composer-section">
<h1>Composer</h1>
<p>A composer consists of two types of composers: a
<a href="#phonetic-composer">phonetic composer</a>
and a
<a href="#radical-composer">radical composer</a>.</p>
<p>A <dfn id="phonetic-composer">phonetic composer</dfn> composes a phonetic
character from its ASCII representation.</p>
<p>A <dfn id="radical-composer">radical composer</dfn> composes a
phonetic character from <a href="#phonetic-radical">phonetic radicals</a>.</p>
<p>A <dfn id="phonetic-radical">phonetic radical</dfn> is a character
component of a Latin character, a Chinese character, or a Korean
character. A Latin character can consist of an ASCII character and
accent marks, e.g. the character ‘á’ consists of
the ASCII character ‘a’ and the accent mark
‘´’. A Chinese character can consist of Chinese
character components that refer to its semantic origins, e.g. the
Chinese character ‘略’ consists of two components
‘田’ and ‘各’. A Korean
character consists of Korean character components that represent
consonants or vowels, e.g. the Korean character
‘가’ consists of the consonant
‘ㄱ’ and the vowel ‘ㅏ’.</p>
<p>A <dfn id="composition-window">composition window</dfn> is a window
that shows ASCII characters being composed by
<a href="#phonetic-composer">phonetic composers</a> or
<a href="#phonetic-radical">phonetic radicals</a> being composed by
<a href="#radical-composer">radical composers</a>.</p>
<p>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 phonetic characters, some composers (such as
Bopomofo composers) output a placeholder character
instead of phonetic characters while composing text.</p>
<section id="phonetic-composer-section">
<h3>Phonetic Composer</h3>
<p>Phonetic composers are not only used for typing Simplified
Chinese and Japanese, but also used for typing non-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 pronunciation: 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 phonetic composer uses these
mapping tables to compose a phonetic character from a sequence of
ASCII characters produced by a US keyboard.</p>
<p>An example of a phonetic composer for Simplified Chinese outputs
the ASCII characters that were input by the user, as its
composition text.</p>
<figure id="fig-ascii-composition-text">
<p><img height="180" src="images/image11.png" width="352"></p>
<figcaption>Composition text (Simplified Chinese)</figcaption>
</figure>
<p>On the other hand, a typical phonetic composer for Japanese
outputs phonetic characters when the typed ASCII characters have
corresponding phonetic characters.</p>
<figure id="fig-kana-composition-text">
<p><img height="180" src="images/image13.png" width="352"></p>
<figcaption>Composition text (Japanese)</figcaption>
</figure>
<p>An example of a phonetic composer for mathematical symbols
outputs composed mathematical symbol and shows the source
keystrokes in its own window, which is an example of a composition
window.</p>
<figure id="fig-composition-window">
<p><img height="214" src="images/image14.png" width="435"></p>
<figcaption>Composition text (Latex input)</figcaption>
</figure>
</section>
<section id="radical-composer-section">
<h3>Radical Composer</h3>
<p>Radical composers are mainly used for typing Traditional
Chinese and Korean with phonetic keyboards. Each phonetic
keyboard of these languages can produce phonetic radicals:
e.g., typing ‘r’ produces ‘ㄱ’
on a Korean keyboard; typing ‘o’ produces
‘人’ on a Traditional-Chinese (or Bopomofo)
keyboard, etc. A radical composer composes a phonetic
character from phonetic radicals given by these keyboards:
e.g., typing ‘ㄱ’ (r) and ‘ㅏ’
(k) produces ‘가’ on a Korean keyboard;
typing ‘人’ (o), ‘弓’ (n), and
‘火’ (f) produces ‘你’ on a
Traditional-Chinese keyboard, etc.</p>
<p>A radical composer for Korean outputs the phonetic radicals as
its composition text.</p>
<figure id="fig-radical-composer-korean">
<p><img height="180" src="images/image15.png" width="352"></p>
<figcaption>Radical composer (Korean)</figcaption>
</figure>
<p>A radical composer for Traditional Chinese outputs a
placeholder character (U+3000) and shows the phonetic radicals
being composed to its own window. This window is an example
of a composition window.</p>
<figure id="fig-radical-composer-chinese">
<p><img height="180" src="images/image02.png" width="352"></p>
<figcaption>Radical composer (Traditional Chinese)</figcaption>
</figure>
<p>Some platforms (such as Mac and Linux) use radical composers
for typing accented characters used in European countries.
For example,
typing ‘ ̈ ’ (option+u) and ‘a’ (a)
produces ‘ä’ on US keyboards of Mac.</p>
<figure id="fig-radical-composer-mac">
<p><img height="177" src="images/image01.png" width="479"></p>
<figcaption>Radical composer (Mac)</figcaption>
</figure>
</section>
<section id="on-screen-keyboard-section">
<h3>On-Screen Keyboard</h3>
<p>On touch-based platforms without hardware keyboard like
mobile phone or tablet platforms, some kind of on-screen keyboard
is displayed to help a user typing text, which occupies some
part of the screen. A user uses this keyboard to type composition
text.</p>
<figure id="fig-on-screen-keyboard-english">
<p><img height="557" src="images/mobile_ime_keyboard_en.png" width="416"></p>
<figcaption>An example of an on-screen keyboard (English)</figcaption>
</figure>
<p>The layout of an on-screen keyboard may vary depending on
language or its input modality (e.g. a telephone number
input field requires number buttons only).</p>
<figure id="fig-on-screen-keyboard-japanese">
<p><img height="467" src="images/mobile_ime_keyboard_jp.png" width="416"></p>
<figcaption>An example of an on-screen keyboard (Japanese)</figcaption>
</figure>
</section>
</section>
<section id="converter-section">
<h2>Converter</h2>
<p>A converter is a context-sensitive parser used for replacing
the outputs of a composer to ideographic characters on Chinese,
Japanese, and Korean.</p>
<p class="note">Korean seldom uses ideographic characters.</p>
<p>Because Chinese, Japanese, and Korean have many homonyms, each
sequence of phonetic characters usually matches many ideographic
characters: e.g., a Japanese
phonetic character ‘か’ matches Japanese
ideographic characters
‘化’, ‘科’,
‘課’,
etc.; Pinyin characters ‘ka’ matches Simplified-Chinese
ideographic characters ‘卡’,
‘喀’,
‘咯’, etc.; Bopomofo characters
‘人弓’ matches Traditional-Chinese
ideographic characters ‘乞’,
‘亿’, ‘亇’, etc.</p>
<p>A converter looks up a dictionary and shows a list of
candidates of possible ideographic characters so a user can choose
one. This list is known as a <dfn id="candidate-list">candidate
list</dfn>.
A candidate list is known as a <dfn id="candidate-window">candidate
window</dfn> when it has its own window.</p>
<p>Some Japanese IMEs show annotations in its
<a href="#candidate-window">candidate window</a>
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.</p>
<figure id="fig-candidate-window-japanese">
<p><img height="342" src="images/image05.png" width="393"></p>
<figcaption>Candidate window (Japanese)</figcaption>
</figure>
<p>The next figure shows a <a href="#candidate-window">candidate
window</a> of a Simplified-Chinese IME.</p>
<figure id="fig-candidate-window-simplified-chinese">
<p><img height="308" src="images/image04.png" width="390"></p>
<figcaption>Candidate window (Simplified Chinese)</figcaption>
</figure>
<p>And the next figure shows a <a href="#candidate-window">candidate
window</a> of a Traditional-Chinese IME.</p>
<figure id="fig-candidate-window-traditional-chinese">
<p><img height="180" src="images/image06.png" width="352"></p>
<figcaption>Candidate window (Traditional Chinese)</figcaption>
</figure>
<p>Some techniques are used to improve conversion quality.
For example, a converter integrates an <dfn id="MRU">MRU</dfn>
(Most-Recently Used) list.
Even though there are many ideographic characters for each phonetic
character (or phonetic radical), a user does not usually use all
these ideographic characters. A converter uses an
<a href="#MRU">MRU list</a> to filter out ideographic characters not
used so often from a <a href="#candidate-list">candidate list</a>.
Another example is a grammar parser. A converter that
integrates a grammar parser splits the given phonetic characters
into grammatical clauses and converts only one clause at a time.
When a sequence of phonetic characters consists 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 converter,
a converter usually processes one clause at a time. This clause is
called the <dfn id="selected-clause">selected clause</dfn>.</p>
<p>An IME usually renders a <a href="#selected-clause">selected
clause</a> with a special style to distinguish it from other
clauses, as shown in the following figure.</p>
<figure id="fig-selected-clause">
<p><img height="346" src="images/image08.png" width="394"></p>
<figcaption>Selected clause (Japanese)</figcaption>
</figure>
<p>When a converter converts two or more clauses, it chooses
candidates for the selected clause so it becomes grammatically
consistent with the surrounding clauses:
e.g., Japanese converters usually output
‘危機一髪’ (not
‘危機一発’)
for Japanese phonetic characters
‘ききいっぱつ’
because
‘危機一発’ is grammatically
incorrect.</p>
<p>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 on-screen keyboard.
</p>
<figure id="fig-mobile-ime">
<p><img height="651" src="images/mobile_ime_composition.png" width="416"></p>
<figcaption>Composition on mobile platform (Japanese)</figcaption>
</figure>
<figure id="fig-mobile-ime2">
<p><img height="592" src="images/mobile_ime_composition3.png" width="416"></p>
<figcaption>Composition on mobile platform (Japanese)</figcaption>
</figure>
</section>
</section>
<section id="conformance">
<p>Implementations that use ECMAScript to implement the APIs defined in
this specification must implement them in a manner consistent with
the ECMAScript Bindings defined in the Web IDL specification
[[WEBIDL]], as this specification uses that specification and
terminology.</p>
</section>
<section id="terminology">
<h1>Terminology and Algorithms</h1>
<p><i>To be written.</i></p>
</section>
<section>
<h1>The inputMethodContext property</h1>
<p>Authors can get an object which implements the
<a>InputMethodContext</a>
interface on an editable
element, which can get keyboard input first
(i.e. a “target” element).
If this property is accessed
on a non-editable element, a user agent SHOULD
return a context for the innermost editable or focusable element
to the element. In this case, the <code>target</code> property
in the <a>InputMethodContext</a>
interface points to the target element.
If all ancestors of an element are neither editable nor focusable,
this property returns <code>null</code>.</p>
<p>To control the IME attached to an element, it is a good idea to add
this property to the HTMLElement interface.</p>
<dl title="partial interface HTMLElement" class="idl">
<dt>readonly attribute InputMethodContext? inputMethodContext</dt>
<dd>
<p>Returns an <a>InputMethodContext</a> interface associated with
this element.</p>
<p>To change the behavior of the IME associated with an
element, authors MUST first obtain an <a>InputMethodContext</a>
interface from the <code>inputMethodContext</code> property of
the HTMLElement interface.</p>
<p>The returned <a>InputMethodContext</a> interface MAY not be directly
associated to the element. An interface MAY be shared
among elements under an innermost editable or focusable element.
In that case, <code>target</code> property in the
<a>InputMethodContext</a> interface points to the element which owns
the interface.</p>
</dd>
</dl>
</section>
<section id="inputmethodcontext-interface">
<h1>The InputMethodContext Interface</h1>
<dl title="interface InputMethodContext : EventTarget" class="idl">
<dt>attribute EventHandler oncandidatewindowshow</dt>
<dd><p>This event should be fired immediately after the IME
candidate window is set to appear, which means immediately after
the position information for the candidate window has been
identified.</p>
<p>Common things among oncandidatewindowshow/update/hide events:</p>
<ol><lI>To get a better performance, these events are of the generic
"Event" interface and fired directly to the
<a>InputMethodContext</a> object. They do not bubble or capture
through the DOM tree.</li>
<li>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 <a>InputMethodContext</a>
object upon which the event is firing.</li>
<li>These events are not cancellable, meaning that the appearing
of the candicate window cannot be controlled via these events
by cancelling them.
<li>Web applications need only register for these events once
per element (the handlers will remain valid for as long as
the element is alive.</li>
</ol></dd>
<dt>attribute EventHandler oncandidatewindowupdate</dt>
<dd><p>This events should be fired after either:</p>
<ol>
<li>The IME candidate window has been identified as needing to
change size (but before animating to the new position) as a
result of displaying new/changed alternatives or predictions.</li>
<li>The IME candidate window has been identified as needing to
change size (but before animating to the new position) due to
user-zoom, browser frame resize, or other action that changes
the candidate window placement.</li>
</ol>
<p>In either case, the event should be fired after the new
size/location of the candidate window is known by the user agent.
</dd>
<dt>attribute EventHandler oncandidatewindowhide</dt>
<dd>This event should be fired after the candidate window is fully
hidden (after the dismissal animation has ended, if there is any).
The event handler code will see that no ClientRect can be obtained
inside this handler.</dd>
<dt>readonly attribute HTMLElement? target</dt>
<dd>
<p>Represents the element associated with the <a>InputMethodContext</a>
object.</p>
<p>Once a target element gets deleted or modified not to accept
any input, any access to the
<a href="#inputmethodcontext-interface">InputMethodContext</a>
interface through the object has no effect. Any method calls
will just return, accesses to <code>target</code> will return
null.
</p>
</dd>
<dt>readonly attribute unsigned long compositionStartOffset</dt>
<dd>
<p>Represents the starting offset of the composition relative to
the target if a composition is occurring, or 0 if there is no
composition in progress. For composition occurring on an
<code><input></code> or <code><textarea></code>
element, the
<code>compositionStartOffset</code> is the starting offset of
the composition within the target's <code>value</code> string.
For compositions occurring on an element with the
<code>contentEditable</code>
flag set, then this is the starting offset relative to the
target's <code>textContent</code> property (textContent is a
linear view of all the text under an element).
</p>
</dd>
<dt>readonly attribute unsigned long compositionEndOffset</dt>
<dd>
<p>Represents the ending offset of the composition,
in a similar way to <code>compositionStartOffset</code>.
</p>
</dd>
<dt>ClientRect getCandidateWindowClientRect()</dt>
<dd><p>
An web application may use this information to explicitly control
the position for its own input-related UI elements, such as search
suggestions.</p>
<p>Note: client coordinates are in document pixels and have origin
at the upper-left corner of the client area.</p></dd>
<dt>sequence<DOMString> getCompositionAlternatives()</dt>
<dd><p>Returns a copy (per call) of the current list of alternate
candidate strings from the InputMethodContext object.
The InputMethodContext object can produce alternates while it
has a composition in progress. When no composition is going on,
getCompositionAlternatives() will always return an empty list.
The list of alternatives is not updated "live"; it is only
updated between compositionupdate events.
</p></dd>
</dl>
</section>
<section class="informative" id="best-practices">
<h1>Best Practices</h1>
<p>This specification provides an interface for developing IME-aware
Web applications.</p>
<p>This section describes practices for some use-cases.</p>
<section id="life-of-inputmethodcontext">
<h1>Life of InputMethodContext</h1>
<p>Once a <a>InputMethodContext</a> interface is obtained,
it should be valid for the lifetime of its <code>target</code>
element's lifetime, as long 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.</p>
<p>Any access to the <a>InputMethodContext</a> 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.
</p>
</section>
</section>
<section id="acknowledgements">
<h1>Acknowledgements</h1>
<p>The editors would like to thank Brendan Elliott, Jianfeng Lin, and Travis Leithead from Microsoft Corporation for their technical feedback and assistance.</p>
</section>
</body>
</html>