nsICompositionStringSynthesizer 编辑

dom/interfaces/base/nsICompositionStringSynthesizer.idlScriptable This interface is a composition string synthesizer interface that synthesizes composition string with arbitrary clauses and a caret 1.0 66 Introduced Gecko 26 Obsolete Gecko 38 Inherits from: nsISupports Last changed in Gecko 38.0 (Firefox 38.0 / Thunderbird 38.0 / SeaMonkey 2.35)

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.windowUtils;
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", "");

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

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

boolean dispatchEvent();

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

void setString(in AString aString);

Constants

Constant	Value	Description
ATTR_RAW_INPUT	0x02	A clause attribute. This means that the clause is not converted. I.e., raw text of user input.
ATTR_SELECTEDRAWTEXT	0x03	A clause attribute but this is typically not used. This means that the clause is not converted but selected to convert or modify.
ATTR_CONVERTEDTEXT	0x04	A clause attribute. This means that the clause is already converted.
ATTR_SELECTEDCONVERTEDTEXT	0x05	A clause attribute. This means that the clause is already converted and is selected to convert.

Methods

appendClause()

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.

dispatchEvent()

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.

setCaret()

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)

setString()

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

void setString(in AString aString);

Parameters

aString

New composition string.