win12.hlp (Table of Contents; Topic list)
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.
WinDrawText (1.2)
Function Group  Overview                          Up Next Previous
────────────────────────────────────────────────────────────────────────────
 
#define INCL_WINMESSAGEMGR
 
SHORT WinDrawText(hps, cchText, pszText, pcrl, clrFore, clrBack, fsCmd)
HPS hps;          /* handle of the presentation space                */
SHORT cchText;    /* number of characters in the string              */
PSZ pszText;      /* address of the text                             */
PRECTL prcl;      /* address of structure with formatting dimensions */
LONG clrFore;     /* color of the foreground                         */
LONG clrBack;     /* color of the background                         */
USHORT fsCmd;     /* text-drawing flags                              */
 
The WinDrawText function draws a single line of formatted text into a
specified rectangle.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies the presentation space in which to draw the text.
 
cchText    Specifies the number of characters in the string to draw. If this
           is set to 0xFFFF, the string is assumed to be null-terminated and
           its length is calculated by the function itself.
 
pszText    Points to the character string to draw. A carriage-return or
           linefeed character terminates the line, even if the line is
           shorter than specified by the cchText parameter.
 
prcl       Points to a RECTL data structure that contains the rectangle in
           which the text is formatted. If DT_QUERYEXTENT is specified in
           the fsCmd parameter, the RECTL structure is set to the string's
           bounding rectangle upon return from WinDrawText.
 
clrFore    Specifies the color of the foreground. This parameter is ignored
           if DT_TEXTATTRS is set in the fsCmd parameter.
 
clrBack    Specifies the color of the background. This parameter is ignored
           if DT_TEXTATTRS is set in the fsCmd parameter.
 
fsCmd      Specifies an array of flags that determine how the text is drawn.
           It can be any of the following values:
 
           Value               Meaning
           ─────────────────────────────────────────────────────────────────
           DT_LEFT             Left justify the text.
 
           DT_RIGHT            Right justify the text.
 
           DT_TOP              Top justify the text.
 
           DT_BOTTOM           Bottom justify the text.
 
           DT_CENTER           Center the text.
 
           DT_VCENTER          Center the text vertically.
 
           DT_ERASERECT        This flag causes the RECTL structure
                               specified in prcl to be filled with the
                               window color before printing the text, but
                               only if the DT_QUERYEXTENT flag is not
                               specified.
 
           DT_EXTERNALLEADING  This flag causes the external leading value
                               from the passed font to be added to the
                               bottom of the bounding rectangle before
                               returning. It only has an effect when both
                               DT_TOP and DT_QUERYEXTENT are also
                               specified.
 
           DT_HALFTONE         Make the text display halftone.
 
           DT_MNEMONIC         If a mnemonic prefix character is
                               encountered, draw the next character with
                               mnemonic emphasis.
 
           DT_QUERYEXTENT      No drawing is performed. The prcl parameter
                               is changed to a rectangle that bounds the
                               string if it was drawn with the WinDrawText
                               function.
 
           DT_TEXTATTRS        This flag causes the colors specified in
                               clrFore and clrBack to be ignored. The colors
                               already selected in the presentation space
                               are used instead.
 
           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 linefeed character. When calculating
                               whether a particular word will fit within the
                               given rectangle, WinDrawText does not
                               consider the trailing blanks. It tests only
                               the length of the visible part of the word
                               against the right edge of the rectangle. Note
                               that WinDrawText will always try 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
                               multi-line text.
 
           Some of the DT flags are mutually exclusive. Only one flag from
           each of the following groups is significant:
 
           ♦  DT_LEFT, DT_CENTER, DT_RIGHT
 
           ♦  DT_TOP, DT_VCENTER, DT_BOTTOM
 
Return Value
 
The return value is the number of characters, drawn by the function, that
fit completely within the structure pointed to by prcl.
 
Example
 
This example shows how the WinDrawText function can be used to wrap text
within a window by using the DT_WORDBREAK flag. The cchDrawn variable
receives the number of characters actually drawn by the WinDrawText
function. If this value is zero, no text was drawn and the for loop is
exited. This can occur if the vertical height of the window is too short for
the entire text. Otherwise, cchDrawn is added to the cchTotalDrawn variable
to provide an offset into the string for the next call to WinDrawText.
 
hps = WinGetPS(hwnd);          /* get a ps for the entire window */
WinQueryWindowRect(hwnd, &rcl);         /* get window dimensions */
WinFillRect(hps, &rcl, CLR_WHITE);      /* clear entire window   */
cchText = strlen(pszText);              /* get length of string  */
cyCharHeight = 15L;                     /* set character height  */
for (cchTotalDrawn = 0;
        cchTotalDrawn != cchText;       /* until all chars drawn */
        rcl.yTop -= cyCharHeight) {
 
    /* draw the text */
 
    cchDrawn = WinDrawText(hps,     /* presentation-space handle */
        cch - cchTotalDrawn,        /* length of text to draw    */
        pszText + cchTotalDrawn,    /* address of the text       */
        &rcl,                       /* rectangle to draw in      */
        0L,                         /* foreground color          */
        0L,                         /* background color          */
        DT_WORDBREAK | DT_TOP | DT_LEFT | DT_TEXTATTRS);
    if (cchDrawn)
        cchTotalDrawn += cchDrawn;
    else
        break;                      /* text could not be drawn   */
}
WinReleasePS(hps);                  /* release the ps            */
 
See Also
 
WinSetDlgItemText, RECTL