AIFontSuite Struct Reference
[API Suite List]

This suite provides functions to access the set of fonts that is available to Illustrator documents, and provide information about individual fonts. More...

#include <AIFont.h>

List of all members.

Public Attributes
AIAPI AIErr(*	CountFonts )(ai::int32 *count)
	Gets the total number of available fonts.
AIAPI AIErr(*	IndexFontList )(ai::int32 index, AIFontKey *fontKey)
	Retrieves a font by index position.
AIAPI AIErr(*	CountTypefaces )(ai::int32 *count)
	Gets the total number of font families.
AIAPI AIErr(*	IndexTypefaceList )(ai::int32 index, AITypefaceKey *typeFaceKey)
	Retrieves a font family by index position.
AIAPI AIErr(*	CountTypefaceStyles )(AITypefaceKey typeface, ai::int32 *count)
	Gets the total number of variants (such as bold and italic) of a font family.
AIAPI AIErr(*	IndexTypefaceStyleList )(AITypefaceKey typeface, ai::int32 index, AIFontKey *fontKey)
	Retrieves a variant of a font family by index position.
AIAPI AIErr(*	TypefaceAndStyleFromFontKey )(AIFontKey theKey, AITypefaceKey typefaceResult, ai::int16 styleResult)
	Retrieves the family and variant of a font.
AIAPI AIErr(*	FindFont )(const char postscriptName, enum AIFontTechnology fontTechnology, AIFaceScript script, AIBoolean substituteFlag, AIFontKey result)
	Finds a font matching specific criteria.
AIAPI AIErr(*	FindMacFontFromMacFontRef )(AIMacFontRef macFontRef, AIFontKey *result)
	Finds an Illustrator font matching a Mac OS system font.
AIAPI AIErr(*	FindWinFont )(AILOGFONTA logFont, AIFontKey result)
	Not implemented.
AIAPI AIErr(*	GetMacFontRef )(AIFontKey fontKey, AIMacFontRef &macFontRef)
	Retrieves the Mac OS ATS font ref for an Illustrator font.
AIAPI AIErr(*	GetSystemFontName )(AIFontKey fontKey, char *result, ai::int16 maxName)
	Retrieves typeface name of a font, or the system name for a system font in Windows.
AIAPI AIErr(*	SetCharWidths )(AIFontKey fontKey, AIReal *charWidths)
	Sets the character widths for a fauxed, single-byte, horizontal font.
AIAPI AIErr(*	GetFontInfo )(AIFontKey font, struct AIFontStyle *result)
	Retrieves the font information for a font.
AIAPI AIErr(*	GetFontMetrics )(AIFontKey font, struct AIFontMetrics *result)
	Retrieves the font metrics for a font.
AIAPI AIErr(*	GetGlyphDimensions )(AIFontKey font, AIGlyphID glyphID, enum AIMetricOrientation orientation, AIReal hResult, AIReal vResult)
	Retrieves the default pen displacement for a glyph in a given orientation, for a 1-point font.
AIAPI AIErr(*	GetCharDimensions )(AIFontKey font, const char charPtr, enum AIMetricOrientation orientation, AIReal hResult, AIReal *vResult)
	Retrieves the default pen displacement for a UTF8-encoded character in a given orientation, for a 1-point font.
AIAPI AIErr(*	GetDefaultFont )(AIFaceScript script, AIFontKey *result)
	Retrieves the default font for a language script.
AIAPI AIErr(*	GetFullFontName )(AIFontKey font, char *fontName, ai::int16 maxName)
	Retrieves the PostScript name of a font, with the encoding information that Illustrator appends.
AIAPI AIErr(*	GetPostScriptFontName )(AIFontKey fontKey, char *postScriptFontName, ai::int16 maxName)
	Retrieves the Illustrator PostScript name of a font (with encoding information appended).
AIAPI AIErr(*	GetFontStyleName )(AIFontKey font, char *styleName, ai::int16 maxName)
	Retrieves the ASCII-encoded name for the variant of a font (for example, "Bold Italic").
AIAPI AIErr(*	GetFontFamilyUIName )(AIFontKey font, char *familyName, ai::int16 maxName)
	Retrieves the display name for the family of a font (for example, "Times Roman").
AIAPI AIErr(*	GetFontStyleUIName )(AIFontKey font, char *styleName, ai::int16 maxName)
	Retrieves the display name for the variant of a font (for example, "Bold Italic").
AIAPI AIErr(*	GetTypefaceName )(AITypefaceKey typeface, char *name, ai::int16 maxName)
	Retrieves the ASCII-encoded name for a font family (for example, "Times Roman").
AIAPI AIErr(*	GetUserFontName )(AIFontKey font, char *userfontName, ai::int16 maxName)
	Retrieves the full ASCII-encoded name for a font (for example, "Times Roman Bold Italic").
AIAPI AIErr(*	GetUserFontUIName )(AIFontKey font, char *userfontName, ai::int16 maxName)
	Retrieves the full display name for a font (for example, "Times Roman Bold Italic") The name is encoded either in ASCII or in the encoding of the font, depending on the preference setting for using English font names.
AIAPI AIErr(*	FontFromFontKey )(AIFontKey font, FontRef *result)
	Converts an Illustrator font key to an Adobe Text Engine (ATE) font reference, for use with ATE functions.
AIAPI AIErr(*	FontKeyFromFont )(FontRef font, AIFontKey *result)
	Converts an Adobe Text Engine (ATE) font reference to an Illustrator font key.
AIAPI AIErr(*	GetFontIsSubstituted )(AIFontKey fontKey, AIBoolean &outIsSubstituted)
	Retrieves whether a font is substituted or not.
