GreCharStringPos

GreCharStringPos draws a character string. The string can be drawn from the current (X,Y) position or from a position specified.

This function must be supported by the presentation driver. The handling routine must provide full support for drawing characters from an image font in CM_MODE1 when the character direction is CHDIRN_LEFTRIGHT (see Character Attributes). For outline characters or characters in any other mode or direction, the handling routine can dispatch the call to the graphics engine at the address given for this call in the default dispatch table.

GreCharStringPos is called by the function GpiCharStringAt. GreCharStringPos is used to draw a character string either at the current position or at a specified position. It will also update the current presentation space position upon completion of output.

Simulation support

None. This function is mandatory for all drivers.

Syntax

GreCharStringPos(hdc, pptlStart, prclRect, flOptions, cChars,
                 pchString, pAdx, pAttrs, pInstance, lFunction)

Parameters

hdc (HDC) - input

Device context handle.

pptlStart (PPOINTL) - input

Pointer to (X,Y) coordinates of start position.

prclRect (PRECTL) - input

Pointer to an opaque or clip rectangle.

The clipping rectangle pointed to by this parameter is defined as a RECTL structure

This rectangle, which is in world coordinates, is used as the clipping rectangle or as the background for the string, or both, depending on the value of flOptions. When the CHS_OPAQUE flag is set, normal background mix attributes are ignored and the rectangle is drawn using overpaint and the character background color attribute. When the CHS_OPAQUE is not set, the background is drawn using the normal method. When neither CHS_OPAQUE nor CHS_CLIP are specified, this parameter is ignored. Notice that points on the boundary of this rectangle are considered to be inside the rectangle.

flOptions (ULONG) - input

Options flag.

The following flags can be used in combination:

CHS_OPAQUE

Background of characters is defined by the rectangle prclRect. The rectangle is to be shaded (with background color and overpaint) before drawing.

CHS_VECTOR

Increment vector supplied (pAdx). If 0, pAdx is ignored.

CHS_LEAVEPOS

Leave current position at the start of the string.

CHS_CLIP

Clip string to rectangle.

CHS_START_XY

Start position of the string. When set, the handling routine must draw the string from the position indicated by pptlStart. If this flag is not set, the current position is used.

CHS_ATTR_INFO

Attributes to be used. When this flag is set, pAttrs indicates the foreground and background colors. Current attributes are unchanged. If the flag is not set, the string is drawn using the current character attributes. See Character Attributes.

CHS_UNDERSCORE

Underscore the characters. See the FATTRS structure in GreCreateLogicalFont.

CHS_STRIKEOUT

Overstrike the characters.

cChars (LONG) - input

Number of characters in the string.

pchString (PCH) - input

Pointer to the character string.

pAdx (PLONG) - input

Pointer to Increment array.

Pointer to an array of LONG integers, one element for each character in the string. When CHS_VECTOR is set, this array is used to set the spacing between characters. Each element is the distance in world coordinates from the bottom-left corner of the corresponding character in the string to the bottom-left corner of the next. The distance is measured along the baseline for left-to-right and right-to-left character directions, and along the shear line for top-to-bottom and bottom-to-top character directions. The final element is used to reposition the current position, when necessary.

pAttrs (PCSP_INFO) - input

Pointer to attributes.

Pointer to a CSP_INFO structure. This structure contains the attributes to be used to draw the string when the CHS_ATTR_INFO flag is set. These do not alter the current character attributes (see Character Attributes). The CSP_INFO structure is defined as:

cSize

Number of bytes in structure

lColor

Use foreground color

lBackColor

Use background color

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

High-order WORD=flags; low-order WORD=NGreCharStringPos.

Return Code

rc (LONG) - returns

Return Codes.

On completion, the handling routine must return a LONG value (cHits) indicating, where appropriate, whether correlation hits were detected:

• GPI_OK Successful
• GPI_HITS Successful with correlation hit (returned by display drivers when the correlation flag is ON, and a hit is detected)
• GPI_ERROR Error

Possible Errors Detected: When an error is detected, the handling routine must call WinSetErrorInfo to post the condition. Error codes for conditions that the handling routine is expected to check include:

• PMERR_BASE_ERROR
• PMERR_COORDINATE_OVERFLOW
• PMERR_DEV_FUNC_NOT_INSTALLED
• PMERR_EXCEEDS_MAX_SEG_LENGTH
• PMERR_FONT_AND_MODE_MISMATCH
• PMERR_HDC_BUSY
• PMERR_HRGN_BUSY
• PMERR_HUGE_FONTS_NOT_SUPPORTED
• PMERR_INSUFFICIENT_MEMORY
• PMERR_INV_HDC
• PMERR_INV_IN_AREA
• PMERR_INV_LENGTH_OR_COUNT
• PMERR_PATH_LIMIT_EXCEEDED

Refer to the "Error Explanations" section in the Presentation Manager Programming Reference for further explanation.

Example Code

Declaration:

 
#define INCL_GRE_STRINGS
#include <os2.h>

HDC          hdc;        /*  Device context handle. */
PPOINTL      pptlStart;  /*  Pointer to (X,Y) coordinates of start position. */
PRECTL       prclRect;   /*  Pointer to an opaque or clip rectangle. */
ULONG        flOptions;  /*  Options flag. */
LONG         cChars;     /*  Number of characters in the string. */
PCH          pchString;  /*  Pointer to the character string. */
PLONG        pAdx;       /*  Pointer to Increment array. */
PCSP_INFO    pAttrs;     /*  Pointer to attributes. */
PVOID        pInstance;  /*  Pointer to instance data. */
ULONG        lFunction;  /*  High-order WORD=flags; low-order WORD=NGreCharStringPos. */
LONG         rc;         /*  Return Codes. */

rc = GreCharStringPos(hdc, pptlStart, prclRect,
       flOptions, cChars, pchString, pAdx,
       pAttrs, pInstance, lFunction);