Working with IME Composition Strings
A version of this page is also available for
4/8/2010
The Input Method Editor (IME) composition string is the current text in the composition window. Each composition string consists of one or more clauses, where a clause is the smallest combination of characters that have a meaning in the language.
As a user enters text in the composition window, the IME tracks the composition status, which includes attribute information, clause information, typing information, and cursor position.
Use the ImmGetCompositionString and ImmSetCompositionString functions to retrieve and set the composition status, or to retrieve and set the characters, attributes, and clauses of the composition string.
ImmSetCompositionString also allows notification messages to be sent to the composition window to ensure that this window updates its appearance based on the changes specified in this call. Applications that set a combination of composition status elements typically set the fNotify parameter to FALSE for all but the last call to this function so that only one notification message is generated for the composition window.
The attribute information is an array of 8-bit values that specifies the status of characters in the composition string. In this array, all characters of one clause must have the same attribute. For each value in the array, bits 0 through 3 can be a combination of the values in the following table.
| Value | Description |
|---|---|
ATTR_INPUT |
The character being entered by a user, not yet converted by the IME. |
ATTR_INPUT_ERROR |
The character is the error character and cannot be converted by the IME. |
ATTR_TARGET_CONVERTED |
The character converted by the IME. A user has selected this character, and the IME has converted it. |
ATTR_CONVERTED |
A converted character. The IME has already converted this character. |
ATTR_TARGET_NOTCONVERTED |
The character being converted. A user has selected this character, but the IME has not yet converted it. |
ATTR_FIXEDCONVERTED |
Characters that are not converted. The IME no longer converts these characters. |
The clause information is an array of 32-bit values that specifies the positions of the clauses in the composition string. Each clause has one value in the array that specifies the beginning of the clause. These clause positions are followed by a final value that specifies the length of the full string. Each value in the array specifies the offset, in bytes, from the beginning of the composition string to the clause. The first value is always 0 because the first clause always starts at the beginning of the string. For example, if a string has two clauses, the clause information has three values: the first value is 0, the second value is the offset of the second clause, and the third value is the length of the string.
The typing information is a null-terminated character string that represents the characters entered at the keyboard.
The cursor position is a value indicating the position of the cursor relative to the characters in the composition string. This value is the offset, in bytes, from the beginning of the string. If this value is 0, the cursor is immediately before the first character in the string. If the value is equal to the length of the string, the cursor is immediately after the last character. If the value is –1, the cursor is not present.