Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

                                                     ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
DWORD ExtTextOut(lpDestDev, wDestXOrg, wDestYOrg, lpClipRect, lpString,
                 wCount, lpFontInfo, lpDrawMode, lpTextXForm, lpCharWidths,
                 lpOpaqueRect, wOptions)
LPPDEVICE lpDestDev;
WORD wDestXOrg;
WORD wDestYOrg;
LPRECT lpClipRect;
LPSZ lpString;
int wCount;
LPFONTINFO lpFontInfo;
LPDRAWMODE lpDrawMode;
LPTEXTXFORM lpTextXForm;
LPSHORT lpCharWidths;
LPRECT lpOpaqueRect;
WORD wOptions;
 
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.
 
Parameter     Description
────────────────────────────────────────────────────────────────────────────
 
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.
 
              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 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 specified by the lpDrawMode parameter, it
                        must restore the member to its original value.
 
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.
 
              Value            Meaning
              ──────────────────────────────────────────────────────────────
              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.
 
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, DRAWMODE, FONTINFO, RECT, TEXTXFORM
 
 
                                      ♦