Retired Documents Library

Developer

ApplicationServices Framework Reference Apple Type Services for Fonts Reference

Options
Deployment Target:

On This Page
Language:

Apple Type Services for Fonts Reference (Retired Document)

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.

Functions

  • Activates one or more fonts from a file specification.

    Deprecation Statement

    Instead use ATSFontActivateFromFileReference.

    Declaration

    Objective-C

    OSStatus ATSFontActivateFromFileSpecification ( const FSSpec *iFile, ATSFontContext iContext, ATSFontFormat iFormat, void *iReserved, ATSOptionFlags iOptions, ATSFontContainerRef *oContainer );

    Parameters

    iFile

    A pointer to the file specification 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.

    iReserved

    An arbitrary 32-bit value. 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 specification. You need this reference when you deactivate the font by calling the function ATSFontDeactivate.

    Return Value

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

    Discussion

    You can use the function ATSFontActivateFromFileSpecification to activate one font or more fonts. Activating a font makes that font available for use either locally (available only to your application) or globally (available to all applications on the system). A font’s availability—local or global—is referred to as its context.

    Availability

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • Activates one or more fonts from a file reference.

    Declaration

    Objective-C

    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

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Deactivates one or more fonts.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Obtains the generation of the font database.

    Declaration

    Objective-C

    ATSGeneration ATSGetGeneration ( void );

    Return Value

    A value that specifies the generation count of the font database. See the description of the ATSGeneration data type.

    Discussion

    Any operation that adds, deletes, or modifies one or more font families or fonts triggers an update of the font database generation count. If you want to obtain the generation of a font family, call the function ATSFontFamilyGetGeneration. If you want to obtain the generation of a font, call the function ATSFontGetGeneration.

    Availability

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Sets the user's global auto-activation setting.

    Declaration

    Objective-C

    OSStatus ATSFontSetGlobalAutoActivationSetting ( ATSFontAutoActivationSetting iSetting );

    Parameters

    iSetting

    A font auto-activation setting. See Automatic Activation Settings.

    Return Value

    If successful, noErr; if invalid input, paramErr.

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.8.

  • Gets the user's global auto-activation setting.

    Declaration

    Objective-C

    ATSFontAutoActivationSetting ATSFontGetGlobalAutoActivationSetting ( void );

    Return Value

    The user's global auto-activation setting.

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.8.

  • Sets the auto-activation setting for the specified application bundle.

    Declaration

    Objective-C

    OSStatus ATSFontSetAutoActivationSettingForApplication ( ATSFontAutoActivationSetting iSetting, CFURLRef iApplicationFileURL );

    Parameters

    iSetting

    A font auto-activation setting. See Automatic Activation Settings.

    iApplicationFileURL

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

    Return Value

    Returns noErr on success, and paramErr for any invalid input. May return memFullErr if unable to allocate temporary structures.

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.8.

  • Gets the activation setting for the specified application.

    Declaration

    Objective-C

    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

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.8.

  • Applies your callback to a font family iteration.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Releases the memory associated with a font family iterator.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Obtains the next font family reference.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Returns the generation count of a font family.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Returns the text encoding used by a font family.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Applies your callback to a font iteration.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Creates a font iterator.

    Declaration

    Objective-C

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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Releases a font iterator.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Obtains the next font reference.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Returns the font reference associated with a font name.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Returns the font reference associated with a PostScript font name.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Obtains the font references contained in a font container.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Returns the generation count for a font.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    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

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.8.

  • Gets the font container reference for a font.

    Declaration

    Objective-C

    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

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Obtains the PostScript name from a font reference.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Obtains the table directory for a font.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Obtains a font table.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Obtains the horizontal metrics for a font.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Obtains the vertical metrics for a font.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Obtains the file specification for a font.

    Deprecation Statement

    Instead use ATSFontGetFileReference.

    Declaration

    Objective-C

    OSStatus ATSFontGetFileSpecification ( ATSFontRef iFont, ATSFSSpec *oFile );

    Parameters

    iFont

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

    oFile

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

    Return Value

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

    Discussion

    The function ATSFontGetFileSpecification obtains the file specification for a font, not the font container. You must call the functions ATSFontActivateFromFileSpecification or ATSFontActivateFromMemory to obtain a font container reference.

    Availability

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.5.

    Not available to 64-bit applications.

  • Obtains the file reference for a font.

    Declaration

    Objective-C

    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

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Obtains the font family resource for a font.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.8.

  • Sets a font state to enabled or disabled.

    Declaration

    Objective-C

    OSStatus ATSFontSetEnabled ( ATSFontRef iFont, ATSOptionFlags iOptions, Boolean iEnabled );

    Parameters

    iFont

    The font reference.

    iOptions

    An options flag.

    iEnabled

    The state to set the font to. True for enabled, false for disabled.

    Return Value

    kATSInvalidFontAccess if the font reference is invalid in the current application context.

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.8.

  • Returns true if the font is enabled.

    Declaration

    Objective-C

    Boolean ATSFontIsEnabled ( ATSFontRef iFont );

    Parameters

    iFont

    The font reference.

    Return Value

    true if the font is enabled.

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.8.

  • Notifies Apple Type Services of an action taken by your application.

    Declaration

    Objective-C

    OSStatus ATSFontNotify ( ATSFontNotifyAction action, void *info );

    Parameters

    action

    A notification action that specifies the action taken by your application. If your application activates or deactivates fonts, you should pass kATSFontNotifyActionFontsChanged. If your application makes changes to any of the font directories (System, local, user, or the Classic System folder), you should pass the constant kATSFontNotifyActionDirectoriesChanged. See Notification Actions for more information on the constants you can supply.

    info

    A pointer to the data you want ATS for Fonts to pass to the clients who subscribe to notifications. You can pass NULL if there is no data associated with this action.

    Return Value

    A result code. See Apple Type Services for Fonts Result Codes. Returns paramErr if you pass an invalid notification action in the action parameter.

    Discussion

    A notification is a mechanism by which your application can inform ATS for Fonts that you have changed a font or font directory. Other applications can sign up to receive notifications of these changes by calling the function ATSFontNotificationSubscribe. When you call the function ATSFontNotify, the system passes the notification along with any data you provide to every client who is signed up to receive notifications.

    You can call the function ATSFontNotify after your application makes a batch of changes. For example, if your application calls the functions ATSFontActivateFromFileSpecification or ATSFontDeactivate multiple times to activate and deactivate fonts, you can set the iOptions parameter in these functions to kATSOptionFlagsDoNotNotify set. When you are done activating and deactivating 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.

    Availability

    Available in Mac OS X 10.2 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    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 option that specifies when you want ATS to respond to notification actions. If you want to receive notifications when your application is in the foreground, pass the constant kATSFontNotifyOptionDefault. If your application is a server process or a tool that performs font management functions and requires immediate notification when fonts change, pass the constant kATSFontNotifyOptionReceiveWhileSuspended. See Notification Options for more information.

    iRefCon

    An arbitrary 32-bit value specified by your application and which you want passed to your callback function. You can pass NULL if your callback does not need any data.

    oNotificationRef

    On output, a notification reference. You need this reference when you call the function ATSFontNotificationUnsubscribe. You can pass NULL if you do not want to obtain the reference.

    Return Value

    A result code. See Apple Type Services for Fonts Result Codes. This function returns paramErr the callback parameter is NULL and memFullErr if the function cannot allocate enough memory for internal data structures.

    Discussion

    If your application uses Carbon events or the Application Kit, you can call the function ATSFontNotificationSubscribe to receive notifications of changes to fonts and font directories. However, if your application is of a type that does not use a CFRunLoop, it can’t receive notifications unless you explicitly set up a run loop. For more information on run loops, see Overview of Programming Topic: Run Loops on the Cocoa Developer Documentation website.

    If you want to stop receiving notifications, call the function ATSFontNotificationUnsubscribe.

    Availability

    Available in Mac OS X 10.2 and later.

    Deprecated in OS X v10.8.

  • Unsubscribes your application from receiving notifications of changes to fonts and font directories.

    Declaration

    Objective-C

    OSStatus ATSFontNotificationUnsubscribe ( ATSFontNotificationRef notificationRef );

    Parameters

    oNotificationRef

    On input, the notification reference you obtained when you called the function ATSFontNotificationSubscribe. On output, NULL.

    Return Value

    A result code. See Apple Type Services for Fonts Result Codes. Returns paramErr if you pass a NULL or invalid notification reference in the oNotificationRef parameter.

    Discussion

    The function ATSFontNotificationUnsubscribe unsubscribes your application from receiving the notification associated with the notification reference you pass to the function. You must call ATSFontNotificationUnsubscribe for each notification for which you want to unsubscribe.

    Availability

    Available in Mac OS X 10.2 and later.

    Deprecated in OS X v10.8.

  • Sets up your application to handle font queries.

    Declaration

    Objective-C

    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

    Available in Mac OS X 10.2 and later.

    Deprecated in OS X v10.8.

  • Creates a new universal procedure pointer (UPP) to a filter callback function that uses your criteria for filtering fonts.

    Declaration

    Objective-C

    FMFontCallbackFilterUPP NewFMFontCallbackFilterUPP ( FMFontCallbackFilterProcPtr userRoutine );

    Return Value

    See the description of the FMFontCallbackFilterUPP data type.

    Discussion

    See the callback FMFontCallbackFilterProcPtr for more information.

    Availability

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.7.

  • Disposes of a universal procedure pointer to a customized filter function used for fonts.

    Declaration

    Objective-C

    void DisposeFMFontCallbackFilterUPP ( FMFontCallbackFilterUPP userUPP );

    Discussion

    See the callback FMFontCallbackFilterProcPtr for more information.

    Availability

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.7.

  • Calls a customized filter function used for fonts.

    Declaration

    Objective-C

    OSStatus InvokeFMFontCallbackFilterUPP ( FMFont iFont, void *iRefCon, FMFontCallbackFilterUPP userUPP );

    Return Value

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

    Discussion

    This function is not recommended nor needed, as the system invokes your filter for you.

    Availability

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.7.

  • Creates a new universal procedure pointer (UPP) to a filter callback function that uses your criteria for filtering font families.

    Declaration

    Objective-C

    FMFontFamilyCallbackFilterUPP NewFMFontFamilyCallbackFilterUPP ( FMFontFamilyCallbackFilterProcPtr userRoutine );

    Return Value

    See the description of the FMFontFamilyCallbackFilterUPP data type.

    Discussion

    See the callback FMFontFamilyCallbackFilterProcPtr for more information.

    Availability

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.7.

  • Disposes of a universal procedure pointer to a customized filter function used for font families.

    Declaration

    Objective-C

    void DisposeFMFontFamilyCallbackFilterUPP ( FMFontFamilyCallbackFilterUPP userUPP );

    Discussion

    See the callback FMFontFamilyCallbackFilterProcPtr for more information.

    Availability

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.7.

  • Calls a customized filter function used for font families.

    Declaration

    Objective-C

    OSStatus InvokeFMFontFamilyCallbackFilterUPP ( FMFontFamily iFontFamily, void *iRefCon, FMFontFamilyCallbackFilterUPP userUPP );

    Return Value

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

    Discussion

    This function is not recommended nor needed, as the system invokes your filter for you.

    Availability

    Available in Mac OS X 10.0 and later.

    Deprecated in OS X v10.7.

