windows编程之TextOut与DrawText

目录

• windows编程之TextOut与DrawText
  • TextOut 是什么函数
  • TextOut 函数原型
  • DrawText 是什么函数
  • DrawText 函数原型
  • TextOut与DrawText区别
  • 后话

windows编程之TextOut与DrawText

TextOut 是什么函数

该函数用当前选择的字体、背景颜色和正文颜色将一个字符串写到指定位置。

TextOut 函数原型

BOOL TextOut(
  _In_  HDC hdc,
  _In_  int nXStart,
  _In_  int nYStart,
  _In_  LPCTSTR lpString,
  _In_  int cchString
);

注：

In_ 说明该参数是输入的，opt 说明该参数是可选参数。

字符串对齐的基准点取决于当前的文本对齐模式。应用程序可以通过调用 GetTextAlign 获得当前的文本对齐模式，通过调用 SetTextAlign 修改该模式。可以使用以下值进行文本对齐。 只能从影响水平对齐和垂直对齐的标志中选择一个标志。 此外，只能选择更改当前位置的两个标志中的一个。

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

参数	含义
hdc	设备环境句柄
nXStart	指定用于字符串对齐的基准点的逻辑 x 坐标（有关基准点请看下边备注）
nYStart	指定用于字符串对齐的基准点的逻辑 y 坐标
lpString	【1】 指向将被绘制字符串的指针 【2】该字符串不必以'\0'结束，因为 cchString 参数指定了该字符串的长度
cchString	lpString 字符串的长度（有多少个字符）

返回值：

1. 如果函数调用成功，返回值为非 0；

2. 如果函数调用失败，返回值为 0。

---

DrawText 是什么函数

该函数在指定的矩形里写入格式化的正文，根据指定的方法对正文格式化（扩展的制表符，字符对齐、折行等）。

---

DrawText 函数原型

int DrawText(
  _In_     HDC hDC,
  _Inout_  LPCTSTR lpchText,
  _In_     int nCount,
  _Inout_  LPRECT lpRect,
  _In_     UINT uFormat
);

参数解析：

参数	含义
hDC	指定“显示设备描述表”句柄
lpchText	【1】 指向将被写入的字符串的指针，如果参数 nCount 是 -1，则字符串必须是以 \0 结束的 【2】如果 uFormat 包含 DT_MODIFYSTRING，则函数可为此字符串增加 4 个字符，存放字符串的缓冲区必须足够大，能容纳附加的字符
nCount	【1】 指向字符串中的字符数【 2】如果 nCount 为 -1，则 lpchText 指向的字符串被认为是以 \0 结束的，DrawText 会自动计算字符数
lpRect	指向 RECT 结构的指针，其中包含文本将被置于其中的矩形的信息（按逻辑坐标）
uFormat	【1】 指定格式化文本的方法 【2】此参数可以通过指定下列标志或标志的组合

uFormat 参数各种标志解析

