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 字符串,也可以使用由 iCharset 参数指定的 Windows ANSI 代码页中的字符集。
[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 Professional [仅限桌面应用] |
最低受支持的服务器 | Windows 2000 Server [仅限桌面应用] |
目标平台 | Windows |
标头 | usp10.h |
Library | Usp10.lib |
DLL | Usp10.dll |
可再发行组件 | Windows Me/98/95 上的 Internet Explorer 5 或更高版本 |