getCharacterPlacementA 函数 (wingdi.h)
GetCharacterPlacement 函数检索有关字符串的信息，例如字符宽度、插入点位置、字符串中的排序和字形呈现。 返回的信息类型取决于 dwFlags 参数，并且基于指定显示上下文中当前选定的字体。 函数将信息复制到指定的 GCP_RESULTS 结构或结构指定的一个或多个数组。
尽管此函数曾经足以处理字符串，但需要处理越来越多的语言和脚本已使其过时。 它已被 Uniscribe 模块的功能所取代。 有关详细信息，请参阅 Uniscribe。
建议应用程序使用 GetFontLanguageInfo 函数来确定GCP_DIACRITIC、GCP_DBCS、GCP_USEKERNING、GCP_LIGATE、GCP_REORDER、GCP_GLYPHSHAPE和GCP_KASHIDA值是否对当前所选字体有效。 如果无效， GetCharacterPlacement 将忽略该值。
不再定义GCP_NODIACRITICS值，不应使用。
语法
DWORD GetCharacterPlacementA(
[in] HDC hdc,
[in] LPCSTR lpString,
[in] int nCount,
[in] int nMexExtent,
[in, out] LPGCP_RESULTSA lpResults,
[in] DWORD dwFlags
);
参数
[in] hdc
设备上下文的句柄。
[in] lpString
指向要处理的字符串的指针。 字符串不需要以零结尾，因为 nCount 指定字符串的长度。
[in] nCount
lpString 指向的字符串的长度。
[in] nMexExtent
处理字符串) 最大范围 (逻辑单元。 如果已处理，将忽略超出此范围的字符。 任何所需排序或字形数组的计算仅适用于包含的字符。 仅当 dwFlags 参数中指定了GCP_MAXEXTENT值时，才使用此参数。 当函数处理输入字符串时，只有当总范围尚未超过最大值时，每个字符及其范围才会添加到输出、范围和其他数组中。 达到限制后，处理将停止。
[in, out] lpResults
指向接收函数结果 的 GCP_RESULTS 结构的指针。
[in] dwFlags
指定如何将字符串处理成所需的数组。 此参数可使用以下一个或多个值。
| 值 | 含义 |
|---|---|
|
指定 lpClass 数组包含字符的预设分类。 分类可能与输出中的分类相同。 如果字符的特定分类未知，则必须将数组中的相应位置设置为零。 有关分类的详细信息，请参阅GCP_RESULTS。 仅当 GetFontLanguageInfo 返回了GCP_REORDER标志时，这才有用。 |
|
确定如何处理字符串中的音调符号。 如果未设置此值，则音调符号将被视为零宽度字符。 例如，希伯来语字符串可能包含音调符号，但你可能不想显示它们。
使用 GetFontLanguageInfo 确定字体是否支持音调符号。 如果有，可以在调用 GetCharacterPlacement 时使用或不使用 GCP_DIACRITIC 标志，具体取决于应用程序的需求。 |
|
对于需要根据单词中字符的位置重新排序或不同的字形形状的语言，不可显示的字符通常出现在代码页中。 例如，在希伯来语代码页中，有从左到右和从右向左标记，以帮助确定输出字符串中字符的最终位置。 通常不会显示这些值，并且会从 lpGlyphs 和 lpDx 数组中删除。 可以使用 GCP_DISPLAYZWG 标志来显示这些字符。 |
|
指定使用当前代码页当前所选字体中定义的标准形状以外的其他形状显示字符串中的部分或所有字符。 某些语言（如阿拉伯语）不支持创建字形，除非指定此值。 一般规则是，如果 GetFontLanguageInfo 为字符串返回此值，则必须将此值与 GetCharacterPlacement 一起使用。 |
|
调整 lpDx 数组中的区，使字符串长度与 nMaxExtent 相同。 GCP_JUSTIFY只能与GCP_MAXEXTENT结合使用。 |
|
使用 Kashidas 以及（而不是）调整范围来修改字符串的长度，使其等于 nMaxExtent 指定的值。 在 lpDx 数组中，Kashida 由负对齐索引指示。 GCP_KASHIDA只能与 GCP_JUSTIFY 结合使用，并且仅当字体 (和语言) 支持 Kashidas 时。 使用 GetFontLanguageInfo 确定当前字体是否支持 Kashidas。
使用 Kashidas 来对齐字符串可能会导致所需的字形数大于输入字符串中的字符数。 因此，在使用 Kashidas 时，应用程序无法假定将数组设置为输入字符串的大小就足够了。 (最大可能值大约为 dxPageWidth/dxAveCharWidth，其中 dxPageWidth 是文档的宽度，dxAveCharWidth 是从 GetTextMetrics 调用) 返回的平均字符宽度。 请注意，仅仅因为 GetFontLanguageInfo 返回GCP_KASHIDA标志并不意味着必须在调用 GetCharacterPlacement 时使用它，而只是该选项可用。 |
|
在任意位置使用连字符。 如果一个字形用于两个或多个字符，则会发生连带。 例如，字母 a 和 e 可以绑定到 ？。 但是，语言支持和字体都必须支持所需的字形， (默认情况下不会以英语) 处理该示例。
使用 GetFontLanguageInfo 确定当前字体是否支持连字。 如果确实存在，并且需要指定限制字符数的最大值，请在 lpGlyphs 数组的第一个元素中设置该数字。 如果需要正常连线，请将此值设置为零。 如果未指定GCP_LIGATE，则不会进行任何结扎。 有关详细信息，请参阅GCP_RESULTS。 如果字符集通常需要GCP_REORDER值，但未指定，则输出将毫无意义，除非传入的字符串已采用可视顺序 (也就是说，在对 GetCharacterPlacement 的一次调用中放入 lpGcpResults-lpOutString> 的结果是) 第二次调用的输入字符串。 请注意，仅仅因为 GetFontLanguageInfo 返回GCP_LIGATE标志并不意味着必须在调用 GetCharacterPlacement 时使用它，只是该选项可用。 |
|
只要生成的范围（以逻辑单元为单位）不超过 nMaxExtent 参数指定的值，字符串的计算范围。 |
|
仅限某些语言。 重写对中性的正常处理，并将其视为与字符串读取顺序匹配的强字符。 仅适用于 GCP_REORDER 标志。 |
|
仅限某些语言。 重写对数字的正常处理，并将其视为与字符串读取顺序匹配的强字符。 仅适用于 GCP_REORDER 标志。 |
|
仅限阿拉伯语/泰语。 对数字使用标准拉丁文字形，并替代系统默认值。 若要确定此选项是否以字体的语言提供，请使用 GetStringTypeEx 查看该语言是否支持多种数字格式。 |
|
仅限阿拉伯语/泰语。 对数字字符使用本地字形并替代系统默认值。 若要确定此选项是否以字体的语言提供，请使用 GetStringTypeEx 查看该语言是否支持多种数字格式。 |
|
对字符串重新排序。 用于非 SBCS 和从左到右阅读顺序的语言。 如果未指定此值，则假定字符串已按显示顺序排列。
如果为 Semitic 语言设置了此标志，并且使用了 lpClass 数组，则数组的前两个元素用于指定超出字符串边界的读取顺序。 GCP_CLASS_PREBOUNDRTL和GCP_CLASS_PREBOUNDLTR可用于设置顺序。 如果不需要预设顺序，请将值设置为零。 如果设置了 GCPCLASSIN 标志，则可以将这些值与其他值组合使用。 如果未指定GCP_REORDER值，则将 lpString 参数设置为对使用该参数的语言进行可视化排序，并忽略 lpOutString 和 lpOrder 字段。 使用 GetFontLanguageInfo 确定当前字体是否支持重新排序。 |
|
仅限符号语言。 指定不重置可交换字符。 例如，在从右到左的字符串中，“ (”和“) ”不会反转。 |
|
创建宽度数组时，如果字体 (有任何) ，请使用字距对。 使用 GetFontLanguageInfo 确定当前字体是否支持字距调整对。
请注意，仅仅因为 GetFontLanguageInfo 返回GCP_USEKERNING标志并不意味着必须在调用 GetCharacterPlacement 时使用它，只是选项可用。 大多数 TrueType 字体都有一个字距调整表，但你不必使用它。 |
建议应用程序使用 GetFontLanguageInfo 函数来确定GCP_DIACRITIC、GCP_DBCS、GCP_USEKERNING、GCP_LIGATE、GCP_REORDER、GCP_GLYPHSHAPE和GCP_KASHIDA值是否对当前所选字体有效。 如果无效， GetCharacterPlacement 将忽略 该值。
不再定义GCP_NODIACRITICS值，不应使用。
返回值
如果函数成功，则返回值为字符串的宽度和高度（以逻辑单元表示）。 宽度是低序字，高度是高阶字。
如果函数失败，则返回值为零。
注解
GetCharacterPlacement 可确保应用程序可以正确处理文本，而不考虑可用的国际设置和字体类型。 应用程序在使用 ExtTextOut 函数之前使用此函数，并取代 GetTextExtentPoint32 函数 (，偶尔会取代 getCharWidth32 和 GetCharABCWidths 函数) 。
除非需要理由或字距调整，否则使用 GetCharacterPlacement 检索字符间间距和索引数组并不总是必要的。 对于非拉丁语字体，应用程序可以在调用 ExtTextOut 之前使用 GetCharacterPlacement 检索字符间间距和索引数组来提高 ExtTextOut 函数呈现文本的速度。 当重复呈现相同文本或使用字符间间距定位插入点时，这尤其有用。 如果在对 ExtTextOut 的调用中使用了 lpGlyphs 输出数组，则必须设置ETO_GLYPH_INDEX标志。
GetCharacterPlacement 检查GCP_RESULTS结构的 lpOrder、lpDX、lpCaretPos、lpOutString 和 lpGlyphs 成员，如果这些成员未设置为 NULL，则填充相应的数组。 如果 GetCharacterPlacement 无法填充数组，则会将相应的成员设置为 NULL。 为了确保检索有效信息，应用程序负责在调用函数之前将成员设置为有效地址，并在调用后检查成员的值。 如果指定了GCP_JUSTIFY或GCP_USEKERNING值， 则 lpDX 和/或 lpCaretPos 成员必须具有有效的地址。
请注意，GCP_RESULTS.lpGlyphs 中返回的字形索引特定于设备上下文中的当前字体，并且只应用于在设备上下文中绘制文本，而该字体保持选中状态。
计算理由时，如果字符串中的尾随字符是空格，则 函数会减少字符串的长度，并在计算理由之前删除空格。 如果数组仅包含空格，则函数将返回错误。
ExtTextOut 需要 DBCS 字符串的每个字节有 一个 lpDX 条目，而 GetCharacterPlacement 为每个字形分配 一个 lpDX 条目。 若要在使用此函数组合时纠正这种不匹配，请使用 GetGlyphIndices ，或者为 DBCS 字节对的相应第二字节扩展具有零宽度条目的 lpDX 数组。
如果逻辑宽度小于输入字符串中前导字符的宽度，GCP_RESULTS.nMaxFit 将返回错误值。 对于这种情况，请为字形索引和 lpDX 数组调用 GetCharacterPlacement。 然后使用 lpDX 数组使用每个字符的前进宽度执行范围计算，其中 nMaxFit 是字形索引前导宽度小于前导字符宽度的字符数。
注意
wingdi.h 标头将 GetCharacterPlacement 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows 2000 Professional [仅限桌面应用] |
| 最低受支持的服务器 | Windows 2000 Server [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | wingdi.h (包括 Windows.h) |
| Library | Gdi32.lib |
| DLL | Gdi32.dll |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