Article directory
Windows programming TextOut and DrawText
What is TextOut function
This function writes a string to the specified location using the currently selected font, background color, and text color.
TextOut function prototype
BOOL TextOut(
_In_ HDC hdc,
_In_ int nXStart,
_In_ int nYStart,
_In_ LPCTSTR lpString,
_In_ int cchString
);
Note :
In_ indicates that the parameter is input, and opt indicates that the parameter is optional.
The base point for string alignment depends on the current text alignment mode. The application can GetTextAlignobtain , and SetTextAlignmodify the mode by calling . The following values can be used for text alignment. Only one flag can be selected from flags that affect horizontal and vertical alignment. Also, only one of the two flags for changing the current position can be selected.
| parameter | illustrate |
|---|---|
| TA_BASELINE | The reference point will be on the base line of the text. |
| OF_BOTTOM | The reference point is at the lower edge of the bounding rectangle. |
| TA_TOP | The reference point will be at the top edge of the bounding rectangle. |
| TA_CENTER | The reference point will be horizontally aligned with the center of the bounding rectangle. |
| TA_LEFT | The reference point will be at the left edge of the bounding rectangle. |
| TA_RIGHT | The reference point is at the right edge of the bounding rectangle. |
| TA_NOUPDATECP | The current position is not updated after each text output call. The reference point will be passed to the text output function. |
| TA_RTLREADING | Middle Eastern language versions of Windows: Text is arranged in right-to-left reading order instead of the default left-to-right order. This only works when the font selected in the device context is Hebrew or Arabic. |
| TA_UPDATECP | The current position is updated after each text output call. The current location is used as a reference point. |
| parameter | meaning |
|---|---|
| hdc | device context handle |
| nXStart | Specifies the logical x-coordinate of the datum point used for string alignment (see the note below for the datum point) |
| newStart | Specifies the logical y-coordinate of the datum point used for string alignment |
| lpString | [1] Pointer to the string to be drawn [2] The string does not have to end with '\0', because the cchString parameter specifies the length of the string |
| cchString | The length of the lpString string (how many characters are there) |
return value:
-
If the function call is successful, the return value is non-zero;
-
If the function call fails, the return value is 0.
What function is DrawText
This function writes formatted text in the specified rectangle, formatting the text according to the specified method (extended tabs, character alignment, line wrapping, etc.).
DrawText function prototype
int DrawText(
_In_ HDC hDC,
_Inout_ LPCTSTR lpchText,
_In_ int nCount,
_Inout_ LPRECT lpRect,
_In_ UINT uFormat
);
Parameter analysis:
| parameter | meaning |
|---|---|
| hDC | Specifies the "display device context" handle |
| lpchText | [1] Pointer to the string to be written, if the parameter nCount is -1, the string must end with \0 [2] If uFormat contains DT_MODIFYSTRING, the function can add 4 characters to this string , the buffer storing the string must be large enough to hold additional characters |
| nCount | [1] Point to the number of characters in the string [2] If nCount is -1, the string pointed to by lpchText is considered to end with \0, and DrawText will automatically calculate the number of characters |
| lpRect | pointer to a RECT structure containing information (in logical coordinates) about the rectangle in which the text will be placed |
| uFormat | [1] The method of specifying formatted text [2] This parameter can be specified by specifying the following flags or a combination of flags |
Analysis of various flags of uFormat parameters
| the sign | meaning |
|---|---|
| DT_BOTTOM | Align text to the bottom of the rectangle, only valid if DT_SINGLELINE flag is set |
| DT_CALCRECT | 1. This parameter determines the width and height of the rectangle 2. If the output text has multiple lines, the DrawText function uses the width of the rectangle defined by lpRect and extends the bottom of the rectangle to accommodate the last line of output text 3. If the output text has only one line, then The DrawText function changes the right border of the rectangle to accommodate the last character of the text line 4. In any of the above cases, the DrawText function will return the height of the formatted text instead of drawing the text |
| DT_CENTER | Center text horizontally |
| DT_EDITCONTROL | Will have the text display features of the multi-line edit control (especially the calculation method of the average character width, and will not display the invisible last line) |
| DT_END_ELLIPSIS | 1. For the displayed text, if the ending string is not within the rectangle, it will be truncated and marked with an ellipsis 2. If a letter is not at the end of the string but outside the rectangle, it will be wrapped but not Append the ellipsis mark 3. The string will not be modified unless the DT_MODIFYSTRING flag is specified |
| DT_EXPANDTABS | 1. Extended tab, the default number of characters per tab is 8 2. DT_WORD_ELLIPSIS, DT_PATH_ELLIPSIS and DT_END_ELLIPSIS cannot be used together with this parameter |
| DT_EXTERNALLEADING | Include the font's outer header in the line height (usually the outer header is not included in the body text line height) |
| DT_HIDEPREFIX | 1. Ignore the prefix character (&) in the text, and the letters after the prefix character will not be underlined, and the calling method of other prefix characters will not be affected. 2. For example: the input string is "F&is&&hC", and the normal display is "Fis&hC" , using DT_HIDEPREFIX to display as "Fis&hC" |
| DT_INTERNAL | Use system fonts to calculate text size |
| DT_LEFT | Align text left |
| DT_MODIFYSTRING | 1. Allow the system to modify the given string to match the displayed text 2. This flag must be used together with DT_END_ELLIPSIS or DT_PATH_ELLIPSIS |
| DT_NOCLIP | Drawing without clipping, using DT_NOCLIP can improve the efficiency of DrawText |
| DT_NOFULLWIDTHCHARBREAK | 1. Prevents line breaks in wide-character strings, so line breaking rules are equivalent to single-character strings 2. For example, we can use it in Korean versions of Windows to provide better readability for icon labels 3 . This value has no effect unless DT_WORDBREAK is specified |
| 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 类似） |
返回值：
-
如果函数调用成功，返回值是正文的高度（逻辑单位）；
-
如果指定了 DT_VCENTER 或 DT_BOTTOM，返回值是 lpRect -> top 到绘制的正文的底部的偏移值；
-
如果 函数调用失败，返回值是 0。
备注：
-
函数
DrawText用设备环境中的字体选择、正文颜色和背景颜色来写正文。 -
DrawText 裁剪正文，使之不会出现在指定矩形的外面，除非指定了
DT_NOCLIP。 -
除非使用
DT_SINGLELINE格式化，否则其余的格式都认为正文有多行。 -
如果选择的字体对指定的矩形而言太大，DrawText 并不会试图去换成一种小字体。
-
设备环境的正文对齐方式必须包括
TA_LEFT,TA_TOP和TA_NOUPDATECP标志。
TextOut与DrawText区别
TextOut
- 绘制简单（指 提供可选参数少）
- ？
- Gdi32.dll
DrawText
- 可以将文本字符串绘制到以逻辑坐标指定的矩形区域中
- 支持多行
- 支持字体多种设置，超出换行或者显示省略号
- User32.dll
后话
应用程序选择适当的字体后，设置所需的文本格式选项，并计算文本字符串所需的字符宽度和高度值，它可以通过调用任何文本输出函数开始绘制字符和符号：
当应用程序调用其中一个函数时，操作系统会将调用传递给图形引擎，从而将调用传递给相应的设备驱动程序。 在设备驱动程序级别，所有这些调用都受驱动程序自己的 ExtTextOut 或 TextOut 函数的一个或多个调用支持。 应用程序将通过调用 ExtTextOut 实现最快的执行，后者可快速转换为设备的 ExtTextOut 调用。 但是，当应用程序应调用其他三个函数之一时，存在一些实例：例如，若要在指定矩形区域的边框内绘制多行文本，调用 DrawText 更高效。 若要创建具有文本对齐列的多列，调用 TabbedTextOut 更高效。