GreCharString

GreCharString draws a character string starting at the current (X,Y) position. Upon completion, the current (X,Y) position is the start point for the character cell immediately after the last character in the string.

GreCharString 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.

GreCharString is called by the function GpiCharString. GreCharString is used to draw a character string from the current position within the presentation space. It updates the current presentation space position upon completion of output and produces a call to GreSetCurrentPosition.

Simulation support

None. This function is mandatory for all drivers.

Syntax

GreCharString(hdc, cChars, pchString, pInstance, lFunction);

Parameters

hdc (HDC) - input

Device context handle.

cChars (LONG) - input

Number of characters in the string.

pchString (PCH) - input

Pointer to the character string.

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

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

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 correlate hit (returned by display drivers when the correlate 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.

Example Code

#define INCL_GRE_STRINGS
#include <os2.h>

HDC      hdc;        /*  Device context handle. */
LONG     cChars;     /*  Number of characters in the string. */
PCH      pchString;  /*  Pointer to the character string. */
PVOID    pInstance;  /*  Pointer to instance data. */
ULONG    lFunction;
LONG     rc;         /*  Return Codes. */

rc = GreCharString(hdc, cChars, pchString,
       pInstance, lFunction);