com.aspose.words

Class FontSettings

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

Specifies font settings for a document.

Aspose.Words uses font settings to resolve the fonts in the document. Fonts are resolved mostly when building document layout or rendering to fixed page formats. But when loading some formats, Aspose.Words also may require to resolve the fonts. For example, when loading HTML documents Aspose.Words may resolve the fonts to perform font fallback. So it is recommended that you set the font settings in LoadOptions when loading the document. Or at least before building the layout or rendering the document to the fixed-page format.

By default all documents uses single static font settings instance. It could be accessed by DefaultInstance property.

Changing font settings is safe at any time from any thread. But it is recommended that you do not change the font settings while processing some documents which uses this settings. This can lead to the fact that the same font will be resolved differently in different parts of the document.

Example:

Demonstrates how to set the folder Aspose.Words uses to look for TrueType fonts during rendering or embedding of fonts.
Document doc = new Document(getMyDir() + "Rendering.doc");

// Note that this setting will override any default font sources that are being searched by default. Now only these folders will be searched for
// fonts when rendering or embedding fonts. To add an extra font source while keeping system font sources then use both FontSettings.GetFontSources and
// FontSettings.SetFontSources instead.
FontSettings.getDefaultInstance().setFontsFolder("C:\\MyFonts\\", false);

doc.save(getArtifactsDir() + "Rendering.SetFontsFolder.pdf");

Example:

Demonstrates how to set Aspose.Words to look in multiple folders for TrueType fonts when rendering or embedding fonts.
Document doc = new Document(getMyDir() + "Rendering.doc");

// Note that this setting will override any default font sources that are being searched by default. Now only these folders will be searched for
// fonts when rendering or embedding fonts. To add an extra font source while keeping system font sources then use both FontSettings.GetFontSources and
// FontSettings.SetFontSources instead.
FontSettings.getDefaultInstance().setFontsFolders(new String[]{"C:\\MyFonts\\", "D:\\Misc\\Fonts\\"}, true);

doc.save(getArtifactsDir() + "Rendering.SetFontsFolders.pdf");

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.
Document doc = new Document(getMyDir() + "Rendering.doc");

// Retrieve the array of environment-dependent font sources that are searched by default. For example this will contain a "Windows\Fonts\" source on a Windows machines.
// We add this array to a new ArrayList to make adding or removing font entries much easier.
ArrayList fontSources = new ArrayList(Arrays.asList(FontSettings.getDefaultInstance().getFontsSources()));

// Add a new folder source which will instruct Aspose.Words to search the following folder for fonts.
FolderFontSource folderFontSource = new FolderFontSource("C:\\MyFonts\\", true);

// Add the custom folder which contains our fonts to the list of existing font sources.
fontSources.add(folderFontSource);

// Convert the Arraylist of source back into a primitive array of FontSource objects.
FontSourceBase[] updatedFontSources = (FontSourceBase[]) fontSources.toArray(new FontSourceBase[fontSources.size()]);

// Apply the new set of font sources to use.
FontSettings.getDefaultInstance().setFontsSources(updatedFontSources);

doc.save(getArtifactsDir() + "Rendering.SetFontsFolders.pdf");

Constructor Summary
 
Property Getters/Setters Summary
static FontSettingsgetDefaultInstance()
Static default font settings.
FontFallbackSettingsgetFallbackSettings()
Settings related to font fallback mechanism.
FontSubstitutionSettingsgetSubstitutionSettings()
Settings related to font substitution mechanism.
 
