GpiCharStringPos

This function draws a character string starting at the current position, with formatting options.

Syntax

GpiCharStringPos(hps, prclRect, flOptions, lCount, pchString, alAdx)

Parameters

hps (HPS) - input: Presentation-space handle.

prclRect (PRECTL) - input: Rectangle structure.; Defines, in world coordinates, the two corners of the rectangle that defines the background of the characters. It is ignored unless CHS_OPAQUE or CHS_CLIP is specified.

flOptions (ULONG) - input

Formatting options.

Option flags that can be used in combination:

CHS_OPAQUE: Background of characters is defined by the rectangle specified by prclRect. The rectangle is to be shaded (with background color and overpaint) before drawing.
CHS_VECTOR: Increments vector (alAdx) is supplied. If zero, alAdx is ignored.
CHS_LEAVEPOS: Leave the current position at the start of the string. If not set, the current position is moved to the position at which the next character would have been drawn, had there been one.
CHS_CLIP: Clip the string to the rectangle.
CHS_UNDERSCORE: Underscore the characters. See FATTR_SEL_UNDERSCORE field in the FATTRS datatype.
CHS_STRIKEOUT: Overstrike the characters. See FATTR_SEL_STRIKEOUT field in the FATTRS datatype.

Other bits are reserved and must be zero.

lCount (LONG) - input: Number of bytes in the string.; Must be greater than 0 and less or equal to 512.

pchString (PCH) - input: Characters to be drawn.; This parameter does not need to be null terminated.

alAdx (PLONG) - input: Increment values.; Vector of increment values, in world coordinates. Any negative values are treated as if they were zero.

Return Value

lHits (LONG) - returns

Correlation and error indicators.

GPI_OK: Successful
GPI_HITS: Correlate hits
GPI_ERROR: Error.

Remarks

A vector of increments can be specified, allowing control over the positioning of each character after the first. This vector consists of distances measured in world coordinates (along the baseline for left-to-right and right-to-left character directions, and along the shearline for top-to-bottom and bottom-to-top character directions). Increment i is the distance of the reference point of character i+1 from the reference point of character i. The last increment may be needed to update the current position. These increments, when specified, set the widths of each character. A further option allows a rectangle to be specified that can be used as the background of the string instead of the normal background. This rectangle is painted using the current character background color and an overpaint mix (unless this is in a dynamic segment, when leave-alone is used). Both corners of the rectangle are specified, so that the rectangle is positioned independently of the current position. Points on the borders of the rectangle are considered to be included within the rectangle. Clipping of the string to the rectangle is also allowed. This is independent of whether the rectangle is actually drawn. The current position can be updated to the point at which the next character would have been drawn, had there been one, or it can be left at the start of the string.

Errors

Possible returns from WinGetLastError:

PMERR_INV_HPS (0x207F): An invalid presentation-space handle was specified.
PMERR_PS_BUSY (0x20F4): An attempt was made to access the presentation space from more than one thread simultaneously.
PMERR_INV_CHAR_POS_OPTIONS (0x204E): An invalid options parameter was specified with GpiCharStringPos or GpiCharStringPosAt.
PMERR_INV_LENGTH_OR_COUNT (0x2092): An invalid length or count parameter was specified.
PMERR_INV_RECT (0x20BD): An invalid rectangle parameter was specified.
PMERR_FONT_AND_MODE_MISMATCH (0x202D): An attempt was made to draw characters with a character mode and character set that are incompatible. For example, the character specifies an image/raster font when the mode calls for a vector/outline font.

Graphic Elements and Orders

Element Type: ETYPE_GCCHSTE Order: Character String Extended at Current Position

Example Code

#define INCL_GPIPRIMITIVES /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

HPS     hps;         /* Presentation-space handle. */
PRECTL  prclRect;    /* Rectangle structure. */
ULONG   flOptions;   /* Formatting options. */
LONG    lCount;      /* Number of bytes in the string. */
PCH     pchString;   /* Characters to be drawn. */
PLONG   alAdx;       /* Increment values. */
LONG    lHits;       /* Correlation and error indicators. */

lHits = GpiCharStringPos(hps, prclRect, flOptions, lCount, pchString, alAdx);

This example uses GpiCharStringPos to display "13 characters", starting at position 10,10 and clipped to a 100x100 rectangle in the lower left corner.

#define INCL_GPIPRIMITIVES /* GPI Primitive functions */
#include <os2.h>

LONG lHits; /* correlation/error indicator */
HPS hps; /* Presentation-space handle */
POINTL pptlStart = {10L,10L}; /* Starting position */
RECTL prclRect = {0L,0L,100L,100L}; /* Rectangle structure */
ULONG flOptions; /* Formatting options */
LONG lCount; /* Number of bytes in the string */
char pchString[25]; /* Characters to be drawn */

GpiMove(hps, &pptlStart);

flOptions = CHS_CLIP; /* clip text to rectangle */
lCount = 13;
strcpy(pchString,"13 characters");

/* draw the string */
lHits = GpiCharStringPos(hps, &prclRect, flOptions, lCount, pchString, NULL);

Related Functions