ExtTextOut

DWORD 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.

• If the wCount parameter is negative, 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. If wCount is positive, the return value is TRUE if the text was output successfully. In all other cases, the return value is 0x80000000L if an error occurred or no output was generated.

lpDestDev

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

wDestXOrg and wDestYOrg

Coordinates, in device units, of the starting point for the string.

lpClipRect

Address of a RECT structure that specifies the clipping rectangle.

lpString

Address of a null-terminated character string that specifies the characters to display.

wCount

Action to carry out. Can be one of these values:

<0	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 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.
>0	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 specified by the lpDrawMode parameter, it must restore the member to its original value.

lpFontInfo

Address of a structure that specifies the physical font to use. If either the ETO_BYTE_PACKED or ETO_BIT_PACKED wOptions flag is set, lpFontInfo points to a NewFontSeg structure. Otherwise, lpFontInfo points to a FONTINFO structure. A display driver indicates that it is capable of handling the NewFontSeg format as well as the FONTINFO format by setting the C1_BYTE_PACKED or C1_BIT_PACKED bit in dpCaps1 of the GDIINFO structure at enable time.

lpDrawMode

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

lpTextXForm

Address of a TEXTXFORM structure that specifies 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 that specifies the opaquing rectangle. This parameter can be NULL.

wOptions

Action to carry out. Can be a combination of these 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.

If neither ETO_BYTE_PACKED or ETO_BIT_PACKED is set, the font is in the format defined by the FONTINFO structure.

The export ordinal for this function is 14.

Depending on the value of its parameters, the ExtTextOut function 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, the ExtTextOut function, or GetTextExtent function.

A graphics driver must export the ExtTextOut function.

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

DRAWMODE, FONTINFO, PDEVICE, PBITMAP, TEXTXFORM, RECT