WinAPI : DrawText & DrawTextEx

My last post on the WinAPI series was WinAPI : Displaying Text. Let’s get ahead with more WinAPI functions starting with DrawText and DrawTextEx functions.

Public Declare Function DrawText Lib "user32" Alias "DrawTextA" ( _
	ByVal hdc As Long, ByVal lpStr As String, ByVal nCount As Long, _
	lpRect As RECT, ByVal wFormat As Long) As Long

Public Type RECT
        Left As Long
        Top As Long
        Right As Long
        Bottom As Long
End Type

While the TextOut function required you to specify only the top-left co-ordinates to write out the text, DrawText requires you to specify the rectangular area where you need to draw and also expects you to specify formatting options as to how text should be aligned or so within the rectangle. The first parameter is takes is the handle to the input context, second the string that you need to print out, next the number of characters from the string to be printed out. The next two parameters are the pointer to the RECT structure and the formatting option (which may be one or more of constants defined below) respectively.

Const DT_LEFT = &H0
Const DT_TOP = &H0
Const DT_CENTER = &H1
Const DT_RIGHT = &H2
Const DT_VCENTER = &H4
Const DT_BOTTOM = &H8

The above constants may be used for vertical/horizontal alignment of the text (default Top-Left). Vertical alignment can be modified only in case of SingleLines (as defined below).

Const DT_WORDBREAK = &H10

Using the constant above ensures that line is automatically broken between words. In absence of this constant the line would break only when encounter carriage return and line feed sequence, and all words that moved out of rectangular area being clipped.

Const DT_SINGLELINE = &H20

Using constant above makes the text to display in a single line. Even the carriage return line feed sequence are not considered for moving to next line.

Const DT_EXPANDTABS = &H40
Const DT_TABSTOP = &H80

DT_EXPANDTABS causes Tab characters to be shown as a sequence of eight (default) space characters. This default value can be modified using constant DT_TABSTOP (am unsure of how? Inputs welcome)

Const DT_NOCLIP = &H100

Constant above ensures that the words are not clipped if they extend beyond the rectangle defined.

Const DT_EXTERNALLEADING = &H200

Leading is the vertical space that separates the two lines. Normally the leading as defined in the font is not considered for drawing the text by the function. Including the constant as above it to be included in drawing the text.

Const DT_CALCRECT = &H400

The above constant can be used to calculate the optimum size of the rectangle that would be required to print out the text. Using this constant doesnot cause the text to be printed but instead modifies the RECT structure passed to the function appropriately.

Const DT_NOPREFIX = &H800
Const DT_HIDEPREFIX = &H100000	'WinXP onwards
Const DT_PREFIXONLY = &H200000	'WinXP onwards

By default the DrawText function considers presence of and ampersand (’&’) as a directive to underline the character that follows, while ‘&’ itself is not drawn. In order to display ‘&’ you need to give ‘& &’. Using the constant as above turns off this nature and draws ‘&’ as it is. The other two constants that were included in WindowsXP. DT_HIDEPREFIX instructs the function to refrain from showing any underlined characters so existence of an ‘&’ which otherwise would have shown character following it as underlined (or shown itself as it is if DT_NOPREFIX used) will neither show the ‘&’ noor the underlining of the next character. DT_PREFIXONLY causes the function to display nothing other than the Underline itself (at location where the character that it underlined would have appeared.

Const DT_INTERNAL = &H1000

“Uses the system font to calculate text metrics.” (as described in MSDN, unsure of what it actually meant)

Const DT_EDITCONTROL = &H2000

Normally for a multiline text if the rectangle is not large enough to accommodate all text a few lines moving outside the rectangle are clipped and the clipping is done without checking in case a line at the bottom is partially visible. Using this constant ensures that such partially visible lines are not shown at all.

Const DT_END_ELLIPSIS = &H8000
Const DT_WORD_ELLIPSIS = &H40000
Const DT_PATH_ELLIPSIS = &H4000

The above three constants are useful if the string is large enough to fit into the rectangle, where it truncates the string adding ellipses ‘…’ (at the end for the first two and in-between for the last). The three constants vary in the manner the addition of ellipses is done. For DT_END_ELLIPSIS it truncates all complete words that move out of rectangle area and adds the ellipses at the end. In this case the ellipses may not always be visible as the last word after which the ellipses occur may itself be clipped by the bounding rectangle. DT_END_ELLIPSIS ensures that the ellipses are visible even if the last word itself needs to be partially-truncated for achieving the same. DT_PATH_ELLIPSIS is useful for showing the strings containing file paths (You may find this being applied in a Anti-Virus or similar software), where it is ensured that most of the filename is kept intact and the ellipses is added in midst of the string to hide part of the folder structure.

Const DT_MODIFYSTRING = &H10000

The above constant ensures that the string itself is modified to match it with that visible within the rectangle.

Const DT_RTLREADING = &H20000

Useful for rendering bi-directional text in Arabic and Hebrew fonts.

Const DT_NOFULLWIDTHCHARBREAK = &H80000

For Win98 onwards. Ensures that line break does not occur between Double Byte Character String (DBCS).

DrawTextEx function adds one for input parameter which is a pointer to the DRAWTEXTPARAMS structure defined below allowing you to configure the Character length for a Tab, Right and Left Margin that should be left while drawing within the rectangle. All other details remain the same as with DrawText function.

Public Declare Function DrawTextEx Lib "user32" Alias "DrawTextExA" ( _
	ByVal hdc As Long, ByVal lpStr As String, ByVal nCount As Long, _
	lpRect As RECT, ByVal wFormat As Long, _
	lpDrawTextParams As DRAWTEXTPARAMS) As Long

Public Type DRAWTEXTPARAMS
	cbSize As Long
	iTabLength As Long
	iLeftMargin As Long
	iRightMargin As Long
	uiLengthDrawn As Long
End Type