ImmSetCompositionString

The ImmSetCompositionString function sets the characters, attributes, and clauses of the composition and reading strings.

BOOL ImmSetCompositionString(
  HIMC hIMC,        
  DWORD dwIndex,    
  LPVOID lpComp,    
  DWORD dwCompLen,  
  LPVOID lpRead,    
  DWORD dwReadLen   
);

Parameters

hIMC

[in] Handle to the input context.

dwIndex

[in] Specifies the type of information to set. This parameter can be one of the following values.

Value	Meaning
SCS_SETSTR	Sets the composition string, the reading string, or both. At least one of the lpComp and lpRead parameters must point to a valid string. If either string is too long, the IME truncates it.
SCS_CHANGEATTR	Sets attributes for the composition string, the reading string, or both. At least one of the lpComp and lpRead parameters must point to a valid attribute array.
SCS_CHANGECLAUSE	Sets 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 98 and Windows 2000: Asks IME to reconvert the string by a specified RECONVERTSTRING structure.
SCS_QUERYRECONVERTSTRING	Windows 98 and Windows 2000: Asks IME to adjust the RECONVERTSTRING structure. Then the application can pass the adjusted RECONVERTSTRING structure into this API with SCS_SETRECONVERTSTRING. IME will not generate any WM_IME_COMPOSITION messages.

lpComp

[in] Pointer to a buffer containing the information to set for the composition string. The information is as specified by the dwIndex value.

dwCompLen

[in] Specifies the size, in bytes, of the information buffer for the composition string. This is true even if SCS_SETSTR is specified and the buffer contains a Unicode string.

lpRead

[in] Pointer to a buffer containing the information to set for the reading string. The information is as specified by the dwIndex value.

dwReadLen

[in] Specifies the size, in bytes, of the information buffer for the reading string. The size is in bytes even if SCS_SETSTR is specified and the buffer contains a Unicode string.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

The application can set lpComp, lpRead or both. If the application does not specify lpComp, lpComp must be NULL and dwCompLen must be zero.

When changing attributes, all characters in a clause must have the same attribute. Converted characters must be either ATTR_CONVERTED or ATTR_TARGET_CONVERTED; unconverted characters either ATTR_INPUT or ATTR_TARGET_NOTCONVERTED.

When changing clause information, only the target clause can be changed and only one boundary of the clause can be changed at a time. The target clause has the ATTR_TARGET_CONVERTED or ATTR_TARGET_NOTCONVERTED attribute.

For more information about attributes (ATTR_* values), see Composition String.

When the IME completes the changes, it sends a WM_IME_COMPOSITION message to the application notifying it of the changes.

Windows 98 and Windows 2000: The SCS_*CONVERTSTRING values are used for reconversion. They can only be used for an IME that has the SCS_CAP_SETRECONVERTSTRING property. They are used as follows: First, call ImmSetCompositionString() with SCS_QUERYRECONVERTSTRING so that IME adjusts the RECONVERTSTRING structure for the reconversion. Then, call ImmSetCompositionString() with SCS_SETRECONVERTSTRING so that IME generates a new composition string. After this, lpComp and lpRead will point to a RECONVERTSTRING structure that contains the updated composition and reading string. lpRead can be used only when the selected IME has SCS_CAP_MAKEREAD set. lpRead can be NULL.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Windows 95/98: Requires Windows 95 or later.
  Header: Declared in Imm.h.
  Library: Use Imm32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Input Method Editor Overview, Input Method Editor Functions, WM_IME_COMPOSITION, RECONVERTSTRING