Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

ATSUI Reference

Framework
ApplicationServices/ApplicationServices.h
Declared in
ATSLayoutTypes.h
ATSUnicodeDirectAccess.h
ATSUnicodeDrawing.h
ATSUnicodeFlattening.h
ATSUnicodeFonts.h
ATSUnicodeGlyphs.h
ATSUnicodeObjects.h
ATSUnicodeTypes.h

Overview

Apple Type Services for Unicode Imaging (ATSUI) enables the rendering of Unicode-encoded text with advanced typographic features. It automatically handles many of the complexities inherent in text layout, including the correct rendering of text in bidirectional and vertical script systems.

ATSUI may be useful to developers who are writing new text editors or word processing applications that render Unicode-encoded text. You can also use ATSUI if you want to modify your existing application to support Unicode text rendering.

This document describes the ATSUI application programming interface (API) through version 2.4. If you are a font designer or want more information about fonts, see the Apple font site: http://developer.apple.com/fonts/

Functions by Task

Creating and Initializing Style Objects

Manipulating Style Attributes

Manipulating Font Features

Manipulating Font Variations

Creating and Initializing Text Layout Objects

Manipulating Text Layout Attributes

Manipulating Line Attributes

Manipulating Line Breaks

Substituting Fonts

Identifying Fonts

Drawing and Highlighting Text

Supporting User Interaction With Onscreen Text

Obtaining Text Metrics

Working With Tabs

Accessing Glyph Data

Flattening and Parsing Style Data

Creating, Calling, and Deleting Universal Procedure Pointers

Not Recommended

Functions

ATSUBatchBreakLines

Calculates soft line breaks for the text associated with a text layout object.

OSStatus ATSUBatchBreakLines (
   ATSUTextLayout iTextLayout,
   UniCharArrayOffset iRangeStart,
   UniCharCount iRangeLength,
   ATSUTextMeasurement iLineWidth,
   ItemCount *oBreakCount
);

Parameters
iTextLayout

The ATSUTextLayout for which you want to determine soft line breaks.

iRangeStart

A UniCharArrayOffset value specifying the offset from the beginning of the text layout object’s text buffer to the first character of the text range to examine. To specify the beginning of the text buffer, pass the constant kATSUFromTextBeginning.

iRangeLength

The number of characters in which to consider in the determination of the soft line breaks.

iLineWidth

An ATSUTextMeasurement value specifying the line width for the text, as measured from the offset provided in the iLineStart parameter. You must pass a nonzero value. You should use the same width as the width layout control set for the text layout object since the final layout of each line is based on the controls set for the line or the entire text layout object. If no line width has been set for the line, ATSUBatchBreakLines uses the line width set for the text layout object; if this value is not set, ATSUBatchBreakLines returns paramErr.

Note that the value you pass for the iLineWidth parameter is used only for the line-breaking operation. For justification, flushness, and other operations to work properly you must also use this value as the line width for the text layout object. You can set the line width for the text layout object by calling the function ATSUSetLineControls or ATSUSetLayoutControls with the kATSULineWidthTag and the line width value.

oBreakCount

The number of soft line breaks found and set from the call. If you do not want to obtain the number of soft line breaks, then set this parameter to NULL.

Return Value

A result code. See “ATSUI Result Codes.”

Discussion

The ATSUBatchBreakLines function is equivalent to repeatedly calling the ATSUBreakLine function with the parameter iUseAsSoftLineBreak set to true. However the ATSUBatchBreakLines function performs more efficiently than repeated call to the ATSUBreakLine function.

You must call the ATSUGetSoftLineBreaks function to obtain the actual soft line breaks that were determined and set by the ATSUBatchBreakLines function.

Availability
Declared In
ATSUnicodeDrawing.h

ATSUBreakLine

Calculates and, optionally, sets a soft line break in a range of text.

