ScriptStringAnalyse 函数 (usp10.h)

项目
08/26/2023

分析纯文本字符串。

语法

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 字符串，也可以使用由 iCharset 参数指定的 Windows ANSI 代码页中的字符集。

[in] cString

要分析的字符串的长度。长度以 ANSI 字符串的字符或 Unicode 字符串的宽字符度量。长度必须至少为 1。

[in] cGlyphs

字形缓冲区的大小，以 WORD 值表示。此大小是必需的。建议的大小为 (1.5 * cString + 16)。

[in] iCharset

字符集描述符。如果输入字符串是 ANSI 字符串，则此描述符设置为字符集标识符。如果字符串是 Unicode 字符串，则此描述符设置为 -1。

定义了以下字符集标识符：

[in] dwFlags

指示所需分析的标志。此参数可以具有下表中列出的值之一。

值	含义
SSA_BREAK	检索中断标志，即字符和字停止。
SSA_CLIP	在 iReqWidth 处剪裁字符串。
SSA_DZWG	为控件字符提供表示形式字形。
SSA_FALLBACK	使用回退字体。
SSA_FIT	将字符串与 iReqWidth 对齐。
SSA_GCP	使用 GetCharacterPlacement 约定检索缺失的字形和 pwLogClust。
SSA_GLYPHS	生成字形、位置和属性。
SSA_HIDEHOTKEY	从显示的字符串中删除第一个“&”。
SSA_HOTKEY	将“&”替换为后续代码点上的下划线。
SSA_HOTKEYONLY	仅显示下划线。可以使用 XOR 掩码显示生成的位模式，以切换热键下划线的可见性，而不会干扰文本。
SSA_LINK	将东亚字体链接和关联应用于非复杂文本。
SSA_METAFILE	使用 ExtTextOutW 调用（而不是字形）编写项目。
SSA_PASSWORD	包含单个字符 cString 时间的重复输入字符串。
SSA_RTL	使用基本嵌入级别 1。
SSA_TAB	展开选项卡。

[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 8开始：若要保持在 Windows 7 上运行的功能，使用 Uniscribe 的模块必须在其库列表中指定 gdi32.lib 之前的 Usp10.lib。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	usp10.h
Library	Usp10.lib
DLL	Usp10.dll
可再发行组件	Windows Me/98/95 上的 Internet Explorer 5 或更高版本