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

指出必要分析的旗標。 此參數可以有下表所列的其中一個值。

[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 的功能可以透過直接呼叫其他函式來實作，但是使用函式本身可大幅減少應用程式中用於純文本處理所需的程式代碼數量。

規格需求

另請參閱

SCRIPT_CONTROL

SCRIPT_STATE

SCRIPT_STRING_ANALYSIS

SCRIPT_TABDEF

ScriptBreak

ScriptItemize

ScriptPlace

ScriptShape

Uniscribe

Uniscribe 函式