OSStatus ATSUBreakLine (
   ATSUTextLayout iTextLayout,
   UniCharArrayOffset iLineStart,
   ATSUTextMeasurement iLineWidth,
   Boolean iUseAsSoftLineBreak,
   UniCharArrayOffset *oLineBreak
);

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 layout object’s text buffer to the first character of the text range to examine. To specify the beginning of the text buffer, pass the constant kATSUFromTextBeginning. When calling ATSUBreakLine repeatedly to obtain all the soft line breaks for a given text range, in each subsequent call pass the value produced in the oLineBreak parameter by the immediately prior call to ATSUBreakLine.

iLineWidth

An ATSUTextMeasurement value specifying the line width for the text, as measured from the offset provided in the iLineStart parameter. You must pass a nonzero value. You can pass kATSUUseLineControlWidth to indicate that ATSUBreakLine should use the previously set line width attribute for the current line to determine how many characters can fit on the line. If no line width has been set for the line, ATSUBreakLine uses the line width set for the text layout object; if this value is not set, ATSUBreakLine returns paramErr.

Note that the value you pass for the iLineWidth parameter is used only for the line-breaking operation. For justification, flushness, and other operations to work properly you must also use this value as the line width for the text layout object. You can set the line width for the text layout object by calling the function ATSUSetLineControls or ATSUSetLayoutControls with the kATSULineWidthTag and the line width value.

iUseAsSoftLineBreak

A Boolean value indicating whether ATSUBreakLine should automatically set the line break produced in the oLineBreak parameter. If true, ATSUBreakLine sets the line break and clears any previously-set soft line breaks that precede the new break in the line but lie after the offset specified by iLineStart.

oLineBreak

A pointer to a UniCharArrayOffset value. On return, the value specifies the offset from the beginning of the text layout object’s text buffer to the location of the calculated soft line break. If the value produced is the same value as specified in iLineStart, you have made an input parameter error. In this case, check to make sure that the line width specified in iLineWidth is big enough for ATSUBreakLine to perform line breaking. ATSUBreakLine does not return an error in this case. ATSUI usually calculates a soft line break to be at the beginning of the first word that does not fit on the line. But if ATSUBreakLine calculates the most optimal line break to be in the middle of a word, it returns the result code kATSULineBreakInWord. Note that ATSUI produces a line break in the middle of a word only as a last resort.

Return Value

A result code. See “ATSUI Result Codes.”

Discussion

When the user inserts or deletes text or changes text layout attributes that affect how glyphs are laid out, you must determine whether the affected range of text still fits in the set line width, that is, whether the text needs to be rewrapped. You can use the ATSUBreakLine function to calculate a soft line break, based on the line width and text range you specify. If you pass true for iUseAsSoftLineBreak, ATSUBreakLine sets the soft line break it calculates and performs line layout on the characters.

If you need to calculate and set soft line breaks for a range of text and you want to use the same width for all lines in this range, you should call the function ATSUBatchBreakLines. Calling ATSUBatchBreakLines is equivalent to repeatedly calling the ATSUBreakLine function with the parameter iUseAsSoftLineBreak set to true. However, the ATSUBatchBreakLines function performs more efficiently than repeated calls to the ATSUBreakLine function.

If you do choose to call the ATSUBreakLine function repeatedly to obtain all possible line breaks for a range of text it will produce the previously set soft line break(s) if there are no additional line breaks to be found, or if the user has altered the text range or its attributes in a way that does not affect glyph layout.

The ATSUBreakLine function suggests a soft line break each time it encounters a hard line break character such as a carriage return, line feed, form feed, line separator, or paragraph separator. If ATSUBreakLine does not encounter a hard line break, it uses the line width you specify to determine how many characters fit on a line and suggests soft line breaks accordingly.

If you pass true for iUseAsSoftLineBreak, ATSUBreakLine uses the soft line break it calculates to perform line layout on the characters. ATSUBreakLine then determines whether the characters still fit within the line, which is necessary due to end-of-line effects such as swashes. When ATSUBreakLine sets a soft line break, it clears any previously-set soft line breaks that precede the new break in the line but lie after the offset specified by iLineStart.

