DrawTextExW 函数 (winuser.h)

项目
03/04/2024

DrawTextEx 函数在指定矩形中绘制带格式的文本。

语法

int DrawTextExW(
  [in]      HDC              hdc,
  [in, out] LPWSTR           lpchText,
  [in]      int              cchText,
  [in, out] LPRECT           lprc,
  [in]      UINT             format,
  [in]      LPDRAWTEXTPARAMS lpdtp
);

参数

[in] hdc

要在其中绘制的设备上下文的句柄。

[in, out] lpchText

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

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

[in] cchText

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

[in, out] lprc

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

[in] format

格式设置选项。此参数可使用以下一个或多个值。

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

[in] lpdtp

指向 DRAWTEXTPARAMS 结构的指针，该结构指定其他格式设置选项。此参数可以为 NULL。

返回值

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

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

注解

DrawTextEx 函数仅支持转义和方向均为零的字体。

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

注意

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

要求

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

另请参阅

通过

DrawTextExW 函数 (winuser.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源