ADC Home > Reference Library > Reference > Carbon > Text & Fonts > Font Manager Reference >

< Previous PageNext Page > Hide TOC

Deprecated Font Manager Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.4

FetchFontInfo

Obtains the information for a specific font. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr FetchFontInfo (
   SInt16 fontID,
   SInt16 fontSize,
   SInt16 fontStyle,
   FontInfo *info
);

Parameters
fontID

A signed, 16-bit integer that specifies the font ID of the font whose information you want to obtain.

fontSize

A signed, 16-bit integer that specifies the font size of the font whose information you want to obtain.

fontStyle

A signed, 16-bit integer that specifies the font style of the font whose information you want to obtain.

info

On output, points to a font information structure that contains measurement information (ascent, descent, width, and leading) for the specified font.

Return Value

A result code. See “Font Manager Result Codes.”

Availability
Declared In
Fonts.h

FMActivateFonts

Activates one or more fonts. (Deprecated in Mac OS X v10.4. Use ATSFontActivateFromFileReference instead.)

OSStatus FMActivateFonts (
   const FSSpec *iFontContainer,
   const FMFilter *iFilter,
   void *iRefCon,
   OptionBits iOptions
);

Parameters
iFontContainer

A pointer to the file specification of the file that contains the font data you want to activate. You can specify a directory or an individual font file.

iFilter

A pointer to a filter specification. This parameter is currently reserved for future use, so you should pass NULL.

iRefCon

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

iOptions

A value that specifies the scope to which the function applies. If you want the Font Manager to make the fonts visible only to your application, use the constant kFMLocalActivationContext. If you want the Font Manager to make fonts visible to all applications installed on the system, use the constant kFMGlobalActivationContext. See Activation Contexts for more information on these constants.

Return Value

A result code. See “Font Manager Result Codes.”

Availability
Declared In
Fonts.h

FMCreateFontFamilyInstanceIterator

Creates a font family instance iterator that your application can use to access the member fonts associated with a font family. (Deprecated in Mac OS X v10.4.)

OSStatus FMCreateFontFamilyInstanceIterator (
   FMFontFamily iFontFamily,
   FMFontFamilyInstanceIterator *ioIterator
);

Parameters
iFontFamily

A reference to the font family you want to access.

ioIterator

A pointer to a structure of type FMFontFamilyInstanceIterator. On input, pass a pointer to an uninitialized structure. On output, its contents may have been changed and may include references to other data structures allocated by the system to maintain the structure’s state. The iterator is positioned before the first member font of the font family. When you no longer need the font family instance iterator, you should call the function FMDisposeFontFamilyInstanceIterator to release the auxiliary data and memory allocated by the system.

Return Value

A result code. See “Font Manager Result Codes.”

Discussion

A font family instance iterator is an opaque data structure used by the Font Manager to keep track of an iteration over currently active font family instances. A font family instance is a typeface and a size—an entry from the font association table.

When the font family iterator is initialized, it does not yet reference a font family instance. Do not attempt to modify the contents of a font family instance iterator.

Availability
Declared In
Fonts.h

FMCreateFontFamilyIterator

Creates a font family iterator that your application can use to access font family objects. (Deprecated in Mac OS X v10.4. Use ATSFontFamilyIteratorCreate instead.)

OSStatus FMCreateFontFamilyIterator (
   const FMFilter *iFilter,
   void *iRefCon,
   OptionBits iOptions,
   FMFontFamilyIterator *ioIterator
);

Parameters
iFilter

A pointer to a filter specification. Pass NULL if you want to access all font family objects within the scope of your iteration. Otherwise, you can use this parameter to restrict the scope of 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 kFMGenerationFilterSelector to select a generation filter or the constant kFMFontFamilyCallbackFilterSelector to select a custom filter. See FMFilterSelector in the ATS Types Reference for more information on these constants.

iRefCon

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

iOptions

A value that specifies the scope to which the font family iterator applies. If you want the Font Manager to apply the font family iterator only to the fonts accessible from your application use the kFMLocalIterationScope constant. If you want the Font Manager to apply the font family iterator to all fonts registered with the system use the constant kFMGlobalIterationScope. See Activation Contexts for more information on these constants.

ioIterator

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

Return Value

A result code. See “Font Manager Result Codes.”

Discussion

A font family iterator is an opaque data structure used by the Font Manager 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. Do not attempt to modify the contents of a font family iterator.

Availability
Declared In
Fonts.h

FMCreateFontIterator

Creates an iterator that your application can use to access fonts. (Deprecated in Mac OS X v10.4. Use ATSFontIteratorCreate instead.)

OSStatus FMCreateFontIterator (
   const FMFilter *iFilter,
   void *iRefCon,
   OptionBits iOptions,
   FMFontIterator *ioIterator
);

Parameters
iFilter

A pointer to font filter specification. Pass NULL if you want to access all font objects within the scope of your iteration. Otherwise, you can use this parameter to restrict the scope of the iteration to font information that matches a technology, font container, or criteria you specify in a custom filter function. Pass the filter selector constant kFMFontTechnologyFilterSelector to select a font technology filter, the constant kFMFontContainerFilterSelector to select a font container filter, or the constant kFMFontCallbackFilterSelector to select a custom filter. See FMFilterSelector in the ATS Types Reference for more information on these constants.

iRefCon

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

iOptions

A value that specifies the scope to which the font iterator applies. If you want the Font Manager to apply the font iterator only to the fonts accessible from your application use the kFMLocalIterationScope constant. If you want the Font Manager to apply the font iterator to all fonts registered with the system use the constants kFMGlobalIterationScope. See Activation Contexts for more information on these constants.