标志	含义
DT_BOTTOM	对齐文字到矩形的底部，当且仅当设置了 DT_SINGLELINE 标志才有效
DT_CALCRECT	1. 这个参数决定矩形的宽度和高度 2. 如果输出文本有多行，DrawText 函数使用 lpRect 定义的矩形的宽度，并扩展矩形的底部以容纳输出文本的最后一行 3. 如果输出文本只有一行，则 DrawText 函数改变矩形的右边界，以容纳下正文行的最后一个字符 4. 出现上述任何一种情况，DrawText 函数将返回格式化文本的高度，而不是绘制文本
DT_CENTER	文本水平居中显示
DT_EDITCONTROL	将拥有多行编辑控件的正文显示特性（尤其是平均字符宽度的计算方法，并且不会显示不可见的最后一行）
DT_END_ELLIPSIS	1. 对于显示的文本，如果结束的字符串的范围不在矩形内，它会被截断并以省略号标识 2. 如果一个字母不是在字符串的末尾但却超出了矩形范围，它会被换行但没有追加省略号标识 3. 除非指定了 DT_MODIFYSTRING 标志，否则字符串不会被修改
DT_EXPANDTABS	1. 扩展制表符，每个制表符的缺省字符数是 8 2. DT_WORD_ELLIPSIS, DT_PATH_ELLIPSIS 和 DT_END_ELLIPSIS 不能和此参数一起使用
DT_EXTERNALLEADING	在行的高度里包含字体的外部标头（通常外部标头不被包含在正文行的高度里）
DT_HIDEPREFIX	1. 忽略正文中的前缀字符（&），并且前缀字符后面的字母不会出现下划线，其它前缀字符的调用方式不受影响 2. 例如：输入字符串为“F&is&&hC”，正常显示为“Fis&hC”，使用 DT_HIDEPREFIX 显示为“Fis&hC”
DT_INTERNAL	用系统字体来计算正文尺寸
DT_LEFT	正文左对齐
DT_MODIFYSTRING	1. 允许系统修改给定的字符串来匹配显示的正文 2. 此标志必须和 DT_END_ELLIPSIS 或 DT_PATH_ELLIPSIS 同时使用
DT_NOCLIP	无裁剪绘制，使用 DT_NOCLIP 可以提高 DrawText 的效率
DT_NOFULLWIDTHCHARBREAK	1. 在宽字符的字符串中防止行断开，因此折行规则相当于单字符的字符串 2. 例如，我们可以用在韩国版的 Windows 中，为图标标签提供更好的可读性 3. 除非指定 DT_WORDBREAK，否则此值没有作用
DT_NOPREFIX	1. 关闭前缀字符的处理（通常 DrawText 解释 & 为给其后的字符加下划线，解释 && 为显示单个 &） 2. 例如：输入字符串为“F&is&&hC”，正常显示为“Fis&hC”，使用 DT_NOPREFIX 显示为“F&is&&hC”
DT_PATH_ELLIPSIS	1. 对于过长的正文，自动替换字符串中间的字符为省略号（...），以确保结果能在合适的矩形内显示 2. 如果该字符串包含反斜杠（\）字符，DT_PATH_ELLIPSIS 尽可能的保留最后一个反斜杠之后的字符 3. 除非指定了 DT_MODIFYSTRING 标志否则字符串不会被修改
DT_PREFIXONLY	1. 仅仅在（&）前缀字符的位置下绘制一个下划线，但不绘制字符串中的任何其他字符 2. 例如：输入字符串为“F&is&&hC”，正常显示为“Fis&hC”，使用 DT_PREFIXONLY 显示为“_”
DT_RIGHT	正文右对齐
DT_RTLREADING	当设备环境的字体是希伯来文或阿拉伯文字体时，为双向正文安排从右到左的阅读顺序
DT_SINGLELINE	显示正文的同一行，回车和换行符都不能换行
DT_TABSTOP	1. 设置制表符，参数 uFormat 的 8~15 位（低位字中的高位字节）指定每个制表符的字符数，每个制表符的缺省字符数是 8 2. DT_CALCRECT, DT_EXTERNALLEADING, DT_INTERNAL, DT_NOCLIP 和 DT_NOPREFIX 不能和此参数一起使用
DT_TOP	正文顶端对齐
DT_VCENTER	使正文在矩形中垂直居中，当且仅当设置了 DT_SINGLELINE 标志才有效
DT_WORDBREAK	1. 当一行中的字符将会延伸到由 lpRect 指定的矩形的边框时，此行自动地在单词之间断开 2. 一个回车一换行也能使之换行 3. 如果没有指定，输出会在一行上
DT_WORD_ELLIPSIS	截短不符合矩形的正文，并增加省略号（与 DT_END_ELLIPSIS 类似）

返回值：

1. 如果函数调用成功，返回值是正文的高度（逻辑单位）；

2. 如果指定了 DT_VCENTER 或 DT_BOTTOM，返回值是 lpRect -> top 到绘制的正文的底部的偏移值；

3. 如果 函数调用失败，返回值是 0。

备注：

1. 函数 DrawText 用设备环境中的字体选择、正文颜色和背景颜色来写正文。

2. DrawText 裁剪正文，使之不会出现在指定矩形的外面，除非指定了 DT_NOCLIP。

3. 除非使用 DT_SINGLELINE 格式化，否则其余的格式都认为正文有多行。

4. 如果选择的字体对指定的矩形而言太大，DrawText 并不会试图去换成一种小字体。

5. 设备环境的正文对齐方式必须包括 TA_LEFT, TA_TOP 和 TA_NOUPDATECP 标志。

---

TextOut与DrawText区别

TextOut

• 绘制简单（指 提供可选参数少）
• ？
• Gdi32.dll

DrawText

• 可以将文本字符串绘制到以逻辑坐标指定的矩形区域中
• 支持多行
• 支持字体多种设置，超出换行或者显示省略号
• User32.dll

---

后话

应用程序选择适当的字体后，设置所需的文本格式选项，并计算文本字符串所需的字符宽度和高度值，它可以通过调用任何文本输出函数开始绘制字符和符号：

• DrawText
• DrawTextEx
• ExtTextOut
• PolyTextOut
• TabbedTextOut
• TextOut

当应用程序调用其中一个函数时，操作系统会将调用传递给图形引擎，从而将调用传递给相应的设备驱动程序。 在设备驱动程序级别，所有这些调用都受驱动程序自己的 ExtTextOut 或 TextOut 函数的一个或多个调用支持。 应用程序将通过调用 ExtTextOut 实现最快的执行，后者可快速转换为设备的 ExtTextOut 调用。 但是，当应用程序应调用其他三个函数之一时，存在一些实例：例如，若要在指定矩形区域的边框内绘制多行文本，调用 DrawText 更高效。 若要创建具有文本对齐列的多列，调用 TabbedTextOut 更高效。