immSetCompositionStringA 函式 (imm.h)
設定組合和讀取字串的字元、屬性和子句。
語法
BOOL ImmSetCompositionStringA(
HIMC unnamedParam1,
[in] DWORD dwIndex,
[in, optional] LPVOID lpComp,
[in] DWORD dwCompLen,
[in, optional] LPVOID lpRead,
[in] DWORD dwReadLen
);
參數
unnamedParam1
[in] dwIndex
要設定的資訊類型。 此參數可以有下列其中一個值。
| 值 | 意義 |
|---|---|
|
設定組合字元串、讀取字串或兩者。 至少一個 lpComp 和 lpRead 參數必須指出有效的字串。 如果任一字串太長，則輸入法會截斷它。 |
|
設定組合字元串、讀取字串或兩者的屬性。 至少一個 lpComp 和 lpRead 參數必須指出有效的屬性陣列。 |
|
設定組合字元串、讀取字串或兩者的子句資訊。 至少一個 lpComp 和 lpRead 參數必須指向有效的子句資訊陣列。 |
|
Windows Me/98、Windows 2000、Windows XP： 要求 IME 使用指定的 RECONVERTSTRING 結構來反轉字串。 |
|
Windows Me/98、Windows 2000、Windows XP： 要求輸入法調整 RECONVERTSTRING 結構。 然後，應用程式可以使用SCS_SETRECONVERTSTRING將調整的結構傳遞至此函式。 IME 不會產生任何 WM_IME_COMPOSITION 訊息。 |
[in, optional] lpComp
緩衝區的指標，其中包含要針對組合字元串設定的資訊，如 dwIndex的值所指定。
[in] dwCompLen
即使指定了SCS_SETSTR，而且緩衝區包含 Unicode 字串，仍會以位元組為單位來調整組合字元串的資訊緩衝區大小。
[in, optional] lpRead
緩衝區的指標，其中包含要針對讀取字串設定的資訊，如 dwIndex的值所指定。 應用程式可以將此參數設定為 Null。
[in] dwReadLen
讀取字串的資訊緩衝區大小，以位元組為單位，即使指定SCS_SETSTR且緩衝區包含 Unicode 字串也一樣。
傳回值
如果成功，則傳回非零值，否則傳回 0。
備註
應用程式可以設定 lpComp、 lpRead或兩者。 如果應用程式未指定 lpComp的值，則必須將此參數設定為 Null ，並將 dwCompLen 設定為 0。
當應用程式變更屬性時，子句中的所有字元都必須具有相同的屬性。 轉換的字元必須具有屬性ATTR_CONVERTED或ATTR_TARGET_CONVERTED。 未轉換的字元必須具有屬性ATTR_INPUT或ATTR_TARGET_NOTCONVERTED。
當應用程式變更子句資訊時，它只能變更目標子句，一次只會影響一個界限。 目標子句具有屬性ATTR_TARGET_CONVERTED或ATTR_TARGET_NOTCONVERTED。
如需屬性 (ATTR_* 值) 的詳細資訊，請參閱 組合字元串。
當輸入法完成變更時，它會將 WM_IME_COMPOSITION 訊息傳送給應用程式，以通知變更。
Windows Me/98、Windows 2000、Windows XP： SCS_*CONVERTSTRING 值用於重新轉換。 它們只能用於具有 SCS_CAP_SETRECONVERTSTRING 屬性的 IME。 應用程式會使用這些值，如下所示：
- 使用 SCS_QUERYRECONVERTSTRING 呼叫 ImmSetCompositionString ，讓 IME 調整重新轉換的 RECONVERTSTRING 結構。
- 使用 SCS_SETRECONVERTSTRING 呼叫 ImmSetCompositionString ，讓 IME 產生新的組合字元串。 之後， lpComp 和 lpRead 會指出包含更新組合和讀取字串的 RECONVERTSTRING 結構。 只有在選取的輸入法已設定SCS_CAP_MAKEREAD時，才使用 lpRead 的值。
注意
imm.h 標頭會根據 UNICODE 預處理器常數的定義，將 ImmSetCompositionString 定義為別名，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。
規格需求
| 最低支援的用戶端 | Windows XP [僅限傳統型應用程式]，已安裝東亞語言支援。 |
| 最低支援的伺服器 | Windows Server 2003 [僅限傳統型應用程式] |
| 目標平臺 | Windows |
| 標頭 | imm.h (包括 Immdev.h、Windows.h) |
| 程式庫 | Imm32.lib |
| DLL | Imm32.dll |