AIAPI AIErr(*	GetGlyphSet )(AIFontKey theFont, ai::int32 otFeature, AIGlyphSet *result)
	Retrieves a glyph set, which contains information about alternate glyphs within an OpenType font.
AIAPI AIErr(*	ReleaseGlyphSet )(AIGlyphSet theSet)
	Disposes of a glyph set object.
AIAPI AIErr(*	CountGlyphs )(AIGlyphSet theSet, int *glyphCountResult)
	Gets the number of glyphs within a glyph set.
AIAPI AIErr(*	GetGlyphInfo )(AIGlyphSet theSet, ai::int32 glyphIndex, AIGlyphInfo *glyphInfoResult)
	Retrieves information about a specific glyph.
AIAPI AIErr(*	GlyphIDToIndex )(AIGlyphSet theSet, AIGlyphID glyphID, int *glyphIndexResult)
	Gets the ordinal position of a given glyph within a glyph set.
AIAPI AIErr(*	GetOTFeatures )(AIFontKey theFont, ai::int32 featureList, ai::int32 featureCount)
	Retrieves all OpenType features supported by a particular font.
AIAPI ai::int32(*	GetGlyphsForFeatureAccessInfo )(ai::int32 theFeature, AIFontKey fontKey, AIBoolean existFlag, AIGlyphSet *glyphSet)
	Reports whether there are any glyphs for a given Open Type feature in a given font, or retrieves the glyph set containing the glyphs, if any.
AIAPI AIErr(*	GetFontInstance )(AIGlyphSet glyphSetOpaque, AIFontInst **result)
	Retrieves the font that contains a glyph set.
AIAPI AIErr(*	GetGlyphID )(AIGlyphInfo glyphInfo, AIGlyphID *result)
	Retrieves the unique identifier of a glyph.
AIAPI AIErr(*	GetAlternateGlyphs )(AIGlyphInfo glyphInfo, AIGlyphSet *result)
	Retrieves the set of alternate glyphs for a given glyph.
AIAPI AIErr(*	GetGlyphOTFeatures )(AIGlyphInfo glyphInfo, const char *otFeatures, ai::int32 otFeatureCount, ai::int32 **otFeatureIndex)
	Retrieves the OpenType features associated with a given glyph.
AIAPI AIErr(*	GetGlyphUnicodeValue )(AIGlyphID mGlyphID, AIFontKey fontKey, const char desiredOTFeature, ASUnicode theChar, int resultLength, char otFeatures, ai::int32 otFeatureCount, ai::int32 **otFeatureIndex)
	Retrieves the Unicode character for a given glyph in a given font, with information about what OpenType features were applied.
AIAPI AIErr(*	GetGlyphFontKey )(AIGlyphInfo theGlyphInfo, AIFontKey *result)
	Retrieves the font for a glyph.
AIAPI AIErr(*	GetGlyphAlternateCount )(AIGlyphInfo theGlyphInfo, int *result)
	Retrieves the number of alternate glyphs for a given glyph.
AIAPI AIErr(*	GetUndefinedGlyphID )(AIGlyphSet theSet, AIGlyphID *undefinedGlyphIDResult)
	Retrieves the undefined glyph for a glyph set.
AIAPI AIBoolean(*	HasUndefinedGlyph )(AIGlyphSet theSet)
	Reports whether a glyph set contains an undefined glyph.
AIAPI AIErr(*	ImportCompositeFonts )(const ai::FilePath &source)
	Imports composite fonts from an AI or ATC file into the current document.
AIAPI AIErr(*	ConvertCharacterToGlyphID )(AIFontKey fontKey, const char ch, ai::int32 srcLen, enum AIMetricOrientation orientation, AIGlyphID glyphID)
	Translates a character value to a single glyph in a given font.
AIAPI AIErr(*	ConvertUnicodeToGlyphID )(AIFontKey fontKey, const ASUnicode ch, ai::int32 srcLen, enum AIMetricOrientation orientation, AIGlyphID glyphID)
	Translates a Unicode character value to a single glyph in a given font.
AIAPI AIErr(*	GetUserFontUINameUnicode )(AIFontKey fontKey, ASUnicode *userfontName, ai::int32 maxName)
	Retrieves the full display name for a font (for example, "Times Roman Bold Italic") in Unicode (UTF16).
AIAPI AIErr(*	GetFontFamilyUINameUnicode )(AIFontKey fontKey, ASUnicode *familyName, ai::int32 maxName)
	Retrieves the display name for the family of a font (for example, "Times Roman") in Unicode (UTF16).
AIAPI AIErr(*	GetFontStyleUINameUnicode )(AIFontKey fontKey, ASUnicode *styleName, ai::int32 maxName)
	Retrieves the display name for the variant of a font (for example, "Bold Italic") in Unicode (UTF16).
AIAPI AIErr(*	GetICFBox )(AIFontKey fontKey, AIRealRect &icfBox)
	Retrieves the ideographic character face (IFC) bounds of a font.
AIAPI AIErr(*	GetVersionString )(AIFontKey fontKey, ai::UnicodeString &versionString)
	Retrieves the version string for a font file.
AIAPI AIErr(*	GetFontFilePathCount )(AIFontKey fontKey, ai::uint32 &count)
	Reports how many files constitute a font.
AIAPI AIErr(*	GetNthFilePath )(AIFontKey fontKey, ai::uint32 n, ai::FilePath &filePath)
	Retrieves a file path associated with a font.
AIAPI AIErr(*	GetNumATCComponents )(AIFontKey fontKey, ai::uint32 &count)
	Gets the number of ATC components for a font.
