< Previous PageNext Page >

Hide TOC

Deprecated ATSUI Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.0

ATSUCreateTextLayoutWithTextHandle

Creates an opaque text layout object containing default text layout attributes as well as associated text and text styles. (Deprecated in Mac OS X v10.0. Use ATSUCreateTextLayoutWithTextPtr instead. See the Discussion for more details.)

Not recommended.

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

Parameters

iText: A handle of type UniCharArrayHandle referring to a text buffer containing UTF-16–encoded text. ATSUI associates this buffer with the new text layout object and analyzes the entire text of the buffer when obtaining the layout context for the current text range. Thus, for paragraph-format text, if you specify a buffer containing less than a complete paragraph, some of ATSUI’s layout results are not guaranteed to be accurate. For example, with a buffer of less than a full paragraph, ATSUI can neither reliably obtain the context for bidirectional processing nor reliably generate accent attachments and ligature formations for Roman text.
iTextOffset: A UniCharArrayOffset value specifying the offset from the beginning of the text buffer to the first character of the range to include in the layout. To indicate that the specified text range starts at the beginning of the text buffer, you can pass the constant kATSUFromTextBeginning. To specify the entire text buffer, pass kATSUFromTextBeginning in this parameter and kATSUToTextEnd in the iTextLength parameter.
iTextLength: A UniCharCount value specifying the length of the text range. Note that iTextOffset + iTextLength must be less than or equal to the value of the iTextTotalLength parameter. If you want the range of text to extend to the end of the text buffer, you can pass the constant kATSUToTextEnd.
iTextTotalLength: A UniCharCount value specifying the length of the entire text buffer. This value should be greater than or equal to the range of text defined by the iTextLength parameter.
iNumberOfRuns: An ItemCount value specifying the number of text style runs you want to define within the text range. The number of style objects and style run lengths passed in the iStyles and iRunLengths parameters, respectively, should each be equal to the number of runs specified here.
iRunLengths: A pointer to a UniCharCount array specifying the lengths of each style run in the text layout object. You can pass kATSUToTextEnd for the last style run length if you want the style run to extend to the end of the text range. If the sum of the style run lengths is less than the total length of the text range, the remaining characters are assigned to the last style run.
iStyles: A pointer to the first element in an ATSUStyle array. Each element in the array must contain a valid style object that corresponds to a style run defined by the iRunLengths array.
oTextLayout: A valid pointer to an ATSUTextLayout value. On return, the value refers to the newly created text layout object.

Return Value

A result code. See “ATSUI Result Codes.”

Discussion

You should use the function ATSUCreateTextLayoutWithTextPtr instead of using the function ATSUCreateTextLayoutWithTextHandle.

The ATSUCreateTextLayoutWithTextHandle function creates a text layout object associated with style objects and text and containing the default text layout attributes described in “Attribute Tags.” To provide nondefault line or layout attributes for a text layout object, you can call the functions ATSUSetLineControls or ATSUSetLayoutControls. After setting text attributes, call ATSUDrawText to draw the text.

Because the only way that ATSUI interacts with text is via the memory references you associate with a text layout object, you are responsible for keeping these references updated, as in the following cases:

When the user deletes or inserts a subrange within a text buffer (but the buffer itself is not relocated), you should call the functions ATSUTextDeleted and ATSUTextInserted, respectively.
When you relocate the entire text buffer (but no other changes have occurred that would affect the buffer’s current subrange), you should call the function ATSUTextMoved.
When both the buffer itself is relocated and a subrange of the buffer’s text is deleted or inserted (that is, a combination of cases 1 and 2, above), you must use either the function ATSUSetTextHandleLocation or the function ATSUSetTextPointerLocation to inform ATSUI.
When you are associating an entirely different buffer with a text layout object, you must call either the function ATSUSetTextHandleLocation or the function ATSUSetTextPointerLocation.

