CompositionEvent

  • Revision slug: DOM/CompositionEvent
  • Revision title: CompositionEvent
  • Revision id: 386005
  • Created:
  • Creator: ethertank
  • Is current revision? No
  • Comment

Revision Content

{{IFSummary("dom/interfaces/events/nsIDOMCompositionEvent.idl", "nsIDOMUIEvent", "Scriptable", "9.0", "An event interface for composition events", "9.0")}}

The DOM CompositionEvent represents events that occur due to the user indirectly entering text.

Method overview

void initCompositionEvent(in DOMString typeArg,in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in DOMString dataArg, in DOMString localeArg);

Attributes

Attribute Type Description
data {{domxref("DOMString")}}

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.

For {{domeventxref("compositionupdate")}}, this is the string as it stands currently as editing is ongoing.

For {{domeventxref("compositionend")}} events, this is the string as committed to the editor.

Read only.

locale {{domxref("DOMString")}}

The locale of current input method (for example, the keyboard layout locale if the composition is associated with IME). Read only.

Methods

initCompositionEvent

Initializes the attributes of a composition event.

void initCompositionEvent(
  in DOMString typeArg,
  in boolean canBubbleArg,
  in boolean cancelableArg,
  in views::AbstractView viewArg,
  in DOMString dataArg,
  in DOMString localeArg
);
Parameters
typeArg
The type of composition event; this will be one of {{domevent("compositionstart")}}, {{domevent("compositionupdate")}}, or {{domevent("compositionend")}}.
canBubbleArg
Whether or not the event can bubble.
cancelableArg
Whether or not the event can be canceled.
viewArg
?
dataArg
The value of the data attribute.
localeArg
The value of the locale attribute.

Specification

Browser compatibility

{{CompatibilityTable}}
Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support {{CompatVersionUnknown}} {{CompatGeckoDesktop("9.0")}} {{CompatVersionUnknown}} {{CompatNo}} {{CompatUnknown}}
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support {{CompatUnknown}} {{CompatGeckoMobile("9.0")}} {{CompatUnknown}} {{CompatUnknown}} {{CompatUnknown}}

Gecko notes

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")}}.

Note: Gecko doesn't support the locale attribute for trusted events yet.  However, web developers can set this value via initCompositionEvent() when creating untrusted events.

Gecko's editors (for example, <input type="text">, <div contenteditable/>, and designMode) start composition after the bubble phase of compositionstart. So, by the time your compositionstart handler is called, no contents have not been modified.

Gecko's editors don't handle the compositionupdate event yet. By the time your compositionupdate handler is called, no contents have been modified.

By the time your compositionend event handler is called, composition is complete, and no further changes will occur. For that reason, if you call {{domxref("event.stopPropagation()")}} on the compositionstart or compositionend 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.

See also

  • {{domeventxref("compositionstart")}}
  • {{domeventxref("compositionend")}}
  • {{domeventxref("compositionupdate")}}
  • UIEvent
  • Event

Revision Source

<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-US/docs/DOM/CompositionEvent#initCompositionEvent()" title="DOM/CompositionEvent#initCompositionEvent()">initCompositionEvent</a>(in DOMString typeArg,in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in DOMString dataArg, in DOMString localeArg);</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>{{domxref("DOMString")}}</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>{{domxref("DOMString")}}</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 href="http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#events-compositionevents" title="http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#events-compositionevents">DOM&nbsp;Level 3: Composition Events</a></li>
</ul>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<div>{{CompatibilityTable}}</div>
<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.&nbsp; 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-US/docs/DOM/Event/UIEvent" title="UIEvent">UIEvent</a></li>
  <li><a href="/en-US/docs/DOM/event" title="Event">Event</a></li>
</ul>
<!--languages( { "ja": "ja/DOM/CompositionEvent" } )-->
Revert to this revision