AIAPI AIErr(*	GetNthATCComponent )(AIFontKey fontKey, ai::uint32 n, AIFontKey &componentFontKey)
	Retrieves a component for an ATC font, by position index.
AIAPI AIErr(*	GetUserFontNameUnicode )(AIFontKey fontKey, ai::UnicodeString &name, AIBoolean native)
	Retrieves the full user name for a font (for example, "Times Roman Bold Italic").
AIAPI AIErr(*	GetFontFamilyNameUnicode )(AIFontKey fontKey, ai::UnicodeString &name, AIBoolean native)
	Retrieves the user name for the family of a font (for example, "Times Roman").
AIAPI AIErr(*	GetFontStyleNameUnicode )(AIFontKey fontKey, ai::UnicodeString &name, AIBoolean native)
	Retrieves the user name for the style of a font (for example, "Bold Italic").
AIAPI AIErr(*	GetIdeoEmBox )(AIFontKey fontKey, AIRealRect &ideoEmBox)
	Retrieves the ideographic em-box of a font, also known as an ideographic font's design space.
AIAPI AIErr(*	GetCloselyMatchingFontStyle )(AITypefaceKey old_Family, short old_Style, AITypefaceKey new_Family, short new_Style)
	Retrieves a font from a given family that is the closest match for a given font from another family.
AIAPI AIErr(*	IndexTypefaceListSortedByDefaultScript )(AITypefaceKey *typeface, ai::int32 index)
	Retrieves a font family by index position, from the list of all available font families.
AIAPI AIErr(*	GetTypefaceUnicodeMenuName )(AITypefaceKey typeface, ai::UnicodeString &typefaceName)

Detailed Description

This suite provides functions to access the set of fonts that is available to Illustrator documents, and provide information about individual fonts.

The set of available fonts includes those from the operating system, those installed with Illustrator, and substitute fonts for missing fonts in open documents. The set of fonts can change during a session as fonts are activated or deleted, and as documents are opened or closed.

There are several different types of font names:

The PostScript name is a unique, ASCII name that can be stored in files to identify a font. For multiple master instances, it includes the specific design axis values.
The Illustrator PostScript name is the PostScript name with a suffix identifying the encoding. It can also be stored in a file to identify a font.
A user name is a display name, which can be in ASCII or a localized encoding. There can be several such names; for example a full name describing the font, and the font family name.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIFontSuite and kAIFontVersion.

Member Data Documentation

AIAPI AIErr(* AIFontSuite::ConvertCharacterToGlyphID)(AIFontKey fontKey, const char *ch, ai::int32 srcLen, enum AIMetricOrientation orientation, AIGlyphID *glyphID)

Translates a character value to a single glyph in a given font.

Parameters:

	fontKey	The font key.
	ch	A string containing the character. Extracts at most one glyph, using as many bytes as needed to form one glyph, starting with the first byte pointed to by `ch`. Derives the encoding from the font.
	srcLen	The number of bytes in `ch`.
	orientation	The text orientation, vertical or horizontal.
	glyphID	[out] A buffer in which to return the glyph identifier, or undefined glyph for the font if a glyph is not defined for this character.

Returns:: The error kGlyphNotDefinedErr if a glyph is not defined for this character.

AIAPI AIErr(* AIFontSuite::ConvertUnicodeToGlyphID)(AIFontKey fontKey, const ASUnicode *ch, ai::int32 srcLen, enum AIMetricOrientation orientation, AIGlyphID *glyphID)

Translates a Unicode character value to a single glyph in a given font.

Parameters:

	fontKey	The font key.
	ch	A UTF16-encoded string containing the character. Extracts at most one glyph, using as many characters as needed to form one glyph, starting with the first character pointed to by `ch`.
	srcLen	The number of `ASUnicode` characters (not bytes) in `ch`.
	orientation	The text orientation, vertical or horizontal.
	glyphID	[out] A buffer in which to return the glyph identifier, or undefined glyph for the font if a glyph is not defined for this character.

Returns:: The error kGlyphNotDefinedErr if a glyph is not defined for this character.

AIAPI AIErr(* AIFontSuite::CountFonts)(ai::int32 *count)

Gets the total number of available fonts.

Variations, such as "Times Roman Regular" and "Times Roman Italic" are counted as distinct fonts. Use with IndexFontList() to iterate through available fonts.

Parameters:

count

[out] A buffer in which to return the number of fonts.

AIAPI AIErr(* AIFontSuite::CountGlyphs)(AIGlyphSet theSet, int *glyphCountResult)

Gets the number of glyphs within a glyph set.

Use with GetGlyphInfo() to iterate through glyphs.

Parameters:

	theSet	The glyph set object.
	glyphCountResult	[out] A buffer in which to return the number of glyphs.

AIAPI AIErr(* AIFontSuite::CountTypefaces)(ai::int32 *count)

Gets the total number of font families.

Variants, such as italic and bold, are counted as a single family. Use with IndexTypefaceList() to iterate through available font families.

Parameters:

count

[out] A buffer in which to return the number of font families.

AIAPI AIErr(* AIFontSuite::CountTypefaceStyles)(AITypefaceKey typeface, ai::int32 *count)

Gets the total number of variants (such as bold and italic) of a font family.

Use with IndexTypefaceStyleList() to iterate through variants.

Parameters:

	typeface	The font family, as returned by `IndexTypefaceList()`.
	count	[out] A buffer in which to return the number of variants.

AIAPI AIErr(* AIFontSuite::FindFont)(const char *postscriptName, enum AIFontTechnology fontTechnology, AIFaceScript script, AIBoolean substituteFlag, AIFontKey *result)

Finds a font matching specific criteria.

