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

Next Page > Hide TOC

Apple Type Services for Fonts Reference

Framework
ApplicationServices/ApplicationServices.h
Declared in
ATSFont.h
ATSTypes.h

Overview

Apple Type Services for Fonts is a collection of functions and data types that you can use to access and manage font data in Mac OS X. It is designed to handle a wide range of font technologies and data formats. The programming interface is designed with performance, scalability, and consistency in mind, and is available to Cocoa and Carbon applications through the Apple Type Services (ATS) and QuickDraw frameworks in Mac OS X.

Carbon supports the Apple Type Services for Fonts.

Functions by Task

Activating and Deactivating Fonts

Working With Font Families

Working With Fonts

Setting Up Notifications and Queries

Creating, Calling, and Deleting Universal Procedure Pointers

Functions

ATSCreateFontQueryRunLoopSource

Sets up your application to handle font queries.

CFRunLoopSourceRef ATSCreateFontQueryRunLoopSource (
   CFIndex queryOrder,
   CFIndex sourceOrder,
   ATSFontQueryCallback callout,
   const ATSFontQuerySourceContext *context
);

Parameters
queryOrder

A CFIndex value that specifies the priority of the query relative to other queries. ATS sends font queries to each run loop in priority order, from highest to lowest, with normal priority equal to 0.

sourceOrder

A CFIndex value that specifies the order of the run loop source.

callout

A pointer to your callback for processing a font query. See ATSFontQueryCallback for more information on the callback you can supply.

context

A pointer to font query source context that ATS passes to your callback function. You can pass NULL if your callback function does not need any data passed to it.

Return Value

A CFRunLoopSourceRef. When you want to stop receiving queries, you must invalidate this reference.

Discussion

When an application needs a font, ATS sends a query to those font utility applications who have signed up to handle queries by calling the function ATSCreateFontQueryRunLoopSource. When a font utility application receives a query, it iterates through its available fonts to look for the requested font. If the font utility application finds the font, it obtains the file specification for the font and sends the file specification to ATS. ATS activates the font and sends notification of the activation to each application who subscribes to notifications.

The function ATSCreateFontQueryRunLoopSource creates a Core Foundation run loop source reference (CFRunLoopSourceRef) to convey font queries from ATS to your font utility application. If your application does not have a CFRunLoop (for example, a faceless server application), you must explicitly set up a CFRunLoop before you can receive queries.

Availability
Declared In
ATSFont.h

ATSFontActivateFromFileReference

Activates one or more fonts from a file reference.

OSStatus ATSFontActivateFromFileReference (
   const FSRef *iFile,
   ATSFontContext iContext,
   ATSFontFormat iFormat,
   void *iRefCon,
   ATSOptionFlags iOptions,
   ATSFontContainerRef *oContainer
);

Parameters
iFile

A pointer to the file reference that specifies the name and location of a file or directory that contains the font data you want to activate.

iContext

A value that specifies the context of the activated font. If you want the activated font to be accessible only from your application use the kATSFontContextLocal constant. If you want the activated font to be accessible to all applications use the constant kATSFontContextGlobal. See “Context Options” for more information.

iFormat

A value that represents the format identifier of the font. Pass kATSFontFormatUnspecified as the system automatically determines the format of the font. For more information on this constant, see “Font Formats.”

iRefCon

This parameter is currently reserved for future use, so you should pass NULL.

iOptions

An options flag. Pass kATSOptionFlagsDefault unless the font’s data fork contains resource-fork information, you need to activate a directory of font directories, or you plan to call this function a number of time. If the font’s data fork contains resource-fork information, pass the option kATSOptionFlagsUseDataForkAsResourceFork. If the you want to activate a font directory that contains font directories, you must pass the option kATSOptionFlagsProcessSubdirectories. If you plan to call this function a number of times, you can set the iOptions parameter to kATSOptionFlagsDoNotNotify set. When you are done activating fonts you can call the function ATSFontNotify with the action parameter set to kATSFontNotifyActionFontsChanged. Then ATS notifies all applications who subscribe to notifications of the changes you made.

oContainer

On output, a reference to the font container that is activated from the file reference. You need this reference when you deactivate the font by calling the function ATSFontDeactivate.

Return Value

If activated successfully, noErr.

Availability
Declared In
ATSFont.h

ATSFontActivateFromMemory

Activates one or more fonts at the specified location in memory.

OSStatus ATSFontActivateFromMemory (
   LogicalAddress iData,
   ByteCount iLength,
   ATSFontContext iContext,
   ATSFontFormat iFormat,
   void *iReserved,
   ATSOptionFlags iOptions,
   ATSFontContainerRef *oContainer
);

Parameters
iData

The logical address of the font you want to activate.

iLength

The length (in bytes) of the font data.

iContext