ioIterator

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

Return Value

A result code. See “Font Manager Result Codes.”

Discussion

A font iterator is an opaque structure used by the Font Manager to maintain font information in the context of the current application process. When the font iterator is initialized, it is not yet positioned on a font object. You should not attempt to modify the contents of a font iterator.

Availability
Declared In
Fonts.h

FMDeactivateFonts

Deactivates one or more fonts. (Deprecated in Mac OS X v10.4. Use ATSFontDeactivate instead.)

OSStatus FMDeactivateFonts (
   const FSSpec *iFontContainer,
   const FMFilter *iFilter,
   void *iRefCon,
   OptionBits iOptions
);

Parameters
iFontContainer

A pointer to the file specification of the file that contains the font data you want to deactivate. You can specify a directory or an individual font file.

iFilter

A pointer to a filter specification. This parameter is currently reserved for future use, so you should pass NULL.

iRefCon

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

iOptions

A value that specifies the scope to which the function applies. This parameter is currently reserved for future use, so you should pass NULL.

Return Value

A result code. See “Font Manager Result Codes.”

Availability
Declared In
Fonts.h

FMDisposeFontFamilyInstanceIterator

Disposes of a font family instance iterator. (Deprecated in Mac OS X v10.4.)

OSStatus FMDisposeFontFamilyInstanceIterator (
   FMFontFamilyInstanceIterator *ioIterator
);

Parameters
ioIterator

A pointer to a font family instance iterator you created with the function FMCreateFontFamilyInstanceIterator. If you try to use the font family instance iterator after disposing of its contents through this function, the Font Manager returns an error code to your application.

Return Value

A result code. See “Font Manager Result Codes.”

Availability
Declared In
Fonts.h

FMDisposeFontFamilyIterator

Disposes of the contents of a font family iterator. (Deprecated in Mac OS X v10.4. Use ATSFontFamilyIteratorRelease instead.)

OSStatus FMDisposeFontFamilyIterator (
   FMFontFamilyIterator *ioIterator
);

Parameters
ioIterator

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

Return Value

A result code. See “Font Manager Result Codes.”

Availability
Declared In
Fonts.h

FMDisposeFontIterator

Disposes of a font iterator. (Deprecated in Mac OS X v10.4. Use ATSFontIteratorRelease instead.)

OSStatus FMDisposeFontIterator (
   FMFontIterator *ioIterator
);

Parameters
ioIterator

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

Return Value

A result code. See “Font Manager Result Codes.”

Availability
Declared In
Fonts.h

FMGetATSFontFamilyRefFromFontFamily

Obtains the ATS font family reference associated with a font family object. (Deprecated in Mac OS X v10.4.)

ATSFontFamilyRef FMGetATSFontFamilyRefFromFontFamily (
   FMFontFamily iFamily
);

Parameters
iFamily

A font family reference.

Return Value

The ATSFontFamilyRef associated with the font family object.

Availability
Declared In
Fonts.h

FMGetFontContainer

Obtains the file that contains data for a font. (Deprecated in Mac OS X v10.4. Use ATSFontGetContainer instead.)

OSStatus FMGetFontContainer (
   FMFont iFont,
   FSSpec *oFontContainer
);

Parameters
iFont

A font reference.

oFontContainer

On output, a pointer to the file specification of the file that contains the font data.

Return Value

A result code. See “Font Manager Result Codes.”

Discussion

You can pass the file specification returned by this function to the Resource Manager or File Manager to obtain the actual font data. However, if the font is an LWFN-class font, the outline data is located in a separate file from the font suitcase. The function FMGetFontContainer obtains the font suitcase. Your application is responsible for finding the individual outline files.

Availability
Declared In
Fonts.h

FMGetFontContainerFromFontFamilyInstance

Obtains the font container associated with a font family instance. (Deprecated in Mac OS X v10.4. Use ATSFontGetContainer instead.)

OSStatus FMGetFontContainerFromFontFamilyInstance (
   FMFontFamily iFontFamily,
   FMFontStyle iStyle,
   FMFontSize iFontSize,
   FSSpec *oFontContainer
);

Parameters
iFontFamily

A font family reference for the font family whose container you want to obtain. You must pass a valid font family.

iStyle

The font style of the font family whose container you want to obtain. You must pass a valid font style.

iFontSize

The font size of the font family whose container you want to obtain. You must pass a valid font size.

oFontContainer

On output, a pointer to a file specification that specifies the name and location of the font container.

Return Value

A result code. See “Font Manager Result Codes.”

Availability
Declared In
Fonts.h

FMGetFontFamilyFromATSFontFamilyRef

Obtains the font family associated with an ATS font family reference. (Deprecated in Mac OS X v10.4.)

FMFontFamily FMGetFontFamilyFromATSFontFamilyRef (
   ATSFontFamilyRef iFamily
);

Parameters
iFamily

An ATS font family reference.

Return Value

The font family reference associated with the specified ATS font family reference.

Availability
Declared In
Fonts.h

FMGetFontFamilyFromName

Returns the font family reference associated with a standard QuickDraw name. (Deprecated in Mac OS X v10.4. Use ATSFontFamilyFindFromName instead.)

FMFontFamily FMGetFontFamilyFromName (
   ConstStr255Param iName
);

Parameters
iName

A QuickDraw font family name.

Return Value

A font family reference. The function returns kInvalidFontFamily if it cannot find a matching font family. See the ATS Types documentation for a description of the FMFontFamily data type.

Discussion

This function is a replacement for the GetFNum function. You should use the function FMGetFontFamilyFromName instead of the function GetFNum to assure your application supports font formats other than the resource fork TrueType and PostScript Type 1 fonts.

