Skip to end of metadata
Go to start of metadata

How Aspose.Words Uses True Type Fonts

Aspose.Words require TrueType fonts when rendering documents to fixed-page formats (PDF, XPS or SWF). When Aspose.Words render a document, it needs to subset and embed TrueType fonts into the resulting document. This is a 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 need to be able to find and access TrueType fonts 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 render 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 try to find a font on the file system with an exact font name match.
  2. Next, Aspose.Words try 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 font defined under FontSettings.setDefaultFontName(java.lang.String), it attempts to select the most suitable font from all of the available fonts.
  4. If Aspose.Words cannot find a font with the exact name match, it will attempt to use the default font specified under FontSettings.setDefaultFontName(java.lang.String). If the user has not chosen their own default font then "Times New Roman" is the selected default font that is used. See the How to Set the Default Font used During Rendering topic for further information on setting default font.
  5. Finally, if Aspose.Words cannot find any fonts on the file system, it renders the document using the free Gentium font that is embedded into the Aspose.Words assembly.

    Aspose.Words evaluates all related fields in FontInfo (Panose, Sig etc) and finds the closest match among the available font sources. In case of font substitution the warning is issued. Note that now font substitution mechanism will override the FontSettings.DefaultFontName in cases when FontInfo for the missing font is available in the document. FontSettings.DefaultFontName will be used only in cases when there are no FontInfo for the missing font.

    Note that the fonts which are set by setFontSubstutites()/addFontSubstitutes() methods are checked after the step #2. So if the font is not present in the system but the substitute is found, the font is still considered as properly resolved. In this case, steps #3 to #5 are not performed.

Font substitution and Font fallback in Aspose.Words

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

Font fallback is used when 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 number of ranges Aspose.Words uses only "Arial Unicode MS" font. If there are no fallback fonts available then 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 XML file. 

XML file used in the above code example:

Where Aspose.Words Look for Fonts

Aspose.Words attempt to find TrueType fonts on the file system automatically. Most of the time 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 look 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. For further details see How To Install True Type Fonts on Linux.

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.

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/fonts This 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(java.lang.String,boolean) 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.

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.setFontsFolder(java.lang.String,boolean) method, an array of folder paths can be specified. 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.

Specifying Fonts to be Read from both the System 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.getFontsSources() and FontSettings.setFontsSources(FontSourceBase[] sources) methods can also be used to achieve this. The steps to achieve this involve:

  1. Retrieving an array of the default font sources using the FontSettings.getFontsSources() method.
  2. Appending your custom folder onto this list of font sources.
  3. Pass the new array of font sources to the FontSettings.setFontsSources(FontSourceBase[] sources) 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.

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 render your documents with the best fidelity.

Most of the DOC and DOCX documents that you will convert 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 fonts 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 yourself.

Install a TrueType Fonts Package

There is 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 following code example. PhysicalFontInfo class specifies information about physical font available to Aspose.Words font engine.

  • No labels