GpiSetCharBox

This function sets the current character-box attribute to the specified value.

Syntax

GpiSetCharBox(hps, psizfxBox)

Parameters

hps (HPS) - input: Presentation-space handle.

psizfxBox (PSIZEF) - input: Character-box size in world coordinates.; The width determines the spacing of consecutive characters along the baseline.; Both width and height can be positive, negative, or zero.; When either parameter is negative, the spacing occurs in the opposite direction to normal and each character is drawn reflected in character-mode 3. Thus, for example, a negative height in the standard direction in mode 3 means that the characters are drawn upside down, and the string drawn below the baseline (assuming no other transformations cause inversion).; A zero character width or height is also valid; here, the string of characters becomes a line. If both are zero, the string is drawn as a single point.

Return Value

rc (BOOL) - returns

Success indicator.

TRUE: Successful completion
FALSE: Error occurred.

Remarks

The parameter psizfxBox specifies values for the width and height of a character box in world coordinates. Whether these values are used when character strings are drawn depends on the type of font being used (raster or outline), and on the value of the character mode attribute (see the GpiSetCharMode function).

For raster fonts, where the character box is used only for positioning in character mode CM_MODE2, the character box width corresponds to the lEmInc font metric (see FONTMETRICS). For proportionally-spaced raster fonts, the effective spacing for a given character is the character box width, scaled by the ratio of that character's width to lEmInc.

For outline fonts, characters are defined in font definition space. The sXDeviceRes and sYDeviceRes fields (see FONTMETRICS) define a rectangle in font definition space that is mapped to the character box rectangle (modified by the character angle and shear attributes) in world coordinates.

sYDeviceRes corresponds to the font point size in font definition space, and therefore the character box height corresponds to the font point size in world coordinates. This is typically less than the lMaxBaselineExt.

The effective width of each character from an outline font is the character box width, scaled by the ratio of the width of the character to sXDeviceRes. The lAveCharWidth (for a proportionally-spaced font) will therefore typically be smaller than the character box width. Indeed, because of differences in font design, lAveCharWidth and lMaxBaselineExt vary between different fonts, even when the character box dimensions are the same.lEmInc and lEmHeight are always equal to the character box width and height, respectively.

To cause characters of a given point-size to be generated using an outline font, establish a world coordinate space with specific metrics (for example, specify PU_TWIPS on GpiCreatePS), and set the character box height to the required point size. Because sXDeviceRes and sYDeviceRes are normally equal, the character box width should also be set equal to the height, if characters are required with the same aspect ratio as defined in the font (assuming that world coordinate space is isotropic).

The initial default value of the character box is the device-coordinates value returned by DevQueryCaps (CAPS_GRAPHICS_CHAR_WIDTH and CAPS_GRAPHICS_CHAR_HEIGHT) for the currently associated device, converted to page coordinates.

Note: In general the initial default value is rectangular, and to avoid character distortion, the character box should normally be set explicitly to be square if an outline font might be used (assuming that world coordinate space is isotropic). The default value can be changed with GpiSetDefAttrs.

GpiSetCharBox must not be issued in an area bracket.

The attribute mode (see GpiSetAttrMode) determines whether the current value of the character-box size 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_GSCC This element type is generated if the attribute mode (see GpiSetAttrMode) is set to AM_NOPRESERVE. Note that GpiCreateLogFont can also generate this element type. Order: Set Character Cell Element Type: OCODE_GPSCC This element type is generated if the attribute mode is set to AM_PRESERVE. Order: Set Character Cell/Push and Set Character Cell

Example Code

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

HPS     hps;         /* Presentation-space handle. */
PSIZEF  psizfxBox;   /* Character-box size in world coordinates. */
BOOL    rc;          /* Success indicator. */

rc = GpiSetCharBox(hps, psizfxBox);

This function sets the current character-box attribute to the specified value.

#define INCL_GPIPRIMITIVES
#include <OS2.H>

HPS hps; /* Presentation space handle */
SIZEF sizfCharBox; /* Character-box size in */
                   /* world coordinates. */

sizfCharBox.cx = MAKEFIXED(8,0); /* values are shifted to the */
sizfCharBox.cy = MAKEFIXED(20,0); /* left 16 bits to make them fixed. */

GpiSetCharBox( hps, &sizfCharBox );

Related Functions