GpiSetCharBreakExtra

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

Syntax

GpiSetCharBreakExtra(hps, BreakExtra)

Parameters

hps (HPS) - input

Presentation-space handle.

BreakExtra (FIXED) - input

Character-break-extra value.

The value can be negative, 0, or positive:

A negative value reduces the effective width of break characters.

A value of 0 results in normal spacing.

A positive value increases the effective width of break characters.

The value is in world coordinates.

Return Value

rc (BOOL) - returns

Success indicator.

TRUE

Successful completion

FALSE

Error occurred.

Remarks

The character-break-extra attribute provides a spacing value that increases or decreases the spacing for break characters in a string. The break character is defined by the font, and can be found by calling GpiQueryFonts (sBreakChar field in the FONTMETRICS structure). The break-extra spacing 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
• Extra spacing, see GpiSetCharExtra.

Break-extra spacing applies to character strings either within or outside a path definition (see GpiBeginPath). The effect of the character-break-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-break-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-break-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_GSCBE

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

Order: Set Character Break Extra

Element Type

OCODE_GPSCBE

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

Order: Push and Set Character Break Extra

Example Code

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

HPS     hps;        /* Presentation-space handle. /
FIXED   BreakExtra; / Character-break-extra value. /
BOOL    rc;         / Success indicator. */

rc = GpiSetCharBreakExtra(hps, BreakExtra);

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

#define INCL_GPIPRIMITIVES
#include <OS2.H>

HPS hps; /* Presentation space handle /
FIXED fxBreak; / Character-break-extra value. /
/ world coordinates. */

fxBreak = 8L<<16; /* values are shifted to the /
/ left 16 bits /
/ to make them fixed. */

GpiSetCharBreakExtra(hps, fxBreak);