Overview

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

Functions by Task

Activating and Deactivating Fonts

• ATSFontActivateFromFileSpecification
• ATSFontActivateFromFileReference
• ATSFontActivateFromMemory
• ATSFontDeactivate
• ATSGetGeneration
• ATSFontSetGlobalAutoActivationSetting
• ATSFontGetGlobalAutoActivationSetting
• ATSFontSetAutoActivationSettingForApplication
• ATSFontGetAutoActivationSettingForApplication

Working With Font Families

• ATSFontFamilyApplyFunction
• ATSFontFamilyIteratorCreate
• ATSFontFamilyIteratorRelease
• ATSFontFamilyIteratorReset
• ATSFontFamilyIteratorNext
• ATSFontFamilyFindFromName
• ATSFontFamilyFindFromQuickDrawName
• ATSFontFamilyGetGeneration
• ATSFontFamilyGetName
• ATSFontFamilyGetQuickDrawName
• ATSFontFamilyGetEncoding

Working With Fonts

• ATSFontApplyFunction
• ATSFontIteratorCreate
• ATSFontIteratorRelease
• ATSFontIteratorReset
• ATSFontIteratorNext
• ATSFontFindFromName
• ATSFontFindFromPostScriptName
• ATSFontFindFromContainer
• ATSFontGetGeneration
• ATSFontGetContainerFromFileReference
• ATSFontGetContainer
• ATSFontGetName
• ATSFontGetPostScriptName
• ATSFontGetTableDirectory
• ATSFontGetTable
• ATSFontGetHorizontalMetrics
• ATSFontGetVerticalMetrics
• ATSFontGetFileSpecification
• ATSFontGetFileReference
• ATSFontGetFontFamilyResource
• ATSFontSetEnabled
• ATSFontIsEnabled

Setting Up Notifications and Queries

• ATSFontNotify
• ATSFontNotificationSubscribe
• ATSFontNotificationUnsubscribe
• ATSCreateFontQueryRunLoopSource

Creating, Calling, and Deleting Universal Procedure Pointers

• DisposeFMFontCallbackFilterUPP Deprecated in OS X v10.7
• DisposeFMFontFamilyCallbackFilterUPP Deprecated in OS X v10.7
• InvokeFMFontCallbackFilterUPP Deprecated in OS X v10.7
• InvokeFMFontFamilyCallbackFilterUPP Deprecated in OS X v10.7
• NewFMFontCallbackFilterUPP Deprecated in OS X v10.7
• NewFMFontFamilyCallbackFilterUPP Deprecated in OS X v10.7

Functions

ATSCreateFontQueryRunLoopSource

Sets up your application to handle font queries.

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

ATSFontActivateFromFileReference

Activates one or more fonts from a file reference.

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

ATSFontActivateFromFileSpecification

Activates one or more fonts from a file specification. (Deprecated. Instead use ATSFontActivateFromFileReference.)

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

ATSFontActivateFromMemory

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

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

ATSFontApplyFunction

Applies your callback to a font iteration.

OSStatus ATSFontApplyFunction (
   ATSFontApplierFunction iFunction,
   void *iRefCon
);

ATSFontDeactivate

Deactivates one or more fonts.

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

ATSFontFamilyApplyFunction

Applies your callback to a font family iteration.

OSStatus ATSFontFamilyApplyFunction (
   ATSFontFamilyApplierFunction iFunction,
   void *iRefCon
);

ATSFontFamilyFindFromName

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

ATSFontFamilyRef ATSFontFamilyFindFromName (
   CFStringRef iName,
   ATSOptionFlags iOptions
);

ATSFontFamilyFindFromQuickDrawName

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

ATSFontFamilyRef ATSFontFamilyFindFromQuickDrawName (
   ConstStr255Param iName
);

ATSFontFamilyGetEncoding

Returns the text encoding used by a font family.

TextEncoding ATSFontFamilyGetEncoding (
   ATSFontFamilyRef iFamily
);

ATSFontFamilyGetGeneration

Returns the generation count of a font family.

ATSGeneration ATSFontFamilyGetGeneration (
   ATSFontFamilyRef iFamily
);

ATSFontFamilyGetName

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

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

ATSFontFamilyGetQuickDrawName

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

OSStatus ATSFontFamilyGetQuickDrawName (
   ATSFontFamilyRef iFamily,
   Str255 oName
);

ATSFontFamilyIteratorCreate

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

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

ATSFontFamilyIteratorNext

