ScriptItemizeOpenType 函数 (usp10.h)

项目
03/03/2024

将 Unicode 字符串拆分为可单独调整的项，并为 OpenType 处理的每个可调整项提供特征标记数组。

语法

HRESULT ScriptItemizeOpenType(
  [in]           const WCHAR          *pwcInChars,
  [in]           int                  cInChars,
  [in]           int                  cMaxItems,
  [in, optional] const SCRIPT_CONTROL *psControl,
  [in, optional] const SCRIPT_STATE   *psState,
  [out]          SCRIPT_ITEM          *pItems,
  [out]          OPENTYPE_TAG         *pScriptTags,
  [out]          int                  *pcItems
);

参数

[in] pwcInChars

指向要逐项化的 Unicode 字符串的指针。

[in] cInChars

pwcInChars 中要逐项化的字符数。

[in] cMaxItems

定义要处理的项的SCRIPT_ITEM 结构的最大数目。

[in, optional] psControl

指向 SCRIPT_CONTROL 结构的指针，该结构指示要执行的项化类型。

或者，如果不需要SCRIPT_CONTROL属性，应用程序可以将此参数设置为 NULL。有关详细信息，请参见“备注”部分。

[in, optional] psState

指向指示初始双向算法状态的SCRIPT_STATE 结构的指针。

或者，如果不需要脚本状态，应用程序可以将此参数设置为 NULL 。有关详细信息，请参见“备注”部分。

[out] pItems

指向缓冲区的指针，函数在其中检索表示已处理项的SCRIPT_ITEM 结构。缓冲区的长度应为 (cMaxItems + 1) * sizeof(SCRIPT_ITEM) 字节。使用处理少于两个 SCRIPT_ITEM 结构的缓冲区调用此函数无效。函数始终将终端项添加到项分析数组中，以便具有从零开始的索引“i”的项的长度始终可用：

pItems[i+1].iCharPos - pItems[i].iCharPos;

[out] pScriptTags

指向缓冲区的指针，函数在其中检索表示脚本标记的OPENTYPE_TAG 结构数组。缓冲区的长度应为 cMaxItems * sizeof(OPENTYPE_TAG) 字节。

注意当项中的所有字符都是中性字符时，此参数的值SCRIPT_TAG_UNKNOWN (0x00000000) 。例如，如果项完全由标点组成，则可能会发生这种情况。

[out] pcItems

指向已处理的 SCRIPT_ITEM 结构数的指针。

返回值

如果成功，则返回 0。如果函数不成功，则返回非零 HRESULT 值。在所有错误情况下，不会完全处理任何项，并且输出的一部分不包含定义的值。应用程序可以使用 SUCCEEDED 和 FAILED 宏测试返回值。

如果 cMaxItems 指示的大小太小，函数将返回E_OUTOFMEMORY。应用程序可以尝试使用更大的缓冲区再次调用函数。

如果出现以下一个或多个情况，函数将返回E_INVALIDARG：

pwcInChars 设置为 NULL
cInChars 为 0
pItems 设置为 NULL
pScriptTags 设置为 NULL
cMaxItems< 2

注解

ScriptItemizeOpenType 优先于较旧的 ScriptItemize 函数。 ScriptItemizeOpenType 的一个优点是每个可塑造项的功能标记的可用性。

有关通常调用此函数的上下文的讨论，请参阅使用 Uniscribe 显示文本。

函数通过调整引擎的更改或方向的更改来分隔项。

应用程序可以从 ScriptItemizeOpenType 检索到的每个SCRIPT_ITEM结构创建多个范围或完全位于单个项中的运行。但是，它不应将多个项合并到单个运行中。在测量或呈现时，应用程序可以为每次运行调用 ScriptShapeOpenType，并且必须在 ScriptItemizeOpenType 检索的SCRIPT_ITEM结构中传递相应的SCRIPT_ANALYSIS结构。

如果应用程序处理的文本可以包含任何从右到左的内容，则应用程序在调用 ScriptItemizeOpenType 时使用 psControl 和 psState 参数。但是，应用程序不必执行此操作，并且可以处理双向文本本身，而不是依赖 Uniscribe 执行此操作。 psControl 和 psState 参数在某些严格从左到右的方案中很有用，例如，当 SCRIPT_CONTROL 的 fLinkStringBefore 成员不是特定于从右到左的脚本时。应用程序将 psControl 和 psState 设置为 NULL ，以便 ScriptItemizeOpenType 完全按字符代码中断 Unicode 字符串。

