Fonts object¶
app.fonts
Note
This functionality was added in After Effects 24.0.
Description
The Fonts objects provides information about the current font ecosystem on your device.
After Effects maintains an internal font proxy to a real font which it has enumerated in the font ecosystem. As the fonts in the font ecosystem are added and removed these internal font proxies are kept in sync as well by being added and removed.
The properties we report via the proxy Font object are the data that is available to us from the font files themselves, which of course will vary according to technology and type of font. It is not possible here to describe all the possible interesting variations and troubles that this causes us and in general it is advisable to be careful with assuming that the behavior and properties for one font type or technology are common to all other font types and technology - the answer as always is “it depends”.
A Font object is a soft reference to one of these internal font proxies and as a consequence is not sufficient to keep the internal font proxy alive. As a result if the internal font proxy is removed, the referencing Font object will throw an invalid exception for any property reference.
On project open, and a few other situations, it may come to pass that the font which is being referenced in the persisted data cannot be found in the current font ecosystem. In these situations an internal font proxy will be created which will contain the desired properties, such as PostScript name, and will return true for isSubstitute. There will be an underlying real font which will be selected to support this internal font proxy, but we do not reveal what it is and there is no way to influence this selection.
Continuing the open process with created substitute fonts, an attempt will be made to sync matching fonts from Creative Cloud Adobe Fonts. This is an asynchronous activity and the project will usually finish opening and be ready for use before any fonts are brought down from Adobe Fonts. Depending on how many fonts are being synced, they may be installed at different times. There is no way to disable this attempt.
After any change to the font ecosystem from installing new real fonts, the outstanding list of substitute fonts will be evaluated to see if there now exists a real font which is a valid replacement for it - currently only requiring the PostScript name to match - and if one is found automatically all the references in the project to the substitute will be replaced with the newly installed font.
Attributes¶
FontsObject.allFonts¶
app.fonts.allFonts
Description
The list of all the fonts currently available on your system.
They are grouped into what is named a family group which are Arrays of Font object.
The Family Name of the group is simply the familyName of any of the Font objects in the group.
The Family Name in one font group is not guaranteed to have unique name compared to different font groups - the grouping is determined by a number of factors including the returned value of FontObject.technology and FontObject.writingScripts.
In addition, it is perfectly acceptable to have multiple fonts with the same PostScript name, though only one will have the same (PostScript name, Technology, Primary Writing Script) tuple. In the case of true duplicates, it is undefined which will be returned and which will be suppressed.
The family groups and Font objects in the group are sorted according to the setting in the Character Panel dropdown “Show Font Names in English”. If set to true, the familyName and styleName property is used, otherwise the nativeFamilyName and nativeStyleName property is used.
Font object for which isSubstitute returns true are always sorted to the end as individual family groups.
Type
Array of Arrays of Font objects; read-only.
Example
This example will select the first returned Font Family Array.
// Getting the first available Font Family Group on the system
var firstFontGroup = app.fonts.allFonts[0];
// Getting the first Style for that Font Family
var firstFontFamilyName = firstFontGroup[0].familyName;
var firstFamilyStyle = firstFontGroup[0].styleName;
alert(firstFontFamilyName+" "+firstFamilyStyle);
FontsObject.favoriteFontFamilyList¶
app.fonts.favoriteFontFamilyList
Note
This functionality was added in After Effects (Beta) 24.4 and subject to change while it remains in Beta.
Description
Provides access to the Favorites list presented in the Character panel and Properties panel. To set the Favorites simply provide an (unsorted) array of strings based on the familyName. To clear the list simply assign an empty Array.
Type
Array of Strings; read/write.
FontsObject.fontsDuplicateByPostScriptName¶
app.fonts.fontsDuplicateByPostScriptName
Note
This functionality was added in After Effects (Beta) 24.4 and subject to change while it remains in Beta.
Description
It is perfectly legal and common for more than one Font object to return the same value for postScriptName but as this can sometimes lead to confusion about what Font object will actually be used when using TextDocument.font or the .font attribute of a CharacterRange object, this property exists to both reveal what duplicates exist and also their relative order.
This an Array in which each element is an Array of Font objects, where the 0th element Font object is considered the primary Font object for the given PostScript name.
Type
Array of Arrays of Font object; read-only.
FontsObject.fontServerRevision¶
app.fonts.fontServerRevision
Note
This functionality was added in After Effects 24.2.
Description
Returns an unsigned number representing the current revision of the font environment.
The revision is advanced when anything happens to the font environment which would change the contents, properties, or order of Font objects returned from a call to FontsObject.allFonts.
Among these are: installing or removing fonts in the font environment, opening or closing a project with substituted fonts, causing a custom Variable font instance to be created, and changing the setting in the Character Panel dropdown “Show Font Names in English”.
Type
Number; read-only.
Example
var fsRev = app.fonts.fontServerRevision;
alert(fsRev);
FontsObject.fontsWithDefaultDesignAxes¶
app.fonts.fontsWithDefaultDesignAxes
Description
Returns an array of variable Font objects, each using a unique font dictionary and with default values for their design axes. This API is a convenient way to quickly filter for a unique instance of each installed variable font.
Type
Array of Font objects; read-only.
Example
var variableFontList = app.fonts.fontsWithDefaultDesignAxes;
alert(variableFontList.length);
FontsObject.freezeSyncSubstitutedFonts¶
app.fonts.freezeSyncSubstitutedFonts
Note
This functionality was added in After Effects (Beta) 24.4 and subject to change while it remains in Beta.
Description
When a Project is opened and one or more fonts are not found in the local font environment, a sync process is initiated with Adobe Fonts to see if one or more Fonts could be activated and installed.
By default this happens automatically—this property will disable it from happening.
Warning
The rules for deciding if Adobe Fonts has a matching font is entirely based on the PostScript name. With some Variable Fonts, due to ambiguity about which font has which named instance, it is possible that more than one face (Regular/Italic) may be installed during an activation. Whether the installed font is a valid replacement is controlled by the FontsObject.substitutedFontReplacementMatchPolicy.
Type
Boolean; read/write. One of:
falseis the default—sync from Adobe Fonts may be attempted.
truemeans that no sync or install will be attempted.
FontsObject.missingOrSubstitutedFonts¶
app.fonts.missingOrSubstitutedFonts
Description
The list of all the missing or substituted fonts of the current Project.
Note
A substituted font is a font that was already missing when the project is opened. A missing font is a font that went missing (font being uninstalled, for example) while the project was open.
Type
Array of Font objects; read-only.
FontsObject.mruFontFamilyList¶
app.fonts.mruFontFamilyList
Note
This functionality was added in After Effects (Beta) 24.4 and subject to change while it remains in Beta.
Description
Provides access to the Most Recently Used (MRU) list presented in the Character panel and Properties panel. To set the MRU simply provide an (unsorted) array of strings based on the familyName. To clear the list simply assign an empty Array.
Type
Array of Strings; read/write.
FontsObject.substitutedFontReplacementMatchPolicy¶
app.fonts.substitutedFontReplacementMatchPolicy
Note
This functionality was added in After Effects (Beta) 24.4 and subject to change while it remains in Beta.
Description
Controls the rules which are used to determine which fonts are considered matching for automatic replacement for a substituted Font object.
Type
A SubstitutedFontReplacementMatchPolicy enumerated value; read/write. One of:
SubstitutedFontReplacementMatchPolicy.POSTSCRIPT_NAMEis the default; any Font object which has the same PostScript name is a valid candidate for replacement of a substituted Font object.SubstitutedFontReplacementMatchPolicy.CTFI_EQUALrequires that the following properties of substituted Font object must match to be considered a valid candidate:writingScripts (primary)
SubstitutedFontReplacementMatchPolicy.DISABLEDmeans that no Font object is an acceptable replacement for a the substituted Font object.
Methods¶
FontsObject.getFontByID()¶
app.fonts.getFontByID(fontID)
Note
This functionality was added in After Effects 24.2.
Description
This function will return an instance of Font object based on the ID of a previously found font.
If no matching font is found, it will return undefined. This can occur with an unknown ID or if the original font has been removed from the font environment.
var font1 = app.fonts.allFonts[0][0];
var font2 = app.fonts.getFontByID(font1.fontID);
alert(font1.fontID == font2.fontID);
Parameters
fontID |
A number containing the ID of the font. |
Returns
Font object, or undefined if no font by that ID.
FontsObject.getFontsByFamilyNameAndStyleName()¶
app.fonts.getFontsByFamilyNameAndStyleName(familyName, styleName)
Description
This function will return an array of Font object based on the Family Name and Style Name of a font. If no suitable font is found, it will return an empty Array.
Note
The returned array length can be more than 1 if you have multiple copies of a same font.
var fontList = app.fonts.getFontsByFamilyNameAndStyleName("Abolition", "Regular")
alert(fontList.length);
Parameters
FamilyName |
A string containing the Family Name of the font. |
StyleName |
A string containing the Style Name of the font. |
Returns
Array of Font objects; read-only.
FontsObject.getFontsByPostScriptName()¶
app.fonts.getFontsByPostScriptName(postscriptName)
Description
This function will return an array of Font objects based on the PostScript name of previously found Fonts.
It is perfectly valid to have multiple Font objects which share the same PostScript name, the order of these is determined by the order in which they were enumerated in the font environment. The entry at [0] will be used when setting the TextDocument.fontObject property.
In addition, there is a special property of this API with regards to Variable fonts. If no Font object matching the requested PostScript exists, but we find that there exist a variable font which matches the requested PostScript name prefix, then this Variable font instance will be requested to create a matching Font object. This is the only way that we will return an instance which did not exist prior to invoking this method.
If no matching font is found, it will return an empty Array.
var fontList = app.fonts.getFontsByPostScriptName("Abolition")
alert(fontList.length);
Parameters
postscriptName |
A string containing the PostScript Name of the font. |
Returns
Array of Font objects; read-only.
FontsObject.pollForAndPushNonSystemFontFoldersChanges()¶
app.fonts.pollForAndPushNonSystemFontFoldersChanges()
Note
This functionality was added in After Effects (Beta) 24.4 and subject to change while it remains in Beta.
Description
The addition and removal of font files in what is considered the system font folders is recognized and handled automatically without user intervention to update the font environment. Non-system font folders are not automatically handled and so additions and removal of font files in these folders are not recognized until the After Effects is restarted.
This function will trigger a check against the known non-system font folders, and if it is recognized that there has been a change, an asynchronous update to the font environment will be scheduled to process this change.
The non-system font folders After Effects knows about are here:
Windows: <systemDrive>:\Program Files\Common Files\Adobe\Fonts
Mac: /Library/Application Support/Adobe/Fonts
Returns
Boolean; One of:
falseif no changes to the font environment are known.trueif a change in the font environment has been detected and an asynchronous update scheduled to deal with it. This state will be cleared once the update has been processed, at which time FontsObject.fontServerRevision will return an incremented value.