Method Summary
FontSourceBase[]getFontsSources()
Gets a copy of the array that contains the list of sources where Aspose.Words looks for TrueType fonts.
voidresetFontSources()
Resets the fonts sources to the system default.
voidsetFontsFolder(java.lang.String fontFolder, boolean recursive)
Sets the folder where Aspose.Words looks for TrueType fonts when rendering documents or embedding fonts. This is a shortcut to setFontsFolders(java.lang.String[],boolean) for setting only one font directory.
voidsetFontsFolders(java.lang.String[] fontsFolders, boolean recursive)
Sets the folders where Aspose.Words looks for TrueType fonts when rendering documents or embedding fonts.
voidsetFontsSources(FontSourceBase[] sources)
Sets the sources where Aspose.Words looks for TrueType fonts when rendering documents or embedding fonts.
 

    • Constructor Detail

      • FontSettings

        public FontSettings()
    • Property Getters/Setters Detail

      • getDefaultInstance

        public static FontSettings getDefaultInstance()
        
        Static default font settings. This instance is used by default in a document unless Document.FontSettings is specified.

        Example:

        Demonstrates how to receive notifications of font substitutions by using IWarningCallback.
        // Load the document to render.
        Document doc = new Document(getMyDir() + "Document.doc");
        
        // Create a new class implementing IWarningCallback and assign it to the PdfSaveOptions class.
        HandleDocumentWarnings callback = new HandleDocumentWarnings();
        doc.setWarningCallback(callback);
        
        // We can choose the default font to use in the case of any missing fonts.
        FontSettings.getDefaultInstance().getSubstitutionSettings().getDefaultFontSubstitution().setDefaultFontName("Arial");
        
        // For testing we will set Aspose.Words to look for fonts only in a folder which doesn't exist. Since Aspose.Words won't
        // find any fonts in the specified directory, then during rendering the fonts in the document will be substituted with the default 
        // font specified under FontSettings.DefaultFontName. We can pick up on this substitution using our callback.
        FontSettings.getDefaultInstance().setFontsFolder("", false);
        
        // Pass the save options along with the save path to the save method.
        doc.save(getArtifactsDir() + "Rendering.MissingFontNotification.pdf");
      • getFallbackSettings

        public FontFallbackSettings getFallbackSettings()
        
        Settings related to font fallback mechanism.

        Example:

        Shows how to distribute fallback fonts across unicode character code ranges.
        Document doc = new Document();
        
        // Create a FontSettings object for our document and get its FallbackSettings attribute
        FontSettings fontSettings = new FontSettings();
        doc.setFontSettings(fontSettings);
        FontFallbackSettings fontFallbackSettings = fontSettings.getFallbackSettings();
        
        // Set our fonts to be sourced exclusively from the "MyFonts" folder
        FolderFontSource folderFontSource = new FolderFontSource(getMyDir() + "\\MyFonts", false);
        fontSettings.setFontsSources(new FontSourceBase[]{folderFontSource});
        
        // Calling BuildAutomatic() will generate a fallback scheme that distributes accessible fonts across as many unicode character codes as possible
        // In our case, it only has access to the handful of fonts inside the "MyFonts" folder
        fontFallbackSettings.buildAutomatic();
        fontFallbackSettings.save(getArtifactsDir() + "Font.FontFallbackSettings.BuildAutomatic.xml");
        
        // We can also load a custom substitution scheme from a file like this
        // This scheme applies the "Arvo" font across the "0000-00ff" unicode blocks, the "Squarish Sans CT" font across "0100-024f",
        // and the "M+ 2m" font in every place that none of the other fonts cover
        fontFallbackSettings.load(getMyDir() + "Font.FallbackSettings.Custom.xml");
        
        // Create a document builder and set its font to one that doesn't exist in any of our sources
        // In doing that we will rely completely on our font fallback scheme to render text
        DocumentBuilder builder = new DocumentBuilder(doc);
        builder.getFont().setName("Missing Font");
        
        // Type out every unicode character from 0x0021 to 0x052F, with descriptive lines dividing unicode blocks we defined in our custom font fallback scheme
        for (int i = 0x0021; i < 0x0530; i++) {
            switch (i) {
                case 0x0021:
                    builder.writeln("\n\n0x0021 - 0x00FF: \nBasic Latin/Latin-1 Supplement unicode blocks in \"Arvo\" font:");
                    break;
                case 0x0100:
                    builder.writeln("\n\n0x0100 - 0x024F: \nLatin Extended A/B blocks, mostly in \"Squarish Sans CT\" font:");
                    break;
                case 0x0250:
                    builder.writeln("\n\n0x0250 - 0x052F: \nIPA/Greek/Cyrillic blocks in \"M+ 2m\" font:");
                    break;
            }
        
            builder.write(Character.toString((char) i));
        }
        
        doc.save(getArtifactsDir() + "Font.FallbackSettings.Custom.pdf");
      • getSubstitutionSettings

        public FontSubstitutionSettings getSubstitutionSettings()
        
        Settings related to font substitution mechanism.

        Example:

        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("os.name").startsWith("Windows")) {
            Assert.assertEquals(SystemFontSource.getSystemFontFolders(), new String[]{"C:\\WINDOWS\\Fonts"});
        }
        
        for (String systemFontFolder : SystemFontSource.getSystemFontFolders()) {
            System.out.println(systemFontFolder);
        }
        
        // Set a font that exists in the windows fonts directory as a substitute for one that doesn't
        doc.getFontSettings().getSubstitutionSettings().getFontInfoSubstitution().setEnabled(true);
        doc.getFontSettings().getSubstitutionSettings().getTableSubstitution().addSubstitutes("Kreon-Regular", new String[]{"Calibri"});
        
        long substituteSize = StreamSupport.stream(doc.getFontSettings().getSubstitutionSettings().getTableSubstitution().getSubstitutes("Kreon-Regular").spliterator(), false).count();
        Assert.assertEquals(substituteSize, 1);
        Assert.assertTrue(doc.getFontSettings().getSubstitutionSettings().getTableSubstitution().getSubstitutes("Kreon-Regular").toString().contains("Calibri"));
        
        // Alternatively, we could add a folder font source in which the corresponding folder contains the font
        FolderFontSource folderFontSource = new FolderFontSource(getMyDir() + "MyFonts", false);
        doc.getFontSettings().setFontsSources(new FontSourceBase[]{systemFontSource, folderFontSource});
        Assert.assertEquals(doc.getFontSettings().getFontsSources().length, 2);
        
        // Resetting the font sources still leaves us with the system font source as well as our substitutes
        doc.getFontSettings().resetFontSources();
        
        Assert.assertEquals(doc.getFontSettings().getFontsSources().length, 1);
        Assert.assertEquals(doc.getFontSettings().getFontsSources()[0].getType(), FontSourceType.SYSTEM_FONTS);
        
        substituteSize = StreamSupport.stream(doc.getFontSettings().getSubstitutionSettings().getTableSubstitution().getSubstitutes("Kreon-Regular").spliterator(), false).count();
        Assert.assertEquals(substituteSize, 1);
    • Method Detail

      • getFontsSources

        public FontSourceBase[] getFontsSources()
        Gets a copy of the array that contains the list of sources where Aspose.Words looks for TrueType fonts.

        The returned value is a copy of the data that Aspose.Words uses. If you change the entries in the returned array, it will have no effect on document rendering. To specify new font sources use the setFontsSources(com.aspose.words.FontSourceBase[]) method.

        Returns:
        A copy of the current font sources.

        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.
        Document doc = new Document(getMyDir() + "Rendering.doc");
        
        // Retrieve the array of environment-dependent font sources that are searched by default. For example this will contain a "Windows\Fonts\" source on a Windows machines.
        // We add this array to a new ArrayList to make adding or removing font entries much easier.
        ArrayList fontSources = new ArrayList(Arrays.asList(FontSettings.getDefaultInstance().getFontsSources()));
        
        // Add a new folder source which will instruct Aspose.Words to search the following folder for fonts.
        FolderFontSource folderFontSource = new FolderFontSource("C:\\MyFonts\\", true);
        
        // Add the custom folder which contains our fonts to the list of existing font sources.
        fontSources.add(folderFontSource);
        
        // Convert the Arraylist of source back into a primitive array of FontSource objects.
        FontSourceBase[] updatedFontSources = (FontSourceBase[]) fontSources.toArray(new FontSourceBase[fontSources.size()]);
        
        // Apply the new set of font sources to use.
        FontSettings.getDefaultInstance().setFontsSources(updatedFontSources);
        
        doc.save(getArtifactsDir() + "Rendering.SetFontsFolders.pdf");
      • resetFontSources

        public void resetFontSources()
        Resets the fonts sources to the system default.

        Example:

        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("os.name").startsWith("Windows")) {
            Assert.assertEquals(SystemFontSource.getSystemFontFolders(), new String[]{"C:\\WINDOWS\\Fonts"});
        }
        
        for (String systemFontFolder : SystemFontSource.getSystemFontFolders()) {
            System.out.println(systemFontFolder);
        }
        
        // Set a font that exists in the windows fonts directory as a substitute for one that doesn't
        doc.getFontSettings().getSubstitutionSettings().getFontInfoSubstitution().setEnabled(true);
        doc.getFontSettings().getSubstitutionSettings().getTableSubstitution().addSubstitutes("Kreon-Regular", new String[]{"Calibri"});
        
        long substituteSize = StreamSupport.stream(doc.getFontSettings().getSubstitutionSettings().getTableSubstitution().getSubstitutes("Kreon-Regular").spliterator(), false).count();
        Assert.assertEquals(substituteSize, 1);
        Assert.assertTrue(doc.getFontSettings().getSubstitutionSettings().getTableSubstitution().getSubstitutes("Kreon-Regular").toString().contains("Calibri"));
        
        // Alternatively, we could add a folder font source in which the corresponding folder contains the font
        FolderFontSource folderFontSource = new FolderFontSource(getMyDir() + "MyFonts", false);
        doc.getFontSettings().setFontsSources(new FontSourceBase[]{systemFontSource, folderFontSource});
        Assert.assertEquals(doc.getFontSettings().getFontsSources().length, 2);
        
        // Resetting the font sources still leaves us with the system font source as well as our substitutes
        doc.getFontSettings().resetFontSources();
        
        Assert.assertEquals(doc.getFontSettings().getFontsSources().length, 1);
        Assert.assertEquals(doc.getFontSettings().getFontsSources()[0].getType(), FontSourceType.SYSTEM_FONTS);
        
        substituteSize = StreamSupport.stream(doc.getFontSettings().getSubstitutionSettings().getTableSubstitution().getSubstitutes("Kreon-Regular").spliterator(), false).count();
        Assert.assertEquals(substituteSize, 1);
      • setFontsFolder

        public void setFontsFolder(java.lang.String fontFolder, boolean recursive)
        Sets the folder where Aspose.Words looks for TrueType fonts when rendering documents or embedding fonts. This is a shortcut to setFontsFolders(java.lang.String[],boolean) for setting only one font directory.
        Parameters:
        fontFolder - The folder that contains TrueType fonts.
        recursive - True to scan the specified folders for fonts recursively.

        Example:

        Demonstrates how to set the folder Aspose.Words uses to look for TrueType fonts during rendering or embedding of fonts.
        Document doc = new Document(getMyDir() + "Rendering.doc");
        
        // Note that this setting will override any default font sources that are being searched by default. Now only these folders will be searched for
        // fonts when rendering or embedding fonts. To add an extra font source while keeping system font sources then use both FontSettings.GetFontSources and
        // FontSettings.SetFontSources instead.
        FontSettings.getDefaultInstance().setFontsFolder("C:\\MyFonts\\", false);
        
        doc.save(getArtifactsDir() + "Rendering.SetFontsFolder.pdf");
      • setFontsFolders

        public void setFontsFolders(java.lang.String[] fontsFolders, boolean recursive)
        Sets the folders where Aspose.Words looks for TrueType fonts when rendering documents or embedding fonts.

        By default, Aspose.Words looks for fonts installed to the system.

        Setting this property resets the cache of all previously loaded fonts.

        Parameters:
        fontsFolders - An array of folders that contain TrueType fonts.
        recursive - True to scan the specified folders for fonts recursively.

        Example:

        Demonstrates how to set Aspose.Words to look in multiple folders for TrueType fonts when rendering or embedding fonts.
        Document doc = new Document(getMyDir() + "Rendering.doc");
        
        // Note that this setting will override any default font sources that are being searched by default. Now only these folders will be searched for
        // fonts when rendering or embedding fonts. To add an extra font source while keeping system font sources then use both FontSettings.GetFontSources and
        // FontSettings.SetFontSources instead.
        FontSettings.getDefaultInstance().setFontsFolders(new String[]{"C:\\MyFonts\\", "D:\\Misc\\Fonts\\"}, true);
        
        doc.save(getArtifactsDir() + "Rendering.SetFontsFolders.pdf");
      • setFontsSources

        public void setFontsSources(FontSourceBase[] sources)
        Sets the sources where Aspose.Words looks for TrueType fonts when rendering documents or embedding fonts.

        By default, Aspose.Words looks for fonts installed to the system.

        Setting this property resets the cache of all previously loaded fonts.

        Parameters:
        sources - An array of sources that contain TrueType fonts.

        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.
        Document doc = new Document(getMyDir() + "Rendering.doc");
        
        // Retrieve the array of environment-dependent font sources that are searched by default. For example this will contain a "Windows\Fonts\" source on a Windows machines.
        // We add this array to a new ArrayList to make adding or removing font entries much easier.
        ArrayList fontSources = new ArrayList(Arrays.asList(FontSettings.getDefaultInstance().getFontsSources()));
        
        // Add a new folder source which will instruct Aspose.Words to search the following folder for fonts.
        FolderFontSource folderFontSource = new FolderFontSource("C:\\MyFonts\\", true);
        
        // Add the custom folder which contains our fonts to the list of existing font sources.
        fontSources.add(folderFontSource);
        
        // Convert the Arraylist of source back into a primitive array of FontSource objects.
        FontSourceBase[] updatedFontSources = (FontSourceBase[]) fontSources.toArray(new FontSourceBase[fontSources.size()]);
        
        // Apply the new set of font sources to use.
        FontSettings.getDefaultInstance().setFontsSources(updatedFontSources);
        
        doc.save(getArtifactsDir() + "Rendering.SetFontsFolders.pdf");