GetCharacterPlacementW 函数 (wingdi.h)

项目
08/27/2023

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 GetCharacterPlacementW(
  [in]      HDC            hdc,
  [in]      LPCWSTR        lpString,
  [in]      int            nCount,
  [in]      int            nMexExtent,
  [in, out] LPGCP_RESULTSW lpResults,
  [in]      DWORD          dwFlags
);

参数

[in] hdc

设备上下文的句柄。

[in] lpString

指向要处理的字符串的指针。字符串不需要以零结尾，因为 nCount 指定字符串的长度。

[in] nCount

lpString 指向的字符串的长度。

[in] nMexExtent

最大范围 () 处理字符串的逻辑单元。如果已处理，将忽略超出此范围的字符。任何所需排序或字形数组的计算仅适用于包含的字符。仅当在 dwFlags 参数中指定了GCP_MAXEXTENT值时，才使用此参数。当函数处理输入字符串时，只有当总范围尚未超过最大值时，每个字符及其范围才会添加到输出、范围和其他数组中。达到限制后，处理将停止。

[in, out] lpResults

指向接收函数结果的GCP_RESULTS 结构的指针。

[in] dwFlags

指定如何将字符串处理成所需的数组。此参数可使用以下一个或多个值。

值	含义
GCP_CLASSIN	指定 lpClass 数组包含字符的预设分类。分类可能与输出中的分类相同。如果字符的特定分类未知，则必须将数组中的相应位置设置为零。有关分类的详细信息，请参阅GCP_RESULTS。仅当 GetFontLanguageInfo 返回GCP_REORDER标志时，这才有用。
GCP_DIACRITIC	确定如何处理字符串中的音调符号。如果未设置此值，则音调符号被视为零宽度字符。例如，希伯来语字符串可能包含音调符号，但你可能不想显示它们。使用 GetFontLanguageInfo 确定字体是否支持音调符号。如果存在，则可以在调用 GetCharacterPlacement 时使用或不使用 GCP_DIACRITIC 标志，具体取决于应用程序的需求。
GCP_DISPLAYZWG	对于需要根据字符在单词中的位置重新排序或不同字形的语言，不可显示的字符通常出现在代码页中。例如，在希伯来语代码页中，有从左到右和从右向左标记，以帮助确定输出字符串中字符的最终位置。通常，它们不会显示，并且会从 lpGlyphs 和 lpDx 数组中删除。可以使用 GCP_DISPLAYZWG 标志来显示这些字符。
GCP_GLYPHSHAPE	指定使用当前代码页当前所选字体中定义的标准形状以外的其他形状显示字符串中的部分或所有字符。某些语言（如阿拉伯语）不支持创建字形，除非指定此值。作为一般规则，如果 GetFontLanguageInfo 返回字符串的此值，则必须将此值与 GetCharacterPlacement 一起使用。
GCP_JUSTIFY	调整 lpDx 数组中的盘区，使字符串长度与 nMaxExtent 相同。 GCP_JUSTIFY只能与 GCP_MAXEXTENT 一起使用。
GCP_KASHIDA	使用 Kashidas 以及（而不是调整的盘区）修改字符串的长度，使其等于 nMaxExtent 指定的值。在 lpDx 数组中，Kashida 由负理由索引指示。 GCP_KASHIDA只能与 GCP_JUSTIFY 一起使用，并且仅当字体 (和语言) 支持 Kashidas 时才可使用。使用 GetFontLanguageInfo 确定当前字体是否支持 Kashidas。使用 Kashidas 来对齐字符串可能会导致所需的字形数大于输入字符串中的字符数。因此，在使用 Kashidas 时，应用程序无法假定将数组设置为输入字符串的大小就足够了。 (可能的最大可能约为 dxPageWidth/dxAveCharWidth，其中 dxPageWidth 是文档的宽度，dxAveCharWidth 是从 getTextMetrics 调用) 返回的平均字符宽度。请注意，仅仅因为 GetFontLanguageInfo 返回GCP_KASHIDA标志并不意味着必须在调用 GetCharacterPlacement 时使用它，只是选项可用。
GCP_LIGATE	在字符与任何位置使用连字。如果一个字形用于两个或多个字符，则会发生连字。例如，字母 a 和 e 可以表示为？。但是，若要使用此功能，语言支持和字体都必须支持所需的字形， (默认情况下不会以英语) 处理该示例。使用 GetFontLanguageInfo 确定当前字体是否支持连字。如果它确实需要，并且需要一个特定的最大值来限制字符数，请在 lpGlyphs 数组的第一个元素中设置该数字。如果需要正常连接，请将此值设置为零。如果未指定GCP_LIGATE，则不会进行结扎。有关详细信息，请参阅GCP_RESULTS。如果字符集通常需要GCP_REORDER值，但未指定，则输出将毫无意义，除非传入的字符串已采用可视顺序 (也就是说，在对 GetCharacterPlacement 的一次调用中放入 lpGcpResults-lpOutString> 的结果是) 第二次调用的输入字符串。请注意，仅仅因为 GetFontLanguageInfo 返回GCP_LIGATE标志并不意味着必须在调用 GetCharacterPlacement 时使用它，只是选项可用。
GCP_MAXEXTENT	字符串的计算范围（以逻辑单位为单位）不超过 nMaxExtent 参数指定的值。
GCP_NEUTRALOVERRIDE	仅限某些语言。重写对中性的正常处理，并将其视为与字符串读取顺序匹配的强字符。仅对 GCP_REORDER 标志有用。
GCP_NUMERICOVERRIDE	仅限某些语言。重写对数字的正常处理，并将其视为与字符串读取顺序匹配的强字符。仅对 GCP_REORDER 标志有用。
GCP_NUMERICSLATIN	仅限阿拉伯语/泰语。对数字使用标准拉丁文字形并替代系统默认值。若要确定此选项是否以字体语言提供，请使用 GetStringTypeEx 查看该语言是否支持多个数字格式。
GCP_NUMERICSLOCAL	仅限阿拉伯语/泰语。对数字字符使用本地字形并替代系统默认值。若要确定此选项是否以字体语言提供，请使用 GetStringTypeEx 查看该语言是否支持多个数字格式。
GCP_REORDER	对字符串重新排序。用于非 SBCS 和从左到右阅读顺序的语言。如果未指定此值，则假定字符串已按显示顺序显示。如果为 Semitic 语言设置了此标志，并且使用了 lpClass 数组，则数组的前两个元素用于指定超出字符串边界的读取顺序。 GCP_CLASS_PREBOUNDRTL和GCP_CLASS_PREBOUNDLTR可用于设置顺序。如果不需要预设顺序，请将值设置为零。如果设置了 GCPCLASSIN 标志，则可以将这些值与其他值组合使用。如果未指定GCP_REORDER值，则将 lpString 参数设置为对使用该参数的语言进行可视化排序，并忽略 lpOutString 和 lpOrder 字段。使用 GetFontLanguageInfo 确定当前字体是否支持重新排序。
GCP_SYMSWAPOFF	仅限 Semitic 语言。指定不重置可交换字符。例如，在从右到左的字符串中，“ (”和“) ”不会反转。
GCP_USEKERNING	如果创建宽度数组时有任何) ，请使用字体 (字距调整对。使用 GetFontLanguageInfo 确定当前字体是否支持字距调整对。请注意，仅仅因为 GetFontLanguageInfo 返回GCP_USEKERNING标志并不意味着必须在调用 GetCharacterPlacement 时使用它，而只是该选项可用。大多数 TrueType 字体都有字距调整表，但你不必使用它。

不再定义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