在遊戲中使用輸入法編輯器

輸入法編輯器 （IME） 是一個程式，允許使用標準鍵盤輸入東亞語言，例如中文、日文、韓文，以及具有複雜字元的語言。 例如，使用 IME 時，用戶可以在字處理器中輸入複雜字元，或大型多人遊戲玩家可以與複雜字元中的朋友聊天。

本文說明如何在全螢幕 Microsoft DirectX 應用程式中實作基本的 IME 編輯控制件。 利用 DXUT 的應用程式會自動取得輸入法編輯器 (IME) 功能。 對於未使用架構的應用程式，本文說明如何將 IME 支援新增至編輯控件。

內容：

• 預設輸入法行為
• 搭配 DXUT 使用 IME
• 覆寫預設輸入法行為
• 功能
• 訊息
• 範例
  • CHT IME 4.2、4.3 和 4.4 版
  • CHT IME 5.0 版
  • CHT IME 5.1 版、5.2 版和 CHS IME 5.3 版
  • CHS IME 4.1 版
  • CHS IME 4.2 版
• 輸入法訊息
  • WM_INPUTLANGCHANGE
  • WM_IME_STARTCOMPOSITION
  • WM_IME_COMPOSITION
  • WM_IME_ENDCOMPOSITION
  • WM_IME_NOTIFY
• 渲染
  • 輸入地區設定指標
  • 組合視窗
  • 閱讀和候選 Windows
• 限制
• 登錄資訊
• 附錄 A：各作業系統的 CHT 版本
• 進一步資訊
• GetReadingString
• ShowReadingWindow

默認輸入法行為

IME 會將鍵盤輸入對應至注音元件或所選語言特定的其他語言元素。 在典型的情境中，使用者輸入代表複雜字元發音的鍵盤按鍵。 如果 IME 將發音辨識為有效，則會向用戶呈現一份單字或片語候選專案清單，讓使用者可以從中選取最終選擇。 接著，所選單字會透過一系列Microsoft Windows WM_CHAR 訊息傳送至應用程式。 由於 IME 會透過攔截鍵盤輸入，在應用程式下方的層級運作，因此 IME 的存在對應用程式而言是透明的。 幾乎所有的 Windows 應用程式都可以輕易地利用輸入法編輯器（IME），而不需要知道它們的存在，也不需要特殊編碼。

典型的 IME 會顯示數個視窗，引導使用者完成字元輸入，如下列範例所示。

搭配 DXUT 使用 IME

在 DXUT 中，CDXUTIMEEditBox 類別會實作 IME 功能。 這個類別衍生自CDXUTEditBox類別，這是架構所提供的基本編輯控件。 CDXUTIMEEditBox 藉由覆寫 CDXUTIMEEditBox 方法，擴充編輯控件以支援 IME。 這些類別的設計方式是為了協助開發人員了解他們需要從架構中取得的內容，以在自己的編輯控件中實作 IME 支援。 本主題的其餘部分會說明架構，特別是CDXUTIMEEditBox如何覆蓋基本編輯控制項來實現IME功能。

CDXUTIMEEditBox 中大部分的 IME 特定變數都會宣告為靜態，因為許多 IME 緩衝區和狀態都專屬於進程。 例如，進程只有一個組合字串的緩衝區。 即使進程有十個編輯控件，它們也會共用相同的組合字串緩衝區。 因此，CDXUTIMEEditBox 的撰寫字串緩衝區是靜態的，可防止應用程式佔用不必要的記憶體空間。

CDXUTIMEEditBox 會在下列 DXUT 程式代碼中實作：

（SDK root）\Samples\C++\Common\DXUTgui.cpp

改變預設的 IME 行為

一般來說，IME 會使用標準 Windows 程式來建立視窗（請參閱使用 Windows ）。 在正常情況下，這會產生令人滿意的結果。 不過，當應用程式以全螢幕模式呈現時，與遊戲一樣常見，標準視窗將無法再運作，而且可能不會顯示在應用程式上方。 若要克服此問題，應用程式必須繪製 IME 視窗本身，而不是依賴 Windows 來執行這項工作。

當預設的 IME 視窗建立行為不滿足應用程式所需時，應用程式能夠覆寫 IME 視窗的處理操作。 應用程式可以藉由處理與輸入法相關的訊息，以及呼叫 Input Method Manager （IMM） API 來達成此目的。

