GpiCharString

This function draws a character string starting at the current position.

Syntax

GpiCharString(hps, lCount, pchString)

Parameters

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

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.

Return Value

lHits (LONG) - returns

Correlation and error indicators.

GPI_OK: Successful
GPI_HITS: Correlate hits
GPI_ERROR: Error.

Remarks

Each character in the string is positioned so that its character reference point is at the current position. The current position is advanced after each character is drawn to give the position for the next character. The characters in the character string are selected from the current character set. The font from which the characters are selected depends on the current character mode. For a description of which fonts are used for each of the possible modes, see GpiSetCharMode. The degree to which approximation of the position and size of characters is allowed, and also the area used during correlation of the character string, is controlled by the character-mode attribute. After the string has been drawn, the current position is set to the end of the character string. This is the point at which the next character would have been drawn, had it existed.

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_LENGTH_OR_COUNT (0x2092): An invalid length or count 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: OCODE_GCCHSTM Order: Character String Move at Current Position

Example Code

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

HPS     hps;       /* Presentation-space handle. */
LONG    lCount;    /* Number of bytes in the string. */
PCH     pchString; /* Characters to be drawn. */
LONG    lHits;     /* Correlation and error indicators. */

lHits = GpiCharString(hps, lCount, pchString);

This example uses the GpiCharString function to draw the string "Hello". The GpiMove function moves the current position to (100,100) so that the string starts there.

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

HPS hps; /* presentation space handle */
POINTL ptlStart; /* beginning of string */

ptlStart.x = 100L;
ptlStart.y = 100L;

/* Start string at (100, 100). */
GpiMove(hps, &ptlStart);

/* Draw the 5-character string. */
GpiCharString(hps, 5L, "Hello");

Related Functions