Parameters:

	postscriptName	The PostScript font name, such as "Times-Roman", or Illustrator PostScript font name.
	fontTechnology	The font type, such as Adobe or TrueType, an `AIFontTechnology` value.
	script	The language for which the font was designed; an `AIFaceScript` value.
	substituteFlag	When true, returns a substitute if an exact match is not found.
	result	[out] A buffer in which to return the font key.

AIAPI AIErr(* AIFontSuite::FindMacFontFromMacFontRef)(AIMacFontRef macFontRef, AIFontKey *result)

Finds an Illustrator font matching a Mac OS system font.

Parameters:

	fontRef	The Mac OS ATS font ref
	result	[out] A buffer in which to return the font key.

AIAPI AIErr(* AIFontSuite::FindWinFont)(AILOGFONTA *logFont, AIFontKey *result)

Not implemented.

AIAPI AIErr(* AIFontSuite::FontFromFontKey)(AIFontKey font, FontRef *result)

Converts an Illustrator font key to an Adobe Text Engine (ATE) font reference, for use with ATE functions.

Parameters:

	font	The font key.
	result	[out] A buffer in which to return the ATE font reference.

See also:: ATETypes.h

AIAPI AIErr(* AIFontSuite::FontKeyFromFont)(FontRef font, AIFontKey *result)

Converts an Adobe Text Engine (ATE) font reference to an Illustrator font key.

Parameters:

	font	The ATE font reference.
	result	[out] A buffer in which to return the font key.

See also:: ATETypes.h

AIAPI AIErr(* AIFontSuite::GetAlternateGlyphs)(AIGlyphInfo glyphInfo, AIGlyphSet *result)

Retrieves the set of alternate glyphs for a given glyph.

Parameters:

	glyphInfo	The glyph information, as returned by `GetGlyphInfo()`.
	result	[out] A buffer in which to return the alternative glyph set.

AIAPI AIErr(* AIFontSuite::GetCharDimensions)(AIFontKey font, const char *charPtr, enum AIMetricOrientation orientation, AIReal *hResult, AIReal *vResult)

Retrieves the default pen displacement for a UTF8-encoded character in a given orientation, for a 1-point font.

Parameters:

	font	The font key.
	charPtr	A pointer to the platform-encoded character.
	orientation	The text orientation (horizontal or vertical).
	hResult	[out] A buffer in which to return the horizontal displacement, in points, or 0 if the orientation is vertical.
	vResult	[out] A buffer in which to return the vertical displacement, in points, or 0 if the orientation is horizontal.

AIAPI AIErr(* AIFontSuite::GetCloselyMatchingFontStyle)(AITypefaceKey old_Family, short *old_Style, AITypefaceKey new_Family, short *new_Style)

Retrieves a font from a given family that is the closest match for a given font from another family.

If the same style is present in the new family, it is selected; otherwise, selects the closest match from the new family.

Parameters:

	old_Family	The typeface of a previously selected font family.
	old_style	The 0-based index of the font style to match within the old family.
	new_Family	The typeface of a new font family, in which to find a match.
	new_style	[out] A bufffer in which to return the 0-based index of the best-match font in the new family.

AIAPI AIErr(* AIFontSuite::GetDefaultFont)(AIFaceScript script, AIFontKey *result)

Retrieves the default font for a language script.

Parameters:

	script	The language script.
	result	[out] A buffer in which to return the font key.

AIAPI AIErr(* AIFontSuite::GetFontFamilyNameUnicode)(AIFontKey fontKey, ai::UnicodeString &name, AIBoolean native)

Retrieves the user name for the family of a font (for example, "Times Roman").

This might not be the same as the display name; retrieve the display name with GetFontFamilyUINameUnicode().

Parameters:

	fontKey	The font key.
	name	[out] A buffer in which to return the name string.
	native	True to get the name in the native language of the font, false to get the name in English, regardless of the font's language.

AIAPI AIErr(* AIFontSuite::GetFontFamilyUIName)(AIFontKey font, char *familyName, ai::int16 maxName)

Retrieves the display name for the family of a font (for example, "Times Roman").

The name is encoded either in ASCII or in the encoding of the font, depending on the preference setting for using English font names.

Parameters:

	font	The font key.
	familyName	[out] A buffer in which to return the name.
	maxName	The number of characters in the name string buffer. The name string, including the `NULL` terminator, is truncated to this size if necessary.

AIAPI AIErr(* AIFontSuite::GetFontFamilyUINameUnicode)(AIFontKey fontKey, ASUnicode *familyName, ai::int32 maxName)

Retrieves the display name for the family of a font (for example, "Times Roman") in Unicode (UTF16).

The name is either in English or the native language of the font depending on the setting of the preference to use English font names.

Parameters:

	fontKey	The font key.
	familyName	[out] A buffer in which to return the name.
	maxName	The number of characters in the name string buffer. The name string, including the `NULL` terminator, is truncated to this size if necessary.

AIAPI AIErr(* AIFontSuite::GetFontFilePathCount)(AIFontKey fontKey, ai::uint32 &count)

Reports how many files constitute a font.

For example, a Windows Type 1 font has a PFB and a PFM file, and a Mac Type 1 font has a suitcase and an outline file, but an OpenType font has only a single file. Use with GetNthFilePath() to access the files.

If the font is fauxed, returns the information for the underlying font used to faux the missing font. Check whether the font is fauxed using GetFontInfo().

Parameters:

	fontKey	The font key.
	count	[out] A buffer in which to return the number of files. This can be 0 for some fonts; see `GetNthFilePath()`.

Note:: This function does not distinguish between two identical font files and two different files for the same font.