A value that specifies the context of the activated font. If you want the activated font to be accessible only from your application use the kATSFontContextLocal constant. If you want the activated font to be accessible to all applications use the constant kATSFontContextGlobal. See “Context Options” for more information.

iFormat

A value that represents the format identifier of the font. There is only one font format constant available for you to pass—kATSFontFormatUnspecified. This constant specifies the default behavior, which is to handle the data as raw TrueType font data. This is equivalent to the contents of an 'sfnt' font resource or the data fork of a Windows TrueType .ttf or .ttc file. You can also activate the contents of an OpenType TrueType .OTF file. See “Font Formats” for more information.

iReserved

An arbitrary 32-bit value. This parameter is currently reserved for future use, so you should pass NULL.

iOptions

An ATSOptionFlags value. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault.

oContainer

On output, a pointer to a font container reference that refers to the file that contains the activated font data.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Discussion

You use this function to activate a streamed font, such as a font contained in a PDF file. Your application must first map the streamed font data to memory and then pass the address of the font data in memory to the function ATSFontActivateFromMemory.

Availability
Declared In
ATSFont.h

ATSFontApplyFunction

Applies your callback to a font iteration.

OSStatus ATSFontApplyFunction (
   ATSFontApplierFunction iFunction,
   void *iRefCon
);

Parameters
iFunction

The callback function you want applied to a font iteration. See ATSFontApplierFunction for more information on the callback you need to supply.

iRefCon

An arbitrary 32-bit value specified by your application. This is passed to your callback.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Discussion

The function ATSFontApplyFunction iterates through the default fonts, which include globally activated fonts and fonts activated locally to your application. Calling this function is similar to creating an iterator that operates on a local context with an unrestricted scope.

Availability
Declared In
ATSFont.h

ATSFontDeactivate

Deactivates one or more fonts.

OSStatus ATSFontDeactivate (
   ATSFontContainerRef iContainer,
   void *iRefCon,
   ATSOptionFlags iOptions
);

Parameters
iContainer

A font container reference that refers to the file containing the activated font data. You obtain a font container reference when you activate a font by calling the functions ATSFontActivateFromFileSpecification or ATSFontActivateFromMemory.

iRefCon

An arbitrary 32-bit value specified. This parameter is currently reserved for future use, so you should pass NULL.

iOptions

An ATSOptionFlags value. You should pass kATSOptionFlagsDefault unless to plan to call this function a number of times to deactivate many fonts. If you plan to call this function a number of times, you can set the iOptions parameter to kATSOptionFlagsDoNotNotify set. When you are done deactivating fonts you can call the function ATSFontNotify with the action parameter set to kATSFontNotifyActionFontsChanged. ATS notifies all applications who subscribe to notifications of the changes you made.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Discussion

When you deactivate a font, you must supply the font container reference you obtained when you activated the font. You can’t deactivate a font that you did not activate by calling the functions ATSFontActivateFromFileSpecification or ATSFontActivateFromMemory.

You should use caution if you deactivate a font that is available globally, as its deactivation impacts any application that uses that font.

Availability
Declared In
ATSFont.h

ATSFontFamilyApplyFunction

Applies your callback to a font family iteration.

OSStatus ATSFontFamilyApplyFunction (
   ATSFontFamilyApplierFunction iFunction,
   void *iRefCon
);

Parameters
iFunction

The callback function you want applied to a font family iteration. See ATSFontApplierFunction for more information on the callback you need to supply.

iRefCon

An arbitrary 32-bit value specified by your application. This value is passed to your callback.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Discussion

The function ATSFontFamilyApplyFunction iterates through the default font families, which include globally activated font families and font families activated locally to your application. Calling this function is similar to creating an iterator that operates on a local context with an unrestricted scope.

Availability
Declared In
ATSFont.h

ATSFontFamilyFindFromName

Returns the font family reference associated with a font family name.

ATSFontFamilyRef ATSFontFamilyFindFromName (
   CFStringRef iName,
   ATSOptionFlags iOptions
);

Parameters
iName

A reference to a font family name, formatted as a CFString.

iOptions

An ATSOptionFlags value. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault.

Return Value

A reference to the font family specified by the iName parameter. See the description of the ATSFontFamilyRef data type.

Availability
Declared In
ATSFont.h

ATSFontFamilyFindFromQuickDrawName

Returns the font family reference associated with a standard QuickDraw font name.

ATSFontFamilyRef ATSFontFamilyFindFromQuickDrawName (
   ConstStr255Param iName
);

Parameters
iName

A QuickDraw font name.

Return Value

A reference to the font family associated with the font name specified by the iName parameter. See the description of the ATSFontFamilyRef data type.

Availability
Declared In
ATSFont.h

ATSFontFamilyGetEncoding

Returns the text encoding used by a font family.

