ExtTextOutA 函数（wingdi.h）

项目
11/20/2024

ExtTextOut 函数使用当前选定的字体、背景色和文本颜色绘制文本。可以选择提供用于剪辑、不透明或两者兼有的维度。

语法

BOOL ExtTextOutA(
  [in] HDC        hdc,
  [in] int        x,
  [in] int        y,
  [in] UINT       options,
  [in] const RECT *lprect,
  [in] LPCSTR     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 应直接处理字符串。请注意，即使假定字符串是光栅字体的 8 位值的数组，所有字形索引都是 16 位值。对于 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 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 项。对于 Unicode 版本的 DBCS 字符 ExtTextOut，每个 Unicode 字形获取单个 pdx 条目。

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

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

此外，在转换为内核模式之前，ExtTextOut 将执行内部批处理，在权衡使用 PolyTextOut 与 ExtTextOut时，会降低某些性能问题。

提示

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

例子

有关示例，请参阅 “使用菜单设置 Menu-Item 文本字符串的字体”。

注意

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

要求

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