GpiSetCharExtra

This function specifies an extra increment to be used for spacing characters in a string.

Syntax

GpiSetCharExtra(hps, Extra)

Parameters

hps (HPS) - input

Presentation-space handle.

Extra (FIXED) - input

Character-extra value.

The value can be negative, 0, or positive:

A negative value forces the characters closer together.

A value of 0 results in normal spacing.

A positive value forces the characters further apart.

The value is in world coordinates.

Return Value

rc (BOOL) - returns

Success indicator.

TRUE: Successful completion

FALSE: Error occurred.

Remarks

The character-extra attribute provides a spacing value that increases or decreases the spacing between characters in a string. It applies to all characters in a font, including the break character and is additional to the spacing generated for other reasons, for example:

• The spacing determined by the font, including proportional spacing and kerning, if applicable
• The vector of increment values, see GpiCharStringPos, GpiCharStringPosAt, GpiQueryCharStringPos and GpiQueryCharStringPosAt
• Break-extra spacing, see GpiSetCharBreakExtra.

Extra spacing applies to character strings either within or outside a path definition (see GpiBeginPath). The effect of the character-extra attribute applies whatever the value of the character-mode attribute (see GpiSetCharMode), and for both outline and raster fonts.

This function must not be issued in an area bracket.

The initial default value of the character-extra attribute is 0, which gives normal spacing. This default value can be changed with GpiSetDefAttrs.

The attribute mode (see GpiSetAttrMode) determines whether the current value of the character-extra attribute is preserved.

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.

Graphic Elements and Orders

Element Type

OCODE_GSCE

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

Order: Set Character Extra

Element Type

OCODE_GPSCE

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

Order: Push and Set Character Extra

Example Code

This function specifies an extra increment to be used for spacing characters in a string.

#define INCL_GPIPRIMITIVES
#include <OS2.H>

HPS hps; /* Presentation space handle */
FIXED fxExtra; /* extra character. */

fxExtra = MAKEFIXED(0,0); /* normal spacing. */

GpiSetCharExtra(hps,fxExtra);