描述
GetCharacterPlacement函数检索有关字符串的信息，例如字符宽度，插入符号定位，字符串中的排序和字形渲染。返回的信息类型取决于dwFlags中参数，并且基于指定显示上下文中当前选定的字体。该函数将信息复制到指定的GCP_RESULTS结构或由结构指定的一个或多个数组。
虽然这个功能曾经适用于使用字符串，但是需要使用越来越多的语言和脚本来使其过时。它已被Uniscribe模块的功能所取代。
C++ 语法
DWORD GetCharacterPlacement( __in HDC hdc, __in LPCTSTR lpString, __in int nCount, __in int nMaxExtent, __inout LPGCP_RESULTS lpResults, __in DWORD dwFlags ); |
PowerBASIC 语法
FUNCTION GetCharacterPlacementA ( _ BYVAL hdc AS DWORD, _ BYREF lpString AS ASCIIZ, _ BYVAL nCount AS LONG, _ BYVAL nMaxExtent AS LONG, _ BYREF lpResults AS GCP_RESULTS, _ BYVAL dwFlags AS DWORD _ ) AS DWORD |
Unicode版本:
FUNCTION GetCharacterPlacementW ( _ BYVAL hdc AS DWORD, _ BYREF lpString AS WSTRINGZ, _ BYVAL nCount AS LONG, _ BYVAL nMaxExtent AS LONG, _ BYREF lpResults AS GCP_RESULTS, _ BYVAL dwFlags AS DWORD _ ) AS DWORD |
参数
hdc
[in]处理设备上下文。
lpString
[in]指向要处理的字符串的指针。字符串不需要为零终止，因为nCount指定字符串的长度。
nCount
[in]指定lpString指向的字符串的长度。
Windows 95/98 / Me：此值不得超过8192。
nMaxExtent
[in]指定字符串处理的最大范围（以逻辑单位）。如果被处理的字符超出这个范围将被忽略。任何所需排序或字形数组的计算仅适用于包含的字符。仅当在dwFlags中参数中指定了GCP_MAXEXTENT值时，才使用此参数。由于函数处理输入字符串，所以每个字符及其范围仅在总范围尚未超过最大值时被添加到输出，范围和其他数组。一旦达到极限，处理将停止。
lpResults
[in, out]指向接收函数结果的GCP_RESULTS结构的指针。
dwFlags
[in]指定如何将字符串处理为必需的数组。此参数可以是以下值中的一个或多个。
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值，但未指定，则输出将无意义，除非传入的字符串已经在可视化排序中（即，在lpGcpResults->lpOutString中调用{ 989796201}是第二个调用的输入字符串）。
请注意，只是因为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
只有闪族语言。指定可交换字符未重置。例如，在从右到左的字符串中，'（'和'）'不反转。
GCP_USEKERNING
在创建宽度数组时，使用字体中的字距对（如果有）。使用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来检索字符间距和索引数组并不总是必需的，除非需要进行校对或字距调整。对于非拉丁字体，应用程序可以通过使用GetCharacterPlacement在调用ExtTextOut之前检索字符间距和索引数组来提高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中返回的字形索引特定于设备上下文中的当前字体，并且只能用于在该字体保持选定的情况下在设备上下文中绘制文本。
当计算对齐时，如果字符串中的尾随字符是空格，则该函数会减少字符串的长度，并在计算对齐之前删除空格。如果数组仅由空格组成，则该函数返回错误。
请注意，对于Kashida而言，GetCharacterPlacement并不会产生与Windows NT / 2000 / XP / Vista / Windows 7上Windows 98 / Me相同的结果。要实现所有操作系统的一致性，请使用Uniscribe。
ExtTextOut期望一个DBCS字符串的每个字节的lpDX条目，而GetCharacterPlacement为每个字形分配一个lpDX条目。要使用这种功能组合来纠正这种不匹配，可以使用GetGlyphIndices或展开lpDX数组，使用零宽度条目对应于DBCS字节对的相应第二个字节。
Windows NT / 2000 / XP / Vista / Windows 7：如果逻辑宽度小于输入字符串中的前导字符的宽度，则GCP_RESULTS.nMaxFit返回一个错误的值。对于这种情况，调用GetCharacterPlacement字形索引和lpDX数组。然后使用lpDX数组使用每个字符的前进宽度进行范围计算，其中nMaxFit是字形索引的前进宽度小于前导字符的宽度的字符数。
Windows 95/98 / Me：Microsoft Layer for Unicode支持GetCharacterPlacementW.
引用文件 #INCLUDE Once
WinGdi.inc（包括Windows.inc）