當使用者與輸入複雜字元的 IME 互動時，IMM 會將訊息傳送給應用程式，以通知其重要事件，例如啟動組合或顯示候選視窗。 應用程式通常會忽略這些訊息，並將其傳遞至預設訊息處理程式，這會導致IME處理它們。 當應用程式而非預設處理程式處理訊息時，它會控制每個 IME 事件所發生的確切情況。 訊息處理程式通常會藉由呼叫 IMM API 來擷取各種 IME 視窗的內容。 一旦應用程式具有這項資訊，它就可以在需要轉譯到顯示器時，正確地繪製 IME 視窗本身。

功能

輸入法需要取得讀取字串、隱藏閱讀視窗，以及取得閱讀視窗的方向。 下表顯示每個 IME 版本的功能：

消息

對於實作 ShowReadingWindow的新輸入法，不需要處理下列訊息。

下列訊息被應用程式訊息處理程式所截獲，也就是不會傳遞至 DefWindowProc），以防止讀取窗口顯示。

Msg == WM_IME_NOTIFY
wParam == IMN_PRIVATE
lParam == 1, 2 (CHT IME version 4.2, 4.3 and 4.4 / CHS IME 4.1 and 4.2)
lParam == 16, 17, 26, 27, 28 (CHT IME version 5.0, 5.1, 5.2 / CHS IME 5.3)

例子

下列範例說明如何從不具備 GetReadingString() 功能的較舊 IME 中取得讀取字串的資訊。 程式代碼會產生下列輸出：

CHT IME 4.2、4.3 和 4.4 版

LPINPUTCONTEXT lpIMC = _ImmLockIMC(himc);
LPBYTE p = *(LPBYTE *)((LPBYTE)_ImmLockIMCC(lpIMC->hPrivate) + 24);
if (!p) break;
dwlen = *(DWORD *)(p + 7*4 + 32*4);
dwerr = *(DWORD *)(p + 8*4 + 32*4);
wstr = (WCHAR *)(p + 56);
unicode = TRUE;

CHT IME 5.0 版

LPINPUTCONTEXT lpIMC = _ImmLockIMC(himc);
LPBYTE p = *(LPBYTE *)((LPBYTE)_ImmLockIMCC(lpIMC->hPrivate) + 3*4);
if (!p) break;
p = *(LPBYTE *)((LPBYTE)p + 1*4 + 5*4 + 4*2 );
if (!p) break;
dwlen = *(DWORD *)(p + 1*4 + (16*2+2*4) + 5*4 + 16);
dwerr = *(DWORD *)(p + 1*4 + (16*2+2*4) + 5*4 + 16 + 1*4);
wstr = (WCHAR *)(p + 1*4 + (16*2+2*4) + 5*4);
unicode = FALSE;

CHT IME 5.1、5.2 和 CHS IME 5.3 版

LPINPUTCONTEXT lpIMC = _ImmLockIMC(himc);
LPBYTE p = *(LPBYTE *)((LPBYTE)_ImmLockIMCC(lpIMC->hPrivate) + 4);
if (!p) break;
p = *(LPBYTE *)((LPBYTE)p + 1*4 + 5*4); 
if (!p) break;
dwlen = *(DWORD *)(p + 1*4 + (16*2+2*4) + 5*4 + 16 * 2);
dwerr = *(DWORD *)(p + 1*4 + (16*2+2*4) + 5*4 + 16 * 2 + 1*4);
wstr  = (WCHAR *) (p + 1*4 + (16*2+2*4) + 5*4);
unicode = TRUE;

CHS IME 4.1 版

// GetImeId(1) returns VS_FIXEDFILEINFO:: dwProductVersionLS of IME file
int offset = ( GetImeId( 1 ) >= 0x00000002 ) ? 8 : 7;
LPINPUTCONTEXT lpIMC = _ImmLockIMC(himc);
BYTE p = *(LPBYTE *)((LPBYTE)_ImmLockIMCC(lpIMC->hPrivate) + offset * 4);
if (!p) break;
dwlen = *(DWORD *)(p + 7*4 + 16*2*4);
dwerr = *(DWORD *)(p + 8*4 + 16*2*4);
dwerr = min(dwerr, dwlen);
wstr = (WCHAR *)(p + 6*4 + 16*2*1);
unicode = TRUE;

CHS IME 4.2 版

int nTcharSize = IsNT() ? sizeof(WCHAR) : sizeof(char);
LPINPUTCONTEXT lpIMC = _ImmLockIMC(himc);
BYTE p = *(LPBYTE *)((LPBYTE)_ImmLockIMCC(lpIMC->hPrivate) + 1*4 + 1*4 + 6*4);
if (!p) break;
dwlen = *(DWORD *)(p + 1*4 + (16*2+2*4) + 5*4 + 16 * nTcharSize);
dwerr = *(DWORD *)(p + 1*4 + (16*2+2*4) + 5*4 + 16 * nTcharSize + 1*4);
wstr  = (WCHAR *) (p + 1*4 + (16*2+2*4) + 5*4);
unicode = IsNT() ? TRUE : FALSE;