TextEncoding ATSFontFamilyGetEncoding (
   ATSFontFamilyRef iFamily
);

Parameters
iFamily

A font family reference.

Return Value

On output, a pointer to the text encoding used by the font family associated with the font family reference. See the Text Encoding Conversion Manager documentation for a description of the TextEncoding data type.

Discussion

Once you have obtained the text encoding, you can use Text Encoding Converter Manager function RevertTextEncodingToScriptInfo to extract the script as follows:

status = ATSFontFamilyGetEncoding (myFontFamily, &myTextEncoding)

status = RevertTextEncodingToScriptInfo (myTextEncoding, &myScriptCode);

Availability
Declared In
ATSFont.h

ATSFontFamilyGetGeneration

Returns the generation count of a font family.

ATSGeneration ATSFontFamilyGetGeneration (
   ATSFontFamilyRef iFamily
);

Parameters
iFamily

A font family reference.

Return Value

On output, the generation count for the font family associated with the font family reference. See the description of the ATSGeneration data type.

Discussion

The generation of a font family changes any time part of a font family is removed or added.

Availability
Declared In
ATSFont.h

ATSFontFamilyGetName

Obtains the font family name associated with a font family reference.

OSStatus ATSFontFamilyGetName (
   ATSFontFamilyRef iFamily,
   ATSOptionFlags iOptions,
   CFStringRef *oName
);

Parameters
iFamily

A font family reference.

iOptions

An ATSOptionFlags value. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault.

oName

On output, a reference to the name associated with the font family reference, formatted as a CFString. You are responsible for releasing the CFStringRef.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Availability
Declared In
ATSFont.h

ATSFontFamilyGetQuickDrawName

Obtains the standard QuickDraw font name associated with a font family reference.

OSStatus ATSFontFamilyGetQuickDrawName (
   ATSFontFamilyRef iFamily,
   Str255 oName
);

Parameters
iName

A reference to the font family name whose QuickDraw name you want to obtain.

oName

On input, a Str255 value allocated by your application. On output, the QuickDraw name associated with the font family reference.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Discussion

All font families are assigned a QuickDraw name by the system. The QuickDraw name is almost identical to the font family name.

Availability
Declared In
ATSFont.h

ATSFontFamilyIteratorCreate

Creates a font family iterator that your application can use to access font family objects.

OSStatus ATSFontFamilyIteratorCreate (
   ATSFontContext iContext,
   const ATSFontFilter *iFilter,
   void *iRefCon,
   ATSOptionFlags iOptions,
   ATSFontFamilyIterator *ioIterator
);

Parameters
iContext

A value that specifies the context of the iterator. If you want to apply the font family iterator only to the fonts accessible from your application use the kATSFontContextLocal constant. If you want the to apply the font family iterator to all fonts registered with the system use the constant kATSFontContextGlobal. See “Context Options” for more information on the constants you can supply. See the Discussion for information on the interaction between the iContext and iOptions parameters.

iFilter

A pointer to a filter specification. Pass NULL if you do not want to apply a filter to this iteration. Otherwise, you can use this parameter to restrict the iteration to the font families that match a generation count or criteria you specify in a custom filter function. Pass the filter selector constant kATSFontFilterSelectorGeneration to select a generation filter or the constant kATSFontFilterSelectorFontApplierFunction to select a custom filter. See “Font Filter Selectors” for more information on the constants you can supply.

iRefCon

An arbitrary 32-bit value specified by your application. If you are using a custom filter function, you can use this parameter to pass data to the custom filter function. Otherwise, pass NULL.

iOptions

A value that specifies the scope of the iterator. If you want to iterate through font families that can be used only by your application, pass the constant kATSOptionFlagsRestrictedScope. If you want to iterate through font families that can be used by all applications pass the constant kATSOptionFlagsUnRestrictedScope. See “Scoping Options” for more information on the constants you can supply. See the Discussion for information on the interaction between the iContext and iOptions parameters.

ioIterator

A pointer to a font family iterator. On output, points to an opaque font family iterator ready for you to use. When you no longer need the font family iterator, you should call the function ATSFontFamilyIteratorRelease to release the auxiliary data and memory allocated by the system.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Discussion

Your application can use a font family iterator to access font family objects. A font family iterator is an opaque data structure used by ATS for Fonts to keep track of an iteration over currently active font families. When the font family iterator is initialized, it does not yet reference a font family.

The context and scope you specify for the font family iterator interact as shown in Table 1.

Table 1  The interaction of context and scope in a font family enumeration

Local context

Global context

Restricted scope

Font families activated locally to your application

Only globally activated font families

Unrestricted scope

Defaults font families, which include globally activated font families and font families activated locally to your application

All font families, which include globally activated font families and all other font families activated locally for an application.

Availability
Declared In
ATSFont.h