Availability
Declared In
Fonts.h

FMGetFontFamilyGeneration

Obtains the generation count of a font family. (Deprecated in Mac OS X v10.4. Use ATSFontFamilyGetGeneration instead.)

OSStatus FMGetFontFamilyGeneration (
   FMFontFamily iFontFamily,
   FMGeneration *oGeneration
);

Parameters
iFontFamily

A font family reference.

oGeneration

On output, a pointer to the generation count for the font family associated with the font family reference.

Return Value

A result code. See “Font Manager Result Codes.”

Availability
Declared In
Fonts.h

FMGetFontFamilyInstanceFromFont

Finds the font family reference and standard QuickDraw style associated with a font. (Deprecated in Mac OS X v10.4.)

OSStatus FMGetFontFamilyInstanceFromFont (
   FMFont iFont,
   FMFontFamily *oFontFamily,
   FMFontStyle *oStyle
);

Parameters
iFont

A font reference.

oFontFamily

A pointer to a font family reference. On output, points to the font family reference associated with the specified font. You are responsible for allocating the memory for the font family reference.

oStyle

A pointer to a font style. On output, points to the font style associated with the specified font. You are responsible for allocating the memory for the font style.

Return Value

A result code. See “Font Manager Result Codes.”

Discussion

A font can be a member of more than one font family. This means if you call the function FMGetFontFromFontFamilyInstance and then call the function FMGetFontFamilyInstanceFromFont, you will not necessarily get the font family reference you supplied when you called FMGetFontFromFontFamilyInstance.

Availability
Declared In
Fonts.h

FMGetFontFamilyName

Obtains the font family name associated with a font family reference. (Deprecated in Mac OS X v10.4. Use ATSFontFamilyGetName instead.)

OSStatus FMGetFontFamilyName (
   FMFontFamily iFontFamily,
   Str255 oName
);

Parameters
iFontFamily

A font family reference.

oName

On output, the string contains the QuickDraw font family name. If the function does not find a name, it returns an empty string and a result code of kFMInvalidFontFamilyErr.

Return Value

A result code. See “Font Manager Result Codes.”

Discussion

This function is a replacement for the GetFontName function. You should use the function FMGetFontFamilyName instead of the function GetFontName to assure your application supports font formats other than the resource fork TrueType and PostScript Type 1 fonts.

Availability
Declared In
Fonts.h

FMGetFontFamilyResource

Obtains the font family resource for a font family. (Deprecated in Mac OS X v10.4. Use ATSFontGetFontFamilyResource instead.)

OSStatus FMGetFontFamilyResource (
   FMFontFamily iFontFamily,
   FMFontStyle iFontStyle,
   FMFontSize iFontSize,
   ByteCount iBufferSize,
   void *ioBuffer,
   ByteCount *oSize
);

Parameters
iFontFamily

A value of type FMFontFamily that specifies the font family whose resource you want to obtain. You must pass a valid font family.

iFontStyle

A value of type FMFontStyle that specifies the font style of the font family whose resource you want to obtain. You must pass a valid font style.

iFontSize

A value of type FMFontSize that specifies the font size of the font family whose resource you want to obtain. You must pass a valid font size.

iBufferSize

The size of the buffer (ioBuffer).

ioBuffer

A pointer to the buffer used to store a copy of the font family resource. On input, pass NULL if you want to obtain only the length of the font family resource, not its contents.

oSize

On output, the actual size of the buffer.

Return Value

A result code. See “Font Manager Result Codes.”

Discussion

You should call the function FMGetFontFamilyResource twice. First, to get the length of the font family resource. Then after you allocate a buffer (ioBuffer) of the appropriate size, call the function a second time to obtain the contents of the font family resource.

Availability
Declared In
Fonts.h

FMGetFontFamilyTextEncoding

Obtains the text encoding used by a font family. (Deprecated in Mac OS X v10.4. Use ATSFontFamilyGetEncoding instead.)

OSStatus FMGetFontFamilyTextEncoding (
   FMFontFamily iFontFamily,
   TextEncoding *oTextEncoding
);

Parameters
iFontFamily

A font family reference.

oTextEncoding

On output, a pointer to the text encoding used by the font family associated with the font family reference.

Return Value

A result code. See “Font Manager Result Codes.”

Discussion

This function is a replacement for the Script Manager function FontToScript. You should use the function FMGetFontFamilyTextEncoding instead of the function FontToScript to ensure your application supports font formats other than the resource fork TrueType and PostScript Type 1 fonts. Unlike the FontToScript function, the state of the font force flag is ignored and the script system of the font family is not mapped to zero even if the script system is disabled in the current application process.

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

status = FMGetFontFamilyTextEncoding (myFontFamily, &myTextEncoding)

status = RevertTextEncodingToScriptInfo (myTextEncoding, &myScriptCode);

Availability
Declared In
Fonts.h

FMGetFontFormat

Obtains the format identifier of a font. (Deprecated in Mac OS X v10.4.)

OSStatus FMGetFontFormat (
   FMFont iFont,
   FourCharCode *oFormat
);

Parameters
iFont

A font reference.

oFormat

On output, a pointer to a four-character-code that represents the format identifier of the font. See the discussion that follows for information on format identifiers.

Return Value

A result code. See “Font Manager Result Codes.”

Discussion

A format identifier is a four-character-code, assigned to a font by a font vendor, that identifies the format of a font. Some of the identifiers currently supported in the Mac OS are:

Availability
Declared In
Fonts.h

FMGetFontFromFontFamilyInstance

