ImmSetCompositionStringA function (imm.h)

Article
02/09/2023

Sets the characters, attributes, and clauses of the composition and reading strings.

Syntax

BOOL ImmSetCompositionStringA(
                 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
SCS_SETSTR	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.
SCS_CHANGEATTR	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.
SCS_CHANGECLAUSE	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.
SCS_SETRECONVERTSTRING	Windows Me/98, Windows 2000, Windows XP: Ask IME to reconvert the string using a specified RECONVERTSTRING structure.
SCS_QUERYRECONVERTSTRING	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 which 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 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