Retired Documents Library

Developer

ApplicationServices Framework Reference ATSUI Reference

Options
Deployment Target:

On This Page
Language:

ATSUI Reference (Retired Document)

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import ApplicationServices

Objective-C

@import ApplicationServices;

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

  • Creates an opaque style object containing only default style attributes, font features, and font variations.

    Declaration

    Objective-C

    OSStatus ATSUCreateStyle ( ATSUStyle *oStyle );

    Parameters

    oStyle

    A pointer to an ATSUStyle value. On return, the pointer refers to an empty style object.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUCreateStyle function creates a style object containing only default values for style attributes, font features, and font variations. The default values for the font features and variations are assigned by the font. The default style attribute values are described in Attribute Tags.

    To make changes to the default style attribute values, you can call the function ATSUSetAttributes. To set font features and font variations, call the functions ATSUSetFontFeatures and ATSUSetVariations, respectively. You can also use the function ATSUCreateAndCopyStyle to create a new style object by copying all the settings from an existing one.

    For ATSUI to apply your selected character-style information, you must associate the style object with a text run in a text layout object. A text run consists of one or more characters that are contiguous in memory. If you associate these characters with a distinct style, you define a style run. You can use the function ATSUSetRunStyle to define a style run by associating a style object with a run of text in a text layout object. Or, to create a text layout object and associate style objects with it at the same time, you can call the function ATSUCreateTextLayoutWithTextPtr. In either case, each text run in a text layout object must be assigned a style object, which may or may not differ from other style objects assigned to other text runs in the text layout object.

    Style objects are readily reusable and should be cached for later use, if possible. You can create a style object once and then use it for as many text layout objects as appropriate. Style objects are thread-safe starting with ATSUI version 2.3.

    Note that you are responsible for disposing of the memory allocated for the style object. However, you should dispose of any text layout objects with which the style object is associated prior to disposing of the style object itself. To dispose of a style object, call the function ATSUDisposeStyle.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Creates a copy of a style object.

    Declaration

    Objective-C

    OSStatus ATSUCreateAndCopyStyle ( ATSUStyle iStyle, ATSUStyle *oStyle );

    Parameters

    iStyle

    An ATSUStyle value specifying the style object to copy.

    oStyle

    A pointer to an ATSUStyle value. On return, the pointer refers to a newly created style object. This style object contains the same values for style attributes, font features, and font variations as those of the style object passed in the iStyle parameter.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUCreateAndCopyStyle function creates a new style object with values obtained from the source style object’s style attributes, font features, and font variations. ATSUCreateAndCopyStyle does not copy reference constants.

    To create a new style object without copying a source object, you can call the function ATSUCreateStyle. Alternately, to copy the contents of a source style object into an existing style object, call the function ATSUCopyAttributes.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Compares the attribute values of two style objects.

    Declaration

    Objective-C

    OSStatus ATSUCompareStyles ( ATSUStyle iFirstStyle, ATSUStyle iSecondStyle, ATSUStyleComparison *oComparison );

    Parameters

    iFirstStyle

    An ATSUStyle value specifying the first style object to compare.

    iSecondStyle

    An ATSUStyle value specifying the second style object to compare.

    oComparison

    A pointer to an ATSUStyleComparison value. On return, the value contains the results of the comparison and indicates whether the two style objects are the same, different, or one a subset of the another. See Style Comparison Options for a description of possible values.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUCompareStyles function compares the contents of two style objects, including their style attributes, font features, and font variations. It does not consider reference constants or application-defined style attributes in the comparison.

    You can call ATSUCompareStyles, in conjunction with the function ATSUGetAllAttributes, to implement style sheets and tables of style runs.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Restores default values to a style object.

    Declaration

    Objective-C

    OSStatus ATSUClearStyle ( ATSUStyle iStyle );

    Parameters

    iStyle

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

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUClearStyle function clears a style object of all style attributes (including any application-defined attributes), font features, and font variations and returns these values to their default settings. Default font variations and font features are defined by the font; default style attribute values are described in Attribute Tags. ATSUClearStyle does not remove reference constants.

    To restore only default style attributes to a style object, you should call the function ATSUClearAttributes. To restore only font variations to a style object, call ATSUClearFontVariations. To restore only font features, call ATSUClearFontFeatures.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Indicates whether a style object contains only default values.

    Declaration

    Objective-C

    OSStatus ATSUStyleIsEmpty ( ATSUStyle iStyle, Boolean *oIsClear );

    Parameters

    iStyle

    An ATSUStyle value specifying the style object to examine.

    oIsClear

    A pointer to a Boolean value. On return, the value is set to true if the style object contains only default values for style attributes, font features, and font variations. If false, the style object contains one or more nondefault values for style attributes, font features, or font variations.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    You can call the ATSUStyleIsEmpty function to determine whether a style object contains only default values for style attributes, font features, and font variations. ATSUStyleIsEmpty does not consider reference constants in its evaluation.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Sets application-specific data for a style object.

    Declaration

    Objective-C

    OSStatus ATSUSetStyleRefCon ( ATSUStyle iStyle, URefCon iRefCon );

    Parameters

    iStyle

    An ATSUStyle value specifying the style object for which to set application-specific data.

    iRefCon

    A 32-bit value containing or referring to application-specific style data.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUSetStyleRefCon function associates a reference constant (that is, application-specific data) with a style object. If you copy or clear a style object that contains a reference constant, the reference constant is neither copied nor removed. To obtain application-specific data for a style object, call the function ATSUGetStyleRefCon.

    When you dispose of a style object that contains a reference constant, you are responsible for freeing any memory allocated for the reference constant. Calling the function ATSUDisposeStyle does not do so.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains application-specific data for a style object.

    Declaration

    Objective-C

    OSStatus ATSUGetStyleRefCon ( ATSUStyle iStyle, URefCon *oRefCon );

    Parameters

    iStyle

    An ATSUStyle value specifying the style object for which to obtain application-specific data.

    oRefCon

    A pointer to a 32-bit value. On return, the value contains or refers to application-specific style data.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUGetStyleRefCon function obtains a reference constant (that is, application-specific data) associated with a style object. To associate a reference constant with a style object, call the function ATSUSetStyleRefCon.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Disposes of the memory associated with a style object.

    Declaration

    Objective-C

    OSStatus ATSUDisposeStyle ( ATSUStyle iStyle );

    Parameters

    iStyle

    An ATSUStyle value specifying the style object to dispose of.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUDisposeStyle function frees the memory associated with the specified style object and its internal structures, including style run attributes. It does not dispose of the memory pointed to by application-defined style run attributes or reference constants. You are responsible for doing so.

    You should call this function after calling the function ATSUDisposeTextLayout to dispose of any text layout objects associated with the style object.

    For best performance, once you create a style object, you should keep it and use it as often as needed. You should dispose of the style object only when it is no longer needed in your application.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Sets style attribute values in a style object.

    Declaration

    Objective-C

    OSStatus ATSUSetAttributes ( ATSUStyle iStyle, ItemCount iAttributeCount, const ATSUAttributeTag iTag[], const ByteCount iValueSize[], const ATSUAttributeValuePtr iValue[] );

    Parameters

    iStyle

    An ATSUStyle value specifying the style object for which to set attributes.

    iAttributeCount

    An ItemCount value specifying the number of attributes to set. This value should correspond to the number of elements in the iTag and iValueSize arrays.

    iTag

    A pointer to the initial ATSUAttributeTag value in an array of attribute tags. Each element in the array must contain a valid style attribute tag that corresponds to the style attribute value to set. Note that an attribute tag cannot be used in versions of the Mac OS that are earlier than the version in which the tag was introduced. For example, a tag available in Mac OS version 10.2 cannot be used in Mac OS version 10.1 or earlier. You can call the function Gestalt to check version information for ATSUI. See Attribute Tags for a description of the Apple-defined style attribute tag constants and for availability information.

    iValueSize

    A pointer to the initial ByteCount value in an array of attribute value sizes. Each element in the array must contain the size (in bytes) of the corresponding style run attribute value being set. ATSUSetAttributes sets style attributes after confirming the sizes in the array.

    iValue

    A pointer to the initial ATSUAttributeValuePtr value in an array of attribute value pointers. Each pointer in the array must reference an attribute value corresponding to a tag in the iTag array. The value referenced by the pointer must be legal for that tag.

    Return Value

    A result code. See ATSUI Result Codes. If there is a function error, ATSUSetAttributes does not set any attributes in the style object.

    Discussion

    Style attributes are a collection of values and settings that override the font-specified behavior for displaying and formatting text in a style run. To specify a style attribute, ATSUI uses a “triple” consisting of (1) an attribute tag, (2) a value for that tag, and (3) the size of the value.

    The ATSUSetAttributes function enables you to set multiple style attribute values for a style object. When you call ATSUSetAttributes, any style attributes that you do not set retain their previous values. To set font features and font variations, call the functions ATSUSetFontFeatures and ATSUSetVariations, respectively.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Copies all style attribute settings from a source style object to a destination style object.

    Declaration

    Objective-C

    OSStatus ATSUCopyAttributes ( ATSUStyle iSourceStyle, ATSUStyle iDestinationStyle );

    Parameters

    iSourceStyle

    An ATSUStyle value specifying the style object from which to copy style attributes.

    iDestinationStyle

    An ATSUStyle value specifying the style object to set style attributes to.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUCopyAttributes function copies all style attributes to a destination style object from a source style object, including any default values (those values not set by your application) in the source object. Default values for style attributes are described in Attribute Tags.

    The ATSUCopyAttributes function does not copy the contents of memory referenced by pointers within custom style attributes or within reference constants. You are responsible for ensuring that this memory remains valid until both the source and destination style objects are disposed of.

    To copy style attributes that are explicitly set in the source but not in the destination style object, call the function ATSUUnderwriteAttributes. To copy all style attributes that are explicitly set in the source object into the destination object, whether or not the destination object has its own settings for these values, call the function ATSUOverwriteAttributes.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Copies to a destination style object the nondefault style attribute settings of a source style object.

    Declaration

    Objective-C

    OSStatus ATSUOverwriteAttributes ( ATSUStyle iSourceStyle, ATSUStyle iDestinationStyle );

    Parameters

    iSourceStyle

    An ATSUStyle value specifying the style object from which to copy nondefault style attributes.

    iDestinationStyle

    An ATSUStyle value specifying the style object containing the style attributes to be overwritten.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUOverwriteAttributes function copies all nondefault style attribute values from a source style object to a destination style object. The source object’s nondefault values are applied to the destination object whether or not the destination object also has nondefault values for the copied attributes. All other settings in the destination style object are left unchanged.

    ATSUOverwriteAttributes does not copy the contents of memory referenced by pointers within custom style attributes or within reference constants. You are responsible for ensuring that this memory remains valid until both the source and destination style objects are disposed of.

    To create a style object that contains all the contents of another style object, call the function ATSUCreateAndCopyStyle. To copy all the style attributes (including any default settings) of a style object into an existing style object, call the function ATSUCopyAttributes. To copy style attributes that are set in the source but not in the destination style object, call the function ATSUUnderwriteAttributes.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Copies to a destination style object only those nondefault style attribute settings of a source style object that are at default settings in the destination object.

    Declaration

    Objective-C

    OSStatus ATSUUnderwriteAttributes ( ATSUStyle iSourceStyle, ATSUStyle iDestinationStyle );

    Parameters

    iSourceStyle

    An ATSUStyle value specifying the style object from which to copy nondefault style attributes.

    iDestinationStyle

    An ATSUStyle value specifying the style object containing style attribute values to be set.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUUnderwriteAttributes function copies to a destination style object only those nondefault style attribute values of a source style object that are not currently set in a destination style object. Note that the corresponding value in the destination object must not be set in order for a copied value to be applied. All other quantities in the destination style object are left unchanged.

    ATSUUnderwriteAttributes does not copy the contents of memory referenced by pointers within custom style attributes or within reference constants. You are responsible for ensuring that this memory remains valid until both the source and destination style objects are disposed of.

    To create a style object that contains all the contents of another style object, call the function ATSUCreateAndCopyStyle. To copy all the style attributes (including any default settings) of a style object into an existing style object, call the function ATSUCopyAttributes. To copy style attributes that are set in the source whether or not they are set in the destination style object, call the function ATSUOverwriteAttributes.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains an array of style attribute tags and value sizes for a style object.

    Declaration

    Objective-C

    OSStatus ATSUGetAllAttributes ( ATSUStyle iStyle, ATSUAttributeInfo oAttributeInfoArray[], ItemCount iTagValuePairArraySize, ItemCount *oTagValuePairCount );

    Parameters

    iStyle

    An ATSUStyle value specifying the style object to examine.

    oAttributeInfoArray

    A pointer to memory you have allocated for an array of ATSUAttributeInfo values. On return, the array contains pairs of tags and value sizes for any of the object’s style attributes that are not at default values. If you are uncertain of how much memory to allocate for this array, see the Discussion.

    iTagValuePairArraySize

    An ItemCount value specifying the maximum number of tag and value size pairs to obtain for the style object. Typically, this is equivalent to the number of ATSUAttributeInfo structures for which you have allocated memory in the oAttributeInfoArray parameter. To determine this value, see the Discussion.

    oTagValuePairCount

    A pointer to an ItemCount value. On return, the value specifies the actual number of ATSUAttributeInfo structures in the style object. This may be greater than the value you specified in the iTagValuePairArraySize parameter.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUGetAllAttributes function obtains all nondefault style attribute tags and values sizes for a style object. You can pass a tag and value-size pair obtained from ATSUGetAllAttributes to the function ATSUGetAttribute to determine the corresponding attribute value.

    Typically you use the function ATSUGetAllAttributes by calling it twice, as follows:

    1. Pass a reference to the style object to examine in the iStyle parameter, a valid pointer to an ItemCount value in the oTagValuePairCount parameter, NULL for the oAttributeInfoArray parameter, and 0 for the iTagValuePairArraySize parameter. ATSUGetAllAttributes returns the size of the tag and value-size arrays in the oTagValuePairCount parameter.

    2. Allocate enough space for an array of the returned size, then call the ATSUGetAllAttributes function again, passing a valid pointer in the oAttributeInfoArray parameter. On return, the pointer refers to an array of the style attribute tag and value-size pairs contained in the style object.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains a style attribute value for a style object.

    Declaration

    Objective-C

    OSStatus ATSUGetAttribute ( ATSUStyle iStyle, ATSUAttributeTag iTag, ByteCount iExpectedValueSize, ATSUAttributeValuePtr oValue, ByteCount *oActualValueSize );

    Parameters

    iStyle

    An ATSUStyle value specifying the style object for which to obtain an attribute value.

    iTag

    An ATSUAttributeTag constant identifying the attribute value to obtain. See Attribute Tags for a description of the Apple-defined style attribute tag constants.

    iExpectedValueSize

    The expected size (in bytes) of the value to obtain. To determine the size of an application-defined style attribute value, see the Discussion.

    oValue

    An ATSUAttributeValuePtr value, identifying the memory you have allocated for the attribute value. If you are uncertain of how much memory to allocate, see the Discussion. On return, oValue contains a valid pointer to the actual attribute value.

    oActualValueSize

    A pointer to a ByteCount value. On return, the value contains the actual size (in bytes) of the attribute value. You should examine this parameter if you are unsure of the size of the attribute value being obtained, as in the case of custom style run attributes.

    Return Value

    A result code. See ATSUI Result Codes. Note that if the attribute value you want to obtain is not set, ATSUGetAttribute produces the default value in the oValue parameter and returns the result code kATSUNotSetErr.

    Discussion

    The ATSUGetAttribute function obtains the value of a specified style attribute for a given style object.

    Before calling ATSUGetAttribute, you should call the function ATSUGetAllAttributes to obtain an array of nondefault style attribute tags and value sizes for the style object. You can then pass ATSUGetAttribute the tag and value size for the attribute value to obtain.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the style attribute values that are continuous over a given text range.

    Declaration

    Objective-C

    OSStatus ATSUGetContinuousAttributes ( ATSUTextLayout iTextLayout, UniCharArrayOffset iOffset, UniCharCount iLength, ATSUStyle oStyle );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object to examine.

    iOffset

    A UniCharArrayOffset value specifying the offset from the beginning of the text buffer to the first character of the text range to examine. 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 iLength parameter.

    iLength

    A UniCharCount value specifying the length of the text range to examine. If you want the range of text to extend to the end of the text buffer, you can pass the constant kATSUToTextEnd.

    oStyle

    An ATSUStyle value. On return, the style object contains those attributes that are the same for the entire text range specified by the iOffset and iLength parameters.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUGetContinuousAttributes function examines the specified text range to obtain the style attribute values (including those at default values) that remain consistent for the entire text range. You should call ATSUGetContinuousAttributes to determine the style information that remains constant over text that has been selected by the user.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Sets font features in a style object.

    Declaration

    Objective-C

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

    Parameters

    iStyle

    An ATSUStyle value specifying the style object for which to set font features.

    iFeatureCount

    An ItemCount value specifying the number of font features to set. This value should correspond to the number of elements in the iType and iSelector arrays.

    iType

    A pointer to the initial ATSUFontFeatureType value in an array of feature types. Each element in the array must contain a valid feature type that corresponds to a feature selector in the iSelector array. To obtain the valid feature types for a font, call the function ATSUGetFontFeatureTypes.

    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 that corresponds to a feature type in the iType array. To obtain the valid feature selectors for a font, call the function ATSUGetFontFeatureSelectors.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUSetFontFeatures function enables you to set multiple font features for a style object. Any unset font features retain their font-defined default values. To set style attributes and font variations for a style object, call the functions ATSUSetAttributes and ATSUSetVariations, respectively.

    The constants that represent font feature types are defined in the header file SFNTLayoutTypes.h. When you use ATSUI to access and set font features, you must use the constants defined in this header file, which are described in Inside Mac OS X: Rendering Unicode Text With ATSUI. As feature types can be added at any time, you should check Apple’s font feature registry website for the most up-to-date list of font feature types and selectors: http://developer.apple.com/fonts/Registry/index.html.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Obtains the font features of a style object that are not at default settings.

    Declaration

    Objective-C

    OSStatus ATSUGetAllFontFeatures ( ATSUStyle iStyle, ItemCount iMaximumFeatureCount, ATSUFontFeatureType oFeatureType[], ATSUFontFeatureSelector oFeatureSelector[], ItemCount *oActualFeatureCount );

    Parameters

    iStyle

    An ATSUStyle value specifying the style object to examine.

    iMaximumFeatureCount

    An ItemCount value specifying the maximum number of feature types and selectors to obtain for the style object. Typically, this is equivalent to the number of ATSUFontFeatureType and ATSUFontFeatureSelector values for which you have allocated memory in the oFeatureType and oFeatureSelector parameters, respectively. To determine this value, see the Discussion.

    oFeatureType

    A pointer to memory you have allocated for an array of ATSUFontFeatureType values. On return, the array contains constants identifying each type of font feature that is at a nondefault setting in the style object. If you are uncertain of how much memory to allocate for this array, see the Discussion.

    oFeatureSelector

    A pointer to memory you have allocated for an array of ATSUFontFeatureSelector values. On return, the array contains constants identifying the feature selectors that are at nondefault settings in the style object. Each selector determines the setting for a corresponding feature type produced in the oFeatureType parameter. If you are uncertain of how much memory to allocate for this array, see the Discussion.

    oActualFeatureCount

    A pointer to an ItemCount value. On return, the value specifies the actual number of font feature types and selectors in the style object. This may be greater than the value you specified in the iMaximumFeatureCount parameter.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUGetAllFontFeatures function obtains all of a style object’s font features that are not at default settings. Font features are grouped into categories called feature types, within which individual feature selectors define particular feature settings. The arrays produced by ATSUGetAllFontFeatures contain constants identifying the object’s font types and their corresponding font selectors.

    Typically you use the function ATSUGetAllFontFeatures by calling it twice, as follows:

    1. Pass a reference to the style object to examine in the iStyle parameter, a valid pointer to an ItemCount value in the oActualFeatureCount parameter, NULL for the oFeatureType and oFeatureSelector parameters, and 0 for the iMaximumFeatureCount parameter. ATSUGetAllFontFeatures returns the size in the oActualFeatureCount parameter to use for the feature type and selector arrays.

    2. Allocate enough space for arrays of the returned size, then call ATSUGetAllFontFeatures again, passing a pointer to the arrays in the oFeatureType and oFeatureSelector parameters. On return, the arrays contain the font feature types and selectors, respectively, for the style object.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the font feature corresponding to an index into an array of font features for a style object.

    Declaration

    Objective-C

    OSStatus ATSUGetFontFeature ( ATSUStyle iStyle, ItemCount iFeatureIndex, ATSUFontFeatureType *oFeatureType, ATSUFontFeatureSelector *oFeatureSelector );

    Parameters

    iStyle

    An ATSUStyle value specifying the style object to examine.

    iFeatureIndex

    An ItemCount value specifying an index into the array of font features for the style object. This index identifies the font feature to examine. Because this index is zero-based, you must pass a value between 0 and one less than the value produced in the oActualFeatureCount parameter of the function ATSUGetAllFontFeatures.

    oFeatureType

    A pointer to memory you have allocated for an ATSUFontFeatureType value. On return, the value identifies the font feature type corresponding to the index passed in the iFeatureIndex parameter.

    oFeatureSelector

    A pointer to memory you have allocated for an ATSUFontFeatureSelector value. On return, the value identifies the font feature selector that corresponds to the feature type produced in the oFeatureType parameter.

    Return Value

    A result code. Note that if the index specifies a font feature that is not set, ATSUGetFontFeature produces the font-specified default value for the feature and returns the result code kATSUNotSetErr. See ATSUI Result Codes.

    Discussion

    The ATSUGetFontFeature function obtains the setting for a specified font feature in a style object. You might typically call ATSUGetFontFeature if you need to obtain one previously set feature after another within your program’s processing loop. To obtain all previously set font features for a given style object, you can call the function ATSUGetAllFontFeatures.

    Before calling ATSUGetFontFeature, you should call the function ATSUGetAllFontFeatures to obtain a count of the font features that are set in the style object. You can then pass the index for the feature whose setting you want to obtain in the iTag and iMaximumValueSize parameters of ATSUGetFontFeature.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the available feature types of a font.

    Declaration

    Objective-C

    OSStatus ATSUGetFontFeatureTypes ( ATSUFontID iFontID, ItemCount iMaximumTypes, ATSUFontFeatureType oTypes[], ItemCount *oActualTypeCount );

    Parameters

    iFont

    An ATSUFontID value identifying the font to examine.

    iMaximumTypes

    An ItemCount value specifying the maximum number of feature types to obtain for the font. Typically, this is equivalent to the number of elements in the oTypes array.

    oTypes

    A pointer to memory you have allocated for an array of ATSUFontFeatureType values. You can call the function ATSUCountFontFeatureTypes to obtain the number of available feature types for a given font and thus determine the amount of memory to allocate. On return, the array contains constants identifying each type of feature that is defined for the font. The constants that represent font feature types are defined in the header file SFNTLayoutTypes.h and are described in Inside Mac OS X: Rendering Unicode Text With ATSUI.

    oActualTypeCount

    A pointer to an ItemCount value. On return, the value specifies the actual number of feature types defined in the font. This may be greater than the value you specify in the iMaximumTypes parameter.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    A given font may not support all possible feature types and selectors. If you select features that are not available in a font, you won’t see a change in the glyph’s appearance. To determine the available features of a font, you can call the functions ATSUGetFontFeatureTypes and ATSUGetFontFeatureSelectors.

    The ATSUGetFontFeatureTypes function reads the font data table for the specified font and obtains its supported feature types. You can then use this information both to present the user a list of font features from which to select and to call such functions as ATSUSetFontFeatures with more accuracy.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the number of available feature types in a font.

    Declaration

    Objective-C

    OSStatus ATSUCountFontFeatureTypes ( ATSUFontID iFontID, ItemCount *oTypeCount );

    Parameters

    iFont

    An ATSUFontID value identifying the font to examine.

    oTypeCount

    A pointer to an ItemCount value. On return, the value specifies the actual number of feature types defined for the font.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUCountFontFeatureTypes function obtains the total number of feature types defined for a font. You can use the count produced by ATSUCountFontFeatureTypes to determine how much memory to allocate for the oTypes array in the function ATSUGetFontFeatureTypes.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the available feature selectors for a given feature type in a font.

    Declaration

    Objective-C

    OSStatus ATSUGetFontFeatureSelectors ( ATSUFontID iFontID, ATSUFontFeatureType iType, ItemCount iMaximumSelectors, ATSUFontFeatureSelector oSelectors[], Boolean oSelectorIsOnByDefault[], ItemCount *oActualSelectorCount, Boolean *oIsMutuallyExclusive );

    Parameters

    iFont

    An ATSUFontID value identifying the font to examine.

    iType

    An ATSUFontFeatureType value specifying one of the font’s supported feature types. To obtain the available feature types for a font, call the function ATSUGetFontFeatureTypes.

    iMaximumSelectors

    An ItemCount value specifying the maximum number of feature selectors to obtain for the font’s specified feature type. Typically, this is equivalent to the number of elements in the oSelectors array.

    oSelectors

    A pointer to memory you have allocated for an array of ATSUFontFeatureSelector values. You can call the function ATSUCountFontFeatureSelectors to obtain the number of available feature selectors for a given font feature type and thus determine the amount of memory to allocate. On return, the array contains constants identifying each available feature selector for the given feature type. The constants that represent font feature selectors are defined in the header file SFNTLayoutTypes.h and are described in Inside Mac OS X: Rendering Unicode Text With ATSUI.

    oSelectorIsOnByDefault

    A pointer to memory you have allocated for an array of Boolean values. The number of elements in this array should correspond to the number of elements in the oSelectors array. On return, the array contains Boolean values indicating whether the corresponding feature selector in the oSelectors array is on or off. If true, the feature selector is on by default; if false, off.

    oActualSelectorCount

    A pointer to an ItemCount value. On return, the value specifies the actual number of feature selectors defined for the given feature type. This value may be greater than the value you specify in the iMaximumSelectors parameter.

    oIsMutuallyExclusive

    A pointer to a Boolean value. On return, the value indicates whether the feature selectors for the given feature type are exclusive or nonexclusive. If a feature type is exclusive you can choose only one of its available feature selectors at a time, such as whether to display numbers as proportional or fixed-width. If a feature type is nonexclusive, you can enable any number of feature selectors at once. If true, the feature type is exclusive and only one selector can be used at a time.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    A given font may not support all possible feature types and selectors. If you select features that are not available in a font, you won’t see a change in the glyph’s appearance. To determine the available features of a font, you can call the functions ATSUGetFontFeatureTypes and ATSUGetFontFeatureSelectors.

    The ATSUGetFontFeatureSelectors function reads the font data table for the specified font and obtains its supported feature selectors for the given feature types. You can then use this information both to present the user a list of font features from which to select and to call such functions as ATSUSetFontFeatures with more accuracy.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the number of available feature selectors for a given feature type in a font.

    Declaration

    Objective-C

    OSStatus ATSUCountFontFeatureSelectors ( ATSUFontID iFontID, ATSUFontFeatureType iType, ItemCount *oSelectorCount );

    Parameters

    iFont

    An ATSUFontID value identifying the font to examine.

    iType

    An ATSUFontFeatureType value specifying one of the font’s supported feature types. To obtain the available feature types for a font, call the function ATSUGetFontFeatureTypes.

    oSelectorCount

    A pointer to an ItemCount value. On return, the value specifies the actual number of feature selectors defined for the feature type by the font.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUCountFontFeatureSelectors function obtains the total number of feature selectors defined for a given feature type in the font. You can use the count produced by ATSUCountFontFeatureSelectors to determine how much memory to allocate for the oSelectors array in the function ATSUGetFontFeatureSelectors.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Sets font variation axes and values in a style object.

    Declaration

    Objective-C

    OSStatus ATSUSetVariations ( ATSUStyle iStyle, ItemCount iVariationCount, const ATSUFontVariationAxis iAxes[], const ATSUFontVariationValue iValue[] );

    Parameters

    iStyle

    An ATSUStyle value specifying the style object for which to set font variation values.

    iVariationCount

    An ItemCount value specifying the number of font variation values to set. This value should correspond to the number of elements in the iAxes and iValue arrays.

    iAxes

    A pointer to the initial ATSUFontVariationAxis value in an array of font variation axes. Each element in the array must represent a valid variation axis tag that corresponds to a variation value in the iValue array. To obtain a valid variation axis tag for a font, you can call the functions ATSUGetIndFontVariation or ATSUGetFontInstance.

    iValue

    A pointer to the initial ATSUFontVariationValue value in an array of font variation values. Each element in the array must contain a value that is valid for the corresponding variation axis in the iAxes parameter. You can obtain a font’s maximum, minimum, and default values for a given variation axis by calling the function ATSUGetIndFontVariation. You can obtain the font variation axis values for a font instance by calling ATSUGetFontInstance.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    If you supply font variation axes and values to the ATSUSetVariations function, you can change the appearance of a style object’s font accordingly. You may specify any number of variation axes and values in a style object. Any of the font’s variations that you do not set retain their font-defined default values.

    You can also use the ATSUSetVariations function to supply your own value within any variation axes defined for the font. However, if the font does not support the variation axis you specify, your custom variation has no visual effect.

    By calling the function ATSUGetIndFontVariation, you can obtain a variation axis and its maximum, minimum, and default values for a font.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains a style object’s font variation values that are not at default settings.

    Declaration

    Objective-C

    OSStatus ATSUGetAllFontVariations ( ATSUStyle iStyle, ItemCount iVariationCount, ATSUFontVariationAxis oVariationAxes[], ATSUFontVariationValue oFontVariationValues[], ItemCount *oActualVariationCount );

    Parameters

    iStyle

    An ATSUStyle value specifying the style object to examine.

    iVariationCount

    An ItemCount value specifying the maximum number of font variation values to obtain for the style object. Typically, this is equivalent to the number of ATSUFontVariationAxis and ATSUFontVariationValue values for which you have allocated memory in the oVariationAxes and oFontVariationValues parameters, respectively. To determine this value, see the Discussion.

    oVariationAxes

    A pointer to memory you have allocated for an array of ATSUFontVariationAxis values. On return, the array contains tags identifying those font variation axes in the style object that are not at default values. If you are uncertain of how much memory to allocate for this array, see the Discussion.

    oFontVariationValues

    A pointer to memory you have allocated for an array of ATSUFontVariationValue values. On return, the array contains the current font variation values for the font variation axes produced in the oVariationAxes array. If you are uncertain of how much memory to allocate for this array, see the Discussion.

    oActualVariationCount

    A pointer to an ItemCount value. On return, the value specifies the actual number of nondefault font variation values in the style object. This may be greater than the value you passed in the iVariationCount parameter.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUGetAllFontVariations function obtains all of a style object’s font variation axes that are not at default settings, as well as the current values for the axes.

    Typically you use the function ATSUGetAllFontVariations by calling it twice, as follows:

    1. Pass a reference to the style object to examine in the iStyle parameter, a pointer to an ItemCount value in the oActualVariationCount parameter, NULL for the oVariationAxes and oFontVariationValues parameters, and 0 for the iVariationCount parameter. ATSUGetAllFontVariations returns the size to use for the variation axes and value arrays in the oActualVariationCount parameter.

    2. Allocate enough space for arrays of the returned size, then call ATSUGetAllFontVariations again, passing a pointer to the arrays in the oVariationAxes and oFontVariationValues parameters. On return, the arrays contain the font variation axes and their corresponding values, respectively, for the style object.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the current value for a font variation axis in a style object.

    Declaration

    Objective-C

    OSStatus ATSUGetFontVariationValue ( ATSUStyle iStyle, ATSUFontVariationAxis iFontVariationAxis, ATSUFontVariationValue *oFontVariationValue );

    Parameters

    iStyle

    An ATSUStyle value specifying the style object to examine.

    iFontVariationAxis

    An ATSUFontVariationAxis tag specifying the style object’s variation axis to examine. You can obtain variation axis tags for a style object from the function ATSUGetAllFontVariations.

    oFontVariationValue

    A pointer to memory you have allocated for an ATSUFontVariationValue value. On return, ATSUGetFontVariationValue produces the currently set value for the style object’s specified variation axis. If this value has not been set, ATSUGetFontVariationValue produces the font-defined default value.

    Return Value

    A result code. Note that if no value has been set for the specified variation axis, ATSUGetFontVariationValue produces the font-defined default value and returns the result code kATSUNotSetErr. See ATSUI Result Codes.

    Discussion

    The ATSUGetFontVariationValue function obtains the setting for a specified font variation axis in a style object. You might typically call ATSUGetFontVariationValue if you need to obtain one previously set variation axis value after another within your program’s processing loop. To obtain all nondefault font variation axis values for a given style object, you can call the function ATSUGetAllFontVariations.

    Before calling ATSUGetFontVariationValue, call the function ATSUGetAllFontVariations to obtain the font variation axes that are set for the style object.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains a variation axis and its value range for a font.

    Declaration

    Objective-C

    OSStatus ATSUGetIndFontVariation ( ATSUFontID iFontID, ItemCount iVariationIndex, ATSUFontVariationAxis *oATSUFontVariationAxis, ATSUFontVariationValue *oMinimumValue, ATSUFontVariationValue *oMaximumValue, ATSUFontVariationValue *oDefaultValue );

    Parameters

    iFont

    An ATSUFontID value identifying the font to examine.

    iVariationIndex

    An ItemCount value specifying an index into the array of variation axes for the font. This index identifies the font variation axis to examine. Because this index is zero-based, you must pass a value between 0 and one less than the value produced in the oVariationCount parameter of the function ATSUCountFontVariations.

    oATSUFontVariationAxis

    A pointer to an ATSUFontVariationAxis value. On return, the value provides a four-character code identifying the font variation axis corresponding to the specified index.

    oMinimumValue

    A pointer to an ATSUFontVariationValue value. On return, the value identifies the variation axis minimum.

    oMaximumValue

    A pointer to an ATSUFontVariationValue value. On return, the value identifies the variation axis maximum.

    oDefaultValue

    A pointer to an ATSUFontVariationValue value. On return, the value identifies the variation axis default.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    By calling the function ATSUGetIndFontVariation, you can obtain a variation axis and its maximum, minimum, and default values for a font.

    If you supply font variation axes and values to the function ATSUSetVariations, you can change the appearance of a style object’s font accordingly.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the number of defined variation axes in a font.

    Declaration

    Objective-C

    OSStatus ATSUCountFontVariations ( ATSUFontID iFontID, ItemCount *oVariationCount );

    Parameters

    iFont

    An ATSUFontID value identifying the font to examine.

    oVariationCount

    A pointer to an ItemCount value. On return, the value specifies the number of variation axes defined for the font.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUCountFontVariations function obtains the total number of variation axes defined for a font. You can use the count produced by ATSUCountFontVariations to get information about a specific font variation axis from the function ATSUGetIndFontVariation.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the font variation axis values for a font instance.

    Declaration

    Objective-C

    OSStatus ATSUGetFontInstance ( ATSUFontID iFontID, ItemCount iFontInstanceIndex, ItemCount iMaximumVariations, ATSUFontVariationAxis oAxes[], ATSUFontVariationValue oValues[], ItemCount *oActualVariationCount );

    Parameters

    iFont

    An ATSUFontID value identifying the font to examine.

    iFontInstanceIndex

    An ItemCount value specifying an index into an array of instances for the font. This index identifies the font instance to examine. Because this index is zero-based, you must pass a value between 0 and one less than the value produced in the oInstances parameter of the function ATSUCountFontInstances.

    iMaximumVariations

    An ItemCount value specifying the maximum number of font variation axes to obtain for the font instance. Typically, this is equivalent to the number of ATSUFontVariationAxis and ATSUFontVariationValue values for which you have allocated memory in the oAxes and oValues parameters, respectively. To determine this value, see the Discussion.

    oAxes

    A pointer to memory you have allocated for an array of ATSUFontVariationAxis values. On return, the array contains tags identifying the font variation axes that constitute the font instance. If you are uncertain of how much memory to allocate for this array, see the Discussion.

    oValues

    A pointer to memory you have allocated for an array of ATSUFontVariationValue values. On return, the array contains the defined values for the font variation axes produced in the oAxes array. If you are uncertain of how much memory to allocate for this array, see the Discussion.

    oActualVariationCount

    A pointer to an ItemCount value. On return, the value specifies the actual number of font variation axes that constitute the font instance. This may be greater than the value you passed in the iMaximumVariations parameter.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    A font instance consists of a named set of values for each variation axis in a font. For example, suppose a font has the variation axis 'wght' with a minimum value of 0.0, a default of 0.5, and a maximum of 1.0. Additionally, the variation axis 'wdth' is also defined for the font, with a similar value range. The type designer can then choose to declare a font instance for a set of specific values within these axes, such as “Demibold” for a value of 0.8 for the 'wght' axis and 0.5 for the 'wdth' axis. By calling the function ATSUGetFontInstance, you can obtain the variation axis values for a given index into an array of font instances.

    Typically you use the function ATSUGetFontInstance by calling it twice, as follows:

    1. Pass the ID of the font to examine in the iFont parameter, a valid pointer to an ItemCount value in the oActualVariationCount parameter, NULL for the oAxes and oValues parameters, and 0 for the other parameters. ATSUGetFontInstance returns the size to use for the oAxes and oValues arrays in the oActualVariationCount parameter.

    2. Allocate enough space for arrays of the returned size, then call the ATSUGetFontInstance again, passing pointers to the arrays in the oAxes and oValues parameters. On return, the arrays contain the font variation axes and their corresponding values, respectively, for the font instance.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the number of defined font instances in a font.

    Declaration

    Objective-C

    OSStatus ATSUCountFontInstances ( ATSUFontID iFontID, ItemCount *oInstances );

    Parameters

    iFont

    An ATSUFontID value identifying the font to examine.

    oInstances

    A pointer to an ItemCount value. On return, the value specifies the number of font instances defined for the font.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUCountFontInstances function obtains the total number of font instances defined in a font. You can use an index value derived from this count to get information about a specific font instance by calling the function ATSUGetFontInstance.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Creates an opaque text layout object containing only default text layout attributes.

    Declaration

    Objective-C

    OSStatus ATSUCreateTextLayout ( ATSUTextLayout *oTextLayout );

    Parameters

    oTextLayout

    A valid pointer to an ATSUTextLayout value. On return, the value refers to an empty text layout object.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUCreateTextLayout function creates a text layout object containing only the default text layout attributes described in Attribute Tags. The resulting text layout object is associated with neither text nor style objects. However, most ATSUI functions that operate on text layout objects require that the objects be associated with style information and text. To associate style objects and text with an empty text layout object, you can call the functions ATSUSetRunStyle and ATSUSetTextPointerLocation. Or, to create a text layout object and associate style objects and text with it at the same time, you can call the function ATSUCreateTextLayoutWithTextPtr.

    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.

    Text layout objects are readily reusable and should be cached for later use, if possible. You can reuse a text layout object even if the text associated with it is altered. Call the functions ATSUSetTextPointerLocation, ATSUTextDeleted, or ATSUTextInserted to manage the altered text.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Creates an opaque text layout object containing default text layout attributes as well as associated text and text styles.

    Declaration

    Objective-C

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

    Parameters

    iText

    A pointer of type ConstUniCharArrayPtr, referring to a text buffer containing UTF-16–encoded text. ATSUI associates this buffer with the new 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.

    iNumberOfRuns

    An ItemCount value specifying the number of text style runs you want to define within the overall text range. The number of style objects and style run lengths passed in the iStyles and iRunLengths parameters, respectively, should be equal to the number of runs specified here.

    iRunLengths

    A pointer to the first element in a UniCharCount array. This array provides ATSUI with the lengths of each of the text’s style runs. 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

    The ATSUCreateTextLayoutWithTextPtr 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:

    1. 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.

    2. 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.

    3. 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 the function ATSUSetTextPointerLocation to inform ATSUI.

    4. When you are associating an entirely different buffer with a text layout object, you must call the function ATSUSetTextPointerLocation.

    Note that, because ATSUI objects retain state information, doing superfluous calling can degrade performance. For example, you could call ATSUSetTextPointerLocation 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 ATSUSetTextPointerLocation, rather than just the affected ones.

    Text layout objects are readily reusable and should themselves be cached for later use, if possible. Text objects are thread-safe starting with ATSUI version 2.4.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Creates a copy of a text layout object.

    Declaration

    Objective-C

    OSStatus ATSUCreateAndCopyTextLayout ( ATSUTextLayout iTextLayout, ATSUTextLayout *oTextLayout );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object to copy.

    oTextLayout

    A pointer to an ATSUTextLayout value. On return, the pointer refers to a newly created text layout object containing the contents of the text layout object in the iTextLayout parameter.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUCreateAndCopyTextLayout function creates a copy of the source text layout object’s style runs (including references to the associated text buffer and style objects), line attributes, layout attributes, and layout caches. ATSUCreateAndCopyTextLayout does not copy reference constants.

    To create a text layout object without copying a source object, you can the function ATSUCreateTextLayout or the function ATSUCreateTextLayoutWithTextPtr.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Associates text with a text layout object or updates previously associated text.

    Declaration

    Objective-C

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

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object for which to set text.

    iText

    A pointer of type ConstUniCharArrayPtr, 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.

    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

    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 text layout object, you must assign text to the object prior to attempting most ATSUI operations.

    You can use the function ATSUSetTextPointerLocation or to associate text with a text layout object. When you call this function, 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 ATSUSetTextPointerLocation overrides the previously associated text, as well as clearing the object’s layout caches. You would typically only call this function 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 ATSUSetTextPointerLocation 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 ATSUSetTextPointerLocation, rather than just the affected ones.

    Similarly, you should not call ATSUSetTextPointerLocation, 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 a text layout object, use ATSUSetRunStyle to associate style information with the text. You can then call the function ATSUDrawText to display the text or a subrange of the text.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains information about the text associated with a text layout object.

    Declaration

    Objective-C

    OSStatus ATSUGetTextLocation ( ATSUTextLayout iTextLayout, void **oText, Boolean *oTextIsStoredInHandle, UniCharArrayOffset *oOffset, UniCharCount *oTextLength, UniCharCount *oTextTotalLength );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object to examine.

    oText

    A pointer to data of any type. On return, the pointer is set to either a pointer or a handle that refers to the text buffer for the specified text layout object.

    oTextIsStoredInHandle

    A pointer to a Boolean value. On return, the value is set to true if the text buffer in the oText parameter is accessed by a handle; if false, a pointer.

    oOffset

    A pointer to a UniCharArrayOffset value. On return, the value specifies the offset from the beginning of the text buffer to the first character of the layout’s current text range.

    oTextLength

    A pointer to a UniCharCount value. On return, the value specifies the length of the text range.

    oTextTotalLength

    A pointer to a UniCharCount value. On return, the value specifies the length of the entire text buffer.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    When you call the ATSUGetTextLocation function for a given text layout object, ATSUI obtains the location of the text layout object’s associated text in physical memory, the length of the text range and its text buffer, and whether the text is accessed by a pointer or handle.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Defines a style run by associating style information with a run of text.

    Declaration

    Objective-C

    OSStatus ATSUSetRunStyle ( ATSUTextLayout iTextLayout, ATSUStyle iStyle, UniCharArrayOffset iRunStart, UniCharCount iRunLength );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying a text layout object with an associated text buffer. ATSUSetRunStyle assigns a style object to a run of text in this buffer.

    iStyle

    An ATSUStyle value specifying the style object to associate with the text run.

    iRunStart

    A UniCharArrayOffset value specifying the offset from the beginning of the text buffer to the first character of the text run.

    iRunLength

    A UniCharCount value specifying the length of the text run.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    A text run consists of one or more characters that are contiguous in memory. If you associate these characters with a distinct style, you define a style run. You can use the ATSUSetRunStyle function to define a style run, by associating a style object with a run of text in a text layout object. There is a limit of 64K different styles for each ATSUI text layout object. Each text run must be assigned its own style object, which may or may not differ from other style objects assigned to other text runs in a given text layout object.

    You can create a new style object containing only default settings by calling the function ATSUCreateStyle. To make changes to the default style attributes, you can call the function ATSUSetAttributes. To set font features and font variations, call the functions ATSUSetFontFeatures and ATSUSetVariations, respectively.

    Note that if you call ATSUSetRunStyle on a text run that is already associated with a style object, the style set by ATSUSetRunStyle overrides the previous style. Additionally, upon completion, ATSUSetRunStyle adjusts the lengths of any style runs on either side of the affected style run.

    For example, you may currently have a run of text, 40 characters long, that is assigned a single style, styleA. If you call ATSUSetRunStyle, you can reassign characters at offset 10–29 to a new style, styleB. If you do so, you would then have three style runs, where there once was one: characters at offset 0–9 (styleA), 10–29 (styleB), and 30–39 (styleA).

    After calling ATSUSetRunStyle, you can call the function ATSUDrawText to display the styled text. When you call ATSUDrawText, if you have not previously assigned styles to all the characters you request to be drawn, ATSUI automatically does so. Specifically, ATSUI extends the first style it locates immediately prior (in storage order) to the unstyled characters to include those unassigned characters. If the unstyled characters are at the beginning of the text stream, ATSUI finds the first style run in the stream and extends it backward to the first character.

    You should call ATSUSetRunStyle whenever you create a new text layout object without any associated styles, as by using the function ATSUCreateTextLayout. You should also call ATSUSetRunStyle to assign a style to a text run in response to a user action, such as when the user selects a run of text and changes the font.

    You do not need to call ATSUSetRunStyle when you change style attributes or text layout attributes. In such cases, ATSUI automatically updates the layout of the text as appropriate.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Obtains style run information for a character offset in a run of text.

    Declaration

    Objective-C

    OSStatus ATSUGetRunStyle ( ATSUTextLayout iTextLayout, UniCharArrayOffset iOffset, ATSUStyle *oStyle, UniCharArrayOffset *oRunStart, UniCharCount *oRunLength );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object for which to obtain style run information.

    iOffset

    A pointer to a UniCharArrayOffset value. This value should specify the offset from the beginning of the text buffer to the character for which to obtain style run information. To specify the beginning of the text buffer, you can pass the constant kATSUFromTextBeginning.

    oStyle

    A pointer to an ATSUStyle value. On return, the value specifies the style object assigned to the range of text containing the character at iOffset. Note that if you pass an offset in the iOffset parameter that is at a style run boundary, ATSUGetRunStyle produces style run information for the following, not preceding, style run.

    oRunStart

    A pointer to a UniCharArrayOffset value. On return, the value specifies the offset from the beginning of the text buffer to the first character of the style run containing the character at iOffset. Note that the entire style run does not necessarily share the same unset attribute values as the character at iOffset.

    oRunLength

    A pointer to a UniCharCount value. On return, the value specifies the length of the style run containing the character at iOffset.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    You can use the ATSUGetRunStyle function to obtain the style object assigned to a given text offset. ATSUGetRunStyle also produces the encompassing text range that shares the style object with the offset.

    Note that the style object contains those previously set style attributes, font features, and font variations that are continuous for the range of text that includes the specified text offset. If you want to obtain all shared style information for a style run, including any unset attributes, call the function ATSUGetContinuousAttributes instead.

    If only one style run is set in the text layout object, and it does not cover the entire text layout object, ATSUGetRunStyle uses the style run information for the iOffset parameter to set the style run information for the remaining text.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Sets application-specific data for a text layout object.

    Declaration

    Objective-C

    OSStatus ATSUSetTextLayoutRefCon ( ATSUTextLayout iTextLayout, URefCon iRefCon );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object for which to set application-specific data.

    iRefCon

    A 32-bit value containing or referring to application-specific text layout data.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUSetTextLayoutRefCon function associates a reference constant (that is, application-specific data) with a text layout object. You might typically use ATSUSetTextLayoutRefCon to track user preferences that can effect layout, for example.

    If you copy or clear a text layout object containing a reference constant, the reference constant is not copied or removed. When you dispose of a text layout object that contains a reference constant, you are responsible for freeing any memory allocated for the reference constant. Calling the function ATSUDisposeTextLayout does not do so.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Obtains application-specific data for a text layout object.

    Declaration

    Objective-C

    OSStatus ATSUGetTextLayoutRefCon ( ATSUTextLayout iTextLayout, URefCon *oRefCon );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object for which to obtain application-specific data.

    oRefCon

    A pointer to a 32-bit value. On return, the value contains or refers to application-specific text layout data.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUGetTextLayoutRefCon function obtains a reference constant (that is, application-specific data) associated with a text layout object. To associate a reference constant with a text layout object, call the function ATSUSetTextLayoutRefCon.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Disposes of the memory associated with a text layout object.

    Declaration

    Objective-C

    OSStatus ATSUDisposeTextLayout ( ATSUTextLayout iTextLayout );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object to dispose of.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUDisposeTextLayout function frees the memory associated with the specified text layout object and its internal structures, including line and layout control attributes, style runs, and soft line breaks. ATSUDisposeTextLayout does not dispose of any memory that may be allocated for reference constants or style objects associated with the text layout object. You are responsible for doing so.

    For best performance, text layout objects are readily reusable and should be cached for later use, if possible. You can reuse a text layout object even if the text associated with it is altered. Call the functions ATSUSetTextPointerLocation, ATSUTextDeleted, or ATSUTextInserted to manage the altered text, rather than disposing of the text layout object and creating a new one.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Sets layout control attribute values in a text layout object.

    Declaration

    Objective-C

    OSStatus ATSUSetLayoutControls ( ATSUTextLayout iTextLayout, ItemCount iAttributeCount, const ATSUAttributeTag iTag[], const ByteCount iValueSize[], const ATSUAttributeValuePtr iValue[] );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object for which to set layout control attributes.

    iAttributeCount

    An ItemCount value specifying the number of attributes to set. This value should correspond to the number of elements in the iTag and iValueSize arrays.

    iTag

    A pointer to the initial ATSUAttributeTag value in an array of layout control attribute tags. Each element in the array must contain a valid tag that corresponds to the layout control attribute to set. See Attribute Tags for a description of the Apple-defined layout control attribute tag constants.

    iValueSize

    A pointer to the initial ByteCount value in an array of attribute value sizes. Each element in the array must contain the size (in bytes) of the corresponding layout control attribute being set. ATSUSetLayoutControls sets layout attributes after confirming the sizes in the array.

    iValue

    A pointer to the initial ATSUAttributeValuePtr value in an array of attribute value pointers. Each value in the array must correspond to a tag in the iTag array and be a legal value for that tag.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    When you use ATSUI to image your text, you can control the text’s display and formatting at a number of different levels.

    One level is that of the entire text range associated with your text layout object, also known as the “layout level.” To affect display and formatting on this level, you can specify various layout control attributes using the ATSUSetLayoutControls function. These attributes affect the width of the text area from margin to margin, the alignment of the text, its justification, rotation, and direction, as well as other layout options.

    Another level is that of a single line of text, that is, the “line level.” To affect display and formatting on this level, you specify various line control attributes via the function ATSUSetLineControls. These attributes are similar to those that you can apply on a full-layout basis, but each affects only an individual text line.

    Given that ATSUI allows you to control similar aspects of the display and formatting of your text at either the line level or the layout level (or both, or neither), it is up to you to decide how much layout control to take. However, you should note the following:

    • Setting layout control attributes overrides the corresponding default layout-level settings for a text layout object. Any layout attributes that you do not set retain the default values described in Attribute Tags.

    • Setting line control attributes overrides the corresponding layout-level settings (whether set or at default values) for a text layout object. This is true even if you set the layout-level attributes subsequently to the line-level ones.

    • From a performance standpoint, it is preferable to work from the layout level and not specify layout line by line unless necessary.

    Finally, it is also possible to control the display and formatting of your text at the level of an individual character or “run” of characters. At this level, you customize layout by manipulating style settings in a style object. Among the character-level aspects you can control are style attributes (such as font size and color), font features (such as ligatures), and font variations (such as continually varying font weights or widths). However, there are certain line control attributes (specified via the ATSLineLayoutOptions flags) that can override style attributes applied to the same text.

    Similarly to style attributes, you use a “triple” to specify a line or layout control attribute. That is, an attribute tag, the value of the attribute it sets, and the size (in bytes) of the attribute value. Attribute tags are constants supplied by ATSUI. Attribute values may be a scalar, a structure, or a pointer.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Copies all layout control attribute settings from a source text layout object to a destination text layout object.

    Declaration

    Objective-C

    OSStatus ATSUCopyLayoutControls ( ATSUTextLayout iSourceTextLayout, ATSUTextLayout iDestTextLayout );

    Parameters

    iSourceTextLayout

    An ATSUTextLayout value specifying the text layout object from which to copy layout control attributes.

    iDestTextLayout

    An ATSUTextLayout value specifying the text layout object for which to set layout control attributes.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUCopyLayoutControls function copies all layout control attribute values to a destination text layout object from a source text layout object, including any default (unset) values in the source object. Default values for unset layout control attributes are described in Attribute Tags.

    ATSUCopyLayoutControls does not copy the contents of memory referenced by pointers within reference constants. You are responsible for ensuring that this memory remains valid until both the source and destination text layout objects are disposed.

    To copy line control attribute values from one text layout object to another, call the function ATSUCopyLineControls.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains an array of layout control attribute tags and value sizes for a text layout object.

    Declaration

    Objective-C

    OSStatus ATSUGetAllLayoutControls ( ATSUTextLayout iTextLayout, ATSUAttributeInfo oAttributeInfoArray[], ItemCount iTagValuePairArraySize, ItemCount *oTagValuePairCount );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object to examine.

    oAttributeInfoArray

    A pointer to memory you have allocated for an array of ATSUAttributeInfo values. On return, the array contains pairs of tags and value sizes for the object’s layout control attributes that are not at default values. If you are uncertain of how much memory to allocate for this array, see the Discussion.

    iTagValuePairArraySize

    An ItemCount value specifying the maximum number of tag and value size pairs to obtain for the text layout object. Typically, this is equivalent to the number of ATSUAttributeInfo structures for which you have allocated memory in the oAttributeInfoArray parameter. To determine this value, see the Discussion.

    oTagValuePairCount

    A pointer to an ItemCount value. On return, the value specifies the actual number of ATSUAttributeInfo structures in the text layout object. This may be greater than the value you specified in the iTagValuePairArraySize parameter.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUGetAllLayoutControls function obtains all nondefault layout control attribute tags and their values sizes for a text layout object. You can pass a tag and value size pair obtained from ATSUGetAllLayoutControls to the function ATSUGetLayoutControl to determine the corresponding attribute value.

    Typically you use the function ATSUGetAllLayoutControls by calling it twice, as follows:

    1. Pass a reference to the text layout object to examine in the iTextLayout parameter, NULL for the oAttributeInfoArray parameter, a pointer to an ItemCount value in the oTagValuePairCount parameter, and 0 for the iTagValuePairArraySize parameter. ATSUGetAllLayoutControls returns the size of the tag and value size arrays in the oTagValuePairCount parameter.

    2. Allocate enough space for an array of the returned size, then call the ATSUGetAllLayoutControls function again, passing a valid pointer in the oAttributeInfoArray parameter. On return, the pointer refers to an array of the layout control attribute tag and value size pairs contained in the text layout object.

    To obtain the nondefault line control attribute tags and value sizes for a text layout object, call the function ATSUGetAllLineControls.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains a layout control attribute value for a text layout object.

    Declaration

    Objective-C

    OSStatus ATSUGetLayoutControl ( ATSUTextLayout iTextLayout, ATSUAttributeTag iTag, ByteCount iExpectedValueSize, ATSUAttributeValuePtr oValue, ByteCount *oActualValueSize );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object for which to obtain a layout control attribute value.

    iTag

    An ATSUAttributeTag constant identifying the attribute value to obtain. See Attribute Tags for a description of the Apple-defined attribute tag constants.

    iExpectedValueSize

    The expected size (in bytes) of the value to obtain. To determine the size of an application-defined style attribute value, see the Discussion.

    oValue

    An ATSUAttributeValuePtr pointer, identifying the memory you have allocated for the attribute value. If you are uncertain of how much memory to allocate, see the Discussion. On return, oValue contains a valid pointer to the actual attribute value. If the value is unset, ATSUGetLayoutControl produces the default value in this parameter.

    oActualValueSize

    A pointer to a ByteCount value. On return, the value contains the actual size (in bytes) of the attribute value. You should examine this parameter if you are unsure of the size of the attribute value being obtained.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUGetLayoutControl function obtains the value of a specified layout control attribute for a given text layout object.

    Before calling ATSUGetLayoutControl, you should call the function ATSUGetAllLayoutControls to obtain an array of nondefault layout control attribute tags and value sizes for the text layout object. You can then pass the tag and value size for the attribute value to obtain to ATSUGetLayoutControl.

    Typically you use the function ATSUGetLayoutControl by calling it twice, as follows:

    1. Pass a reference to the text layout object to examine in the iTextLayout parameter, NULL for the oValue parameter, 0 for the iExpectedValueSize parameter. ATSUGetLayoutControl returns the actual size of the attribute value in the oActualValueSize parameter.

    2. Allocate enough space for an array of the returned size, then call the ATSUGetLayoutControl function again, passing a valid pointer in the oValue parameter. On return, the pointer refers to the actual attribute value contained in the text layout object.

    To obtain the value of a line control attribute value for a text layout object, call the function ATSUGetLineControl.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Sets layout control attribute values for a single line in a text layout object.

    Declaration

    Objective-C

    OSStatus ATSUSetLineControls ( ATSUTextLayout iTextLayout, UniCharArrayOffset iLineStart, ItemCount iAttributeCount, const ATSUAttributeTag iTag[], const ByteCount iValueSize[], const ATSUAttributeValuePtr iValue[] );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object for which to set 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 set control attributes.

    iAttributeCount

    An ItemCount value specifying the number of attributes to set. This value should correspond to the number of elements in the iTag and iValueSize arrays.

    iTag

    A pointer to the initial ATSUAttributeTag value in an array of line control attribute tags. Each element in the array must contain a valid tag that corresponds to the line control attribute to set. See Attribute Tags for a description of the Apple-defined line control attribute tag constants.

    iValueSize

    A pointer to the initial ByteCount value in an array of attribute value sizes. Each element in the array must contain the size (in bytes) of the corresponding line control attribute being set. ATSUSetLineControls sets line attributes after confirming the sizes in the array.

    iValue

    A pointer to the initial ATSUAttributeValuePtr value in an array of attribute value pointers. Each value in the array must correspond to a tag in the iTag array and be a legal value for that tag.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    When you use ATSUI to image your text, you can control the text’s display and formatting at a number of different levels. One level is that of the entire text range associated with your text layout object, also known as the “layout level.” To affect display and formatting on this level, you can specify various layout control attributes using the ATSUSetLayoutControls function. These attributes affect the width of the text area from margin to margin, the alignment of the text, its justification, rotation, and direction, as well as other layout options.

    Another level is that of a single line of text, that is, the “line level.” To affect display and formatting on the line level, you specify various line control attributes using the function ATSUSetLineControls. These attributes are similar to those that you can apply on a full-layout basis, but each affects only an individual text line.

    You can break text into lines by calling the functions ATSUBatchBreakLines or ATSUBreakLine. You can define separate lines of text by specifying soft breaks either by

    • calling the function ATSUBatchBreakLines

    • calling the function ATSUBreakLine with the iUseAsSoftBreak parameter set to true

    • specifying the soft line breaks using the function ATSUSetSoftLineBreak

    Given that ATSUI allows you to control similar aspects of the display and formatting of your text at either the line level or the layout level (or both, or neither), it is up to you to decide how much layout control to take. However, you should note the following:

    • Setting layout control attributes overrides the corresponding default layout-level settings for a text layout object. Any layout attributes that you do not set retain the default values described in Attribute Tags.

    • Setting line control attributes overrides the corresponding layout-level settings (whether set or at default values) for a text layout object. This is true even if you set the layout-level attributes subsequently to the line-level ones. Any line attributes that you do not set retain their default values.

    • From a performance standpoint, it is preferable to work from the layout level and not specify layout line by line unless necessary.

    Finally, it is also possible to control the display and formatting of your text at the level of an individual character or “run” of characters. At this level, you customize layout by manipulating style settings in a style object. Among the character-level aspects you can control are style attributes (such as font size and color), font features (such as ligatures), and font variations (such as continually varying font weights or widths). However, there are certain line control attributes (specified via the ATSLineLayoutOptions flags) that can override style attributes applied to the same text.

    Similarly to style attributes, you use a “triple” to specify a line or layout control attribute. That is, an attribute tag, the value of the attribute it sets, and the size (in bytes) of the attribute value. Attribute tags are constants supplied by ATSUI. Attribute values may be a scalar, a structure, or a pointer.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Copies line control attribute settings from a line in a source text layout object to a line in a destination text layout object.

    Declaration

    Objective-C

    OSStatus ATSUCopyLineControls ( ATSUTextLayout iSourceTextLayout, UniCharArrayOffset iSourceLineStart, ATSUTextLayout iDestTextLayout, UniCharArrayOffset iDestLineStart );

    Parameters

    iSourceTextLayout

    An ATSUTextLayout value specifying the text layout object from which to copy line control attributes.

    iSourceLineStart

    A UniCharArrayOffset value specifying the offset from the beginning of the text layout object’s text buffer to the first character of the line from which to copy control attributes.

    iDestTextLayout

    An ATSUTextLayout value specifying the text layout object for which to set line control attributes. This can be the same text layout object passed in the iSourceTextLayout parameter if you want to copy line control attributes from one line to another within a text layout object.

    iDestLineStart

    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 set control attributes.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUCopyLineControls function copies all line control attribute values to a line in a destination text layout object from a line in a source text layout object, including any default (unset) values in the source line. Unset line control attributes are assigned the default values described in Attribute Tags.

    ATSUCopyLineControls does not copy the contents of memory referenced by pointers within reference constants. You are responsible for ensuring that this memory remains valid until the source text layout object is disposed.

    To copy layout control attributes from one text layout object to another, call the function ATSUCopyLayoutControls.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains an array of line control attribute tags and value sizes for a line in a text layout object.

    Declaration

    Objective-C

    OSStatus ATSUGetAllLineControls ( ATSUTextLayout iTextLayout, UniCharArrayOffset iLineStart, ATSUAttributeInfo oAttributeInfoArray[], ItemCount iTagValuePairArraySize, ItemCount *oTagValuePairCount );

    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 line for which to obtain line control attribute values.

    oAttributeInfoArray

    A pointer to memory you have allocated for an array of ATSUAttributeInfo values. On return, the array contains pairs of tags and value sizes for the object’s line control attributes that are not at default values. If you are uncertain of how much memory to allocate for this array, see the Discussion.

    iTagValuePairArraySize

    An ItemCount value specifying the maximum number of tag and value size pairs to obtain for the line. Typically, this is equivalent to the number of ATSUAttributeInfo structures for which you have allocated memory in the oAttributeInfoArray parameter. To determine this value, see the Discussion.

    oTagValuePairCount

    A pointer to an ItemCount value. On return, the value specifies the actual number of ATSUAttributeInfo structures in the line. This may be greater than the value you specified in the iTagValuePairArraySize parameter.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUGetAllLineControls function obtains all nondefault line control attribute tags and their values sizes for a line in a text layout object. You can pass a tag and value size pair obtained from ATSUGetAllLineControls to the function ATSUGetLineControl to determine the corresponding attribute value.

    Typically you use the function ATSUGetAllLineControls by calling it twice, as follows:

    1. Pass a reference to the text layout object to examine in the iTextLayout parameter, the appropriate UniCharArrayOffset value in the iLineStart parameter, NULL for the oAttributeInfoArray parameter, a pointer to an ItemCount value in the oTagValuePairCount parameter, and 0 for the iTagValuePairArraySize parameter. ATSUGetAllLineControls returns the size of the tag and value size arrays in the oTagValuePairCount parameter.

    2. Allocate enough space for an array of the returned size, then call the ATSUGetAllLineControls function again, passing a valid pointer in the oAttributeInfoArray parameter. On return, the pointer refers to an array of the line control attribute tag and value size pairs contained in the specified line.

    To obtain the nondefault layout control attribute tags and value sizes for a text layout object, call the function ATSUGetAllLayoutControls.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains a line control attribute value for a line in a text layout object.

    Declaration

    Objective-C

    OSStatus ATSUGetLineControl ( ATSUTextLayout iTextLayout, UniCharArrayOffset iLineStart, ATSUAttributeTag iTag, ByteCount iExpectedValueSize, ATSUAttributeValuePtr oValue, ByteCount *oActualValueSize );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object for which to obtain a line control attribute value.

    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 obtain a line control attribute value.

    iTag

    An ATSUAttributeTag constant identifying the attribute value to obtain. See Attribute Tags for a description of the Apple-defined attribute tag constants.

    iExpectedValueSize

    The expected size (in bytes) of the value to obtain.

    oValue

    An ATSUAttributeValuePtr pointer, identifying the memory you have allocated for the attribute value. If you are uncertain of how much memory to allocate, see the Discussion. On return, oValue contains a valid pointer to the actual attribute value. If the value is unset, ATSUGetLineControl produces the default value in this parameter.

    oActualValueSize

    A pointer to a ByteCount value. On return, the value contains the actual size (in bytes) of the attribute value. You should examine this parameter if you are unsure of the size of the attribute value being obtained.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUGetLineControl function obtains the value of a specified line control attribute for a given line of text in a text layout object.

    Before calling ATSUGetLineControl, you should call the function ATSUGetAllLineControls to obtain an array of nondefault line control attribute tags and value sizes for the line. You can then pass the tag and value size for the attribute value to obtain to ATSUGetLineControl.

    To obtain the value of a layout control attribute value for a text layout object, call the function ATSUGetLayoutControl.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Sets a soft line break that you specify.

    Declaration

    Objective-C

    OSStatus ATSUSetSoftLineBreak ( ATSUTextLayout iTextLayout, UniCharArrayOffset iLineBreak );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object for which to set a line break.

    iLineBreak

    A UniCharArrayOffset value specifying the offset from the beginning of the text layout object’s text buffer to the line break to set.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUSetSoftLineBreak function enables you to set a soft line break in a text range. You should typically only call ATSUSetSoftLineBreak to set line breaks when you are using your own line-breaking algorithm to calculate these breaks. For optimal performance, you should use ATSUBatchBreakLines to both calculate and set soft line breaks in your text.

    After calling ATSUSetSoftLineBreak, you should call the function ATSUGetUnjustifiedBounds to determine whether the characters still fit within the line, which is necessary due to end-of-line effects such as swashes.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains soft line breaks in a range of text.

    Declaration

    Objective-C

    OSStatus ATSUGetSoftLineBreaks ( ATSUTextLayout iTextLayout, UniCharArrayOffset iRangeStart, UniCharCount iRangeLength, ItemCount iMaximumBreaks, UniCharArrayOffset oBreaks[], ItemCount *oBreakCount );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object to examine.

    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 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 iRangeLength parameter.

    iRangeLength

    A UniCharCount value specifying the length of the text range. If you want the range of text to extend to the end of the text buffer, you can pass the constant kATSUToTextEnd.

    iMaximumBreaks

    An ItemCount value specifying the maximum number of soft line breaks to obtain. Typically, this is equivalent to the number of UniCharArrayOffset values for which you have allocated memory in the oBreaks array. To determine this value, see the Discussion.

    oBreaks

    A pointer to memory you have allocated for an array of UniCharArrayOffset values. On return, the array contains offsets from the beginning of the text buffer to each of the soft line breaks in the text range. If you are uncertain of how much memory to allocate for this array, see the Discussion.

    oBreakCount

    A pointer to an ItemCount value. On return, the value specifies the actual number of soft line breaks in the range of text. This may be greater than the value you specified in the iMaximumBreaks parameter.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUGetSoftLineBreaks function obtains the soft line breaks that are currently set in a given text range.

    Typically you use the function ATSUGetSoftLineBreaks by calling it twice, as follows:

    1. Pass valid values for the iTextLayout, iRangeStart, iRangeLength, and oBreakCount parameters. Pass NULL for the oBreaks parameter and 0 for the iMaximumBreaks parameter. On return, the value of the oBreakCount parameter specifies the number of items in the offset array.

    2. Allocate enough space for an array of the appropriate size (number of items in the array multiplied by 4 bytes per item), then call the function again, passing a valid pointer in the oBreaks parameter. On return, the pointer refers to an array containing the text range’s soft line breaks.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Removes soft line breaks from a range of text.

    Declaration

    Objective-C

    OSStatus ATSUClearSoftLineBreaks ( ATSUTextLayout iTextLayout, UniCharArrayOffset iRangeStart, UniCharCount iRangeLength );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object for which to remove 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 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 iRangeLength parameter.

    iRangeLength

    A UniCharCount value specifying the length of the text range. If you want the range of text to extend to the end of the text buffer, you can pass the constant kATSUToTextEnd.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUClearSoftLineBreaks function clears all previously set soft line breaks for the specified text range and clears any associated layout caches as well.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Examines a text range for characters that cannot be drawn with the current font and suggests a substitute font, if necessary.

    Declaration

    Objective-C

    OSStatus ATSUMatchFontsToText ( ATSUTextLayout iTextLayout, UniCharArrayOffset iTextStart, UniCharCount iTextLength, ATSUFontID *oFontID, UniCharArrayOffset *oChangedOffset, UniCharCount *oChangedLength );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object to examine.

    iTextStart

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

    iTextLength

    A UniCharCount value specifying the length of the text range to examine. If you want the range of text to extend to the end of the text buffer, you can pass the constant kATSUToTextEnd.

    oFontID

    A pointer to a ATSUFontID value. On return, the value provides a font ID for the suggested substitute font or kATSUInvalidFontID, if no substitute font is available.

    oChangedOffset

    A pointer to a UniCharArrayOffset value. On return, this value specifies the offset from the beginning of the text buffer to the first character that cannot be drawn with the current font.

    oChangedLength

    A pointer to a UniCharCount value. On return, this value specifies the length of the text range that cannot be drawn with the current font.

    Return Value

    A result code. See ATSUI Result Codes. The result code noErr indicates that all the characters in the given range can be rendered with their current font(s) and no font substitution is needed. If you receive either of the result codes kATSUFontsMatched or kATSUFontsNotMatched, you should update the input range and call ATSUMatchFontsToText again to ensure that all the characters in the range can be drawn.

    Discussion

    When you call the ATSUMatchFontsToText function, ATSUI scans the given range of text for characters that cannot be drawn with the currently assigned font. When ATSUI finds such a character, it identifies a substitute font for drawing the character. ATSUI then continues scanning the text range for subsequent characters that cannot be drawn, stopping when it

    • finds a character that can be drawn with the currently assigned font, or

    • finds a character that cannot be drawn with either the currently assigned font or the substitute font, or

    • reaches the end of the text range you have specified

    ATSUI’s default behavior for finding a substitute font is to recommend the first valid font that it finds when scanning the fonts in the user’s system. ATSUI first searches in the standard application fonts for various languages. If that fails, ATSUI searches through the remaining fonts on the system in the order in which the Font Manager returns the fonts. After ATSUI has searched all the fonts in the system, any unmatched text is drawn using the last-resort font. That is, missing glyphs are represented by and empty box to indicate to the user that a valid font for that character is not installed on their system. You can alter ATSUI’s default search behavior by calling the function ATSUCreateFontFallbacks and defining your own font fallback settings for the text layout object.

    So, for example, if the subrange of text for which you wanted to perform font substitution was the text “abcde”, and the characters ‘c’ and ‘d’ could not be drawn with the current font, but could be drawn with font X, and the character ‘e’ either could be drawn with the current font or could not be drawn with font X, then ATSUMatchFontsToText produces the ID of font X in the oFont parameter and sets the oChangedOffset parameter to 2 and the oChangedLength parameter to 2.

    Because ATSUI does not necessarily completely scan the text range you specify with each call to ATSUMatchFontsToText, if ATSUI does find any characters that cannot be rendered with their current font, you should call ATSUMatchFontsToText again and update the input range to check that all the subsequent characters in the range can be drawn. For that reason, you should call ATSUMatchFontsToText from within a loop to assure that the entire range of text is checked.

    Note that calling ATSUMatchFontsToText does not cause the suggested font substitution to be performed. If you want ATSUI to perform font substitution for you, you can call the function ATSUSetTransientFontMatching.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Turns automatic font substitution on or off for a text layout object.

    Declaration

    Objective-C

    OSStatus ATSUSetTransientFontMatching ( ATSUTextLayout iTextLayout, Boolean iTransientFontMatching );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object for which to set automatic font substitution on or off.

    iTransientFontMatching

    A Boolean value indicating whether ATSUI is to perform automatic font substitution for the text layout object. If you pass true, ATSUI performs automatic font substitution for the text range associated with the text layout object.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    Calling the ATSUSetTransientFontMatching function sets ATSUI’s automatic font substitution to on or off for a given text layout object. When automatic font substitution is on, ATSUI scans the text range associated with specified text layout object looking for undrawable characters whenever a layout is performed, for example, when text is measured or drawn. When ATSUI finds a character that cannot be drawn with the currently assigned font, it identifies a valid font for the character and draws the character. ATSUI continues scanning the text range for characters in need of substitute fonts, replacing the font and redrawing the characters as needed. ATSUI stops scanning when it reaches the end of the text range associated with the text layout object.

    ATSUI’s default behavior for finding a substitute font is to use the first valid font that it finds when sequentially scanning the fonts in the user’s system. However, you can alter this behavior by calling the function ATSUCreateFontFallbacks and defining your own font fallback settings for the text layout object. If ATSUI cannot find any suitable replacement fonts, it substitutes the missing-character glyph—that is, a glyph representing an empty box—to indicate to the user that a valid font is not installed on their system.

    Note that when ATSUSetTransientFontMatching performs font substitution, it does not change the font attribute in the associated style object. That is, the font attribute for the style object associated with the redrawn character(s) remains set to the invalid font—not the valid substitute font— just as it was prior to calling ATSUSetTransientFontMatching.

    If you want ATSUI to identify a substitute font, but you do not want ATSUI to automatically perform the font substitution, you can call the function ATSUMatchFontsToText.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Obtains whether ATSUI automatically performs font substitution for a text layout object.

    Declaration

    Objective-C

    OSStatus ATSUGetTransientFontMatching ( ATSUTextLayout iTextLayout, Boolean *oTransientFontMatching );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object to examine.

    oTransientFontMatching

    A pointer to a Boolean value. On return, the value indicates whether ATSUI performs automatic font substitution for the text layout object. If true, ATSUI automatically performs font substitution for the text range associated with the text layout object.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    You can call the ATSUGetTransientFontMatching function to find out whether ATSUI automatically performs font substitution for a given text layout object when a character cannot be drawn with the assigned font. To turn automatic font substitution on or off for a text layout object, call the function ATSUSetTransientFontMatching.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Creates an opaque object that can be set to contain a font list and a font-search method.

    Declaration

    Objective-C

    OSStatus ATSUCreateFontFallbacks ( ATSUFontFallbacks *oFontFallback );

    Parameters

    oFontFallback

    A pointer to an ATSUFontFallbacks value. On return, the pointer refers to a newly created font fallback object.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUCreateFontFallbacks function creates an “empty” font fallback object, which can be used to define ATSUI’s search behavior when seeking substitute fonts for a text layout object. Font fallback objects are thread safe and can be shared among threads.

    You set the font list and search method for the font fallback 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. You pass these functions the control attribute value kATSULineFontFallbacksTag to set the font fallback object.

    Similarly to a style object, a font fallback object can be used with any number of text layout objects. While it is innately more efficient to reuse font fallback objects, instead of repeatedly creating (and destroying) them, there is another reason to share a given font fallback object among text layout objects. That is, as a font fallback object is used, it continues to amass data about the system’s fonts and which are best applied to the various ranges of Unicode. Therefore, for best performance, once you create a font fallback object, you should keep it and use it as often as needed.

    You should dispose of a font fallback object only when it is no longer needed in your application. To dispose of the memory associated with a font fallback object, call the function ATSUDisposeFontFallbacks.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.1 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Assigns a font list and a font-search method to a font fallback object.

    Declaration

    Objective-C

    OSStatus ATSUSetObjFontFallbacks ( ATSUFontFallbacks iFontFallbacks, ItemCount iFontFallbacksCount, const ATSUFontID iFonts[], ATSUFontFallbackMethod iFontFallbackMethod );

    Parameters

    iFontFallbacks

    An ATSUFontFallbacks value specifying the font fallback object for which to define settings.

    iFontFallbacksCount

    An ItemCount value specifying the number of fonts that ATSUI is to search. This value is typically equal to the number of font IDs you are providing in the iFonts array.

    iFonts

    A pointer to the first ATSUFontID value in an array of font IDs identifying the fonts ATSUI is to search.

    iFontFallbackMethod

    An ATSUFontFallbackMethod value identifying the order in which ATSUI is to search. See Font Fallback Methods for a description of possible values.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUSetObjFontFallbacks function defines the settings for a font fallback object. These settings determine the font list and search order that ATSUI uses when seeking substitute fonts for the text layout object with which the font fallback object is associated.

    Creating, defining settings for, and associating a font fallback object with a text layout object is the only way to ensure that ATSUI uses your preferred font fallback settings for your text. To create a font fallback object, you first call the function ATSUCreateFontFallbacks. You then define settings for the object by calling the ATSUSetObjFontFallbacks function. To associate the font fallback object with a text layout object call the function ATSUSetLayoutControls. You pass these functions the control attribute value kATSULineFontFallbacksTag to set the font fallback object.

    If you do not call ATSUSetObjFontFallbacks to change ATSUI’s default search behavior, ATSUI searches all the fonts on the system sequentially and uses the first valid font it finds for a substitute. If you are careful in ordering the fonts that you supply to ATSUSetObjFontFallbacks, you can minimize the time ATSUI needs to find a substitute font.

    Font fallback settings affect the behavior of the function ATSUMatchFontsToText and of font selection during layout and drawing when the function ATSUSetTransientFontMatching is set to on.

    To obtain the font list and font-search method associated with a font fallback object, call the function ATSUGetObjFontFallbacks.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.1 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the font list and font-search method associated with a font fallback object.

    Declaration

    Objective-C

    OSStatus ATSUGetObjFontFallbacks ( ATSUFontFallbacks iFontFallbacks, ItemCount iMaxFontFallbacksCount, ATSUFontID oFonts[], ATSUFontFallbackMethod *oFontFallbackMethod, ItemCount *oActualFallbacksCount );

    Parameters

    iFontFallbacks

    An ATSUFontFallbacks value specifying the font fallback object to examine.

    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 oFonts parameter. To determine this value, see the Discussion.

    oFonts

    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 in the font list associated with the font fallback object.

    oFontFallbackMethod

    A pointer to an ATSUFontFallbackMethod value. On return, the value identifies the font-search method associated with the font fallback object. 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 in the font list associated with the text layout object. This value may be greater than that passed in the iMaxFontFallbacksCount parameter.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUGetObjFontFallbacks function obtains the list of fonts and the search order associated with a given font fallback object.

    Typically you use the function ATSUGetObjFontFallbacks by calling it twice, as follows:

    1. Pass valid values for the iFontFallbacks and oActualFallbacksCount parameters, NULL for the oFonts and oFontFallbackMethod parameters and 0 for the iMaxFontFallbacksCount parameter. ATSUGetObjFontFallbacks returns the size of the font array in the oActualFallbacksCount parameter.

    2. Allocate enough space for an array of the returned size, then call the function again, passing a valid pointer in the oFonts parameter. On return, the array contains the font list associated with the font fallback object.

    You set the font list and search method for a font fallback object by calling the function ATSUSetObjFontFallbacks.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.1 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Disposes of the memory associated with a font fallback object.

    Declaration

    Objective-C

    OSStatus ATSUDisposeFontFallbacks ( ATSUFontFallbacks iFontFallbacks );

    Parameters

    iFontFallbacks

    An ATSUFontFallbacks value specifying the font fallback object to dispose. See the ATSUFontFallbacks data type.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUDisposeFontFallbacks function frees the memory associated with the specified font fallback object and its internal structures.

    For best performance, once you create a font fallback object, you should keep it and use it as often as needed. You should dispose of the font fallback object only when it is no longer needed in your application.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.1 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains a list of all the ATSUI-compatible fonts installed on the user’s system.

    Declaration

    Objective-C

    OSStatus ATSUGetFontIDs ( ATSUFontID oFontIDs[], ItemCount iArraySize, ItemCount *oFontCount );

    Parameters

    oFontIDs

    A pointer to memory you have allocated for an array of ATSUFontID values. On return, the array contains unique identifiers for each of the ATSUI-compatible fonts installed on the user’s system. You should allocate enough memory to contain an array the size of the count produced by the function ATSUFontCount.

    iArraySize

    An ItemCount value specifying the maximum number of fonts to obtain. Typically, this is equivalent to the number of ATSUFontID values for which you have allocated memory in the oFontIDs parameter.

    oFontCount

    A pointer to an ItemCount value. On return, the value specifies the actual number of ATSUI-compatible fonts installed on the user’s system. This may be greater than the value you specified in the iArraySize parameter.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUGetFontIDs function obtains the IDs of all the fonts on the user’s system except for the last-resort font. It is important to note that the set of installed ATSUI-compatible fonts may change while your application is running. In Mac OS X, the set of installed fonts may change at any time. Although in Mac OS 9, fonts cannot be removed from the Fonts folder while an application other than the Finder is running, they can be removed from other locations, and it is possible for fonts to be added.

    To ensure an accurate representation of the set of installed ATSUI-compatible fonts, you should call ATSUGetFontIDs to rebuild your font menu each time your application is brought to the foreground.

    Finally, note that Apple Type Services assigns ATSUFontID values systemwide at runtime. As a result, these font IDs can change across system restarts.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the number of ATSUI-compatible fonts installed on a user’s system.

    Declaration

    Objective-C

    OSStatus ATSUFontCount ( ItemCount *oFontCount );

    Parameters

    oFontCount

    A pointer to an ItemCount value. On return, the value specifies the current number of ATSUI-compatible fonts installed on the user’s system.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUFontCount function obtains the number of fonts on a user’s system that are compatible with ATSUI. Incompatible fonts include those that cannot be used to represent Unicode, the missing-character glyph font, and fonts whose names begin with a period or a percent sign. You can use the count produced in the oFontCount parameter to determine the amount of memory to allocate for the oFontIDs array in the function ATSUGetFontIDs.

    It is important to note that the set of installed ATSUI-compatible fonts may change while your application is running. In Mac OS X, the set of installed fonts may change at any time. Although in Mac OS 9, fonts cannot be removed from the Fonts folder while an application other than the Finder is running, they can be removed from other locations, and it is possible for fonts to be added.

    Additionally, just because the number of fonts stays the same between two successive calls to ATSUFontCount, this does not mean that the font lists are the same. It is possible for a font to be added and another removed between two successive calls to ATSUFontCount, leaving the total number unchanged.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains a name string and index value for the first font in a name table that matches the specified ATSUI font ID, name code, platform, script, and/or language.

    Declaration

    Objective-C

    OSStatus ATSUFindFontName ( ATSUFontID iFontID, FontNameCode iFontNameCode, FontPlatformCode iFontNamePlatform, FontScriptCode iFontNameScript, FontLanguageCode iFontNameLanguage, ByteCount iMaximumNameLength, Ptr oName, ByteCount *oActualNameLength, ItemCount *oFontNameIndex );

    Parameters

    iFontID

    The ATSUFontID value of the font for which to obtain a name string. Note that because Apple Type Services assigns ATSUFontID values systemwide at runtime, font IDs can change across system restarts.

    iFontNameCode

    The FontNameCode value of the font for which to obtain a name string. The FontNameCode is a UInt32 data type, and it is defined in the SFNTTypes.h header file.

    iFontNamePlatform

    A FontPlatformCode value specifying the encoding of the font, for example, kFontUnicodePlatform, kFontMacintoshPlatform, kFontReservedPlatform, kFontMicrosoftPlatform, or kFontCustomPlatform. If you pass the kFontNoPlatformCode constant, ATSUFindFontName produces the first font in the name table matching the other specified parameters. See the SFNTTypes.h header file for a definition of the FontPlatformCode type and a list of possible values.

    iFontNameScript

    A FontScriptCode value specifying the script code of the font, for example, kFontRomanScript. If you pass the kFontNoScriptCode constant, ATSUFindFontName produces the first font in the name table matching the other specified parameters. See the SFNTTypes.h header file for a definition of the FontScriptCode type and a list of possible values.

    iFontNameLanguage

    A FontLanguageCode value specifying the language of the font, for example, kFontNorwegianLanguage. If you pass the kFontNoLanguageCode constant, ATSUFindFontName produces the first font in the name table matching the other specified parameters. See the SFNTTypes.h header file for a definition of the FontLanguageCode type and a list of possible values.

    iMaximumNameLength

    A ByteCount value specifying the maximum length of the font name to obtain. Typically, this is equivalent to the size of the buffer that you have allocated in the oName parameter. To determine this length, see the Discussion.

    oName

    A pointer to a buffer. On return, the buffer contains the name string of the first font in the font name table matching your specified parameters. If the buffer you allocate is not large enough, ATSUFindFontName produces a partial string.

    oActualNameLength

    A pointer to a ByteCount value. On return, the value specifies the actual length of the complete name string. This may be greater than the value passed in the iMaximumNameLength parameter. You should check this value to ensure that you have allocated sufficient memory and therefore obtained the complete name string for the font.

    oFontNameIndex

    A pointer to an ItemCount value. On return, the value provides a 0-based index to the font name in the font name table.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUFindFontName function obtains a name string and index value for the first font in a name table that matches the specified ATSUI font ID, name code, platform, script, and/or language.

    Typically you use the ATSUFindFontName function by calling it twice, as follows:

    1. Pass NULL for the oName and oFontNameIndex parameters, 0 for the iMaximumNameLength parameter, and valid values for the other parameters. ATSUFindFontName returns the length of the font name string in the oActualNameLength parameter.

    2. Allocate enough space for a buffer of the returned size, then call the function again, passing a valid pointer to the buffer in the oName parameter. On return, the buffer contains the font name string.

    To obtain an ATSUI font ID for the first font in a name table that matches the specified name string, name code, platform, script, and/or language, call the function ATSUFindFontFromName. To obtain the font name string, name code, platform, script, and language for the font that matches an ATSUI font ID and name table index, call the function ATSUGetIndFontName.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains an ATSUI font ID for the first entry in a name table that matches the specified name string, name code, platform, script, and/or language.

    Declaration

    Objective-C

    OSStatus ATSUFindFontFromName ( const void *iName, ByteCount iNameLength, FontNameCode iFontNameCode, FontPlatformCode iFontNamePlatform, FontScriptCode iFontNameScript, FontLanguageCode iFontNameLanguage, ATSUFontID *oFontID );

    Parameters

    iName

    A string that specifies the font name whose ATSUI font ID you want to obtain. The string that you pass must be appropriate for the value you pass in the iFontNameCode parameter. For example, if the iFontNameCode parameter is kFontPostscriptName, then you would supply a string that specifies the PostScript name of the font.

    iNameLength

    A ByteCount value specifying the length of the font name string provided in the iName parameter.

    iFontNameCode

    The FontNameCode value of the font name for which to obtain an ATSUI font ID. The FontNameCode is a UInt32 data type, and it is defined in the SFNTTypes.h header file. You can supply any of the following constants, kFontCopyrightName, kFontFamilyName, kFontStyleName, kFontUniqueName, kFontFullName, kFontVersionName, kFontPostscriptName, kFontTrademarkName, kFontManufacturerName, kFontDesignerName, kFontDescriptionName, kFontVendorURLName, kFontDesignerURLName, kFontLicenseDescriptionName,or kFontLicenseInfoURLName.

    iFontNamePlatform

    A FontPlatformCode value specifying the encoding of the font name, for example, kFontUnicodePlatform (for UTF-16), kFontMacintoshPlatform, kFontReservedPlatform, kFontMicrosoftPlatform, or kFontCustomPlatform. If you pass the kFontNoPlatformCode constant, ATSUFindFontFromName produces the first font in the name table matching the other specified parameters. See the SFNTTypes.h header file for a definition of the FontPlatformCode type and a list of possible values.

    iFontNameScript

    A FontScriptCode value specifying the script code of the font name, for example, kFontRomanScript. Pass kFontNoScriptCode if you supplied the kFontUnicodePlatform constant for the iFontNamePlatform parameter. If you pass the kFontNoScriptCode constant, ATSUFindFontFromName produces the first font in the name table matching the other specified parameters. See the SFNTTypes.h header file for a definition of the FontScriptCode type and a list of possible values.

    iFontNameLanguage

    A FontLanguageCode value specifying the language of the font name, for example, kFontNorwegianLanguage. Pass kFontNoLanguageCode if you supplied the kFontUnicodePlatform constant for the iFontNamePlatform parameter. If you pass the kFontNoLanguageCode constant, ATSUFindFontFromName produces the first font in the name table matching the other specified parameters. See the SFNTTypes.h header file for a definition of the FontLanguageCode type and a list of possible values.

    oFontID

    On return, points to the unique identifier for the specified font that matches the specified name string, name code, platform, script, and/or language. Note that because Apple Type Services assigns ATSUFontID values systemwide at runtime, font IDs can change across system restarts.

    Return Value

    A result code. If no installed font matches the specified parameters, ATSUFindFontFromName produces the constant kATSUInvalidFontID and returns the result code kATSUInvalidFontErr. See ATSUI Result Codes.

    Discussion

    The ATSUFindFontFromName function obtains an ATSUI font ID for the first font that matches the specified name string, name code, platform, script, and/or language. Because ATSUI cannot guarantee the uniqueness of names among installed fonts, ATSUFindFontFromName does not necessarily find the only font ID that matches these parameters. As a result, you may want to create a more sophisticated name-matching algorithm or guarantee the uniqueness of names among installed fonts.

    To find a name string and index value for the first font in a name table that matches an ATSUI font ID and the specified font parameters, call the function ATSUFindFontName.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains a name string, name code, platform, script, and language for the font that matches an ATSUI font ID and name table index value.

    Declaration

    Objective-C

    OSStatus ATSUGetIndFontName ( ATSUFontID iFontID, ItemCount iFontNameIndex, ByteCount iMaximumNameLength, Ptr oName, ByteCount *oActualNameLength, FontNameCode *oFontNameCode, FontPlatformCode *oFontNamePlatform, FontScriptCode *oFontNameScript, FontLanguageCode *oFontNameLanguage );

    Parameters

    iFontID

    The ATSUFontID value of the font for which to obtain information. Note that because Apple Type Services assigns ATSUFontID values systemwide at runtime, font IDs can change across system restarts.

    iFontNameIndex

    An ItemCount value providing an index to the font for which to obtain information. Because this index must be 0-based, you should pass a value between 0 and one less than the count produced by the function ATSUCountFontNames.

    iMaximumNameLength

    A ByteCount value specifying the maximum length of the font name string to obtain. Typically, this is equivalent to the size of the buffer that you have allocated in the oName parameter. To determine this length, see the Discussion.

    oName

    A pointer to a buffer. On return, the buffer contains the name string of the font matching the ATSUI font ID and name table index value being passed. If the buffer you allocate is not large enough to contain the name string, ATSUGetIndFontName produces a partial string.

    oActualNameLength

    A pointer to a ByteCount value. On return, the value specifies the actual length of the complete name string. This may be greater than the value passed in the iMaximumNameLength parameter. You should check this value to ensure that you have allocated sufficient memory and therefore obtained the complete name string for the font.

    oFontNameCode

    A pointer to a FontNameCode value. On return, the value contains the name code for the font. The FontNameCode is a UInt32 data type, and it is defined in the SFNTTypes.h header file. ATSUI can return any of the following constants, kFontCopyrightName, kFontFamilyName, kFontStyleName, kFontUniqueName, kFontFullName, kFontVersionName, kFontPostscriptName, kFontTrademarkName, kFontManufacturerName, kFontDesignerName, kFontDescriptionName, kFontVendorURLName, kFontDesignerURLName, kFontLicenseDescriptionName, or kFontLicenseInfoURLName.

    oFontNamePlatform

    A pointer to a FontPlatformCode value. On return, this value specifies the encoding of the font, for example, kFontUnicodePlatform, kFontMacintoshPlatform, kFontReservedPlatform, kFontMicrosoftPlatform, or kFontCustomPlatform. See the SFNTTypes.h header file for a definition of the FontPlatformCode type and a list of possible values.

    oFontNameScript

    A pointer to a FontScriptCode value. On return, this value specifies the script code of the font, for example, kFontRomanScript. See the SFNTTypes.h header file for a definition of the FontScriptCode type and a list of possible values.

    oFontNameLanguage

    A pointer to a FontLanguageCode value. On return, this value specifies the language of the font, for example, kFontNorwegianLanguage. See the SFNTTypes.h header file for a definition of the FontLanguageCode type and a list of possible values.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUGetIndFontName function obtains a name string, name code, language code, script code, and platform code for the font that matches the specified ATSUI font ID and name table index value.

    Typically you use the ATSUGetIndFontName function by calling it twice, as follows:

    1. Pass valid values for the iFontID, iFontNameIndex, and oActualNameLength parameters, 0 for the iMaximumNameLength parameter, and NULL for the other parameters. ATSUGetIndFontName returns the length of the font name string in the oActualNameLength parameter.

    2. Allocate enough space for a buffer of the returned size, then call the function again, passing a valid pointer to the buffer in the oName parameter. On return, the buffer contains the font name string.

    To find a name string and index value for the first font in a name table that matches an ATSUI font ID and the specified font parameters, call the function ATSUFindFontName. To obtain an ATSUI font ID for the first font in a name table that matches the specified name string, name code, platform, script, and/or language, call the function ATSUFindFontFromName.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the number of font names that correspond to a given ATSUI font ID.

    Declaration

    Objective-C

    OSStatus ATSUCountFontNames ( ATSUFontID iFontID, ItemCount *oFontNameCount );

    Parameters

    iFontID

    An ATSUFontID value specifying the font to examine.

    oFontNameCount

    A pointer to an ItemCount value. On return, the value specifies the number of entries in the font name table corresponding to the given ATSUI font ID.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUCountFontNames function obtains the number of font names defined in a font name table for a given ATSUI font ID. This number includes repetitions of the same name in different platforms, languages, and scripts; names of font features, variations, tracking settings, and instances for the font; and font names identified by name code constants.

    You can pass an index value based on this count to the function ATSUGetIndFontName to obtain a name string, name code, platform, script, and language for a given ATSUI font ID.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the name code and tracking value for the font tracking that matches an ASTUI font ID, glyph orientation, and tracking table index.

    Declaration

    Objective-C

    OSStatus ATSUGetIndFontTracking ( ATSUFontID iFontID, ATSUVerticalCharacterType iCharacterOrientation, ItemCount iTrackIndex, Fixed *oFontTrackingValue, FontNameCode *oNameCode );

    Parameters

    iFont

    The ATSUFontID value of the font tracking for which to obtain a name code and tracking value. Note that because Apple Type Services assigns ATSUFontID values systemwide at runtime, font IDs can change across system restarts.

    iCharacterOrientation

    An ATSUVerticalCharacterType constant identifying the glyph orientation of the font tracking value to obtain, for example kATSUStronglyHorizontal or kATSUStronglyVertical. See Vertical Character Types for a description of possible values.

    iTrackIndex

    An ItemCount value providing an index to the font tracking for which to obtain information. Because this index must be 0-based, you should pass a value between 0 and one less than the count produced by the function ATSUCountFontTracking.

    oFontTrackingValue

    A pointer to a Fixed value. On return, the value contains the font tracking value.

    oNameCode

    A pointer to a FontNameCode value. On return, the value contains the name code for the font tracking. The FontNameCode is a UInt32 data type, and it is defined in the SFNTTypes.h header file.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    You can call the ATSUGetIndFontTracking function to obtain the name code and tracking value that matches the specified ATSUI font ID, glyph orientation, and tracking table index value.

    You can use the function ATSUFindFontName to obtain the localized name string for the name code produced by ATSUGetIndFontTracking.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the number of entries in the font tracking table that correspond to a given ATSUI font ID and glyph orientation.

    Declaration

    Objective-C

    OSStatus ATSUCountFontTracking ( ATSUFontID iFontID, ATSUVerticalCharacterType iCharacterOrientation, ItemCount *oTrackingCount );

    Parameters

    iFont

    An ATSUFontID value specifying the font to examine.

    iCharacterOrientation

    An ATSUVerticalCharacterType constant identifying the glyph orientation of the font tracking entries, for example kATSUStronglyHorizontal or kATSUStronglyVertical. See Vertical Character Types for a description of possible values.

    oTrackingCount

    A pointer to an ItemCount value. On return, the value specifies the number of entries in the font tracking table corresponding to the given ATSUI font ID and glyph orientation.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUCountFontTracking function obtains the number of font tracking entries defined in a font tracking table for a given ATSUI font ID and glyph orientation. You can pass an index value based on this count to the function ATSUGetIndFontTracking to obtain the name code and tracking value of a font tracking.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the name code for a font’s feature type or selector that matches an ASTUI font ID, feature type, and feature selector.

    Declaration

    Objective-C

    OSStatus ATSUGetFontFeatureNameCode ( ATSUFontID iFontID, ATSUFontFeatureType iType, ATSUFontFeatureSelector iSelector, FontNameCode *oNameCode );

    Parameters

    iFont

    The ATSUFontID value of the font for which to obtain the name code for a feature type or selector. Note that because Apple Type Services assigns ATSUFontID values systemwide at runtime, font IDs can change across system restarts.

    iType

    An ATSUFontFeatureType constant identifying a valid feature type. To obtain the valid feature types for a font, call the function ATSUGetFontFeatureTypes.

    iSelector

    An ATSUFontFeatureSelector constant identifying a valid feature selector that corresponds to the feature type passed in the iType parameter. If you pass the constant kATSUNoSelector, the name code produced by ATSUGetFontFeatureNameCode is that of the feature type, not the feature selector. To obtain the valid feature selectors for a font, call the functionATSUGetFontFeatureSelectors.

    oNameCode

    A pointer to a FontNameCode value. On return, the value contains the name code for the font feature selector or type. The FontNameCode is a UInt32 data type, and it is defined in the SFNTTypes.h header file.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUGetFontFeatureNameCode function obtains the name code for a font’s feature type or selector that matches an ASTUI font ID, feature type and feature selector values. By default, ATSUGetFontFeatureNameCode function obtains the name code of a feature selector. To determine the name code of a feature type, pass the constant kATSUNoSelector in the iSelector parameter.

    You can use the function ATSUFindFontName to obtain the localized name string for the name code produced by ATSUGetFontFeatureNameCode.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the name code for the font variation that matches an ASTUI font ID and font variation axis.

    Declaration

    Objective-C

    OSStatus ATSUGetFontVariationNameCode ( ATSUFontID iFontID, ATSUFontVariationAxis iAxis, FontNameCode *oNameCode );

    Parameters

    iFont

    The ATSUFontID value of the font for which to obtain a font variation name code. Note that because Apple Type Services assigns ATSUFontID values systemwide at runtime, font IDs can change across system restarts.

    iAxis

    An ATSUFontVariationAxis value representing a valid variation axis tag. To obtain a valid variation axis tag for a font, you can call the functionsATSUGetIndFontVariation or ATSUGetFontInstance.

    oNameCode

    A pointer to a FontNameCode value. On return, the value contains the name code for the font variation. The FontNameCode is a UInt32 data type, and it is defined in the SFNTTypes.h header file.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUGetFontVariationNameCode function obtains the name code for the font variation that matches an ASTUI font ID and font variation axis tag. You can use the function ATSUFindFontName to obtain the localized name string for the name code produced by ATSUGetFontVariationNameCode.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the name code for the font instance that matches an ASTUI font ID and font instance index value.

    Declaration

    Objective-C

    OSStatus ATSUGetFontInstanceNameCode ( ATSUFontID iFontID, ItemCount iInstanceIndex, FontNameCode *oNameCode );

    Parameters

    iFont

    The ATSUFontID value of the font for which to obtain a font instance name code. Note that because Apple Type Services assigns ATSUFontID values systemwide at runtime, font IDs can change across system restarts.

    iInstanceIndex

    An ItemCount value providing an index to the font instance for which to obtain a name code. Because this index must be 0-based, you should pass a value between 0 and one less than the count produced by the function ATSUCountFontInstances.

    oNameCode

    A pointer to a FontNameCode value. On return, the value contains the name code for the font instance. The FontNameCode is a UInt32 data type, and it is defined in the SFNTTypes.h header file.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    A font instance consists of a named set of values for each variation axis in a font. The ATSUGetFontInstanceNameCode function obtains the name code for the font instance that matches an ASTUI font ID and font instance index value.

    You can use the function ATSUFindFontName to obtain the localized name string for the name code produced by ATSUGetFontInstanceNameCode. You can obtain the font variation axis values for a font instance by calling the functionATSUGetFontInstance.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • ATSUDrawText ATSUDrawText (OS X v10.6)

    Renders a range of text at a specified location in a QuickDraw graphics port or Quartz graphics context.

    Declaration

    Objective-C

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

    Parameters

    iTextLayout

    An ATSUTextLayout value identifying the text layout object for which to render text.

    iLineOffset

    A UniCharArrayOffset value specifying the offset from the beginning of the text buffer to the first character of the range to render. The function ATSUDrawText renders text to the first soft line break it encounters. If the range of text spans multiple lines, you should call ATSUDrawText for each line, passing the offset corresponding to the beginning of the new line to draw with each call. 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 iLineLength parameter.

    iLineLength

    A UniCharCount value specifying the length of the text range to render. If you want the range of text to extend to the end of the text buffer, you can pass the constant kATSUToTextEnd. Keep in mind that the function ATSUDrawText renders text one line at a time. If the range of text spans multiple lines, you must call ATSUDrawText for each line.

    iLocationX

    An ATSUTextMeasurement value specifying the x-coordinate of the origin (in either the current QuickDraw graphics port or in a Quartz graphics context) of the line containing the text range to render. Note that the ATSUTextMeasurement type is defined as a Fixed value, so you must ensure that your coordinates are converted to Fixed values before passing them to this function. Pass the constant kATSUUseGrafPortPenLoc, described in Convenience Constants, to draw relative to the current pen location in the current graphics port.

    iLocationY

    An ATSUTextMeasurement value specifying the y-coordinate of the origin (in either the current graphics port or Quartz graphics context) of the line containing the text range to render. Note that the ATSUTextMeasurement type is defined as a Fixed value, so you must ensure that your coordinates are converted to Fixed values before passing them to this function. Pass the constant kATSUUseGrafPortPenLoc, described in Convenience Constants, to draw relative to the current pen location in the current graphics port.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUDrawText function renders a range of text at a specified location in a QuickDraw graphics port or Quartz graphics context. This function renders text to the first soft line break it encounters. If you draw into a QuickDraw graphics port you get the best performance by using a bit depth of 16 bits. If you use bit depths of 1, 4, or 8, your application incurs a performance penalty.

    You typically call the ATSUDrawText function every time you need to draw or redraw unhighlighted text. To draw highlighted text, call the function ATSUHighlightText.

    ATSUDrawText uses the transfer mode and resolution that are set in the graphics port or graphics context. If you explicitly set in the style object, then text color is taken from the style object, and the value in the graphics port/context is ignored. If the text color was not explicitly set in the style object, ATSUDrawText uses the graphics port/context setting.

    ATSUDrawText 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, ATSUI 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, ATSUI assigns these characters to the first style run it finds. If there is no style run at the end of the text range, ATSUI assigns the remaining characters to the last style run it finds.

    If you want to draw a range of text that spans multiple lines, you should call ATSUDrawText for each line of text to draw, 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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Renders a highlighted range of text at a specified location in a QuickDraw graphics port or Quartz graphics context.

    Declaration

    Objective-C

    OSStatus ATSUHighlightText ( ATSUTextLayout iTextLayout, ATSUTextMeasurement iTextBasePointX, ATSUTextMeasurement iTextBasePointY, UniCharArrayOffset iHighlightStart, UniCharCount iHighlightLength );

    Parameters

    iTextLayout

    An ATSUTextLayout value identifying the text layout object for which to render highlighted text.

    iTextBasePointX

    An ATSUTextMeasurement value specifying the x-coordinate of the origin (in either the current graphics port or in a Quartz graphics context) of the line containing the text range to highlight. Pass the constant kATSUUseGrafPortPenLoc, described in Convenience Constants, to draw relative to the current pen location in the current graphics port.

    iTextBasePointY

    An ATSUTextMeasurement value specifying the y-coordinate of the origin (in either the current graphics port or graphics context) of the line containing the text range to highlight. Pass the constant kATSUUseGrafPortPenLoc, described in Convenience Constants, to draw relative to the current pen location in the current graphics port.

    iHighlightStart

    A UniCharArrayOffset value specifying the offset from the beginning of the text buffer to the first character of the range to highlight. If the range of text spans multiple lines, you should call ATSUHighlightText for each line, passing the offset corresponding to the beginning of the new line to draw with each call. 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 iHighlightLength parameter.

    iHighlightLength

    A UniCharCount value specifying the length of the text range to highlight. If you want the range of text to extend to the end of the text buffer, you can pass the constant kATSUToTextEnd.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    When the user selects a series of glyphs, the characters in memory corresponding to the glyphs make up the selection range and should be highlighted to indicate where the next editing operation is to occur. The characters in a selection range are always contiguous in memory, but their corresponding glyphs are not necessarily so onscreen. If the selection range crosses a direction boundary, it is appropriate to display discontinuous highlighting.

    The ATSUHighlightText function renders a highlighted range of text at a specified location in a QuickDraw graphics port or Quartz graphics context, using the highlight information in the graphics port or context. ATSUHighlightText automatically produces discontinuous highlighting, if needed. You typically call the ATSUHighlightText function every time you need to draw or redraw highlighted text.

    If you provide your own CGContextRef (for example, one created by calling the function QDBeginCGContext) for an ATSUTextLayout, highlighting performed by calling the function ATSUHighlightText will not work unless you first call the function ATSUSetHighlightingMethod with the iMethod parameter set to kRedrawHighlighting and a pointer to an ATSUUnhighlightData structure as the iUnhighlightData parameter.

    Before drawing the highlighted text, ATSUHighlightText 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, ATSUI 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, ATSUI assigns these characters to the first style run it finds. If there is no style run at the end of the text range, ATSUI assigns the remaining characters to the last style run it finds.

    ATSUHighlightText uses the previously set line ascent and descent values to calculate the height of the highlighted region. If these values have not been set for the line, ATSUHighlightText uses the line ascent and descent values set for the text layout object containing the line. If these are not set, it uses the default values.

    To draw a highlighted text range that spans multiple lines, you should call ATSUHighlightText for each line of the text range, even if all the lines are in the same text layout object. You should adjust the iHighlightStart parameter to reflect the beginning of each line to be drawn.

    After calling ATSUHighlightText, to properly redraw the unhighlighted text and background, you should always call the function ATSUUnhighlightText.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Renders a previously highlighted range of text in an unhighlighted state.

    Declaration

    Objective-C

    OSStatus ATSUUnhighlightText ( ATSUTextLayout iTextLayout, ATSUTextMeasurement iTextBasePointX, ATSUTextMeasurement iTextBasePointY, UniCharArrayOffset iHighlightStart, UniCharCount iHighlightLength );

    Parameters

    iTextLayout

    An ATSUTextLayout value identifying the text layout object for which to render unhighlighted text.

    iTextBasePointX

    An ATSUTextMeasurement value specifying the x-coordinate of the origin (in either the current graphics port or in a Quartz graphics context) of the line containing the text range. Pass the constant kATSUUseGrafPortPenLoc, described in Convenience Constants, to draw relative to the current pen location in the current graphics port.

    iTextBasePointY

    An ATSUTextMeasurement value specifying the y-coordinate of the origin (in either the current graphics port or in a Quartz graphics context) of the line containing the text range. Pass the constant kATSUUseGrafPortPenLoc, described in Convenience Constants, to draw relative to the current pen location in the current graphics port.

    iHighlightStart

    A UniCharArrayOffset value specifying the offset from the beginning of the text buffer to the first character of the text range. If the text range spans multiple lines, you should call ATSUUnhighlightText for each line, passing the offset corresponding to the beginning of the new line to draw with each call. 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 iHighlightLength parameter.

    iHighlightLength

    A UniCharCount value specifying the length of the text range. To indicate that the text range extends to the end of the text buffer, pass the constant kATSUToTextEnd.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUUnhighlightText function renders a previously highlighted range of text in an unhighlighted state. You should always call ATSUUnhighlightText after calling the function ATSUHighlightText, to properly redraw the unhighlighted text and background.

    If the inversion method of highlighting was used, when you call ATSUUnhighlightText, it merely undoes the inversion and renders the text.

    If the redraw method of highlighting was used, ATSUUnhighlightText turns off the highlighting and restores the desired background. Depending on the complexity of the background, ATSUI restores the background in one of two ways:

    • When the background is a single color (such as white), ATSUI can readily unhighlight the background. In such a case, you specify the background color that ATSUI uses by calling the function ATSUSetHighlightingMethod and setting iMethod to kRedrawHighlighting and iUnhighlightData.dataType to kATSUBackgroundColor and providing the background color in iUnhighlightData.unhighlightData. With these settings defined, when you call ATSUUnhighlightText, ATSUI simply calculates the previously highlighted area, repaints it with the specified background color, and then redraws the text.

    • When the background is more complex (containing, for example, multiple colors, patterns, or pictures), you must provide a redraw background callback function when you call ATSUSetHighlightingMethod. You do this by setting iUnhighlightData.dataType to kATSUBackgroundCallback and providing a RedrawBackgroundUPP in iUnhighlightData.unhighlightData. When ATSUI calls your callback, you are responsible for redrawing the background of the unhighlighted area. If you choose to also redraw the text, then your callback should return false as a function result. If your callback returns true ATSUI redraws any text that needs to be redrawn. See RedrawBackgroundProcPtr for additional information.

    Before calculating the dimensions of the area to unhighlight, ATSUUnhighlightText 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, ATSUI 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, ATSUI assigns these characters to the first style run it finds. If there is no style run at the end of the text range, ATSUI assigns the remaining characters to the last style run it finds.

    The ATSUUnhighlightText function uses the previously set line ascent and descent values to calculate the height of the region to unhighlight. If these values have not been set for the line, ATSUUnhighlightText uses the line ascent and descent values set for the text layout object containing the line. If these are not set, it uses the default values.

    If you want to remove highlighting from a text range that spans multiple lines, you should call ATSUUnhighlightText for each line of text that is being unhighlighted, even if all the lines belong to the same text layout object. You should adjust the iHighlightStart parameter to reflect the beginning of each line to be unhighlighted.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Sets the method ATSUI uses to highlight and unhighlight text for a text layout object.

    Declaration

    Objective-C

    OSStatus ATSUSetHighlightingMethod ( ATSUTextLayout iTextLayout, ATSUHighlightMethod iMethod, const ATSUUnhighlightData *iUnhighlightData );

    Parameters

    iTextLayout

    An ATSUTextLayout value identifying the text layout object for which to set the highlighting method.

    iMethod

    An ATSUHighlightMethod value specifying the type of highlighting for ATSUI to use (kInvertHighlighting or kRedrawHighlighting). The default highlighting method, if you do not call ATSUSetHighlightingMethod, is inversion. See Highlight Methods for a description of available values.

    iUnhighlightData

    A pointer to an ATSUUnhighlightData structure if you are setting the iMethod parameter to kRedrawHighlighting or NULL if setting iMethod to kInvertHighlighting. Before calling ATSUSetHighlightingMethod, you should set the ATSUUnhighlightData structure to contain the data needed (either a color or a UPP for a background drawing callback) to redraw the background.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    In Mac OS 9 and by default in Mac OS X (except with Cocoa applications—see below), ATSUI highlights text by “inverting” the region containing the text, that is, its background color. Although inversion provides satisfactory highlighting in most cases, it does not always provide the best result for grayscale text. (Mac OS X sets a lower threshold for antialiasing, while in Mac OS 9 grayscale text can be turned off by the user.)

    In Mac OS X, when using a Quartz graphics context, you can instruct ATSUI to use the redraw method of highlighting, rather than simple inversion. (Note that Cocoa applications always use the redraw method of highlighting.) The redraw method allows for accurate highlighting of more complex backgrounds, such as those containing multiple colors, patterns, or pictures. To set redrawing on, call the ATSUSetHighlightingMethod function and specify that the redraw method be used (by passing kRedrawHighlighting in the iMethod parameter).

    If you specify the redraw method of highlighting when you call ATSUSetHighlightingMethod, then you must also specify how the background is to be redrawn when the function ATSUUnhighlightText is called. ATSUI can restore the desired background in one of two ways, depending on the background’s complexity:

    • When the background is a single color (such as white), ATSUI can readily unhighlight the background. In such a case, you specify the background color that ATSUI uses by calling ATSUSetHighlightingMethod and setting iUnhighlightData.dataType to kATSUBackgroundColor and providing the background color in iUnhighlightData.unhighlightData. With these settings defined, when you call ATSUUnhighlightText, ATSUI simply calculates the previously highlighted area, repaints it with the specified background color, and then redraws the text.

    • When the background is more complex (containing, for example, multiple colors, patterns, or pictures), you must provide a redraw background callback function when you call ATSUSetHighlightingMethod. You do this by setting iUnhighlightData.dataType to kATSUBackgroundCallback and providing a RedrawBackgroundUPP in iUnhighlightData.unhighlightData. Then when you call ATSUUnhighlightText and ATSUI calls your callback, you are responsible for redrawing the background of the unhighlighted area. If you choose to also redraw the text, then your callback should return false as a function result. If your callback returns true ATSUI redraws any text that needs to be redrawn. See RedrawBackgroundProcPtr for additional information.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the highlight region for a range of text.

    Declaration

    Objective-C

    OSStatus ATSUGetTextHighlight ( ATSUTextLayout iTextLayout, ATSUTextMeasurement iTextBasePointX, ATSUTextMeasurement iTextBasePointY, UniCharArrayOffset iHighlightStart, UniCharCount iHighlightLength, RgnHandle oHighlightRegion );

    Parameters

    iTextLayout

    An ATSUTextLayout value identifying the text layout object containing the text range.

    iTextBasePointX

    An ATSUTextMeasurement value specifying the x-coordinate of the origin (in either the current graphics port or in a Quartz graphics context) of the line containing the text range. Pass the constant kATSUUseGrafPortPenLoc, described in Convenience Constants, to obtain the highlight region relative to the current pen location in the current graphics port.

    iTextBasePointY

    An ATSUTextMeasurement value specifying the y-coordinate of the origin (in either the current graphics port or graphics context) of the line containing the text range. Pass the constant kATSUUseGrafPortPenLoc, described in Convenience Constants, to obtain the highlight region relative to the current pen location in the current graphics port.

    iHighlightStart

    A UniCharArrayOffset value specifying the offset from the beginning of the text buffer to the first character of the range. If the range of text spans multiple lines, you should call ATSUGetTextHighlight for each line, passing the offset corresponding to the beginning of the new line with each call. 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 iHighlightLength parameter.

    iHighlightLength

    A UniCharCount value specifying the length of the text range. If you want the text range to extend to the end of the text buffer, you can pass the constant kATSUToTextEnd.

    oHighlightRegion

    A valid RgnHandle value. On return, ATSUGetTextHighlight produces a MacRegion structure containing the highlight region for the specified range of text. In the case of discontinuous highlighting, the region consists of multiple components, with MacRegion.rgnBBox specifying the bounding box around the entire area of discontinuous highlighting.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUGetTextHighlight function obtains the highlight region for a range of text. To highlight text, call the function ATSUHighlightText.

    The ATSUGetTextHighlight function uses the previously set line ascent and descent values to calculate the height of the highlight region. If these values have not been set for the line, ATSUGetTextHighlight uses the line ascent and descent values set for the text layout object containing the line. If these are not set, it uses the default values.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Highlights previously selected text using an alpha value of 0.5.

    Declaration

    Objective-C

    OSStatus ATSUHighlightInactiveText ( ATSUTextLayout iTextLayout, ATSUTextMeasurement iTextBasePointX, ATSUTextMeasurement iTextBasePointY, UniCharArrayOffset iHighlightStart, UniCharCount iHighlightLength );

    Parameters

    iTextLayout

    An ATSUTextLayout value identifying the text layout object containing the text range.

    iTextBasePointX

    An ATSUTextMeasurement value specifying the x-coordinate of the origin (in either the current graphics port or in a Quartz graphics context) of the line containing the text range. Pass the constant kATSUUseGrafPortPenLoc, described in Convenience Constants, to obtain the highlight region relative to the current pen location in the current graphics port.

    iTextBasePointY

    An ATSUTextMeasurement value specifying the y-coordinate of the origin (in either the current graphics port or graphics context) of the line containing the text range. Pass the constant kATSUUseGrafPortPenLoc, described in Convenience Constants, to obtain the highlight region relative to the current pen location in the current graphics port.

    iHighlightStart

    A UniCharArrayOffset value specifying the offset from the beginning of the text buffer to the first character of the range. If the range of text spans multiple lines, you should call ATSUGetTextHighlight for each line, passing the offset corresponding to the beginning of the new line with each call. 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 iHighlightLength parameter.

    iHighlightLength

    A UniCharCount value specifying the length of the text range. If you want the text range to extend to the end of the text buffer, you can pass the constant kATSUToTextEnd.

    Return Value

    A result code. See ATSUI Result Codes.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Informs ATSUI of the location and length of a text insertion.

    Declaration

    Objective-C

    OSStatus ATSUTextInserted ( ATSUTextLayout iTextLayout, UniCharArrayOffset iInsertionLocation, UniCharCount iInsertionLength );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object containing the inserted text.

    iInsertionLocation

    A UniCharArrayOffset value specifying the offset from the beginning of the text buffer to the memory location of the inserted text. To specify an insertion point at the beginning of the text buffer, you can pass the constant kATSUFromTextBeginning.

    iInsertionLength

    A UniCharCount value specifying the length of the inserted text.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    When you call the ATSUTextInserted function to inform ATSUI of a text insertion, it extends the style run containing the insertion point by the amount of the inserted text. If the insertion point is between two style runs, the first style run is extended to include the new text.

    The ATSUTextInserted function also extends the total length of the text buffer containing the inserted text by the amount of the inserted text. That is, it shifts the memory location of the text following the inserted text by iInsertionLength. ATSUTextInserted then updates drawing caches.

    Note that the ATSUTextInserted function does not change the actual memory location of the inserted text. You are responsible for placing the inserted text into the text buffer at the appropriate location.

    The ATSUTextInserted function does not insert style runs or line breaks; to do so, call the functions ATSUSetRunStyle and ATSUSetSoftLineBreak, respectively. Break line operations should be redone after you call ATSUTextInserted.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Informs ATSUI of the location and length of a text deletion.

    Declaration

    Objective-C

    OSStatus ATSUTextDeleted ( ATSUTextLayout iTextLayout, UniCharArrayOffset iDeletedRangeStart, UniCharCount iDeletedRangeLength );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object containing the deleted text.

    iDeletedRangeStart

    A UniCharArrayOffset value specifying the offset from the beginning of the text buffer to the memory location of the deleted text. To specify a deletion point at the beginning of the text buffer, you can pass the constant kATSUFromTextBeginning. To specify that the entire text buffer has been deleted, pass kATSUFromTextBeginning in this parameter and kATSUToTextEnd in the iDeletedRangeLength parameter.

    iIDeletedRangeLength

    A UniCharCount value specifying the length of the deleted text. To specify a deletion length extending to the end of the text buffer, you can pass the constant kATSUToTextEnd.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    When you call the ATSUTextDeleted function to inform ATSUI of a text deletion, it shortens the style run(s) containing the deleted text by the amount of the deletion. If a style run corresponds entirely to a range of deleted text, that style run is removed. If the deletion point is between two style runs, the first style run is shortened (or removed).

    The ATSUTextDeleted function also shortens the total length of the text buffer containing the deleted text by the amount of the deletion. That is, it shifts the memory location of the text following the deleted text by iDeletedRangeLength. ATSUTextDeleted also removes any soft line breaks that fall within the deleted text and updates affected drawing caches.

    The ATSUTextDeleted function does not change the actual memory location of the affected text. You are responsible for deleting the corresponding text is from the text buffer. You are also responsible for calling the function ATSUDisposeStyle to dispose of the memory associated with any style runs that have been removed.

    Note that calling the function ATSUTextDeleted automatically removes previously-set soft line breaks if the line breaks are within the range of text that is deleted.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Informs ATSUI of the new memory location of relocated text.

    Declaration

    Objective-C

    OSStatus ATSUTextMoved ( ATSUTextLayout iTextLayout, ConstUniCharArrayPtr iNewLocation );

    Parameters

    iTextLayout

    An ATSUTextLayout value identifying the text layout object associated with the relocated text.

    iNewLocation

    A ConstUniCharArrayPtr specifying the new memory location of the moved text.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    You should call the ATSUTextMoved function when a range of text consisting of less than an entire text buffer has been moved. The ATSUTextMoved function informs ATSUI of the new memory location of the text. You are responsible for moving the text. The text buffer should remain otherwise unchanged.

    When a range of text consisting of an entire text buffer has been moved, you should:

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Obtains the memory offset for the glyph edge nearest a mouse-down event.

    Declaration

    Objective-C

    OSStatus ATSUPositionToOffset ( ATSUTextLayout iTextLayout, ATSUTextMeasurement iLocationX, ATSUTextMeasurement iLocationY, UniCharArrayOffset *ioPrimaryOffset, Boolean *oIsLeading, UniCharArrayOffset *oSecondaryOffset );

    Parameters

    iTextLayout

    An ATSUTextLayout value identifying the text layout object in which the mouse-down event occurred.

    iLocationX

    An ATSUTextMeasurement value specifying the x-coordinate of the event, in local coordinates, relative to the origin of the line where the event occurred. That is, to specify the x-coordinate value, you should subtract the x-coordinate of the line origin from the x-coordinate of the hit point (in local coordinates). You can pass the constant kATSUUseGrafPortPenLoc, described in Convenience Constants, for the location of the mouse-down event relative to the current pen location in the current graphics port.

    iLocationY

    An ATSUTextMeasurement value specifying the y-coordinate of the event, in local coordinates, relative to the origin of the line where the event occurred. That is, to specify the y-coordinate value, you should subtract the y-coordinate of the line origin from the y-coordinate of the hit point (in local coordinates). You can pass the constant kATSUUseGrafPortPenLoc, described in Convenience Constants, for the location of the mouse-down event relative to the current pen location in the current graphics port.

    ioPrimaryOffset

    A pointer to a UniCharArrayOffset value specifying the offset corresponding to the beginning of the line where the event occurred. On return, the value specifies the offset corresponding to the glyph edge that is visually closest to the event. To determine whether this offset indicates the leading or trailing edge of the glyph, you can examine the value produced in the oIsLeading parameter.

    oIsLeading

    A pointer to a Boolean value. On return, the value indicates whether the offset produced in the ioPrimaryOffset parameter is leading or trailing. The function ATSUPositionToOffset produces a value of true if the offset is leading (that is, more closely associated with the subsequent character in memory). It produces a value of false if the offset is trailing (that is, more closely associated with the preceding character in memory).

    oSecondaryOffset

    A pointer to a UniCharArrayOffset value. On return, the value typically specifies the same offset as that produced in the ioPrimaryOffset parameter, unless the event occurred within a glyph cluster or at a line direction boundary. If so, the value specifies a secondary offset. The secondary offset is associated with the glyph that has a different direction from the primary line direction.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The process of hit-testing text obtains the location of a mouse-down event relative both to the position of onscreen glyphs and to the corresponding offset between character codes in memory. You can then use the location information obtained by hit-testing to set the insertion point (that is, the caret) or selection range (for highlighting).

    Hit-testing text is complicated by the fact that a given line of text may be bidirectional. Therefore, the onscreen order of glyphs may not readily correspond to the storage order of the corresponding character codes. And the concept of which glyph comes “first” in a line of text cannot always be limited to the visual terms “left” and “right.” Because of these complexities, it is more accurate to speak in terms of “leading” and “trailing” edges to glyphs. A “leading edge” is defined as the edge of a glyph that you first encounter when you read the text that includes that glyph. For example, when reading Roman text, you first encounter the left edge of a Roman glyph. Similarly, the “trailing edge” is defined as the edge of the glyph encountered last.

    ATSUI can translate the location of a mouse click into an onscreen position, as well as to a memory offset. When you use ATSUI for hit-testing, ATSUI takes into account the glyph edge (whether leading or trailing) nearest to where the click occurred, thus providing positional information in complex situations, such as at line direction boundaries or within glyph clusters.

    The first step in obtaining the caret position(s) for a mouse-down event is to pass the location (in local coordinates, relative to the line origin) of the event to the function ATSUPositionToOffset. For example, if you have a mouse-down event whose position in local coordinates is (75,50), you would subtract this value from the position of the origin of the line in the current graphics port. If the position of the origin of the line in the current graphics port is (50,50), then the relative position of the event that you would pass in the iLocationX and iLocationY parameters is (25,0).

    The ATSUPositionToOffset function produces the memory offset corresponding to the glyph edge nearest the event. If the mouse-down event occurs at a line direction boundary or within a glyph cluster, ATSUPositionToOffset produces two offsets. You can then provide the offset(s) to the ATSUOffsetToPosition function, to obtain the actual caret position(s) for the event.

    When you call the ATSUPositionToOffset function, ATSUI examines the Unicode directionality of the character corresponding to the event location. The ATSUPositionToOffset function produces a value of true in the oIsLeading parameter if the offset is leading (that is, more closely associated with the subsequent character in memory and therefore indicative of a left-to-right line direction). It produces a value of false if the offset is trailing (that is, more closely associated with the preceding character in memory and indicative of a right-to-left line direction).

    Finally, note that when the event occurs beyond the leftmost or rightmost caret positions of the line (not taking into account line rotation), such that no glyph corresponds to the location of the hit, the ATSUPositionToOffset function produces the primary offset of the closest edge of the line to the input location. The oIsLeading flag depends on the directionality of the closest glyph and the side of the line to which the input location is closest. In this case, the secondary offset is equal to the primary offset, since no glyph was hit.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Obtains the caret position(s) corresponding to a memory offset.

    Declaration

    Objective-C

    OSStatus ATSUOffsetToPosition ( ATSUTextLayout iTextLayout, UniCharArrayOffset iOffset, Boolean iIsLeading, ATSUCaret *oMainCaret, ATSUCaret *oSecondCaret, Boolean *oCaretIsSplit );

    Parameters

    iTextLayout

    An ATSUTextLayout value identifying the text layout object to examine.

    iOffset

    A UniCharArrayOffset value specifying the memory offset for which to obtain the corresponding caret position. To respond to a mouse-down event, pass the offset produced in the ioPrimaryOffset parameter of the function ATSUPositionToOffset—that is, the offset corresponding to the glyph edge closest to the event.

    iIsLeading

    A Boolean value indicating whether the offset corresponds to the leading or trailing edge of the glyph. You can obtain this information from the function ATSUPositionToOffset. This value is relevant if the offset occurs at a line direction boundary or within a glyph cluster.

    oMainCaret

    A pointer to an ATSUCaret structure. On return, the structure contains the starting and ending pen locations of the high caret if the value produced in oCaretIsSplit is true. If the value is false, the structure contains the starting and ending pen locations of the main caret.

    oSecondCaret

    A pointer to an ATSUCaret structure. On return, the structure contains the starting and ending pen locations of the low caret if the value passed back in the oCaretIsSplit parameter is true. If the value is false, the structure contains the starting and ending pen locations of the main caret (that is, the same values as the oMainCaret parameter).

    oCaretIsSplit

    A pointer to a Boolean value. On return, the value indicates whether the offset specified in the iOffset parameter occurs at a line direction boundary. If true, the offset occurs at a line direction boundary; otherwise, false.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The process of hit-testing text obtains the location of a mouse-down event relative both to the position of onscreen glyphs and to the corresponding offset between character codes in memory. You can then use the location information obtained by hit-testing to set the insertion point (that is, the caret) or selection range (for highlighting).

    Hit-testing text is complicated by the fact that a given line of text may be bidirectional. Therefore, the onscreen order of glyphs may not readily correspond to the storage order of the corresponding character codes. And the concept of which glyph comes “first” in a line of text cannot always be limited to the visual terms “left” and “right.” Because of these complexities, it is more accurate to speak in terms of “leading” and “trailing” edges to glyphs. A “leading edge” is defined as the edge of a glyph that you first encounter when you read the text that includes that glyph. For example, when reading Roman text, you first encounter the left edge of a Roman glyph. Similarly, the “trailing edge” is defined as the edge of the glyph encountered last.

    ATSUI can translate the location of a mouse click into an onscreen position, as well as to a memory offset. When you use ATSUI for hit-testing, ATSUI takes into account the glyph edge (whether leading or trailing) nearest to where the click occurred, thus providing positional information in complex situations, such as at line direction boundaries or within glyph clusters.

    Line direction boundaries can occur on the trailing edges of two glyphs, the leading edges of two glyphs, or at the beginning or end of a text segment. At direction boundaries, a single insertion point in memory can require two caret positions onscreen, one for text entry in each direction. The two separate carets (known as a split caret or a dual caret) consist of a high caret and a low caret. The high (primary) caret is displayed at the caret position for inserting text whose direction corresponds to the line direction (the dominant direction for the overall line of text). The low (secondary) caret is displayed at the caret position for inserting text whose direction is counter to the overall line direction.

    The first step in obtaining the caret position(s) for a mouse-down event is to pass the location (in local coordinates, relative to the line origin) of the event to the function ATSUPositionToOffset. The ATSUPositionToOffset function produces the memory offset corresponding to the glyph edge nearest the event. If the mouse-down event occurs at a line direction boundary or within a glyph cluster, the ATSUPositionToOffset function produces two offsets. You can then provide the offset(s) to the ATSUOffsetToPosition function, to obtain the actual caret position(s) for the event.

    The ATSUOffsetToPosition function produces two structures of type ATSUCaret. These structures contain the pen positioning information needed to draw the caret(s) for the event, specified relative to the origin of the line in the current graphics port or graphics context. Specifically, the ATSUCaret structures contain x-y coordinates for both the caret’s starting and ending pen positions (the latter taking into account line rotation, caret slanting, and split-caret appearances).

    If the memory offset you pass to ATSUOffsetToPosition is at a line boundary, the structure produced in the oMainCaret parameter contains the starting and ending pen locations for the high caret, while the oSecondCaret parameter contains the corresponding values for the low caret. If the offset is not at a line boundary, both parameters contain the starting and ending pen locations of the main caret.

    Because you provide the ATSUOffsetToPosition function an offset relative to the origin of the line where the hit occurred, ATSUOffsetToPosition produces positioning information that is also relative. Therefore, you must transform the positions produced by the ATSUOffsetToPosition function before drawing the caret(s). To transform the caret location(s), add the starting and ending caret coordinates to the coordinates of the origin of the line in which the hit occurred. For example, if ATSUOffsetToPosition produces starting and ending pen locations of (25,0), (25,25) in the oMainCaret parameter (and the oSecondCaret parameter contains the same coordinates, meaning that the caret was not split), you would add these to the position of the origin of the line in the graphics port or context. If the position of the line origin was at (50,50), then the starting and ending pen locations of the caret would be (75,50), (75,75).

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the memory offset for the insertion point that follows the current insertion point in storage order, as determined by a move of the specified length.

    Declaration

    Objective-C

    OSStatus ATSUNextCursorPosition ( ATSUTextLayout iTextLayout, UniCharArrayOffset iOldOffset, ATSUCursorMovementType iMovementType, UniCharArrayOffset *oNewOffset );

    Parameters

    iTextLayout

    An ATSUTextLayout value identifying the text layout object to examine.

    iOldOffset

    A UniCharArrayOffset value specifying the memory offset corresponding to the current caret position. To specify the beginning of the text buffer, pass the constant kATSUFromTextBeginning.

    iMovementType

    An ATSUCursorMovementType constant identifying the unit of movement. See Caret Movement Types for a description of possible values (which range from a single Unicode character to a Unicode word in length). Note that ATSUI may not be able to move the caret by a single Unicode character in some cases, since doing so might place the insertion point in the middle of a surrogate pair.

    oNewOffset

    A pointer to a UniCharArrayOffset value. On return, the value provides the memory offset corresponding to the following insertion point. This offset may be outside the initial text buffer.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUNextCursorPosition function obtains the memory offset for the insertion point that follows the current insertion point in storage order, as determined by a move of the specified length.

    You should use the ATSUNextCursorPosition function or the function ATSUPreviousCursorPosition to determine caret position when the initial memory offset is not at a line direction boundary. If the initial offset is at a line direction boundary, you should instead use the functions ATSURightwardCursorPosition or ATSULeftwardCursorPosition.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the memory offset for the insertion point that precedes the current insertion point in storage order, as determined by a move of the specified length.

    Declaration

    Objective-C

    OSStatus ATSUPreviousCursorPosition ( ATSUTextLayout iTextLayout, UniCharArrayOffset iOldOffset, ATSUCursorMovementType iMovementType, UniCharArrayOffset *oNewOffset );

    Parameters

    iTextLayout

    An ATSUTextLayout value identifying the text layout object to examine.

    iOldOffset

    A UniCharArrayOffset value specifying the memory offset corresponding to the current caret position. To specify the beginning of the text buffer, pass the constant kATSUFromTextBeginning,

    iMovementType

    An ATSUCursorMovementType constant identifying the unit of movement. See Caret Movement Types for a description of possible values (which range from a single Unicode character to a Unicode word in length). Note that ATSUI may not be able to move the caret by a single Unicode character in some cases, since doing so might place the insertion point in the middle of a surrogate pair.

    oNewOffset

    A pointer to a UniCharArrayOffset value. On return, the value provides the memory offset corresponding to the preceding insertion point. This offset may be outside the initial text buffer.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUPreviousCursorPosition function obtains the memory offset for the insertion point that precedes the current insertion point in storage order, as determined by a move of the specified length.

    You should use the ATSUPreviousCursorPosition function or the function ATSUNextCursorPosition to determine caret position when the initial offset is not at a line direction boundary. If the initial offset is at a line direction boundary, you should instead use the functions ATSURightwardCursorPosition or ATSULeftwardCursorPosition.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the memory offset for the insertion point to the right of the high caret position, as determined by a move of the specified length at a line direction boundary.

    Declaration

    Objective-C

    OSStatus ATSURightwardCursorPosition ( ATSUTextLayout iTextLayout, UniCharArrayOffset iOldOffset, ATSUCursorMovementType iMovementType, UniCharArrayOffset *oNewOffset );

    Parameters

    iTextLayout

    An ATSUTextLayout value identifying the text layout object to examine.

    iOldOffset

    A UniCharArrayOffset value specifying the memory offset corresponding to the current caret position. To specify the beginning of the text buffer, pass the constant kATSUFromTextBeginning. For bidirectional text, you can specify the previous layout by passing the constant kATSUFromPreviousLayout and the following layout by passing the constant kATSUFromFollowingLayout. See the Discussion for the function ATSULeftwardCursorPosition for an example of how these constants can be used.

    iMovementType

    An ATSUCursorMovementType constant identifying the unit of movement. See Caret Movement Types for a description of possible values (which range from a single Unicode character to a Unicode word in length). Note that ATSUI may not be able to move the caret by a single Unicode character in some cases, since doing so might place the insertion point in the middle of a surrogate pair.

    oNewOffset

    A pointer to a UniCharArrayOffset value. On return, the value provides the memory offset corresponding to the new insertion point. This offset may be outside the initial text buffer.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    Line direction boundaries can occur on the trailing edges of two glyphs, the leading edges of two glyphs, or at the beginning or end of a text segment. At direction boundaries, a single insertion point in memory can require two caret positions onscreen, one for text entry in each direction. The two separate carets (known as a split caret or a dual caret) consist of a high caret and a low caret. The high (primary) caret is displayed at the caret position for inserting text whose direction corresponds to the line direction (the dominant direction for the overall line of text). The low (secondary) caret is displayed at the caret position for inserting text whose direction is counter to the overall line direction.

    The ATSURightwardCursorPosition function obtains the memory offset for the insertion point to the right of the high caret position, as determined by a move of the specified length at a line direction boundary.

    You should use the ATSURightwardCursorPosition function or the function ATSULeftwardCursorPosition to determine caret position when the user presses the right and left arrow keys.

    Except in the case of Indic text (and other cases where the font rearranges the glyphs), for left-to-right text, calling the function ATSURightwardCursorPosition has the same effect as calling ATSUNextCursorPosition. For right-to-left text, calling the function ATSURightwardCursorPosition has the same effect as calling ATSUPreviousCursorPosition.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the memory offset for the insertion point to the left of the high caret position, as determined by a move of the specified length at a line direction boundary.

    Declaration

    Objective-C

    OSStatus ATSULeftwardCursorPosition ( ATSUTextLayout iTextLayout, UniCharArrayOffset iOldOffset, ATSUCursorMovementType iMovementType, UniCharArrayOffset *oNewOffset );

    Parameters

    iTextLayout

    An ATSUTextLayout value identifying the text layout object to examine.

    iOldOffset

    A UniCharArrayOffset value specifying the memory offset corresponding to the current caret position. To specify the beginning of the text buffer, pass the constant kATSUFromTextBeginning. For bidirectional text, you can specify the previous layout by passing the constant kATSUFromPreviousLayout and the following layout by passing the constant kATSUFromFollowingLayout. See the Discussion for example code that shows how to use these constants.

    iMovementType

    An ATSUCursorMovementType constant identifying the unit of movement. See Caret Movement Types for a description of possible values (which range from a single Unicode character to a Unicode word in length). Note that ATSUI may not be able to move the caret by a single Unicode character in some cases, since doing so might place the insertion point in the middle of a surrogate pair.

    oNewOffset

    A pointer to a UniCharArrayOffset value. On return, the value provides the memory offset corresponding to the new insertion point. This offset may be outside the initial text buffer.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    Line direction boundaries can occur on the trailing edges of two glyphs, the leading edges of two glyphs, or at the beginning or end of a text segment. At direction boundaries, a single insertion point in memory can require two caret positions onscreen, one for text entry in each direction. The two separate carets (known as a split caret or a dual caret) consist of a high caret and a low caret. The high (primary) caret is displayed at the caret position for inserting text whose direction corresponds to the line direction (the dominant direction for the overall line of text). The low (secondary) caret is displayed at the caret position for inserting text whose direction is counter to the overall line direction.

    The ATSURightwardCursorPosition function obtains the memory offset for the insertion point to the left of the high caret position, as determined by a move of the specified length at a line direction boundary.

    You should use the ATSULeftwardCursorPosition function or the function ATSURightwardCursorPosition to determine caret position when the user presses the right and left arrow keys.

    Except in the case of Indic text (and other cases where the font rearranges the glyphs), for left-to-right text, calling the function ATSULeftwardCursorPosition has the same effect as calling ATSUPreviousCursorPosition. For right-to-left text, calling the function ATSULeftwardCursorPosition has the same effect as calling ATSUNextCursorPosition.

    The following code shows how to use the constants kATSUFromPreviousLayout and kATSUFromFollowingLayout with the function ATSULeftwardCursorPosition:

    • typedef struct TLayoutWithEndOffset
    • {
    • ATSUTextLayout layout;
    • UInt32 endOffset;
    • };
    • typedef struct TLayoutsWithEndOffsets
    • {
    • UInt32 count;
    • TLayoutWithEndOffset layouts[];
    • }
    • UniCharArrayOffset MyAbsoluteToRelativeOffset (
    • TLayoutsWithEndOffsets * iLayouts,
    • UniCharArrayOffset iAbsoluteOffset );
    • UniCharArrayOffset MyRelativeToAbsoluteOffset (
    • TLayoutsWithEndOffsets * iLayouts,
    • UInt32 iLayoutIndex,
    • UniCharArrayOffset iRelativeOffset );
    • UniCharArrayOffset MyGetLayoutEndOffset (
    • TLayoutsWithEndOffsets * iLayouts,
    • UInt32 iLayoutIndex );
    • /* Passing in current offset relative to the beginning of */
    • /* the entire text buffer (absolute), */
    • /* not just the current paragraph. This returns the new (absolute) */
    • /* offset relative to the beginning of the entire text buffer.*/
    • UniCharArrayOffset
    • MyLeftwardCursorPosition ( TLayoutsWithEndOffsets * iLayouts,
    • UInt32 iLayoutIndex,
    • UniCharArrayOffset iAbsoluteOffset,
    • ATSUCursorMovementType iType )
    • {
    • OSStatus status;
    • UInt32 newLayoutIndex = iLayoutIndex;
    • UniCharArrayOffset newRelativeOffset;
    • status = ATSULeftwardCursorPosition(
    • iLayouts->layouts[iLayoutIndex].layout,
    • MyAbsoluteToRelativeOffset (iLayouts, iAbsoluteOffset ),
    • iType, &newRelativeOffset );
    • if ( status == noErr )
    • {
    • /* If the API returns the same value as */
    • /* that passed in then we're at */
    • /* the edge of the layout so need to move */
    • /* to the adjacent layout. f */
    • /* If that value is zero then we're moving to the previous layout. */
    • /* (This is left-to-right text.) */
    • if ( (newRelativeOffset == iRelativeOffset) &&
    • (iRelativeOffset == 0) )
    • {
    • /* Don't want to move before the first layout! */
    • if ( iLayoutIndex != 0 )
    • {
    • /* Pass kATSUFromFollowingLayout to the previous */
    • /* ATSUTextLayout. */
    • /* Note that the returned offset is relative to
    • /* the ATSUTextLayout passed in here.*/
    • newLayoutIndex--;
    • status = ATSULeftwardCursorPosition(
    • iLayouts[newLayoutIndex],
    • kATSUFromFollowingLayout,
    • iType &newRelativeOffset );
    • }
    • }
    • else
    • {
    • UniCharArrayOffset endAbsoluteOffset = MyGetLayoutEndOffset(
    • iLayouts, iLayoutIndex );
    • /* We've moved to the very end of this layout */
    • /* (past the trailing carriage return presumably) */
    • /* so we're moving to the following layout. */
    • /* Make sure we aren't at the */
    • /* end of the text buffer. (This is right-to-left text.) */
    • if ( (newRelativeOffset == MyAbsoluteToRelativeOffset (
    • iLayouts, endAbsoluteOffset )) &&
    • (iLayoutIndex != iLayouts->count) )
    • {
    • newLayoutIndex++;
    • status = ATSULeftwardCursorPosition(
    • iLayouts->layouts[newLayoutIndex],
    • kATSUFromPreviousLayout, iType,
    • &newRelativeOffset );
    • /* If we're moving from one paragraph to the following one */
    • /* and we aren't at the beginning of the layout means
    • /* that we're moving to a left-to-right */
    • /* paragraph and we must back up one so that*/
    • /* we're just before the line ending whitespace
    • /* (space or <CR>), unless the */
    • /* following layout is the last one. */
    • if ( (newRelOffset > 0) && (newLayoutIndex !=
    • iLayouts->count) )
    • newRelativeOffset--;
    • }
    • }
    • }
    • return MyRelativeToAbsoluteOffset( iLayouts, newLayoutIndex,
    • newRelativeOffset );
    • }

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the memory offset for the glyph edge nearest a mouse-down event, after a move of the specified length.

    Declaration

    Objective-C

    OSStatus ATSUPositionToCursorOffset ( ATSUTextLayout iTextLayout, ATSUTextMeasurement iLocationX, ATSUTextMeasurement iLocationY, ATSUCursorMovementType iMovementType, UniCharArrayOffset *ioPrimaryOffset, Boolean *oIsLeading, UniCharArrayOffset *oSecondaryOffset );

    Parameters

    iTextLayout

    An ATSUTextLayout value identifying the text layout object in which the mouse-down event occurred.

    iLocationX

    An ATSUTextMeasurement value specifying the x-coordinate of the event, in local coordinates, relative to the origin of the line where the event occurred. That is, to specify the x-coordinate value, you should subtract the x-coordinate of the line origin from the x-coordinate of the event (in local coordinates). You can pass the constant kATSUUseGrafPortPenLoc, described in Convenience Constants, for the location of the mouse-down event relative to the current pen location in the current graphics port.

    iLocationY

    An ATSUTextMeasurement value specifying the y-coordinate of the event, in local coordinates, relative to the origin of the line where the event occurred. That is, to specify the y-coordinate value, you should subtract the y-coordinate of the line origin from the y-coordinate of the event (in local coordinates). You can pass the constant kATSUUseGrafPortPenLoc, described in Convenience Constants, for the location of the mouse-down event relative to the current pen location in the current graphics port.

    iMovementType

    An ATSUCursorMovementType constant identifying the unit of movement. See Caret Movement Types for a description of possible values (which range from a single Unicode character to a Unicode word in length). Note that ATSUI may not be able to move the caret by a single Unicode character in some cases, since doing so might place the insertion point in the middle of a surrogate pair.

    ioPrimaryOffset

    A pointer to a UniCharArrayOffset value specifying the offset corresponding to the beginning of the line where the event occurred. On return, the value specifies the offset corresponding to the glyph edge nearest the event, after a movement of the specified type. This offset corresponds to where the insertion point would be placed after the move. To determine whether this offset indicates the leading or trailing edge of the glyph, you can examine the value produced in the oIsLeading parameter.

    oIsLeading

    A pointer to a Boolean value. On return, the value indicates whether the offset produced in the ioPrimaryOffset parameter is leading or trailing. The ATSUPositionToOffset function produces a value of true if the offset is leading (that is, more closely associated with the subsequent character in memory). It produces a value of false if the offset is trailing (that is, more closely associated with the preceding character in memory).

    oSecondaryOffset

    A pointer to a UniCharArrayOffset value. On return, the value typically specifies the same offset as that produced in the ioPrimaryOffset parameter, unless the event occurred within a glyph cluster or at a line direction boundary. If so, the value specifies the secondary offset, for the glyph edge furthest from the event.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUPositionToCursorOffset function produces the memory offset for the glyph edge nearest a mouse-down event, after a move of the specified length. This offset corresponds to where an insertion point would be placed after the move.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the caret position(s) corresponding to a memory offset, after a move of the specified length.

    Declaration

    Objective-C

    OSStatus ATSUOffsetToCursorPosition ( ATSUTextLayout iTextLayout, UniCharArrayOffset iOffset, Boolean iIsLeading, ATSUCursorMovementType iMovementType, ATSUCaret *oMainCaret, ATSUCaret *oSecondCaret, Boolean *oCaretIsSplit );

    Parameters

    iTextLayout

    An ATSUTextLayout value identifying the text layout object to examine.

    iOffset

    A UniCharArrayOffset value specifying the memory offset corresponding to the glyph edge nearest the event, after a movement of the specified type. You can obtain this value by examining the offset produced in the ioPrimaryOffset parameter of the function ATSUPositionToCursorOffset.

    iIsLeading

    A Boolean value indicating whether the specified offset corresponds to the leading or trailing edge of the glyph. You can obtain this information from the function ATSUPositionToCursorOffset. This value is relevant if the offset occurs at a line direction boundary or within a glyph cluster.

    iMovementType

    An ATSUCursorMovementType constant identifying the unit of cursor movement. See Caret Movement Types for a description of possible values (which range from a single Unicode character to a Unicode word in length). Note that ATSUI may not be able to move the cursor by a single Unicode character in some cases, since doing so might place the cursor in the middle of a surrogate pair.

    oMainCaret

    A pointer to an ATSUCaret structure. On return, the structure contains the starting and ending pen locations of the high caret if the value produced in the oCaretIsSplit parameter is true. If the value is false, the structure contains the starting and ending pen locations of the main caret.

    oSecondCaret

    A pointer to an ATSUCaret structure. On return, the structure contains the starting and ending pen locations of the low caret if the value passed back in the oCaretIsSplit parameter is true. If the value is false, the structure contains the starting and ending pen locations of the main caret (that is, the same values as the oMainCaret parameter).

    oCaretIsSplit

    A pointer to a Boolean value. On return, the value indicates whether the offset specified in the iOffset parameter occurs at a line direction boundary. If true, the offset occurs at a line direction boundary; otherwise, false.

    Return Value

    A result code. See ATSUI Result Codes.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the image bounding rectangle for a line of text after final layout.

    Declaration

    Objective-C

    OSStatus ATSUMeasureTextImage ( ATSUTextLayout iTextLayout, UniCharArrayOffset iLineOffset, UniCharCount iLineLength, ATSUTextMeasurement iLocationX, ATSUTextMeasurement iLocationY, Rect *oTextImageRect );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object to examine.

    iLineOffset

    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 specified 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 text range. If you want the range of text to extend to the end of the text buffer, you can pass the constant kATSUToTextEnd. However, the image bounds is restricted to the line in which iLineOffset resides.

    iLocationX

    An ATSUTextMeasurement value specifying the x-coordinate of the line’s origin in the current graphics port or Quartz graphics context. Pass the constant kATSUUseGrafPortPenLoc, described in Convenience Constants, for the dimensions of the bounds relative to the current pen location in the current graphics port or graphics context. You can pass 0 to obtain only the dimensions of the bounding rectangle relative to one another, not their actual onscreen position.

    iLocationY

    An ATSUTextMeasurement value specifying the y-coordinate of the line’s origin in the current graphics port or Quartz graphics context. Pass the constant kATSUUseGrafPortPenLoc, described in Convenience Constants, for the dimensions of the bounds relative to the current pen location in the current graphics port or graphics context. You can pass 0 to obtain only the dimensions of the bounding rectangle relative to one another, not their actual onscreen position.

    oTextImageRect

    A pointer to a Rect structure. On return, the structure contains the dimensions of the image bounding rectangle for the text, offset by the values specified in the iLocationX and iLocationY parameters. If the line is rotated, the sides of the rectangle are parallel to the coordinate axis.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The ATSUMeasureTextImage function obtains the image bounds of a laid-out line of text. These bounds are described by the smallest rectangle that completely encloses the filled or framed parts of a block of text—that is, the text’s “inked” glyphs.

    In measuring the line, the ATSUMeasureTextImage function takes into account line rotation, alignment, and justification, as well as other characteristics that affect layout, such as hanging punctuation. (If the line is rotated, the sides of the rectangle are parallel to the coordinate axes and encompass the rotated line.) If no attributes are set for the line, ATSUMeasureTextImage uses the global attributes set for the text layout object.

    Because the height of the image bounding rectangle is determined by the actual device metrics, ATSUMeasureTextImage ignores any previously set line ascent and descent values for the line it is measuring.

    Before calculating the image bounds for the text range, the ATSUMeasureTextImage function 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, ATSUMeasureTextImage 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, the ATSUMeasureTextImage function assigns these characters to the first style run it finds. If there is no style run at the end of the text range, ATSUMeasureTextImage assigns the remaining characters to the last style run it finds.

    To obtain the final typographic bounds of a line, call the function ATSUGetGlyphBounds. To calculate the unjustified typographic bounds of a line, call the function ATSUGetUnjustifiedBounds.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the typographic bounding rectangle for a line of text prior to final layout.

    Declaration

    Objective-C

    OSStatus ATSUGetUnjustifiedBounds ( ATSUTextLayout iTextLayout, UniCharArrayOffset iLineStart, UniCharCount iLineLength, ATSUTextMeasurement *oTextBefore, ATSUTextMeasurement *oTextAfter, ATSUTextMeasurement *oAscent, ATSUTextMeasurement *oDescent );

    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 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.

    oTextBefore

    A pointer to an ATSUTextMeasurement value. On return, the value specifies the starting point of the typographic bounds for the line, relative to the origin (0,0) of the line and taking into account cross-stream shifting. Note that the ATSUMeasureText function might produce negative values for the typographic starting point of the line if, for example, the initial character of the line is allowed to hang into the margin. For horizontal text, this value corresponds to the left side of the bounding rectangle.

    oTextAfter

    A pointer to an ATSUTextMeasurement value. On return, the value specifies the end point of the typographic bounds for the line, relative to the origin (0,0) of the line and taking into account cross-stream shifting. For horizontal text, this value corresponds to the right side of the bounding rectangle.

    oAscent

    A pointer to an ATSUTextMeasurement value. On return, the value specifies the ascent of the typographic bounds for the line, relative to the origin (0,0) of the line and taking into account cross-stream shifting. For horizontal text, this value corresponds to the top side of the bounding rectangle.

    oDescent

    A pointer to an ATSUTextMeasurement value. On return, the value specifies the descent of the typographic bounds for the line, relative to the origin (0,0) of the line and taking into account cross-stream shifting. For horizontal text, this value corresponds to the bottom side of the bounding rectangle.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    There are two kinds of bounds that your application may typically want to obtain for a block of text: typographic bounds and image bounds. The image bounds define the smallest rectangle that completely encloses the filled or framed parts of a block of text—that is, the text’s “inked” glyphs. Because of the potential differences in glyph height in a text block, your application may instead need to determine the typographic bounds. The typographic bounding rectangle contains the extra space above and below the image bounding rectangle where characters with ascenders or descenders would be drawn (even if none currently are).

    The ATSUGetUnjustifiedBounds function calculates the typographic bounds (in coordinates independent of the rendering device) for a line of text. Note that ATSUGetUnjustifiedBounds calculates these bounds prior to the text’s final layout, and therefore, the calculated bounds might not reflect those of the final laid-out line. To obtain the typographic bounds of a line after it is laid out, you can call the function ATSUGetGlyphBounds.

    The ATSUGetUnjustifiedBounds function ignores any previously set line attributes such as line rotation, flushness, justification, ascent, and descent in its calculations. You typically only call ATSUGetUnjustifiedBounds when you need to find out what the width of a line is without these attributes, such as for determining your own line breaks or the leading and line spacing to impose on a line.

    The ATSUGetUnjustifiedBounds function treats the specified text range as a single line. That is, if the range of text you specify is less than a line, it nevertheless treats the initial character in the range as the start of a line, for measuring purposes. If the range of text extends beyond a line, ATSUGetUnjustifiedBounds ignores soft line breaks, again, treating the text as a single line.

    Before calculating the typographic bounds for the text range, the ATSUGetUnjustifiedBounds function 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, ATSUGetUnjustifiedBounds 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, ATSUGetUnjustifiedBounds assigns these characters to the first style run it finds. If there is no style run at the end of the text range, ATSUGetUnjustifiedBounds assigns the remaining characters to the last style run it finds.

    To obtain the image bounding rectangle of a laid-out line, call the function ATSUMeasureTextImage.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the typographic bounds of a line of glyphs after final layout.

    Declaration

    Objective-C

    OSStatus ATSUGetGlyphBounds ( ATSUTextLayout iTextLayout, ATSUTextMeasurement iTextBasePointX, ATSUTextMeasurement iTextBasePointY, UniCharArrayOffset iBoundsCharStart, UniCharCount iBoundsCharLength, UInt16 iTypeOfBounds, ItemCount iMaxNumberOfBounds, ATSTrapezoid oGlyphBounds[], ItemCount *oActualNumberOfBounds );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object to examine.

    iTextBasePointX

    An ATSUTextMeasurement value specifying the x-coordinate of the origin of the line containing the glyphs in the current graphics port or Quartz graphics context. Pass the constant kATSUUseGrafPortPenLoc, described in Convenience Constants, to obtain the glyph bounds relative to the current pen location in the current graphics port or graphics context. You can pass 0 to obtain only the dimensions of the bounds relative to one another, not their actual onscreen position.

    iTextBasePointY

    An ATSUTextMeasurement value specifying the y-coordinate of the origin of the line containing the glyphs in the current graphics port or Quartz graphics context. Pass the constant kATSUUseGrafPortPenLoc, described in Convenience Constants, to obtain the glyph bounds relative to the current pen location in the current graphics port or graphics context. You can pass 0 to obtain only the dimensions of the bounds relative to one another, not their actual onscreen position.

    iBoundsCharStart

    A UniCharArrayOffset value specifying the offset from the beginning of the text buffer to the character corresponding to the first glyph to measure. To indicate that the text range starts at the beginning of the text buffer, you can pass the constant kATSUFromTextBeginning.

    iBoundsCharLength

    A UniCharCount value specifying the length of the text range to measure. If you want the range to extend to the end of the text buffer, you can pass the constant kATSUToTextEnd.

    iTypeOfBounds

    A glyph bounds constant indicating whether the width of the resulting typographic glyph bounds is determined using the caret origin (midway between two characters), the glyph origin in device space, or the glyph origin in fractional absolute positions (uncorrected for device display). See Glyph Origin Selectors for a description of possible values.

    iMaxNumberOfBounds

    An ItemCount value specifying the maximum number of bounding trapezoids to obtain. Typically, this is equivalent to the number of bounds in the oGlyphBounds array. To determine this value, see the Discussion.

    oGlyphBounds

    A pointer to memory you have allocated for an array of ATSTrapezoid values. On return, the array contains a trapezoid representing the typographic bounds for glyphs in the text range. If the specified range of text encloses nested bidirectional text, ATSUGetGlyphBounds produces multiple trapezoids defining these regions.In ATSUI 1.1, the maximum number of enclosing trapezoids that can be returned is 31; in ATSUI 1.2, the maximum number is 127. If you pass a range that covers an entire line, ATSUGetGlyphBounds returns 1 trapezoid. If you are uncertain of how much memory to allocate for this array, see the Discussion.

    oActualNumberOfBounds

    A pointer to an ItemCount value. On return, the value specifies the actual number of enclosing trapezoids bounding the specified characters. This may be greater than the value you provide in the iMaxNumberOfBounds parameter.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    There are two kinds of bounds that your application may typically want to obtain for a block of text: typographic bounds and image bounds. The image bounds define the smallest rectangle that completely encloses the filled or framed parts of a block of text—that is, the text’s “inked” glyphs. Because of the potential differences in glyph height in a text block, your application may instead need to determine the typographic bounds. The typographic bounding rectangle contains the extra space above and below the image bounding rectangle where characters with ascenders or descenders would be drawn (even if none currently are).

    The ATSUGetGlyphBounds function produces the enclosing trapezoid(s) that represent the typographic bounds for glyphs in a final, laid-out range of text. You typically call this function when you need to obtain an enclosing trapezoid for a line, taking rotation and all other layout attributes into account.

    ATSUI determines the height of each trapezoid by examining any line ascent and descent attribute values you may have set for the line. If you have not set these attributes for the line, the ATSUGetGlyphBounds function uses any line ascent and descent values you may have set for the text layout object containing the line. If these are not set, ATSUGetGlyphBounds uses the font’s natural line ascent and descent values for the line. If these are previously set, ATSUGetGlyphBounds uses the ATSUStyle ascent and or descent/leading values.

    Depending on the value you pass in the iTypeOfBounds parameter, the width of the resulting trapezoid(s) is determined using one of the following values:

    • the caret origin, located halfway between two characters, which should be used when performing your own highlighting

    • the glyph origin in device space, which is useful for obtaining bounds adjusted for specific rendering and device constraints

    • the glyph origin in fractional (or “ideal”) absolute positions, uncorrected for device display

    Note that the coordinates produced for the trapezoid(s) are offset by the amount specified in the iTextBasePointX and iTextBasePointY parameters. If your goal in calling the ATSUGetGlyphBounds function is to obtain metrics for drawing the typographic bounds on the screen, pass the position of the origin of the line in the current graphics port or graphics context in these parameters. This enables ATSUGetGlyphBounds to match the trapezoids to their onscreen image.

    Before calculating the typographic glyph bounds for the given text range, the ATSUGetGlyphBounds function 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, ATSUGetGlyphBounds 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, ATSUGetGlyphBounds assigns these characters to the first style run it can find. If there is no style run at the end of the range of text, ATSUGetGlyphBounds assigns the remaining characters to the last style run it can find.

    Typically you use the ATSUGetGlyphBounds function by calling it twice, as follows:

    1. Pass NULL for the oGlyphBounds parameter, 0 for the iMaxNumberOfBounds parameter, and valid values for the other parameters. The ATSUGetGlyphBounds function returns the actual number of trapezoids needed to enclose the glyphs in the oActualNumberOfBounds parameter.

    2. Allocate enough space for a buffer of the returned size, then call the function again, passing a valid pointer to the buffer in the oGlyphBounds parameter. On return, the buffer contains the trapezoids for the glyphs’ typographic bounds.

    To obtain the typographic bounds of a line of text prior to line layout, call the function ATSUGetUnjustifiedBounds. To calculate the image bounding rectangle for a final laid-out line, call the function ATSUMeasureTextImage.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains resolution-independent font metric information for glyphs associated with a given style object.

    Declaration

    Objective-C

    OSStatus ATSUGlyphGetIdealMetrics ( ATSUStyle iATSUStyle, ItemCount iNumOfGlyphs, GlyphID iGlyphIDs[], ByteOffset iInputOffset, ATSGlyphIdealMetrics oIdealMetrics[] );

    Parameters

    iATSUStyle

    An ATSUStyle value specifying the style object to examine.

    iNumOfGlyphs

    An ItemCount value specifying the number of glyphs to examine. This value should be the same as the number of glyph IDs being passed in the iGlyphIDs parameter and the number of ATSGlyphIdealMetrics structures for which memory is allocated in the oIdealMetrics parameter.

    iGlyphIDs

    A pointer to the first GlyphID value in an array of glyph IDs. Each ID should identify a glyph for which to obtain font metric information.

    iInputOffset

    A ByteOffset value specifying the offset in bytes between glyph IDs in the iGlyphIDs array.

    oIdealMetrics

    A pointer to memory you have allocated for an array of ATSGlyphIdealMetrics structures. On return, each structure contains advance and side-bearing values for a glyph.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The advance width is the full horizontal width of the glyph as measured from its origin to the origin of the next glyph on the line, including the left-side and right-side bearings. For vertical text, the advance height is the sum of the top-side bearing, the bounding-box height, and the bottom-side bearing.

    You can call the ATSUGlyphGetIdealMetrics function to obtain an array of ATSGlyphIdealMetrics structures containing values for the specified glyphs’ advance and side bearings. ATSUGlyphGetIdealMetrics can analyze both horizontal and vertical text, automatically producing the appropriate bearing values (oriented for width or height, respectively) for each.

    You should call ATSUGlyphGetIdealMetrics to obtain resolution-independent glyph metrics. To obtain device-adjusted (that is, resolution-dependent) glyph metrics, call the function ATSUGlyphGetScreenMetrics.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains device-adjusted font metric information for glyphs associated with a given style object.

    Declaration

    Objective-C

    OSStatus ATSUGlyphGetScreenMetrics ( ATSUStyle iATSUStyle, ItemCount iNumOfGlyphs, GlyphID iGlyphIDs[], ByteOffset iInputOffset, Boolean iForcingAntiAlias, Boolean iAntiAliasSwitch, ATSGlyphScreenMetrics oScreenMetrics[] );

    Parameters

    iATSUStyle

    An ATSUStyle value specifying the style object to examine.

    iNumOfGlyphs

    An ItemCount value specifying the number of glyphs to examine. This value should be the same as the number of glyph IDs being passed in the iGlyphIDs parameter and the number of ATSGlyphScreenMetrics structures for which memory is allocated in the oScreenMetrics parameter.

    iGlyphIDs

    A pointer to the first GlyphID value in an array of glyph IDs. Each ID should identify a glyph for which to obtain font metric information.

    iInputOffset

    A ByteOffset value specifying the offset in bytes between glyph IDs in the iGlyphIDs array.

    iForcingAntiAlias

    A Boolean value indicating whether anti-aliasing is forced for the style object.

    iAntiAliasSwitch

    A Boolean value indicating whether anti-aliasing is currently on or off.

    oScreenMetrics

    A pointer to memory you have allocated for an array of ATSGlyphScreenMetrics structures. On return, each structure contains device-adjusted metrics for a glyph, including advance and side bearings, but also values for the top left, height, and width of the glyph.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    You can call the ATSUGlyphGetScreenMetrics function to obtain an array of ATSGlyphScreenMetrics structures containing values for the specified glyphs’ advance and side bearings, top left, height, and width.

    You should call ATSUGlyphGetScreenMetrics to obtain device-adjusted (that is, resolution-dependent) glyph metrics. To obtain resolution-independent glyph metrics, call the function ATSUGlyphGetIdealMetrics.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the type of outline path used for glyphs associated with a given style object.

    Declaration

    Objective-C

    OSStatus ATSUGetNativeCurveType ( ATSUStyle iATSUStyle, ATSCurveType *oCurveType );

    Parameters

    iATSUStyle

    An ATSUStyle value specifying the style object to examine.

    oCurveType

    A pointer to an ATSCurveType value. On return, the value provides a constant specifying the type of outline path being used. Possible values include kATSCubicCurveType, kATSQuadCurveType, and kATSOtherCurveType.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    You can call the ATSUGetNativeCurveType function to obtain the type of outline path used for glyphs associated with a given style object.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the outline paths for a glyph associated with a given style object.

    Declaration

    Objective-C

    OSStatus ATSUGlyphGetCurvePaths ( ATSUStyle iATSUStyle, GlyphID iGlyphID, ByteCount *ioBufferSize, ATSUCurvePaths *oPaths );

    Parameters

    iATSUStyle

    An ATSUStyle value specifying the style object to examine.

    iGlyphID

    A GlyphID value identifying the glyph for which to obtain an outline path.

    ioBufferSize

    A pointer to a ByteCount value specifying the size of the buffer you have allocated for the ATSUCurvePaths structure in the oPaths parameter. On return, the value provides the actual size of buffer needed to contain the produced ATSUCurvePaths structure.

    oPaths

    A pointer to an ATSUCurvePaths structure. On return, the ATSUCurvePaths structure contains a value specifying the number of contours that comprise the glyph’s outline, as well as an array of ATSUCurvePath structures, each of which defines a contour.

    Return Value

    A result code. See ATSUI Result Codes. If the font is a protected font, returns kATSUInvalidFontErr.

    Discussion

    This function only returns quadratic paths. The glyph outlines that are returned are the hinted outlines at the font size specified in the style object. If you want to obtain unhinted outlines, set the font size to a very large size, (for example, 1000 points) and then scale down the returned curves to the desired size. More typically, however, you would use the functions ATSUGlyphGetCubicPaths and ATSUGlyphGetQuadraticPaths when drawing curves.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the cubic outline paths for a glyph.

    Declaration

    Objective-C

    OSStatus ATSUGlyphGetCubicPaths ( ATSUStyle iATSUStyle, GlyphID iGlyphID, ATSCubicMoveToUPP iMoveToProc, ATSCubicLineToUPP iLineToProc, ATSCubicCurveToUPP iCurveToProc, ATSCubicClosePathUPP iClosePathProc, void *iCallbackDataPtr, OSStatus *oCallbackResult );

    Parameters

    iATSUStyle

    An ATSUStyle value specifying the style object to examine.

    iGlyphID

    A GlyphID value identifying the glyph for which to obtain an outline path.

    iMoveToProc

    A pointer to your callback function for handling the pen move-to operation.

    iLineToProc

    A pointer to your callback function for handling the line-to operation.

    iCurveToProc

    A pointer to your callback function for handling the curve-to operation.

    iClosePathProc

    A pointer to your callback function for handling the close-path operation.

    iCallbackDataPtr

    A pointer to any data your callback functions need. This pointer is passed through to your callback functions.

    oCallbackResult

    On output, a value that indicates the status of your callback function. When a callback function returns any value other than 0, the ATSGlyphGetCubicPaths function stops parsing the glyph path outline and returns the result kATSOutlineParseAbortedErr.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The glyph outlines that are returned are the hinted outlines at the font size specified in the style object. If you want to use unhinted outlines, set the font size to a very large size, (for example, 1000 points) and then scale down the returned curves to the desired size.

    As of Mac OS X version 10.1, the curves returned by this function are derived from quadratic curves, irrespective of the native curve type of the font.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the quadratic outline paths for a glyph.

    Declaration

    Objective-C

    OSStatus ATSUGlyphGetQuadraticPaths ( ATSUStyle iATSUStyle, GlyphID iGlyphID, ATSQuadraticNewPathUPP iNewPathProc, ATSQuadraticLineUPP iLineProc, ATSQuadraticCurveUPP iCurveProc, ATSQuadraticClosePathUPP iClosePathProc, void *iCallbackDataPtr, OSStatus *oCallbackResult );

    Parameters

    iATSUStyle

    An ATSUStyle value specifying the style object to examine.

    iGlyphID

    A GlyphID value identifying the glyph for which to obtain an outline path.

    iNewPathProc

    A pointer to your callback function for handling the new-path operation.

    iLineProc

    A pointer to your callback function for handling the line operation.

    iCurveProc

    A pointer to your callback function for handling the curve operation.

    iClosePathProc

    A pointer to your callback function for handling the close-path operation.

    iCallbackDataPtr

    A pointer to any data your callback functions need. This pointer is passed through to your callback functions.

    oCallbackResult

    On output, a value that indicates the status of your callback function. When a callback function returns any value other than 0, the ATSGlyphGetQuadraticPaths function stops parsing the path outline and returns the result kATSOutlineParseAbortedErr.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The glyph outlines that are returned are the hinted outlines at the font size specified in the style object. If you want to use unhinted outlines, set the font size to a very large size, (for example, 1000 points) and then scale down the returned curves to the desired size.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Sets a tab ruler for a text layout object.

    Declaration

    Objective-C

    OSStatus ATSUSetTabArray ( ATSUTextLayout iTextLayout, const ATSUTab iTabs[], ItemCount iTabCount );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object for which you want to set a tab ruler.

    iTabs[]

    An array of the tab values you want applied to the text layout object. This tab ruler is applied to all lines in the text layout object. You can pass NULL if iTabCount equals 0. Passing NULL effectively deletes any tab ruler that was set previously.

    iTabCount

    The number of tabs in the given iTabs array. If value is 0, any previously-set tab ruler is cleared from the text layout object.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    When a tab ruler is set for a text layout object, ATSUI automatically aligns text such that any tabs in the text are laid out to follow the tab ruler’s specifications. If you want to use tabs in your text and you also want to use the function ATSUBatchBreakLines, then you must set tabs by calling the function ATSUSetTabArray.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Retrieves the tab ruler associated with a text layout object.

    Declaration

    Objective-C

    OSStatus ATSUGetTabArray ( ATSUTextLayout iTextLayout, ItemCount iMaxTabCount, ATSUTab oTabs[], ItemCount *oTabCount );

    Parameters

    iTextLayout

    An ATSUTextLayout value specifying the text layout object whose tab ruler you want to obtain.

    iMaxTabCount

    The maximum number of tabs that can be written to the iTabs array.

    oTabs[]

    An array of ATSUTab values. On return, this array contains the current tab values in order of position along the line from left to right. Pass NULL if you want to retrieve the number of tabs, but not the tab values.

    oTabCount

    The number of tabs set for the text layout object.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    This function can be used to retrieve all the tabs that were previously set for a text layout object, using the function ATSUSetTabArray. All the returned tabs will be in order of position along the line.Typically you use the ATSUGetTabArray function by calling it twice, as follows:

    1. Pass NULL for the oTabs parameter, 0 for the iMaxTabCount parameter, and valid values for the other parameters. The ATSUGetTabArray function returns the actual number of tabs in the oTabCount parameter.

    2. Allocate enough space for a buffer of the returned size, then call the function again, passing a valid pointer to the buffer in the oTabs parameter. On return, the buffer contains the tab values in order of position along the line from left to right.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Obtains the glyph data specified by a direct-data selector and for a specific line of text.

    Declaration

    Objective-C

    OSStatus ATSUDirectGetLayoutDataArrayPtrFromLineRef ( ATSULineRef iLineRef, ATSUDirectDataSelector iDataSelector, Boolean iCreate, void *oLayoutDataArrayPtr[], ItemCount *oLayoutDataCount );

    Parameters

    iLineRef

    An ATSULineRef value that specifies the line of text whose data you want to obtain. You should pass the same ATSULineRef value passed to the ATSUDirectLayoutOperationOverrideProcPtr callback function from which you are calling this function.

    iDataSelector

    A direct-data selector constant that specifies the data you want to obtain. You can pass any of the constants described in Direct Data Selectors.

    iCreate

    A Boolean value that specifies whether to create an array if one does not already exist. Pass true if you want an array created. If the line referenced by the iLineRef parameter does not already have an array created that contains the data specified by the iDataSelector parameter, then ATSUI creates a zero-filled array and returns the array in the oLayoutDataArray parameter. The iCreate parameter has no effect for some data specified by the direct-data selector. See Direct Data Selectors for details.

    oLayoutDataArrayPtr[]

    On return, points to an array that contains the data specified by the iDataSelector parameter. The data is for the line of text referenced by the iLineRef parameter. If an array for the specified data does not exist, and if the iCreate is set to false, ATSUI returns NULL. If an array for the specified data does not exist, and if the iCreate is set to true, ATSUI creates a zero-filled array. You can pass NULL if you only want to obtain the number of entries in the array returned in the oLayoutDataArray array.

    oLayoutDataCount

    On return, the number of entries in the array returned in the oLayoutDataArray array.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The function ATSUDirectGetLayoutDataArrayPtrFromLineRef returns the data pointer specified by the iDataSelector parameter and referenced by the iLineRef parameter. You must call this function from within an ATSUDirectLayoutOperationOverrideProcPtr callback function. You must only release the data pointer by calling the function ATSUDirectReleaseLayoutDataArrayPtr. When you call this function, it signals ATSUI that you are done with the data and that ATSUI can merge your modifications with the font’s data. If you do not properly free the data by calling the function ATSUDirectReleaseLayoutDataArrayPtr, a memory leak may result.

    The data you obtain is the actual data used by ATSUI in its layout process; it is not a copy. This function is very efficient because ATSUI does not need to allocate memory and copy data. Furthermore, because you obtain a pointer to the data that ATSUI uses for its layout, any modifications you make to the data effect the final layout.

    Many of the data arrays you can request are created by ATSUI only when necessary. If you plan to alter the data in an array, make sure you set the iCreate parameter to true. This ensures that the array is created. If an arrays are not created, ATSUI assumes all entries in the array are zero.

    The pointer returned by this function is only valid within the context of the ATSUDirectLayoutOperationOverrideProcPtr callback function. You must not retain it for later use.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.6.

  • Obtains a copy of the glyph data specified by a direct-data selector and for a specific line of text in a text layout object.

    Declaration

    Objective-C

    OSStatus ATSUDirectGetLayoutDataArrayPtrFromTextLayout ( ATSUTextLayout iTextLayout, UniCharArrayOffset iLineOffset, ATSUDirectDataSelector iDataSelector, void *oLayoutDataArrayPtr[], ItemCount *oLayoutDataCount );

    Parameters

    iTextLayout

    An ATSUTextLayout value that specifies the text layout object whose data you want to obtain.

    iLineOffset

    The edge offset that corresponds to the beginning of the line of text whose data you want to obtain.

    iDataSelector

    A direct-data selector constant that specifies the data you want to obtain. You can pass any of the constants described in Direct Data Selectors.

    oLayoutDataArrayPtr[]

    On return, points to an array that contains the data specified by the iDataSelector parameter. The data is for the line of text referenced by the iLineOffset parameter. If an array for the specified data does not exist, ATSUI returns NULL. You can pass NULL if you only want to obtain the number of entries in the array in the oLayoutDataArray array.

    oLayoutDataCount

    On return, the number of entries in the array oLayoutDataArray.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The function ATSUDirectGetLayoutDataArrayPtrFromTextLayout returns a pointer to the data specified by iDataSelector and referenced by iTextLayout for the line starting at iLineOffset. You must not call this function from within an ATSUDirectLayoutOperationOverrideProcPtrcallback function.

    You should only release the data pointer by calling the function ATSUDirectReleaseLayoutDataArrayPtr. When you call this function, it signals ATSUI that you are done with the data and that ATSUI can merge your modifications with the font’s data. If you do not properly free the data by calling the function ATSUDirectReleaseLayoutDataArrayPtr, a memory leak may result.

    The data you obtain is a copy of the data ATSUI uses for its layout processes. This means the following:

    • Obtaining data through a copy operation takes more time than obtaining the actual data. This function returns in order-n time instead of in a constant time.

    • Changing any of the data values has no effect on the layout.

    Before you use this function, you should consider using the functionATSUDirectGetLayoutDataArrayPtrFromLineRef with the kATSULayoutOperationPostLayoutAdjustment selector.

    If you use the function ATSUDirectGetLayoutDataArrayPtrFromTextLayout to obtain the ATSUStyleSettingRef array, the structures referenced by each element of the array are invalid after you call the function ATSUDirectReleaseLayoutDataArrayPtr to release the array. If want to retain one or more of the elements in the ATSUStyleSettingRef array for later use, you must not call the function ATSUDirectReleaseLayoutDataArrayPtr until all operations that use the elements in the ATSUStyleSettingRef in the array are complete. The elements in the ATSUStyleSettingRef array are valid only within the context of the callback from which they were obtained

    Many of the requested data arrays are created by ATSUI only when necessary. This means that it's possible for the function ATSUDirectGetLayoutDataArrayPtrFromTextLayout to return a NULL pointer and a count of 0. If this is case and if the function does not return an error, the array doesn't exist. You should interpret this result to mean that all values in the array are 0.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Releases a pointer to a direct-data array.

    Declaration

    Objective-C

    OSStatus ATSUDirectReleaseLayoutDataArrayPtr ( ATSULineRef iLineRef, ATSUDirectDataSelector iDataSelector, void *iLayoutDataArrayPtr[] );

    Parameters

    iLineRef

    An ATSULineRef value that specifies the line of text whose data is pointed to by the iLayoutDataArrayPtr parameter. Pass NULL if you did not obtain the layout data array pointer using a lineRef.

    iDataSelector

    A direct-data selector constant that specifies the data pointed to by the iLayoutDataArrayPtr parameter. You can pass any of the constants described in Direct Data Selectors.

    iLayoutDataArrayPtr[]

    A pointer to the layout data array of which you want to dispose.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    You must call the function ATSUDirectReleaseLayoutDataArrayPtr when you no longer need the direct-data pointer you obtained from the ATSUDirectGetLayoutDataArrayPtrFromLineRef or ATSUDirectGetLayoutDataArrayPtrFromTextLayout functions. You must dispose of the pointer to inform ATSUI you no longer need the data and to allow for ATSUI to make any internal adjustments prior to completing the layout process.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.6.

  • Looks up, and if necessary, adds a style setting to a line of text.

    Declaration

    Objective-C

    OSStatus ATSUDirectAddStyleSettingRef ( ATSULineRef iLineRef, ATSUStyleSettingRef iStyleSettingRef, UInt16 *oStyleIndex );

    Parameters

    iLineRef

    An ATSULineRef value that specifies the line of text to which you want to add a style setting. You should pass the same reference provided as a parameter to your ATSUDirectLayoutOperationOverrideProcPtr callback function.

    iStyleSettingRef

    An ATSUStyleSettingRef value that specifies the style setting you want ATSUI to look up or add to the text layout object referenced by the line starting at the offset iLineOffset.

    oStyleIndex

    On return, points to the index of the ATSUStyleSettingRef passed in iStyleSettingRef for the line referenced by iLineRef. If the ATSUStyleSettingRef does not exist in that context, ATSUI adds it and returns the index value.

    Return Value

    A result code. See ATSUI Result Codes.

    Discussion

    The function ATSUDirectAddStyleSettingRef checks to see if a line of text has a specified style setting reference associated with it. If the style setting reference is not associated with the line of text, ATSUI adds the style setting reference.

    You must call this function from within an ATSUDirectLayoutOperationOverrideProcPtr callback function. You can use the function ATSUDirectAddStyleSettingRef to replace or substitute glyphs. For example, you can check a line of text for a specific character, such as a whitespace character. When your application finds a whitespace character, it can call the function ATSUDirectAddStyleSettingRef to set style attributes that achieve the desired effect.

    Do not call this function if you obtained an ATSUStyleSettingRef array for the line specified by iLineRef and have not yet disposed of the pointer to this array by calling the function ATSUDirectReleaseLayoutDataArrayPtr, as the pointer is not guaranteed to be valid after you call the function ATSUDirectAddStyleSettingRef.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Flattens ATSUI style-run data so that it can be saved to disk or passed (through the pasteboard) to another application.

    Declaration

    Objective-C

    OSStatus ATSUFlattenStyleRunsToStream ( ATSUFlattenedDataStreamFormat iStreamFormat, ATSUFlattenStyleRunOptions iFlattenOptions, ItemCount iNumberOfRunInfo, const ATSUStyleRunInfo iRunInfoArray[], ItemCount iNumberOfStyleObjects, const ATSUStyle iStyleArray[], ByteCount iStreamBufferSize, void *oStreamBuffer, ByteCount *oActualStreamBufferSize );

    Parameters

    iStreamFormat

    The format of the flattened data. There is only one format supported at this time, 'ustl' so you must pass the constant kATSUDataStreamUnicodeStyledText.

    iFlattenOptions

    The options you want to use to flatten the data. There are no options supported at this time, so you must pass the constant kATSUFlattenOptionsNoOptionsMask.

    iNumberOfRunInfo

    The number of style run information structures passed in the iRunInfoArray parameter. If you pass 0, ATSUI assumes there is only one style for the entire text block passed in the oStreamBuffer parameter. The flattened data format passed to the iStreamFormat parameter must support the use of one style.

    iRunInfoArray[]

    An array of ATSUStyleRunInfo structures that describes the style runs to be flattened. This array must contain iNumberOfRunInfo entries. An ATSUStyleRunInfo structure contains an index into an array of unique ATSUI style objects (ATSUStyle) and the length of the run to which the style object applies. Each index in the ATSUStyleRunInfo structure must reference a valid ATSUStyle object passed in the iStyleArray parameter. You can pass NULL, only if iNumberOfRunInfo is set to zero.

    iNumberOfStyleObjects

    The number of ATSUStyle objects in the array passed to the iStyleArray parameter. You must pass a value that is greater than 0.

    iStyleArray[]

    An array of ATSUStyle objects to be flattened. You cannot pass NULL.

    iStreamBufferSize

    The size of the stream buffer, pointed to by the oStreamBuffer parameter. You can pass 0 only if the iStreamBufferSize parameter is set to NULL. If you are uncertain of the size of the array, see the Discussion.

    oStreamBuffer

    On input, a pointer to the data you want to flatten. On return, points to the flattened data. If you pass NULL for this parameter, no data is flattened. Instead, the size of the buffer is calculated by ATSUI and returned in oActualStreamSize parameter. See the Discussion for more details. You are responsible for allocating the text buffer passed in the oStreamBuffer parameter.

    oActualStreamBufferSize

    On return, the size of the data written to the oStreamBuffer parameter. You can pass NULL only if the oStreamBuffer parameter is not NULL.

    Return Value

    A result code. See ATSUI Result Codes. This function can also return paramErr if you pass invalid values for any of the parameters.

    Discussion

    The function ATSUFlattenStyleRunsToStream takes an array of ATSUStyle objects and style run information and flattens the data to the specified format. The style runs must all reference the same block of Unicode text (usually passed separately as text in the 'utxt' format). The style runs must also be in ascending order relative to the text in the text block.

    Typically you use the function ATSUFlattenStyleRunsFromStream by calling it twice, as follows:

    1. Provide appropriate values for the iStreamFormat, iFlattenOptions, iNumberOfRunInfo, iRunInfoArray, iNumberOfStyleObjects, and iStyleArray parameters. Set iStreamBufferSize to 0, oStreamBuffer to NULL, and pass a valid reference to a ByteCount variable in the oActualStreamBufferSize parameter. Call the function ATSUFlattenStyleRunsToStream. On return, oActualStreamBufferSize points to the size needed for the buffer.

    2. Allocate an appropriately-sized buffer for the oStreamBuffer parameter and then call the function ATSUFlattenStyleRunsToStream a second time.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.

  • Unflattens previously-flattened ATSUI style run data so that it can be read from disk or accepted (through the pasteboard) from another application.

    Declaration

    Objective-C

    OSStatus ATSUUnflattenStyleRunsFromStream ( ATSUFlattenedDataStreamFormat iStreamFormat, ATSUUnFlattenStyleRunOptions iUnflattenOptions, ByteCount iStreamBufferSize, const void *iStreamBuffer, ItemCount iNumberOfRunInfo, ItemCount iNumberOfStyleObjects, ATSUStyleRunInfo oRunInfoArray[], ATSUStyle oStyleArray[], ItemCount *oActualNumberOfRunInfo, ItemCount *oActualNumberOfStyleObjects );

    Parameters

    iStreamFormat

    The format of the flattened data. There is only one format supported at this time ('ustl') so you must pass the constant kATSUDataStreamUnicodeStyledText.

    iUnflattenOptions

    The options you want to use to unflatten the data. There are no options supported at this time, so you must pass the constant kATSUUnflattenOptionsNoOptionsMask.

    iStreamBufferSize

    The size of the buffer pointed to by the iStreamBuffer parameter. You must pass a value greater than 0.

    iStreamBuffer

    A pointer to the buffer that contains the flattened data. The data must be of the format specified by the iStreamFormat parameter and must be of size specified by the iStreamBufferSize parameter. You cannot pass NULL.

    iNumberOfRunInfo

    The number of style run information structures passed in the iRunInfoArray parameter. If you are uncertain of the number of style run information structures, see the Discussion.

    iNumberOfStyleObjects

    The number of ATSUStyle objects in the array passed into the iStyleArray parameter. If you are uncertain of the number of ATSUStyle objects, see the Discussion.

    oRunInfoArray[]

    On return, points to an array of style run information structures. Each structure contains a style run length and index into the oStyleArray array. If you are uncertain of how much memory to allocate for this array, see the Discussion. You are responsible for disposing of the array when you no longer need it.

    oStyleArray[]

    On return, a pointer to an array of the unique ATSUI style objects (ATSUStyle) obtained from the flattened data. The indices returned in the array oRunInfoArray are indices into this array. If you are uncertain of how much memory to allocate for this array, see the Discussion. You are responsible for disposing of the array and the ATSUI style objects in the array when you no longer need the array.

    oActualNumberOfRunInfo

    On return, points to the actual number of ATSUStyleRunInfo structures obtained from the flattened data. The actual number of structures is the number of entries added to the array oRunInfoArray. You can pass NULL if you to not want to obtain this value.

    oActualNumberOfStyleObjects

    On return, points to the actual number of unique ATSUI style objects (ATSUStyle) obtained from the flattened data. The actual number is the number of entries added to the oStyleArray array. You can pass NULL if you do no want to obtain this value.

    Return Value

    A result code. See ATSUI Result Codes. This function can also return paramErr if you pass invalid values for any of the parameters.

    Discussion

    The function ATSUUnflattenStyleRunsFromStream extracts the ATSUI style run information from previously-flattened data. The style objects and style run information structures are returned in two separate arrays—the array oStyleArray and the array oRunInfoArray. These arrays are not parallel. Each ATSUStyle object in the oStyleArray is a unique ATSUStyle object. To figure out which ATSUStyle object belongs to which text run, the caller must parse the array of ATSUStyleRunInfo structures. These structures contain the style run lengths and an index into the oStyleArray.

    Typically you use the function ATSUUnflattenStyleRunsFromStream by calling it twice, as follows:

    1. Provide appropriate values for the iStreamFormat, iUnflattenOptions, and iStreamBuffer parameters. Pass 0 for the iNumberOfRunInfo and iNumberOfStyleObjects parameters, NULL for the oRunInfoArray and oStyleArray, parameters and valid ItemCount references for the oActualNumberOfRunInfo and oActualNumberOfStyleObjects parameters. On return, oActualNumberOfRunInfo and oActualNumberOfStyleObjects point to the sizes needed to allocate these arrays.

    2. Allocate appropriately-sized arrays of ATSUStyleRunInfo data structures and ATSUStyle objects. Call the function ATSUUnflattenStyleRunsFromStream a second time, passing the newly allocated arrays in the oRunInfoArray and oStyleArray parameters, with the iNumberOfRunInfo and iNumberOfStyleObjects parameters set to the values you obtained from the first call.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.6.

    Not available to 64-bit applications.