Note that, because ATSUI objects retain state information, doing superfluous calling can degrade performance. For example, you could call ATSUSetTextHandleLocation rather than ATSUTextInserted when the user inserts text, but there would be a performance penalty, as all the layout caches are flushed when you call ATSUSetTextHandleLocation, rather than just the affected ones.

Text layout objects are readily reusable and should themselves be cached for later use, if possible.

The ATSUCreateTextLayoutWithTextHandle function associates text with a text layout object via a handle, but ATSUI functions that need to access the text return the handle to its original state upon completion.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.0.
Not available to 64-bit applications.

Declared In

ATSUnicodeObjects.h

ATSUIdle

Performs background processing. (Deprecated in Mac OS X v10.0. There is no replacement because this function does nothing in Mac OS X.)

Not recommended.

OSStatus ATSUIdle (
   ATSUTextLayout iTextLayout
);

Parameters

iTextLayout: A reference to the text layout object in which you want ATSUI to perform background processing.

Return Value

A result code. See “ATSUI Result Codes.”

Discussion

The function ATSUIdle is not recommended. Current versions of ATSUI do not implement background processing for text layout objects. In Mac OS X, the function ATSUIdle does nothing.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.0.
Not available to 64-bit applications.

Declared In

ATSUnicodeObjects.h

ATSUSetTextHandleLocation

Associates text with a text layout object. (Deprecated in Mac OS X v10.0. Use ATSUSetTextPointerLocation instead. See the Discussion for more details.)

Not recommended.

OSStatus ATSUSetTextHandleLocation (
   ATSUTextLayout iTextLayout,
   UniCharArrayHandle iText,
   UniCharArrayOffset iTextOffset,
   UniCharCount iTextLength,
   UniCharCount iTextTotalLength
);

Parameters

iTextLayout: An ATSUTextLayout value specifying the text layout object with which to associate text.
iText: A handle of type UniCharArrayHandle, referring to a text buffer containing UTF-16–encoded text. ATSUI associates this buffer with the text layout object and analyzes the complete text of the buffer when obtaining the layout context for the current text range. Thus, for paragraph-format text, if you specify a buffer containing less than a complete paragraph, some of ATSUI’s layout results are not guaranteed to be accurate. For example, with a buffer of less than a full paragraph, ATSUI can neither reliably obtain the context for bidirectional processing nor reliably generate accent attachments and ligature formations for Roman text.
iTextOffset: A UniCharArrayOffset value specifying the offset from the beginning of the text buffer to the first character of the range to include in the layout. To indicate that the specified text range starts at the beginning of the text buffer, you can pass the constant kATSUFromTextBeginning,. To specify the entire text buffer, pass kATSUFromTextBeginning in this parameter and kATSUToTextEnd in the iTextLength parameter.
iTextLength: A UniCharCount value specifying the length of the text range. Note that iTextOffset + iTextLength must be less than or equal to the value of the iTextTotalLength parameter. If you want the range of text to extend to the end of the text buffer, you can pass the constant kATSUToTextEnd.
iTextTotalLength: A UniCharCount value specifying the length of the entire text buffer. This value should be greater than or equal to the range of text defined by the iTextLength parameter.

Return Value

A result code. See “ATSUI Result Codes.”

Discussion

You should use the function ATSUSetTextPointerLocation instead of the function ATSUSetTextHandleLocation.

For ATSUI to render your text, you must associate the text with both a text layout object and style information. Some functions, such as ATSUCreateTextLayoutWithTextPtr, create a text layout object and associate text with it concurrently. However, if you use the function ATSUCreateTextLayout to create a layout object, you must assign text to the text layout object prior to attempting most ATSUI operations.

You can use either of the functions ATSUSetTextHandleLocation or ATSUSetTextPointerLocation to associate text with a text layout object. When you call these functions, you are both assigning a text buffer to a text layout object and specifying the current text subrange within the buffer to include in the layout.

