Carbon


ATSUFindFontName

Header: ATSUnicode.h Carbon status: Supported

Finds the index and font name of the first font in a name table matching given font name parameters.

OSStatus ATSUFindFontName (
    ATSUFontID iFontID, 
    FontNameCode iFontNameCode, 
    FontPlatformCode iFontNamePlatform, 
    FontScriptCode iFontNameScript, 
    FontLanguageCode iFontNameLanguage, 
    ByteCount iMaximumNameLength, 
    Ptr oName, 
    ByteCount *oActualNameLength, 
    ItemCount *oFontNameIndex
);
Parameter descriptions
iFontID

The ID of the font whose particular font name you are searching for.

iFontNameCode

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

iFontNamePlatform

The encoding of the font name string you are searching for. 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 of a font name. In this case, ATSUFindFontName 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 you are searching for. Depending upon the font name platform, see “Macintosh Platform Script Code Constants”, “Microsoft Platform Script Code Constants”, or “Unicode Platform Script Code Constants” in the Font Manager for a description of possible values. You can pass the kFontNoScript constant if you do not care about the script ID. In this case, ATSUFindFontName will pass back the first font in the name table matching the other font name parameters.

iFontNameLanguage

The language of the font name string you are searching for. 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 of the font name. In this case, ATSUFindFontName will pass back the first font in the name table matching the other font name parameters.

iMaximumNameLength

The maximum length of the font name. Typically, this is equivalent to the size of the buffer allocated to contain the font name pointed to by the oName parameter. To determine this length, see the discussion below.

oName

A pointer to a buffer. Before calling ATSUFindFontName, pass a pointer to memory that you have allocated for this buffer. On return, the buffer contains the font name string. If the buffer you allocate is not large enough, ATSUFindFontName passes back a partial string. You cannot pass NULL for this parameter.

oActualNameLength

On return, a pointer to the actual length of the font name string. This may be greater than the value passed in the iMaximumNameLength parameter. You should check this value to make sure that you allocated enough memory for the buffer. You cannot pass NULL for this parameter.

oFontNameIndex

On return, a pointer to the index of the font name in the font name table. Note that the index is 0-based.

function result

A result code. The result code kATSUNotSetErr indicates that the font has no name in its name table matching the given parameters. The result code kATSUInvalidFontErr indicates that the specified font does not correspond to any installed font.

DISCUSSION

The ATSUFindFontName function obtains the index and font name string of the first font in a name table that matches a particular font name code, language, platform, and script. The best way to use ATSUFindFontName is to call it twice:

  1. Pass the ID of the font whose name table you are searching in the iFontID parameter, NULL for the oName parameter, and 0 for the other parameters. ATSUFindFontName returns the length of the font name string in the oActualNameLength parameter.
  2. Allocate enough space for a font name buffer of the returned size, then call the function again, passing a pointer in the oName parameter; on return, the pointer references the font name string.

To find the first font that matches the specified name, platform, language, and script, call the function ATSUFindFontFromName. To find the font name string and other font name parameters for an indexed font name, call the function ATSUGetIndFontName.

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)