Obtains the font reference associated with a standard QuickDraw style and font family. (Deprecated in Mac OS X v10.4. Use CTFontCreateWithQuickdrawInstance instead.)

OSStatus FMGetFontFromFontFamilyInstance (
   FMFontFamily iFontFamily,
   FMFontStyle iStyle,
   FMFont *oFont,
   FMFontStyle *oIntrinsicStyle
);

Parameters
iFontFamily

A font family reference.

iStyle

A font style.

oFont

A pointer to a font reference. On output, points to the font reference for the specified font family and style. You are responsible for allocating the memory for the font reference.

oIntrinsicStyle

On output, a pointer to an intrinsic font style. If a font object isn’t found that matches the font family reference and font style you specify, the function returns the QuickDraw style that matches most closely.

Return Value

A result code. See “Font Manager Result Codes.” If a font reference and intrinsic style are not found, the function returns a value of kFMInvalidFontErr.

Availability
Declared In
Fonts.h

FMGetFontGeneration

Obtains the generation count of a font. (Deprecated in Mac OS X v10.4. Use ATSFontGetGeneration instead.)

OSStatus FMGetFontGeneration (
   FMFont iFont,
   FMGeneration *oGeneration
);

Parameters
iFont

A font reference.

oGeneration

On output, a pointer to a value that specifies the generation count of the font.

Return Value

A result code. See “Font Manager Result Codes.”

Availability
Declared In
Fonts.h

FMGetFontTable

Retrieves all or part of a data table for a font. (Deprecated in Mac OS X v10.4. Use ATSFontGetTable or CTFontCopyTable instead.)

OSStatus FMGetFontTable (
   FMFont iFont,
   FourCharCode iTag,
   ByteOffset iOffset,
   ByteCount iLength,
   void *iBuffer,
   ByteCount *oActualLength
);

Parameters
iFont

A font reference.

iTag

A tag that identifies the data table for a font.

iOffset

An offset to font table data you want to retrieve. The offset is relative to the beginning of the data table and is zero-based.

iLength

The size of the data buffer (ioBuffer) you allocate.

iBuffer

A pointer to the buffer used to store a copy of the font table. On input, pass NULL if you want to obtain only the length of the table, not its contents.

oActualLength

On output, the actual length of the font table.

Return Value

A result code. See “Font Manager Result Codes.”

Discussion

You should call the function FMGetFontTable twice. First, call it to retrieve the length of the font table. Then, after you’ve allocated space for the iBuffer parameter, call the function a second time to obtain the contents of the font table.

Availability
Declared In
Fonts.h

FMGetFontTableDirectory

Obtains the table directory for a font. (Deprecated in Mac OS X v10.4.)

OSStatus FMGetFontTableDirectory (
   FMFont iFont,
   ByteCount iLength,
   void *iBuffer,
   ByteCount *oActualLength
);

Parameters
iFont

A font reference.

iLength

The number of bytes in the buffer used to store a copy of the font table directory associated with the font.

iBuffer

A pointer to the buffer used to store a copy of the font table directory. On input, pass NULL if you want to obtain only the length of the table directory, not its contents.

oActualLength

On output, the length of the font table directory.

Return Value

A result code. See “Font Manager Result Codes.”

Discussion

You should call the function FMGetFontTableDirectory twice. First, call it to retrieve the length of the font table directory. Then, after you’ve allocated space for the iBuffer parameter, call the function a second time to obtain the contents of the table directory.

Availability
Declared In
Fonts.h

FMGetNextFont

Obtains the next font reference. (Deprecated in Mac OS X v10.4. Use ATSFontIteratorNext instead.)

OSStatus FMGetNextFont (
   FMFontIterator *ioIterator,
   FMFont *oFont
);

Parameters
ioIterator

A pointer to a font iterator you created using the function FMCreateFontIterator.

oFont

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

Return Value

A result code. See “Font Manager Result Codes.” If there are no more font objects to get, the function FMGetNextFont returns the result code kFMIterationCompleted.

Availability
Declared In
Fonts.h

FMGetNextFontFamily

Obtains the next font family reference. (Deprecated in Mac OS X v10.4. Use ATSFontFamilyIteratorNext instead.)

OSStatus FMGetNextFontFamily (
   FMFontFamilyIterator *ioIterator,
   FMFontFamily *oFontFamily
);

Parameters
ioIterator

A pointer to a font family iterator you created using the function FMCreateFontFamilyIterator.

oFontFamily

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

Return Value

A result code. See “Font Manager Result Codes.” If there are no more font family references to get, the function FMGetNextFontFamily returns the result code kFMIterationCompleted.

Discussion

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

Availability
Declared In
Fonts.h

FMGetNextFontFamilyInstance

Obtains the next instance associated with a font family reference. (Deprecated in Mac OS X v10.4.)

OSStatus FMGetNextFontFamilyInstance (
   FMFontFamilyInstanceIterator *ioIterator,
   FMFont *oFont,
   FMFontStyle *oStyle,
   FMFontSize *oSize
);

Parameters
ioIterator

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

oFont

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

oStyle

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

oSize

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

Return Value

A result code. See “Font Manager Result Codes.” If there is no more font family information to retrieve, the function FMGetNextFontFamlyInstance returns the status code kFMIterationCompleted.

Discussion

Instances are not necessarily retrieved in the order they are listed in a Font Association Table.

If any changes are made to the font database while your application is using the font family instance iterator, the iterator is invalidated and the function FMGetNextFontFamilyInstance returns the error kFMIteratorScopeModified. To remedy this error, your application must either call the FMResetFontFamilyInstanceIterator or the FMDisposeFontFamilyInstanceIterator functions.

