GpiQueryCharStringPosAt

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

See also: GpiQueryCharStringPos

Syntax

GpiQueryCharStringPosAt(hps, pptlStart, flOptions, lCount, pchString, alXincrements, aptlPositions)

Parameters

hps (HPS) - input

Presentation-space handle.

pptlStart (PPOINTL) - input

Starting position.

flOptions (ULONG) - input

Option flags.

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

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

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

Return Code

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.

Example Code

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

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

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

This example uses the GpiQueryCharStringPosAt 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            */
POINTL ptlStart = { 100, 100 };
POINTL aptl[12];

GpiQueryCharStringPosAt(hps,  /* presentation-space handle      */
    &ptlStart,                /* starting point for string      */
    0L,                       /* do not use vector increments   */
    11L,                      /* 11 characters in string        */
    "This string",            /* character string               */
    NULL,                     /* no vector increments           */
    aptl);                    /* array of structures for points */

Related Functions

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