ATSFontFamilyIteratorNext

Obtains the next font family reference.

OSStatus ATSFontFamilyIteratorNext (
   ATSFontFamilyIterator iIterator,
   ATSFontFamilyRef *oFamily
);

Parameters
iIterator

A pointer to a font family iterator you created with the function ATSFontFamilyIteratorCreate.

oFamily

A pointer to a font family reference. On output, points to the font family reference obtained by the iterator. You are responsible for allocating memory for the font family reference.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Discussion

If any changes are made to the font database while you are using the font family iterator, the iterator is invalidated and the function ATSFontFamilyIteratorNext returns the error kATSIterationScopeModified. To remedy this error, your application must either restart or cancel the enumeration by calling the ATSFontFamilyIteratorReset or the ATSFontFamilyIteratorRelease functions.

Availability
Declared In
ATSFont.h

ATSFontFamilyIteratorRelease

Releases the memory associated with a font family iterator.

OSStatus ATSFontFamilyIteratorRelease (
   ATSFontFamilyIterator *ioIterator
);

Parameters
ioIterator

A pointer to a font family iterator you created with the function ATSFontFamilyIteratorCreate. If you try to use the font family iterator after disposing of its contents through this function, ATS for Fonts returns an error code to your application.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Discussion

If you plan to use the font family iterator again, you should consider calling the function ATSFontFamilyIteratorReset rather than releasing the font family iterator and then creating it again.

Availability
Declared In
ATSFont.h

ATSFontFamilyIteratorReset

Resets a font family iterator to the beginning of the iteration.

OSStatus ATSFontFamilyIteratorReset (
   ATSFontContext iContext,
   const ATSFontFilter *iFilter,
   void *iRefCon,
   ATSOptionFlags iOptions,
   ATSFontFamilyIterator *ioIterator
);

Parameters
iContext

A value that specifies the context of the iterator. If you want to apply the font family iterator only to the fonts accessible from your application use the kATSFontContextLocal constant. If you want the to apply the font family iterator to all fonts registered with the system use the constant kATSFontContextGlobal. See “Context Options” for more information.

iFilter

A pointer to a filter specification. Pass NULL if you do not want to apply a filter to this iteration. Otherwise, you can use this parameter to restrict the iteration to the font families that match a generation count or criteria you specify in a custom filter function. Pass the filter selector constant kATSFontFilterSelectorGeneration to select a generation filter or the constant kATSFontFilterSelectorFontApplierFunction to select a custom filter. See “Font Filter Selectors” for more information on these constants.

iRefCon

An arbitrary 32-bit value specified by your application. If you are using a custom filter function, you can use this parameter to pass data to the custom filter function. If you are not using a custom filter function, pass NULL.

iOptions

An value that specifies the scope of the iterator. If you want to iterate through font families that can be used only by your application, pass the constant kATSOptionFlagsRestrictedScope. If you want to iterate through font families that can be used by all applications pass the constant kATSOptionFlagsUnRestrictedScope.

ioIterator

A pointer to a font family iterator you created with the function ATSFontFamilyIteratorCreate. On output, the font family iterator is reset to the beginning of the iteration.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Discussion

Once you have created a font family iterator, you can reuse it by calling the function ATSFontFamilyIteratorReset. This function sets the parameters to the new values you specify, and repositions the iterator so it is ready to get the first font family reference when you call the function ATSFontFamilyIteratorNext.

During an iteration, if you obtain the result code kATSIterationScopeModified from the function ATSFontFamilyIteratorNext, you can reset the iteration by calling the function ATSFontFamilyIteratorReset. This assures that you obtain the most up-to-date information from the iteration.

Availability
Declared In
ATSFont.h

ATSFontFindFromContainer

Obtains the font references contained in a font container.

OSStatus ATSFontFindFromContainer (
   ATSFontContainerRef iContainer,
   ATSOptionFlags iOptions,
   ItemCount iCount,
   ATSFontRef ioArray[],
   ItemCount *oCount
);

Parameters
iContainer

A reference to the font container whose fonts you want to obtain. You obtain a font container reference when you activate a font by calling the functions ATSFontActivateFromFileSpecification or ATSFontActivateFromMemory.

iOptions

An ATSOptionFlags value. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault.

iCount

The number of items in the ioArray array. If you are uncertain of how many items are in this array, see the Discussion.

ioArray

A pointer to memory you have allocated for an array of font references. On return, the array contains the font references in the font container specified by the iContainer parameter. If you are uncertain of how much memory to allocate for this array, see the Discussion.

oCount

A pointer to an ItemCount value. On output, the value specifies the actual number of ATSFontRef values in the font container.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Discussion