Availability
Declared In
Fonts.h

FMResetFontFamilyInstanceIterator

Resets the a font family instance iterator to the beginning of the iteration for the specified font family. (Deprecated in Mac OS X v10.4.)

OSStatus FMResetFontFamilyInstanceIterator (
   FMFontFamily iFontFamily,
   FMFontFamilyInstanceIterator *ioIterator
);

Parameters
iFontFamily

A font family reference.

ioIterator

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

Return Value

A result code. See “Font Manager Result Codes.”

Discussion

Once you have created a font family instance iterator, you can reuse it by calling the function FMResetFontFamilyInstanceIterator. This function sets the iFontFamily parameter to the new font family object you specify, and repositions the iterator so it is ready to get the first font family instance when you call the function FMGetNextFontFamilyInstance.

Availability
Declared In
Fonts.h

FMResetFontFamilyIterator

Resets a font family iterator to the beginning of the iteration. (Deprecated in Mac OS X v10.4. Use ATSFontFamilyIteratorReset instead.)

OSStatus FMResetFontFamilyIterator (
   const FMFilter *iFilter,
   void *iRefCon,
   OptionBits iOptions,
   FMFontFamilyIterator *ioIterator
);

Parameters
iFilter

A pointer to a filter specification. Pass NULL if you want to access all font family objects within the scope of your iteration. Otherwise, you can use this parameter to restrict the scope of the iteration to the font families that match a generation count or criteria you specify in a custom filter function.

iRefCon

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

iOptions

A value that specifies the scope to which the font family iterator applies. If you want the Font Manager to apply the font family iterator only to the fonts accessible from your application use the kFMLocalIterationScope constant. If you want the Font Manager to apply the font family iterator to all fonts registered with the system use the constant kFMGlobalIterationScope.

i0Iterator

A pointer to a font family iterator you created with the function FMCreateFontFamilyIterator. On output, the font family iterator is reset.

Return Value

A result code. See “Font Manager Result Codes.”

Discussion

Once you have created a font family iterator, you can reuse it by calling the function FMResetFontFamilyIterator. 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 FMGetNextFontFamily.

Availability
Declared In
Fonts.h

FMResetFontIterator

Resets a font iterator to the beginning of the iteration. (Deprecated in Mac OS X v10.4. Use ATSFontIteratorReset instead.)

OSStatus FMResetFontIterator (
   const FMFilter *iFilter,
   void *iRefCon,
   OptionBits iOptions,
   FMFontIterator *ioIterator
);

Parameters
iFilter

A pointer to font filter specification. Pass NULL if you want to access all font objects within the scope of your iteration. Otherwise, you can use this parameter to restrict the scope of the iteration to font information that matches a technology, font container, or criteria you specify in a custom filter function. Pass the filter selector constant kFMFontTechnologyFilterSelector to select a font technology filter, the constant kFMFontContainerFilterSelector to select a font container filter, or the constant kFMFontCallbackFilterSelector to select a custom filter. See FMFilterSelector in the ATS Types Reference for more information on these constants.

iRefCon

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

iOptions

A value that specifies the scope to which the font iterator applies. If you want the Font Manager to apply the font iterator only to the fonts accessible from your application use the kFMLocalIterationScope constant. If you want the Font Manager to apply the font iterator to all fonts registered with the system use the constant kFMGlobalIterationScope.

ioIterator

A pointer to a font iterator you created with the function FMCreateFontIterator. On output, the font iterator is not positioned on a font object, and any information about font objects that were returned previously in the font iterator is no longer available.

Return Value

A result code. See “Font Manager Result Codes.”

Discussion

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

Availability
Declared In
Fonts.h

FMSwapFont

Returns a pointer to the font output structure for a specified font. (Deprecated in Mac OS X v10.4. There is no replacement function.)

FMOutPtr FMSwapFont (
   const FMInput *inRec
);

Parameters
inRec

A pointer to the font input structure for which you want to obtain font output information. A font input structure contains the font family ID, the style requested, scaling factors, and other information that specifies the characteristics of the font that is requested.

Return Value

A pointer to a font output structure (FMOutput). The font output structure contains a handle to the font resource for the specified input font, along with information about the font, such as the ascent, descent, and leading measurements.

Discussion

The function FMSwapFont is typically called by QuickDraw and other parts of the system software to access font handles. QuickDraw calls the FMSwapFont function every time a QuickDraw text function is used.

In most cases you don’t need to call this function. If you want to call the FMSwapFont function to get a handle to a font resource or information about a font, you must first create a font input structure and fill it with the appropriate information. You can use the pointer returned by FMSwapFont to access the font output structure. You cannot assume that the font resource pointed to by the fontHandle field of the font output structure returned by this function is of any particular type, such as 'NFNT' or 'sfnt'. If you need to access specific information in the font resource, call the Resource Manager function GetResInfo with the handle returned in the font output structure to determine the font resource type.

The pointer to the font output structure returned by the function FMSwapFont points to a structure allocated in low memory by the Font Manager. The same structure is reused for each call made to FMSwapFont. Do not free the memory allocated for this structure.

Availability
Declared In
Fonts.h

FontMetrics

Obtains fractional measurements for the font, size, and style specified in the current graphics port. (Deprecated in Mac OS X v10.4. There is no replacement function.)

void FontMetrics (
   FMetricRecPtr theMetrics
);

Parameters
theMetrics

A pointer to a font metrics structure. On output, the structure contains the font measurement information in fractional values.

Discussion

The FontMetrics function obtains measurements for the ascent, descent, leading, and width of the largest glyph in the font for the font, size, and style specified in the current graphics port.