輸入法訊息

全螢幕應用程式必須正確處理下列 IME 相關訊息：

WM_INPUTLANGCHANGE（輸入語言更改）

在使用者透過按鍵組合（通常是 ALT+SHIFT）、任務欄或語言列上的輸入地區設定指標更改輸入地區設定後，IMM 會將 WM_INPUTLANGCHANGE 訊息傳送至應用程式的活躍視窗。 語言列是螢幕控制件，用戶可以設定文字服務。 （請參閱 如何顯示語言列。下列螢幕快照顯示當使用者按兩下地區設定指標時所顯示的語言選取清單。

當使用者點擊地區設定指標時所顯示的

當 IMM 傳送WM_INPUTLANGCHANGE訊息時，CDXUTIMEEditBox 必須執行數項重要工作：

1. 呼叫 GetKeyboardLayout 方法以傳回應用程式線程的輸入地區設定標識碼（ID）。 CDXUTIMEEditBox 類別會將此標識符儲存在其靜態成員變數中，s_hklCurrent以供日後使用。 應用程式必須知道目前的輸入地區設定，因為每個語言的 IME 有自己的不同行為。 開發人員可能需要為不同的輸入地區設定提供不同的程序代碼。
2. CDXUTIMEEditBox 會初始化字串，以顯示在編輯框語言指標中。 當應用程式以全螢幕模式執行，且任務列和語言列都看不到時，此指標可以顯示使用中的輸入語言。
3. 呼叫 ImmGetConversionStatus 方法，以指出輸入地區設定是否為原生或非原生轉換模式。 原生轉換模式可讓使用者以所選語言輸入文字。 非原生轉換模式會讓鍵盤作為標準英文鍵盤。 請務必為使用者提供有關目前轉換模式的視覺提示，讓使用者可以輕鬆地知道按下按鍵時預期的字元。 CDXUTIMEEditBox 提供了一個視覺提示，透過語言指標的色彩來呈現。 當輸入地區設定使用具有原生轉換模式的 IME 時，CDXUTIMEEditBox 類別會使用 m_IndicatorImeColor 參數所定義的色彩繪製指標文字。 當 IME 處於非原生轉換模式，或完全不使用 IME 時，類別會使用 m_IndicatorEngColor 參數所定義的色彩繪製指標文字。
4. CDXUTIMEEditBox 會檢查輸入地區設定，並將靜態成員變數 s_bInsertOnType 對於韓文設為 TRUE，對於其他所有語言設為 FALSE。 此旗標是必要的，因為韓文 IME 和其他所有 IME 的行為不同。 以韓文以外的語言輸入字元時，使用者輸入的文字會顯示在組合視窗中，而且使用者可以自由變更組合字串的內容。 當使用者滿意組合字串時按下 ENTER 鍵，而組合字串會以一系列WM_CHAR訊息的形式傳送至應用程式。 不過，在韓文 IME 中，當使用者按下按鍵以輸入文字時，會立即將字元傳送至應用程式。 當使用者後續按下更多按鍵來修改該初始字元時，編輯方塊中的字元會變更以反映使用者的其他輸入。 基本上，使用者正在編輯方塊中撰寫字元。 這兩種行為已經足夠不同，CDXUTIMEEditBox 必須特別為每個行為撰寫程序代碼。
5. 系統會呼叫靜態成員方法 SetupImeApi，從 IME 模組擷取兩個函式的位址：GetReadingString 和 ShowReadingWindow。 如果這些函式存在，則會呼叫 ShowReadingWindow 來隱藏此 IME 的預設讀取視窗。 因為應用程式會轉譯讀取視窗本身，所以它會通知 IME 停用繪製預設讀取視窗，使其不會干擾全螢幕轉譯。

啟用應用程式視窗時，IMM 會傳送WM_IME_SETCONTEXT訊息。 此訊息的 lParam 參數包含旗標，指出 IME 應該繪製哪些視窗，以及不應該繪製哪些視窗。 由於應用程式正在處理所有繪圖，因此不需要 IME 來繪製任何 IME 視窗。 因此，應用程式的訊息處理程式只會將 lParam 設定為 0 並傳回。