The function ATSFontFindFromContainer operates on font containers that reference font files. It does not work on font containers that reference font directories.

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

  1. Pass a reference to the font container to examine in the iContainer parameter, a valid pointer to an ItemCount value in the oCount parameter, NULL for the ioArray parameter, and 0 for the iCount parameter. ATSFindFontFromContainer returns the size of the array in the oCount parameter.

  2. Allocate enough space for an array of the returned size, then call the ATSFindFontFromContainer function again, passing a valid pointer in the ioArray parameter and the number of items in the array in the iCount parameter. On return, the pointer refers to an array of the font references contained in the font container.

Availability
Declared In
ATSFont.h

ATSFontFindFromName

Returns the font reference associated with a font name.

ATSFontRef ATSFontFindFromName (
   CFStringRef iName,
   ATSOptionFlags iOptions
);

Parameters
iName

A reference to a font name formatted as a CFString.

iOptions

An ATSOptionFlags value. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault.

Return Value

A reference to the font specified by the iName parameter. See the description of the ATSFontRef data type.

Availability
Declared In
ATSFont.h

ATSFontFindFromPostScriptName

Returns the font reference associated with a PostScript font name.

ATSFontRef ATSFontFindFromPostScriptName (
   CFStringRef iName,
   ATSOptionFlags iOptions
);

Parameters
iName

A reference to the PostScript name for a font, formatted as a CFString.

iOptions

An ATSOptionFlags value. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault.

Return Value

A reference to the font specified by the iName parameter. See the description of the ATSFontRef data type.

Availability
Declared In
ATSFont.h

ATSFontGetAutoActivationSettingForApplication

Gets the activation setting for the specified application.

ATSFontAutoActivationSetting ATSFontGetAutoActivationSettingForApplication (
   CFURLRef iApplicationFileURL
);

Parameters
iApplicationFileURL

A valid file URL for an application. Pass NULL to specify the current process.

Return Value

The activation setting for the specified application.

Availability
Declared In
ATSFont.h

ATSFontGetContainer

Gets the font container reference for a font.

OSStatus ATSFontGetContainer (
   ATSFontRef iFont,
   ATSOptionFlags iOptions,
   ATSFontContainerRef *oContainer
);

Parameters
iFont

The font reference.

iOptions

An options flag.

oContainer

On output, a reference to the font container that was used to activate the font reference. On error ATS sets this to kATSFontContainerRefUnspecified.

Return Value

If successful, noErr; if the container is invalid, kATSInvalidFontContainerAccess.

Availability
Declared In
ATSFont.h

ATSFontGetContainerFromFileReference

Gets the font container reference associated with an activated file reference.

OSStatus ATSFontGetContainerFromFileReference (
   const FSRef *iFile,
   ATSFontContext iContext,
   ATSOptionFlags iOptions,
   ATSFontContainerRef *oContainer
);

Parameters
iFile

A pointer to the valid file reference that specifies the activated font file for which to get the container.

iContext

The context that the font file is accessible to. If you want the activated font to be accessible only from your application pass kATSFontContextDefault or kATSFontContextLocal. If you want the activated font to be accessible to all applications use the constant kATSFontContextGlobal. See “Context Options” for more information.

iOptions

An options flag.

oContainer

On output, a reference to the font container representing the file reference activated in the specified context. On error or for a file that is not activated, ATS sets this to kATSFontContainerRefUnspecified.

Return Value

noErr or paramErr if one or more parameters are invalid.

Availability
Declared In
ATSFont.h

ATSFontGetFileReference

Obtains the file reference for a font.

OSStatus ATSFontGetFileReference (
   ATSFontRef iFont,
   FSRef *oFile
);

Parameters
iFont

A reference to the font whose file reference you want to obtain.

oFile

On output, points to the file reference that specifies the name and location of a file or directory that contains the font data specified by the iFont parameter.

Return Value

If successful, noErr.

Availability
Declared In
ATSFont.h

ATSFontGetFontFamilyResource

Obtains the font family resource for a font.

OSStatus ATSFontGetFontFamilyResource (
   ATSFontRef iFont,
   ByteCount iBufferSize,
   void *ioBuffer,
   ByteCount *oSize
);

Parameters
iFont

A font reference.

iBufferSize

The size of the buffer pointed to by the ioBuffer parameter. See the Discussion if you are unsure of the size of this buffer.

ioBuffer

On input, a pointer to memory you allocated for the font family resource. On output, points to the FOND resource for the font. Note that the FOND resource data is in big endian format, regardless of the native endian format of the Macintosh computer on which you make the function call. If you are uncertain of how much memory to allocate for this array, see the Discussion.

oSize

On output, the actual size of the buffer.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Discussion