Obtains the next font family reference.

OSStatus ATSFontFamilyIteratorNext (
   ATSFontFamilyIterator iIterator,
   ATSFontFamilyRef *oFamily
);

ATSFontFamilyIteratorRelease

Releases the memory associated with a font family iterator.

OSStatus ATSFontFamilyIteratorRelease (
   ATSFontFamilyIterator *ioIterator
);

ATSFontFamilyIteratorReset

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

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

ATSFontFindFromContainer

Obtains the font references contained in a font container.

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

ATSFontFindFromName

Returns the font reference associated with a font name.

ATSFontRef ATSFontFindFromName (
   CFStringRef iName,
   ATSOptionFlags iOptions
);

ATSFontFindFromPostScriptName

Returns the font reference associated with a PostScript font name.

ATSFontRef ATSFontFindFromPostScriptName (
   CFStringRef iName,
   ATSOptionFlags iOptions
);

ATSFontGetAutoActivationSettingForApplication

Gets the activation setting for the specified application.

ATSFontAutoActivationSetting ATSFontGetAutoActivationSettingForApplication (
   CFURLRef iApplicationFileURL
);

ATSFontGetContainer

Gets the font container reference for a font.

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

ATSFontGetContainerFromFileReference

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

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

ATSFontGetFileReference

Obtains the file reference for a font.

OSStatus ATSFontGetFileReference (
   ATSFontRef iFont,
   FSRef *oFile
);

ATSFontGetFileSpecification

Obtains the file specification for a font. (Deprecated. Instead use ATSFontGetFileReference.)

OSStatus ATSFontGetFileSpecification (
   ATSFontRef iFont,
   ATSFSSpec *oFile
);

ATSFontGetFontFamilyResource

Obtains the font family resource for a font.

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

ATSFontGetGeneration

Returns the generation count for a font.

ATSGeneration ATSFontGetGeneration (
   ATSFontRef iFont
);

ATSFontGetGlobalAutoActivationSetting

Gets the user's global auto-activation setting.

ATSFontAutoActivationSetting ATSFontGetGlobalAutoActivationSetting (
   void
);

ATSFontGetHorizontalMetrics

Obtains the horizontal metrics for a font.

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

ATSFontGetName

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

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

ATSFontGetPostScriptName

Obtains the PostScript name from a font reference.

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

ATSFontGetTable

Obtains a font table.

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

ATSFontGetTableDirectory

Obtains the table directory for a font.

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

ATSFontGetVerticalMetrics

Obtains the vertical metrics for a font.

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

ATSFontIsEnabled

Returns true if the font is enabled.

Boolean ATSFontIsEnabled (
   ATSFontRef iFont
);

ATSFontIteratorCreate

Creates a font iterator.

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

ATSFontIteratorNext

Obtains the next font reference.

OSStatus ATSFontIteratorNext (
   ATSFontIterator iIterator,
   ATSFontRef *oFont
);

ATSFontIteratorRelease

Releases a font iterator.

OSStatus ATSFontIteratorRelease (
   ATSFontIterator *ioIterator
);

ATSFontIteratorReset

Resets a font iterator to the beginning of the iteration.

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

ATSFontNotificationSubscribe

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

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

ATSFontNotificationUnsubscribe

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

OSStatus ATSFontNotificationUnsubscribe (
   ATSFontNotificationRef notificationRef
);

ATSFontNotify

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

OSStatus ATSFontNotify (
   ATSFontNotifyAction action,
   void *info
);

ATSFontSetAutoActivationSettingForApplication

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

OSStatus ATSFontSetAutoActivationSettingForApplication (
   ATSFontAutoActivationSetting iSetting,
   CFURLRef iApplicationFileURL
);

ATSFontSetEnabled

Sets a font state to enabled or disabled.

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

ATSFontSetGlobalAutoActivationSetting

Sets the user's global auto-activation setting.

OSStatus ATSFontSetGlobalAutoActivationSetting (
   ATSFontAutoActivationSetting iSetting
);

ATSGetGeneration

Obtains the generation of the font database.

ATSGeneration ATSGetGeneration (
   void
);

Callbacks by Task

ATS Callbacks

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

• ATSFontApplierFunction
• ATSFontFamilyApplierFunction
• ATSFontQueryCallback
• ATSNotificationCallback

FM Callbacks

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

• FMFontCallbackFilterProcPtr
• FMFontFamilyCallbackFilterProcPtr

Callbacks

ATSFontApplierFunction

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

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

