Class FontSubstitutionSettings

  • java.lang.Object
    • com.aspose.words.FontSubstitutionSettings
public class FontSubstitutionSettings 
extends java.lang.Object

Specifies font substitution mechanism settings.

Font substitution process consists of several rules which are checked one by one in specific order. If the first rule can't resolve the font then second rule is checked and so on.

The order of the rules is following: 1. Font config substitution rule (disabled by default) 2. Table substitution rule (enabled by default) 3. Font info substitution rule (enabled by default) 4. Default font rule (enabled by default)

Note that font info 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 font config substitution rule will resolve the font in most cases and thus overrides all other rules.


Shows how to access a document's system font source and set font substitutes.
Document doc = new Document();

// Create a font settings object for our document
doc.setFontSettings(new FontSettings());

// By default we always start with a system font source
Assert.assertEquals(doc.getFontSettings().getFontsSources().length, 1);

SystemFontSource systemFontSource = (SystemFontSource) doc.getFontSettings().getFontsSources()[0];
Assert.assertEquals(systemFontSource.getType(), FontSourceType.SYSTEM_FONTS);
Assert.assertEquals(systemFontSource.getPriority(), 0);

if (System.getProperty("").startsWith("Windows")) {
    Assert.assertEquals(SystemFontSource.getSystemFontFolders(), new String[]{"C:\\WINDOWS\\Fonts"});

for (String systemFontFolder : SystemFontSource.getSystemFontFolders()) {

// Set a font that exists in the windows fonts directory as a substitute for one that doesn't
doc.getFontSettings().getSubstitutionSettings().getTableSubstitution().addSubstitutes("Kreon-Regular", new String[]{"Calibri"});

long substituteSize ="Kreon-Regular").spliterator(), false).count();
Assert.assertEquals(substituteSize, 1);

// Alternatively, we could add a folder font source in which the corresponding folder contains the font
FolderFontSource folderFontSource = new FolderFontSource(getFontsDir(), false);
doc.getFontSettings().setFontsSources(new FontSourceBase[]{systemFontSource, folderFontSource});
Assert.assertEquals(2, doc.getFontSettings().getFontsSources().length);

// Resetting the font sources still leaves us with the system font source as well as our substitutes

Assert.assertEquals(1, doc.getFontSettings().getFontsSources().length);
Assert.assertEquals(FontSourceType.SYSTEM_FONTS, doc.getFontSettings().getFontsSources()[0].getType());
Assert.assertEquals(1, IterableUtils.size(doc.getFontSettings().getSubstitutionSettings().getTableSubstitution().getSubstitutes("Kreon-Regular")));

