Carbon


ATSUGetFontInstance

Header: ATSUnicode.h Carbon status: Supported

Obtains information about a font instance.

OSStatus ATSUGetFontInstance (
    ATSUFontID iFont, 
    ItemCount iFontInstanceIndex, 
    ItemCount iMaximumVariations, 
    ATSUFontVariationAxis oAxes[], 
    ATSUFontVariationValue oValues[], 
    ItemCount *oActualVariationCount
);
Parameter descriptions
iFont

The ID of the font whose font instance you want information about.

iFontInstanceIndex

An index of the font instance you wish information about. Pass a value between 0 and one less than the count passed back in the function ATSUCountFontInstances.

iMaximumVariations

The maximum number of font variations. Typically, this is equivalent to the number of elements in the oAxes and oValues arrays. To determine this value, see the discussion below.

oAxes

An array of font variation axes. Before calling ATSUGetFontInstance, pass a pointer to memory that you have allocated for this array. If you are uncertain of how much memory to allocate, see the discussion below. On return, an array of the font variation axes in the font. You cannot pass NULL for this parameter.

oValues

An array of font variation values. Before calling ATSUGetFontInstance, pass a pointer to memory that you have allocated for this array. If you are uncertain of how much memory to allocate, see the discussion below. On return, an array of the font variation values corresponding to the axes in the oAxes parameter in the font. You cannot pass NULL for this parameter.

oActualVariationCount

On return, a pointer to the actual number of font variations. This may be greater than the value passed in the iMaximumVariations parameter. You cannot pass NULL for this parameter.

function result

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

DISCUSSION

The ATSUGetFontInstance function obtains the axis and corresponding value for a given font index. The best way to use ATSUGetFontInstance is to call it twice:

  1. Pass the ID of the font whose font instance you want information about in the iFont parameter, NULL for the oAxes and oValues parameters, and 0 for the other parameters. ATSUGetFontInstance returns the size of the oAxes and oValues arrays in the oActualVariationCount parameter.
  2. Allocate enough space for an array of the returned size, then call the function again, passing pointers in the oAxes and oValues parameters; on return, the pointers reference the array of axes and values corresponding to the font instances in the font.

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)