If you name your function MyATSFontApplierFunction, you would declare it like this:

OSStatus MyATSFontApplierFunction (
   ATSFontRef iFont,
   void * iRefCon
);

ATSFontFamilyApplierFunction

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

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

If you name your function MyATSFontFamilyApplierFunction, you would declare it like this:

OSStatus MyATSFontFamilyApplierFunction (
   ATSFontFamilyRef iFamily,
   void * iRefCon
);

ATSFontQueryCallback

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

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

If you name your function MyATSFontQueryCallback, you would declare it like this:

CFPropertyListRef MyATSFontQueryCallback (
   ATSFontQueryMessageID msgid,
   CFPropertyListRef data
   void * iRefCon
);

ATSNotificationCallback

Defines a pointer to a customized function that handles notifications.

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

If you name your function MyATSNotificationCallback, you would declare it like this:

void MyATSNotificationCallback (
   ATSFontNotificationInfoRef info,
   void * iRefCon
);

FMFontCallbackFilterProcPtr

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

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

If you name your function MyFMFontCallbackFilterProc, you would declare it like this:

OSStatus MyFMFontCallbackFilterProcPtr (
   FMFont iFont,
   void * iRefCon
);

FMFontFamilyCallbackFilterProcPtr

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

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

If you name your function MyFMFontFamilyCallbackFilterProc, you would declare it like this:

OSStatus MyFMFontFamilyCallbackFilterProcPtr (
   FMFontFamily iFontFamily,
   void * iRefCon
);

Data Types

ATS Data Types

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

ATSFontContainerRef

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

typedef UInt32 ATSFontContainerRef;

ATSFontFamilyIterator

An opaque data type that represents a font family iterator.

typedef struct ATSFontFamilyIterator_ * ATSFontFamilyIterator;

ATSFontFamilyRef

An opaque data type that represents a font family reference.

typedef UInt32 ATSFontFamilyRef;

ATSFontFilter

Contains font filter information.

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 Selectors”for 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.

ATSFontIterator

An opaque data type that represents a font iterator.

typedef struct ATSFontIterator_ * ATSFontIterator;

ATSFontMetrics

Contains metrics for a font.

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.

ATSFontNotificationInfoRef

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

typedef struct ATSFontNotificationInfoRef_ * ATSFontNotificationInfoRef;

ATSFontNotificationRef

An opaque data type that represents a font notification structure.

typedef struct ATSFontNotificationRef_ * ATSFontNotificationRef;

ATSFontQuerySourceContext

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

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.

ATSFontRef

An opaque data type that represents a font reference.

typedef UInt32 ATSFontRef;

ATSFontSize

Represents a font size.

typedef Float32 ATSFontSize;

ATSGeneration

Represents a generation count.

typedef UInt32 ATSGeneration;

ATSOptionFlags

Represents options you can pass to various ATS functions.

typedef OptionBits ATSOptionFlags;

FM Data types

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

FMFilter

Contains a filter format, a selector and filter information.

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.

FMFont

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

typedef UInt32 FMFont;

FMFontCallbackFilterUPP

Defines a universal procedure pointer to a font filter callback.

typedef FMFontCallbackFilterProcPtr FMFontCallbackFilter;

FMFontDirectoryFilter

Contains font directory information used to restrict a font iteration.

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.

FMFontFamily

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

typedef SInt16 FMFontFamily;

FMFontFamilyCallbackFilterUPP

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

typedef FMFontFamilyCallbackFilterProcPtr FMFontFamilyCallbackFilter;

FMFontFamilyInstance

Contains a font family reference and a QuickDraw style.

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

Fields

fontFamily

A font family reference.

fontStyle

A QuickDraw font style.

FMFontFamilyInstanceIterator

An opaque structure used to enumerate font family instances.

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

Fields

reserved

Reserved for Apple’s use.

FMFontFamilyIterator

An opaque structure used to enumerate font families.

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

Fields

reserved

Reserved for Apple’s use.

FMFontIterator

An opaque structure used to enumerate fonts.

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

Fields

reserved

Reserved for Apple’s use.

FMFontSize

Represents a font size.

typedef SInt16 FMFontSize;

FMFontStyle

Represents a font style.

typedef SInt16 FMFontStyle;

FMGeneration

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

typedef UInt32 FMGeneration;

ATSUI Data Types

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

ATSGlyph

Represents a glyph code.

typedef UInt16 ATSGlyph;

ATSGlyphIdealMetrics

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

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.