The font metrics structure (of data type FMetricRec) contains a handle to the global width table, which in turn contains a handle to the associated font family resource for the current font (the font in the current graphics port). It also contains the values of four measurements for the current font.

The FontMetrics function is similar to the QuickDraw function GetFontInfo except that FontMetrics returns fractional values for greater accuracy in high-resolution printing. The FontMetrics function also does not take into account any additional widths that are added by QuickDraw when it applies styles to the glyphs in a font.

Availability
Declared In
Fonts.h

GetAppFont

Returns the font family ID of the current application font. (Deprecated in Mac OS X v10.4. There is no replacement function.)

short GetAppFont (
   void
);

Return Value

The font family ID of the current application font. This is the font family ID that has been mapped to 1 by the system software.

Availability
Declared In
Fonts.h

GetDefFontSize

Determines the default size of the system font. (Deprecated in Mac OS X v10.4. There is no replacement function.)

short GetDefFontSize (
   void
);

Return Value

The the default font size of the system font.

Discussion

You can determine the preferred size for either the system font or the application font of any enabled script system by calling the Script Manager function GetScriptManagerVariable.

Availability
Declared In
Fonts.h

GetFNum

Obtains the font family ID for a specified font family name. (Deprecated in Mac OS X v10.4. Use ATSFontFamilyFindFromName instead.)

Not recommended.

void GetFNum (
   ConstStr255Param name,
   short *familyID
);

Parameters
name

The font family name.

familyID

On output, a pointer to the font family ID for the font family specified in name. If the font specified in the parameter name does not exist, the font family ID contains 0.

Carbon Porting Notes

You should use the function FMGetFontFamilyFromName instead of the function GetFNum.

Availability
Related Sample Code
Declared In
Fonts.h

GetFontName

Obtains the name of a font family that has a specified family ID number. (Deprecated in Mac OS X v10.4. Use ATSFontFamilyGetName instead.)

Not recommended.

void GetFontName (
   short familyID,
   Str255 name
);

Parameters
familyID

The font family ID.

name

On output, this parameter contains the font family name for the font family specified in familyID. If the font specified in the familyID parameter does not exist, name contains an empty string.

Availability
Declared In
Fonts.h

GetOutlinePreferred

Obtains the current preference for whether outline or bitmapped fonts are returned when the Font Manager receives a font request. (Deprecated in Mac OS X v10.4. There is no replacement function.)

Boolean GetOutlinePreferred (
   void
);

Return Value

The value of the Font Manager’s current preference for outline or bitmapped fonts. If GetOutlinePreferred returns TRUE, then the Font Manager will return an outline font when both an outline font and a bitmapped font are available for a particular request. If GetOutlinePreferred returns FALSE, then the Font Manager will return the bitmapped font when both types are available. See the Debugger Services documentation for a description of the Boolean data type.

Availability
Declared In
Fonts.h

GetPreserveGlyph

Determines whether the Font Manager preserves the shapes of glyphs from outline fonts. (Deprecated in Mac OS X v10.4. There is no replacement function.)

Boolean GetPreserveGlyph (
   void
);

Return Value

A Boolean value that indicates whether the Font Manager preserves the shapes of glyphs from outline fonts. Your application can set the value of this variable with the SetPreserveGlyph function. If GetPreserveGlyph returns TRUE, the Font Manager preserves glyph shapes; if GetPreserveGlyph returns FALSE, then the Font Manager scales glyphs to fit between the ascent and descent lines for the font in use.

Availability
Declared In
Fonts.h

GetSysFont

Obtains the font family ID of the current system font. (Deprecated in Mac OS X v10.4. There is no replacement function.)

short GetSysFont (
   void
);

Return Value

The current value of the font family ID of the current system font. This is the font family ID that has been mapped to 0 by the system software.

Availability
Declared In
Fonts.h

IsAntiAliasedTextEnabled

Checks whether antialiased text is enabled. (Deprecated in Mac OS X v10.4. There is no replacement function.)

Boolean IsAntiAliasedTextEnabled (
   SInt16 *oMinFontSize
);

Parameters
oMinFontSize

On output, points to the minimum font size for which antialiasing is enabled.

Return Value

Returns true if antialiased text is enabled; false otherwise.

Availability
Declared In
Fonts.h

IsOutline

Determines whether the specified scaling factors will cause the Font Manager to choose an outline font for the current graphics port. (Deprecated in Mac OS X v10.4. There is no replacement function.)

Boolean IsOutline (
   Point numer,
   Point denom
);

Parameters
numer

The numerators of the vertical and horizontal scaling factors. The numer parameter is of type Point, and contains two fields: h (the numerator of the ratio for horizontal scaling) and v (the numerator of the ratio for vertical scaling).

denom

The denominators of the vertical and horizontal scaling factors. The denom parameter is of type Point, and contains two fields: h (the denominator of the ratio for horizontal scaling) and v (the denominator of the ratio for vertical scaling).

Return Value

Returns TRUE if the Font Manager will choose an outline font for the current graphics port.

Discussion

The Font Manager uses the font scaling factors specified in the numer and denom parameters as well as the current preference (as set by the SetOutlinePreferred function) as criteria to choose which font to use.

Availability
Declared In
Fonts.h

OutlineMetrics

Obtains font measurements for a block of text to be drawn in a specified outline font. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSErr OutlineMetrics (
   short byteCount,
   const void *textPtr,
   Point numer,
   Point denom,
   short *yMax,
   short *yMin,
   FixedPtr awArray,
   FixedPtr lsbArray,
   RectPtr boundsArray
);

Parameters
byteCount