The function ATSFontGetFontFamilyResource provides a compatibility path for font families that use resources. Beginning with Mac OS X version 10.2, ATS for Fonts synthesizes FOND resources for OpenType fonts.

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

  1. Pass a reference to the font to examine in the iFont parameter, a valid pointer in the oSize parameter, NULL for the ioBuffer parameter, and 0 for the iBufferSize parameter. ATSFontGetFontFamilyResource returns the size of the buffer in the oSize parameter.

  2. Allocate enough space for an array of the returned size, then call the ATSFontGetFontFamilyResource function again, passing a valid pointer in the ioBuffer parameter, the size of the buffer in the iBufferSize parameter, and the appropriate values in the other parameters. On return, the pointer refers to an array of the font references contained in the font container.

Availability
Declared In
ATSFont.h

ATSFontGetGeneration

Returns the generation count for a font.

ATSGeneration ATSFontGetGeneration (
   ATSFontRef iFont
);

Parameters
iFont

A font reference.

Return Value

A generation count. See the description of the ATSGeneration data type.

Discussion

ATS for Fonts increments the generation count for any changes to a font, including when the system synthesizes data for the font.

Availability
Declared In
ATSFont.h

ATSFontGetGlobalAutoActivationSetting

Gets the user's global auto-activation setting.

ATSFontAutoActivationSetting ATSFontGetGlobalAutoActivationSetting (
   void
);

Return Value

The user's global auto-activation setting.

Availability
Declared In
ATSFont.h

ATSFontGetHorizontalMetrics

Obtains the horizontal metrics for a font.

OSStatus ATSFontGetHorizontalMetrics (
   ATSFontRef iFont,
   ATSOptionFlags iOptions,
   ATSFontMetrics *oMetrics
);

Parameters
iFont

A reference to the font whose horizontal metrics you want to obtain.

iOptions

An options flag. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault.

oMetrics

On input, a valid pointer to an ATSFontMetrics data structure. On output, the structure contains the font’s horizontal metrics. If one or more measurements are not available for a font, then the appropriate fields in the ATSFontMetrics data structure are set to 0.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Availability
Declared In
ATSFont.h

ATSFontGetName

Obtains the name of a font associated with a font reference.

OSStatus ATSFontGetName (
   ATSFontRef iFont,
   ATSOptionFlags iOptions,
   CFStringRef *oName
);

Parameters
iFont

A font reference.

iOptions

An ATSOptionFlags value. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault.

oName

On output, a reference to the font name associated with the specified font reference, formatted as a CFString. You are responsible for releasing the CFStringRef.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Availability
Declared In
ATSFont.h

ATSFontGetPostScriptName

Obtains the PostScript name from a font reference.

OSStatus ATSFontGetPostScriptName (
   ATSFontRef iFont,
   ATSOptionFlags iOptions,
   CFStringRef *oName
);

Parameters
iFont

A font reference.

iOptions

An ATSOptionFlags value. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault.

oName

On output, a reference to the PostScript name for the font, formatted as a CFString. You are responsible for releasing the CFStringRef.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Discussion

The system automatically detects whether or not the font is composed PostScript. If the font is, ATS for Fonts appends the CMAP name.

Availability
Declared In
ATSFont.h

ATSFontGetTable

Obtains a font table.

OSStatus ATSFontGetTable (
   ATSFontRef iFont,
   FourCharCode iTag,
   ByteOffset iOffset,
   ByteCount iBufferSize,
   void *ioBuffer,
   ByteCount *oSize
);

Parameters
iFont

A reference to the font whose table you want to obtain.

iTag

A four-character code that specifies the font table you want to obtain.

iOffset

The offset to a font table. If you want to obtain all the font tables associated with a font, pass 0.

iBufferSize

The size of the buffer pointed to by the ioBuffer parameter. The size should be the actual size of the buffer (oSize) minus the offset to the font table (iOffset) you want to obtain. See the Discussion if you are unsure of value to supply.

ioBuffer

On input, a valid pointer. On output, a pointer to the font table. Note that the data returned in the font table is in big endian format, regardless of the native endian format of the Macintosh computer on which you make the function call. See the Discussion for information on allocating this buffer.

oSize

On output, the actual size of the buffer returned in the ioBuffer parameter.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Discussion

Synthetic font tables (entries with offset of 0) can only be accessed by calling the function ATSFontGetTable.

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

  1. Pass a reference to the font whose table you want obtain in the iFont parameter, a four-character code that specifies the font table you want to obtain in the iTag parameter, the appropriate offset to the font table in the iOffset parameter, 0 for the iBufferSize parameter, NULL for the ioBuffer parameter, and a valid pointer to a ByteCount value in the oSize parameter. ATSUFontGetTable returns the size of the table in the oSize parameter.

  2. Allocate enough space for a buffer of the returned size, then call the ATSFontGetTable function again, passing a valid pointer in the ioBuffer parameter, the size of the buffer in the iBufferSize parameter, and the appropriate values in the other parameters. On return, the pointer refers to the table for the font specified by the iFont parameter and the table specified by the iTag parameter.