If there is already text associated with a text layout object, calling ATSUSetTextHandleLocation or ATSUSetTextPointerLocation overrides the previously associated text, as well as clearing the object’s layout caches. You would typically only call these functions for a text layout object with existing associated text if either (a) both the buffer itself is relocated and a subrange of the buffer’s text is deleted or inserted or (b) when associating an entirely different buffer with a text layout object.

Note that, because ATSUI objects retain state, doing superfluous calling can degrade performance. For example, you could call ATSUSetTextHandleLocation rather than ATSUTextInserted when the user simply inserts a subrange of text within a text buffer, but there would be a performance penalty, as all the layout caches are flushed by ATSUSetTextHandleLocation, rather than just the affected ones.

Similarly, you should not call ATSUSetTextHandleLocation, when an entire text buffer associated with a text layout object is relocated, but no other changes have occurred that would affect the buffer’s current subrange. Instead, you should call ATSUTextMoved, which is a more focused function and therefore more efficient.

After associating text with the text layout object, use ATSUSetRunStyle to associate style information with the text. You can then call the function ATSUDrawText to display the text.

Note that while ATSUSetTextHandleLocation associates text with a text layout object via a handle, ATSUI functions that need to access the text return the handle to its original state upon function completion.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.0.
Not available to 64-bit applications.

Declared In

ATSUnicodeObjects.h

Deprecated in Mac OS X v10.1

ATSUCopyToHandle

Copies an ATSUI style to a handle. (Deprecated in Mac OS X v10.1. Use ATSUFlattenStyleRunsToStream instead.)

Not Recommended

OSStatus ATSUCopyToHandle (
   ATSUStyle iStyle,
   Handle oStyleHandle
);

Parameters

iStyle: An ATSUStyle value.
oStyleHandle: A valid handle.

Return Value

A result code.

Discussion

The ATSUCopyToHandle function is not recommended for use, as this function does not produce the correct data format for the display of ATSUI style data. You should instead use the function ATSUFlattenStyleRunsToStream to flatten style data and the function ATSUUnflattenStyleRunsFromStream to unflatten style data. These functions read and write data using the ustl data specification. You can use a data block format of this type to copy and paste Unicode-encoded styled text between applications or within your application. The ustl data structure contains flattened text layout data, flattened style run data, and flattened style list data. For more information on the ustl data structure see Inside Mac OS X: ATSUI Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.1.
Not available to 64-bit applications.

Declared In

ATSUnicodeFlattening.h

Deprecated in Mac OS X v10.3

ATSUDrawGlyphInfo

Draws glyphs at the specified location, based on style and layout information specified for each glyph. (Deprecated in Mac OS X v10.3. Use functions from “Accessing Glyph Data” instead.)

Not recommended.

OSStatus ATSUDrawGlyphInfo (
   ATSUGlyphInfoArray *iGlyphInfoArray,
   Float32Point iLocation
);

Parameters

iGlyphInfoArray: A pointer to an ATSUGlyphInfoArray structure containing the glyph information to draw. You can obtain an ATSUGlyphInfoArray structure from the function ATSUGetGlyphInfo.
iLocation: A Float32Point data structure that contains the x and y coordinates at which to draw the glyph(s). Each coordinate in the Float32Point data structure is a Float32 value.

Return Value

A result code. See “ATSUI Result Codes.”

Discussion

You must use ATSUDrawGlyphInfo to draw glyphs if you have previously called the function ATSUGetGlyphInfo, and you have modified the glyph information. However, if you want to modify the glyph information you should use the functions ATSUGlyphGetQuadraticPaths or ATSUGlyphGetCubicPaths instead of calling the function ATSUGetGlyphInfo.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.3.
Not available to 64-bit applications.

Declared In

ATSUnicodeGlyphs.h

ATSUGetFontFallbacks

Obtains the global font list and search order that ATSUI uses when a font does not have the glyph needed to image a character. (Deprecated in Mac OS X v10.3. Use font fallback objects instead.)

Not recommended.

