GpiQueryCharStringPos

This function processes a string as if it is being drawn under the current character attributes using GpiCharStringPos, and returns the positions in the string at which each character would be drawn.

Syntax

GpiQueryCharStringPos(hps, flOptions, lCount, pchString, alXincrements, aptlPositions)

Parameters

hps (HPS) - input

Presentation-space handle.

flOptions (ULONG) - input

Option flag.

CHS_VECTOR - Increments vector supplied (alXincrements). If 0, alXincrements is ignored.

lCount (LONG) - input

Length of the string.

It must be greater or equal to 0 and less or equal to 512.

pchString (PCH) - input

Character string to be examined.

alXincrements (PLONG) - input

Vector of x-increment values.

These are signed values in world coordinates. Any negative values are treated as if they were 0. This parameter is ignored if CHS_VECTOR is not set.

aptlPositions (PPOINTL) - output

Array of points.

The positions of each character in world coordinates. The first point returned is the initial current position, and the last point is the new current position if the string has been drawn.

Returns

rc (BOOL) - returns

Success indicator.

TRUE - Successful completion.

FALSE - Error occurred.

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_IN_RETAIN_MODE (0x208C)

An attempt was made to issue a function (for example, query) that is invalid when the actual drawing mode is not draw or draw-and-retain.

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_COORDINATE (0x205B)

An invalid coordinate value was specified.

PMERR_COORDINATE_OVERFLOW (0x2014)

An internal coordinate overflow error occurred. This can occur if coordinates or matrix transformation elements (or both) are invalid or too large.

PMERR_INV_DC_TYPE (0x2060)

An invalid type parameter was specified with DevOpenDC, or a function was issued that is invalid for a OD_METAFILE_NOQUERY device context.

Remarks

A vector of increments can be specified, allowing control over the positioning of each character after the first. These are 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). The i'th increment is the distance of the reference point of the (i+1)'th character from the reference point of the i'th. The last increment may be needed to update current position.

These increments, if specified, set the widths of each character.

This function is invalid when the drawing mode (see GpiSetDrawingMode) is set to retain.

Graphic Elements and Orders

Element Type

OCODE_GQSCS

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to AM_NOPRESERVE.

Order: Query String of Character Positions

Element Type

OCODE_GPQSCS

This element type is generated if the attribute mode is set to AM_PRESERVE.

Order: Push and Query String of Character Positions

Example Code

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

HPS        hps;            /*  Presentation-space handle. */
ULONG      flOptions;      /*  Option flag. */
LONG       lCount;         /*  Length of the string. */
PCH        pchString;      /*  Character string to be examined. */
PLONG      alXincrements;  /*  Vector of x-increment values. */
PPOINTL    aptlPositions;  /*  Array of points. */
BOOL       rc;             /*  Success indicator. */

rc = GpiQueryCharStringPos(hps, flOptions,
       lCount, pchString, alXincrements, aptlPositions);

This example calls the GpiQueryCharStringPos function to determine the location of each character in the string. Vector increments are not used.

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

HPS hps;                /* presentation space handle            */
CHAR szString[] = "Sample string";
POINTL aptl[sizeof(szString) + 1];

GpiQueryCharStringPos(hps,     /* presentation-space handle      */
    0L,                        /* does not use vector increments */
    sizeof(szString),          /* number of characters in string */
    szString,                  /* character string               */
    NULL,                      /* no vector increments           */
    aptl);                     /* array of structures for points */

Related Functions

• GpiCharString
• GpiCharStringAt
• GpiCharStringPos
• GpiCharStringPosAt
• GpiQueryCharStringPosAt
• GpiSetCharAngle
• GpiSetCharBox
• GpiSetCharDirection
• GpiSetCharMode
• GpiSetCharSet
• GpiSetCharShear