Legacy Document

Inside Macintosh: Text /

Chapter 4 - Font Manager / Font Manager Reference

Routines / Getting the Characteristics of a Font

OutlineMetrics

The OutlineMetrics function gets font measurements for a block of text to be drawn in a specified outline font.

FUNCTION OutlineMetrics (byteCount: Integer; textPtr: UNIV Ptr;
                         numer,denom: Point;
                         VAR yMax: Integer; VAR yMin: Integer;
                         awArray: FixedPtr; lsbArray: FixedPtr;
                         boundsArray: RectPtr): OSErr; 

byteCount

The number of bytes in the block of text that you want measured.

textPtr

A pointer to the block of text that you want measured.

numer

The numerators of the vertical and horizontal scaling factors. The numer parameter is of type Point, and contains two integers: the first is the numerator of the ratio for vertical scaling, and the second is the numerator of the ratio for horizontal scaling. The Font Manager applies these scaling factors to the current font in order to calculate the measurements for glyphs in the block of text.

denom

The denominators of the vertical and horizontal scaling factors. The denom parameter is of type Point, and contains two integers: the first is the denominator of the ratio for vertical scaling, and the second is the denominator of the ratio for horizontal scaling. The Font Manager applies these scaling factors to the current font in order to calculate the measurements for glyphs in the block of text.

yMax

On output, this is the maximum y-value for the text. Pass NIL in this parameter if you don't want this value returned.

yMin

On output, this is the minimum y-value for the text. Pass NIL in this parameter if you don't want this value returned.

awArray

A pointer to an array that, on output, is filled with the advance width measurements for the glyphs being measured. These measurements are in pixels, based on the point size and font scaling factors of the current font. There is an entry in this array for each glyph that is being measured.

The awArray parameter is of type FixedPtr. The FixedPtr data type is a pointer to an array, and each entry in the array is of type Fixed, which is 4 bytes in length. Multiply byteCount by 4 to calculate the memory you need in bytes.

If the FractEnable global variable has been set to TRUE through the SetFractEnable procedure, the values in awArray have fractional character widths. If FractEnable has been set to FALSE, the Font Manager returns integer values for the advance widths, with 0 in the decimal part of the values.

lsbArray

A pointer to an array that is, on output, filled with the left-side bearing measurements for the glyphs being measured. The measurements are in pixels, based on the point size of the current font. There is an entry in this array for each glyph that is being measured.

The lsbArray parameter is of type FixedPtr. The FixedPtr data type is a pointer to an array, and each entry in the array is of type Fixed, which is 4 bytes in length. Multiply byteCount by 4 to calculate the memory you need in bytes.

Left-side bearing values are not rounded.

boundsArray

A pointer to an array that is, on output, filled with the bounding boxes for the glyphs being measured. Bounding boxes are the smallest rectangles that fit around the pixels of the glyph. There is an entry in this array for each glyph that is being measured.

The coordinate system used to describe the bounding boxes is in pixel units, centered at the glyph origin, and with a vertical positive direction upwards, which is the opposite of the QuickDraw vertical orientation.

The boundsArray parameter is of type RectPtr. The RectPtr data type is a pointer to QuickDraw's Rect data type, which is 8 bytes in length. Multiply byteCount by 8 to calculate the memory you need in bytes. Allocate the memory needed for the array and pass a pointer to the array in the boundsArray parameter.

DESCRIPTION

The OutlineMetrics function computes the maximum y-value, minimum y-value, advance widths, left-side bearings, and bounding boxes for a block of text. It uses the font, size, and style specified in the current graphics port. You can use these measurements when laying out text. You may need to adjust line spacing to accommodate exceptionally large glyphs.

The OutlineMetrics function works for outline fonts only and is the preferred method for measuring text that is drawn with an outline font.

When you are using OutlineMetrics to compute advance width values, left-side bearing values, or bounding boxes, you need to bear in mind that when a text block contains 2-byte characters, not every byte in the awArray, lsbArray, and boundsArray structures is used. Each of these arrays is indexed by the glyph index; thus, if you have five characters in a string and two of them are 2-byte characters, only the first five entries in each array contains a value. Call the CharByte function (described in the chapter "Script Manager" in this book) to determine how many characters there are in the text block, and ignore the unused array entries (which occur at the end of each array).

If you don't want OutlineMetrics to compute one of these three values, pass NIL in the applicable parameter. Otherwise, allocate the amount of memory needed for the array and pass a pointer to it in this parameter.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and selector for the OutlineMetrics procedure are

Trap macro	Selector
_FontDispatch	$7008

SEE ALSO

The terms used for measuring text, including advance width, left-side bearing, and bounding box, are described in the section "Font Measurements," which begins on page 4-8. Scaling of fonts and the use of the font scaling factors are described in the section "How the Font Manager Scales Fonts," which begins on page 4-19.