DrawTextW 函数 (winuser.h)

项目
01/10/2024

DrawText 函数在指定矩形中绘制格式化文本。它根据指定的方法格式化文本 (展开制表符、对齐字符、断行等) 。

若要指定其他格式设置选项，请使用 DrawTextEx 函数。

语法

int DrawTextW(
  [in]      HDC     hdc,
  [in, out] LPCWSTR lpchText,
  [in]      int     cchText,
  [in, out] LPRECT  lprc,
  [in]      UINT    format
);

参数

[in] hdc

设备上下文的句柄。

[in, out] lpchText

指向指定要绘制的文本的字符串的指针。如果 nCount 参数为 -1，则字符串必须以 null 结尾。

如果 uFormat 包含DT_MODIFYSTRING，则函数最多可为此字符串添加四个附加字符。包含字符串的缓冲区应足够大，以容纳这些额外的字符。

[in] cchText

字符串的长度（以字符为单位）。如果 nCount 为 -1，则 假定 lpchText 参数是指向以 null 结尾的字符串的指针， DrawText 会自动计算字符计数。

[in, out] lprc

指向 RECT 结构的指针，该结构包含要设置文本格式的逻辑坐标) 矩形 (。

[in] format

设置文本格式的方法。此参数可使用以下一个或多个值。

值	含义
DT_BOTTOM	使文本与矩形底部对齐。此值仅用于DT_SINGLELINE值。
DT_CALCRECT	确定矩形的宽度和高度。如果存在多行文本， DrawText 将使用 lpRect 参数指向的矩形的宽度，并扩展矩形的基以绑定最后一行文本。如果最大的单词比矩形宽，则宽度将展开。如果文本小于矩形的宽度，则宽度将减小。如果只有一行文本， DrawText 将修改矩形的右侧，使其绑定行中的最后一个字符。在任一情况下， DrawText 都返回格式化文本的高度，但不绘制文本。
DT_CENTER	在矩形中水平居中居中文本。
DT_EDITCONTROL	复制多行编辑控件的文本显示特征。具体而言，平均字符宽度的计算方式与编辑控件的计算方式相同，并且函数不显示部分可见的最后一行。
DT_END_ELLIPSIS	对于显示的文本，如果字符串的末尾不适合矩形，则会将其截断并添加省略号。如果不在字符串末尾的单词超出矩形的限制，则会将其截断，而不用省略号。除非指定了DT_MODIFYSTRING标志，否则不会修改字符串。与DT_PATH_ELLIPSIS和DT_WORD_ELLIPSIS进行比较。
DT_EXPANDTABS	扩展制表符。每个制表符的默认字符数是 8。 DT_WORD_ELLIPSIS、DT_PATH_ELLIPSIS和DT_END_ELLIPSIS值不能与DT_EXPANDTABS值一起使用。
DT_EXTERNALLEADING	在行高中包括字体外部间隙。通常，外部前导不包括在文本行的高度中。
DT_HIDEPREFIX	忽略文本中的和号 (&) 前缀字符。后面的字母不会加下划线，但仍会处理其他助记前缀字符。例如：输入字符串：“A&bc&&d” normal： “Abc&d” DT_HIDEPREFIX：“Abc&d” 与 DT_NOPREFIX 和 DT_PREFIXONLY 进行比较。
DT_INTERNAL	使用系统字体计算文本规格。
DT_LEFT	将文本向左对齐。
DT_MODIFYSTRING	修改指定的字符串以匹配显示的文本。除非指定了DT_END_ELLIPSIS或DT_PATH_ELLIPSIS，否则此值不起作用。
DT_NOCLIP	绘制时不进行剪裁。使用 DT_NOCLIP 时，DrawText 的速度会稍快一些。
DT_NOFULLWIDTHCHARBREAK	防止 DBCS 中的换行 (双宽字符串) ，以便换行规则等效于 SBCS 字符串。例如，这可以在朝鲜语窗口中使用，以便提高图标标签的可读性。除非指定了DT_WORDBREAK，否则此值不起作用。
DT_NOPREFIX	关闭对前缀字符的处理。通常， DrawText 将助记前缀字符 & 解释为指令来强调后面的字符，助记前缀字符 && 作为指令来打印单个 &。通过指定DT_NOPREFIX，会关闭此处理。例如，例如：输入字符串：“A&bc&&d” normal： “Abc&d” DT_NOPREFIX：“A&bc&&d” 与DT_HIDEPREFIX和DT_PREFIXONLY进行比较。
DT_PATH_ELLIPSIS	对于显示的文本，将字符串中间的字符替换为省略号，以便结果适合指定矩形。如果字符串包含反斜杠 (\\) 字符，DT_PATH_ELLIPSIS在最后一个反斜杠之后保留尽可能多的文本。除非指定了DT_MODIFYSTRING标志，否则不会修改字符串。与 DT_END_ELLIPSIS 和 DT_WORD_ELLIPSIS 进行比较。
DT_PREFIXONLY	仅在字符的后部绘制一个下划线，并 (&) 前缀字符。不会在字符串中绘制任何其他字符。例如，例如：输入字符串：“A&bc&&d”n normal： “Abc&d” DT_PREFIXONLY：“_ ” 与DT_HIDEPREFIX和DT_NOPREFIX进行比较。
DT_RIGHT	将文本向右对齐。
DT_RTLREADING	当 hdc 中选择的字体是希伯来语或阿拉伯语字体时，双向文本的从右到左阅读顺序布局。所有文本的默认阅读顺序都是从左到右。
DT_SINGLELINE	仅显示单行上的文本。回车符和换行符不会中断该行。
DT_TABSTOP	设置制表位。 15-8 位 (uFormat 参数的低序字) 的高阶字节指定每个选项卡的字符数。每个选项卡的默认字符数为 8。 DT_CALCRECT、DT_EXTERNALLEADING、DT_INTERNAL、DT_NOCLIP和DT_NOPREFIX值不能与DT_TABSTOP值一起使用。
DT_TOP	使文本与矩形顶部对齐。
DT_VCENTER	垂直居中文本。此值仅用于DT_SINGLELINE值。
DT_WORDBREAK	中断字词。如果单词超出 lpRect 参数指定的矩形边缘，则单词之间的行会自动断开。回车符换行序列也会中断该行。如果未指定此项，则输出位于一行中。
DT_WORD_ELLIPSIS	截断矩形中不适合的任何单词，并添加省略号。与DT_END_ELLIPSIS和DT_PATH_ELLIPSIS进行比较。

返回值

如果函数成功，则返回值是文本的高度（以逻辑单位为单位）。如果指定了DT_VCENTER或DT_BOTTOM，则返回值是绘制 lpRect->top 文本从到底部的偏移量

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

注解

DrawText 函数使用设备上下文的所选字体、文本颜色和背景色来绘制文本。除非使用DT_NOCLIP格式， 否则 DrawText 将剪裁文本，使其不显示在指定矩形之外。请注意，可能会剪裁具有明显悬垂的文本，例如，文本字符串中的初始“W”或斜体文本。除非指定了DT_SINGLELINE格式，否则假定所有格式都包含多行。

如果所选字体对于指定的矩形来说太大， 则 DrawText 函数不会尝试替换较小的字体。

设备上下文的文本对齐模式必须包括TA_LEFT、TA_TOP和TA_NOUPDATECP标志。

注意

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

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	winuser.h (包括 Windows.h)
Library	User32.lib
DLL	User32.dll
API 集	在 Windows 8) 中引入的 ext-ms-win-ntuser-misc-l1-1-0 (

另请参阅

通过

DrawTextW 函数 (winuser.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源