Aspose::Words::Fonts::FontSubstitutionSettings Class Reference

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 name substitution rule (enabled by default)
2. Font config substitution rule (disabled by default)
3. Table substitution rule (enabled by default)
4. Font info substitution rule (enabled by default)
5. 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.

Examples

Shows how to access a document's system font source and set font substitutes.

auto doc = MakeObject<Document>();
doc->set_FontSettings(MakeObject<FontSettings>());
 
// By default, a blank document always contains a system font source.
ASSERT_EQ(1, doc->get_FontSettings()->GetFontsSources()->get_Length());
 
auto systemFontSource = System::DynamicCast<SystemFontSource>(doc->get_FontSettings()->GetFontsSources()->idx_get(0));
ASSERT_EQ(FontSourceType::SystemFonts, systemFontSource->get_Type());
ASSERT_EQ(0, systemFontSource->get_Priority());
 
System::PlatformID pid = System::Environment::get_OSVersion().get_Platform();
bool isWindows = (pid == System::PlatformID::Win32NT) || (pid == System::PlatformID::Win32S) || (pid == System::PlatformID::Win32Windows) ||
                 (pid == System::PlatformID::WinCE);
if (isWindows)
{
    const String fontsPath = u"C:\\WINDOWS\\Fonts";
    ASSERT_EQ(fontsPath.ToLower(), SystemFontSource::GetSystemFontFolders()->LINQ_First().ToLower());
}
 
for (String systemFontFolder : SystemFontSource::GetSystemFontFolders())
{
    std::cout << systemFontFolder << std::endl;
}
 
// Set a font that exists in the Windows Fonts directory as a substitute for one that does not.
doc->get_FontSettings()->get_SubstitutionSettings()->get_FontInfoSubstitution()->set_Enabled(true);
doc->get_FontSettings()->get_SubstitutionSettings()->get_TableSubstitution()->AddSubstitutes(u"Kreon-Regular", MakeArray<String>({u"Calibri"}));
 
ASSERT_EQ(1, doc->get_FontSettings()->get_SubstitutionSettings()->get_TableSubstitution()->GetSubstitutes(u"Kreon-Regular")->LINQ_Count());
ASSERT_TRUE(doc->get_FontSettings()
                ->get_SubstitutionSettings()
                ->get_TableSubstitution()
                ->GetSubstitutes(u"Kreon-Regular")
                ->LINQ_ToArray()
                ->Contains(u"Calibri"));
 
// Alternatively, we could add a folder font source in which the corresponding folder contains the font.
auto folderFontSource = MakeObject<FolderFontSource>(FontsDir, false);
doc->get_FontSettings()->SetFontsSources(MakeArray<SharedPtr<FontSourceBase>>({systemFontSource, folderFontSource}));
ASSERT_EQ(2, doc->get_FontSettings()->GetFontsSources()->get_Length());
 
// Resetting the font sources still leaves us with the system font source as well as our substitutes.
doc->get_FontSettings()->ResetFontSources();
 
ASSERT_EQ(1, doc->get_FontSettings()->GetFontsSources()->get_Length());
ASSERT_EQ(FontSourceType::SystemFonts, doc->get_FontSettings()->GetFontsSources()->idx_get(0)->get_Type());
ASSERT_EQ(1, doc->get_FontSettings()->get_SubstitutionSettings()->get_TableSubstitution()->GetSubstitutes(u"Kreon-Regular")->LINQ_Count());

#include <Aspose.Words.Cpp/Fonts/FontSubstitutionSettings.h>

Inheritance diagram for Aspose::Words::Fonts::FontSubstitutionSettings:

Public Member Functions
SharedPtr< DefaultFontSubstitutionRule >	get_DefaultFontSubstitution () const
	Settings related to default font substitution rule. More...
SharedPtr< FontConfigSubstitutionRule >	get_FontConfigSubstitution () const
	Settings related to font config substitution rule. More...
SharedPtr< FontInfoSubstitutionRule >	get_FontInfoSubstitution () const
	Settings related to font info substitution rule. More...
SharedPtr< FontNameSubstitutionRule >	get_FontNameSubstitution () const
	Settings related to font name substitution rule. More...
SharedPtr< TableSubstitutionRule >	get_TableSubstitution () const
	Settings related to table substitution rule. More...
virtual const TypeInfo &	GetType () const override
virtual bool	Is (const TypeInfo &target) const override

Static Public Member Functions
static const TypeInfo &	Type ()

Member Function Documentation

get_DefaultFontSubstitution()

System::SharedPtr<Aspose::Words::Fonts::DefaultFontSubstitutionRule> Aspose::Words::Fonts::FontSubstitutionSettings::get_DefaultFontSubstitution

(

)

const

Settings related to default font substitution rule.

Examples

Shows how to set the default font substitution rule.

auto doc = MakeObject<Document>();
auto fontSettings = MakeObject<FontSettings>();
doc->set_FontSettings(fontSettings);
 
