nsICompositionStringSynthesizer

This interface is obsoleted in Gecko 38. You need to use nsITextInputProcessor instead of this.

Every instance is associated with a DOM window at created by nsIDOMWindowUtils.createCompositionStringSynthesizer(). To create an instance for this:

var domWindowUtils = window.QueryInterface(Components.interfaces.nsIInterfaceRequestor)
                     .getInterface(Components.interfaces.nsIDOMWindowUtils);
var compositionStringSynthesizer = domWindowUtils.createCompositionStringSynthesizer();

For example, when you create a composition whose composing string is "foo-bar-buzz" and "bar" is selected to convert, then, first, you need to start composition:

domWindowUtils.sendCompositionEvent("compositionstart", "", "");

Next, dispatch composition string with crause information and caret information (optional):

// set new composition string with .setString().
compositionStringSynthesizer.setString("foo-bar-buzz");
// set clause information with .appendClause().
compositionStringSynthesizer.appendClause("foo-".length,  compositionStringSynthesizer.ATTR_CONVERTEDTEXT);
compositionStringSynthesizer.appendClause("bar".length,   compositionStringSynthesizer.ATTR_SELECTEDCONVERTEDTEXT);
compositionStringSynthesizer.appendClause("-buzz".length, compositionStringSynthesizer.ATTR_CONVERTEDTEXT);
// set caret position in the composition string. (optional)
compositionStringSynthesizer.setCaret("foo-bar".length, 0);
// dispatch DOM events to modify the focused editor
compositionStringSynthesizer.dispatchEvent();

When you modify the composing string, you don't need to recreate the instance anymore. The composing string information is cleared by a call of .dispatchEvent(). For example, if the "bar" is converted to "BAR":

compositionStringSynthesizer.setString("foo-BAR-buzz");
compositionStringSynthesizer.appendClause("foo-".length,  compositionStringSynthesizer.ATTR_CONVERTEDTEXT);
compositionStringSynthesizer.appendClause("BAR".length,   compositionStringSynthesizer.ATTR_SELECTEDCONVERTEDTEXT);
compositionStringSynthesizer.appendClause("-buzz".length, compositionStringSynthesizer.ATTR_CONVERTEDTEXT);
compositionStringSynthesizer.setCaret("foo-BAR".length, 0);
compositionStringSynthesizer.dispatchEvent();

Finally, when you commits composition with the last composition string "foo-BAR-buzz":

// Deprecated in 36, first, dispatch commit string without clause information
compositionStringSynthesizer.setString("foo-BAR-buzz");
compositionStringSynthesizer.dispatchEvent();
// Then, dispatch compositionend with the commit string
domWindowUtils.sendCompositionEvent("compositionend", "foo-BAR-buzz", "");

Requires Gecko 36 Starting Gecko 36, You can do it simpler:

domWindowUtils.sendCompositionEvent("compositioncommitasis", "", "");

If you need to commit composition with different commit string Gecko 36 or later, you can use "compositioncommit":

domWindowUtils.sendCompositionEvent("compositioncommit", "FOO-BAR-BUZZ", "");

Method overview

Constants

Methods

Appends a clause to the composition string which is set by setString(). Sum of aLength must be same as the length of aString of setString().

void appendClause(in unsigned long aLength,
                  in unsigned long aAttribute);

Parameters

aLength

The length of appending clause.

aAttribute

The attribute of appending clause. Must be one of ATTR_* constants.

Dispatches DOM events for setting the composition string which are specified by setString(), appendClause() and setCaret() to the focused editor.

If appendClause() hasn't been called, this dispatches events to set composition string without clause information. In other words, commits composition string.

If appendClause() and/or setCaret() are not called properly, e.g., sum of aLength of calls of appendClause() is not same as composition string set by setString(), this throws an exception.

After a call of this, all stored composition string information is cleared. Therefore, you can reuse the instance for modifying composition string.

boolean dispatchEvent();

Return value

If dispatched event's default is prevented, returns true. However, this must always return false since all dispatching DOM events are not cancelable.

Sets caret position in the composition string set by setString(). This is optional.  I.e., you may not call this before dispatchEvent().

void setCaret(in unsigned long aOffset,
              in unsigned long aLength);

Parameters

aOffset

Caret offset in the composition string. This value must be between 0 and the length of aString of setString().

aLength

If you want wide caret, you can set over 0. However, Gecko doesn't support wide caret yet. (bug 979112)

Sets new composition string. This must be called before every call of dispatchEvent().

void setString(in AString aString);

Parameters

aString

New composition string.