View source for GpiCharStringPosAt

This function draws a character string starting at a specified position, with formatting options.

==Syntax==
 GpiCharStringPosAt(hps, pptlStart, prclRect, flOptions, lCount, pchString, alAdx)

==Parameters==
; hps ([[HPS]]) - input
: Presentation-space handle.

; pptlStart ([[PPOINTL]]) - input
: Starting position.

; prclRect ([[PRECTL]]) - input
: Rectangle structure.
: Defines, in world coordinates, the two corners of the rectangle that defines the background of the characters. It is ignored unless CHS_OPAQUE or CHS_CLIP is selected.

; flOptions ([[ULONG]]) - input
: Formatting options.
: Option flags that can be used in combination:
:; CHS_OPAQUE
:: Background of characters is defined by the rectangle specified by prclRect. The rectangle is to be shaded (with background color and overpaint) before drawing.
:; CHS_VECTOR
:: Increments vector (alAdx) is supplied. If 0, alAdx is ignored.
:; CHS_LEAVEPOS
:: If set, current position is unchanged by this function. If not set, current position is moved to the position at which the next character would have been drawn, had there been one.
:; CHS_CLIP
:: Clip the string to the rectangle.
:; CHS_UNDERSCORE
:: Underscore the characters. See FATTR_SEL_UNDERSCORE in the FATTRS datatype.
:; CHS_STRIKEOUT
:: Overstrike the characters. See FATTR_SEL_STRIKEOUT in the FATTRS datatype.
: Other bits are reserved and must be zero.

; lCount ([[LONG]]) - input
: Number of bytes in the string.
: Must be greater than 0 and less or equal to 512.

; pchString ([[PCH]]) - input
: Character string.
: This parameter does not need to be null terminated.

; alAdx ([[PLONG]]) - input
: Increment values.
: Vector of increment values, in world coordinates. Any negative values are treated as if they were zero.

==Return Value==
; lHits ([[LONG]]) - returns
: Correlation and error indicators.
:; GPI_OK
:: Successful
:; GPI_HITS
:: Correlate hits
:; GPI_ERROR
:: Error.

==Remarks==
A vector of increments can be specified, allowing control over the position of each character after the first. This vector consists of 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 character directions). Increment i is the distance of the reference point (for example, lower left corner) of character i+1 from the reference point of character i. The last increment may be needed to update the current position.
These increments, if specified, set the widths of each character.
A further option allows a rectangle to be specified that can be used as the background of the string instead of the normal background. This rectangle is painted using the current character background color and an overpaint mix (unless this is in a dynamic segment, when leave-alone is used). Both corners of the rectangle are specified, so that the rectangle is positioned independently of current position. Points on the borders of the rectangle are considered to be included within the rectangle.
Clipping of the string to the rectangle is also allowed. This is independent of whether the rectangle is actually drawn.
Current position can be updated to the point at which the next character would have been drawn, had there been one, or it can be left at the start of the string.

==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_CHAR_POS_OPTIONS (0x204E)
: An invalid options parameter was specified with GpiCharStringPos or GpiCharStringPosAt.
; PMERR_INV_COORDINATE (0x205B)
: An invalid coordinate value was specified.
; PMERR_INV_RECT (0x20BD)
: An invalid rectangle parameter 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: ETYPE_GCHSTE
Order: Character String Extended at Given Position

==Example Code==
<PRE>
#define INCL_GPIPRIMITIVES /* Or use INCL_GPI, INCL_PM, */
#include &lt;os2.h&gt;

HPS     hps;         /* Presentation-space handle. */
PPOINTL pptlStart;   /* Starting position. */
PRECTL  prclRect;    /* Rectangle structure. */
ULONG   flOptions;   /* Formatting options. */
LONG    lCount;      /* Number of bytes in the string. */
PCH     pchString;   /* Character string. */
PLONG   alAdx;       /* Increment values. */
LONG    lHits;       /* Correlation and error indicators. */

lHits = GpiCharStringPosAt(hps, pptlStart, prclRect, flOptions, lCount, pchString, alAdx);
</PRE>

This example uses GpiCharStringPosAt to display "13 Characters", starting at position (10,10) and clipped to a 100x100 rectangle in the lower left corner.

<pre>
#define INCL_GPIPRIMITIVES /* GPI Primitive functions */
#include &lt;os2.h&gt;

LONG lHits; /* correlation/error indicator */
HPS hps; /* Presentation-space handle */
POINTL pptlStart = {10L,10L}; /* Starting position */
RECTL rclRect = {0L,0L,100L,100L}; /* Rectangle structure */
ULONG flOptions; /* Formatting options */
LONG lCount; /* Number of bytes in the string */
char pchString[14]; /* Characters to be drawn */

flOptions = CHS_CLIP; /* clip text to rectangle */
lCount = 13;
strcpy(pchString,"13 characters");

lHits = GpiCharStringPosAt(hps, &pptlStart, &rclRect, flOptions, lCount, pchString, NULL);
</pre>

==Related Functions==
* [[GpiCharString]]
* [[GpiCharStringAt]]
* [[GpiCharStringPos]]
* [[GpiPop]]
* [[GpiQueryCharStringPos]]
* [[GpiQueryCharStringPosAt]]
* [[GpiQueryDefCharBox]]
* [[GpiSetAttrMode]]
* [[GpiSetAttrs]]
* [[GpiSetBackColor]]
* [[GpiSetBackMix]]
* [[GpiSetCharAngle]]
* [[GpiSetCharBox]]
* [[GpiSetCharDirection]]
* [[GpiSetCharMode]]
* [[GpiSetCharSet]]
* [[GpiSetCharShear]]
* [[GpiSetColor]]
* [[GpiSetDefAttrs]]
* [[GpiSetMix]]

[[Category:Gpi]]