textOutW 函数 (wingdi.h)

项目
08/27/2023

TextOut 函数使用当前所选字体、背景色和文本颜色在指定位置写入字符串。

语法

BOOL TextOutW(
  [in] HDC     hdc,
  [in] int     x,
  [in] int     y,
  [in] LPCWSTR lpString,
  [in] int     c
);

参数

[in] hdc

设备上下文的句柄。

[in] x

系统用于对齐字符串的引用点的 x 坐标（以逻辑坐标表示）。

[in] y

系统用于对齐字符串的引用点的 y 坐标（以逻辑坐标表示）。

[in] lpString

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

[in] c

lpString 指向的字符串的长度（以字符为单位）。

返回值

如果该函数成功，则返回值为非零值。

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

注解

参考点的解释取决于当前文本对齐模式。应用程序可以通过调用 GetTextAlign 函数来检索此模式;应用程序可以通过调用 SetTextAlign 函数来更改此模式。可以使用以下值进行文本对齐。只能从影响水平和垂直对齐的标志中选择一个标志。此外，只能选择更改当前位置的两个标志中的一个。

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

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

将 TextOut 函数置于路径括号内时，系统会为包含每个字符及其字符框的 TrueType 文本生成路径。生成的区域是字符框减去文本，而不是文本本身。在将 TextOut 函数置于路径括号中之前，可以通过将背景模式设置为透明来获取 TrueType 文本轮廓所包围的区域。下面是演示此过程的示例代码。


// Obtain the window's client rectangle 
GetClientRect(hwnd, &r);

// THE FIX: by setting the background mode 
// to transparent, the region is the text itself 
// SetBkMode(hdc, TRANSPARENT); 

// Bracket begin a path 
BeginPath(hdc);

// Send some text out into the world 
TCHAR text[ ] = "Defenestration can be hazardous";
TextOut(hdc,r.left,r.top,text, ARRAYSIZE(text));

// Bracket end a path 
EndPath(hdc);

// Derive a region from that path 
SelectClipPath(hdc, RGN_AND);

// This generates the same result as SelectClipPath() 
// SelectClipRgn(hdc, PathToRegion(hdc)); 

// Fill the region with grayness 
FillRect(hdc, &r, GetStockObject(GRAY_BRUSH));

示例

有关示例，请参阅枚举已安装的字体。

注意

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

要求

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