Callbacks

The callbacks in this section are used by ATS for Fonts.

  • Defines a pointer to a customized function to be applied to a font iteration.

    Declaration

    Swift

    typealias ATSFontApplierFunction = CFunctionPointer<((ATSFontRef, UnsafeMutablePointer<Void>) -> OSStatus)>

    Objective-C

    typedef OSStatus (*ATSFontApplierFunction) ( ATSFontRef iFont, void * iRefCon );

    Parameters

    iFont

    A font reference. This is the font on which your callback operates.

    iRefCon

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

    Return Value

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

    Discussion

    You provide a pointer to an ATSFontApplierFunction callback as a parameter to the function ATSFontApplyFunction. You can also provide a pointer to an ATSFontApplierFunction callback in the ATSFontFilter data structure. This structure can be passed as a parameter to the functions ATSFontIteratorCreate and ATSFontIteratorReset.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a customized function to be applied to a font family iteration.

    Declaration

    Swift

    typealias ATSFontFamilyApplierFunction = CFunctionPointer<((ATSFontFamilyRef, UnsafeMutablePointer<Void>) -> OSStatus)>

    Objective-C

    typedef OSStatus (*ATSFontFamilyApplierFunction) ( ATSFontFamilyRef iFamily, void * iRefCon );

    Parameters

    iFamily

    A font family reference. This is the font family on which your callback operates.

    iRefCon

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

    Return Value

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

    Discussion

    You provide a pointer to an ATSFontFamilyApplierFunction callback as a parameter to the function ATSFontFamilyApplyFunction. You can also provide a pointer to an ATSFontApplierFunction callback in the ATSFontFilter data structure. This structure can be passed as a parameter to the functions ATSFontFamilyIteratorCreate and ATSFontFamilyIteratorReset.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a customized function that handles font queries.

    Declaration

    Swift

    typealias ATSFontQueryCallback = CFunctionPointer<((ATSFontQueryMessageID, CFPropertyList!, UnsafeMutablePointer<Void>) -> Unmanaged<CFPropertyList>!)>

    Objective-C

    typedef CFPropertyListRef (*ATSFontQueryCallback) ( ATSFontQueryMessageID msgid, CFPropertyListRef data void * iRefCon );

    Parameters

    msgid

    An ATSFontQueryMessageID value that identifies the message type your application receives from ATS. See Font Query Message ID for the constants you can supply.

    data

    A CFPropertyListRef that represents the font query. The content of the CFPropertyList is specific to the message type. The property list should contain data that specifies the font for which the query is sent.

    iRefCon

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

    Return Value

    A CFPropertyListRef that represents your application’s response to the query. The content of the CFPropertyList is specific to the message type, and it may be NULL.

    Discussion

    ATS for Fonts calls your customized function each time ATS receives a font query from another application. You provide a pointer to an ATSFontQueryCallback as a parameter to the function ATSCreateFontQueryRunLoopSource.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Defines a pointer to a customized function that handles notifications.

    Declaration

    Swift

    typealias ATSNotificationCallback = CFunctionPointer<((ATSFontNotificationInfo!, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    typedef void (*ATSNotificationCallback) ( ATSFontNotificationInfoRef info, void * iRefCon );

    Parameters

    info

    Reserved for future use. Currently, your callback is passed NULL.

    iRefCon

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

    Discussion

    ATS for Fonts calls your customized function each time ATS receives a font notification from another application. You provide a pointer to an ATSNotificationCallback callback function as a parameter to the function ATSFontNotificationSubscribe.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

The callbacks in this section are used by the Font Manager.

  • Defines a pointer to a customized filter function to be used with a font iterator.

    Declaration

    Swift

    typealias FMFontCallbackFilterProcPtr = CFunctionPointer<((FMFont, UnsafeMutablePointer<Void>) -> OSStatus)>

    Objective-C

    typedef OSStatus (*FMFontCallbackFilterProcPtr) ( FMFont iFont, void * iRefCon );

    Parameters

    iFont

    A font reference. This is the font on which your callback operates.

    iRefCon

    A pointer to arbitrary data that defines your custom filter.

    Return Value

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

    Discussion

    The Font Manager calls your customized function each time it obtains a font in a font iteration. You can use a custom filter function in any Font Manager function that has a parameter of type FMFilter. You provide a universal procedure pointer to your filter callback function in the FMFilter data structure. First, you must use the NewFMFontCallbackFilterUPP function to create a universal procedure pointer (UPP) of type FMFontCallbackFilterUPP. You can do so with code similar to the following:

    FMFontCallbackFilterUPP MyFMFontFilterUPPMyFMFontFilterUPP = NewFMFontCallbackFilterUPP (&MyFMFontCallbackFilterCallback)

    Your application must specify the result code that should be returned by the Font Manager. Any value other than noErr will cause the iterator to ignore a font.

    When you are finished with your filter callback function, you should use the DisposeFMFontCallbackFilterUPP function to dispose of the UPP associated with it. However, if you plan to use the same filter callback function in subsequent calls, you can reuse the same UPP, rather than dispose of it and later create a new UPP.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a customized filter function to be used with a font family iterator.

    Declaration

    Swift

    typealias FMFontFamilyCallbackFilterProcPtr = CFunctionPointer<((FMFontFamily, UnsafeMutablePointer<Void>) -> OSStatus)>

    Objective-C

    typedef OSStatus (*FMFontFamilyCallbackFilterProcPtr) ( FMFontFamily iFontFamily, void * iRefCon );

    Parameters

    iFontFamily

    A font family reference. This is the font family on which your callback operates.

    iRefCon

    A pointer to arbitrary data that defines your custom filter.

    Return Value

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

    Discussion

    The Font Manager calls your customized function each time it obtains a font family in a font family iteration. You can use a custom filter function in any Font Manager function that has a parameter of type FMFilter. You provide a universal procedure pointer to your filter callback function in the FMFilter data structure. First, you must use the function NewFMFontFamilyCallbackFilterUPP to create a universal procedure pointer (UPP) of type FMFontFamilyCallbackFilterUPP. You can do so with code similar to the following:

    FMFontFamilyCallbackFilterUPP MyFMFontFamilyFilterUPPMyFMFontFamilyFilterUPP = NewFMFontFamilyCallbackFilterUPP (&MyFMFontFamilyCallbackFilterCallback)

    Your application must specify the result code that should be returned by the Font Manager. Any value other than noErr will cause the iterator to ignore a font family.

    When you are finished with your filter callback function, you should use the DisposeFMFontFamilyCallbackFilterUPP function to dispose of the UPP associated with it. However, if you plan to use the same filter callback function in subsequent calls, you can reuse the same UPP, rather than dispose of it and later create a new UPP.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

Data Types

ATS Data Types

The data types in this section are used by ATS for Fonts.

  • An opaque data type that represents a reference to a font file or folder.

    Declaration

    Swift

    typealias ATSFontContainerRef = UInt32

    Objective-C

    typedef UInt32 ATSFontContainerRef;

    Discussion

    A font container reference is an opaque type used as a parameter in the functions ATSFontActivateFromFileSpecification and ATSFontActivateFromMemory.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • An opaque data type that represents a font family iterator.

    Declaration

    Swift

    typealias ATSFontFamilyIterator = COpaquePointer

    Objective-C

    typedef struct ATSFontFamilyIterator_ * ATSFontFamilyIterator;

    Discussion

    You initialize a structure of type ATSFontFamilyIterator by calling the function ATSFontFamilyIteratorCreate. You should not attempt to modify the contents of a font family iterator.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • An opaque data type that represents a font family reference.

    Declaration

    Swift

    typealias ATSFontFamilyRef = UInt32

    Objective-C

    typedef UInt32 ATSFontFamilyRef;

    Discussion

    Unlike font family and font names which are part of a font’s data, data types, such as ATSFontFamily represent values that are arbitrarily assigned by ATS at system startup. These values can change when the system is restarted.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Contains font filter information.

    Declaration

    Swift

    struct ATSFontFilter { var version: UInt32 var filterSelector: ATSFontFilterSelector }

    Objective-C

    struct ATSFontFilter { UInt32 version ATSFontFilterSelector filterSelector union { ATSGeneration generationFilter; ATSFontFamilyRef fontFamilyFilter; ATSFontFamilyApplierFunction fontFamilyApplierFunctionFilter; ATSFontApplierFunction fontApplierFunctionFilter; } filter; }; typedef struct ATSFontFilter ATSFontFilter;

    Fields

    version

    The version of the filter.

    filterSelector

    A font filter selector. See Font Filter Selectorsfor a list of the filter selectors you can specify.

    filter

    A union whose contents are specified by the filterSelector field.

    generationFilter

    An ATSGeneration value that specifies the generation to which you want to restrict an operation.

    fontFamilyFilter

    A font family reference that specifies the font family to which you want to restrict an operation.

    fontFamilyApplierFunctionFilter

    A pointer the callback you want applied to a font family iteration. See ATSFontFamilyApplierFunction for more information on the callback you can supply.

    fontApplierFunctionFilter

    A pointer the callback you want applied to a font iteration. See ATSFontApplierFunction for more information on the callback you can supply.

    Discussion

    You can pass an ATSFontFilter structure to the functions ATSFontFamilyIteratorCreate, ATSFontFamilyIteratorReset, ATSFontIteratorCreate, and ATSFontIteratorReset.

    Availability

    Available in OS X v10.0 and later.

  • An opaque data type that represents a font iterator.

    Declaration

    Swift

    typealias ATSFontIterator = COpaquePointer

    Objective-C

    typedef struct ATSFontIterator_ * ATSFontIterator;

    Discussion

    You initialize a structure of type ATSFontIterator by calling the function ATSFontIteratorCreate. You should not attempt to modify the contents of a font iterator.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Contains metrics for a font.

    Declaration

    Swift

    struct ATSFontMetrics { var version: UInt32 var ascent: CGFloat var descent: CGFloat var leading: CGFloat var avgAdvanceWidth: CGFloat var maxAdvanceWidth: CGFloat var minLeftSideBearing: CGFloat var minRightSideBearing: CGFloat var stemWidth: CGFloat var stemHeight: CGFloat var capHeight: CGFloat var xHeight: CGFloat var italicAngle: CGFloat var underlinePosition: CGFloat var underlineThickness: CGFloat }

    Objective-C

    struct ATSFontMetrics { UInt32 version; Float32 ascent; Float32 descent; Float32 leading; Float32 avgAdvanceWidth; Float32 maxAdvanceWidth; Float32 minLeftSideBearing; Float32 minRightSideBearing; Float32 stemWidth; Float32 stemHeight; Float32 capHeight; Float32 xHeight; Float32 italicAngle; Float32 underlinePosition; Float32 underlineThickness; }; typedef struct ATSFontMetrics ATSFontMetrics;

    Fields

    version

    The version of the font metrics structure.

    ascent

    The maximum height from the baseline to the ascent line of the glyphs in the font. For vertical text, the maximum distance from the center line to the ascent line of the glyphs in the font.

    descent

    The maximum distance from the baseline to the descent line of the the glyphs in the font. For vertical text, the maximum distance from center line to the descent line of the glyphs in the font.

    leading

    The spacing from the descent line to the ascent line below it. This defines the spacing between lines of text

    avgAdvanceWidth

    The average advance width of the glyph in the font.

    maxAdvanceWidth

    The maximum advance width of the glyphs in the font.

    minLeftSideBearing

    The minimum left-side bearing value of the glyphs in the font. For vertical text, the minimum top-side bearing value of the glyphs in the font.

    minRightSideBearing

    The minimum right-side bearing value of the glyphs in the font. For vertical text, the minimum bottom side bearing of a glyphs in the font.

    stemWidth

    The width of the dominant vertical stems of the glyphs in the font.

    stemHeight

    The vertical width of the dominant horizontal stems of glyphs in the font.

    capHeight

    The height of a capital letter in the font from the baseline to the top of the letter.

    xHeight

    The height of lowercase characters in the font, specifically the letter x, excluding ascenders and descenders.

    italicAngle

    The angle (in degrees counterclockwise) at which glyphs in the font slant when italicized.

    underlinePosition

    The position at which an underline stroke should be placed for the font.

    underlineThickness

    The thickness, in pixels, of the underscore character used to underline the glyphs in the font.

    Discussion

    This structure is passed as a parameter to the functions ATSFontGetHorizontalMetrics and ATSFontGetVerticalMetrics.

    Availability

    Available in OS X v10.0 and later.

  • An opaque data type that represents a font notification information structure.

    Declaration

    Swift

    typealias ATSFontNotificationInfoRef = ATSFontNotificationInfo

    Objective-C

    typedef struct ATSFontNotificationInfoRef_ * ATSFontNotificationInfoRef;

    Discussion

    This data type is used in the ATSNotificationCallback callback function.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • An opaque data type that represents a font notification structure.

    Declaration

    Swift

    typealias ATSFontNotificationRef = ATSFontNotification

    Objective-C

    typedef struct ATSFontNotificationRef_ * ATSFontNotificationRef;

    Discussion

    The ATSFontNotificationRef data type is returned by the function ATSFontNotificationSubscribe and passed as a parameter to the function ATSFontNotificationUnsubscribe.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Contains font query information that is passed back to a font query callback.

    Declaration

    Swift

    struct ATSFontQuerySourceContext { var version: UInt32 var refCon: UnsafeMutablePointer<Void> var retain: CFAllocatorRetainCallBack var release: CFAllocatorReleaseCallBack }

    Objective-C

    struct ATSFontQuerySourceContext { UInt32 version; void * refCon; CFAllocatorRetainCallBack retain; CFAllocatorReleaseCallBack release; }; typedef struct ATSFontQuerySourceContext ATSFontQuerySourceContext;

    Fields

    version

    A 32-bit unsigned integer that indicates the version of this data structure. You can set this value to 0.

    refCon

    An arbitrary 32-bit value specified in your font query callback function.

    retain

    A callback you supply for increasing the retention count associated with the refCon value. The CFAllocatorRetainCallBack is defined in the header file CFBase.h. For more information on Core Foundation allocators, see the Core Foundation Base Services Reference.

    release

    A callback you supply for decreasing the retention count associated with the refCon value. The CFAllocatorReleaseCallBack is defined in the header file CFBase.h.

    Discussion

    You pass a ATSFontQuerySourceContext data structure to the function ATSCreateFontQueryRunLoopSource.

    Availability

    Available in OS X v10.2 and later.

  • An opaque data type that represents a font reference.

    Declaration

    Objective-C

    typedef UInt32 ATSFontRef;

    Discussion

    Unlike font names which are part of a font’s data, data types, such as ATSFontRef represent values that are arbitrarily assigned by ATS at system startup. These values can change when the system is restarted.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Represents a font size.

    Declaration

    Swift

    typealias ATSFontSize = CGFloat

    Objective-C

    typedef Float32 ATSFontSize;

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Represents a generation count.

    Declaration

    Swift

    typealias ATSGeneration = UInt32

    Objective-C

    typedef UInt32 ATSGeneration;

    Discussion

    The generation count data type is used by ATS for Fonts to keep track of the generation of the font database, each font family, and each font. You can obtain a generation count from the functions ATSGetGeneration, ATSFontFamilyGetGeneration, and ATSFontGetGeneration.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Represents options you can pass to various ATS functions.

    Declaration

    Swift

    typealias ATSOptionFlags = OptionBits

    Objective-C

    typedef OptionBits ATSOptionFlags;

    Discussion

    There are a variety of options associated with this data type. See Assorted Options, Scoping Options, and Iteration Precedence Options.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

FM Data types

The data types in this section are used by the Font Manager.

  • Contains a filter format, a selector and filter information.

    Declaration

    Swift

    struct FMFilter { var format: UInt32 var selector: FMFilterSelector }

    Objective-C

    struct FMFilter { UInt32 format FMFilterSelector selector union { FourCharCode fontTechnologyFilter; FSSpec fontContainerFilter; FMGeneration generationFilter; FMFontFamilyCallbackFilterUPP fontFamilyCallbackFilter; FMFontCallbackFilterUPP fontCallbackFilter; FMFontDirectoryFilter fontDirectoryFilter; } filter; }; typedef struct FMFilter FMFilter;

    Fields

    format

    A filter format. For possible values, see FM Filter Format.

    selector

    A filter selector. The selector indicates the data contained in the union. For possible values, see FM Filter Selectors.

    filter

    The filter you want to use to restrict an operation. The filter must correspond to the selector parameter. If you are using a custom filter, you should provide a universal procedure pointer that is either of type FMFontFamilyCallbackFilterUPP or FMFontCallBackFilterUPP.

    fontTechnologyFilter

    A FourCharCode value that specifies the font technology to which you want to restrict an operation. See FM Font Technologies for constants you can supply.

    fontContainerFilter

    A pointer to the file specification that specifies the name and location of a file or directory to which you want to restrict an operation.

    generationFilter

    The generation count to which you want to restrict an operation.

    fontFamilyCallbackFilter

    The font family callback that you want to use to restrict an operation.

    fontCallbackFilter

    The font callback that you want to use to restrict an operation.

    fontDirectoryFilter

    The font directory filter that you want to use to restrict an operation.

    Discussion

    You use the FMFilter data structure when you want to restrict the enumeration and activation functions to the criteria specified by a filter.

    Availability

    Available in OS X v10.0 and later.

  • An opaque data type that specifies a font registered with the font database.

    Declaration

    Swift

    typealias FMFont = UInt32

    Objective-C

    typedef UInt32 FMFont;

    Discussion

    You should not modify this value.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Defines a universal procedure pointer to a font filter callback.

    Declaration

    Objective-C

    typedef FMFontCallbackFilterProcPtr FMFontCallbackFilter;

    Discussion

    For more information, see the description of the FMFontCallbackFilterProcPtr callback function.

    Import Statement

  • Contains font directory information used to restrict a font iteration.

    Declaration

    Swift

    struct FMFontDirectoryFilter { var fontFolderDomain: Int16 var reserved: (UInt32, UInt32) }

    Objective-C

    struct FMFontDirectoryFilter { SInt16 fontFolderDomain; UInt32 reserved[2]; }; typedef struct FMFontDirectoryFilter FMFontDirectoryFilter;

    Fields

    fontFolderDomain

    A signed 16-bit integer that specifies the directory to which you want to restrict the font iteration.

    reserved

    Reserved for future use.

    Discussion

    You supply the FMFontDirectoryFilter data structure as part of the FMFilter data structure when you want to restrict a font iteration to a font directory.

    Availability

    Available in OS X v10.0 and later.

  • A reference to a collection of fonts with the same design characteristics.

    Declaration

    Swift

    typealias FMFontFamily = Int16

    Objective-C

    typedef SInt16 FMFontFamily;

    Discussion

    The font family reference replaces the QuickDraw font ID and can be used with all QuickDraw functions including GetFontName and TextFont. Unlike the QuickDraw font identifier, the font family reference cannot be passed to the Resource Manager to access information from a 'FOND' resource. A font family reference does not imply a script system, nor is the character encoding of a font family determined by an arithmetic mapping of the font family reference.

    The fonts associated with a font family consist of individual outline fonts that may be used with the font access functions of the Font Manager and ATSUI.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Defines a universal procedure pointer to a font family filter callback.

    Declaration

    Objective-C

    typedef FMFontFamilyCallbackFilterProcPtr FMFontFamilyCallbackFilter;

    Discussion

    For more information, see the description of the FMFontFamilyCallbackFilterProcPtr callback function.

    Import Statement

  • Contains a font family reference and a QuickDraw style.

    Declaration

    Swift

    struct FMFontFamilyInstance { var fontFamily: FMFontFamily var fontStyle: FMFontStyle }

    Objective-C

    struct FMFontFamilyInstance { FMFontFamily fontFamily; FMFontStyle fontStyle; }; typedef struct FMFontFamilyInstance FMFontFamilyInstance;

    Fields

    fontFamily

    A font family reference.

    fontStyle

    A QuickDraw font style.

    Discussion

    Each font object can map to one or more font family instance. This mapping is equivalent to the information stored in the font association table of the 'FOND' resource, except the font family instance does not contain a point size descriptor. Since a font object represents the entire array of point sizes for a given font, only the font family reference and style are required to specify fully any given font object.

    Availability

    Available in OS X v10.0 and later.

  • An opaque structure used to enumerate font family instances.

    Declaration

    Swift

    struct FMFontFamilyInstanceIterator { var reserved: (UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32) }

    Objective-C

    struct FMFontFamilyInstanceIterator { UInt32 reserved[16]; }; typedef struct FMFontFamilyInstanceIterator FMFontFamilyInstanceIterator;

    Fields

    reserved

    Reserved for Apple’s use.

    Discussion

    You initialize a structure of type FMFontFamilyInstanceIterator by calling the function FMCreateFontFamilyInstanceIterator. You should not attempt to modify the contents of a font family instance iterator.

    Availability

    Available in OS X v10.0 and later.

  • An opaque structure used to enumerate font families.

    Declaration

    Swift

    struct FMFontFamilyIterator { var reserved: (UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32) }

    Objective-C

    struct FMFontFamilyIterator { UInt32 reserved[16]; }; typedef struct FMFontFamilyIterator FMFontFamilyIterator;

    Fields

    reserved

    Reserved for Apple’s use.

    Discussion

    You initialize a structure of type FMFontFamilyIterator by calling the function FMCreateFontFamilyIterator. You should not attempt to modify the contents of a font family iterator.

    Availability

    Available in OS X v10.0 and later.

  • An opaque structure used to enumerate fonts.

    Declaration

    Swift

    struct FMFontIterator { var reserved: (UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32) }

    Objective-C

    struct FMFontIterator { UInt32 reserved[16]; }; typedef struct FMFontIterator FMFontIterator;

    Fields

    reserved

    Reserved for Apple’s use.

    Discussion

    You initialize a structure of type FMFontIterator by calling the function FMCreateFontIterator. You should not attempt to modify the contents of a font iterator.

    Availability

    Available in OS X v10.0 and later.

  • Represents a font size.

    Declaration

    Swift

    typealias FMFontSize = Int16

    Objective-C

    typedef SInt16 FMFontSize;

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Represents a font style.

    Declaration

    Swift

    typealias FMFontStyle = Int16

    Objective-C

    typedef SInt16 FMFontStyle;

    Discussion

    The low 8 bits of a Font Manager font style correspond to a QuickDraw style.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Keeps track of any operation that adds, deletes, or modifies one or more fonts or font family objects.

    Declaration

    Swift

    typealias FMGeneration = UInt32

    Objective-C

    typedef UInt32 FMGeneration;

    Discussion

    Any operation that adds, deletes, or modifies one or more fonts or font family objects triggers an update of a global generation seed value. Each font and font family modified during a transaction is tagged with a copy of the generation seed.

    You can use the function FMGetGeneration to get the current value of the generation seed. Then you can use this information in conjunction with the functions FMGetFontGeneration and FMGetFontFamilyGeneration to identify any changes in the font database.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

ATSUI Data Types

The data types in this section are used by Apple Type Services for Unicode Imaging (ATSUI).

  • Represents a glyph code.

    Declaration

    Objective-C

    typedef UInt16 ATSGlyph;

    Import Statement

  • Contains ideal (resolution-independent) metrics for a glyph.

    Declaration

    Swift

    struct ATSGlyphIdealMetrics { var advance: ATSPoint var sideBearing: ATSPoint var otherSideBearing: ATSPoint }

    Objective-C

    struct ATSGlyphIdealMetrics { Float32Point advance; Float32Point sideBearing; Float32Point otherSideBearing; }; typedef struct ATSGlyphIdealMetrics ATSGlyphIdealMetrics;

    Fields

    advance

    The amount by which the pen is advanced after drawing the glyph.

    sideBearing

    The offset from the glyph origin to the beginning of the glyph image.

    otherSideBearing

    The offset from the end of the glyph image to the end of the glyph advance.

    Discussion

    This data structure is passed as a parameter to the ATSUI function ATSUGlyphGetIdealMetrics. For more information, see Inside Mac OS X: ATSUI Reference.

    Availability

    Available in OS X v10.0 and later.

  • Represents a glyph reference.

    Declaration

    Swift

    typealias ATSGlyphRef = UInt16

    Objective-C

    typedef UInt16 ATSGlyphRef;

    Discussion

    This data type is used in the ATSUI data structure ATSLayoutRecord. For information, see Inside Mac OS X: ATSUI Reference.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Contains device-adjusted font metric information for glyphs in a font.

    Declaration

    Swift

    struct ATSGlyphScreenMetrics { var deviceAdvance: ATSPoint var topLeft: ATSPoint var height: UInt32 var width: UInt32 var sideBearing: ATSPoint var otherSideBearing: ATSPoint }

    Objective-C

    struct ATSGlyphScreenMetrics { Float32Point deviceAdvance; Float32Point topLeft; UInt32 height; UInt32 width; Float32Point sideBearing; Float32Point otherSideBearing; }; typedef struct ATSGlyphScreenMetrics ATSGlyphScreenMetrics;

    Fields

    deviceAdvance

    The number of pixels of the advance for the glyph as actually drawn on the screen.

    topLeft

    The top-left point of the glyph in device coordinates.

    height

    The height of the glyph, in pixels. The glyph specified by this value may overlap with other glyphs when drawn.

    width

    The width of the glyph, in pixels. The glyph specified by this value may overlap with other glyphs when drawn.

    sideBearing

    The origin-side bearing, in pixels.

    otherSideBearinge

    The trailing-side bearing, in pixels.

    Discussion

    The ATSGlyphScreenMetrics data structure contains metrics for where glyphs should be drawn on the screen. The metrics include any adjustments needed to display the glyphs properly on the current screen. The structure is returned by the ATSUI function ATSUGlyphGetScreenMetrics. Many of the metrics in this structure are Float32Point data types so the metrics can integrate with Quartz functions, which all require Float32Point data types.

    For information on the ATSUI function ATSUGlyphGetScreenMetrics, see Inside Mac OS X: ATSUI Reference.

    Availability

    Available in OS X v10.0 and later.

  • Contains curve information for a glyph path.

    Declaration

    Swift

    struct ATSUCurvePath { var vectors: UInt32 var controlBits: (UInt32) var vector: (ATSPoint) }

    Objective-C

    struct ATSUCurvePath { UInt32 vectors; UInt32 controlBits[1]; Float32Point vector[1]; }; typedef struct ATSUCurvePath ATSUCurvePath;

    Fields

    vectors

    The number of values in each of the controlBits and vector arrays.

    controlBits

    An array of control bit values that, together with the values in the vector array, define one cubic curve in a glyph.

    vector

    An array of vector values that, together with the values in the controlBits array, define one cubic curve in a glyph.

    Discussion

    This data structure is used in the ATSUCurvePaths data structure. The ATSUCurvePaths data structure is passed as a parameter to the ATSUI function ATSUGlyphGetCurvePaths. For more information, see Inside Mac OS X: ATSUI Reference.

    Availability

    Available in OS X v10.0 and later.

  • Contains curve information for an array of glyph paths.

    Declaration

    Swift

    struct ATSUCurvePaths { var contours: UInt32 var contour: (ATSUCurvePath) }

    Objective-C

    struct ATSUCurvePaths { UInt32 contours; ATSUCurvePath contour[1]; }; typedef struct ATSUCurvePaths ATSUCurvePaths;

    Fields

    contours

    The number of cubic curves contained in the contour array.

    contour

    An array of cubic curves that define the outline of a glyph.

    Discussion

    The ATSUCurvePaths data structure is passed as a parameter to the ATSUI function ATSUGlyphGetCurvePaths. For more information, see Inside Mac OS X: ATSUI Reference.

    Availability

    Available in OS X v10.0 and later.

  • Represents a reference to a glyph.

    Declaration

    Swift

    typealias GlyphID = ATSGlyphRef

    Objective-C

    typedef ATSGlyphRef GlyphID;

    Discussion

    The GlyphID data type is used by ATSUI. For more information, see Inside Mac OS X: ATSUI Reference.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

Constants

ATS Constants

  • Specify assorted options.

    Declaration

    Swift

    var kATSOptionFlagsDefault: Int { get } var kATSOptionFlagsComposeFontPostScriptName: Int { get } var kATSOptionFlagsUseDataForkAsResourceFork: Int { get } var kATSOptionFlagsUseResourceFork: Int { get } var kATSOptionFlagsUseDataFork: Int { get }

    Objective-C

    enum { kATSOptionFlagsDefault = kNilOptions, kATSOptionFlagsComposeFontPostScriptName = 1 << 0, kATSOptionFlagsUseDataForkAsResourceFork = 1 << 8, kATSOptionFlagsUseResourceFork = 2 << 8, kATSOptionFlagsUseDataFork = 3 << 8 };

    Constants

    • kATSOptionFlagsDefault

      kATSOptionFlagsDefault

      Specifies to use the default setting.

      Available in OS X v10.0 and later.

    • kATSOptionFlagsComposeFontPostScriptName

      kATSOptionFlagsComposeFontPostScriptName

      Specifies the composed PostScript name of a font.

      Available in OS X v10.0 and later.

    • kATSOptionFlagsUseDataForkAsResourceFork

      kATSOptionFlagsUseDataForkAsResourceFork

      Specifies to use the data fork of a font as a resource fork. You can pass this option in the iOptions parameter for the function ATSFontActivateFromFileSpecification.

      Available in OS X v10.0 and later.

    • kATSOptionFlagsUseResourceFork

      kATSOptionFlagsUseResourceFork

      Specifies to use the resource fork of a font.

      Available in OS X v10.0 and later.

    • kATSOptionFlagsUseDataFork

      kATSOptionFlagsUseDataFork

      Specifies to use the data fork of a font.

      Available in OS X v10.0 and later.

  • Values for automatic activation settings.

    Declaration

    Swift

    typealias ATSFontAutoActivationSetting = UInt32

    Objective-C

    enum { kATSFontAutoActivationDefault = 0, kATSFontAutoActivationDisabled = 1, kATSFontAutoActivationEnabled = 2, kATSFontAutoActivationAsk = 4 } typedef UInt32 ATSFontAutoActivationSetting;

    Constants

    • kATSFontAutoActivationDefault

      kATSFontAutoActivationDefault

      Resets the setting the the default state. For application settings this clears the setting. For the global setting, it reverts to the initial system setting, kATSFontAutoActivationEnabled.

      Available in OS X v10.5 and later.

    • kATSFontAutoActivationAsk

      kATSFontAutoActivationAsk

      Asks the user before automatically activating fonts requested by the application.

      Available in OS X v10.5 and later.

    • kATSFontAutoActivationEnabled

      kATSFontAutoActivationEnabled

      Enables automatic activation of fonts.

      Available in OS X v10.5 and later.

    • kATSFontAutoActivationDisabled

      kATSFontAutoActivationDisabled

      Disables automatic activation of fonts.

      Available in OS X v10.5 and later.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.5 and later.

  • Specify a context to use when enumerating, activating, or deactivating fonts and font families.

    Declaration

    Swift

    typealias ATSFontContext = UInt32

    Objective-C

    typedef UInt32 ATSFontContext; enum { kATSFontContextUnspecified = 0, kATSFontContextGlobal = 1, kATSFontContextLocal = 2 };

    Constants

    • kATSFontContextUnspecified

      kATSFontContextUnspecified

      Indicates a context is not specified. This option has the same result as providing the option kATSFontContextLocal.

      Available in OS X v10.0 and later.

    • kATSFontContextGlobal

      kATSFontContextGlobal

      Specifies to use a global context. Fonts with a global context are available to all applications on the system.

      Available in OS X v10.0 and later.

    • kATSFontContextLocal

      kATSFontContextLocal

      Specifies to use a local context. Fonts with a local context are available to your application.

      Available in OS X v10.1 and later.

    Discussion

    Context refers to the font’s availability and can be local or global. You provide a context as an option to such functions as ATSFontActivateFromFileSpecification, ATSFontActivateFromMemory, ATSFontFamilyIteratorCreate, ATSFontFamilyIteratorReset. ATSFontIteratorCreate, and ATSFontIteratorReset.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Indicate data that is not specified.

    Declaration

    Swift

    var kATSGenerationUnspecified: Int { get } var kATSFontContainerRefUnspecified: Int { get } var kATSFontFamilyRefUnspecified: Int { get } var kATSFontRefUnspecified: Int { get }

    Objective-C

    enum { kATSGenerationUnspecified = 0, kATSFontContainerRefUnspecified = 0, kATSFontFamilyRefUnspecified = 0, kATSFontRefUnspecified = 0 };

    Constants

    • kATSGenerationUnspecified

      kATSGenerationUnspecified

      Indicates the generation is not specified.

      Available in OS X v10.0 and later.

    • kATSFontContainerRefUnspecified

      kATSFontContainerRefUnspecified

      Indicates the font container reference is not specified.

      Available in OS X v10.0 and later.

    • kATSFontFamilyRefUnspecified

      kATSFontFamilyRefUnspecified

      Indicates the font family reference is not specified.

      Available in OS X v10.0 and later.

    • kATSFontRefUnspecified

      kATSFontRefUnspecified

      Indicates the font reference is not specified.

      Available in OS X v10.0 and later.

    Discussion

    You can pass these constants to functions when you either don’t know the appropriate value or do not care to obtain the associated information. These constants can also be returned to you to indicate an error.

  • Specify the type of criteria to use when limiting an iteration.

    Declaration

    Swift

    struct ATSFontFilterSelector { init(_ value: UInt32) var value: UInt32 }

    Objective-C

    enum ATSFontFilterSelector { kATSFontFilterSelectorUnspecified = 0, kATSFontFilterSelectorGeneration = 3, kATSFontFilterSelectorFontFamily = 7, kATSFontFilterSelectorFontFamilyApplierFunction = 8, kATSFontFilterSelectorFontApplierFunction = 9 }; typedef enum ATSFontFilterSelector ATSFontFilterSelector;

    Constants

    • kATSFontFilterSelectorUnspecified

      kATSFontFilterSelectorUnspecified

      Specifies to limit an iteration based on unspecified criteria. In this case, the default is used, which is to iterate using a local context with an unrestricted scope.

      Available in OS X v10.0 and later.

    • kATSFontFilterSelectorGeneration

      kATSFontFilterSelectorGeneration

      Specifies to limit an iteration based on generation criteria.

      Available in OS X v10.0 and later.

    • kATSFontFilterSelectorFontFamily

      kATSFontFilterSelectorFontFamily

      Specifies to limit an iteration based on font family criteria.

      Available in OS X v10.0 and later.

    • kATSFontFilterSelectorFontFamilyApplierFunction

      kATSFontFilterSelectorFontFamilyApplierFunction

      Specifies to limit an iteration based on criteria defined by a font family applier function.

      Available in OS X v10.0 and later.

    • kATSFontFilterSelectorFontApplierFunction

      kATSFontFilterSelectorFontApplierFunction

      Specifies to limit an iteration based on criteria defined by a font applier function.

      Available in OS X v10.0 and later.

    Discussion

    You use these constants in the data structure ATSFontFilter to specify the type of data in the filter union.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Specify the version of a font filter.

    Declaration

    Swift

    typealias ATSFontFormat = UInt32

    Objective-C

    typedef UInt32 ATSFontFormat; enum { kATSFontFilterCurrentVersion = 0 };

    Constants

    • kATSFontFilterCurrentVersion

      kATSFontFilterCurrentVersion

      Specifies to use the current version of a font filter.

      Available in OS X v10.0 and later.

    Discussion

    There is currently only one constant in this enumeration. You can assign this constant to the version field in the ATSFontFilter data structure.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Specify a font format.

    Declaration

    Swift

    var kATSFontFormatUnspecified: Int { get }

    Objective-C

    enum { kATSFontFormatUnspecified = 0 };

    Constants

    • kATSFontFormatUnspecified

      kATSFontFormatUnspecified

      Indicates the font format is not specified. You can pass this in the iFormat parameter of the function ATSFontActivateFromFileSpecification.

      Available in OS X v10.0 and later.

    Discussion

    There are no other font formats currently defined for this enumeration.

  • Represent keys in a font request query dictionary.

    Declaration

    Objective-C

    #define kATSQueryClientPID CFSTR ("ATS client pid") #define kATSQueryQDFamilyName CFSTR ("font family name") #define kATSQueryFontName CFSTR ("font name") #define kATSQueryFontPostScriptName CFSTR ("font PS name") #define kATSQueryFontNameTableEntries CFSTR ("font name table entries") #define kATSFontNameTableCode CFSTR ("font name code") #define kATSFontNameTablePlatform CFSTR ("font platform code") #define kATSFontNameTableScript CFSTR ("font script code") #define kATSFontNameTableLanguage CFSTR ("font language code") #define kATSFontNameTableBytes CFSTR ("font name table bytes")

    Constants

    • kATSQueryClientPID

      kATSQueryClientPID

      Specifies a process ID. The value associated with this key is a CFNumberRef value that refers to a the process ID (pid_t) of the application making the query.

    • kATSQueryQDFamilyName

      kATSQueryQDFamilyName

      Specifies a QuickDraw family name. The value associated with this key is a CFStringRef value that refers to the QuickDraw family name of the requested font. For example, the name passed to the function GetFNum.

    • kATSQueryFontName

      kATSQueryFontName

      Specifies a font name. The value associated with this key is a CFStringRef value that refers to the full name of the requested font. You can use this font name as an argument to the function ATSFontFindFromName.

    • kATSQueryFontPostScriptName

      kATSQueryFontPostScriptName

      Specifies the PostScript name of a font. The value associated with this key is a CFStringRef value that refers to either the PostScript name derived from the font's FOND resource or from the font’s 'sfnt' name table, with preference given to the FOND PostScript name. You can use this font name as an argument to the function ATSFontFindFromPostScriptName.

    • kATSQueryFontNameTableEntries

      kATSQueryFontNameTableEntries

      Specifies the descriptor for 'sfnt' name table entries. The value associated with this key an array (CFArrayRef ) of CFDictionaryRef values that describe entries in a name table. A font must have all of the specified entries to be considered a match.

    • kATSFontNameTableCode

      kATSFontNameTableCode

      Specifies the font name's name code. The value associated with this key is a CFNumberRef. If no value is specified, the value kFontNoNameCode is used.

    • kATSFontNameTablePlatform

      kATSFontNameTablePlatform

      Specifies the font name's platform code. The value associated with this key is a CFNumberRef. If no value is specified, the value kFontNoPlatformCode is used.

    • kATSFontNameTableScript

      kATSFontNameTableScript

      Specifies the font name's script code. The value associated with this key is a CFNumberRef. If no value is specified, the value kFontNoScriptCode is used.

    • kATSFontNameTableLanguage

      kATSFontNameTableLanguage

      Specifies the font name's language code. The value associated with this key is a CFNumberRef. If no value is specified, the value kFontNoLanguageCode is used.

    • kATSFontNameTableBytes

      kATSFontNameTableBytes

      Specifies the raw bytes of the font name. The value associated with this key is a CFDataRef value that refers to the raw name bytes for the font.

    Discussion

    Font request query keys appear in the dictionary passed to, and returned by, your ATSFontQueryCallback callback function. The keys comprise a property list (CFPropertyList) that defines the query sent to your callback. On return, you supply a property list that specifies your response to the query.

  • Specifies a message ID for a font request query.

    Declaration

    Swift

    struct ATSFontQueryMessageID { init(_ value: UInt32) var value: UInt32 }

    Objective-C

    enum ATSFontQueryMessageID { kATSQueryActivateFontMessage = 'atsa' }; typedef enum ATSFontQueryMessageID ATSFontQueryMessageID;

    Constants

    • kATSQueryActivateFontMessage

      kATSQueryActivateFontMessage

      Specifies to activate a font message. The data associated with this message ID is a flattened CFDictionaryRef. The CFDictionary contains on or more of the keys described in Font Request Query Keys.

      Available in OS X v10.2 and later.

    Discussion

    There is currently only one constant in this enumeration. You use a constant of this type when you create an ATSFontQueryCallback callback function.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Specify the order of an iteration.

    Declaration

    Swift

    var kATSOptionFlagsIterateByPrecedenceMask: Int { get }

    Objective-C

    enum { kATSOptionFlagsIterateByPrecedenceMask = 0x00000001 << 5 };

    Constants

    • kATSOptionFlagsIterateByPrecedenceMask

      kATSOptionFlagsIterateByPrecedenceMask

      Specifies to iterate fonts in the order dictated by a precedence mask.

      Available in OS X v10.1 and later.

  • Specify a notification action.

    Declaration

    Swift

    struct ATSFontNotifyAction { init(_ value: UInt32) var value: UInt32 }

    Objective-C

    enum ATSFontNotifyAction { kATSFontNotifyActionFontsChanged = 1, kATSFontNotifyActionDirectoriesChanged = 2 }; typedef enum ATSFontNotifyAction ATSFontNotifyAction;

    Constants

    • kATSFontNotifyActionFontsChanged

      kATSFontNotifyActionFontsChanged

      Specifies that your application has activated or deactivated fonts. Typically you call the functions ATSFontActivateFromFileSpecification or ATSFontDeactivate multiple times to activate and deactivate fonts. In each call, you set the iOptions parameter to kATSOptionFlagsDoNotNotify set. When you are done activating and deactivating 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.

      Available in OS X v10.2 and later.

    • kATSFontNotifyActionDirectoriesChanged

      kATSFontNotifyActionDirectoriesChanged

      Specifies that your application has made changes to one or more of the font directories. When you are making changes to font directories, you can call the function ATSFontNotify with the action parameter set to kATSFontNotifyActionDirectoriesChanged. Then ATS scans these directories and notifies all applications who subscribe to notifications of the changes you made.

      Available in OS X v10.2 and later.

    Discussion

    You can use these options with the function ATSFontNotify.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Specify when ATS should notify your application of changes in the font database.

    Declaration

    Swift

    struct ATSFontNotifyOption { init(_ value: UInt32) var value: UInt32 }

    Objective-C

    enum ATSFontNotifyOption { kATSFontNotifyOptionDefault = 0, kATSFontNotifyOptionReceiveWhileSuspended = 1L << 0 }; typedef enum ATSFontNotifyOption ATSFontNotifyOption;

    Constants

    • kATSFontNotifyOptionDefault

      kATSFontNotifyOptionDefault

      Specifies to use the default behavior of the function ATSFontNotificationSubscribe.

      Available in OS X v10.2 and later.

    • kATSFontNotifyOptionReceiveWhileSuspended

      kATSFontNotifyOptionReceiveWhileSuspended

      Specifies to receive notifications even if the application is in the background. Setting this option can degrade performance; you should set this option if your application is a faceless process or a tool that performs font management functions and requires immediate notification when fonts change.

      Available in OS X v10.2 and later.

    Discussion

    You use notification options when you call the function ATSFontNotificationSubscribe. The default behavior is for applications to receive ATS notifications only when the application runs in the foreground. By default, if the application is suspended, the notification is delivered when the application comes to the foreground.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Specify the scope to which an operation should apply or a notification schedule.

    Declaration

    Swift

    var kATSOptionFlagsDoNotNotify: Int { get } var kATSOptionFlagsIterationScopeMask: Int { get } var kATSOptionFlagsDefaultScope: Int { get } var kATSOptionFlagsUnRestrictedScope: Int { get } var kATSOptionFlagsRestrictedScope: Int { get } var kATSOptionFlagsProcessSubdirectories: Int { get }

    Objective-C

    enum { kATSOptionFlagsDoNotNotify = 0x00000001 << 8, kATSOptionFlagsIterationScopeMask = 0x00000007 << 12, kATSOptionFlagsDefaultScope = 0x00000000 << 12, kATSOptionFlagsUnRestrictedScope = 0x00000001 << 12, kATSOptionFlagsRestrictedScope = 0x00000002 << 12, kATSOptionFlagsProcessSubdirectories = 0x00000001 << 6 };

    Constants

    Discussion

    Scope refers to whether a font’s use is restricted or unrestricted. Fonts with a restricted scope can be used only by your application whereas fonts with an unrestricted scope cay be used by all applications.

Font Manager Constants

  • Specifies a filter format.

    Declaration

    Swift

    var kFMCurrentFilterFormat: Int { get }

    Objective-C

    enum { kFMCurrentFilterFormat = 0 };

    Constants

    • kFMCurrentFilterFormat

      kFMCurrentFilterFormat

      Specifies the current filter format. You can use this to set the format field when you initialize the FMFilter data type for use in creating an iterator object with the functions FMCreateFontFamilyIterator or FMCreateFontIterator. Currently, this is the only format you can specify.

      Available in OS X v10.0 and later.

  • Specifies a filter type.

    Declaration

    Swift

    typealias FMFilterSelector = UInt32

    Objective-C

    typedef UInt32 FMFilterSelector; enum { kFMFontTechnologyFilterSelector = 1, kFMFontContainerFilterSelector = 2, kFMGenerationFilterSelector = 3, kFMFontFamilyCallbackFilterSelector = 4, kFMFontCallbackFilterSelector = 5, kFMFontDirectoryFilterSelector = 6 };

    Constants

    • kFMFontTechnologyFilterSelector

      kFMFontTechnologyFilterSelector

      Selects font technology filter. You can use this filter only with a font iterator.

      Available in OS X v10.0 and later.

    • kFMFontContainerFilterSelector

      kFMFontContainerFilterSelector

      Selects font container filter. You can use this filter only with a font iterator.

      Available in OS X v10.0 and later.

    • kFMGenerationFilterSelector

      kFMGenerationFilterSelector

      Selects generation filter. You can use this filter only with a font family iterator.

      Available in OS X v10.0 and later.

    • kFMFontFamilyCallbackFilterSelector

      kFMFontFamilyCallbackFilterSelector

      Indicates a custom filter to be used only with a font family iterator.

      Available in OS X v10.0 and later.

    • kFMFontCallbackFilterSelector

      kFMFontCallbackFilterSelector

      Indicates a custom filter to be used only with a font iterator.

      Available in OS X v10.0 and later.

    Discussion

    You use these constants to specify a filter type in the FMFilter data structure used by many Font Manager functions.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Specify a font technology.

    Declaration

    Swift

    var kFMTrueTypeFontTechnology: Int { get } var kFMPostScriptFontTechnology: Int { get }

    Objective-C

    enum { kFMTrueTypeFontTechnology = 'true', kFMPostScriptFontTechnology = 'typ1' };

    Constants

    • kFMTrueTypeFontTechnology

      kFMTrueTypeFontTechnology

      Indicates True Type font technology.

      Available in OS X v10.0 and later.

    • kFMPostScriptFontTechnology

      kFMPostScriptFontTechnology

      Indicates Post Script font technology.

      Available in OS X v10.0 and later.

  • Specify an invalid value.

    Declaration

    Swift

    var kInvalidGeneration: Int { get } var kInvalidFontFamily: Int { get } var kInvalidFont: Int { get }

    Objective-C

    enum { kInvalidGeneration = 0, kInvalidFontFamily = -1, kInvalidFont = 0 };

    Constants

    • kInvalidGeneration

      kInvalidGeneration

      Indicates an invalid generation value.

      Available in OS X v10.0 and later.

    • kInvalidFontFamily

      kInvalidFontFamily

      Indicates the font family reference is invalid.

      Available in OS X v10.0 and later.

    • kInvalidFont

      kInvalidFont

      Indicates the font reference is invalid.

      Available in OS X v10.0 and later.

    Discussion

    The kInvalidGeneration, kInvalidFontFamily, and kInvalidFont constants may be used to indicate invalid values for generation count, font family, and font data types.

ATSUI Constants

  • Represent numerical values that are commonly used in font calculations.

    Declaration

    Swift

    var kATSItalicQDSkew: Int { get } var kATSBoldQDStretch: Int { get } var kATSRadiansFactor: Int { get }

    Objective-C

    enum { kATSItalicQDSkew = (1 << 16) / 4, kATSBoldQDStretch = (1 << 16) * 3 / 2, kATSRadiansFactor = 1144 };

    Constants

    • kATSItalicQDSkew

      kATSItalicQDSkew

      A Fixed value of 0.25 that represents the skew used by QuickDraw to draw italicized glyphs.

      Available in OS X v10.0 and later.

    • kATSBoldQDStretch

      kATSBoldQDStretch

      A Fixed value that represents the stretch-factor used by QuickDraw to draw bold-faced glyphs.

      Available in OS X v10.0 and later.

    • kATSRadiansFactor

      kATSRadiansFactor

      A Fixed value of approximately pi/180(0.0174560546875) that represents an angle of 1 radian. This is a convenience constant you can use when you draw rotated text.

      Available in OS X v10.0 and later.

    Discussion

    These constants are provided for convenience. Your application can use them when it needs to perform font calculations.

  • Specify a curve type used to draw a font.

    Declaration

    Swift

    typealias ATSCurveType = UInt16

    Objective-C

    typedef UInt16 ATSCurveType; enum { kATSCubicCurveType = 0x0001, kATSQuadCurveType = 0x0002, kATSOtherCurveType = 0x0003 };

    Constants

    • kATSCubicCurveType

      kATSCubicCurveType

      Specifies a cubic curve.

      Available in OS X v10.0 and later.

    • kATSQuadCurveType

      kATSQuadCurveType

      Specifies a quadratic curve.

      Available in OS X v10.0 and later.

    • kATSOtherCurveType

      kATSOtherCurveType

      Specifies a curve other than cubic or quadratic.

      Available in OS X v10.0 and later.

    Discussion

    These are used in the ATSUI function ATSUGetNativeCurveType. See Inside Mac OS X: ATSUI Reference for more information.

    Import Statement

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.0 and later.

  • Specifies that a glyph is deleted.

    Declaration

    Swift

    var kATSDeletedGlyphcode: Int { get }

    Objective-C

    enum { kATSDeletedGlyphcode = 0xFFFF };

    Constants

    • kATSDeletedGlyphcode

      kATSDeletedGlyphcode

      Indicates that a glyph is deleted. That is, the glyph is set to no longer appear in a text layout.

      Available in OS X v10.2 and later.

    Discussion

    This constant is used by ATSUI. When a glyph is deleted, ATSUI sets the corresponding ATSGlyphRef to kATSDeletedGlyphcode. For more information, see Inside Mac OS X: ATSUI Reference.

Result Codes

The most common result codes returned by Apple Type Services for Fonts are listed below.

  • The iteration is complete.

    Value

    -980L

    Description

    The iteration is complete.

    Available in OS X v10.0 and later.

  • Your application tried to access an invalid font family.

    Value

    -981L

    Description

    Your application tried to access an invalid font family.

    Available in OS X v10.0 and later.

  • Your application tried to access an invalid font.

    Value

    -982L

    Description

    Your application tried to access an invalid font.

    Available in OS X v10.0 and later.

  • The font database changed during an iteration.

    Value

    -983L

    Description

    The font database changed during an iteration.

    Available in OS X v10.0 and later.

  • Your application tried to access an invalid font table.

    Value

    -984L

    Description

    Your application tried to access an invalid font table.

    Available in OS X v10.0 and later.

  • Your application tried to access an invalid font container.

    Value

    -985L

    Description

    Your application tried to access an invalid font container.

    Available in OS X v10.0 and later.