Carbon


ATSUSetTextPointerLocation

Header: ATSUnicode.h Carbon status: Supported

Assigns or updates text accessed with a pointer.

OSStatus ATSUSetTextPointerLocation (
    ATSUTextLayout iTextLayout, 
    ConstUniCharArrayPtr iText, 
    UniCharArrayOffset iTextOffset, 
    UniCharCount iTextLength, 
    UniCharCount iTextTotalLength
);
Parameter descriptions
iTextLayout

A reference to an initialized text layout object containing text that you want to assign or update. You cannot pass NULL for this parameter.

iText

A pointer to the beginning of a text buffer you want to update or assign. Note that ATSUI expects the buffer to contain Unicode text. Your application is responsible for allocating the memory associated with this pointer.

iTextOffset

The edge offset in backing store memory that corresponds to the beginning of range of text that you want ATSUI to update or assign. If you want the range of text to start at the beginning of the text buffer, you should pass the constant kATSUFromTextBeginning, described in “Text Offset and Length Constants”. If you want the range of text to cover the entire text buffer, pass kATSUFromTextBeginning in this parameter and kATSUToTextEnd in the iTextLength parameter. If the specified range of text is outside the text buffer, ATSUSetTextPointerLocation returns the result code kATSUInvalidTextRangeErr.

iTextLength

The length of the range of text that you want ATSUI to update or assign. If you want the range of text to extend to the end of the text buffer, you should pass the constant kATSUToTextEnd, described in “Text Offset and Length Constants”. If you want the range of text to cover the entire text buffer, pass kATSUToTextEnd in this parameter and kATSUFromTextBeginning in the iTextOffset parameter. If the specified range of text is outside the text buffer, ATSUSetTextPointerLocation returns the result code kATSUInvalidTextRangeErr.

iTextTotalLength

The total length of the text buffer that you want ATSUI to update or assign. This value should be greater than the range of text you passed in the iTextOffset and iTextLength parameters, unless you want to perform layout operations on the entire text buffer.

function result

A result code.

DISCUSSION

The ATSUSetTextPointerLocation function assigns new text or updates existing text that is accessed by a handle. For uninitialized text layout objects, ATSUSetTextPointerLocation assigns new text; for initialized text layout objects, it updates existing text that is accessed by a pointer. ATSUSetTextPointerLocation clears layout caches. If you want to assign or update text accessed by a handle, call the function ATSUSetTextHandleLocation.

If the user deletes, inserts, or moves text in a text layout object and the range of text covers the entire text buffer, you should

You can then call the function ATSUDrawText to display the updated text.

Most functions that operate on text layout objects perform these operations on the range of text that you specify in the iTextOffset and iTextLength parameters. Typically, this is a subrange of the entire text buffer. If this range is shorter than the entire text buffer, the text layout object will scan the remaining text to get the full context for bidirectional processing and other information about the text.

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