AIAPI AIErr(* AIFontSuite::GetFontInfo)(AIFontKey font, struct AIFontStyle *result)

Retrieves the font information for a font.

Parameters:

	theKey	The font key.
	result	[out] A buffer in which to return the font information structure.

AIAPI AIErr(* AIFontSuite::GetFontInstance)(AIGlyphSet glyphSetOpaque, AIFontInst **result)

Retrieves the font that contains a glyph set.

Parameters:

	glyphSetOpaque	The glyph set.
	result	[out] A buffer in which to return the font object.

AIAPI AIErr(* AIFontSuite::GetFontIsSubstituted)(AIFontKey fontKey, AIBoolean &outIsSubstituted)

Retrieves whether a font is substituted or not.

Parameters:

	fontKey	The font key.
	outIsSubstituted	[out] A buffer in which to return the boolean value.

AIAPI AIErr(* AIFontSuite::GetFontMetrics)(AIFontKey font, struct AIFontMetrics *result)

Retrieves the font metrics for a font.

Parameters:

	theKey	The font key.
	result	[out] A buffer in which to return the font metrics structure.

AIAPI AIErr(* AIFontSuite::GetFontStyleName)(AIFontKey font, char *styleName, ai::int16 maxName)

Retrieves the ASCII-encoded name for the variant of a font (for example, "Bold Italic").

Parameters:

	font	The font key.
	styleName	[out] A buffer in which to return the name.
	maxName	The number of characters in the name string buffer. The name string, including the `NULL` terminator, is truncated to this size if necessary.

AIAPI AIErr(* AIFontSuite::GetFontStyleNameUnicode)(AIFontKey fontKey, ai::UnicodeString &name, AIBoolean native)

Retrieves the user name for the style of a font (for example, "Bold Italic").

This might not be the same as the display name; retrieve the display name with GetFontStyleUINameUnicode().

Parameters:

	fontKey	The font key.
	name	[out] A buffer in which to return the name string.
	native	True to get the name in the native language of the font, false to get the name in English, regardless of the font's language.

AIAPI AIErr(* AIFontSuite::GetFontStyleUIName)(AIFontKey font, char *styleName, ai::int16 maxName)

Retrieves the display name for the variant of a font (for example, "Bold Italic").

The name is encoded either in ASCII or in the encoding of the font, depending on the preference setting for using English font names.

Parameters:

	font	The font key.
	styleName	[out] A buffer in which to return the name.
	maxName	The number of characters in the name string buffer. The name string, including the `NULL` terminator, is truncated to this size if necessary.

AIAPI AIErr(* AIFontSuite::GetFontStyleUINameUnicode)(AIFontKey fontKey, ASUnicode *styleName, ai::int32 maxName)

Retrieves the display name for the variant of a font (for example, "Bold Italic") in Unicode (UTF16).

The name is either in English or the native language of the font depending on the setting of the preference to use English font names.

Parameters:

	fontKey	The font key.
	styleName	[out] A buffer in which to return the name.
	maxName	The number of characters in the name string buffer. The name string, including the `NULL` terminator, is truncated to this size if necessary.

AIAPI AIErr(* AIFontSuite::GetFullFontName)(AIFontKey font, char *fontName, ai::int16 maxName)

Retrieves the PostScript name of a font, with the encoding information that Illustrator appends.

This name is always encoded in ASCII.

Parameters:

	font	The font key.
	fontName	[out] A buffer in which to return the name.
	maxName	The number of characters in the name string buffer. The name string, including the `NULL` terminator, is truncated to this size if necessary.

AIAPI AIErr(* AIFontSuite::GetGlyphAlternateCount)(AIGlyphInfo theGlyphInfo, int *result)

Retrieves the number of alternate glyphs for a given glyph.

Parameters:

	theGlyphInfo	The glyph information, as returned by `GetGlyphInfo()`.
	result	[out] A buffer in which to return the number of alternative glyphs.

AIAPI AIErr(* AIFontSuite::GetGlyphDimensions)(AIFontKey font, AIGlyphID glyphID, enum AIMetricOrientation orientation, AIReal *hResult, AIReal *vResult)

Retrieves the default pen displacement for a glyph in a given orientation, for a 1-point font.

Parameters:

	font	The font key.
	glyphID	The glyph identifier.
	orientation	The text orientation (horizontal or vertical).
	hResult	[out] A buffer in which to return the horizontal displacement, in points, or `NULL` if the orientation is vertical.
	vResult	[out] A buffer in which to return the vertical displacement, in points, or `NULL` if the orientation is horizontal.

AIAPI AIErr(* AIFontSuite::GetGlyphFontKey)(AIGlyphInfo theGlyphInfo, AIFontKey *result)

Retrieves the font for a glyph.

Parameters:

	theGlyphInfo	The glyph information, as returned by `GetGlyphInfo()`.
	result	[out] A buffer in which to return the font key.

AIAPI AIErr(* AIFontSuite::GetGlyphID)(AIGlyphInfo glyphInfo, AIGlyphID *result)

Retrieves the unique identifier of a glyph.

Parameters:

	glyphInfo	The glyph information, as returned by `GetGlyphInfo()`.
	result	[out] A buffer in which to return the glyph identifier.

AIAPI AIErr(* AIFontSuite::GetGlyphInfo)(AIGlyphSet theSet, ai::int32 glyphIndex, AIGlyphInfo *glyphInfoResult)

Retrieves information about a specific glyph.

Use with CountGlyphs() to iterate through glyphs.

Parameters:

	theSet	The glyph set object.
	glyphIndex	The index position of the glyph, in the range `[1..numGlyphs]`.
	glyphInfoResult	[out] A buffer in which to return the glyph information.