Before calculating soft line breaks, ATSUBreakLine turns off any previously set line justification, rotation, width, alignment, descent, and ascent values and treats the text as a single line. Additionally, ATSUBreakLine examines the text layout object to ensure that each of the characters in the range is assigned to a style run. If there are gaps between style runs, ATSUBreakLine assigns the characters in the gap to the style run that precedes (in storage order) the gap. If there is no style run at the beginning of the text range, ATSUBreakLine assigns these characters to the first style run it finds. If there no style run at the end of the text range, ATSUBreakLine assigns the remaining characters to the last style run it finds.

For optimal performance, you should use ATSUBreakLine or ATSUBatchBreakLines to both calculate and set soft line breaks in your text. You should typically only call the function ATSUSetSoftLineBreak to set soft line breaks when you are using your own line-breaking algorithm to calculate soft line breaks.

Availability
Declared In
ATSUnicodeDrawing.h

ATSUCalculateBaselineDeltas

Obtains the optimal baseline positions for glyphs in a style run.

OSStatus ATSUCalculateBaselineDeltas (
   ATSUStyle iStyle,
   BslnBaselineClass iBaselineClass,
   BslnBaselineRecord oBaselineDeltas
);

Parameters
iStyle

An ATSUStyle value specifying the style object to examine.

iBaselineClass

A BslnBaselineClass constant identifying the primary baseline from which to measure other baselines. See SFNTLayoutTypes.h for an enumeration of possible values. Pass the constant kBSLNNoBaselineOverride to use the standard baseline value from the current font.

oBaselineDeltas

A BslnBaselineRecord array consisting of Fixed values. On return, the array contains baseline offsets, specifying distances measured in points, from the default baseline to each of the other baseline types in the style object. Positive values indicate baselines above the default baseline and negative values indicate baselines below it. See SFNTLayoutTypes.h for a description of the BslnBaselineRecord type.

Return Value

A result code. See “ATSUI Result Codes.”

Discussion

Depending on the writing system, a baseline may be above, below, or through the centers of glyphs. In general, a style run has a default baseline, to which all glyphs are visually aligned when the text is laid out. For example, in a run of Roman text, the default baseline is the Roman baseline, upon which glyphs sit (except for descenders, which extend below the baseline).

You can call the ATSUCalculateBaselineDeltas function to obtain the distances from a specified baseline type to that of other baseline types for a given style object. ATSUCalculateBaselineDeltas takes into account font and text size when performing these calculations. ATSUI uses these distances to determine the cross-stream shifting to apply when aligning glyphs in a style run. You can use the resulting array to set or obtain the optimal baseline positions of glyphs in a style run. You can also set various baseline values to create special effects such as drop capitals.

The functions ATSUSetLineControls and ATSUSetLayoutControls allow you to set baseline offset values at the line or layout level, respectively, using the kATSULineBaselineValuesTag control attribute tag. For more information on kATSULineBaselineValuesTag, see “Attribute Tags.”

Availability
Declared In
ATSUnicodeObjects.h

ATSUClearAttributes

Restores default values to the specified style attributes of a style object.

OSStatus ATSUClearAttributes (
   ATSUStyle iStyle,
   ItemCount iTagCount,
   const ATSUAttributeTag iTag[]
);

Parameters
iStyle

An ATSUStyle value specifying the style object for which to restore default style attribute values.

iTagCount

An ItemCount value specifying the number of attributes to restore to default values. This value should correspond to the number of elements in the iTag array. To restore all style attributes in the specified style object, pass the constant kATSUClearAll in this parameter. In this case, the value in the iTag parameter is ignored.

iTag

A pointer to the initial ATSUAttributeTag constant in an array of attribute tags. Each tag should identify a style attribute to restore to its default value. See “Attribute Tags” for a description of the Apple-defined style attribute tag constants.

Return Value

A result code. See “ATSUI Result Codes.”

Discussion

The ATSUClearAttributes function removes those style attribute values identified by the tag constants in the iTag array and replaces them with the default values described in “Attribute Tags.” If you specify that any currently unset attribute values be removed, the function does not return an error.

To remove all previously set style attribute, font feature, and font variation values from a style object, call the function ATSUClearStyle.

Availability
Declared In
ATSUnicodeObjects.h

ATSUClearFontFeatures