ATSGlyphRef

Represents a glyph reference.

typedef UInt16 ATSGlyphRef;

ATSGlyphScreenMetrics

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

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.

ATSUCurvePath

Contains curve information for a glyph path.

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.

ATSUCurvePaths

Contains curve information for an array of glyph paths.

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.

GlyphID

Represents a reference to a glyph.

typedef ATSGlyphRef GlyphID;

Constants

ATS Constants

Assorted Options

Specify assorted options.

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

Constants

kATSOptionFlagsDefault

Specifies to use the default setting.

Available in OS X v10.0 and later.

Declared in ATSFont.h.

kATSOptionFlagsComposeFontPostScriptName

Specifies the composed PostScript name of a font.

Available in OS X v10.0 and later.

Declared in ATSFont.h.

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.

Declared in ATSFont.h.

kATSOptionFlagsUseResourceFork

Specifies to use the resource fork of a font.

Available in OS X v10.0 and later.

Declared in ATSFont.h.

kATSOptionFlagsUseDataFork

Specifies to use the data fork of a font.

Available in OS X v10.0 and later.

Declared in ATSFont.h.

Automatic Activation Settings

Values for automatic activation settings.

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

Constants

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.

Declared in ATSFont.h.

kATSFontAutoActivationAsk

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

Available in OS X v10.5 and later.

Declared in ATSFont.h.

kATSFontAutoActivationEnabled

Enables automatic activation of fonts.

Available in OS X v10.5 and later.

Declared in ATSFont.h.

kATSFontAutoActivationDisabled

Disables automatic activation of fonts.

Available in OS X v10.5 and later.

Declared in ATSFont.h.

Context Options

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

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

Constants

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.

Declared in ATSFont.h.

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.

Declared in ATSFont.h.

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.

Declared in ATSFont.h.

Data Not Specified Constants

Indicate data that is not specified.

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

Constants

kATSGenerationUnspecified

Indicates the generation is not specified.

Available in OS X v10.0 and later.

Declared in ATSTypes.h.

kATSFontContainerRefUnspecified

Indicates the font container reference is not specified.

Available in OS X v10.0 and later.

Declared in ATSTypes.h.

kATSFontFamilyRefUnspecified

Indicates the font family reference is not specified.

Available in OS X v10.0 and later.

Declared in ATSTypes.h.

kATSFontRefUnspecified

Indicates the font reference is not specified.

Available in OS X v10.0 and later.

Declared in ATSTypes.h.

Font Filter Selectors

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

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

Constants

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.

Declared in ATSFont.h.

kATSFontFilterSelectorGeneration

Specifies to limit an iteration based on generation criteria.

Available in OS X v10.0 and later.

Declared in ATSFont.h.

kATSFontFilterSelectorFontFamily

Specifies to limit an iteration based on font family criteria.

Available in OS X v10.0 and later.

Declared in ATSFont.h.

kATSFontFilterSelectorFontFamilyApplierFunction

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

Available in OS X v10.0 and later.

Declared in ATSFont.h.

kATSFontFilterSelectorFontApplierFunction

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

Available in OS X v10.0 and later.

Declared in ATSFont.h.

Font Filter Versions

Specify the version of a font filter.

typedef UInt32 ATSFontFormat;
enum {
   kATSFontFilterCurrentVersion = 0
};

Constants

kATSFontFilterCurrentVersion

Specifies to use the current version of a font filter.

Available in OS X v10.0 and later.

Declared in ATSFont.h.

Font Formats

Specify a font format.

enum {
   kATSFontFormatUnspecified = 0
};

Constants

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.

Declared in ATSTypes.h.

Font Request Query Keys

Represent keys in a font request query dictionary.

#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

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

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

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

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

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

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

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

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

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

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.

Font Query Message ID

Specifies a message ID for a font request query.

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

Constants

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.

Declared in ATSFont.h.

Iteration Precedence Options

Specify the order of an iteration.

enum {
   kATSOptionFlagsIterateByPrecedenceMask = 0x00000001 <<  5
};

Constants

kATSOptionFlagsIterateByPrecedenceMask

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

Available in OS X v10.1 and later.

Declared in ATSFont.h.

Notification Actions

Specify a notification action.

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

Constants

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.

Declared in ATSFont.h.

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.

Declared in ATSFont.h.

Notification Options

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

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

Constants

kATSFontNotifyOptionDefault

Specifies to use the default behavior of the function ATSFontNotificationSubscribe.

