Skip to end of metadata
Go to start of metadata

How Aspose.Words Uses True Type Fonts

Aspose.Words requires TrueType fonts when rendering documents to fixed-page formats (PDF, XPS). When Aspose.Words renders a document, it needs to subset and embed TrueType fonts into the resulting document. This is normal practice during PDF or XPS generation and it ensures the document will appear identical for any viewer. Moreover, the XPS specification requires that fonts are always embedded in the document.

For Aspose.Words to ensure the best fidelity, to successfully measure characters and embed fonts, the following conditions need to be met:

  • Aspose.Words needs to be able to find and access TrueType font’s files on the system.
  • There should be sufficient TrueType fonts available to Aspose.Words, preferably with the same font family names as used in the document.

Font Availability and Substitution

Text in a document is formatted using various fonts such as Arial, Times New Roman, Verdana, and others. When Aspose.Words renders a document it attempts to select the fonts that are specified by the document. However, there are situations when the exact font cannot be found and Aspose.Words must substitute a similar font instead. The exact process of this is explained below.Aspose.Words selects the fonts according to the following process:

  1. Aspose.Words tries to find a font on the file system with an exact font name match.
  2. Next, Aspose.Words tries to find the required font among the fonts embedded in the original document. Some document formats such as DOCX can contain embedded fonts.
  3. If Aspose.Words is unable to locate the defined font with the exact name match and AltName is defined then it will find the font defined with AltName from FontInfo.
  4. If Aspose.Words is unable to locate the font defined and AltName is also not defined then the following font substitution rules shall apply
    1. Aspose.Words will attempt to select font defined in fontconfig utility which is designed to provide system-wide font configuration substitution. This rule is disabled by default.
    2. Table substitution rule is enabled by default and Aspose.Words shall substitute font by this rule if not substituted with fontconfig. By this rule, the list of substitute font names to be used if the original font is not available and substitutes will be checked for the font name and the FontInfo.AltName.
    3. Font info substitution rule shall be applied if table substitution rule fails to find the font. This rule is also enabled by default. According to this rule, Aspose.Words evaluates all the related fields in FontInfo (Panose, Sig etc) for the missing font and finds the closest match among the available font sources. If FontInfo is not available for the missing font then nothing will be done.
    4. Default font substitution shall be applied if font info substitution also fails. This rule is also enabled by default. According to this rule, Aspose.Words will attempt to use the default font specified under FontSettings.SubstitutionSettings.DefaultFontSubstitution.DefaultFontName. If the user has not chosen their own default font then "Times New Roman" is the selected default font to be used.
  5. Finally, if Aspose.Words cannot find any fonts on the file system, it renders the document using the free Fanwood font that is embedded into the Aspose.Words assembly.


Note that font substitution rule will always resolve the font if FontInfo is available and will override the default font rule. If you want to use the default font rule then you should disable the font info substitution rule.

Note that the font config substitution rule will resolve the font in most of the cases and thus overrides all other rules.

Font FallBack Settings from XML

In Aspose.Words there are two different mechanisms - font substitution and font fallback. Font substitution is used when the font specified in the document couldn't be found among the font sources as described in the above section.

Font fallback is used when the font is resolved but it doesn't contain a specific character. In this case, Aspose.Words tries to use one of the fallback fonts for the character. The list of fallback fonts is predefined for each Unicode range. Currently for a number of ranges Aspose.Words uses only "Arial Unicode MS" font. If there are no fallback fonts available then the character is rendered as a missing glyph from the original font.

You can control the font fallback behavior by using the properties of FontFallbackSettings class. This class specifies font fallback mechanism settings. Below code example shows how to load font fallback settings from the XML file. 

The XML file used in the above code example:

Predefined Font FallBack Settings for Google Noto Fonts

