GetCharacterPlacementW 函式 (wingdi.h)
GetCharacterPlacement函式會擷取字元字串的相關資訊，例如字元寬度、插入號位置、字串內的順序，以及圖像轉譯。 傳回的資訊類型取決於 dwFlags 參數，而且是以指定顯示內容中目前選取的字型為基礎。 函式會將資訊複製到指定的 GCP_RESULTS 結構，或複製到 結構所指定的一或多個陣列。
雖然此函式一次足以處理字元字串，但需要處理愈來愈多的語言和腳本，就已過時。 它已被 Uniscribe 模組的功能取代。 如需詳細資訊，請參閱 Uniscribe。
建議應用程式使用 GetFontLanguageInfo 函式來判斷目前所選字型的GCP_DIACRITIC、GCP_DBCS、GCP_USEKERNING、GCP_LIGATE、GCP_REORDER、GCP_GLYPHSHAPE和GCP_KASHIDA值是否有效。 如果無效， GetCharacterPlacement 會忽略值。
GCP_NODIACRITICS值已不再定義，不應使用。
語法
DWORD GetCharacterPlacementW(
[in] HDC hdc,
[in] LPCWSTR lpString,
[in] int nCount,
[in] int nMexExtent,
[in, out] LPGCP_RESULTSW lpResults,
[in] DWORD dwFlags
);
參數
[in] hdc
裝置內容的控制碼。
[in] lpString
要處理的字元字串指標。 字串不需要以零結束，因為 nCount 會指定字串的長度。
[in] nCount
lpString所指向的字串長度。
[in] nMexExtent
字串所處理的邏輯單元) 的最大範圍 (。 如果已處理，則會忽略超過此範圍的字元。 任何必要排序或字元陣列的計算只會套用至包含的字元。 只有在 dwFlags 參數中指定GCP_MAXEXTENT值時，才會使用此參數。 當函式處理輸入字串時，只有當總範圍尚未超過最大值時，才會將每個字元及其範圍新增至輸出、範圍和其他陣列。 達到限制之後，處理將會停止。
[in, out] lpResults
接收函式結果 之GCP_RESULTS 結構的指標。
[in] dwFlags
指定如何將字串處理為必要的陣列。 此參數可以是下列一或多個值。
| 值 | 意義 |
|---|---|
|
指定 lpClass 陣列包含字元的預設分類。 分類可能與輸出時相同。 如果未知字元的特定分類，陣列中的對應位置必須設定為零。 如需分類的詳細資訊，請參閱GCP_RESULTS。 只有在 GetFontLanguageInfo 傳回GCP_REORDER旗標時，這才有用。 |
|
決定如何處理字串中的讀音符號。 如果未設定此值，讀音符號會被視為零寬度字元。 例如，希伯來文字串可能包含變音符號，但您可能不想顯示它們。
使用 GetFontLanguageInfo 來判斷字型是否支援讀音符號。 如果這樣做，您可以根據應用程式的需求，在 呼叫 GetCharacterPlacement中使用或不使用 GCP_DIACRITIC 旗標。 |
|
對於需要重新排列或不同字元圖形的語言，視單字中字元的位置而定，不可顯示字元通常會出現在字碼頁中。 例如，在希伯來文字碼頁中，有從左至右和由右至左標記，以協助判斷輸出字串中字元的最終位置。 這些通常不會顯示，而且會從 lpGlyphs 和 lpDx 陣列中移除。 您可以使用 GCP_DISPLAYZWG 旗標來顯示這些字元。 |
|
指定字串中的部分或所有字元都是使用目前字碼頁目前選取字型中定義之標準圖形以外的圖形來顯示。 某些語言，例如阿拉伯文，除非指定此值，否則無法支援圖像建立。 一般規則是，如果 GetFontLanguageInfo 傳回字串的這個值，這個值必須搭配 GetCharacterPlacement使用。 |
|
調整 lpDx 陣列中的範圍，讓字串長度與 nMaxExtent相同。 GCP_JUSTIFY只能與GCP_MAXEXTENT搭配使用。 |
|
使用 Kashidas 以及 或 ，而不是調整的範圍來修改字串的長度，使其等於 nMaxExtent所指定的值。 在 lpDx 陣列中，Kashida 是以負數理由索引表示。 GCP_KASHIDA只能與GCP_JUSTIFY搭配使用，而且只有在字型 (和語言) 支援 Kashidas 時才使用。 使用 GetFontLanguageInfo 來判斷目前的字型是否支援 Kashidas。
使用 Kashidas 來證明字串，可能會導致所需的字元數目大於輸入字串中的字元數。 因此，使用 Kashidas 時，應用程式無法假設將陣列設定為輸入字串的大小就已足夠。 (可能的最大值大約是 dxPageWidth/dxAveCharWidth，其中 dxPageWidth 是檔的寬度，而 dxAveCharWidth 是從 GetTextMetrics 呼叫傳回的平均字元寬度) 。 請注意，因為 GetFontLanguageInfo 會傳回 GCP_KASHIDA 旗標，並不表示它必須用於 GetCharacterPlacement的呼叫中，只是選項可用。 |
|
使用連字號的連字位置。 發生連字號，其中一個字元用於兩個或多個字元。 例如，字母 a 和 e 可以連至 ？。 不過，若要使用此功能，語言支援和字型都必須支援所需的字元， (範例預設不會以英文) 處理。
使用 GetFontLanguageInfo 來判斷目前的字型是否支援連字。 如果這樣做，而且需要特定上限才能達到該限制的字元數目，請在 lpGlyphs 陣列的第一個專案中設定數位。 如果需要一般連字，請將此值設定為零。 如果未指定GCP_LIGATE，則不會發生任何連字。 如需詳細資訊，請參閱GCP_RESULTS。 如果字元集通常需要GCP_REORDER值，但未指定，除非傳入的字串已經以視覺化順序排序 (，否則輸出會是無意義的，因此在對GetCharacterPlacement的單一呼叫中放入 lpGcpResults-lpOutString > 的結果是第二次呼叫的輸入字串) 。 請注意，由於 GetFontLanguageInfo 會傳回 GCP_LIGATE 旗標，並不表示它必須用於 GetCharacterPlacement的呼叫中，只是選項可用。 |
|
只要產生的範圍在邏輯單元中，字串的計算範圍不會超過 nMaxExtent 參數所指定的值。 |
|
僅限特定語言。 覆寫中性的一般處理，並將其視為符合字串讀取順序的強字元。 僅適用于 GCP_REORDER 旗標。 |
|
僅限特定語言。 覆寫數值的一般處理，並將其視為符合字串讀取順序的強字元。 僅適用于 GCP_REORDER 旗標。 |
|
僅限阿拉伯文/泰文。 針對數位使用標準拉丁字元，並覆寫系統預設值。 若要判斷這個選項是否以字型的語言提供，請使用 GetStringTypeEx 來查看語言是否支援多個數位格式。 |
|
僅限阿拉伯文/泰文。 針對數位字元使用本機字元，並覆寫系統預設值。 若要判斷這個選項是否以字型的語言提供，請使用 GetStringTypeEx 來查看語言是否支援多個數位格式。 |
|
重新排序字串。 用於非 SBCS 和由左至右讀取順序的語言。 如果未指定此值，則會假設字串已依顯示順序排列。
如果針對 Semitic 語言設定此旗標，並使用 lpClass 陣列，則會使用陣列的前兩個元素來指定超出字串界限的讀取順序。 GCP_CLASS_PREBOUNDRTL和GCP_CLASS_PREBOUNDLTR可用來設定順序。 如果不需要預設順序，請將值設定為零。 如果設定 GCPCLASSIN 旗標，這些值可以與其他值結合。 如果未指定GCP_REORDER值， 則會將 lpString 參數視為使用這個語言的視覺排序，並忽略 lpOutString 和 lpOrder 欄位。 使用 GetFontLanguageInfo 來判斷目前字型是否支援重新排序。 |
|
僅限半元語言。 指定無法重設可交換的字元。 例如，在由右至左的字串中，不會反轉 ' (' 和 ') '。 |
|
如果建立寬度陣列時有任何) ，請在字型中使用字型 (字組。 使用 GetFontLanguageInfo 來判斷目前字型是否支援 kerning 配對。
請注意，由於 GetFontLanguageInfo 傳回GCP_USEKERNING旗標並不表示它必須用於 GetCharacterPlacement的呼叫中，只是選項可用。 大部分的 TrueType 字型都有一個 kerning 表格，但您不需要使用它。 |
建議應用程式使用 GetFontLanguageInfo 函式來判斷目前選取字型是否有效GCP_DIACRITIC、GCP_DBCS、GCP_USEKERNING、GCP_LIGATE、GCP_REORDER、GCP_GLYPHSHAPE和GCP_KASHIDA值。 如果無效， GetCharacterPlacement 會忽略值。
GCP_NODIACRITICS值已不再定義，不應使用。
傳回值
如果函式成功，則傳回值是以邏輯單元表示字串的寬度和高度。 寬度是低序字，高度是高序字。
如果此函式失敗，則傳回值為零。
備註
GetCharacterPlacement 可確保應用程式可以正確處理文字，而不論可用的國際設定和字型類型為何。 應用程式先使用此函式，再使用 ExtTextOut 函式，並取代 GetTextExtentPoint32 函式 (，而偶爾會取代 GetCharWidth32 和 GetCharABCWidths 函式) 。
除非需要理由或 kerning，否則使用 GetCharacterPlacement 來擷取字元間距和索引陣列並不一定必要。 針對非拉丁字型，應用程式可以使用GetCharacterPlacement來擷取字元間距和索引陣列，再呼叫ExtTextOut之前，改善ExtTextOut函數轉譯文字的速度。 這在重複轉譯相同的文字時，或使用插號間距放置插入號時特別有用。 如果在對ExtTextOut的呼叫中使用lpGlyphs輸出陣列，則必須設定ETO_GLYPH_INDEX旗標。
GetCharacterPlacement會檢查 GCP_RESULTS結構的lpOrder、lpDX、lpCaretPos、lpOutString和lpGlyphs成員，並在這些成員未設定為Null時填滿對應的陣列。 如果 GetCharacterPlacement 無法填滿陣列，則會將對應的成員設定為 Null。 為了確保擷取有效的資訊，應用程式會負責在呼叫 函式之前將成員設定為有效的位址，以及在呼叫之後檢查成員的值。 如果指定GCP_JUSTIFY或GCP_USEKERNING值， lpDX 和/或 lpCaretPos 成員必須具有有效的位址。
請注意，GCP_RESULTS.lpGlyphs 中傳回的字元索引是裝置內容中目前字型特有的，而且應該只用來在裝置內容中繪製文字，同時該字型仍保持選取狀態。
計算理由時，如果字串中的尾端字元是空格，則函式會減少字串的長度，並在計算理由之前移除空格。 如果陣列只包含空格，函式會傳回錯誤。
ExtTextOut 需要 DBCS 字串的每個位元組 lpDX 專案，而 GetCharacterPlacement 會為每個字元指派 lpDX 專案。 若要在使用此函式組合時更正此不符，請使用 GetGlyphIndices ，或針對 DBCS 位元組配對的對應第二個位元組，展開 lpDX 陣列與零寬度的專案。
如果邏輯寬度小於輸入字串中前置字元的寬度，GCP_RESULTS.nMaxFit 會傳回不正確的值。 在此情況下，請針對字元索引和lpDX陣列呼叫GetCharacterPlacement。 然後使用 lpDX 陣列，使用每個字元的進階寬度來執行範圍計算，其中 nMaxFit 是字元索引進階寬度的字元數小於前置字元的寬度。
注意
wingdi.h 標頭會將 GetCharacterPlacement 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。
規格需求
| 最低支援的用戶端 | Windows 2000 專業版 [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows 2000 Server [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | wingdi.h (包含 Windows.h) |
| 程式庫 | Gdi32.lib |
| Dll | Gdi32.dll |
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應