// Get the default substitution rule within FontSettings.
// This rule will substitute all missing fonts with "Times New Roman".
SharedPtr<DefaultFontSubstitutionRule> defaultFontSubstitutionRule = fontSettings->get_SubstitutionSettings()->get_DefaultFontSubstitution();
ASSERT_TRUE(defaultFontSubstitutionRule->get_Enabled());
ASSERT_EQ(u"Times New Roman", defaultFontSubstitutionRule->get_DefaultFontName());
 
// Set the default font substitute to "Courier New".
defaultFontSubstitutionRule->set_DefaultFontName(u"Courier New");
 
// Using a document builder, add some text in a font that we do not have to see the substitution take place,
// and then render the result in a PDF.
auto builder = MakeObject<DocumentBuilder>(doc);
 
builder->get_Font()->set_Name(u"Missing Font");
builder->Writeln(u"Line written in a missing font, which will be substituted with Courier New.");
 
doc->Save(ArtifactsDir + u"FontSettings.DefaultFontSubstitutionRule.pdf");

get_FontConfigSubstitution()

System::SharedPtr<Aspose::Words::Fonts::FontConfigSubstitutionRule> Aspose::Words::Fonts::FontSubstitutionSettings::get_FontConfigSubstitution

(

)

const

Settings related to font config substitution rule.

Examples

Shows operating system-dependent font config substitution.

auto fontSettings = MakeObject<FontSettings>();
SharedPtr<FontConfigSubstitutionRule> fontConfigSubstitution = fontSettings->get_SubstitutionSettings()->get_FontConfigSubstitution();
 
System::PlatformID pid = System::Environment::get_OSVersion().get_Platform();
bool isWindows = (pid == System::PlatformID::Win32NT) || (pid == System::PlatformID::Win32S) || (pid == System::PlatformID::Win32Windows) ||
                 (pid == System::PlatformID::WinCE);
 
// The FontConfigSubstitutionRule object works differently on Windows/non-Windows platforms.
// On Windows, it is unavailable.
if (isWindows)
{
    ASSERT_FALSE(fontConfigSubstitution->get_Enabled());
    ASSERT_FALSE(fontConfigSubstitution->IsFontConfigAvailable());
}
 
bool isLinuxOrMac = (pid == System::PlatformID::Unix) || (pid == System::PlatformID::MacOSX);
 
// On Linux/Mac, we will have access to it, and will be able to perform operations.
if (isLinuxOrMac)
{
    ASSERT_TRUE(fontConfigSubstitution->get_Enabled());
    ASSERT_TRUE(fontConfigSubstitution->IsFontConfigAvailable());
 
    fontConfigSubstitution->ResetCache();
}

get_FontInfoSubstitution()

System::SharedPtr<Aspose::Words::Fonts::FontInfoSubstitutionRule> Aspose::Words::Fonts::FontSubstitutionSettings::get_FontInfoSubstitution

(

)

const

Settings related to font info substitution rule.

Examples

Shows how to set the property for finding the closest match for a missing font from the available font sources.

void EnableFontSubstitution()
{
    // Open a document that contains text formatted with a font that does not exist in any of our font sources.
    auto doc = MakeObject<Document>(MyDir + u"Missing font.docx");
 
    // Assign a callback for handling font substitution warnings.
    auto substitutionWarningHandler = MakeObject<ExFontSettings::HandleDocumentSubstitutionWarnings>();
    doc->set_WarningCallback(substitutionWarningHandler);
 
    // Set a default font name and enable font substitution.
    auto fontSettings = MakeObject<FontSettings>();
    fontSettings->get_SubstitutionSettings()->get_DefaultFontSubstitution()->set_DefaultFontName(u"Arial");
    ;
    fontSettings->get_SubstitutionSettings()->get_FontInfoSubstitution()->set_Enabled(true);
 
    // We will get a font substitution warning if we save a document with a missing font.
    doc->set_FontSettings(fontSettings);
    doc->Save(ArtifactsDir + u"FontSettings.EnableFontSubstitution.pdf");
 
    {
        SharedPtr<System::Collections::Generic::IEnumerator<SharedPtr<WarningInfo>>> warnings = substitutionWarningHandler->FontWarnings->GetEnumerator();
        while (warnings->MoveNext())
        {
            std::cout << warnings->get_Current()->get_Description() << std::endl;
        }
    }
 
    // We can also verify warnings in the collection and clear them.
    ASSERT_EQ(WarningSource::Layout, substitutionWarningHandler->FontWarnings->idx_get(0)->get_Source());
    ASSERT_EQ(u"Font '28 Days Later' has not been found. Using 'Calibri' font instead. Reason: alternative name from document.",
              substitutionWarningHandler->FontWarnings->idx_get(0)->get_Description());
 
    substitutionWarningHandler->FontWarnings->Clear();
 
    ASSERT_EQ(0, substitutionWarningHandler->FontWarnings->get_Count());
}
 
