Framework | ApplicationServices/ApplicationServices.h |
Declared in | ATSFont.h ATSTypes.h |
Apple Type Services for Fonts is a collection of functions and data types that you can use to access and manage font data in Mac OS X. It is designed to handle a wide range of font technologies and data formats. The programming interface is designed with performance, scalability, and consistency in mind, and is available to Cocoa and Carbon applications through the Apple Type Services (ATS) and QuickDraw frameworks in Mac OS X.
Carbon supports the Apple Type Services for Fonts.
ATSFontActivateFromFileReference
ATSFontActivateFromMemory
ATSFontDeactivate
ATSGetGeneration
ATSFontSetGlobalAutoActivationSetting
ATSFontGetGlobalAutoActivationSetting
ATSFontSetAutoActivationSettingForApplication
ATSFontGetAutoActivationSettingForApplication
ATSFontActivateFromFileSpecification
Deprecated in Mac OS X v10.5
ATSFontFamilyApplyFunction
ATSFontFamilyIteratorCreate
ATSFontFamilyIteratorRelease
ATSFontFamilyIteratorReset
ATSFontFamilyIteratorNext
ATSFontFamilyFindFromName
ATSFontFamilyFindFromQuickDrawName
ATSFontFamilyGetGeneration
ATSFontFamilyGetName
ATSFontFamilyGetQuickDrawName
ATSFontFamilyGetEncoding
ATSFontApplyFunction
ATSFontIteratorCreate
ATSFontIteratorRelease
ATSFontIteratorReset
ATSFontIteratorNext
ATSFontFindFromName
ATSFontFindFromPostScriptName
ATSFontFindFromContainer
ATSFontGetGeneration
ATSFontGetContainerFromFileReference
ATSFontGetContainer
ATSFontGetName
ATSFontGetPostScriptName
ATSFontGetTableDirectory
ATSFontGetTable
ATSFontGetHorizontalMetrics
ATSFontGetVerticalMetrics
ATSFontGetFileReference
ATSFontGetFontFamilyResource
ATSFontSetEnabled
ATSFontIsEnabled
ATSFontGetFileSpecification
Deprecated in Mac OS X v10.5
ATSFontNotify
ATSFontNotificationSubscribe
ATSFontNotificationUnsubscribe
ATSCreateFontQueryRunLoopSource
NewFMFontCallbackFilterUPP
DisposeFMFontCallbackFilterUPP
InvokeFMFontCallbackFilterUPP
NewFMFontFamilyCallbackFilterUPP
DisposeFMFontFamilyCallbackFilterUPP
InvokeFMFontFamilyCallbackFilterUPP
Sets up your application to handle font queries.
CFRunLoopSourceRef ATSCreateFontQueryRunLoopSource ( CFIndex queryOrder, CFIndex sourceOrder, ATSFontQueryCallback callout, const ATSFontQuerySourceContext *context );
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
.
A CFIndex
value that specifies the order of the run loop source.
A pointer to your callback for processing a font query. See ATSFontQueryCallback
for more information on the callback you can supply.
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.
A CFRunLoopSourceRef
. When you want to stop receiving queries, you must invalidate this reference.
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.
ATSFont.h
Activates one or more fonts from a file reference.
OSStatus ATSFontActivateFromFileReference ( const FSRef *iFile, ATSFontContext iContext, ATSFontFormat iFormat, void *iRefCon, ATSOptionFlags iOptions, ATSFontContainerRef *oContainer );
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.
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.
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.”
This parameter is currently reserved for future use, so you should pass NULL
.
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.
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
.
If activated successfully, noErr
.
ATSFont.h
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 );
The logical address of the font you want to activate.
The length (in bytes) of the font data.
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.
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.
An arbitrary 32-bit value. This parameter is currently reserved for future use, so you should pass NULL
.
An ATSOptionFlags
value. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault
.
On output, a pointer to a font container reference that refers to the file that contains the activated font data.
A result code. See “Apple Type Services for Fonts Result Codes.”
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
.
ATSFont.h
Applies your callback to a font iteration.
OSStatus ATSFontApplyFunction ( ATSFontApplierFunction iFunction, void *iRefCon );
The callback function you want applied to a font iteration. See ATSFontApplierFunction
for more information on the callback you need to supply.
An arbitrary 32-bit value specified by your application. This is passed to your callback.
A result code. See “Apple Type Services for Fonts Result Codes.”
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.
ATSFont.h
Deactivates one or more fonts.
OSStatus ATSFontDeactivate ( ATSFontContainerRef iContainer, void *iRefCon, ATSOptionFlags iOptions );
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
.
An arbitrary 32-bit value specified. This parameter is currently reserved for future use, so you should pass NULL
.
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.
A result code. See “Apple Type Services for Fonts Result Codes.”
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.
ATSFont.h
Applies your callback to a font family iteration.
OSStatus ATSFontFamilyApplyFunction ( ATSFontFamilyApplierFunction iFunction, void *iRefCon );
The callback function you want applied to a font family iteration. See ATSFontApplierFunction
for more information on the callback you need to supply.
An arbitrary 32-bit value specified by your application. This value is passed to your callback.
A result code. See “Apple Type Services for Fonts Result Codes.”
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.
ATSFont.h
Returns the font family reference associated with a font family name.
ATSFontFamilyRef ATSFontFamilyFindFromName ( CFStringRef iName, ATSOptionFlags iOptions );
A reference to a font family name, formatted as a CFString
.
An ATSOptionFlags
value. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault
.
A reference to the font family specified by the iName
parameter. See the description of the ATSFontFamilyRef
data type.
ATSFont.h
Returns the font family reference associated with a standard QuickDraw font name.
ATSFontFamilyRef ATSFontFamilyFindFromQuickDrawName ( ConstStr255Param iName );
A QuickDraw font name.
A reference to the font family associated with the font name specified by the iName
parameter. See the description of the ATSFontFamilyRef
data type.
ATSFont.h
Returns the text encoding used by a font family.
TextEncoding ATSFontFamilyGetEncoding ( ATSFontFamilyRef iFamily );
A font family reference.
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.
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);
ATSFont.h
Returns the generation count of a font family.
ATSGeneration ATSFontFamilyGetGeneration ( ATSFontFamilyRef iFamily );
A font family reference.
On output, the generation count for the font family associated with the font family reference. See the description of the ATSGeneration
data type.
The generation of a font family changes any time part of a font family is removed or added.
ATSFont.h
Obtains the font family name associated with a font family reference.
OSStatus ATSFontFamilyGetName ( ATSFontFamilyRef iFamily, ATSOptionFlags iOptions, CFStringRef *oName );
A font family reference.
An ATSOptionFlags
value. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault
.
On output, a reference to the name associated with the font family reference, formatted as a CFString
. You are responsible for releasing the CFStringRef
.
A result code. See “Apple Type Services for Fonts Result Codes.”
ATSFont.h
Obtains the standard QuickDraw font name associated with a font family reference.
OSStatus ATSFontFamilyGetQuickDrawName ( ATSFontFamilyRef iFamily, Str255 oName );
A reference to the font family name whose QuickDraw name you want to obtain.
On input, a Str255
value allocated by your application. On output, the QuickDraw name associated with the font family reference.
A result code. See “Apple Type Services for Fonts Result Codes.”
All font families are assigned a QuickDraw name by the system. The QuickDraw name is almost identical to the font family name.
ATSFont.h
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 );
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.
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.
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
.
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.
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.
A result code. See “Apple Type Services for Fonts Result Codes.”
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.
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. |
ATSFont.h
Obtains the next font family reference.
OSStatus ATSFontFamilyIteratorNext ( ATSFontFamilyIterator iIterator, ATSFontFamilyRef *oFamily );
A pointer to a font family iterator you created with the function ATSFontFamilyIteratorCreate
.
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.
A result code. See “Apple Type Services for Fonts Result Codes.”
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.
ATSFont.h
Releases the memory associated with a font family iterator.
OSStatus ATSFontFamilyIteratorRelease ( ATSFontFamilyIterator *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.
A result code. See “Apple Type Services for Fonts Result Codes.”
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.
ATSFont.h
Resets a font family iterator to the beginning of the iteration.
OSStatus ATSFontFamilyIteratorReset ( ATSFontContext iContext, const ATSFontFilter *iFilter, void *iRefCon, ATSOptionFlags iOptions, ATSFontFamilyIterator *ioIterator );
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.
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.
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
.
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
.
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.
A result code. See “Apple Type Services for Fonts Result Codes.”
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.
ATSFont.h
Obtains the font references contained in a font container.
OSStatus ATSFontFindFromContainer ( ATSFontContainerRef iContainer, ATSOptionFlags iOptions, ItemCount iCount, ATSFontRef ioArray[], ItemCount *oCount );
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
.
An ATSOptionFlags
value. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault
.
The number of items in the ioArray
array. If you are uncertain of how many items are in this array, see the Discussion.
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.
A pointer to an ItemCount
value. On output, the value specifies the actual number of ATSFontRef
values in the font container.
A result code. See “Apple Type Services for Fonts Result Codes.”
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:
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.
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.
ATSFont.h
Returns the font reference associated with a font name.
ATSFontRef ATSFontFindFromName ( CFStringRef iName, ATSOptionFlags iOptions );
A reference to a font name formatted as a CFString
.
An ATSOptionFlags
value. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault
.
A reference to the font specified by the iName
parameter. See the description of the ATSFontRef
data type.
ATSFont.h
Returns the font reference associated with a PostScript font name.
ATSFontRef ATSFontFindFromPostScriptName ( CFStringRef iName, ATSOptionFlags iOptions );
A reference to the PostScript name for a font, formatted as a CFString
.
An ATSOptionFlags
value. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault
.
A reference to the font specified by the iName
parameter. See the description of the ATSFontRef
data type.
ATSFont.h
Gets the activation setting for the specified application.
ATSFontAutoActivationSetting ATSFontGetAutoActivationSettingForApplication ( CFURLRef iApplicationFileURL );
A valid file URL for an application. Pass NULL
to specify the current process.
The activation setting for the specified application.
ATSFont.h
Gets the font container reference for a font.
OSStatus ATSFontGetContainer ( ATSFontRef iFont, ATSOptionFlags iOptions, ATSFontContainerRef *oContainer );
The font reference.
An options flag.
On output, a reference to the font container that was used to activate the font reference. On error ATS sets this to kATSFontContainerRefUnspecified
.
If successful, noErr
; if the container is invalid, kATSInvalidFontContainerAccess
.
ATSFont.h
Gets the font container reference associated with an activated file reference.
OSStatus ATSFontGetContainerFromFileReference ( const FSRef *iFile, ATSFontContext iContext, ATSOptionFlags iOptions, ATSFontContainerRef *oContainer );
A pointer to the valid file reference that specifies the activated font file for which to get the container.
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.
An options flag.
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
.
noErr
or paramErr
if one or more parameters are invalid.
ATSFont.h
Obtains the file reference for a font.
OSStatus ATSFontGetFileReference ( ATSFontRef iFont, FSRef *oFile );
A reference to the font whose file reference you want to obtain.
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.
If successful, noErr
.
ATSFont.h
Obtains the font family resource for a font.
OSStatus ATSFontGetFontFamilyResource ( ATSFontRef iFont, ByteCount iBufferSize, void *ioBuffer, ByteCount *oSize );
A font reference.
The size of the buffer pointed to by the ioBuffer
parameter. See the Discussion if you are unsure of the size of this buffer.
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.
On output, the actual size of the buffer.
A result code. See “Apple Type Services for Fonts Result Codes.”
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:
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.
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.
ATSFont.h
Returns the generation count for a font.
ATSGeneration ATSFontGetGeneration ( ATSFontRef iFont );
A font reference.
A generation count. See the description of the ATSGeneration
data type.
ATS for Fonts increments the generation count for any changes to a font, including when the system synthesizes data for the font.
ATSFont.h
Gets the user's global auto-activation setting.
ATSFontAutoActivationSetting ATSFontGetGlobalAutoActivationSetting ( void );
The user's global auto-activation setting.
ATSFont.h
Obtains the horizontal metrics for a font.
OSStatus ATSFontGetHorizontalMetrics ( ATSFontRef iFont, ATSOptionFlags iOptions, ATSFontMetrics *oMetrics );
A reference to the font whose horizontal metrics you want to obtain.
An options flag. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault
.
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
.
A result code. See “Apple Type Services for Fonts Result Codes.”
ATSFont.h
Obtains the name of a font associated with a font reference.
OSStatus ATSFontGetName ( ATSFontRef iFont, ATSOptionFlags iOptions, CFStringRef *oName );
A font reference.
An ATSOptionFlags
value. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault
.
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
.
A result code. See “Apple Type Services for Fonts Result Codes.”
ATSFont.h
Obtains the PostScript name from a font reference.
OSStatus ATSFontGetPostScriptName ( ATSFontRef iFont, ATSOptionFlags iOptions, CFStringRef *oName );
A font reference.
An ATSOptionFlags
value. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault
.
On output, a reference to the PostScript name for the font, formatted as a CFString
. You are responsible for releasing the CFStringRef
.
A result code. See “Apple Type Services for Fonts Result Codes.”
The system automatically detects whether or not the font is composed PostScript. If the font is, ATS for Fonts appends the CMAP name.
ATSFont.h
Obtains a font table.
OSStatus ATSFontGetTable ( ATSFontRef iFont, FourCharCode iTag, ByteOffset iOffset, ByteCount iBufferSize, void *ioBuffer, ByteCount *oSize );
A reference to the font whose table you want to obtain.
A four-character code that specifies the font table you want to obtain.
The offset to a font table. If you want to obtain all the font tables associated with a font, pass 0
.
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.
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.
On output, the actual size of the buffer returned in the ioBuffer
parameter.
A result code. See “Apple Type Services for Fonts Result Codes.”
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:
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.
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.
ATSFont.h
Obtains the table directory for a font.
OSStatus ATSFontGetTableDirectory ( ATSFontRef iFont, ByteCount iBufferSize, void *ioBuffer, ByteCount *oSize );
The font reference whose table directory you want to obtain.
The size of the buffer pointed to by the ioBuffer
parameter. See the Discussion if you are unsure of the size of this buffer.
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.
On output, the actual size of the buffer returned in the ioBuffer
parameter.
A result code. See “Apple Type Services for Fonts Result Codes.”
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:
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.
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
.
ATSFont.h
Obtains the vertical metrics for a font.
OSStatus ATSFontGetVerticalMetrics ( ATSFontRef iFont, ATSOptionFlags iOptions, ATSFontMetrics *oMetrics );
A reference to the font whose vertical metrics you want to obtain.
An options flag. This parameter is currently reserved for future use, so you should pass kATSOptionFlagsDefault
.
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
.
A result code. See “Apple Type Services for Fonts Result Codes.”
ATSFont.h
Returns true
if the font is enabled.
Boolean ATSFontIsEnabled ( ATSFontRef iFont );
The font reference.
true
if the font is enabled.
ATSFont.h
Creates a font iterator.
OSStatus ATSFontIteratorCreate ( ATSFontContext iContext, const ATSFontFilter *iFilter, void *iRefCon, ATSOptionFlags iOptions, ATSFontIterator *ioIterator );
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.
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.
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
.
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.
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.
A result code. See “Apple Type Services for Fonts Result Codes.”
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.
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. |
ATSFont.h
Obtains the next font reference.
OSStatus ATSFontIteratorNext ( ATSFontIterator iIterator, ATSFontRef *oFont );
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.
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.
A result code. See “Apple Type Services for Fonts Result Codes.”
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.
ATSFont.h
Releases a font iterator.
OSStatus ATSFontIteratorRelease ( ATSFontIterator *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.
A result code. See “Apple Type Services for Fonts Result Codes.”
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.
ATSFont.h
Resets a font iterator to the beginning of the iteration.
OSStatus ATSFontIteratorReset ( ATSFontContext iContext, const ATSFontFilter *iFilter, void *iRefCon, ATSOptionFlags iOptions, ATSFontIterator *ioIterator );
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.
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.
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
.
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
.
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.
A result code. See “Apple Type Services for Fonts Result Codes.”
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.
ATSFont.h
Signs up your application to receive notification of changes to fonts and font directories.
OSStatus ATSFontNotificationSubscribe ( ATSNotificationCallback callback, ATSFontNotifyOption options, void *iRefcon, ATSFontNotificationRef *oNotificationRef );
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.
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.
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.
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.
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.
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
.
ATSFont.h
Unsubscribes your application from receiving notifications of changes to fonts and font directories.
OSStatus ATSFontNotificationUnsubscribe ( ATSFontNotificationRef notificationRef );
On input, the notification reference you obtained when you called the function ATSFontNotificationSubscribe
. On output, NULL
.
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.
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.
ATSFont.h
Notifies Apple Type Services of an action taken by your application.
OSStatus ATSFontNotify ( ATSFontNotifyAction action, void *info );
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.
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.
A result code. See “Apple Type Services for Fonts Result Codes.” Returns paramErr
if you pass an invalid notification action in the action
parameter.
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.
ATSFont.h
Sets the auto-activation setting for the specified application bundle.
OSStatus ATSFontSetAutoActivationSettingForApplication ( ATSFontAutoActivationSetting iSetting, CFURLRef iApplicationFileURL );
A font auto-activation setting. See “Automatic Activation Settings.”
A valid file URL for an application. Pass NULL
to specify the current process.
Returns noErr
on success, and paramErr
for any invalid input. May return memFullErr
if unable to allocate temporary structures.
ATSFont.h
Sets a font state to enabled or disabled.
OSStatus ATSFontSetEnabled ( ATSFontRef iFont, ATSOptionFlags iOptions, Boolean iEnabled );
The font reference.
An options flag.
The state to set the font to. True
for enabled, false
for disabled.
kATSInvalidFontAccess
if the font reference is invalid in the current application context.
ATSFont.h
Sets the user's global auto-activation setting.
OSStatus ATSFontSetGlobalAutoActivationSetting ( ATSFontAutoActivationSetting iSetting );
A font auto-activation setting. See “Automatic Activation Settings.”
If successful, noErr
; if invalid input, paramErr
.
ATSFont.h
Obtains the generation of the font database.
ATSGeneration ATSGetGeneration ( void );
A value that specifies the generation count of the font database. See the description of the ATSGeneration
data type.
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
.
ATSFont.h
Disposes of a universal procedure pointer to a customized filter function used for fonts.
void DisposeFMFontCallbackFilterUPP ( FMFontCallbackFilterUPP userUPP );
See the callback FMFontCallbackFilterProcPtr
for more information.
ATSTypes.h
Disposes of a universal procedure pointer to a customized filter function used for font families.
void DisposeFMFontFamilyCallbackFilterUPP ( FMFontFamilyCallbackFilterUPP userUPP );
See the callback FMFontFamilyCallbackFilterProcPtr
for more information.
ATSTypes.h
Calls a customized filter function used for fonts.
OSStatus InvokeFMFontCallbackFilterUPP ( FMFont iFont, void *iRefCon, FMFontCallbackFilterUPP userUPP );
A result code. See “Apple Type Services for Fonts Result Codes.”
This function is not recommended nor needed, as the system invokes your filter for you.
ATSTypes.h
Calls a customized filter function used for font families.
OSStatus InvokeFMFontFamilyCallbackFilterUPP ( FMFontFamily iFontFamily, void *iRefCon, FMFontFamilyCallbackFilterUPP userUPP );
A result code. See “Apple Type Services for Fonts Result Codes.”
This function is not recommended nor needed, as the system invokes your filter for you.
ATSTypes.h
Creates a new universal procedure pointer (UPP) to a filter callback function that uses your criteria for filtering fonts.
FMFontCallbackFilterUPP NewFMFontCallbackFilterUPP ( FMFontCallbackFilterProcPtr userRoutine );
See the description of the FMFontCallbackFilterUPP
data type.
See the callback FMFontCallbackFilterProcPtr
for more information.
ATSTypes.h
Creates a new universal procedure pointer (UPP) to a filter callback function that uses your criteria for filtering font families.
FMFontFamilyCallbackFilterUPP NewFMFontFamilyCallbackFilterUPP ( FMFontFamilyCallbackFilterProcPtr userRoutine );
See the description of the FMFontFamilyCallbackFilterUPP
data type.
See the callback FMFontFamilyCallbackFilterProcPtr
for more information.
ATSTypes.h
The callbacks in this section are used by ATS for Fonts.
The callbacks in this section are used by the Font Manager.
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 );
A font reference. This is the font on which your callback operates.
An arbitrary 32-bit value specified by your application and that is passed to your callback.
A result code. See “Apple Type Services for Fonts Result Codes.”
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
.
ATSFont.h
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 );
A font family reference. This is the font family on which your callback operates.
An arbitrary 32-bit value specified by your application and that is passed to your callback.
A result code. See “Apple Type Services for Fonts Result Codes.”
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
.
ATSFont.h
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 );
An ATSFontQueryMessageID
value that identifies the message type your application receives from ATS. See “Font Query Message ID” for the constants you can supply.
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.
An arbitrary 32-bit value specified by your application and that is passed to your callback.
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
.
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
.
ATSFont.h
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 );
Reserved for future use. Currently, your callback is passed NULL
.
An arbitrary 32-bit value specified by your application and that is passed to your callback.
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
.
ATSFont.h
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 );
A font reference. This is the font on which your callback operates.
A pointer to arbitrary data that defines your custom filter.
A result code. See “Apple Type Services for Fonts Result Codes.”
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.
ATSTypes.h
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 );
A font family reference. This is the font family on which your callback operates.
A pointer to arbitrary data that defines your custom filter.
A result code. See “Apple Type Services for Fonts Result Codes.”
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.
ATSTypes.h
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.
typedef UInt32 ATSFontContainerRef;
A font container reference is an opaque type used as a parameter in the functions ATSFontActivateFromFileSpecification
and ATSFontActivateFromMemory
.
ATSTypes.h
An opaque data type that represents a font family iterator.
typedef struct ATSFontFamilyIterator_ * ATSFontFamilyIterator;
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.
ATSFont.h
An opaque data type that represents a font family reference.
typedef UInt32 ATSFontFamilyRef;
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.
ATSTypes.h
Contains font filter information.
struct ATSFontFilter { UInt32 version ATSFontFilterSelector filterSelector union { ATSGeneration generationFilter; ATSFontFamilyRef fontFamilyFilter; ATSFontFamilyApplierFunction fontFamilyApplierFunctionFilter; ATSFontApplierFunction fontApplierFunctionFilter; } filter; }; typedef struct ATSFontFilter ATSFontFilter;
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.
You can pass an ATSFontFilter
structure to the functions ATSFontFamilyIteratorCreate
, ATSFontFamilyIteratorReset
, ATSFontIteratorCreate
, and ATSFontIteratorReset
.
ATSFont.h
An opaque data type that represents a font iterator.
typedef struct ATSFontIterator_ * ATSFontIterator;
You initialize a structure of type ATSFontIterator
by calling the function ATSFontIteratorCreate
. You should not attempt to modify the contents of a font iterator.
ATSFont.h
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;
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.
This structure is passed as a parameter to the functions ATSFontGetHorizontalMetrics
and ATSFontGetVerticalMetrics
.
ATSTypes.h
An opaque data type that represents a font notification information structure.
typedef struct ATSFontNotificationInfoRef_ * ATSFontNotificationInfoRef;
This data type is used in the ATSNotificationCallback
callback function.
ATSFont.h
An opaque data type that represents a font notification structure.
typedef struct ATSFontNotificationRef_ * ATSFontNotificationRef;
The ATSFontNotificationRef
data type is returned by the function ATSFontNotificationSubscribe
and passed as a parameter to the function ATSFontNotificationUnsubscribe
.
ATSFont.h
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;
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
.
You pass a ATSFontQuerySourceContext
data structure to the function ATSCreateFontQueryRunLoopSource
.
ATSFont.h
An opaque data type that represents a font reference.
typedef UInt32 ATSFontRef;
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.
ATSTypes.h
Represents a font size.
typedef Float32 ATSFontSize;
ATSTypes.h
Represents a generation count.
typedef UInt32 ATSGeneration;
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
.
ATSTypes.h
Represents options you can pass to various ATS functions.
typedef OptionBits ATSOptionFlags;
There are a variety of options associated with this data type. See “Assorted Options,” “Scoping Options,” and “Iteration Precedence Options.”
ATSTypes.h
The data types in this section are used by the Font Manager.
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;
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.
You use the FMFilter
data structure when you want to restrict the enumeration and activation functions to the criteria specified by a filter.
ATSTypes.h
An opaque data type that specifies a font registered with the font database.
typedef UInt32 FMFont;
You should not modify this value.
ATSTypes.h
Defines a universal procedure pointer to a font filter callback.
typedef FMFontCallbackFilterProcPtr FMFontCallbackFilter;
For more information, see the description of the FMFontCallbackFilterProcPtr
callback function.
Contains font directory information used to restrict a font iteration.
struct FMFontDirectoryFilter { SInt16 fontFolderDomain; UInt32 reserved[2]; }; typedef struct FMFontDirectoryFilter FMFontDirectoryFilter;
fontFolderDomain
A signed 16-bit integer that specifies the directory to which you want to restrict the font iteration.
reserved
Reserved for future use.
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.
ATSTypes.h
A reference to a collection of fonts with the same design characteristics.
typedef SInt16 FMFontFamily;
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.
ATSTypes.h
Defines a universal procedure pointer to a font family filter callback.
typedef FMFontFamilyCallbackFilterProcPtr FMFontFamilyCallbackFilter;
For more information, see the description of the FMFontFamilyCallbackFilterProcPtr
callback function.
Contains a font family reference and a QuickDraw style.
struct FMFontFamilyInstance { FMFontFamily fontFamily; FMFontStyle fontStyle; }; typedef struct FMFontFamilyInstance FMFontFamilyInstance;
fontFamily
A font family reference.
fontStyle
A QuickDraw font style.
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.
ATSTypes.h
An opaque structure used to enumerate font family instances.
struct FMFontFamilyInstanceIterator { UInt32 reserved[16]; }; typedef struct FMFontFamilyInstanceIterator FMFontFamilyInstanceIterator;
reserved
Reserved for Apple’s use.
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.
ATSTypes.h
An opaque structure used to enumerate font families.
struct FMFontFamilyIterator { UInt32 reserved[16]; }; typedef struct FMFontFamilyIterator FMFontFamilyIterator;
reserved
Reserved for Apple’s use.
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.
ATSTypes.h
An opaque structure used to enumerate fonts.
struct FMFontIterator { UInt32 reserved[16]; }; typedef struct FMFontIterator FMFontIterator;
reserved
Reserved for Apple’s use.
You initialize a structure of type FMFontIterator
by calling the function FMCreateFontIterator
. You should not attempt to modify the contents of a font iterator.
ATSTypes.h
Represents a font size.
typedef SInt16 FMFontSize;
ATSTypes.h
Represents a font style.
typedef SInt16 FMFontStyle;
The low 8 bits of a Font Manager font style correspond to a QuickDraw style.
ATSTypes.h
Keeps track of any operation that adds, deletes, or modifies one or more fonts or font family objects.
typedef UInt32 FMGeneration;
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.
ATSTypes.h
The data types in this section are used by Apple Type Services for Unicode Imaging (ATSUI).
Represents a glyph code.
typedef UInt16 ATSGlyph;
Contains ideal (resolution-independent) metrics for a glyph.
struct ATSGlyphIdealMetrics { Float32Point advance; Float32Point sideBearing; Float32Point otherSideBearing; }; typedef struct ATSGlyphIdealMetrics ATSGlyphIdealMetrics;
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.
This data structure is passed as a parameter to the ATSUI function ATSUGlyphGetIdealMetrics
. For more information, see Inside Mac OS X: ATSUI Reference.
ATSTypes.h
Represents a glyph reference.
typedef UInt16 ATSGlyphRef;
This data type is used in the ATSUI data structure ATSLayoutRecord
. For information, see Inside Mac OS X: ATSUI Reference.
ATSTypes.h
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;
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.
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.
ATSTypes.h
Contains curve information for a glyph path.
struct ATSUCurvePath { UInt32 vectors; UInt32 controlBits[1]; Float32Point vector[1]; }; typedef struct ATSUCurvePath ATSUCurvePath;
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.
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.
ATSTypes.h
Contains curve information for an array of glyph paths.
struct ATSUCurvePaths { UInt32 contours; ATSUCurvePath contour[1]; }; typedef struct ATSUCurvePaths ATSUCurvePaths;
contours
The number of cubic curves contained in the contour
array.
contour
An array of cubic curves that define the outline of a glyph.
The ATSUCurvePaths
data structure is passed as a parameter to the ATSUI function ATSUGlyphGetCurvePaths
. For more information, see Inside Mac OS X: ATSUI Reference.
ATSTypes.h
Represents a reference to a glyph.
typedef ATSGlyphRef GlyphID;
The GlyphID
data type is used by ATSUI. For more information, see Inside Mac OS X: ATSUI Reference.
ATSTypes.h
Specify assorted options.
enum { kATSOptionFlagsDefault = kNilOptions, kATSOptionFlagsComposeFontPostScriptName = 1 << 0, kATSOptionFlagsUseDataForkAsResourceFork = 1 << 8, kATSOptionFlagsUseResourceFork = 2 << 8, kATSOptionFlagsUseDataFork = 3 << 8 };
kATSOptionFlagsDefault
Specifies to use the default setting.
Available in Mac OS X v10.0 and later.
Declared in ATSFont.h
.
kATSOptionFlagsComposeFontPostScriptName
Specifies the composed PostScript name of a font.
Available in Mac 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 Mac OS X v10.0 and later.
Declared in ATSFont.h
.
kATSOptionFlagsUseResourceFork
Specifies to use the resource fork of a font.
Available in Mac OS X v10.0 and later.
Declared in ATSFont.h
.
kATSOptionFlagsUseDataFork
Specifies to use the data fork of a font.
Available in Mac OS X v10.0 and later.
Declared in ATSFont.h
.
Values for automatic activation settings.
enum { kATSFontAutoActivationDefault = 0, kATSFontAutoActivationDisabled = 1, kATSFontAutoActivationEnabled = 2, kATSFontAutoActivationAsk = 4 } typedef UInt32 ATSFontAutoActivationSetting;
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 Mac OS X v10.5 and later.
Declared in ATSFont.h
.
kATSFontAutoActivationAsk
Asks the user before automatically activating fonts requested by the application.
Available in Mac OS X v10.5 and later.
Declared in ATSFont.h
.
kATSFontAutoActivationEnabled
Enables automatic activation of fonts.
Available in Mac OS X v10.5 and later.
Declared in ATSFont.h
.
kATSFontAutoActivationDisabled
Disables automatic activation of fonts.
Available in Mac OS X v10.5 and later.
Declared in ATSFont.h
.
ATSFont.h
Specify a context to use when enumerating, activating, or deactivating fonts and font families.
typedef UInt32 ATSFontContext; enum { kATSFontContextUnspecified = 0, kATSFontContextGlobal = 1, kATSFontContextLocal = 2 };
kATSFontContextUnspecified
Indicates a context is not specified. This
option has the same result as providing the option kATSFontContextLocal
.
Available in Mac 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 Mac 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 Mac OS X v10.1 and later.
Declared in ATSFont.h
.
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
.
Indicate data that is not specified.
enum { kATSGenerationUnspecified = 0, kATSFontContainerRefUnspecified = 0, kATSFontFamilyRefUnspecified = 0, kATSFontRefUnspecified = 0 };
kATSGenerationUnspecified
Indicates the generation is not specified.
Available in Mac OS X v10.0 and later.
Declared in ATSTypes.h
.
kATSFontContainerRefUnspecified
Indicates the font container reference is not specified.
Available in Mac OS X v10.0 and later.
Declared in ATSTypes.h
.
kATSFontFamilyRefUnspecified
Indicates the font family reference is not specified.
Available in Mac OS X v10.0 and later.
Declared in ATSTypes.h
.
kATSFontRefUnspecified
Indicates the font reference is not specified.
Available in Mac OS X v10.0 and later.
Declared in ATSTypes.h
.
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.
enum ATSFontFilterSelector { kATSFontFilterSelectorUnspecified = 0, kATSFontFilterSelectorGeneration = 3, kATSFontFilterSelectorFontFamily = 7, kATSFontFilterSelectorFontFamilyApplierFunction = 8, kATSFontFilterSelectorFontApplierFunction = 9 }; typedef enum ATSFontFilterSelector ATSFontFilterSelector;
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 Mac OS X v10.0 and later.
Declared in ATSFont.h
.
kATSFontFilterSelectorGeneration
Specifies to limit an iteration based on generation criteria.
Available in Mac OS X v10.0 and later.
Declared in ATSFont.h
.
kATSFontFilterSelectorFontFamily
Specifies to limit an iteration based on font family criteria.
Available in Mac 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 Mac 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 Mac OS X v10.0 and later.
Declared in ATSFont.h
.
You use these constants in the data structure ATSFontFilter
to specify the type of
data in the filter
union.
Specify the version of a font filter.
typedef UInt32 ATSFontFormat; enum { kATSFontFilterCurrentVersion = 0 };
kATSFontFilterCurrentVersion
Specifies to use the current version of a font filter.
Available in Mac OS X v10.0 and later.
Declared in ATSFont.h
.
There is currently only one constant in this enumeration.
You can assign this constant to the version
field
in the ATSFontFilter
data
structure.
Specify a font format.
enum { kATSFontFormatUnspecified = 0 };
kATSFontFormatUnspecified
Indicates the font format is not specified.
You can pass this in the iFormat
parameter
of the function ATSFontActivateFromFileSpecification
.
Available in Mac OS X v10.0 and later.
Declared in ATSTypes.h
.
There are no other font formats currently defined for this enumeration.
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")
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 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.
enum ATSFontQueryMessageID { kATSQueryActivateFontMessage = 'atsa' }; typedef enum ATSFontQueryMessageID ATSFontQueryMessageID;
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 Mac OS X v10.2 and later.
Declared in ATSFont.h
.
There is currently only one constant in this enumeration.
You use a constant of this type when you create an ATSFontQueryCallback
callback
function.
Specify the order of an iteration.
enum { kATSOptionFlagsIterateByPrecedenceMask = 0x00000001 << 5 };
kATSOptionFlagsIterateByPrecedenceMask
Specifies to iterate fonts in the order dictated by a precedence mask.
Available in Mac OS X v10.1 and later.
Declared in ATSFont.h
.
Specify a notification action.
enum ATSFontNotifyAction { kATSFontNotifyActionFontsChanged = 1, kATSFontNotifyActionDirectoriesChanged = 2 }; typedef enum ATSFontNotifyAction ATSFontNotifyAction;
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 Mac 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 Mac OS X v10.2 and later.
Declared in ATSFont.h
.
You can use these options with the function ATSFontNotify
.
Specify when ATS should notify your application of changes in the font database.
enum ATSFontNotifyOption { kATSFontNotifyOptionDefault = 0, kATSFontNotifyOptionReceiveWhileSuspended = 1L << 0 }; typedef enum ATSFontNotifyOption ATSFontNotifyOption;
kATSFontNotifyOptionDefault
Specifies to use the default behavior of the
function ATSFontNotificationSubscribe
.
Available in Mac 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 Mac OS X v10.2 and later.
Declared in ATSFont.h
.
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.
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 };
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 Mac OS X v10.2 and later.
Declared in ATSFont.h
.
kATSOptionFlagsIterationScopeMask
Specifies mask option bits 12-14 for iteration scopes.
Available in Mac 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 Mac 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 Mac 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 Mac 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 Mac OS X v10.2 and later.
Declared in ATSFont.h
.
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.
Specifies a filter format.
enum { kFMCurrentFilterFormat = 0 };
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 Mac OS X v10.0 and later.
Declared in ATSTypes.h
.
Specifies a filter type.
typedef UInt32 FMFilterSelector; enum { kFMFontTechnologyFilterSelector = 1, kFMFontContainerFilterSelector = 2, kFMGenerationFilterSelector = 3, kFMFontFamilyCallbackFilterSelector = 4, kFMFontCallbackFilterSelector = 5, kFMFontDirectoryFilterSelector = 6 };
kFMFontTechnologyFilterSelector
Selects font technology filter. You can use this filter only with a font iterator.
Available in Mac 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 Mac 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 Mac 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 Mac 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 Mac OS X v10.0 and later.
Declared in ATSTypes.h
.
You use these constants to specify a filter type in the FMFilter
data structure
used by many Font Manager functions.
Specify a font technology.
enum { kFMTrueTypeFontTechnology = 'true', kFMPostScriptFontTechnology = 'typ1' };
kFMTrueTypeFontTechnology
Indicates True Type font technology.
Available in Mac OS X v10.0 and later.
Declared in ATSTypes.h
.
kFMPostScriptFontTechnology
Indicates Post Script font technology.
Available in Mac OS X v10.0 and later.
Declared in ATSTypes.h
.
Specify an invalid value.
enum { kInvalidGeneration = 0, kInvalidFontFamily = -1, kInvalidFont = 0 };
kInvalidGeneration
Indicates an invalid generation value.
Available in Mac OS X v10.0 and later.
Declared in ATSTypes.h
.
kInvalidFontFamily
Indicates the font family reference is invalid.
Available in Mac OS X v10.0 and later.
Declared in ATSTypes.h
.
kInvalidFont
Indicates the font reference is invalid.
Available in Mac OS X v10.0 and later.
Declared in ATSTypes.h
.
The kInvalidGeneration
, kInvalidFontFamily
,
and kInvalidFont
constants
may be used to indicate invalid values for generation count, font
family, and font data types.
Represent numerical values that are commonly used in font calculations.
enum { kATSItalicQDSkew = (1 << 16) / 4, kATSBoldQDStretch = (1 << 16) * 3 / 2, kATSRadiansFactor = 1144 };
kATSItalicQDSkew
A Fixed
value
of 0.25
that represents
the skew used by QuickDraw to draw italicized glyphs.
Available in Mac 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 Mac 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 Mac OS X v10.0 and later.
Declared in ATSTypes.h
.
These constants are provided for convenience. Your application can use them when it needs to perform font calculations.
Available beginning with ATSUI 1.0.
Specify a curve type used to draw a font.
typedef UInt16 ATSCurveType; enum { kATSCubicCurveType = 0x0001, kATSQuadCurveType = 0x0002, kATSOtherCurveType = 0x0003 };
kATSCubicCurveType
Specifies a cubic curve.
Available in Mac OS X v10.0 and later.
Declared in ATSTypes.h
.
kATSQuadCurveType
Specifies a quadratic curve.
Available in Mac OS X v10.0 and later.
Declared in ATSTypes.h
.
kATSOtherCurveType
Specifies a curve other than cubic or quadratic.
Available in Mac OS X v10.0 and later.
Declared in ATSTypes.h
.
These are used in the ATSUI function ATSUGetNativeCurveType
.
See Inside Mac OS X: ATSUI Reference for more
information.
Specifies that a glyph is deleted.
enum { kATSDeletedGlyphcode = 0xFFFF };
kATSDeletedGlyphcode
Indicates that a glyph is deleted. That is, the glyph is set to no longer appear in a text layout.
Available in Mac OS X v10.2 and later.
Declared in ATSTypes.h
.
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.
The most common result codes returned by Apple Type Services for Fonts are listed below.
© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-12-11)