ImmSetCompositionStringW function (imm.h)
Sets the characters, attributes, and clauses of the composition and reading strings.
Syntax
BOOL ImmSetCompositionStringW(
HIMC unnamedParam1,
[in] DWORD dwIndex,
[in, optional] LPVOID lpComp,
[in] DWORD dwCompLen,
[in, optional] LPVOID lpRead,
[in] DWORD dwReadLen
);
Parameters
unnamedParam1
[in] dwIndex
Type of information to set. This parameter can have one of the following values.
| Value | Meaning |
|---|---|
|
Set the composition string, the reading string, or both. At least one of the lpComp and lpRead parameters must indicate a valid string. If either string is too long, the IME truncates it. |
|
Set attributes for the composition string, the reading string, or both. At least one of the lpComp and lpRead parameters must indicate a valid attribute array. |
|
Set the clause information for the composition string, the reading string, or both. At least one of the lpComp and lpRead parameters must point to a valid clause information array. |
|
Windows Me/98, Windows 2000, Windows XP: Ask IME to reconvert the string using a specified RECONVERTSTRING structure. |
|
Windows Me/98, Windows 2000, Windows XP: Ask IME to adjust the RECONVERTSTRING structure. Then the application can pass the adjusted structure into this function using SCS_SETRECONVERTSTRING. IME does not generate any WM_IME_COMPOSITION messages. |
[in, optional] lpComp
Pointer to a buffer containing the information to set for the composition string, as specified by the value of dwIndex.
[in] dwCompLen
Size, in bytes, of the information buffer for the composition string, even if SCS_SETSTR is specified and the buffer contains a Unicode string.
[in, optional] lpRead
Pointer to a buffer containing the information to set for the reading string, as specified by the value of dwIndex. The application can set this parameter to NULL.
[in] dwReadLen
Size, in bytes, of the information buffer for the reading string, even if SCS_SETSTR is specified and the buffer contains a Unicode string.
Return value
Returns a nonzero value if successful, or 0 otherwise.
Remarks
The application can set lpComp, lpRead, or both. If the application does not specify a value for lpComp, it must set this parameter to NULL and set dwCompLen to 0.
When the application is changing attributes, all characters in a clause must have the same attribute. Converted characters must have the attribute ATTR_CONVERTED or ATTR_TARGET_CONVERTED. Unconverted characters must have the attribute ATTR_INPUT or ATTR_TARGET_NOTCONVERTED.
When the application is changing clause information, it can change only the target clause, just affecting one boundary at a time. The target clause has the attribute ATTR_TARGET_CONVERTED or ATTR_TARGET_NOTCONVERTED.
For additional information about attributes (ATTR_* values), see Composition String.
When the IME completes the changes, it sends a WM_IME_COMPOSITION message to the application to notify it of the changes.
Windows Me/98, Windows 2000, Windows XP: The SCS_*CONVERTSTRING values are used for reconversion. They can only be used for an IME that has the SCS_CAP_SETRECONVERTSTRING property. The application uses these values as follows:
- Call ImmSetCompositionString with SCS_QUERYRECONVERTSTRING, so that IME adjusts the RECONVERTSTRING structure for the reconversion.
- Call ImmSetCompositionString with SCS_SETRECONVERTSTRING, so that IME generates a new composition string. After this, lpComp and lpRead indicate a RECONVERTSTRING structure that contains the updated composition and reading string. Use the value of lpRead only when the selected IME has SCS_CAP_MAKEREAD set.
Note
The imm.h header defines ImmSetCompositionString as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only],East Asian language support installed. |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | imm.h (include Immdev.h, Windows.h) |
| Library | Imm32.lib |
| DLL | Imm32.dll |