OSStatus ATSUGetFontFallbacks (
   ItemCount iMaxFontFallbacksCount,
   ATSUFontID oFontIDs[],
   ATSUFontFallbackMethod *oFontFallbackMethod,
   ItemCount *oActualFallbacksCount
);

Parameters

iMaxFontFallbacksCount: An ItemCount value specifying the maximum number of fonts that you want to obtain. Typically, this is equivalent to the size of the array allocated in the oFontIDs parameter. To determine this value, see the Discussion.
oFontIDs: A pointer to memory you have allocated for an array of ATSUFontID values. If you are uncertain of how much memory to allocate, see the Discussion. On return, the array contains font IDs identifying the fonts ATSUI searches when seeking a substitute font.
oFontFallbackMethod: A pointer to an ATSUFontFallbackMethod value. On return, the value identifies the order in which ATSUI searches fonts. See “Font Fallback Methods” for a description of possible values.
oActualFallbacksCount: A pointer to an ItemCount value. On return, the value specifies the actual number of fonts that ATSUI searches. This value may be greater than that passed in the iMaxFontFallbacksCount parameter.

Return Value

A result code. See “ATSUI Result Codes.”

Discussion

You should not use this function because it operates on a global scope and may not be available in future versions of ATSUI. You should instead use the function ATSUGetObjFontFallbacks with a font fallback object that has been associated with a text layout object. See Inside Mac OS X: Rendering Unicode Text With ATSUI for step-by-step instructions on creating a font fallback object and associating it with a text layout object.

Special Considerations

Global font fallback settings can be changed by any ATSUI client, so they can be changed unexpectedly. The only way to ensure that ATSUI uses your preferred font fallback settings for your text is to create a font fallback object and associated it with a text layout object. See the Discussion for more details.

Version Notes

Available beginning with ATSUI 1.1.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.3.
Not available to 64-bit applications.

Declared In

ATSUnicodeObjects.h

ATSUGetGlyphInfo

Obtains a copy of the style and layout information for each glyph in a line. (Deprecated in Mac OS X v10.3. Use functions from “Accessing Glyph Data” instead.)

Not recommended.

OSStatus ATSUGetGlyphInfo (
   ATSUTextLayout iTextLayout,
   UniCharArrayOffset iLineStart,
   UniCharCount iLineLength,
   ByteCount *ioBufferSize,
   ATSUGlyphInfoArray *oGlyphInfoPtr
);

Parameters

iTextLayout: An ATSUTextLayout value specifying the text layout object to examine.
iLineStart: A UniCharArrayOffset value specifying the offset from the beginning of the text buffer to the first character of the line to examine. To indicate that the line starts at the beginning of the text buffer, you can pass the constant kATSUFromTextBeginning. To specify the entire text buffer, pass kATSUFromTextBeginning in this parameter and kATSUToTextEnd in the iLineLength parameter.
iLineLength: A UniCharCount value specifying the length of the line. If you want the line to extend to the end of the text buffer, you can pass the constant kATSUToTextEnd.
ioBufferSize: A pointer to a ByteCount value specifying the size of the buffer you have allocated for the ATSUGlyphInfoArray structure produced in the oGlyphInfoPtr parameter. On return, the value specifies the actual size of the ATSUGlyphInfoArray structure.
oGlyphInfoPtr: A pointer to an ATSUGlyphInfoArray structure. On return, the structure contains values identifying the text layout object, the number of glyphs in the specified line, and an array of ATSUGlyphInfo structures for each of the glyphs. Each ATSUGlyphInfo structure contains information identifying the glyph, the style object with which it is associated, and other related layout values.

Return Value

A result code. See “ATSUI Result Codes.”

Discussion

The ATSUGetGlyphInfo function obtains a copy of the style and layout information for each glyph in a line of text. Copying can be slow, so it’s best to use this function only if you do not plan to modify the glyph information. If you do modify the glyph information, you can only draw the modified glyphs by calling the function ATSUDrawGlyphInfo. Because you are working with a copy of the glyph data and not the actual data that ATSUI has, if you try to draw text by calling the ATSUDrawText function, none of the changes you make to the glyph information will be reflected in the drawn text.

