Legacy Document

Inside Macintosh: Text /

Chapter 3 - QuickDraw Text / QuickDraw Text Reference

Routines / Measuring Text

MeasureText

The MeasureText procedure provides an array version of the TextWidth function. For each character in the specified text, MeasureText calculates the width of the character's glyph in pixels from the left edge of the text segment.

PROCEDURE MeasureText (count: Integer; textAddr, charLocs: Ptr);

count

The number of bytes to be measured.

textAddr

A pointer to the memory location of the beginning of the text to be measured. The value of textAddr must point directly to the first character whose glyph is to be measured.

charLocs

A pointer to an application-defined array of count + 1 integers.

DESCRIPTION

The MeasureText procedure calculates the onscreen pixel width of the glyph of each character beginning from the left edge of the text segment. On return, the first element in the charLocs array contains 0 and the last element contains the total width of the text segment, when the primary line direction is left to right and the text is unidirectional. When the primary line direction is right to left and the text is unidirectional, the first element in the array contains the total width of the text segment, and the last element in the array contains 0. When the text is bidirectional, at a direction boundary, MeasureText selects the character whose direction maps to that of the primary line direction.

The MeasureText procedure returns the same results that an application would get if it called CharToPixel for each character with a direction parameter value of hilite. Using MeasureText to find the pixel location of a character's glyph is less efficient than using the CharToPixel function because the application must define the array pointed to by charLocs, and then walk the array after MeasureText returns the results.

For more information about MeasureText, contact Developer Technical Support.

SPECIAL CONSIDERATIONS

Some fonts in 1-byte script systems may have zero-width characters, which are usually overlapping diacritical marks that typically follow the base character in memory. In this case, MeasureText measures both the glyph of the base character (the high-order, low-address byte) and the width of the diacritical mark. The charLoc array includes an entry for each, but both entries contain the same value.

For 1-byte complex script systems, MeasureText calculates the widths of any ligatures, reversals, compound characters, and character clusters that need to be drawn. For example, for an Arabic ligature, the entry that corresponds to the trailing edge of each character that is part of the ligature is the trailing edge of the entire ligature.

Note that count is the number of bytes to be measured, not the number of characters. Because 2-byte script systems also include characters consisting of only one byte, do not simply multiply the number of characters by 2 to determine this value; you must determine and specify the correct number of bytes. For 2-byte characters, the charLocs array contains two entries--one corresponding to each byte--but both entries contain the same pixel-width value.