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 に設定されている場合、デバイス コンテキスト ハンドルは省略可能です。 デバイス コンテキスト ハンドルが指定されている場合、関数はデバイス コンテキストの現在のフォントを検査します。 現在のフォントがシンボリック フォントの場合、関数は文字列を 1 つのニュートラル SCRIPT_UNDEFINED項目として扱います。

[in] pString

分析する文字列へのポインター。 文字列には少なくとも 1 文字が必要です。 iCharset パラメーターで指定されているように、Unicode 文字列を使用することも、Windows ANSI コード ページの文字セットを使用することもできます。

[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を返します。 関数は、成功しない場合は 0 以外の HRESULT 値を返します。

エラーの戻り値は次のとおりです。

• E_INVALIDARG。 無効なパラメーターが見つかりました。
• USP_E_SCRIPT_NOT_IN_FONT。 SSA_FALLBACKが指定されていないか、標準のフォールバック フォントがありません。

関数は、HRESULT 型に変換されたシステム エラーを返すこともできます。 たとえば、デバイス コンテキストを使用したメモリまたは GDI 呼び出しがないために返されるエラーです。

注釈

この関数の使用は、プレーン テキスト文字列を処理する最初の手順です。 このような文字列には、フォントが 1 つだけ、スタイルが 1 つ、サイズが 1 つ、色が 1 つなどです。 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 関数