Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Chapter 3 - QuickDraw Text / QuickDraw Text Reference

MeasureJustified
For text that is expanded, condensed, or scaled, the MeasureJustified procedure calculates the onscreen width in pixels from the left edge of the text segment to the glyph of the character.
PROCEDURE MeasureJustified (textPtr: Ptr; textLength: LongInt;
                            slop: Fixed; charLocs: Ptr;
                            styleRunPosition: JustStyleCode;
                            numer, denom: Point);
textPtr
A pointer to the memory location of the beginning of the text to
be measured.
textLength
The number of bytes of text to be measured. The text length should equal the entire visible part of the text on a line, including trailing spaces if and only if they are displayed. Otherwise, the results for the last glyph on the line may be invalid.
slop
The amount of slop for the text to be drawn. A positive value extends the text segment; a negative value condenses the text segment.
charLocs
A pointer to an application-defined array of textLength + 1 integers.
styleRunPosition
The position on the line of this style run. The style run can be the only one on the line, the leftmost on the line, the rightmost on the line, or one between two other style runs.
numer
A point giving the numerator for the horizontal and vertical
scaling factors.
denom
A point giving the denominator for the horizontal and vertical
scaling factors.

DESCRIPTION
The MeasureJustified procedure is similar to the MeasureText procedure, except that it is used to find the pixel location of a character's glyph in text that is expanded or condensed.
The MeasureJustified procedure calculates the onscreen pixel width of the glyph of each character beginning from the left edge of the text segment, taking into account slop value, scaling, and style run position.
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, MeasureJustified selects the character whose direction maps to that of the primary line direction.
The MeasureJustified 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 MeasureJustified 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.
The MeasureJustified procedure temporarily resets the space extra (spExtra) value, adding to the current value of the field, if any, the amount of extra space to be added to space characters in order to fully justify the text, based on calculations that take into account the slop value and all the text characteristics. On exit, MeasureJustified restores the original value.
Because MeasureJustified measures text in only the current font, style, and size, you need to call it once for each individual style run.
For more information about the scaling factors, see "The numer and denom Parameters" on page 3-64. See "The styleRunPosition Parameter" on page 3-63 for a description of the styleRunPosition parameter and the values it takes. See "The slop Parameter" on page 3-63 for more information about the slop parameter.
For additional information about MeasureJustified, contact Developer
Technical Support.

SPECIAL CONSIDERATIONS
The MeasureJustified procedure works properly for text in all script systems. For 1-byte complex script systems, MeasureJustified calculates the widths of any ligatures, reversals, and compound characters that would need to be drawn.
Note that textLength is the number of bytes to be drawn, not the number of characters. Because 2-byte script systems also include characters consisting of only one byte, you should not simply multiply the number of characters by 2 to determine this value; the application must determine and specify the correct number of bytes.
Some 1-byte script system fonts may have zero-width characters, which are usually overlapping diacritical marks that typically follow the base character in memory. In this case, MeasureJustified 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, MeasureJustified 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.
The MeasureJustified procedure may move memory; do not call this procedure at interrupt time.