You should use the function ATSFontGetTable when you need to obtain an entire font table. For performance reasons, avoid using the function to check a single value in the table.

Availability
Declared In
ATSFont.h

ATSFontGetTableDirectory

Obtains the table directory for a font.

OSStatus ATSFontGetTableDirectory (
   ATSFontRef iFont,
   ByteCount iBufferSize,
   void *ioBuffer,
   ByteCount *oSize
);

Parameters
iFont

The font reference whose table directory you want to obtain.

iBufferSize

The size of the buffer pointed to by the ioBuffer parameter. See the Discussion if you are unsure of the size of this buffer.

ioBuffer

On input, a valid pointer. On output, points to the table directory for the font specified by the iFont parameter. Note that the data returned in the table directory is in big endian format, regardless of the native endian format of the Macintosh computer on which you make the function call. See the Discussion for information on allocating this buffer.

oSize

On output, the actual size of the buffer returned in the ioBuffer parameter.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Discussion

If necessary, ATS for Fonts synthesizes font tables or data, replacing existing tables or data. ATS for Fonts synthesizes data on an as needed basis; if data is synthesized, the generation count of the font increases.

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

  1. Pass a reference to the font whose table directory you want obtain in the iFont parameter, 0 for the iBufferSize parameter, NULL for the ioBuffer parameter, and a valid pointer to a ByteCount value in the oSize parameter. ATSFontGetTableDirectory returns the size of the table directory in the oSize parameter.

  2. Allocate enough space for a buffer of the returned size, then call the ATSFontGetTableDirectory function again, passing a valid pointer in the ioBuffer parameter, and the size of the buffer in the iBufferSize parameter. On return, the pointer refers to the table directory for the font specified by the iFont parameter.

If you want to obtain a font table, call the function ATSFontGetTable.

Availability
Declared In
ATSFont.h

ATSFontGetVerticalMetrics

Obtains the vertical metrics for a font.

OSStatus ATSFontGetVerticalMetrics (
   ATSFontRef iFont,
   ATSOptionFlags iOptions,
   ATSFontMetrics *oMetrics
);

Parameters
iFont

A reference to the font whose vertical metrics you want to obtain.

iOptions

An options flag. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault.

oMetrics

On input, a valid pointer to an ATSFontMetrics data structure. On output, the structure contains the font’s vertical metrics. If one or more measurements are not available for a font, then the appropriate fields in the ATSFontMetrics data structure are set to 0.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Availability
Declared In
ATSFont.h

ATSFontIsEnabled

Returns true if the font is enabled.

Boolean ATSFontIsEnabled (
   ATSFontRef iFont
);

Parameters
iFont

The font reference.

Return Value

true if the font is enabled.

Availability
Declared In
ATSFont.h

ATSFontIteratorCreate

Creates a font iterator.

OSStatus ATSFontIteratorCreate (
   ATSFontContext iContext,
   const ATSFontFilter *iFilter,
   void *iRefCon,
   ATSOptionFlags iOptions,
   ATSFontIterator *ioIterator
);

Parameters
iContext

A value that specifies the context of the iterator. If you want to apply the font iterator only to the fonts accessible from your application use the kATSFontContextLocal constant. If you want the to apply the font iterator to all fonts registered with the system use the constant kATSFontContextGlobal. See “Context Options” for more information on the constants you can supply. See the Discussion for information on the interaction between the iContext and iOptions parameters.

iFilter

A pointer to a filter specification. Pass NULL if you do not want to apply a filter to this iteration. Otherwise, you can use this parameter to restrict the iteration to the fonts that match a generation count or criteria you specify in a custom filter function. Pass the filter selector constant kATSFontFilterSelectorGeneration to select a generation filter or the constant kATSFontFilterSelectorFontApplierFunction to select a custom filter. See “Font Filter Selectors” for more information on these constants.

iRefCon

An arbitrary 32-bit value specified by your application. If you are using a custom filter function, you can use this parameter to pass data to the custom filter function. Otherwise, pass NULL.

iOptions

A value that specifies the scope of the iterator. If you want to iterate through fonts that can be used only by your application, pass the constant kATSOptionFlagsRestrictedScope. If you want to iterate through fonts that can be used by all applications pass the constant kATSOptionFlagsUnRestrictedScope. See “Scoping Options” for more information on the constants you can supply. See the Discussion for information on the interaction between the iContext and iOptions parameters.

ioIterator

A pointer to a font iterator. On input, pass a pointer to an uninitialized iterator. On output, the iterator’s contents may have been changed and may include references to data structures allocated by the system to maintain the iterator’s state. When you no longer need the font iterator, you should call the function ATSFontIteratorRelease to release the auxiliary data and memory allocated by the system.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Discussion

