Revision 286772 of CompositionEvent

<p>{{ IFSummary("dom/interfaces/events/nsIDOMCompositionEvent.idl", "nsIDOMUIEvent", "Scriptable", "9.0", "An event interface for composition events", "9.0") }}</p>
<p>The DOM <code>CompositionEvent</code> represents events that occur due to the user indirectly entering text.</p>
<h2 id="Method_overview">Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code>void <a href="/en/DOM/CompositionEvent#initCompositionEvent()" title="en/DOM/CompositionEvent#initCompositionEvent()">initCompositionEvent</a>(in DOMString typeArg,in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in DOMString dataArg, in DOMString localeArg);<br> </code></td> </tr> </tbody>
</table>
<h2 id="Attributes">Attributes</h2>
<table class="standard-table"> <tbody> <tr> <td class="header">Attribute</td> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>data</code></td> <td><a href="/en/DOMString" title="en/DOMString"><code>DOMString</code></a></td> <td> <p>For {{ domeventxref("compositionstart") }} events, this is the currently selected text that will be replaced by the string being composed. This value doesn't change even if content changes the selection range; rather, it indicates the string that was selected when composition started.</p> <p>For {{ domeventxref("compositionupdate") }}, this is the string as it stands currently as editing is ongoing.</p> <p>For {{ domeventxref("compositionend") }} events, this is the string as committed to the editor.</p> <p><strong>Read only</strong>.</p> </td> </tr> <tr> <td><code>locale</code></td> <td><a href="/en/DOMString" title="en/DOMString"><code>DOMString</code></a></td> <td> <p>The locale of current input method (for example, the keyboard layout locale if the composition is associated with IME). <strong>Read only.</strong></p> </td> </tr> </tbody>
</table>
<h2 id="Methods">Methods</h2>
<h3 id="initCompositionEvent">initCompositionEvent</h3>
<p>Initializes the attributes of a composition event.</p>
<pre>void initCompositionEvent(
  in DOMString typeArg,
  in boolean canBubbleArg,
  in boolean cancelableArg,
  in views::AbstractView viewArg,
  in DOMString dataArg,
  in DOMString localeArg
);
</pre>
<h6 id="Parameters">Parameters</h6>
<dl> <dt><code>typeArg</code></dt> <dd>The type of composition event; this will be one of {{ domevent("compositionstart") }}, {{ domevent("compositionupdate") }}, or {{ domevent("compositionend") }}.</dd> <dt><code>canBubbleArg</code></dt> <dd>Whether or not the event can bubble.</dd> <dt><code>cancelableArg</code></dt> <dd>Whether or not the event can be canceled.</dd> <dt><code>viewArg</code></dt> <dd>?</dd> <dt><code>dataArg</code></dt> <dd>The value of the <code>data</code> attribute.</dd> <dt><code>localeArg</code></dt> <dd>The value of the <code>locale</code> attribute.</dd>
</dl>
<h2 id="Specification">Specification</h2>
<ul> <li><a class="external" href="https://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#events-compositionevents" title="https://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#events-compositionevents">DOM Level 3: Composition Events</a></li>
</ul>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop"> <table class="compat-table"> <tbody> <tr> <th>Feature</th> <th>Chrome</th> <th>Firefox (Gecko)</th> <th>Internet Explorer</th> <th>Opera</th> <th>Safari</th> </tr> <tr> <td>Basic support</td> <td>{{ CompatVersionUnknown() }}</td> <td>{{ CompatGeckoDesktop("9.0") }}</td> <td>{{ CompatVersionUnknown() }}</td> <td>{{ CompatNo() }}</td> <td>{{ CompatUnknown() }}</td> </tr> </tbody> </table>
</div>
<div id="compat-mobile"> <table class="compat-table"> <tbody> <tr> <th>Feature</th> <th>Android</th> <th>Firefox Mobile (Gecko)</th> <th>IE Mobile</th> <th>Opera Mobile</th> <th>Safari Mobile</th> </tr> <tr> <td>Basic support</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatGeckoMobile("9.0") }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> </tr> </tbody> </table>
</div>
<h3 id="Gecko_notes">Gecko notes</h3>
<p>The {{ domeventxref("compositionstart") }} and {{ domeventxref("compositionend") }} events were fired in versions of Gecko before 9.0, but didn't have the DOM Level 3 attributes and methods. In addition, support for the {{ domeventxref("compositionupdate") }} event was added in Gecko 9.0 {{ geckoRelease("9.0") }}.</p>
<div class="note"><strong>Note:</strong> Gecko doesn't support the <code>locale</code> attribute for trusted events yet.  However, web developers can set this value via <code>initCompositionEvent()</code> when creating untrusted events.</div>
<p>Gecko's editors (for example, <code>&lt;input type="text"&gt;</code>, <code>&lt;div contenteditable/&gt;</code>, and <code>designMode</code>) start composition after the bubble phase of <code>compositionstart</code>. So, by the time your <code>compositionstart</code> handler is called, no contents have not been modified.</p>
<p>Gecko's editors don't handle the <code>compositionupdate</code> event yet. By the time your <code>compositionupdate</code> handler is called, no contents have been modified.</p>
<p>By the time your <code>compositionend</code> event handler is called, composition is complete, and no further changes will occur. For that reason, if you call {{ domxref("event.stopPropagation()") }} on the <code>compositionstart</code> or <code>compositionend</code> event, you can break composition behavior and cause editors to fail to manage editing properly. See {{ bug(697842) }} for progress on this problem getting fixed.</p>
<h2 id="See_also">See also</h2>
<ul> <li>{{ domeventxref("compositionstart") }}</li> <li>{{ domeventxref("compositionend") }}</li> <li>{{ domeventxref("compositionupdate") }}</li> <li><a href="/en/DOM/Event/UIEvent" title="UIEvent">UIEvent</a></li> <li><a href="/en/DOM/event" title="Event">Event</a></li>
</ul>
<p>{{ languages( { "ja": "ja/DOM/CompositionEvent" } ) }}</p>