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", "");
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); |
| 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. |
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);
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();
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);
Sets new composition string. This must be called before every call of dispatchEvent().
void setString(in AString aString);