AIAPI AIErr(* AIFontSuite::GetGlyphOTFeatures)(AIGlyphInfo glyphInfo, const char **otFeatures, ai::int32 *otFeatureCount, ai::int32 **otFeatureIndex)

Retrieves the OpenType features associated with a given glyph.

Parameters:

	glyphInfo	The glyph information, as returned by `GetGlyphInfo()`.
	otFeatures	[out] A buffer in which to return the features. Do not modify the returned character array (which is not a null-terminated string). The array contains a set of 4-character feature codes; for example "vertswsh" for a glyph to which 'vert' and 'swsh' features can be applied.
	otFeatureCount	[out] A buffer in which to return the number of features in `otFeatures`.
	otFeatureIndex	[out] A buffer in which to return an array of length `otFeatureCount` containing the number of alternates available for each feature listed in the `otFeatures` array.

AIAPI AIErr(* AIFontSuite::GetGlyphSet)(AIFontKey theFont, ai::int32 otFeature, AIGlyphSet *result)

Retrieves a glyph set, which contains information about alternate glyphs within an OpenType font.

Parameters:

	theFont	An OpenType font.
	otFeature	When zero, gets information about all glyphs. Otherwise, specify the feature of interest, as a 4-byte character sequence (in a `ai::int32`) for an OpenType feature tag.
	result	[out] A buffer in which to return the glyph set. You must release this object using `ReleaseGlyphSet()` when it is no longer needed.

See also:: For the set of registered features tags, https://docs.microsoft.com/en-us/typography/opentype/spec/featuretags

AIAPI ai::int32(* AIFontSuite::GetGlyphsForFeatureAccessInfo)(ai::int32 theFeature, AIFontKey fontKey, AIBoolean existFlag, AIGlyphSet *glyphSet)

Reports whether there are any glyphs for a given Open Type feature in a given font, or retrieves the glyph set containing the glyphs, if any.

(Note that this function returns a numeric value, not an error code.)

Parameters:

	theFeature	The feature, a 4-byte character sequence (in a `ai::int32`) representing an OpenType feature tag.
	fontKey	The font key.
	existFlag	When true, the function reports on whether the font contains any glyphs for the feature. A font can define an OpenType feature, but assign no glyphs to that feature. Use this assure that at least one glyph is present. When false, the function retrieves the glyph set containing the glyphs (if any). This is the same as using `GetGlyphSet()`.
	result	[out] A buffer in which to return the glyph set. You must release this object using `ReleaseGlyphSet()` when it is no longer needed.

Returns:: Non-zero (true) if the font contains at least one glyph for the given feature, zero (false) otherwise.

See also:: For the set of registered features tags, https://docs.microsoft.com/en-us/typography/opentype/spec/featuretags

AIAPI AIErr(* AIFontSuite::GetGlyphUnicodeValue)(AIGlyphID mGlyphID, AIFontKey fontKey, const char *desiredOTFeature, ASUnicode *theChar, int *resultLength, char **otFeatures, ai::int32 *otFeatureCount, ai::int32 **otFeatureIndex)

Retrieves the Unicode character for a given glyph in a given font, with information about what OpenType features were applied.

Parameters:

	mGlyphID	The glyph identifier.
	fontKey	The font key.
	desiredOTFeature	A string containing the OpenType features of interest. See `GetGlyphOTFeatures()`. The mapping of glyphs and feature sets to characters is not 1:1, so the returned character can have a different set of features than those requested.
	theChar	[out] A buffer in which to return the Unicode character.
	resultLength	[out] A buffer in which to return the number of features in `theChar`.
	otFeatures	[out] A buffer in which to return the OpenType features set that was applied to `theChar`. See `GetGlyphOTFeatures()`. You must release this memory with `SPBasicSuite::FreeBlock()` when it is no longer needed.
	otFeatureCount	[out] A buffer in which to return the number of features in `otFeatures`.
	otFeatureIndex	[out] A buffer in which to return an array of length `otFeatureCount` containing the number of alternates available for each feature listed in the `otFeatures` array. You must release this memory with `SPBasicSuite::FreeBlock()` when it is no longer needed.

AIAPI AIErr(* AIFontSuite::GetICFBox)(AIFontKey fontKey, AIRealRect &icfBox)

Retrieves the ideographic character face (IFC) bounds of a font.

The ICF-box is the maximum bounding box of the ideographic portion of a CJK font, usually centered within the em-box. The value is also defined also for non-CJK fonts. The coordinate values are relative to the font coordinate system's origin. X values increase to the right and Y values increase downward.

Parameters:

	fontKey	The font key.
	icfBox	[out] A buffer in which to return the bounding box

See also:: Baseline tags icfb and icft in the OpenType tag registry.

AIAPI AIErr(* AIFontSuite::GetIdeoEmBox)(AIFontKey fontKey, AIRealRect &ideoEmBox)

Retrieves the ideographic em-box of a font, also known as an ideographic font's design space.

This defines a standard monospaced escapement around the glyphs of the font, for both horizontal and vertical writing modes. It is one em high and one em wide unless the vendor explicitly indicates otherwise in the font. The OpenType specification strongly recommends against this being other than an em wide, but there are legitimate reasons for it to be other than one em high: some fonts used in Japanese newspaper layout, for example, have a vertically compressed ideographic em-box.

The returned value, an array with the left, top, right, and bottom edges (in horizontal writing mode) of the ideographic em-box of a 1-unit-em font, is defined for every font (including non-CJK fonts, where it can be used to em-box-align these fonts alongside CJK fonts).

The coordinate values are relative to the font coordinate system's origin. X values increase to the right and Y values increase downward.

