ScriptStringAnalyse 函式 (usp10.h)
分析純文字字串。
語法
HRESULT ScriptStringAnalyse(
[in] HDC hdc,
[in] const void *pString,
[in] int cString,
[in] int cGlyphs,
[in] int iCharset,
[in] DWORD dwFlags,
[in] int iReqWidth,
[in, optional] SCRIPT_CONTROL *psControl,
[in, optional] SCRIPT_STATE *psState,
[in, optional] const int *piDx,
[in, optional] SCRIPT_TABDEF *pTabdef,
[in] const BYTE *pbInClass,
[out] SCRIPT_STRING_ANALYSIS *pssa
);
參數
[in] hdc
裝置內容的句柄。 如果 dwFlags 設定為 SSA_GLYPHS，則需要裝置內容句柄。 如果 dwFlags 設定為SSA_BREAK，則裝置內容句柄是選擇性的。 如果提供裝置內容句柄，函式會檢查裝置內容中的目前字型。 如果目前的字型是符號字型，函式會將字元字串視為單一中性SCRIPT_UNDEFINED專案。
[in] pString
要分析之字串的指標。 字串必須至少有一個字元。 它可以是 Unicode 字串，或使用 Windows ANSI 代碼頁中的字元集，如 iCharset 參數所指定。
[in] cString
要分析的字串長度。 長度是以 ANSI 字串的字元或 Unicode 字串的寬字元來測量。 長度至少必須是 1。
[in] cGlyphs
文字緩衝區的大小，以 WORD 值為單位。 需要此大小。 建議的大小為 (1.5 * cString + 16)。
[in] iCharset
字元集描述元。 如果輸入字串是 ANSI 字串，此描述元會設定為字元集識別碼。 如果字串是 Unicode 字串，此描述元會設定為 -1。
定義下列字元集識別碼：
[in] dwFlags
指出必要分析的旗標。 此參數可以有下表所列的其中一個值。
| 值 | 意義 |
|---|---|
|
擷取斷點旗標，也就是字元和單字停駐點。 |
|
在 iReqWidth 裁剪字串。 |
|
提供控制字元的表示字元。 |
|
使用後援字型。 |
|
將字串對齊 iReqWidth。 |
|
使用 GetCharacterPlacement 慣例擷取遺漏的字元和 pwLogClust。 |
|
產生字元、位置和屬性。 |
|
從顯示的字串中移除第一個 「&」。 |
|
將 「&」 取代為後續程式代碼點的底線。 |
|
僅顯示底線。 產生的點陣圖樣可能會使用 XOR 遮罩來顯示，以切換熱鍵底線的可見度，而不會干擾文字。 |
|
將東亞字型連結和關聯套用至非叢集文字。 |
|
使用 ExtTextOutW 呼叫來撰寫專案，而不使用字元。 |
|
包含單一字元 cString 時間的重複輸入字串。 |
|
使用基底內嵌層級 1。 |
|
展開索引標籤。 |
[in] iReqWidth
調整或裁剪所需的寬度。
[in, optional] psControl
SCRIPT_CONTROL 結構的指標。 應用程式可以將此參數設定為 NULL ，以指出所有 SCRIPT_CONTROL 成員都設定為 0。
[in, optional] psState
SCRIPT_STATE 結構的指標。 應用程式可以將此參數設定為 NULL ，以指出所有 SCRIPT_STATE 成員都設定為 0。 忽略 SCRIPT_STATE的 uBidiLevel 成員。 所使用的值衍生自SSA_RTL旗標，並搭配裝置內容的版面配置。
[in, optional] piDx
要求的邏輯 dx 陣列指標。
[in, optional] pTabdef
SCRIPT_TABDEF 結構的指標。 只有在 dwFlags 設定為 SSA_TAB 時，才需要此值。
[in] pbInClass
表示 GetCharacterPlacement 字元分類的 BYTE 值的指標。
[out] pssa
這個函式擷取 SCRIPT_STRING_ANALYSIS 結構的緩衝區指標。 此結構會在函式成功傳回時動態配置。
傳回值
如果成功，則傳回S_OK。 如果函式未成功，函式會傳回非零 HRESULT 值。
錯誤傳回包括：
- E_INVALIDARG。 找到無效的參數。
- USP_E_SCRIPT_NOT_IN_FONT。 尚未指定SSA_FALLBACK，或遺漏標準後援字型。
函式也可以傳回轉換成 HRESULT 類型的系統錯誤。 例如，由於缺少記憶體或使用裝置內容進行 GDI 呼叫，而傳回錯誤。
備註
使用此函式是處理純文字字串的第一個步驟。 這類字串只有一個字型、一個樣式、一個大小、一種色彩等等。 ScriptStringAnalyse 會為專案分析、圖像、進階寬度等專案配置暫存緩衝區。 然後，它會自動執行 ScriptItemize、ScriptShape、ScriptPlace 和 ScriptBreak。 結果可透過所有其他 ScriptString* 函式取得。
從此函式成功傳回時， pssa 會指出動態配置的結構，應用程式可以連續傳遞至其他 ScriptString* 函式。 應用程式最終必須藉由呼叫 ScriptStringFree 來釋放結構。
雖然 ScriptStringAnalyse 的功能可以透過直接呼叫其他函式來實作，但是使用函式本身可大幅減少應用程式中用於純文本處理所需的程式代碼數量。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows 2000 專業版 [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows 2000 Server [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | usp10.h |
| 程式庫 | Usp10.lib |
| Dll | Usp10.dll |
| 可轉散發套件 | Windows Me/98/95 上的 Internet Explorer 5 或更新版本 |