WinDrawText

This function draws a single line of formatted text into a specified rectangle.

Syntax

 WinDrawText(hps, cchText, lpchText, prcl, clrFore, clrBack, flCmd)

Parameters

hps (HPS) - Input

Presentation-space handle.

cchText (LONG) - Input

Count of the number of characters in the string.

This parameter must be greater than 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 always 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.

Template:Hp2

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 Template:Hp2 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 &osq.external leading&osq. 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 &osq.GpiSetAttrs&osq. and &osq.GpiSetBackMix&osq. 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.

0

Error occurred

Other

Count of characters drawn within the rectangle.

Returns

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.

0

Error occurred

Other

Count of characters drawn within the rectangle.

Remarks

Text is always drawn in the current font with the current foreground and background mix modes. This function must only be used in draw mode (DM_DRAW), to a screen device context; hps can be either a micro presentation space or a normal presentation space (see &osq.GpiCreatePS&osq. in the Graphics Programming Interface Programming Reference).

Errors

Possible returns from WinGetLastError:

• PMERR_INVALID_FLAG (0x1019)

An invalid bit was set for a parameter. Use constants defined by PM for options, and do not set any reserved bits.

Example Code

#define INCL_WINWINDOWMGR /* Or use INCL_WIN, INCL_PM, */
#include <os2.h>

HPS       hps;     /*  Presentation-space handle. */
LONG      cchText; /*  Count of the number of characters in the string. */
PCH       lpchText; /*  Character string to be drawn. */
PRECTL    prcl;    /*  Text rectangle. */
LONG      clrFore; /*  Foreground color. */
LONG      clrBack; /*  Background color. */
ULONG     flCmd;   /*  An array of flags that determines how the text is drawn. */
LONG      lChars;  /*  Count of characters drawn within the rectangle. */

lChars = WinDrawText(hps, cchText, lpchText,
           prcl, clrFore, clrBack, flCmd);

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 is 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 hTotalDrawn variable to provide an offset into the string for the next call to WinDrawText.

#define INCL_WINWINDOWMGR       /* Window Manager Functions     */
#include <os2.h>

HWND    hwnd;           /* parent window                        */
RECTL  rcl;             /* update region                        */
HPS    hps;             /* presentation-space handle            */
char   *pszText;        /* string                               */
LONG   hText;          /* length of string                     */
LONG  cyCharHeight;     /* set character height                 */
LONG   hTotalDrawn;    /* total characters drawn               */
LONG   hDrawn;         /* characters drawn by WinDrawText      */
LONG   cchText;
LONG   cchTotalDrawn;
LONG   cchDrawn;

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 =  (LONG)strlen(pszText);       /* get length of string  */
cyCharHeight = 15L;                     /* set character height  */

/* until all chars drawn */
for (cchTotalDrawn = 0;  hTotalDrawn !=  hText;
                        rcl.yTop -= cyCharHeight)
   {
   /* draw the text */

    hDrawn = WinDrawText(hps,     /* presentation-space handle */
        hText -  hTotalDrawn,    /* length of text to draw    */
       pszText +  hTotalDrawn,    /* 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)
        hTotalDrawn +=  hDrawn;
   else
       break;                      /* text could not be drawn   */
   }

WinReleasePS(hps);                  /* release the ps            */

Related Functions

• WinDrawBitmap
• WinDrawBorder
• WinDrawPointer
• WinFillRect
• WinGetSysBitmap
• WinInvertRect
• WinQueryPresParam
• WinRemovePresParam
• WinScrollWindow
• WinSetPresParam