![]() |
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 );
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.
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
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
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
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
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 rectangles sides are parallel to the coordinate axis. You cannot pass NULL for this parameter.
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.
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.
Available beginning with ATSUI 1.0.
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)