Carbon


FNSReferenceMatchFonts

Header: FontSync.h Carbon status: Supported

Obtains a list of font objects that match a reference.

OSStatus FNSReferenceMatchFonts (
    FNSFontReference iReference, 
    FNSMatchOptions iMatchOptions, 
    ItemCount iOutputSize, 
    FMFont oFonts[], 
    ItemCount *oNumMatches
);
Parameter descriptions
iReference

A reference to the font reference whose matching font(s) you wish to determine.

iMatchOptions

A bit mask you can use to set the matching option bits to be used in the comparison. To specify the global default match criteria, pass the bit mask returned by the function FNSMatchDefaultsGet. The total number of matching references is passed back in the oNumMatches parameter. Your application can specify options that are different from the user’s preferences via this mask.

iOutputSize

The capacity of the oFonts array. This may be less than the actual number of matches passed back in the oNumMatches parameter.

oFonts

On return, a pointer to an array of indices identifying the fonts matching the specified reference. The number of indices returned is limited by the value you specify in the iOutputSize parameter.

oNumMatches

On return, a pointer to the total number of font objects that match the specified reference. This value may be greater than the number of fonts passed back in the oFonts array.

function result

A result code. The result code kFNSBadReferenceVersionErr indicates that a font reference has an unsupported format version number. This may indicate that the reference is valid, but created by a later version of FontSync, or that the reference is truly invalid. The result code kFNSInvalidReferenceErr indicates that a font reference is invalid. The result code kFNSMismatchErr indicates that no matches were found. Memory Manager errors indicate that you did not have enough memory available in your heap.

DISCUSSION

The FNSReferenceMatchFonts function passes back a list of active fonts which match the specified reference. FNSReferenceMatchFonts maps a font reference to an actual font that can be used with ATSUI. Since there may be more than one such font, a list is returned.

The number of fonts passed back in the oFonts array is limited by the value you specify in the iOutputSize parameter. The actual number of matches is passed back in the oNumMatches parameter. You can check this value to determine whether the oFonts array was large enough to contain the matches.

If you want to determine whether the profile has a matching font, but don’t care which one, pass 0 for the iOutputSize parameter and NULL for the oNumMatches parameter. The result code noErr indicates that matches were found, while the result code kFNSMismatchErr indicates that no matches were found.

To determine the number of matches, call FNSReferenceMatchFonts and pass 0 for the iOutputSize parameter. The pointer passed back in the oNumMatches parameter will point to the actual number of matches. You can then call FNSReferenceMatchFonts again, passing the returned number of matches in the iOutputSize parameter.

If FNSReferenceMatchFonts cannot find an active font that matches a font reference and your application has registered interest in this process, FontSync sends an Apple Event with the details of the request to the third party font-management utility in question. The receiver should respond with a list of matching fonts, taking whatever steps are necessary to identify and activate them before replying to the event. Registration is handled by the simple expedient of installing a handler for the appropriate Apple Event. This handler will typically be installed in the system table, though FontSync will check for handlers both in the system and in the context’s local handler table. The Apple Event will be a send-to-self.

VERSION NOTES

Available beginning with FontSync 1.0.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when Font Sync 1.0 or later is present.


© 2000 Apple Computer, Inc. (Last Updated 7/13/2000)