Restores default settings to the specified font features of a style object.

OSStatus ATSUClearFontFeatures (
   ATSUStyle iStyle,
   ItemCount iFeatureCount,
   const ATSUFontFeatureType iType[],
   const ATSUFontFeatureSelector iSelector[]
);

Parameters
iStyle

An ATSUStyle value specifying the style object for which to restore default font feature settings.

iFeatureCount

An ItemCount value specifying the number of font features to restore to default settings. This value should correspond to the number of elements in the iType and iSelector arrays. To restore default settings to all the font features in the specified style object, pass the constant kATSUClearAll in this parameter. In this case, the values in the iType and iSelector parameters are ignored.

iType

A pointer to the initial ATSUFontFeatureType value in an array of feature types. Each value should identify a font feature to restore to its default setting. To obtain all previously set font features for a given style object, you can call the function ATSUGetAllFontFeatures.

iSelector

A pointer to the initial ATSUFontFeatureSelector value in an array of feature selectors. Each element in the array must contain a valid feature selector corresponding to a font feature you provide in the iType parameter. To obtain all previously set feature selectors for a given style object, you can call the function ATSUGetAllFontFeatures.

Return Value

A result code. See “ATSUI Result Codes.”

Discussion

The ATSUClearFontFeatures function removes those font features that are identified by the feature selector and type constants in the iSelector and iType arrays and replaces them with their font-defined default values. Note that if you pass ATSUClearFontFeatures a font feature and selector that are already at default settings, the function does not return an error.

To restore default font variations to a style object, call the function ATSUClearFontVariations. To restore default style attributes to a style object, call ATSUClearAttributes. To restore all default settings to a style object (for font features, variations, and style attributes), call the function ATSUClearStyle.

Availability
Declared In
ATSUnicodeFonts.h

ATSUClearFontVariations

Restores default values to the specified font variation axes of a style object.

OSStatus ATSUClearFontVariations (
   ATSUStyle iStyle,
   ItemCount iAxisCount,
   const ATSUFontVariationAxis iAxis[]
);

Parameters
iStyle

An ATSUStyle value specifying the style object for which to restore default font variation axis settings.

iAxisCount

An ItemCount value specifying the number of font variation axes to restore to default settings. This value should correspond to the number of elements in the iAxis array. To restore default values to all the font variation axes in the style object, pass the constant kATSUClearAll in this parameter. If you pass kATSUClearAll the value in the iAxis parameter is ignored.

iAxis

A pointer to the initial ATSUFontVariationAxis tag in an array of font variation axes. Each element in the array must contain a valid tag that corresponds to a font variation axis to restore to its default setting. You can obtain variation axis tags for a style object from the function ATSUGetAllFontVariations.

Return Value

A result code. See “ATSUI Result Codes.”

Discussion

The ATSUClearFontVariations function removes those font variation axis values identified by variation axis tags in the iAxis array and replaces them with their font-defined default values. You can remove unset font variation values from a style object without a function error.

To restore default font features to a style object, call the function ATSUClearFontFeatures. To restore default style attributes, call ATSUClearAttributes. To restore all default settings to a style object (for font features, variations, and style attributes), call the function ATSUClearStyle.

Availability
Declared In
ATSUnicodeFonts.h

ATSUClearLayoutCache

Clears the layout cache of a line or an entire text layout object.

OSStatus ATSUClearLayoutCache (
   ATSUTextLayout iTextLayout,
   UniCharArrayOffset iLineStart
);

Parameters
iTextLayout

An ATSUTextLayout value identifying the text layout object for which to clear a layout cache.

iLineStart

A UniCharArrayOffset value specifying the offset from the beginning of the text buffer to the beginning of the line for which to discard the layout cache. If the range of text spans multiple lines, you should call ATSUClearLayoutCache for each line, passing the offset corresponding to the beginning of the new line to draw with each call. To clear the layout cache of the entire text layout object, you can pass the constant kATSUFromTextBeginning.

Return Value

A result code. See “ATSUI Result Codes.”

Discussion

