Carbon


ATSUCreateTextLayoutWithTextHandle

Header: ATSUnicode.h Carbon status: Supported

Creates a text layout object containing a handle to associated text and style runs.

OSStatus ATSUCreateTextLayoutWithTextHandle (
    UniCharArrayHandle iText, 
    UniCharArrayOffset iTextOffset, 
    UniCharCount iTextLength, 
    UniCharCount iTextTotalLength, 
    ItemCount iNumberOfRuns, 
    UniCharCount iRunLengths[], 
    ATSUStyle iStyles[], 
    ATSUTextLayout *oTextLayout
);
Parameter descriptions
iText

A handle to the beginning of the text buffer you want associated with the text layout object. ATSUI expects the buffer to contain Unicode text. Before calling ATSUCreateTextLayoutWithTextHandle, allocate the memory for this handle.

iTextOffset

The edge offset in backing store memory corresponding to the beginning of the range of text you wish to perform layout operations on. To indicate the beginning of the text buffer, pass the constant kATSUFromTextBeginning, described in “Text Offset and Length Constants”. If you wish to perform layout operations on the entire text buffer, pass kATSUFromTextBeginning in the this parameter and kATSUToTextEnd in the iTextLength parameter. If the range of text is outside the text buffer, ATSUCreateTextLayoutWithTextHandle returns the result code kATSUInvalidTextRangeErr.

iTextLength

The length of the range of text to perform layout operations on. If you want the range of text to extend to the end of the text buffer, pass the constant kATSUToTextEnd, described in “Text Offset and Length Constants”. If you wish to perform layout operations on the entire text buffer, pass kATSUFromTextBeginning in the iTextOffset parameter and kATSUToTextEnd in this parameter. If the range of text is outside the text buffer, ATSUCreateTextLayoutWithTextHandle returns the result code kATSUInvalidTextRangeErr.

iTextTotalLength

The length of the entire text buffer. This value should be greater than or equal to the range of text specified in the iTextOffset and iTextLength parameters.

iNumberOfRuns

The number of style runs you wish to assign to the text layout object. This should be equivalent to the number of elements in the iRunLengths and iStyles arrays.

iRunLengths

An array of style run lengths corresponding to the style objects passed in the iStyles array. Pass kATSUToTextEnd for the last style run length if you want it to extend to the end of the text buffer. If the sum of the style run lengths is less than the total length of the text buffer, the remaining characters are assigned to the last style run.

iStyles

An array of style object references. Each element in the array must contain a valid style object that corresponds to a style run length in the iRunLengths array.

oTextLayout

On return, a pointer to a reference to a newly-created text layout object. You cannot pass NULL for this parameter.

function result

A result code.

DISCUSSION

The ATSUCreateTextLayoutWithTextHandle function creates a text layout object that contains style runs, a handle to associated text, and default text layout attribute values described in “Text Layout Attribute Tag Constants”. ATSUI functions that need to access text referenced by the handle will return the handle to its original state upon function completion.

If you wish to instead create a text layout object with a pointer to associated text, call the function ATSUCreateTextLayoutWithTextPtr.

Most ATSUI functions perform layout operations on the range of text specified in the iTextOffset and iTextLength parameters. Generally, this range is less than the entire text buffer. If this is the case, the text layout object will scan the remaining text to get the full context for bidirectional processing and other information about the text.

You are responsible for updating the memory location of the text associated with the text layout object whenever the user inserts, deletes, or moves text. To update the text memory location, call the function ATSUTextMoved.

ATSUCreateTextLayoutWithTextHandle allocates 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)