java.lang.Objectcom.aspose.words.FontSubstitutionSettings
public class FontSubstitutionSettings
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
Note that font config substitution rule will resolve the font in most cases and thus overrides all other rules.
Example:
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(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
doc.getFontSettings().resetFontSources();
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 | ||
---|---|---|
DefaultFontSubstitutionRule | getDefaultFontSubstitution() | |
Settings related to default font substitution rule. | ||
FontConfigSubstitutionRule | getFontConfigSubstitution() | |
Settings related to font config substitution rule. | ||
FontInfoSubstitutionRule | getFontInfoSubstitution() | |
Settings related to font info substitution rule. | ||
TableSubstitutionRule | getTableSubstitution() | |
Settings related to table substitution rule. |
Property Getters/Setters Detail |
---|
getDefaultFontSubstitution | |
public DefaultFontSubstitutionRule getDefaultFontSubstitution() |
Example:
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(); doc.setFontSettings(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.assertTrue(defaultFontSubstitutionRule.getEnabled()); 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."); doc.save(getArtifactsDir() + "Font.DefaultFontSubstitutionRule.pdf");
getFontConfigSubstitution | |
public FontConfigSubstitutionRule getFontConfigSubstitution() |
Example:
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("os.name").toLowerCase(); // On Windows, it is unavailable if (OS == "win") { Assert.assertFalse(configSubstitution.getEnabled()); Assert.assertFalse(configSubstitution.isFontConfigAvailable()); } // On Linux/Mac, we will have access and will be able to perform operations if (OS == "nix") { Assert.assertTrue(configSubstitution.getEnabled()); Assert.assertTrue(configSubstitution.isFontConfigAvailable()); configSubstitution.resetCache(); }
getFontInfoSubstitution | |
public FontInfoSubstitutionRule getFontInfoSubstitution() |
Example:
Shows how to set the property for finding the closest match font among the available font sources instead missing font.@Test public void enableFontSubstitution() throws Exception { Document doc = new Document(getMyDir() + "Missing font.docx"); // Assign a custom warning callback HandleDocumentSubstitutionWarnings substitutionWarningHandler = new HandleDocumentSubstitutionWarnings(); doc.setWarningCallback(substitutionWarningHandler); // Set a default font name and enable font substitution FontSettings fontSettings = new FontSettings(); fontSettings.getSubstitutionSettings().getDefaultFontSubstitution().setDefaultFontName("Arial"); fontSettings.getSubstitutionSettings().getFontInfoSubstitution().setEnabled(true); // When saving the document with the missing font, we should get a warning doc.setFontSettings(fontSettings); doc.save(getArtifactsDir() + "Font.EnableFontSubstitution.pdf"); // List all warnings using an enumerator Iterator<WarningInfo> warnings = substitutionWarningHandler.FontWarnings.iterator(); try /*JAVA: was using*/ { while (warnings.hasNext()) System.out.println(warnings.next().getDescription()); } 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.", substitutionWarningHandler.FontWarnings.get(0).getDescription()); // The warning info collection can also be cleared like this substitutionWarningHandler.FontWarnings.clear(); Assert.assertNull(substitutionWarningHandler.FontWarnings); } 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) FontWarnings.warning(info); } public WarningInfoCollection FontWarnings = new WarningInfoCollection(); }
getTableSubstitution | |
public TableSubstitutionRule getTableSubstitution() |
Example:
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(); doc.setFontSettings(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 { tableSubstitutionRule.load(fileStream); } 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.getFont().setName("Arial"); 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."); doc.save(getArtifactsDir() + "Font.TableSubstitutionRule.Custom.pdf");