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:

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:

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