-
Notifications
You must be signed in to change notification settings - Fork 0
/
Annex.html
675 lines (656 loc) · 30.4 KB
/
Annex.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
<!doctype html>
<html>
<head>
<!-- foo -->
<meta charset="UTF-8">
<title>Input Method Editor API Annex</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: "kochi@google.com"
},
{ name: "Kenji Baheux",
company: "Google",
mailto: "kenjibaheux@google.com"
},
{ 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>
<p class="note">
The original IME API was written with APIs in this document, but for
the standardization process to proceed smoothly, we extract what we agree
on as a <a href="Overview.html">“main” part</a> first to
make it a public standard faster.<br>
This document includes all the APIs including what is already included
in the main part, but the editor is planning to make this diff-only
(i.e. all interfaces will be partial).<br>
The content of this document may (or may not) be merged into the main
API spec in the future.
</p>
<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 methods to
retrieve detailed data from an in-progress IME
<a href="#ime-composition">composition</a>.</li>
<li>A <a>CompositionEvent</a> interface, which represents read-only
attributes about the current
<a href="#ime-composition">composition</a>, such as actual text
and its associated information.</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 when
they want text input on non-editable elements such as the
<code><div></code> element without <code>contenteditable</code>
attribute being set to <code>true</code>, or interact with IMEs;
those difficulties include
the fact that a Web application cannot do the following:</p>
<ul>
<li>get input outside any editable element even with focus</li>
<li>indicate to the user whether the Web application renders
composition text by itself, or needs to ask user agents to
render it</li>
<li>determine the place where user agents render composition text</li>
<li>determine the place where user agents render
<a href="#candidate-window">candidate windows</a></li>
</ul>
<p>To solve these IME-related problems, this specification introduces
an IME API that allows Web applications to interact with the IME.
This specification introduces interfaces for
<a href="#ime-composition">compositions</a>,
so Web applications can read detailed composition data.
A <a>CompositionEvent</a> object provides a reference to an ongoing IME
<a href="#ime-composition">composition</a>,
so Web applications can retrieve the composition text and
its attributes. In addition,
this API also gives Web applications the ability to
give a hint as to where to position a
<a href="#composition-window">composition window</a>.
<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="use-cases/Overview.html">use cases for Input Method Editor
API </a>document for more information about possible use cases.</p>
<p>Consider the following examples.</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>
<p>This example shows the source which draws composition text in
its own style.</p>
<p class="note">For the usage of compositionupdate event, see also
the note in
<a href="#drawing-composition-text">Drawing Composition Text</a>
section.
</p>
<pre class="example highlight" id="ex-drawing-composition">
<!DOCTYPE html>
<html>
<head>
<style>
.clause {
margin-right: 2px;
border-style: solid;
border-width: 0px 0px 1px 0px;
border-color: #333333;
}
.selected {
border-width: 0px 0px 2px 0px;
border-color: #000000;
}
</style>
<script language="javascript" type="text/javascript">
// compositionupdate event handler
function onCompositionUpdate(event) {
var target = event.target;
// Remove all children.
while (target.childNodes.length < 0) {
edit.removeChild(edit.childNodes[0]);
}
// Get the IME context.
var ctx = target.inputMethodContext;
// Create clause spans.
var text = event.data;
var segments = event.getSegments();
for (i = 0; i < segments.length; i++) {
var span = document.createElement('span');
span.classList.add('clause');
var selected = false;
if (segments[i] == event.activeSegmentStart) {
selected = true;
span.classList.add('selected');
}
var end = text.length;
if (i < segments.length - 1) {
end = segments[i + 1];
}
span.textContent = text.substring(segments[i], end);
target.appendChild(span);
if (selected) {
ctx.setCaretRectangle(document.body, rect.left, rect.top,
rect.width, rect.height);
}
}
// Prevent the browser from drawing composition text.
event.preventDefault();
}
function init() {
var composition = document.getElementById('composition');
composition.enableEditingEvents();
composition.focus();
composition.addEventHandler('compositionupdate', onCompositionUpdate, false);
}
</script>
</head>
<body onload="init();">
<div id="composition"></div>
</body>
</html>
</pre>
</section>
<section class="informative" id="background">
<h1>Background: What’s an Input Method Editor?</h1>
<p><i>See <a href="Overview.html#background">the main document</a>.</i></p>
</section>
<section id="conformance">
<p><i>More to be written.</i></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 or
<a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#focusable">focusable</a>
element, which can get keyboard input first
(i.e. a “target” element).
.
If this property is accessed
on non-editable, non-focusable 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="compositionevent-interface">
<h1>The CompositionEvent Interface</h1>
<p>This interface represents an ongoing IME composition, by extending
<a href="http://www.w3.org/TR/DOM-Level-3-Events/#interface-CompositionEvent">CompositionEvent interface</a> definedin [[DOM-LEVEL-3-EVENTS]].
It provides attributes representing the text being composed by an IME
and its associated information.</p>
<dl title="partial interface CompositionEvent" class="idl">
<dt>readonly attribute long activeSegmentStart</dt>
<dd><p>Represents the 0-based index to the first character of
the active segment in the current composition text.</p>
<p class="note">An author can assume that
<code>activeSegmentStart</code> and <code>activeSegmentEnd</code>
boundary fit in with any of <code>segments</code>, and
that <code>activeSegmentStart</code> is equal or less than
<code>activeSegmentEnd</code>.</p></dd>
<dt>readonly attribute long activeSegmentEnd</dt>
<dd><p>Represents the 0-based index to the next position of
the last character of the active segment in the current composition
text.
If there is no active segment, activeSegmentStart and
activeSegmentEnd MUST be the same value and they indicate
the position of the caret.</p>
<p>For example, if “DEF” is selected in composition
text “abcDEFghi”, <code>activeSegmentStart</code> is 3
and <code>activeSegmentEnd</code> is 6.
If the caret is between “B” and “C”
in composition text “ABCD”, both
<code>actieSegmentStart</code> and <code>activeSegmentEnd</code> are 2.
</p></dd>
<dt>sequence<unsigned long> getSegments()</dt>
<dd>If composition text is segmented into clauses by an IME,
this array contains 0-based indices of the starting character of
each clause in increasing order. If composition text is not
segmented, it contains one '0' element.
<p class="note">This can be used to render compostion text as
segmented clauses, but how to visualize them are not specified
here. It is recommended to follow the platform standard way to
visualize the segmentation (e.g. using underline or reverse
background etc.).</p>
<p class="note">The way the platform standard renders composition
text might be customized by a user (e.g. for accessibility).
CSS property to indicate the current default style to render
the composition is desired.
</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 DOMString locale</dt>
<dd>Represents the locale of the current input method as
a BCP-47 tag (e.g. "en-US").
The locale MAY be the empty string when
inapplicable or unknown.
<p class="note">More clarification should be written on
how IME locale should be described using BCP-47.</p>
</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>composition</code> and
<code>target</code> will return null, and accesses to
<code>locale</code> will return the empty string.
</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>void confirmComposition()</dt>
<dd>
<p>Finishes the ongoing composition of the hosting user agent.</p>
<p>When a Web application calls this function, a user agent sends a
compositionend event and a textInput event as a user types an
‘Accept’ key as written in
<a href="http://www.w3.org/TR/DOM-Level-3-Events/#keys-IME">“Input Method Editors” section the DOM Level 3 Events specification</a>
[[!DOM-LEVEL-3-EVENTS]].</p>
<p class="note">This may cause the race condition when a script
calls confirmComposition while system IME gets accept key in the
same time, a user agent may confirm the ongoing composition twice.
Instead,
<a href="http://lists.w3.org/Archives/Public/public-webapps/2013AprJun/0361.html">
introducing cancelComposition() is proposed
</a>
and when a script needs the behavior of confirmComposition(), it
can commit the current composition and then call
cancelComposition().</p>
</dd>
<dt>void setCaretRectangle(Node anchor, long x, long y, long w, long h)</dt>
<dd>
<p>Notifies the rectangle of composition text to a user agent. When
a user agent renders a
<a href="#candidate-window">candidate window</a>
or a composition window, it uses
this rectangle to draw windows next to the composition or
prevent these windows from being rendered on this rectangle.</p>
<p>If a Web application wants to render composition text itself,
it has to tell a user agent where the composition text will be
located whenever it gets <code>compositionstart</code> event
or <code>compositionend</code> event.</p>
<p>On Windows, this rectangle is used as a parameter for
ImmSetCandidateWindow(). On Mac, this rectangle is sent when it calls
[firstRectForCharacterRange:]. On Linux (GTK), this rectangle is used as a
parameter for gtk_im_context_set_cursor_location().</p>
<ul>
<li>The <var>anchor</var> parameter represents the DOM node
against which the rectangle is positioned. This MAY
be a different node than the node that listens to composition
events which has focus and therefore a Web application can
draw composition text where it does not have focus.
</li>
<li>The <var>x</var>, and <var>y</var> are the offsets to the
top-left of the rectangle relative to <var>anchor</var>
node's top-left.</li>
<li>The <var>w</var>, and <var>h</var> are width and height of
the rectangle.</li>
</ul>
<p>These set values apply only to the current
composition session (i.e. until <code>compositionend</code>
event is sent).</p>
<p>A user agent MAY need to convert these
coordinates to the screen coordinates when it shows a
<a href="#candidate-window">candidate window</a>.
</dd>
<dt>void enableEditingEvents()</dt>
<dd>
<p>Causes the target element of this context to get editing
events (e.g. <code>input</code>,
<code>compositionupdate</code>) delivered when the element
is focused.</p>
<p>If this method is called on a editable element (
<code><input></code>, <code><textarea></code>,
<code>contenteditable=true</code>), it has no effect.</p>
</dd>
<dt>void disableEditingEvents()</dt>
<dd>
<p>Causes the target element of this context to turn off
receiving editing events (e.g. <code>input</code>,
<code>compositionupdate</code>) after
<code>enableEditingEvents()</code> is called.</p>
<p>If this method is called on a editable element (
<code><input></code>, <code><textarea></code>,
<code>contenteditable=true</code>), it has no effect.</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 id="drawing-composition-text">
<h1>Drawing Composition Text</h1>
<p class="note" id="note-beforeInput">As of this writing, the order of
<code>compositionupdate</code> event and DOM update is being
discussed
(see <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=18931">Bug 18931</a>)
and if <code>compositionupdate</code> event happens after
DOM modification, this section has to be rewritten using
<code>beforeInput</code> event, which is also being discussed.
Example 2 code should be updated as well.</p>
<p>If a Web application wants to draw composition text by itself,
it SHOULD handle the <code>compositionupdate</code> event
to get notified from the IME that the composition text has been
changed, and then
use the interface described in this document to retrieve
composition and let the IME know
where the composition text is drawn by calling
<code>setCaretRectangle()</code> method.
If <code>setCaretRectangle()</code> is not called, IME will not have
information about where to show IME UIs, and it may show UIs at
an obtrusive position. To avoid this situation, a user agent may
set some decent default position in the vicinity of the focused
input field.
<p>When a Web application draws composition text, it MUST call
<code>preventDefault()</code> in <code>compositionupdate</code>
handler so that the user agent will not draw the text.</p>
<p>When a Web application wants to handle DOM level3 composition events
on a non-<code><input></code>, <code><textarea></code>,
or <code>contenteditable</code> node,
it MUST call <code>enableEditingEvents()</code> method beforehand
and focus it to get composition events.</p>
<p>The following diagram shows the flow of events
among the keyboard, the IME, the user agent, and the Web application
when a user types
‘kyouha’ to convert to
‘今日は’.</p>
<figure id="fig-imeapi-flow">
<p><img height="1133" src="images/imeapi_flow.png" width="744"></p>
<figcaption>Event flow of IME and an IME-aware Web application.</figcaption>
</figure>
</section>
</body>
</html>