Carbon


ATSUFindFontFromName

Header: ATSUnicode.h Carbon status: Supported

Finds the first font in a name table that matches given font name parameters.

OSStatus ATSUFindFontFromName (
    Ptr iName, 
    ByteCount iNameLength, 
    FontNameCode iFontNameCode, 
    FontPlatformCode iFontNamePlatform, 
    FontScriptCode iFontNameScript, 
    FontLanguageCode iFontNameLanguage, 
    ATSUFontID *oFontID
);
Parameter descriptions
iName

A pointer to a buffer. Pass the name string of the font you want to obtain.

iNameLength

The length (in bytes) of the font name string.

iFontNameCode

The type of the font name string. See “Font Name Code Constants” in the Font Manager for a description of possible values.

iFontNamePlatform

The encoding of the font name string. See “Font Name Platform Constants” in the Font Manager for a description of possible values. You can pass the kFontNoPlatform constant if you do not care about the encoding. In this case, ATSUFindFontFromName will pass back the first font in the name table matching the other font name parameters.

iFontNameScript

The script ID of the font name string. Depending upon the font name platform, see “Macintosh Platform Script Code Constants”, “Microsoft Platform Script Code Constants”, or “Unicode Platform Script Code Constants” for a description of possible values. You can pass the kFontNoScript constant if you do not care about the script ID. In this case, ATSUFindFontFromName will pass back the first font in the name table matching the other font name parameters.

iFontNameLanguage

The language of the font name string. See “Font Name Language Constants” in the Font Manager for a description of possible values. You can pass the kFontNoLanguage constant if you do not care about the language. In this case, ATSUFindFontFromName will pass back the first font in the name table matching the other font name parameters.

oFontID

On return, a pointer to the first font that matches the specified font name code, platform, script, and language. If no installed font matches these parameters, ATSUFindFontFromName passes back the constant kATSUInvalidFontID and returns the result code kATSUInvalidFontErr.

function result

A result code.

DISCUSSION

The ATSUFindFontFromName function finds the first font that matches the specified name, platform, language, and script. Because ATSUI cannot guarantee the uniqueness of names among installed fonts, ATSUFindFontFromName does not necessarily find the only font that matches these parameters. As a result, you may wish to create a more sophisticated name-matching algorithm or guarantee the uniqueness of names among installed fonts.

To find the font name string and font name table information corresponding to an indexed font name, call the function ATSUGetIndFontName. To find the index and font name of the first font in a name table matching given font name parameters, call the function ATSUFindFontName.

ATSUFindFontFromName may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

VERSION NOTES

Available beginning with ATSUI 1.0.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.5 or later.


© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)