ExtTextOut

2.x

BOOL ExtTextOut(hdc, nXStart, nYStart, fuOptions, lprc, lpszString, cbString, lpDx)
HDC hdc;	/* handle of device context	*/
int nXStart;	/* x-coordinate of starting position	*/
int nYStart;	/* y-coordinate of starting position	*/
UINT fuOptions;	/* rectangle type, */
const RECT FAR* lprc;	/* address of structure with rectangle	*/
LPCSTR lpszString;	/* address of string	*/
UINT cbString;	/* number of bytes in string	*/
int FAR* lpDx;	/* spacing between character cells	*/

The ExtTextOut function writes a character string within a rectangular region, using the currently selected font. The rectangular region can be opaque (filled by using the current background color as set by the SetBkColor function), and it can be a clipping region.

Parameters

hdc

Identifies the device context.

nXStart

Specifies the logical x-coordinate at which the string begins.

nYStart

Specifies the logical y-coordinate at which the string begins.

fuOptions

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

Value

Meaning

ETO_CLIPPED	Text is clipped to the rectangle.
ETO_OPAQUE	Current background color fills the rectangle. (An application can set and query the current background color by using the SetBkColor and GetBkColor functions.)

lprc

Points to a RECT structure that determines the dimensions of the rectangle. The RECT structure has the following form:

typedef struct tagRECT {    /* rc */
   int left;
   int top;
   int right;
   int bottom;
} RECT;

For a full description of this structure, see the Microsoft Windows Programmer's Reference, Volume 3.

lpszString

Points to the specified character string.

cbString

Specifies the number of bytes in the string.

lpDx

Points to an array of values that indicate the distance, in logical units, between origins of adjacent character cells. The nth element in the array specifies the number of logical units that separate the origin of the nth item in the string from the origin of item n + 1. If this parameter is NULL, ExtTextOut uses the default spacing between characters. Otherwise, the array contains the number of elements specified in the cbString parameter.

Return Value

The return value is nonzero if the function is successful. Otherwise, it is zero.

Comments

If the fuOptions parameter is zero and the lprc parameter is NULL, the ExtTextOut function writes text to the device context without using a rectangular region.

By default, the current position is not used or updated by ExtTextOut. If an application needs to update the current position when it calls ExtTextOut, the application can call the SetTextAlign function with the wFlags parameter set to TA_UPDATECP. When this flag is set, Windows ignores the nXStart and nYStart parameters on subsequent calls to ExtTextOut, using 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 the lpDX parameter, whichever is greater.

Example

The following example uses the ExtTextOut function to clip text to a rectangular region defined by a RECT structure:

RECT rc;

SetRect(&rc, 90, 190, 250, 220);

ExtTextOut(hdc, 100, 200,    /* x and y coordinates       */
    ETO_CLIPPED,             /* clips text to rectangle   */
    &rc,                     /* address of RECT structure */
    "Test of ExtTextOut function.", /* string to write    */
    28,                      /* characters in string      */
    (LPINT) NULL);           /* default character spacing */

ExtTextOut

2.x

Parameters

Return Value

Comments

Example

See Also