class HandleDocumentSubstitutionWarnings : public IWarningCallback
{
public:
    SharedPtr<WarningInfoCollection> FontWarnings;
 
    void Warning(SharedPtr<WarningInfo> info) override
    {
        if (info->get_WarningType() == WarningType::FontSubstitution)
        {
            FontWarnings->Warning(info);
        }
    }
 
    HandleDocumentSubstitutionWarnings() : FontWarnings(MakeObject<WarningInfoCollection>())
    {
    }
};

get_FontNameSubstitution()

System::SharedPtr<Aspose::Words::Fonts::FontNameSubstitutionRule> Aspose::Words::Fonts::FontSubstitutionSettings::get_FontNameSubstitution

(

)

const

Settings related to font name substitution rule.

get_TableSubstitution()

System::SharedPtr<Aspose::Words::Fonts::TableSubstitutionRule> Aspose::Words::Fonts::FontSubstitutionSettings::get_TableSubstitution

(

)

const

Settings related to table substitution rule.

Examples

Shows how to work with custom font substitution tables.

auto doc = MakeObject<Document>();
auto fontSettings = MakeObject<FontSettings>();
doc->set_FontSettings(fontSettings);
 
// Create a new table substitution rule and load the default Windows font substitution table.
SharedPtr<TableSubstitutionRule> tableSubstitutionRule = fontSettings->get_SubstitutionSettings()->get_TableSubstitution();
 
// If we select fonts exclusively from our folder, we will need a custom substitution table.
// We will no longer have access to the Microsoft Windows fonts,
// such as "Arial" or "Times New Roman" since they do not exist in our new font folder.
auto folderFontSource = MakeObject<FolderFontSource>(FontsDir, false);
fontSettings->SetFontsSources(MakeArray<SharedPtr<FontSourceBase>>({folderFontSource}));
 
// Below are two ways of loading a substitution table from a file in the local file system.
// 1 -  From a stream:
{
    auto fileStream = MakeObject<System::IO::FileStream>(MyDir + u"Font substitution rules.xml", System::IO::FileMode::Open);
    tableSubstitutionRule->Load(fileStream);
}
 
// 2 -  Directly from a file:
tableSubstitutionRule->Load(MyDir + u"Font substitution rules.xml");
 
// Since we no longer have access to "Arial", our font table will first try substitute it with "Nonexistent Font".
// We do not have this font so that it will move onto the next substitute, "Kreon", found in the "MyFonts" folder.
ASPOSE_ASSERT_EQ(MakeArray<String>({u"Missing Font", u"Kreon"}), tableSubstitutionRule->GetSubstitutes(u"Arial")->LINQ_ToArray());
 
// We can expand this table programmatically. We will add an entry that substitutes "Times New Roman" with "Arvo"
ASSERT_TRUE(tableSubstitutionRule->GetSubstitutes(u"Times New Roman") == nullptr);
tableSubstitutionRule->AddSubstitutes(u"Times New Roman", MakeArray<String>({u"Arvo"}));
ASPOSE_ASSERT_EQ(MakeArray<String>({u"Arvo"}), tableSubstitutionRule->GetSubstitutes(u"Times New Roman")->LINQ_ToArray());
 
// 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" as a second substitute option.
tableSubstitutionRule->AddSubstitutes(u"Times New Roman", MakeArray<String>({u"M+ 2m"}));
ASPOSE_ASSERT_EQ(MakeArray<String>({u"Arvo", u"M+ 2m"}), tableSubstitutionRule->GetSubstitutes(u"Times New Roman")->LINQ_ToArray());
 
// SetSubstitutes() can set a new list of substitute fonts for a font.
tableSubstitutionRule->SetSubstitutes(u"Times New Roman", MakeArray<String>({u"Squarish Sans CT", u"M+ 2m"}));
ASPOSE_ASSERT_EQ(MakeArray<String>({u"Squarish Sans CT", u"M+ 2m"}), tableSubstitutionRule->GetSubstitutes(u"Times New Roman")->LINQ_ToArray());
 
// Writing text in fonts that we do not have access to will invoke our substitution rules.
auto builder = MakeObject<DocumentBuilder>(doc);
builder->get_Font()->set_Name(u"Arial");
builder->Writeln(u"Text written in Arial, to be substituted by Kreon.");
 
builder->get_Font()->set_Name(u"Times New Roman");
builder->Writeln(u"Text written in Times New Roman, to be substituted by Squarish Sans CT.");
 
doc->Save(ArtifactsDir + u"FontSettings.TableSubstitutionRule.Custom.pdf");

GetType()

virtual const System::TypeInfo& Aspose::Words::Fonts::FontSubstitutionSettings::GetType ( ) const

overridevirtual

Reimplemented from System::Object.

Is()

virtual bool Aspose::Words::Fonts::FontSubstitutionSettings::Is ( const System::TypeInfo &  target ) const

overridevirtual

Reimplemented from System::Object.

Type()

static const System::TypeInfo& Aspose::Words::Fonts::FontSubstitutionSettings::Type ( )

static