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.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_GPIPRIMITIVES
 
LONG GpiCharStringPos(hps, prcl, flOptions, cchString, pchString, adx)
HPS hps;            /* presentation-space handle                      */
PRECTL prcl;        /* address of structure for rectangle coordinates */
ULONG flOptions;    /* formatting flags                               */
LONG cchString;     /* number of characters in string                 */
PCH pchString;      /* address of string to draw                      */
PLONG adx;          /* address of array of increment values           */
 
The GpiCharStringPos function draws a character string starting at the
current position and using one or more formatting options. The options
direct the function to draw a background for the string, clip the string to
the given rectangle, or position the characters in the string using
distances given in an array. After drawing the string, the function either
leaves the current position at the end of the string or resets it to the
beginning of the string.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies the presentation space.
 
prcl       Points to a RECTL structure that contains the lower-left and
           upper-right corners of a rectangle. The function draws the
           rectangle if the CHS_OPAQUE option is given. It uses the
           rectangle to clip the string if the CHS_CLIP option is given.
           Otherwise the rectangle is ignored.
 
flOptions  Specifies the formatting options. It can be one or more of the
           following values:
 
           Value         Meaning
           ─────────────────────────────────────────────────────────────────
           CHS_CLIP      Clips the string to the rectangle, omitting any
                         portion of any character outside the rectangle. The
                         function clips the string regardless of whether
                         CHS_OPAQUE is specified.
 
           CHS_LEAVEPOS  Resets the current position back to the start of
                         the string. If not given, GpiCharStringPos moves
                         the current position to the end of string.
 
           CHS_OPAQUE    Draws the rectangle whose lower-left and
                         upper-right corners are specified by prcl, then
                         fills the rectangle with the current background
                         color. The string is drawn after filling the
                         rectangle.
 
           CHS_VECTOR    Advances the current position after each character
                         is drawn by using the next value in the array adx.
                         The current character direction defines which
                         direction the current position is advanced.
 
           All other values are reserved.
 
cchString  Specifies the number of characters in the string pointed to by
           pchString.
 
pchString  Points to the character string to be drawn.
 
adx        Points to an array of increment values. Each value is a 4-byte,
           signed integer specifying the distance in world coordinates to
           advance the current position after drawing a character. There
           must be one value for each character in the string. The first
           element specifies the distance to advance after drawing the first
           character, the second element specifies the distance after the
           second character, and so on.
 
Return Value
 
The return value is GPI_OK or GPI_HITS if the function is successful (it is
GPI_HITS if the detectable attribute is set for the presentation space and a
correlation hit occurs). The return value is GPI_ERROR if an error occurs.
 
Errors
 
Use the WinGetLastError function to retrieve the error value, which may be
one of the following:
 
     PMERR_FONT_AND_MODE_MISMATCH
     PMERR_INV_CHAR_POS_OPTIONS
     PMERR_INV_COORDINATE
     PMERR_INV_HPS
     PMERR_INV_RECT
     PMERR_PS_BUSY
 
Comments
 
If CHS_OPAQUE is specified and the drawing mode is DM_RETAIN,
GpiCharStringPos uses the color mix mode BM_OVERPAINT to fill the rectangle.
In other drawing modes, the function uses the BM_LEAVEALONE.
GpiCharStringPos draws the rectangle using the coordinates specified in
prcl. It does not use the start of the string to compute the rectangle's
location.
 
See Also
 
GpiCharString, GpiCharStringAt, GpiCharStringPosAt, RECTL
 
                                      ♦