WinDrawText - Parameters

hps (HPS) - input

Presentation-space handle.

cchText (LONG) - input

Count of the number of characters in the string.

This parameter must be greater or equal to -1L.

• 1L
  The string is null-terminated and its length is to be calculated by this function.
  Other
  Count of the number of characters in the string.

  lpchText (PCH) - input

  Character string to be drawn.

  A carriage-return or line-feed character allways terminates a line. If the length of a line is less than cchText(the string is divided into more than one line) each line is terminated by either of the mentioned characters.

  prcl (PRECTL) - in/out

  Text rectangle.

  Rectangle within which the text is to be formatted, in world coordinates. Points on the boundary of this rectangle are deemed to be inside the rectangle.

  On input, this rectangle is the desired rectangle in which the text is to be drawn.

  On output, the height of the rectangle is modified to the actual size needed to draw the given text string. The return value is only of interest in the instance where DT_QUERYEXTENT is set in flCmd.

  Note: The value of each field in this structure must be in the range -32 768 through 32 767. The data type WRECT can also be used, if supported by the language.

  clrFore (LONG) - input

  Foreground color.

  Ignored if DT_TEXTATTRS is specified.

  clrBack (LONG) - input

  Background color.

  The background is drawn with the current background mix. The default is BM_LEAVEALONE, that is, clrBack is ignored unless GpiSetBackMix is called.

  The background rectangle is the rectangle that bounds the text; it is not the input parameter rectangle.

  This parameter is ignored if DT_TEXTATTRS is specified.

  flCmd (ULONG) - input

  An array of flags that determines how the text is drawn.

  Some of the DT_ flags are mutually exclusive. Only one from each of these groups is significant:

  • DT_LEFT (default), DT_CENTER, DT_RIGHT 
    DT_TOP (default), DT_VCENTER, DT_BOTTOM.
    When mutually-exclusive flags are used together, the function gives indeterminate results.

    If DT_HALFTONE, DT_ERASERECT, or DT_MNEMONIC is used, the presentation space must be in PU_PELS units.

    DT_LEFT

    Left-justify the text.
    DT_CENTER
    Center the text.
    DT_RIGHT
    Right-justify the text.
    DT_VCENTER
    Vertically center the text.
    DT_TOP
    Top-justify the text.
    DT_BOTTOM
    Bottom-justify the text.
    DT_HALFTONE
    Halftone the text display.
    DT_MNEMONIC
    If a mnemonic prefix character is encountered, the next character is drawn with mnemonic emphasis.
    DT_QUERYEXTENT
    The height prcl is changed to a rectangle that bounds the string if it were drawn with WinDrawText.
    DT_WORDBREAK
    Only words that fit completely within the supplied rectangle are drawn. A word is defined as:

    Any number of leading spaces followed by one or more visible characters and terminated by a space, carriage return, or line-feed character.

    When calculating whether a particular word fits within the given rectangle, this function does not consider the trailing blanks. Only the length of the visible part of the word is tested against the right edge of the rectangle.

    Also, note that this function always tries to draw at least one word, even if that word does not fit in the passed rectangle. This is so that progress is always made when drawing multiline text.

    DT_EXTERNALLEADING
    This flag causes the "external leading" value for the current font to be added to the bottom of the bounding rectangle before returning. It has an effect only when both DT_TOP and DT_QUERYEXTENT are also specified.
    DT_TEXTATTRS
    If this is specified, text is drawn using the character foreground and background colors of the presentation space, and clrFore and clrBack are ignored.
    DT_ERASERECT
    If this is specified, the rectangle defined by prcl is erased before drawing the text. Otherwise, the background of the characters themselves can be erased if the character background mix ( see "GpiSetAttrs" and "GpiSetBackMix" in the Graphics Programming Interface Programming Reference) is set to BM_OVERPAINT.
    DT_UNDERSCORE
    Underscore the characters. See FATTR_SEL_UNDERSCORE in the FATTRS datatype.
    DT_STRIKEOUT
    Overstrike the characters. See FATTR_SEL_STRIKEOUT in the FATTRS datatype.

    lChars (LONG) - returns

    Count of characters drawn within the rectangle.

    If DT_WORDBREAK is specified, this parameter returns the number of characters displayed. However, if the first word of the string does not fit in the rectangle, this parameter reflects the fact that the entire word is drawn.

    If DT_WORDBREAK is not specified, the count returned is the full length of the string regardless of how much fits into the bounding rectangle.

    • Error occurred Other
      Count of characters drawn within the rectangle.

      ---

      [Back: WinDrawText Return Value - lChars]
      [Next: WinDrawText - Remarks]