GpiCharStringAt

This function draws a character string starting at a specified position.

Syntax

GpiCharStringAt(hps, pptlPoint, lCount, pchString)

Parameters

hps (HPS) - input

Presentation-space handle.

pptlPoint (PPOINTL) - input

Starting position.

Defines, in world coordinates, the position at which the first character in the string is to be placed.

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

The function GpiCharStringAt (hps, point, count, string) is equivalent to:

• GpiMove (hps, point)
• GpiCharString (hps, count, string)

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 font from which the characters in the character string 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 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_COORDINATE (0x205B)

An invalid coordinate value was specified.

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_GCHSTM Order: Character String Move at Given Position

Example Code

This example uses the GpiCharStringAt function to draw the string "Hello" starting at the position (100,100). It then uses the GpiMove and GpiCharString functions to draw the same string at exactly the same position.

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

HPS hps; /* presentation space handle */
POINTL ptlStart;

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

/* Draw the string "Hello" at (100, 100). */
GpiCharStringAt(hps, &ptlStart, 5, "Hello");

/* These two calls are identical to the one above. */
GpiMove(hps, &ptlStart);
GpiCharString(hps, 5L, "Hello");

Related Functions

• GpiCharString
• GpiCharStringPos
• GpiCharStringPosAt
• GpiPop
• GpiQueryCharStringPos
• GpiQueryCharStringPosAt
• GpiQueryDefCharBox
• GpiSetAttrMode
• GpiSetAttrs
• GpiSetBackColor
• GpiSetBackMix
• GpiSetCharAngle
• GpiSetCharBox
• GpiSetCharDirection
• GpiSetCharMode
• GpiSetCharSet
• GpiSetCharShear
• GpiSetColor
• GpiSetDefAttrs
• GpiSetMix