Your application can use a font iterator to access font data. A font iterator is an opaque data structure used by ATS for Fonts to keep track of an iteration over currently active fonts. When the font iterator is initialized, it does not yet reference a font.

The context and scope you specify for the font iterator interact as shown in Table 2.

Table 2  The interaction of context and scope in a font enumeration

Local context

Global context

Restricted scope

Fonts activated locally to your application

Only globally activated fonts

Unrestricted scope

Defaults fonts, which include globally activated fonts and fonts activated locally to your application

All fonts, which include globally activated fonts and all other fonts activated locally for an application.

Availability
Declared In
ATSFont.h

ATSFontIteratorNext

Obtains the next font reference.

OSStatus ATSFontIteratorNext (
   ATSFontIterator iIterator,
   ATSFontRef *oFont
);

Parameters
iIterator

A pointer to a font iterator you created with the function ATSFontIteratorCreate. If you try to use the font iterator after disposing of its contents through this function, ATS for Fonts returns an error code to your application.

oFont

A pointer to a font reference. On output, points to the font reference obtained by the iterator. You are responsible for allocating memory for the font reference.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Discussion

If any changes are made to the font database while you are using the font iterator, the iterator is invalidated and the function ATSFontFamilyIteratorNext returns the error kATSIterationScopeModified. To remedy this error, your application must either restart or cancel the enumeration by calling the ATSFontFamilyIteratorReset or the ATSFontIteratorRelease functions.

Availability
Declared In
ATSFont.h

ATSFontIteratorRelease

Releases a font iterator.

OSStatus ATSFontIteratorRelease (
   ATSFontIterator *ioIterator
);

Parameters
ioIterator

A pointer to a font iterator you created with the function ATSFontIteratorCreate. If you try to use the font iterator after disposing of its contents through this function, ATS for Fonts returns an error code to your application.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Discussion

If you plan to use the font iterator again, you should consider calling the function ATSFontIteratorReset rather than releasing the font iterator and then creating it again.

Availability
Declared In
ATSFont.h

ATSFontIteratorReset

Resets a font iterator to the beginning of the iteration.

OSStatus ATSFontIteratorReset (
   ATSFontContext iContext,
   const ATSFontFilter *iFilter,
   void *iRefCon,
   ATSOptionFlags iOptions,
   ATSFontIterator *ioIterator
);

Parameters
iContext

A value that specifies the context of the iterator. If you want to apply the font iterator only to the fonts accessible from your application use the kATSFontContextLocal constant. If you want the to apply the font iterator to all fonts registered with the system use the constant kATSFontContextGlobal. See “Context Options” for more information.

iFilter

A pointer to a filter specification. Pass NULL if you do not want to apply a filter to this iteration. Otherwise, you can use this parameter to restrict the iteration to the fonts that match a generation count or criteria you specify in a custom filter function. Pass the filter selector constant kATSFontFilterSelectorGeneration to select a generation filter or the constant kATSFontFilterSelectorFontApplierFunction to select a custom filter. See “Font Filter Selectors” for more information on these constants.

iRefCon

An arbitrary 32-bit value specified by your application. If you are using a custom filter function, you can use this parameter to pass data to the custom filter function. Otherwise, pass NULL.

iOptions

A value that specifies the scope of the iterator. If you want to iterate through fonts that can be used only by your application, pass the constant kATSOptionFlagsRestrictedScope. If you want to iterate through fonts that can be used by all applications pass the constant kATSOptionFlagsUnRestrictedScope.

ioIterator

A pointer to a font iterator you created with the function ATSFontIteratorCreate. If you try to use the font iterator after disposing of its contents through this function, ATS for Fonts returns an error code to your application.

Return Value

A result code. See “Apple Type Services for Fonts Result Codes.”

Discussion

Once you have created a font iterator, you can reuse it by calling the function ATSFontIteratorReset. This function sets the parameters to the new values you specify, and repositions the iterator so it is ready to get the first font reference when you call the function ATSFontIteratorNext.

During an iteration, if you obtain the result code kATSIterationScopeModified from the function ATSFontIteratorNext, you can reset the iteration by calling the function ATSFontIteratorReset. This assures that you obtain the most up-to-date information from the iteration.

Availability
Declared In
ATSFont.h

ATSFontNotificationSubscribe

Signs up your application to receive notification of changes to fonts and font directories.

OSStatus ATSFontNotificationSubscribe (
   ATSNotificationCallback callback,
   ATSFontNotifyOption options,
   void *iRefcon,
   ATSFontNotificationRef *oNotificationRef
);

Parameters
callback

The callback function you want ATS to invoke whenever the notification action specified in the options parameter occurs. See ATSNotificationCallback for more information on the callback you can supply.

options

A notification o