Property Getters/Setters Summary
Settings related to default font substitution rule.
Settings related to font config substitution rule.
Settings related to font info substitution rule.
Settings related to table substitution rule.

    • Property Getters/Setters Detail

      • getDefaultFontSubstitution

        public DefaultFontSubstitutionRule getDefaultFontSubstitution()
        Settings related to default font substitution rule.


        Shows how to set the default font substitution rule.
        // Create a blank document and a new FontSettings property
        Document doc = new Document();
        FontSettings fontSettings = new FontSettings();
        // Get the default substitution rule within FontSettings, which will be enabled by default and will substitute all missing fonts with "Times New Roman"
        DefaultFontSubstitutionRule defaultFontSubstitutionRule = fontSettings.getSubstitutionSettings().getDefaultFontSubstitution();
        Assert.assertEquals("Times New Roman", defaultFontSubstitutionRule.getDefaultFontName());
        // Set the default font substitute to "Courier New"
        defaultFontSubstitutionRule.setDefaultFontName("Courier New");
        // Using a document builder, add some text in a font that we don't have to see the substitution take place,
        // and render the result in a PDF
        DocumentBuilder builder = new DocumentBuilder(doc);
        builder.getFont().setName("Missing Font");
        builder.writeln("Line written in a missing font, which will be substituted with Courier New.");
        + "Font.DefaultFontSubstitutionRule.pdf");
      • getFontConfigSubstitution

        public FontConfigSubstitutionRule getFontConfigSubstitution()
        Settings related to font config substitution rule.


        Shows OS-dependent font config substitution.
        // Create a new FontSettings object and get its font config substitution rule
        FontSettings fontSettings = new FontSettings();
        FontConfigSubstitutionRule configSubstitution = fontSettings.getSubstitutionSettings().getFontConfigSubstitution();
        // The FontConfigSubstitutionRule object works differently on Windows/non-Windows platforms
        final String OS = System.getProperty("").toLowerCase();
        // On Windows, it is unavailable
        if (OS == "win") {
        // On Linux/Mac, we will have access and will be able to perform operations
        if (OS == "nix") {
      • getFontInfoSubstitution

        public FontInfoSubstitutionRule getFontInfoSubstitution()
        Settings related to font info substitution rule.


        Shows how to set the property for finding the closest match font among the available font sources instead missing font.
        public void enableFontSubstitution() throws Exception {
            Document doc = new Document(getMyDir() + "Missing font.docx");
            // Assign a custom warning callback
            HandleDocumentSubstitutionWarnings substitutionWarningHandler = new HandleDocumentSubstitutionWarnings();
            // Set a default font name and enable font substitution
            FontSettings fontSettings = new FontSettings();
            // When saving the document with the missing font, we should get a warning
   + "Font.EnableFontSubstitution.pdf");
            // List all warnings using an enumerator
            Iterator<WarningInfo> warnings = substitutionWarningHandler.FontWarnings.iterator();
            try /*JAVA: was using*/ {
                while (warnings.hasNext())
            } finally {
                if (warnings != null) warnings.remove();
            // Warnings are stored in this format
            Assert.assertEquals(WarningSource.LAYOUT, substitutionWarningHandler.FontWarnings.get(0).getSource());
            Assert.assertEquals("Font '28 Days Later' has not been found. Using 'Calibri' font instead. Reason: alternative name from document.",
            // The warning info collection can also be cleared like this
        public static class HandleDocumentSubstitutionWarnings implements IWarningCallback {
            /// <summary>
            /// Our callback only needs to implement the "Warning" method. This method is called whenever there is a
            /// potential issue during document processing. The callback can be set to listen for warnings generated during document
            /// load and/or document save.
            /// </summary>
            public void warning(WarningInfo info) {
                // We are only interested in fonts being substituted
                if (info.getWarningType() == WarningType.FONT_SUBSTITUTION)
            public WarningInfoCollection FontWarnings = new WarningInfoCollection();
      • getTableSubstitution

        public TableSubstitutionRule getTableSubstitution()
        Settings related to table substitution rule.


        Shows how to work with custom font substitution tables.
        // Create a blank document and a new FontSettings object
        Document doc = new Document();
        FontSettings fontSettings = new FontSettings();
        // Create a new table substitution rule and load the default Windows font substitution table
        TableSubstitutionRule tableSubstitutionRule = fontSettings.getSubstitutionSettings().getTableSubstitution();
        // If we select fonts exclusively from our own folder, we will need a custom substitution table
        FolderFontSource folderFontSource = new FolderFontSource(getFontsDir(), false);
        fontSettings.setFontsSources(new FontSourceBase[]{folderFontSource});
        // There are two ways of loading a substitution table from a file in the local file system
        // 1: Loading from a stream
        InputStream fileStream = new FileInputStream(getMyDir() + "Font substitution rules.xml");
        try {
        } finally {
            if (fileStream != null) fileStream.close();
        // 2: Load directly from file
        tableSubstitutionRule.load(getMyDir() + "Font substitution rules.xml");
        // Since we no longer have access to "Arial", our font table will first try substitute it with "Nonexistent Font", which we don't have,
        // and then with "Kreon", found in the "MyFonts" folder
        Assert.assertEquals(tableSubstitutionRule.getSubstitutes("Arial"), Arrays.asList(new String[]{"Missing Font", "Kreon"}));
        // If we find this substitution table lacking, we can also expand it programmatically
        // In this case, we add an entry that substitutes "Times New Roman" with "Arvo"
        Assert.assertNull(tableSubstitutionRule.getSubstitutes("Times New Roman"));
        tableSubstitutionRule.addSubstitutes("Times New Roman", "Arvo");
        Assert.assertEquals(tableSubstitutionRule.getSubstitutes("Times New Roman"), Arrays.asList(new String[]{"Arvo"}));
        // We can add a secondary fallback substitute for an existing font entry with AddSubstitutes()
        // In case "Arvo" is unavailable, our table will look for "M+ 2m"
        tableSubstitutionRule.addSubstitutes("Times New Roman", "M+ 2m");
        Assert.assertEquals(tableSubstitutionRule.getSubstitutes("Times New Roman"), Arrays.asList(new String[]{"Arvo", "M+ 2m"}));
        // SetSubstitutes() can set a new list of substitute fonts for a font
        tableSubstitutionRule.setSubstitutes("Times New Roman", new String[]{"Squarish Sans CT", "M+ 2m"});
        Assert.assertEquals(tableSubstitutionRule.getSubstitutes("Times New Roman"), Arrays.asList(new String[]{"Squarish Sans CT", "M+ 2m"}));
        // TO demonstrate substitution, write text in fonts we have no access to and render the result in a PDF
        DocumentBuilder builder = new DocumentBuilder(doc);
        builder.writeln("Text written in Arial, to be substituted by Kreon.");
        builder.getFont().setName("Times New Roman");
        builder.writeln("Text written in Times New Roman, to be substituted by Squarish Sans CT.");
        + "Font.TableSubstitutionRule.Custom.pdf");