Carbon


ATSUDrawText

Header: ATSUnicode.h Carbon status: Supported

Draws a range of text at a specified screen location.

OSStatus ATSUDrawText (
    ATSUTextLayout iTextLayout, 
    UniCharArrayOffset iLineOffset, 
    UniCharCount iLineLength, 
    ATSUTextMeasurement iLocationX, 
    ATSUTextMeasurement iLocationY
);
Parameter descriptions
iTextLayout

A reference to an initialized text layout object containing the range of text you wish to render. You cannot pass NULL for this parameter.

iLineOffset

The edge offset that corresponds to the beginning of the range of text you wish to render. If the range of text spans multiple lines, you should call ATSUDrawText for each line and pass the edge offset corresponding to the beginning of the new line to draw. 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, ATSUDrawText returns the result code kATSUInvalidTextRangeErr.

iLineLength

The length of the range of text you want to render. 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 iLineOffset parameter. If the specified range of text is outside the text buffer, ATSUDrawText returns the result code kATSUInvalidTextRangeErr.

iLocationX

The x-coordinate of the origin (in the current graphics port) of the line containing the range of text you want to render. Pass the constant kATSUUseGrafPortPenLoc, described in “Current Pen Location and Clear All Constants”, to draw 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 containing the range of text you want to render. Pass the constant kATSUUseGrafPortPenLoc, described in “Current Pen Location and Clear All Constants”, to draw relative to the current pen location in the current graphics port.

function result

A result code. The result code kATSUInvalidCacheErr indicates that an attempt was made to read in style data from an invalid cache. This may be because 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 rendering a line of text.

DISCUSSION

The ATSUDrawText function renders a range of text at a specified screen location. It uses the same transfer mode and resolution as those set in the graphics port. Text color is taken from the style object and the value in the graphics port is ignored. If the text color was not previously set in the style object, you will get black text, regardless of what was set in the graphics port.

Before drawing the line, ATSUDrawText turns off any previously set line justification, rotation, width alignment, descent, and ascent values and treats the text as a single line. It then 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, ATSUDrawText 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, ATSUDrawText assigns these characters to the first style run it can find. If there no style run at the end of the range of text, ATSUDrawText assigns the remaining characters to the last style run it can find.

If you want to draw a range of text that spans multiple lines, you should call ATSUDrawText for each line of text that is being drawn, even if all the lines are in the same text layout object. You should adjust the iLineOffset parameter to reflect the beginning of each line to be drawn.

ATSUDrawText 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)