Parameters:

	fontKey	The font key.
	ideoEmBox	[out] A buffer in which to return the bounding box,

See also:: Baseline tag ideo in the OpenType tag registry for more information.

AIAPI AIErr(* AIFontSuite::GetMacFontRef)(AIFontKey fontKey, AIMacFontRef &macFontRef)

Retrieves the Mac OS ATS font ref for an Illustrator font.

If the given font does not correspond to a system font, gets the default system font.

Parameters:

	fontKey	The font key.
	macFontRef	[out] A buffer in which to return the Mac OS ATS font ref.

AIAPI AIErr(* AIFontSuite::GetNthATCComponent)(AIFontKey fontKey, ai::uint32 n, AIFontKey &componentFontKey)

Retrieves a component for an ATC font, by position index.

Use with GetNumATCComponents() to access font components.

If the font is fauxed, returns the information for the underlying font used to faux the missing font. Check whether the font is fauxed, and that it is an ATC font, using GetFontInfo().

Parameters:

	fontKey	The font key.
	n	The position index of the component, the range `[0..numATCComponents-1]`.
	componentFontKey	[out] A buffer in which to return the component font key.

AIAPI AIErr(* AIFontSuite::GetNthFilePath)(AIFontKey fontKey, ai::uint32 n, ai::FilePath &filePath)

Retrieves a file path associated with a font.

Use with GetFontFilePathCount() to access font files.

This method does not work for fonts whose paths Illustrator does not know, such as Windows bitmap fonts, and Mac OS bitmap-only fonts. For an ATC font, gets the location of the top-level rearrangement file only. To get the paths of component fonts, iterate over the component dictionaries.

If the font is fauxed, returns the information for the underlying font used to faux the missing font. Check whether the font is fauxed using GetFontInfo().

Parameters:

	fontKey	The font key.
	n	The position index of the file path, the range `[0..pathCount-1]`.
	filePath	[out] A buffer in which to return the path.

AIAPI AIErr(* AIFontSuite::GetNumATCComponents)(AIFontKey fontKey, ai::uint32 &count)

Gets the number of ATC components for a font.

If the font is fauxed, returns the information for the underlying font used to faux the missing font. Check whether the font is fauxed, and that it is an ATC font, using GetFontInfo().

Parameters:

	fontKey	The font key.
	count	[out] A buffer in which to return the number of ATC components. This is 0 for a non-ATC font.

AIAPI AIErr(* AIFontSuite::GetOTFeatures)(AIFontKey theFont, ai::int32 *featureList, ai::int32 *featureCount)

Retrieves all OpenType features supported by a particular font.

Parameters:

	theFont	The font key.
	featureList	[in, out] An array of OpenType features of length `featureCount`. Each value is a 4-byte character sequence (in a `ai::int32`) representing an OpenType feature tag. Caller must provide the array. Pass NULL to obtain the size of the array required.
	featureCount	[out] A buffer in which to return the size of array required for `featureList`.

See also:: For the set of registered features tags, https://docs.microsoft.com/en-us/typography/opentype/spec/featuretags

AIAPI AIErr(* AIFontSuite::GetPostScriptFontName)(AIFontKey fontKey, char *postScriptFontName, ai::int16 maxName)

Retrieves the Illustrator PostScript name of a font (with encoding information appended).

This uniquely identifies a font, for example, in a file. This name is always encoded in ASCII.

Parameters:

	font	The font key.
	postScriptFontName	[out] A buffer in which to return the name.
	maxName	The number of characters in the name string buffer. The name string, including the `NULL` terminator, is truncated to this size if necessary.

AIAPI AIErr(* AIFontSuite::GetSystemFontName)(AIFontKey fontKey, char *result, ai::int16 maxName)

Retrieves typeface name of a font, or the system name for a system font in Windows.

Parameters:

	fontKey	The font key.
	result	[out] A buffer in which to return the typeface name, or, in Windows only, the face name of the WindowsLogFont if the font is a system font..
	maxName	The number of characters in the name string buffer. The name string, including the `NULL` terminator, is truncated to this size if necessary.

AIAPI AIErr(* AIFontSuite::GetTypefaceName)(AITypefaceKey typeface, char *name, ai::int16 maxName)

Retrieves the ASCII-encoded name for a font family (for example, "Times Roman").

Parameters:

	typeface	The font family key.
	name	[out] A buffer in which to return the name.
	maxName	The number of characters in the name string buffer. The name string, including the `NULL` terminator, is truncated to this size if necessary.

AIAPI AIErr(* AIFontSuite::GetTypefaceUnicodeMenuName)(AITypefaceKey typeface, ai::UnicodeString &typefaceName)

AIAPI AIErr(* AIFontSuite::GetUndefinedGlyphID)(AIGlyphSet theSet, AIGlyphID *undefinedGlyphIDResult)

Retrieves the undefined glyph for a glyph set.

Each font has one undefined glyph, but not every glyph set contains one. Use HasUndefinedGlyph() to check.

Parameters:

	theSet	The glyph set.
	undefinedGlyphIDResult	[out] A buffer in which to return the glyph identifier.

AIAPI AIErr(* AIFontSuite::GetUserFontName)(AIFontKey font, char *userfontName, ai::int16 maxName)

Retrieves the full ASCII-encoded name for a font (for example, "Times Roman Bold Italic").

The name is always encoded in ASCII.

Parameters:

	font	The font key.
	userfontName	[out] A buffer in which to return the name.
	maxName	The number of characters in the name string buffer. The name string, including the `NULL` terminator, is truncated to this size if necessary.