The layout cache contains all the layout information ATSUI calculates and needs to draw a range of text in a text layout object. This includes caret positions, the memory locations of glyphs, and other information needed to lay out the glyphs. ATSUI uses information in the layout cache to avoid laying out the text again, thereby improving performance. When you clear the layout cache of a line or block of text, ATSUI takes longer to redraw a line, since it must perform the calculations that support glyph layout again.

You should call the function ATSUClearLayoutCache when you need to decrease the amount of memory your application uses. This function reclaims memory at the cost of optimal performance.

By default, the ATSUClearLayoutCache function removes the layout cache of a single line. To clear the layout cache for multiple lines, you should call ATSUClearLayoutCache for each line. To clear the layout cache of an entire text layout object, pass the constant kATSUFromTextBeginning in the iLineStart parameter. Note that ATSUClearLayoutCache does not produce a function error if lines do not have a layout cache.

The ATSUClearLayoutCache function flushes the layout cache but does not alter previously set text layout attributes, soft line break positions, or the text memory location. If you do not want to retain these values, you should dispose of the text layout object by calling the ATSUDisposeTextLayout function.

Availability
Declared In
ATSUnicodeObjects.h

ATSUClearLayoutControls

Restores default values to the specified layout control attributes of a text layout object.

OSStatus ATSUClearLayoutControls (
   ATSUTextLayout iTextLayout,
   ItemCount iTagCount,
   const ATSUAttributeTag iTag[]
);

Parameters
iTextLayout

An ATSUTextLayout value specifying the text layout object for which to restore default layout control attribute values.

iTagCount

An ItemCount value specifying the number of layout control attributes to restore to default values. This value should correspond to the number of elements in the iTag array. To restore all layout control attributes in the specified text layout object, pass the constant kATSUClearAll in this parameter. In this case, the value in the iTag parameter is ignored.

iTag

A pointer to the initial ATSUAttributeTag constant in an array of attribute tags. Each tag should identify a layout control attribute to restore to its default value. See “Attribute Tags” for a description of the Apple-defined layout control attribute tag constants.

Return Value

A result code. See “ATSUI Result Codes.”

Discussion

The ATSUClearLayoutControls function removes those layout control attribute values identified by the tag constants in the iTag array and replaces them with the default values described in “Attribute Tags.” If you specify that any currently unset attribute values be removed, the function does not return an error.

To restore default values to line control attributes in a text layout object, call the function ATSUClearLineControls.

Availability
Declared In
ATSUnicodeObjects.h

ATSUClearLineControls

Restores default values to the specified line control attributes of a line in a text layout object.

OSStatus ATSUClearLineControls (
   ATSUTextLayout iTextLayout,
   UniCharArrayOffset iLineStart,
   ItemCount iTagCount,
   const ATSUAttributeTag iTag[]
);

Parameters
iTextLayout

An ATSUTextLayout value specifying the text layout object containing the line for which to restore default line control attribute values.

iLineStart

A UniCharArrayOffset value specifying the offset from the beginning of the text layout object’s text buffer to the first character of the line for which to restore attribute values.

iTagCount

An ItemCount value specifying the number of line control attributes to restore to default values. This value should correspond to the number of elements in the iTag array. To restore all line control attributes of the specified line, pass the constant kATSUClearAll in this parameter. In this case, the value in the iTag parameter is ignored.

iTag

A pointer to the initial ATSUAttributeTag constant in an array of attribute tags. Each tag should identify a line control attribute to restore to its default value. See “Attribute Tags” for a description of the Apple-defined line control attribute tag constants.

Return Value

A result code. See “ATSUI Result Codes.”

Discussion

The ATSUClearLineControls function removes those line control attribute values identified by the tag constants in the iTag array and replaces them with the default values described in “Attribute Tags.” If you specify that any currently unset attribute values be removed, the function does not return an error.

To restore default values to layout control attributes in a text layout object, call the function ATSUClearLayoutControls.

Availability
Declared In
ATSUnicodeObjects.h

ATSUClearSoftLineBreaks

Removes soft line breaks from a range of text. 

OSStatus ATSUClearSoftLineBreaks (
   ATSUTextLayout iTextLayout,