应用程序可以将所有参数设置为非 NULL 值，使函数执行完整的 Unicode 双向分析。若要允许进行正确的 Unicode 双向分析，应根据段落开头的阅读顺序初始化 SCRIPT_STATE 结构，并应在整个段落中传递 ScriptItemizeOpenType 。具体而言，对于从左到右， uBidiLevel 成员应初始化为 0，从右到左初始化为 1。

SCRIPT_ANALYSIS 的 fRTL 成员在 SCRIPT_ITEM 中引用。 SCRIPT_PROPERTIES的 fNumeric 成员由 ScriptGetProperties 检索。这些成员共同提供与 GCP_RESULTS 的 lpClass 成员相同的分类，由 GetCharacterPlacement 中的 lpResults 引用。

欧洲数字 U+0030 到 U+0039 可以呈现为国家/地区数字，如下表所示。

SCRIPT_STATE.fDigitSubstitute	SCRIPT_CONTROL.fContextDigits	为 Unicode U+0030 到 U+0039 显示的数字形状
FALSE	任意	欧洲数字
TRUE	FALSE	在 SCRIPT_CONTROL 的 uDefaultLanguage 成员中指定。
TRUE	TRUE	与之前的强文本一样，默认为 SCRIPT_CONTROL 的 uDefaultLanguage 成员。

在上下文数字模式下，将执行以下操作之一：

如果 uDefaultLanguage 指定的脚本与输出方向相同，则第一个字母之前遇到的所有数字都以 uDefaultLanguage 指示的语言呈现。
如果 uDefaultLanguage 指定的脚本与输出方向相反，则第一个字母之前遇到的所有数字都以欧洲数字呈现。

例如，如果 uDefaultLanguage 指示LANG_ARABIC，则从右到左嵌入 Arabic-Indic 初始数字。但是，它们在从左到右的嵌入中以欧洲数字表示。

有关详细信息，请参阅数字形状。

下表提供了 Unicode 控件字符和定义，以及它们对SCRIPT_STATE 成员的影响。有关 Unicode 控制字符的详细信息，请参阅 Unicode 标准。

Unicode 控制字符	含义	对SCRIPT_STATE的影响
NADS	使用国家数字形状替代欧洲数字 (NODS) 。	设置 fDigitSubstitute。
点头	使用名义数字形状，也称为欧洲数字。请参阅 NADS。	清除 fDigitSubstitute。
屁股	激活对称对的交换，例如括号。对于这些字符，左和右解释为开始和关闭。这是默认值。请参阅 ISS。	清除 fInhibitSymSwap。
ISS	禁止交换对称对。请参阅 ASS。	设置 fInhibitSymSwap。
AAFS	激活阿拉伯语演示文稿窗体的阿拉伯文表单整形。请参阅 IAFS。	设置 fCharShape。
IAFS	禁止阿拉伯语表示形式，即连字和草书连接，用于阿拉伯语表示形式。名义阿拉伯字符不受影响。这是默认值。请参阅 AAFS。	清除 fCharShape。

SCRIPT_STATE 的 fArabicNumContext 成员支持在阿拉伯语脚本文本中区分上下文显示数字。它指示数字是使用本机阿拉伯语脚本数字形状还是欧洲数字呈现。在段落开头，对于阿拉伯语区域设置，此成员通常应初始化为 TRUE ，对于任何其他区域设置，应初始化为 FALSE 。函数在处理强文本时更新脚本状态。

输出参数 pScriptTags 指示具有与项并行的条目的数组。对于每个项，此函数将检索一个脚本标记，该标记应用于在所有后续操作中定形。

脚本标记通常由 ScriptItemizeOpenType 根据输入字符确定。如果函数检索特定的脚本标记，则应用程序应将其传递给其他函数，而不会进行更改。但是，当字符为中性 (例如数字) 且无法确定脚本时，应用程序应根据与文本关联的字体和语言选择适当的脚本标记。

重要从 Windows 8 开始：若要保持在 Windows 7 上运行的能力，使用 Uniscribe 的模块必须在其库列表中指定 gdi32.lib 之前的 Usp10.lib。

要求

要求	值
最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	usp10.h
Library	Usp10.lib
DLL	Usp10.dll
可再发行组件	在 Windows XP 上 Usp10.dll 版本 1.600 或更高版本