The number of bytes in the block of text that you want measured.

textPtr

A pointer to the block of text that for which you want to obtain font measurements.

numer

The numerators of the vertical and horizontal scaling factors. The numer parameter is of type Point, and contains two fields: h (the numerator of the ratio for horizontal scaling) and v (the numerator of the ratio for vertical scaling). The Font Manager applies these scaling factors to the current font when calculating the measurements for glyphs in the block of text.

denom

The denominators of the vertical and horizontal scaling factors. The denom parameter is of type Point, and contains two fields: h (the denominator of the ratio for horizontal scaling) and v (the denominator of the ratio for vertical scaling). The Font Manager applies these scaling factors to the current font when calculating the measurements for glyphs in the block of text.

yMax

On output, a pointer to the maximum y-value for the text. Pass NULL in this parameter if you don’t want this value returned.

yMin

On output, a pointer to the minimum y-value for the text. Pass NULL in this parameter if you don’t want this value returned.

awArray

A pointer to an array. On output the array is filled with the advance width measurements for the glyphs being measured. These measurements are in pixels, based on the point size and font scaling factors of the current font. There is an entry in this array for each glyph that is being measured.

The awArray parameter is of type FixedPtr. The FixedPtr data type is a pointer to an array, and each entry in the array is of type Fixed, which is 4 bytes in length. Multiply byteCount by 4 to calculate the memory you need in bytes.

If the FractEnable global variable has been set to TRUE through the SetFractEnable function, the values in awArray have fractional character widths. If FractEnable has been set to FALSE, the Font Manager returns integer values for the advance widths, with 0 in the decimal part of the values.

lsbArray

A pointer to an array. On output the array is filled with the left-side bearing measurements for the glyphs being measured. The measurements are in pixels, based on the point size of the current font. There is an entry in this array for each glyph that is being measured.

The lsbArray parameter is of type FixedPtr. The FixedPtr data type is a pointer to an array, and each entry in the array is of type Fixed, which is 4 bytes in length. Multiply byteCount by 4 to calculate the memory you need in bytes.

The fractional portion of left-side bearing values are retained.

boundsArray

A pointer to an array. On output the array is filled with the bounding boxes for the glyphs being measured. Bounding boxes are the smallest rectangles that fit around the pixels of the glyph. There is an entry in this array for each glyph that is being measured.

The coordinate system used to describe the bounding boxes is in pixel units, centered at the glyph origin, and with a vertical positive direction upwards. This is the opposite of the QuickDraw vertical orientation.

The boundsArray parameter is of type RectPtr. The RectPtr data type is a pointer to QuickDraw’s Rect data type, which is 8 bytes in length. Multiply byteCount by 8 to calculate the memory you need in bytes. Allocate the memory needed for the array and pass a pointer to the array in the boundsArray parameter.

Return Value

A result code. See “Font Manager Result Codes.”

Discussion

The OutlineMetrics function computes the maximum y-value, minimum y-value, advance widths, left-side bearings, and bounding boxes for a block of text. It uses the font, size, and style specified in the current graphics port. You can use these measurements when laying out text. You may need to adjust line spacing to accommodate exceptionally large glyphs.

The OutlineMetrics function works for outline fonts only and is the preferred method for measuring text that is drawn with an outline font.

When you are using OutlineMetrics to compute advance width values, left-side bearing values, or bounding boxes, you need to bear in mind that when a text block contains 2-byte characters, not every byte in the awArray, lsbArray, and boundsArray structures is used. Each of these arrays is indexed by the glyph index; thus, if you have five characters in a string, only the first five entries in each array contains a value. Call the Script Manager function CharByte to determine how many characters there are in the text block, and ignore the unused array entries (which occur at the end of each array).

If you don’t want OutlineMetrics to compute one of these three values, pass NULL in the applicable parameter. Otherwise, allocate the amount of memory needed for the array and pass a pointer to it in this parameter.

Availability
Declared In
Fonts.h

QDTextBounds

Obtains a rectangle that specifies the bounds of QuickDraw text. (Deprecated in Mac OS X v10.4. There is no replacement function.)

void QDTextBounds (
   short byteCount,
   const void *textAddr,
   Rect *bounds
);

Parameters
byteCount

The number of bytes in the buffer that contains the text whose bounds you want to obtain.

textAddr

A pointer to a buffer that contains the text whose bounds you want to obtain. You must allocate this buffer.

bounds

On output, points to a rectangle that specifies the bounds of QuickDraw text.

Availability
Declared In
Fonts.h

RealFont

Determines whether a font is available or is intended for use in a specified size. (Deprecated in Mac OS X v10.4. There is no replacement function.)

Boolean RealFont (
   short fontNum,
   short size
);

Parameters
fontNum

The font family ID.

size

The font size requested.

Return Value

Returns TRUE if the requested size of the font is available. The function RealFont first checks for a bitmapped font from the specified family. If one is not available, RealFont checks next for an outline font. If neither kind of font is available, RealFont returns FALSE.

Discussion

If an outline font exists for the requested font family, RealFont normally considers the font to be available in any requested size. However, the font designer can include instructions in the font that outlines should not be used at certain point sizes, in which case the RealFont function considers the font unavailable and returns FALSE. The Font Manager determines whether the size is valid by testing the value of the smallest readable size element of the font family header table.

Availability
Declared In
Fonts.h

SetAntiAliasedTextEnabled

Enables or disables antialiased text for an application. (Deprecated in Mac OS X v10.4. There is no replacement function.)

OSStatus SetAntiAliasedTextEnabled (
   Boolean iEnable,
   SInt16 iMinFontSize
);

Parameters
iEnable