Note that is you obtain glyph information with the function ATSUGetGlyphInfo and then draw glyphs using ATSUDrawGlyphInfo, ATSUI does not take synthetic styles into account when it draw. This means that font substitution will not work.

If you want to modify glyph information you should instead use the ATSUI direct-access functions ATSUGlyphGetQuadraticPaths or ATSUGlyphGetCubicPaths. You use each of these functions along with callback functions you supply for drawing the glyphs. When you modify and draw glyphs using ATSUI’s direct-access functions, you obtain access to the same information as that supplied by the function ATSUGetGlyphInfo, but in a way that allows font substitution to work. For more information on retrieving and drawing glyph outlines, see Inside Mac OS X: Rendering Unicode Text With ATSUI.

The Unicode characters in the text layout object (ATSUTextLayout) and the glyphs returned by the function ATSUGetGlyphInfo do not necessarily have a one-to-one correspondence. For example, the accented Latin character é can be represented by an e with a combining ´ accent. In this case, two characters map to one glyph.

Common ligatures such as ﬁ also form automatically for some fonts, causing two characters to map to one glyph. Right-to-left scripts such as Arabic, and complex scripts such as Devanagari or Thai have even more complicated mappings from characters to glyphs.

For this reason it's best to use the high level ATSUI functions whenever possible, and to associate a paragraph of text with a text layout object. Your application is then completely insulated from such issues.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.3.
Not available to 64-bit applications.

Declared In

ATSUnicodeGlyphs.h

ATSUMeasureText

(Deprecated in Mac OS X v10.3. Use ATSUGetUnjustifiedBounds instead.)

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.3.
Not available to 64-bit applications.

Declared In

ATSUnicodeDrawing.h

ATSUSetFontFallbacks

Sets, on a global scope, the font list and search order for ATSUI to use when a font does not have the glyph needed to image a character. (Deprecated in Mac OS X v10.3. Use font fallback objects instead.)

Not recommended.

OSStatus ATSUSetFontFallbacks (
   ItemCount iFontFallbacksCount,
   const ATSUFontID iFontIDs[],
   ATSUFontFallbackMethod iFontFallbackMethod
);

Parameters

iFontFallbacksCount: An ItemCount value specifying the number of fonts to be searched. This value should be equivalent to the number of elements in the iFontIDs array.
iFontIDs: A pointer to the first ATSUFontID value in the array of fonts to be searched.
iFontFallbackMethod: An ATSUFontFallbackMethod value specifying the order in which ATSUI is to search the fonts. See “Font Fallback Methods” for a description of possible search orders.

Return Value

A result code. See “ATSUI Result Codes.”

Discussion

When you call ATSUSetFontFallbacks, any settings you apply are global to the process and are used by all ATSUI clients in the process. Therefore, any ATSUI clients in the process can change these global font fallback settings unexpectedly. Other application threads can modify the font fallbacks settings, as well. The only way to ensure that ATSUI uses your preferred font fallback settings for your text is to create a font fallback object and associated it with a text layout object.

You create a font fallback object by calling the function ATSUCreateFontFallbacks. You define settings for the object by calling the function ATSUSetObjFontFallbacks. To associate the font fallback object with a text layout object, call either of the functions ATSUSetLayoutControls or ATSUSetLineControls. See Inside Mac OS X: Rendering Unicode Text With ATSUI for step-by-step instructions on creating a font fallback object and associating it with a text layout object.

Special Considerations

You should not use this function because it operates on a global scope and may not be available in future versions of ATSUI. Instead, use font fallback objects as described in the Discussion.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.3.
Not available to 64-bit applications.

Declared In

ATSUnicodeObjects.h

< Previous PageNext Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.