AIAPI AIErr(* AIFontSuite::GetUserFontNameUnicode)(AIFontKey fontKey, ai::UnicodeString &name, AIBoolean native)

Retrieves the full user name for a font (for example, "Times Roman Bold Italic").

This might not be the same as the display name; retrieve the display name with GetUserFontUINameUnicode().

Parameters:

	fontKey	The font key.
	name	[out] A buffer in which to return the name string.
	native	True to get the name in the native language of the font, false to get the name in English, regardless of the font's language.

AIAPI AIErr(* AIFontSuite::GetUserFontUIName)(AIFontKey font, char *userfontName, ai::int16 maxName)

Retrieves the full display name for a font (for example, "Times Roman Bold Italic") The name is encoded either in ASCII or in the encoding of the font, depending on the preference setting for using English font names.

Parameters:

	font	The font key.
	userfontName	[out] A buffer in which to return the name.
	maxName	The number of characters in the name string buffer. The name string, including the `NULL` terminator, is truncated to this size if necessary.

AIAPI AIErr(* AIFontSuite::GetUserFontUINameUnicode)(AIFontKey fontKey, ASUnicode *userfontName, ai::int32 maxName)

Retrieves the full display name for a font (for example, "Times Roman Bold Italic") in Unicode (UTF16).

The name is either in English or the native language of the font depending on the setting of the preference to use English font names.

Parameters:

	fontKey	The font key.
	userfontName	[out] A buffer in which to return the name.
	maxName	The number of characters in the name string buffer. The name string, including the `NULL` terminator, is truncated to this size if necessary.

AIAPI AIErr(* AIFontSuite::GetVersionString)(AIFontKey fontKey, ai::UnicodeString &versionString)

Retrieves the version string for a font file.

If the font object is fauxed, gets version information for the underlying font. You can check whether the font is fauxed using GetFontInfo().

Parameters:

	fontKey	The font key.
	versionString	[out] A buffer in which to return the version string.

AIAPI AIErr(* AIFontSuite::GlyphIDToIndex)(AIGlyphSet theSet, AIGlyphID glyphID, int *glyphIndexResult)

Gets the ordinal position of a given glyph within a glyph set.

Parameters:

	theSet	The glyph set object.
	glyphID	The unique identifier of the glyph.
	glyphIndex	[out] A buffer in which to return the index position of the glyph, in the range `[1..numGlyphs]`.

AIAPI AIBoolean(* AIFontSuite::HasUndefinedGlyph)(AIGlyphSet theSet)

Reports whether a glyph set contains an undefined glyph.

Each font has one undefined glyph, but not every glyph set contains one. Use GetUndefinedGlyphID to retrieve it if there is one. (Note that this function returns a boolean value, not an error code.)

Parameters:

theSet

The glyph set.

Returns:: True if the set contains an undefined glyph.

AIAPI AIErr(* AIFontSuite::ImportCompositeFonts)(const ai::FilePath &source)

Imports composite fonts from an AI or ATC file into the current document.

Parameters:

source

The AI or ATC file path.

AIAPI AIErr(* AIFontSuite::IndexFontList)(ai::int32 index, AIFontKey *fontKey)

Retrieves a font by index position.

Use with CountFonts() to iterate through available fonts. Font indices can change as fonts are added and removed.

Parameters:

	index	The 0-based position index.
	fontKey	[out] A buffer in which to return the font key.

AIAPI AIErr(* AIFontSuite::IndexTypefaceList)(ai::int32 index, AITypefaceKey *typeFaceKey)

Retrieves a font family by index position.

Use with CountTypefaces() to iterate through available font families. Indices can change as fonts are added and removed.

Parameters:

	index	The 0-based position index.
	typeFaceKey	[out] A buffer in which to return the font family key.

AIAPI AIErr(* AIFontSuite::IndexTypefaceListSortedByDefaultScript)(AITypefaceKey *typeface, ai::int32 index)

Retrieves a font family by index position, from the list of all available font families.

Use with CountTypefaces() to iterate through available font families. Indices can change as fonts are added and removed.

Parameters:

	index	The 0-based position index.
	typeFaceKey	[out] A buffer in which to return the font family key.

AIAPI AIErr(* AIFontSuite::IndexTypefaceStyleList)(AITypefaceKey typeface, ai::int32 index, AIFontKey *fontKey)

Retrieves a variant of a font family by index position.

Use with CountTypefaceStyles() to iterate through variants.

Parameters:

	typeface	The font family, as returned by `IndexTypefaceList()`.
	index	The 0-based position index.
	fontKey	[out] A buffer in which to return the font key.

AIAPI AIErr(* AIFontSuite::ReleaseGlyphSet)(AIGlyphSet theSet)

Disposes of a glyph set object.

Parameters:

theSet The object, as returned by GetGlyphSet().

AIAPI AIErr(* AIFontSuite::SetCharWidths)(AIFontKey fontKey, AIReal *charWidths)

Sets the character widths for a fauxed, single-byte, horizontal font.

Parameters:

	fontKey	The font key.
	charWidths	A pointer to the new array of width values, in points. This is an array of 256 values where each entry is the advance override for the corresponding glyph.

AIAPI AIErr(* AIFontSuite::TypefaceAndStyleFromFontKey)(AIFontKey theKey, AITypefaceKey *typefaceResult, ai::int16 *styleResult)

Retrieves the family and variant of a font.

Parameters:

	theKey	The font key.
	typefaceResult	[out] A buffer in which to return the font family key.
	styleResult	[out] A buffer in which to return the index position of the family variant (such as bold or italic).

The documentation for this struct was generated from the following file:

AIFont.h

AIFontSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AIFontSuite Struct Reference
[API Suite List]