Aspose.Words provides predefined font fallback settings for Google Noto fonts. These are free fonts licensed under SIL OFL and can be downloaded from here ( The FontFallbackSetting class provides LoadNotoFallbackSettings method which loads predefined fallback settings which uses Google Noto fonts as shown in code example given below:

Note that only Sans style Noto fonts with regular weight are used in the predefined settings.

Note that some of the Noto fonts use advanced typography features. Advanced typography is currently not supported by AW and these fonts may be rendered inaccurately.

Where Aspose.Words Looks for Fonts

Aspose.Words attempts to find TrueType fonts on the file system automatically. Most of the times you can rely on the default behavior of Aspose.Words to find TrueType fonts, but sometimes you need to specify your own folders with TrueType fonts. Where Aspose.Words looks for fonts and how to specify your own font locations is explained in the How to Specify True Type Fonts Location topic.

Typical Font-Related Problems and Solutions

This table lists some of the problems that you might encounter when rendering documents to PDF, XPS and SWF using Aspose.Words and their solutions.

Keep in mind when copying any fonts that most fonts are copyrighted. First, locate the license of a font beforehand and verify they can be freely transferred to another machine.



The layout and fonts in the output document are different from the original.

You are using Aspose.Words on Linux or Mac OS. The document uses fonts that are not present on your computer or Aspose.Words cannot locate fonts on your computer.
Copy True Type font files from a Windows machine or install a True Type font package. Use the FontSettings class to specify the location of the font files.

List bullets come out as squares or other symbols.

You are using Aspose.Words on Linux or Mac OS. List bullets most likely require the Symbol or the Wingding font and these fonts are not present on your system. Copy the font files from a Windows machine to your Linux or Mac OS machine to the directory where True Type fonts are installed. Copy the following files:

  • C:\Windows\Fonts\symbol.ttf
  • C:\Windows\Fonts\wingding.ttf

How to Specify True Type Fonts Location

This topic describes:

  • The default behavior of Aspose.Words when searching for TrueType fonts. This behavior depends on the operating system.
  • How to explicitly specify TrueType font folders for Aspose.Words.

Where Aspose.Words Looks for TrueType Fonts on Windows

Aspose.Words looks for fonts in the _%windir%\Fonts folder. This setting will work for you most of the time. You only need to specify your own fonts folders if you need to.Aspose.Words for .NET also looks for any additional fonts registered in the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Fonts registry key.Aspose.Words rendering on a server will typically not work in an ASP.NET application configured to run under the Medium Trust level because it prohibits access to registry and limits access to the file system. To solve this issue you can need to specify your own folders filled with the appropriate fonts as shown below.

Where Aspose.Words Looks for TrueType Fonts on Linux

Different Linux distributions store fonts in different folders. Aspose.Words looks for fonts in several well-known locations. By default, Aspose.Words looks for the fonts in all of the following locations:* /usr/share/fonts* /usr/local/share/fonts* /usr/X11R6/lib/X11/fontsThis default behavior will work for most Linux distributions, but not guaranteed to work all of the time. You might need to specify the location of true type fonts explicitly. To do this, you need to know where TrueType fonts are installed on your Linux distribution.

Where Aspose.Words Looks for TrueType Fonts on Mac OS X

Aspose.Words looks for fonts in the /Library/Fonts folder which is the standard location for TrueType fonts on Mac OS X. This setting will work for you most of the time. You only need to specify your own fonts folders if you need to.

Specifying a Font Folder

The FontSettings.SetFontsFolder method is used to indicate where Aspose.Words should look for fonts. When a valid path is passed to this method, Aspose.Words no longer looks in the registry or the Windows\Font folder to look for fonts and only scans for fonts within the specified folder. When a custom font folder is set using this method, the folder is checked that it exists and is accessible. If the folder cannot be found an exception is thrown.

Below example demonstrates how to set the folder Aspose.Words uses to look for TrueType fonts during rendering or embedding of fonts. You can download the template file of this example from here.

Specifying Multiple Font Folders

The FontSettings class also provides a method to specify multiple folders which are scanned for fonts during rendering. Using the FontSettings.SetFontsFolders method, an array of folder paths can be specified. An extra boolean parameter controls if fonts are scanned recursively through all folders, that is, all child folders of the specified folders are scanned. Below example demonstrates how to set Aspose.Words to look in multiple folders for TrueType fonts when rendering or embedding fonts. You can download the template file of this example from here.

Specifying Fonts to be Read from both the Windows Fonts Folder and a Custom Folder

It is common to want to specify fonts to be read from both the default system folders (e.g Windows\Font directory on a Window’s machine) and from a folder filled with your own fonts. A combination of the FontSettings.GetFontsFolders and FontSettings.SetFontsFolders method can also be used to achieve this. The steps to achieve this involve:# Retrieving an array of the default font folders using the FontSettings.GetFontsFolders method.# Appending your custom folder onto this list.# Pass the new array of font folders to the FontSettings.SetFontsFolders for changes to take effect. Below example demonstrates how to set Aspose.Words to look for TrueType fonts in system folders as well as a custom defined folder when scanning for fonts. You can download the template file of this example from here.

How to Install True Type Fonts on Linux

The most likely scenario is that you are using Aspose.Words to convert DOC or DOCX documents to PDF. If you are doing this on Linux, then this topic explains how to ensure Aspose.Words renders your documents with the best fidelity.

Most of the DOC and DOCX documents that you will convent were probably created by people using Microsoft Word on Windows or Mac OS operating systems. Those people used fonts that were available to them to format the documents. Therefore most fonts that are used by DOC and DOCX documents will be "Windows fonts" or "Office fonts" e.g. the fonts that are installed with Microsoft Windows or with Microsoft Office. These fonts include Arial, Calibri, Cambria, Century Gothic, Courier New, Garamond, Tahoma, Verdana, Wingdings, and many others.

The problem is that the abovementioned TrueType fonts are not installed by default on Linux distributions. If you take a typical DOCX document that is formatted with the Cambria font and try to convert it to PDF on Linux, Aspose.Words will use a different font because Cambria is not available. This will cause the resulting PDF to look different compared to the original DOCX. To make sure that documents converted by Aspose.Words appear as close to the original as possible, you might need to install "Windows fonts" on your Linux system.

There are two main ways to get TrueType fonts on a Linux system:

  • Copy .TTF and .TTC files from a Windows machine to your Linux machine.
  • Install a TrueType font’s package, such as msttcorefonts.

Copy Fonts from a Windows Machine

An easy and quick way is to copy .TTF and .TTC files from the C:\Windows\Fonts directory on a Windows machine to some directory on your Linux machine. You do not need to install or register these fonts on Linux in any way; you just need to specify the location of the fonts using the FontSettings class in Aspose.Words.

As far as we can tell, Microsoft licenses the fonts for anyone to freely use them, but please check the font licensing for you.

Install a TrueType Fonts Package

There are a number of Linux packages that contain Microsoft TrueType fonts that you can download and install onto your Linux machine. The exact steps might be different on different Linux distributions.

  • On Ubuntu, go to the Synaptic Package Manager. Find and install the ttf-mscorefonts-installer package.
  • On openSUSE, go to Yast2, Software Management. Find and install the fetchmsttfonts package.
  • Use Liberation Fonts which are licensed under OFL and are an alternative to standard Windows fonts: Arial, Times New Roman, and Courier New.
  • For font packages for other Linux distributions, please search the documentation and the internet.

How to Get Available Fonts for Rendering

If you want to get the list of fonts that are used to render the PDF document, you can use  FontSourceBase.GetAvailableFonts method as shown in the following code example. PhysicalFontInfo class specifies information about physical font available to Aspose.Words font engine.

  • No labels