![]() |
FNSReferenceMatchFamilies |
||||
Header: | FontSync.h | Carbon status: | Supported | |
Obtains a list of font families that match a reference.
OSStatus FNSReferenceMatchFamilies ( FNSFontReference iReference, FNSMatchOptions iMatchOptions, ItemCount iOutputSize, FMFontFamilyInstance oFonts[], ItemCount *oNumMatches );
A reference to the font reference whose matching font(s) you wish to determine.
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 users preferences via this mask.
The capacity of the oFonts array. This may be less than the actual number of matches passed back in the oNumMatches parameter.
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.
On return, a pointer to the total number of font families that match the specified reference. This value may be greater than the number of fonts passed back in the oFonts array.
A result code. The result code kFNSBadReferenceVersionErr indicates that a font reference has an unsupported 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.
The FNSReferenceMatchFamilies function maps a font reference to an active font that can be used with QuickDraw Text. 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 FNSReferenceMatchFamilies cannot find a font family that matches a font reference and someone 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. For more information, see the discussion for the function FNSReferenceMatchFonts.
If you want to determine whether the profile has a matching font, but dont 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 FNSReferenceMatchFamilies 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 FNSReferenceMatchFamilies again, passing the returned number of matches in the iOutputSize parameter.
Available beginning with FontSync 1.0.
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)