Carbon


ATSUMeasureTextImage

Header: ATSUnicode.h Carbon status: Supported

Obtains the standard bounding rectangle of a final laid-out line.

OSStatus ATSUMeasureTextImage (
    ATSUTextLayout iTextLayout, 
    UniCharArrayOffset iLineOffset, 
    UniCharCount iLineLength, 
    ATSUTextMeasurement iLocationX, 
    ATSUTextMeasurement iLocationY, 
    Rect *oTextImageRect
);
Parameter descriptions
iTextLayout

A reference to an initialized text layout object containing the range of text whose standard bounding rectangle you wish to determine. You cannot pass NULL for this parameter.

iLineOffset

The edge offset that corresponds to the beginning of the range of text whose standard bounding rectangle you want to obtain. To specify the beginning of the text buffer, pass the constant kATSUFromTextBeginning, described in “Text Offset and Length Constants”. To indicate the entire text buffer, pass kATSUFromTextBeginning in this parameter and the constant kATSUToTextEnd in the iLineLength parameter. If the specified range of text is outside the text buffer, ATSUMeasureTextImage returns the result code kATSUInvalidTextRangeErr.

iLineLength

The length of the range of text whose standard bounding rectangle you want to obtain. If you want the length to extend to the end of the text buffer, pass the constant kATSUToTextEnd, described in “Text Offset and Length Constants”. To indicate the entire text buffer, pass kATSUToTextEnd in this parameter and the constant kATSUFromTextBeginning in the iLineStart parameter. If the specified range of text is outside the text buffer, ATSUMeasureTextImage returns the result code kATSUInvalidTextRangeErr.

iLocationX

The x-coordinate of the origin (in the current graphics port) of the line whose image bounds you want to calculate. Pass 0 if you just want the dimensions of the bounds with respect to one another, not their actual onscreen position. Pass the constant kATSUUseGrafPortPenLoc, described in “Current Pen Location and Clear All Constants”, for the dimensions of the bounds relative to the current pen location in the current graphics port.

iLocationY

The y-coordinate of the origin (in the current graphics port) of the line whose image bounds you want to calculate. Pass 0 if you just want the dimensions of the bounds with respect to one another, not their actual onscreen position. Pass the constant kATSUUseGrafPortPenLoc, described in “Current Pen Location and Clear All Constants”, for the dimensions of the bounds relative to the current pen location in the current graphics port.

oTextImageRect

On return, a pointer to a structure that contains the dimensions of the enclosing rectangle representing the image bounds offset by the iLocationX and iLocationY parameters. If the line is rotated, the rectangle’s sides are parallel to the coordinate axis. You cannot pass NULL for this parameter.

function result

A result code. The result code kATSUInvalidCacheErr indicates that an attempt was made to read in style data from an invalid cache (that is, the format of the cached data does not match that used by ATSUI or the cached data is corrupt). The result code kATSUQuickDrawTextErr indicates that the QuickDraw function DrawText encountered an error while measuring a line of text.

DISCUSSION

The ATSUMeasureTextImage function obtains the standard bounding rectangle, or image bounds, of a line of text. ATSUMeasureTextImage takes into account line rotation, alignment, and justification, as well as other characteristics that affect layout like hanging punctuation. The rectangle passed back in oTextImageRect is the same one used by the function ATSUDrawText to draw a line of text.

The standard bounding rectangle is the smallest rectangle that completely encloses the filled or framed parts of the line. While the typographic bounding rectangle takes into account the ascent and descent lines for the displayed glyphs, the standard bounding rectangle just encloses the “inked parts” of the displayed glyphs.

To obtain the typographic bounds of a line after it is laid out, call the function ATSUGetGlyphBounds. To calculate the typographic bounds of a line before it is laid out, call the function ATSUMeasureText. If you want to instead obtain the typographic bounds of a final laid-out line, call the function ATSUGetGlyphBounds.

Before calculating the standard bounding rectangle enclosing a range of text, ATSUMeasureTextImage examines the text layout object to make sure that the style runs cover the entire range of text. If there are gaps between style runs, ATSUMeasureTextImage assigns the characters in the gap to the style run following the gap. If there is no style run at the beginning of the range of text, ATSUMeasureTextImage assigns these characters to the first style run it can find. If there no style run at the end of the range of text, ATSUMeasureTextImage assigns the remaining characters to the last style run it can find.

The height of the standard bounding rectangle is determined by the natural line ascent and descent calculated for the line. ATSUMeasureTextImage ignores the previously set line ascent and descent values for the line it is measuring. However, it uses other text layout attributes set for the line determine character layout. If no attributes have been set for the line, ATSUMeasureTextImage uses attributes set for the text layout object.

If the line is rotated, the sides of the passed back rectangle are parallel to the coordinate axes and encompass the rotated line. You should pass the standard bounding rectangle of a line of text to the function EraseRect to ensure erase all the text. In contrast, the typographic bounding rectangle passed back by ATSUMeasureText reflects an unrotated line.

The coordinates you specify in iLocationX and iLocationY are the same values used by ATSUDrawText for the line of text to be measured.

ATSUMeasureTextImage may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

VERSION NOTES

Available beginning with ATSUI 1.0.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.5 or later.


© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)