ExtTextOut

The ExtTextOut function writes text strings by converting characters in a given string into raster, vector, or outline glyphs and copying the glyphs to the given device or bitmap. Depending on the value of its parameters, ExtTextOut also computes the x and y extents of the bounding rectangle of the displayed string, clips the text to fit a given clipping rectangle, fills a given rectangle with the specified background color before copying glyphs, and overrides the default spacing of the glyphs using values specified in an array of character widths. GDI may call ExtTextOut if an application calls the TextOut function (GDI.33), the ExtTextOut function (GDI.351), or GetTextExtent function (GDI.91).

A graphics driver must export the ExtTextOut function if the RC_GDI20_OUTPUT value is set in the dpRaster member of the driver's GDIINFO structure.

Parameters

lpDestDev

Points to a PDEVICE or PBITMAP structure specifying the device or bitmap to receive the text output.

wDestXOrg

Specifies the x-coordinate (in device units) of the starting point for the string.

wDestYOrg

Specifies the y-coordinate (in device units) of the starting point for the string.

lpClipRect

Points to a RECT structure specifying the clipping rectangle.

lpString

Points to a null-terminated character string specifying the characters to display.

wCount

Specifies which action to carry out. It can be one of the following values.

lpFontInfo

Points to a FONTINFO structure specifying the physical font to use.

lpDrawMode

Points to a DRAWMODE structure specifying the current text color, background mode, background color, text justification, and character spacing.

lpTextXForm

Points to a TEXTXFORM structure specifying additional information about the appearance of the characters when drawn.

lpCharWidths

Points to an array of character widths. If this parameter is not NULL, each element in the array is the advance width (in device units) of the corresponding character in the string. The function uses these widths (instead of the default character widths) to compute the position of the next character in the string. There must be one advance width for each character in the string.

lpOpaqueRect

Points to a RECT structure specifying the opaquing rectangle. This parameter can be NULL.

wOptions

Specifies which action to carry out. It can be a combination of the following values.

Return Value

If the wCount parameter is nonzero, this function returns the x and y extents of the string's bounding rectangle; the x extent is in the low-order 16 bits and the y extent in the high-order 16 bits. If the x extent exceeds the maximum value for an extent (0x7FFF), the function returns 0x7FFF in the low-order 16 bits and wDestXorg in the high-order 16 bits.

If wCount is zero, the return value is TRUE if the specified rectangle was filled with the background color. In all other cases, the return value is 0x80000000L if an error occurred or no output was generated.

Comments

The export ordinal for this function is 14.

ExtTextOut places the upper-left corner of the string at the point defined by the DestYOrg parameter. This means that the characters in the string appear below and to the right of the starting point. In some cases, character glyphs may overlap, especially if widths specified in lpCharWidths are less than the default widths or are negative.

ExtTextOut uses the drawing mode specified by lpDrawMode to determine the current text color, the background mode, and the background color. The background mode determines whether ExtTextOut draws an opaque bounding box before drawing the characters. The background color determines what color that box must be. The text color determines the color of the text in the box. For raster glyphs, all 1 bits must be the text color; for vector and outline glyphs, lines and filled areas must be the text color. ExtTextOut does not use the binary-raster operation mode (specified by the Rop2 member in the DRAWMODE structure pointed to by the lpDrawMode parameter) when drawing text.ExtTextOut clips text to the rectangle specified by lpClipRect, or to the intersection of lpClipRect and lpOpaqueRect if wOptions specifies ETO_CLIPPED. Only pixels within the rectangle are drawn. (Pixels that have the same x-coordinate as the rectangle's right edge, or the same y-coordinate as the rectangle's bottom edge are not in the rectangle.) For example, no pixels are drawn if the clipping rectangle is empty (zero width and height), and only one pixel is drawn if it has a width and height of 1.

ExtTextOut uses the lpTextXForm parameter only if the device supports the additional text transformation capabilities. For example, if lpTextXForm specifies a point size different from the one specified by lpFontInfo, ExtTextOut should ignore the lpTextXForm point size unless the function can size characters. Text transformation capabilities are specified in the dpText member of the driver's GDIINFO structure.

If the TBreakExtra or CharExtra members in the DRAWMODE structure pointed to by the lpDrawMode parameter is nonzero, ExtTextOut must adjust widths of break characters or other characters using the following or similar algorithm:

int width; /* width of character */

for (i=0; i<wCount; i++) {

/* Set width here using the default character for lpString[i]. */

/* The default width and how to retrieve it depends */

/* on the font. */

if ((lpDrawMode->TBreakExtra != 0) &&

(lpString[i]==lpFont->dfBreakChar)) {

width = width + lpDrawMode->BreakExtra;

lpDrawMode->BreakErr=lpDrawMode->BreakErr-lpDrawMode->BreakRem;

if (lpDrawMode->BreakErr <= 0) {

width = width ++

BreakErr = BreakErr + BreakCount

}

}

width = width + lpDrawMode->CharExtra;

}

See Also

StrBlt