extTextOutW 函数 (wingdi.h)

项目
03/04/2024

ExtTextOut 函数使用当前所选字体、背景色和文本颜色绘制文本。可以选择提供用于剪辑和/或不透明的尺寸。

语法

BOOL ExtTextOutW(
  [in] HDC        hdc,
  [in] int        x,
  [in] int        y,
  [in] UINT       options,
  [in] const RECT *lprect,
  [in] LPCWSTR    lpString,
  [in] UINT       c,
  [in] const INT  *lpDx
);

参数

[in] hdc

设备上下文的句柄。

[in] x

用于定位字符串的引用点的 x 坐标（以逻辑坐标表示）。

[in] y

用于定位字符串的引用点的 y 坐标（以逻辑坐标为单位）。

[in] options

指定如何使用应用程序定义的矩形。此参数可使用以下一个或多个值。

值	含义
ETO_CLIPPED	文本将被剪裁为矩形。
ETO_GLYPH_INDEX	lpString 数组是指从 GetCharacterPlacement 返回的数组，应该由 GDI 直接分析，因为不需要进一步特定于语言的处理。字形索引仅适用于 TrueType 字体，但标志可用于位图和矢量字体，以指示不需要进一步的语言处理，GDI 应直接处理字符串。请注意，所有字形索引都是 16 位值，即使假定字符串是光栅字体的 8 位值的数组。对于 ExtTextOutW，字形索引将保存到图元文件。但是，若要显示正确的字符，必须使用相同的字体播放图元文件。对于 ExtTextOutA，不保存字形索引。
ETO_IGNORELANGUAGE	预留给系统使用。如果应用程序设置此标志，它将失去国际脚本支持，在某些情况下，它可能根本不显示任何文本。
ETO_NUMERICSLATIN	若要显示数字，请使用欧洲数字。
ETO_NUMERICSLOCAL	若要显示数字，请使用适合区域设置的数字。
ETO_OPAQUE	应使用当前背景色来填充矩形。
ETO_PDY	设置此项后， lpDx 指向的数组包含值对。与往常一样，每对的第一个值是相邻字符单元格的原点之间的距离，但第二个值是沿字体垂直方向的位移。
ETO_RTLREADING	Windows 中东语言版本：如果指定了此值，并在设备上下文中选择了希伯来语或阿拉伯语字体，则使用从右到左的阅读顺序输出字符串。如果未指定此值，则按从左到右的顺序输出字符串。可以通过在 SetTextAlign 中设置TA_RTLREADING值来实现相同的效果。保留此值是为了向后兼容。

ETO_GLYPH_INDEX值和ETO_RTLREADING值不能一起使用。由于 ETO_GLYPH_INDEX 表示所有语言处理都已完成，因此如果还指定了ETO_RTLREADING标志，则函数将忽略该标志。

[in] lprect

指向可选 RECT 结构的指针，该结构指定用于剪裁和/或不透明矩形的维度（以逻辑坐标表示）。

[in] lpString

指向指定要绘制的文本的字符串的指针。字符串不需要以零结尾，因为 cbCount 指定字符串的长度。

[in] c

lpString 指向的字符串的长度。

此值不能超过 8192。

[in] lpDx

指向可选值数组的指针，这些值指示相邻字符单元格的原点之间的距离。例如，lpDx[i] 逻辑单元分隔字符单元格 i 和字符单元格 i + 1 的原点。

返回值

如果绘制字符串，则返回值为非零值。但是，如果使用 ETO_GLYPH_INDEX 调用 ExtTextOut 的 ANSI 版本，则即使函数不执行任何操作，函数也会返回 TRUE 。

如果函数失败，则返回值为零。

注解

指定设备上下文的当前文本对齐设置决定了如何使用引用点来定位文本。通过调用 GetTextAlign 函数检索文本对齐设置。通过调用 SetTextAlign 函数更改文本对齐设置。可以使用以下值进行文本对齐。只能从影响水平和垂直对齐的标志中选择一个标志。此外，只能选择更改当前位置的两个标志中的一个。

术语	说明
TA_BASELINE	引用点将位于文本的基行上。
TA_BOTTOM	引用点将位于边界矩形的下边缘。
TA_TOP	引用点将位于边界矩形的上边缘。
TA_CENTER	参考点将与边界矩形的中心水平对齐。
TA_LEFT	引用点将位于边界矩形的左边缘。
TA_RIGHT	引用点将位于边界矩形的右边缘。
TA_NOUPDATECP	每次文本输出调用后，当前位置不会更新。引用点将传递给文本输出函数。
TA_RTLREADING	Windows 中东语言版本：文本按从右到左的阅读顺序进行布局，而不是默认的从左到右的顺序。仅当在设备上下文中选择的字体是希伯来语或阿拉伯语时才适用。
TA_UPDATECP	每次文本输出调用后，当前位置都会更新。当前位置用作参考点。

如果 lpDx 参数为 NULL， 则 ExtTextOut 函数使用字符之间的默认间距。字符单元格原点和 lpDx 参数指向的数组的内容按逻辑单元指定。字符单元格原点定义为字符单元格的左上角。

默认情况下，此函数不使用或更新当前位置。但是，应用程序可以调用 SetTextAlign 函数，并将 fMode 参数设置为 TA_UPDATECP，以允许系统在每次为指定设备上下文调用 ExtTextOut 时使用和更新当前位置。设置此标志后，系统会在后续 ExtTextOut 调用中忽略 X 和 Y 参数。

对于 ExtTextOut 的 ANSI 版本， lpDx 数组的 INT 值数与 lpString 中的字节数相同。对于 DBCS 字符，只要两个字节的总和加起来达到所需的 dx，就可以在前导字节和尾部字节之间的 lpDx 条目中分配 dx。对于具有 Unicode 版本的 ExtTextOut 的 DBCS 字符，每个 Unicode 字形获取一个 pdx 条目。

请注意，GetTextExtentExPoint 中的 alpDx 值与 ExtTextOut 的 lpDx 值不同。若要在 lpDx 中使用 alpDx 值，必须先处理它们。

ExtTextOut 将在必要时使用 Uniscribe ，从而导致字体回退。 ETO_IGNORELANGUAGE标志将禁止此行为，不应传递。

此外， ExtTextOut 将在转换到内核模式之前执行内部批处理调用，从而缓解 了在权衡 PolyTextOut 与 ExtTextOut 使用情况时的一些性能问题。

提示

强烈建议使用 ExtTextOut 替代 PolyTextOut 进行新式开发，因为它能够处理不同语言的显示。

示例

有关示例，请参阅 Using Menus 中的“设置 Menu-Item 文本字符串的字体”。

注意

wingdi.h 标头将 ExtTextOut 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	wingdi.h (包括 Windows.h)
Library	Gdi32.lib
DLL	Gdi32.dll