為了讓應用程式支援 IME，IME 相關訊息需要特殊處理WM_IME_SETCONTEXT。 由於 Windows 通常會在呼叫 PanoramaInitialize（） 方法之前，將此訊息傳送給應用程式，因此 Panorama 沒有機會處理 UI 以顯示候選清單視窗。

下列代碼段會指定 Windows 應用程式不要顯示與候選清單視窗相關聯的任何 UI，允許 Panorama 特別處理此 UI。

case WM_IME_SETCONTEXT:
         lParam = 0;
    lRet = DefWindowProc(hWnd, msg, wParam, lParam);
    break;
    //... more message processing
    return lRet;

WM_IME_STARTCOMPOSITION

當使用者即將開始輸入法組字時，IMM 會將 WM_IME_STARTCOMPOSITION 訊息傳送給應用程式。 如果 IME 使用組合視窗，它會在組合視窗中顯示目前的組合字串。 CDXUTIMEEditBox 會執行兩項工作來處理此訊息：

1. CDXUTIMEEditBox 會清除組合字串緩衝區和屬性緩衝區。 這些緩衝區是CDXUTIMEEditBox的靜態成員。
2. CDXUTIMEEditBox 會將s_bHideCaret靜態成員變數設定為 TRUE。 這個成員定義於基底CDXUTEditBox類別中，可控制編輯方塊中的游標是否應在編輯方塊轉譯時繪製。 組合視窗的運作方式類似於具有文字和游標的編輯框。 若要避免在組合視窗可見時造成混淆，編輯框會隱藏游標，以便一次只顯示一個游標。

WM_IME_COMPOSITION

當使用者輸入擊鍵以變更組合字串時，IMM 會將WM_IME_COMPOSITION訊息傳送給應用程式。 lParam 的值表示應用程式可以從輸入方法管理員 （IMM） 擷取的信息類型。 應用程式應該藉由呼叫 ImmGetCompositionString 來擷取可用的資訊，然後應該將資訊儲存在其私用緩衝區中，以便稍後轉譯 IME 元素。

CDXUTIMEEditBox 會檢查並擷取下列組合字串資料：

WM_IME_ENDCOMPOSITION

當輸入法組合作業結束時，IMM 會將WM_IME_ENDCOMPOSITION訊息傳送給應用程式。 當使用者按下 ENTER 鍵來核准組合字串，或 ESC 鍵取消組合時，就會發生這種情況。 CDXUTIMEEditBox 會藉由將組合字串緩衝區設定為空白來處理此訊息。 然後，它會將s_bHideCaret設為 FALSE，因為組合視窗已關閉，而且編輯方塊中的游標應該會再次顯示。

CDXUTIMEEditBox 訊息處理程式也會將s_bShowReadingWindow設定為 FALSE。 此旗標會控制類別在編輯方塊轉譯時是否繪製讀取視窗，因此當組合結束時，它必須設定為 FALSE。

WM_IME_NOTIFY

每當輸入法視窗變更時，IMM 就會將WM_IME_NOTIFY訊息傳送給應用程式。 處理 IME 視窗繪圖的應用程式應該處理此訊息，讓它知道視窗內容的任何更新。 wParam 表示命令或正在進行的變更。 CDXUTIMEEditBox 會處理下列命令：

渲染

IME 元素和視窗的顯示是直觀的。 CDXUTIMEEditBox 會先讓基類轉譯，因為 IME 視窗應該出現在編輯控件的頂端。 轉譯基底編輯方塊之後，CDXUTIMEEditBox 會檢查每個 IME 視窗的可見度旗標（指標、組合、候選和讀取視窗），如果應該顯示，則會繪製視窗。 請參閱「預設 IME 行為」以了解不同 IME 視窗類型的描述。

輸入地區設定指標

輸入地區設定指標會在任何其他 IME 視窗之前呈現，因為它是一律顯示的元素。 因此，它就應該出現在其他輸入法視窗下方。 CDXUTIMEEditBox 藉由呼叫 RenderIndicator 方法來轉譯指標，其中指標字型色彩會藉由檢查s_ImeState靜態變數來決定，以反映目前的輸入法轉換模式。 啟用 IME 並啟用原生轉換時，此方法會使用 m_IndicatorImeColor 做為指標色彩。 如果 IME 已停用或處於非原生轉換模式，則m_IndicatorImeColor用來繪製指標文字。 根據預設，指標視窗本身會繪製到編輯方塊右邊。 應用程式可以藉由覆寫 RenderIndicator 方法來變更此行為。

下圖顯示輸入語言地區指示器的不同外觀：英語模式、日文英數字轉換模式，以及日文本地轉換模式。

