Carbon


ATSUGetIndFontName

Header: ATSUnicode.h Carbon status: Supported

Finds the font name string and other font name parameters for an indexed font name.

OSStatus ATSUGetIndFontName (
    ATSUFontID iFontID, 
    ItemCount iFontNameIndex, 
    ByteCount iMaximumNameLength, 
    Ptr oName, 
    ByteCount *oActualNameLength, 
    FontNameCode *oFontNameCode, 
    FontPlatformCode *oFontNamePlatform, 
    FontScriptCode *oFontNameScript, 
    FontLanguageCode *oFontNameLenguage
);
Parameter descriptions
iFontID

The ID of the font whose indexed font name you want information about.

iFontNameIndex

An index of the font name you want information about. Pass a value between 0 and one less than the count passed back by the function ATSUCountFontNames.

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 ATSUGetIndFontName, pass a pointer to memory that you have allocated for this buffer. If you are uncertain of how much memory to allocate, see the discussion below. On return, the buffer contains the font name string. If the buffer you allocate is not large enough, ATSUGetIndFontName 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.

oFontNameCode

On return, a pointer to the type of the font name string. See “Font Name Code Constants” in the Font Manager for a description of possible values.

oFontNamePlatform

On return, a pointer to the encoding of the font name string. See “Font Name Platform Constants” in the Font Manager for a description of possible values.

oFontNameScript

On return, a pointer to 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” in the Font Manager for a description of possible values.

oFontNameLenguage

On return, a pointer to the language of the font name string. See “Font Name Language Constants” in the Font Manager for a description of possible values.

function result

A result code. The result code kATSUInvalidFontErr indicates that the ID does not correspond to any installed font.

DISCUSSION

You should call the ATSUGetIndFontName function to iterate through the entries of a font name table to find the font name string, name code, language code, script code, and platform code of an indexed font name. The best way to use ATSUGetIndFontName is to call it twice:

  1. Pass the ID of the font whose name table you want to iterate in the iFontID parameter, NULL for the oName parameter, and 0 for the other parameters. ATSUGetIndFontName 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 index and font name of the first font in a name table matching given font name parameters, call the function ATSUFindFontName. To find the first font that matches the specified name, platform, language, and script, call the function ATSUFindFontFromName.

ATSUGetIndFontName 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)