Share via


CDC::ExtTextOut

Call this member function to write a character string within a rectangular region using the currently selected font.

virtual BOOL ExtTextOut( 
   int x, 
   int y, 
   UINT nOptions, 
   LPCRECT lpRect, 
   LPCTSTR lpszString, 
   UINT nCount, 
   LPINT lpDxWidths  
); 
BOOL ExtTextOut( 
   int x, 
   int y, 
   UINT nOptions, 
   LPCRECT lpRect, 
   const CString& str, 
   LPINT lpDxWidths  
);

Parameters

  • x
    Specifies the logical x-coordinate of the character cell for the first character in the specified string.

  • y
    Specifies the logical y-coordinate of the top of the character cell for the first character in the specified string.

  • nOptions
    Specifies the rectangle type. This parameter can be one, both, or neither of the following values:

    • ETO_CLIPPED   Specifies that text is clipped to the rectangle.

    • ETO_OPAQUE   Specifies that the current background color fills the rectangle. (You can set and query the current background color with the SetBkColor and GetBkColor member functions.)

  • lpRect
    Points to a RECT structure that determines the dimensions of the rectangle. This parameter can be NULL. You can also pass a CRect object for this parameter.

  • lpszString
    Points to the specified character string to be drawn. You can also pass a CString object for this parameter.

  • nCount
    Specifies the number of characters in the string.

  • lpDxWidths
    Points to an array of values that indicate the distance between origins of adjacent character cells. For instance, lpDxWidths[i] logical units will separate the origins of character cell i and character cell i + 1. If lpDxWidths is NULL, ExtTextOut uses the default spacing between characters.

  • str
    A CString object that contains the specified characters to be drawn.

Return Value

Nonzero if the function is successful; otherwise 0.

Remarks

The rectangular region can be opaque (filled with the current background color), and it can be a clipping region.

If nOptions is 0 and lpRect is NULL, the function writes text to the device context without using a rectangular region. By default, the current position is not used or updated by the function. If an application needs to update the current position when it calls ExtTextOut, the application can call the CDC member function SetTextAlign with nFlags set to TA_UPDATECP. When this flag is set, Windows ignores x and y on subsequent calls to ExtTextOut and uses the current position instead. When an application uses TA_UPDATECP to update the current position, ExtTextOut sets the current position either to the end of the previous line of text or to the position specified by the last element of the array pointed to by lpDxWidths, whichever is greater.

Requirements

Header: afxwin.h

See Also

Reference

CDC Class

Hierarchy Chart

CDC::SetTextAlign

CDC::TabbedTextOut

CDC::TextOut

CDC::GetBkColor

CDC::SetBkColor

CDC::SetTextColor

ExtTextOut

RECT Structure