輸入地區設定指標的不同外觀

組合視窗

撰寫視窗的繪圖是在CDXUTIMEEditBox的RenderComposition方法中處理。 組合視窗會浮動在編輯方塊上方。 它應該繪製在基礎編輯控制元件的游標位置。 CDXUTIMEEditBox 會處理轉譯，如下所示：

1. 整個組合字串會使用預設組合字串色彩來繪製。
2. 具有特定特殊屬性的字元應該以不同的色彩繪製，因此CDXUTIMEEditBox會檢閱組合字串的字元，並檢查字串屬性。 如果屬性需要不同的顏色，則將使用適當的顏色再次繪製角色。
3. 撰寫視窗的游標被繪製完成渲染。

游標在韓文 IME 中應閃爍，但在其他 IME 中則不應如此。 RenderComposition 會根據使用韓文輸入法時的定時器值來判斷游標是否應該顯示。

讀取和候選 Windows 作業系統

閱讀和候選視窗會由相同的 CDXUTIMEEditBox 方法 RenderCandidateReadingWindow 轉譯。 這兩個視窗都包含垂直排列的字串陣列，或者在水平排列時包含單個字串。 RenderCandidateReadingWindow 中的大部分程式代碼是用來放置視窗，讓窗口沒有任何部分落在應用程式視窗外並被裁剪。

局限性

IME 有時會包含進階功能，以改善輸入文字的便利性。 在較新的 IME 中找到的一些功能會顯示在下圖中。 這些進階功能不存在於 DXUT 中。 實作這些進階功能的支援可能具有挑戰性，因為沒有定義介面可從IME取得必要的資訊。

具有擴充候選清單的進階繁體中文輸入法：

進階日文輸入法編輯器，其中一些候選項目包含附加文字以描述其意義。

包含手寫辨識系統的進階韓文輸入法：

登錄資訊

當目前的 IME 是較舊的 CHT New Phonetic 時，會檢查下列登錄資訊來判斷讀取視窗的方向，而該 CHT New Phonetic 不會實作 GetReadingString（）。

其中：如果 IME 檔案版本為 5.1 或更新版本，IME_Name為 MSTCIPH;否則IME_Name為 TINTLGNT。

如果符合下列任一條件，閱讀視窗的方向將為水平：

• IME 為 5.0 版，且鍵盤對應值0x22或0x23
• 輸入法是 5.1 版或 5.2 版，鍵盤對應值是0x22、0x23或0x24。

如果兩個條件都不符合，讀取視窗會是垂直的。

附錄 A：每個作業系統的 CHT 版本

進一步資訊

如需詳細資訊，請參閱下列各項：

• 安裝和使用輸入法編輯器
• 國際文字顯示
• Unicode 聯盟
• 開發國際軟體。 Dr. International 第2版 華盛頓州雷德蒙德：Microsoft出版社，2003年。

取得閱讀字符串 (GetReadingString)

取得讀取字串資訊。

參數

himc

[in]輸入內容。

uReadingBufLen

[in] lpwReadingBuf 的長度，以 WCHAR 計算。 如果它是零，則表示查詢讀取緩衝區長度。

lpwReadingBuf

[out] 傳回讀取字串（不以零作為結尾）。

pnErrorIndex

[out]如果有，則傳回讀取字串中錯誤字元的索引。

pfIsVertical

[out]如果為 TRUE，則讀取 UI 是垂直的。 否則，橫向的 puMaxReadingLen。

puMaxReadingLen

[out]讀取UI長度。 讀取長度上限未固定;它不僅取決於鍵盤配置，而且取決於輸入模式（例如，內部程式代碼、代理輸入）。

傳回值

讀取字串長度。

備註

如果傳回值大於 uReadingBufLen 的值，則所有輸出參數都會未定義。

此函式是在 CHT IME 6.0 或更新版本中實作，而且可由 IME 模組句柄上的 GetProcAddress 取得：ImmGetIMEFileName 和 LoadLibrary 可以取得 IME 模組句柄。

需求

標題

在 Imm.h 中宣告。

匯入函式庫

使用 Imm.lib。

顯示閱讀視窗

顯示 （或隱藏） 閱讀視窗。

參數

himc

[in]輸入內容。

bShow

[in]設定為 TRUE 以顯示閱讀視窗 （或 FALSE 隱藏它）。

傳回值

備註

如果成功則傳回 TRUE，否則傳回 FALSE。

需求

標題

在 Imm.h 中宣告。

匯入函式庫

使用 Imm.lib。