DrawText (Compact 2013)

  • Article

3/28/2014

This function draws text in the specified rectangle and formats it according to the methods you specify.

Syntax

int DrawText(
  HDC hDC, 
  LPCTSTR lpString, 
  int nCount, 
  LPRECT lpRect, 
  UNIT uFormat
);

Parameters

  • hDC
    [in] Handle to the device context.
  • lpString
    [in] Long pointer to the string that you want to draw. If the nCount parameter is -1, you must specify a null-terminated string.
  • nCount
    [in] Integer that specifies the number of characters in the string. If nCount is -1, DrawText assumes that the lpString parameter is a pointer to a null-terminated string and computes the character count automatically.
  • lpRect
    [in] Long pointer to a RECT structure that contains the rectangle, in logical coordinates, in which you want to format the text.

  • uFormat
    [in] Unsigned integer that specifies the method used to format the text. The following table shows the possible values that you can combine to create a value for this parameter.

    Value

    Description

    DT_BOTTOM

    Aligns text to the bottom of the rectangle. You must combine this value with DT_SINGLELINE.

    DT_CALCRECT

    Determines the width and height of the rectangle. If the rectangle includes multiple lines of text, DrawText uses the width of the rectangle pointed to by the lpRect parameter and extends the base of the rectangle vertically to bound the last line of text. If the rectangle includes only one line of text, DrawText extends the right side of the rectangle to bound the last character in the line. In either case, DrawText returns the height of the formatted text but does not draw the text.

    You must set the right and bottom members of the RECT structure pointed to by lpRect before you call DrawText. These members are updated with the call to DrawText.

    DT_CENTER

    Centers text horizontally in the rectangle.

    DT_END_ELLIPSIS

    Truncates a text string that is wider than the display rectangle and adds an ellipsis.

    DT_EXPANDTABS

    Expands tab characters. The default number of characters per tab is eight.

    DT_INTERNAL

    Uses the system font to calculate text metrics.

    DT_LEFT

    Aligns text to the left.

    DT_NOCLIP

    Draws without clipping. DrawText is somewhat faster when DT_NOCLIP is used.

    DT_NOPREFIX

    Turns off processing of prefix characters.

    DT_RIGHT

    Aligns text to the right.

    DT_RTLREADING

    Lays out text in right-to-left reading order for bi-directional text when the font selected in the hDC handle is a Hebrew or Arabic font. The default reading order for all text is left-to-right.

    DT_SINGLELINE

    Displays text on a single line only. Carriage returns and linefeeds do not break the line.

    DT_TABSTOP

    Sets tab stops. Bits 8-15 of the uFormat parameter specify the number of characters for each tab. These bits form the high-order byte of the low-order word. The default number of characters per tab is eight. You cannot use the DT_CALCRECT, DT_EXTERNALLEADING, DT_INTERNAL, DT_NOCLIP, or DT_NOPREFIX values with the DT_TABSTOP value.

    DT_TOP

    Aligns text to the top of the rectangle. You must combine this value with DT_SINGLELINE.

    DT_VCENTER

    Centers text vertically. You must combine this value with DT_SINGLELINE.

    DT_WORD_ELLIPSIS

    Truncates any word that does not fit in the display rectangle and adds an ellipsis.

    DT_WORDBREAK

    Breaks lines between words.

Return Value

Returns an integer that indicates the height of the text to indicate success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The DrawText function uses the selected font, text color, and background color for the device context to draw the text. If the selected font is too large for the specified rectangle, the DrawText function does not attempt to substitute a smaller font.

Unless you specify the DT_NOCLIP value, DrawText clips the text so that it does not appear outside the specified rectangle. DrawText assumes that all formatting has multiple lines unless you specify the DT_SINGLELINE format. DrawText automatically breaks lines between words if a word would extend past the edge of the rectangle specified by the lpRect parameter. You can also add line breaks by using a carriage return-linefeed sequence.

Line breaking is supported for the Chinese, Korean, and Japanese languages.

Unless you specify DT_NOPREFIX, DrawText interprets the mnemonic-prefix character ampersand (&) as an indication to underscore the character that follows and interprets the mnemonic-prefix characters && as an indication to print a single &.

Requirements

Header

windows.h

Library

coredll.lib

See Also

Reference

Fonts Functions
ExtTextOut
RECT