A Boolean value. Pass true to enable antialiased text or false to disable it.

iMinFontSize

A integer of type SInt16 that specifies the minimum font size to which antialiasing should be enabled.

Return Value

A result code. See “Font Manager Result Codes.”

Availability
Declared In
Fonts.h

SetFractEnable

Enables or disables fractional glyph widths. (Deprecated in Mac OS X v10.4. There is no replacement function.)

void SetFractEnable (
   Boolean fractEnable
);

Parameters
fractEnable

Specifies whether fractional widths or integer widths are to be used to determine glyph measurements. A value of TRUE indicates fractional glyph widths; a value of FALSE indicates integer glyph widths.

The SetFractEnable function assigns the value that you specify in the fractEnable parameter to the global variable FractEnable.

Discussion

The SetFractEnable function establishes whether or not the Font Manager provides fractional glyph widths to QuickDraw, which then uses them for advancing the pen during text drawing.

The Font Manager defaults to integer widths to ensure compatibility with existing applications. When fractional glyph widths are enabled, the Font Manager can determine the locations of glyphs more accurately than is possible with integer widths.

Availability
Declared In
Fonts.h

SetFScaleDisable

Enables or disables the computation of font scaling factors by the Font Manager for bitmapped glyphs. (Deprecated in Mac OS X v10.4. There is no replacement function.)

void SetFScaleDisable (
   Boolean fscaleDisable
);

Parameters
fscaleDisable

Specifies whether bitmapped fonts are to be scaled. A value of TRUE indicates that font scaling is disabled; a value of FALSE indicates that font scaling is enabled.

If you set the fscaleDisable parameter to TRUE, the Font Manager disables font scaling, which means it responds to a request for a font size that is not available by computing font scaling factors of 1/1 and returning a smaller, unscaled bitmapped font with the widths of the requested size. If you set the fscaleDisable parameter to FALSE, the Font Manager computes scaling factors for bitmapped fonts.

Discussion

QuickDraw performs the actual scaling of glyph bitmaps for bitmapped fonts by using the font scaling factors computed and returned by the Font Manager.

When font scaling is enabled, the Font Manager can scale a bitmapped glyph that is present in the System file to imitate the appearance of a bitmapped glyph in another point size that is not present. By default, the Font Manager scales fonts to ensure compatibility with existing applications.

Availability
Declared In
Fonts.h

SetOutlinePreferred

Sets the preference for whether to use bitmapped or outline fonts when both kinds of fonts are available. (Deprecated in Mac OS X v10.4. There is no replacement function.)

void SetOutlinePreferred (
   Boolean outlinePreferred
);

Parameters
outlinePreferred

Specifies whether the Font Manager chooses an outline font or a bitmapped font when both are available to fill a font request. A value of TRUE indicates an outline font; a value of FALSE indicates a bitmapped font.

If you want the Font Manager to choose outline fonts over any bitmapped font counterparts, set the outlinePreferred parameter to TRUE. If you want it to choose bitmapped fonts, set the outlinePreferred parameter to FALSE.

Discussion

If an outline font and a bitmapped font are both available for a font request, the default behavior for the Font Manager is to choose the bitmapped font, in order to maintain compatibility with documents that were created on computer systems on which outline fonts were not available. The SetOutlinePreferred function sets the Font Manager’s current preference for either bitmapped or outline fonts when both are available.

If only outline fonts are available, the Font Manager chooses them regardless of the value of the outlinePreferred parameter. If only bitmapped fonts are available, they are chosen. The Font Manager chooses bitmapped versus outline fonts on a size basis, before it takes stylistic variations into account, which can lead to unexpected results.

The preference you set is valid only during the current session with your application. The outlinePreferred parameter does not set a global variable.

Availability
Declared In
Fonts.h

SetPreserveGlyph

Temporarily changes the default behavior of the Font Manager, so that it does not scale oversized glyphs. (Deprecated in Mac OS X v10.4. There is no replacement function.)

void SetPreserveGlyph (
   Boolean preserveGlyph
);

Parameters
preserveGlyph

Specifies whether or not glyphs from an outline font are scaled to fit between the ascent and descent lines. If you set the value of the preserveGlyph parameter to TRUE, the measurements of all glyphs are preserved, which means that your application may have to alter the leading between lines in a document if some of the glyphs extend beyond the ascent or descent lines. If you set the value of the preserveGlyph parameter to FALSE, all glyphs are scaled to fit between the ascent and descent lines.

Discussion

The SetPreserveGlyph function establishes how the Font Manager treats glyphs that do not fit between the ascent and descent lines for the current font. The default behavior for the Font Manager is to scale a glyph from an outline font so that it fits between the ascent and descent lines; however, this alters the appearance of the glyph.

You can determine the current behavior of the Font Manager in this regard by calling the GetPreserveGlyph function. To ensure that documents have the same appearance whenever they are opened, you need to call GetPreserveGlyph and save the value that it returns with your documents and restore it each time a document is displayed by your application.

Availability
Declared In
Fonts.h

Deprecated in Mac OS X v10.5

FMGetGeneration

Retrieves the value of the generation count. (Deprecated in Mac OS X v10.5. Use ATSGetGeneration instead.)

FMGeneration FMGetGeneration (
   void
);

Return Value

The generation count. See the ATS Types documentation for a description of the FMGeneration data type.

Discussion

Any operation that adds, deletes, or modifies one or more font families or fonts triggers an update of the global generation count. You can use this function in conjunction with the iteration functions to identify changes made to the font database.

Availability
Declared In
Fonts.h

< Previous PageNext Page > Hide TOC

© 2002, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-12-11)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.