Available in OS X v10.2 and later.

Declared in ATSFont.h.

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.

Declared in ATSFont.h.

Scoping Options

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

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

Constants

kATSOptionFlagsDoNotNotify

Specifies not to send a notification after a font is activated or deactivated globally. You can set the iOptions parameter of the functions ATSFontActivateFromFileSpecification or ATSFontDeactivate to this constant. 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.

Declared in ATSFont.h.

kATSOptionFlagsIterationScopeMask

Specifies mask option bits 12-14 for iteration scopes.

Available in OS X v10.1 and later.

Declared in ATSFont.h.

kATSOptionFlagsDefaultScope

Specifies to use the default scope, which is equivalent to kATSOptionFlagsUnRestrictedScope. You can pass this as a parameter to the functions ATSFontFamilyIteratorCreate, ATSFontFamilyIteratorReset, ATSFontIteratorCreate and ATSFontIteratorReset.

Available in OS X v10.1 and later.

Declared in ATSFont.h.

kATSOptionFlagsUnRestrictedScope

Specifies to use an unrestricted scope. You can pass this as a parameter to the functions ATSFontFamilyIteratorCreate, ATSFontFamilyIteratorReset, ATSFontIteratorCreate and ATSFontIteratorReset.

Available in OS X v10.1 and later.

Declared in ATSFont.h.

kATSOptionFlagsRestrictedScope

Specifies to use a restricted scope. You can pass this as a parameter to the functions ATSFontFamilyIteratorCreate, ATSFontFamilyIteratorReset, ATSFontIteratorCreate and ATSFontIteratorReset.

Available in OS X v10.1 and later.

Declared in ATSFont.h.

kATSOptionFlagsProcessSubdirectories

Specifies to process the font directories within a font directory. You can pass this as a parameter to the function ATSFontActivateFromFileSpecification.

Available in OS X v10.2 and later.

Declared in ATSFont.h.

Font Manager Constants

FM Filter Format

Specifies a filter format.

enum {
   kFMCurrentFilterFormat = 0
};

Constants

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.

Declared in ATSTypes.h.

FM Filter Selectors

Specifies a filter type.

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

Constants

kFMFontTechnologyFilterSelector

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

Available in OS X v10.0 and later.

Declared in ATSTypes.h.

kFMFontContainerFilterSelector

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

Available in OS X v10.0 and later.

Declared in ATSTypes.h.

kFMGenerationFilterSelector

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

Available in OS X v10.0 and later.

Declared in ATSTypes.h.

kFMFontFamilyCallbackFilterSelector

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

Available in OS X v10.0 and later.

Declared in ATSTypes.h.

kFMFontCallbackFilterSelector

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

Available in OS X v10.0 and later.

Declared in ATSTypes.h.

FM Font Technologies

Specify a font technology.

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

Constants

kFMTrueTypeFontTechnology

Indicates True Type font technology.

Available in OS X v10.0 and later.

Declared in ATSTypes.h.

kFMPostScriptFontTechnology

Indicates Post Script font technology.

Available in OS X v10.0 and later.

Declared in ATSTypes.h.

Invalid Values

Specify an invalid value.

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

Constants

kInvalidGeneration

Indicates an invalid generation value.

Available in OS X v10.0 and later.

Declared in ATSTypes.h.

kInvalidFontFamily

Indicates the font family reference is invalid.

Available in OS X v10.0 and later.

Declared in ATSTypes.h.

kInvalidFont

Indicates the font reference is invalid.

Available in OS X v10.0 and later.

Declared in ATSTypes.h.

ATSUI Constants

Convenience Constants

Represent numerical values that are commonly used in font calculations.

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

Constants

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.

Declared in ATSTypes.h.

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.

Declared in ATSTypes.h.

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.

Declared in ATSTypes.h.

Curve Types

Specify a curve type used to draw a font.

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

Constants

kATSCubicCurveType

Specifies a cubic curve.

Available in OS X v10.0 and later.

Declared in ATSTypes.h.

kATSQuadCurveType

Specifies a quadratic curve.

Available in OS X v10.0 and later.

Declared in ATSTypes.h.

kATSOtherCurveType

Specifies a curve other than cubic or quadratic.

Available in OS X v10.0 and later.

Declared in ATSTypes.h.

Deleted Glyph Code

Specifies that a glyph is deleted.

enum {
   kATSDeletedGlyphcode = 0xFFFF
};

Constants

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.

Declared in ATSTypes.h.

Result Codes

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