Partager via

Gdi::DrawTextW_I

  • Article

This method draws formatted text in the specified rectangle, formatting the text according to the specified format method.

static WINUSERAPI int WINAPI DrawTextW_I(
  HDC hDC,
  const WCHAR* lpString,
  int nCount,
  RECT* lpRect,
  unsigned int 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, the string must be null-terminated.
  • nCount
    [in] Integer that specifies the number of characters in the string. If nCount is –1, the lpString parameter is assumed to be a pointer to a null-terminated string and Gdi::DrawTextW_I computes the character count automatically.
  • lpRect
    [in] Long pointer to a RECT structure that contains the rectangle, in logical coordinates, in which the text is to be formatted.
  • uFormat
    [in] Unsigned integer that specifies the method of formatting the text. The following table shows the possible values.
    Value Description
    DT_BOTTOM Justifies the 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. For multiple lines of text, Gdi::DrawTextW_I uses the width of the rectangle pointed to by the lpRect parameter and extends the base of the rectangle to bound the last line of text. For only one line of text, Gdi::DrawTextW_I modifies the right side of the rectangle so that the rectangle bounds the last character in the line. In either case, Gdi::DrawTextW_I returns the height of the formatted text but does not draw the text.

    Before calling Gdi::DrawTextW_I, an application must set the right and bottom members of the RECT structure pointed to by lpRect. The call to Gdi::DrawTextW_I updates these members.
    DT_CENTER Centers text horizontally in the rectangle.
    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. Gdi::DrawTextW_I is somewhat faster when DT_NOCLIP is used.
    DT_NOPREFIX Turns off processing of prefix characters. Typically, Gdi::DrawTextW_I interprets the mnemonic-prefix character & as a directive to underscore the character that follows, and the mnemonic-prefix characters && as a directive to print a single &. By specifying DT_NOPREFIX, an application turns off this processing.
    DT_RIGHT Aligns text to the 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 15–8, which make up the high-order byte of the low-order word, of the uFormat parameter specify the number of characters for each tab. The default number of characters per tab is eight. You cannot use the DT_CALCRECT, DT_EXTERNALLEADING, DT_INTERNAL, DT_NOCLIP, and DT_NOPREFIX values with the DT_TABSTOP value.
    DT_TOP Top-justifies text. You must combine this value with DT_SINGLELINE.
    DT_VCENTER Centers text vertically. You must combine this value with DT_SINGLELINE.
    DT_WORDBREAK Breaks words. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by the lpRect parameter. A carriage return-linefeed sequence also breaks the line.

Return Values

The height of the text indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

This method is an internal version of the DrawText function.

The Gdi::DrawTextW_I method uses the selected font, text color, and background color for the device context to draw the text. Unless an application uses the DT_NOCLIP format, Gdi::DrawTextW_I clips the text so that the text does not appear outside the specified rectangle. All formatting is assumed to have multiple lines unless the application specifies the DT_SINGLELINE format.

If the selected font is too large for the specified rectangle, Gdi::DrawTextW_I does not attempt to substitute a smaller font.

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

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Gdi.hpp.

See Also

DrawText | Gdi::ExtTextOutW_I | RECT

Last updated on Wednesday, April 13, 2005

© 2005 Microsoft Corporation. All rights reserved.