DrawText 函数 (winuser.h)

项目
01/10/2024

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

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

语法

int DrawText(
  [in]      HDC     hdc,
  [in, out] LPCTSTR 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标志。

要求

要求	值
最低受支持的客户端	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 (

另请参阅

通过

DrawText 函数 (winuser.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源