DIB_ExtTextOut


DWORD DIB_ExtTextOut(LPPDEVICE lpDestDev, WORD wDestXOrg, 
    WORD wDestYOrg, LPRECT lpClipRect, LPSZ lpString, int wCount, 
    LPFONTINFO lpFontInfo, LPDRAWMODE lpDrawMode, 
    LPTEXTXFORM lpTextXForm, LPSHORT lpCharWidths, 
    LPRECT lpOpaqueRect, WORD wOptions);

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, DIB_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.

Value

Meaning

x- and y-extents of string's bounding rectangle

wCount was negative and the function succeeded. The x-extent is in the low-order 16 bits and the y-extent is in the high-order 16 bits.

x-extent is 0x7FFF and y-extent is wDestXOrg

wCount was negative; the function failed because the x-extent was too large.

TRUE

wCount was zero and the specified rectangle was filled with the background color.

TRUE

wCount was positive and the text was output successfully.

0x80000000L

An error occurred; no output was generated.


lpDestDev

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

wDestXOrg and wDestYOrg

The x- and y-coordinates (in device units) of the starting point for the string.

lpClipRect

Address of a RECT structure specifying the clipping rectangle.

lpString

Address of a null-terminated string specifying the characters to display.

wCount

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

Value

Meaning

Negative

Compute the x- and y-extents of the smallest rectangle that completely encloses the displayed string, but do not generate output. In this case, the absolute value of wCount specifies the number of characters in the string. The function uses the current font, text justification, and other factors to compute the bounding rectangle, but does not apply the clipping rectangle. The function must update the BreakErr member of the DRAWMODE structure specified by the lpDrawMode parameter.

0

Fill the rectangle specified by lpOpaqueRect but only if wOptions is ETO_OPAQUE. In this case, the function does not generate text output.

Positive

Draw the characters in the string. wCount specifies the number of characters to draw. The function uses the current font, text justification, escapement, rotation, and other factors to draw the characters, and it applies the clipping and opaque rectangles if specified. If the function modifies the BreakErr member of the DRAWMODE structure specified by the lpDrawMode parameter, it must restore the member to its original value.


lpFontInfo

Address of a FONTINFO structure specifying the physical font to use.

lpDrawMode

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

lpTextXForm

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

lpCharWidths

Address of 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

Address of a RECT structure specifying the opaquing rectangle. This parameter can be NULL.

wOptions

Action to carry out. It can be a combination of the following values.

ETO_OPAQUE (2)

Fills the rectangle specified by the lpOpaqueRect parameter (and clipped to the lpClipRect parameter) with the background color specified by the lpDrawMode parameter. The function fills the rectangle regardless of the whether lpDrawMode specifies opaque or transparent background mode.

ETO_CLIPPED (4)

Creates a new clipping rectangle by intersecting the rectangles specified by lpOpaqueRect and lpClipRect.

ETO_GLYPH_INDEX

For fonts in the format defined by the FONTINFO structure, if this flag is set, lpString points to a word array of glyph indexes into the character offset table. For fonts in the format defined by the FONTINFO structure, if this flag is clear, lpString points to a byte array and the index to the glyph in the character offset table must be computed by subtracting the index of the first character in the table. For fonts in the format defined by the NewFontSeg structure, if this flag is set, lpString points to a word array of glyph indexes into the character offset table. For fonts in the format defined by the NewFontSeg structure, if this flag is clear, lpString points to a byte array of glyph indexes into the character offset table.

ETO_BYTE_PACKED

Indicates the font is in the format defined by the NewFontSeg structure. The glyphs are byte-packed, meaning they are stored in rows where each row is padded out to a byte boundary.

ETO_BIT_PACKED

Indicates the font is in the format defined by the NewFontSeg structure. The glyphs are bit-packed, meaning they are stored in rows with no padding.

ETO_LEVEL_MODE

Indicates that the background mode specified in lpDrawMode ->bkMode is set to one of the blending levels used for anti-aliasing and is neither transparent or opaque.


The export ordinal for this function is 14.

See also DIB_ExtTextOutExt