Aspose::Words::Fonts::FontSettings Class Reference

Detailed Description

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.

Examples

Shows how to set a font source directory.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->get_Font()->set_Name(u"Arvo");
builder->Writeln(u"Hello world!");
builder->get_Font()->set_Name(u"Amethysta");
builder->Writeln(u"The quick brown fox jumps over the lazy dog.");
// Our font sources do not contain the font that we have used for text in this document.
// If we use these font settings while rendering this document,
// Aspose.Words will apply a fallback font to text which has a font that Aspose.Words cannot locate.
ArrayPtr<SharedPtr<FontSourceBase>> originalFontSources = FontSettings::get_DefaultInstance()->GetFontsSources();
ASSERT_EQ(1, originalFontSources->get_Length());
ASSERT_TRUE(originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Arial"; }));
// The default font sources are missing the two fonts that we are using in this document.
ASSERT_FALSE(originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Arvo"; }));
ASSERT_FALSE(
originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Amethysta"; }));
// Use the "SetFontsFolder" method to set a directory which will act as a new font source.
// Pass "false" as the "recursive" argument to include fonts from all the font files that are in the directory
// that we are passing in the first argument, but not include any fonts in any of that directory's subfolders.
// Pass "true" as the "recursive" argument to include all font files in the directory that we are passing
// in the first argument, as well as all the fonts in its subdirectories.
FontSettings::get_DefaultInstance()->SetFontsFolder(FontsDir, recursive);
ArrayPtr<SharedPtr<FontSourceBase>> newFontSources = FontSettings::get_DefaultInstance()->GetFontsSources();
ASSERT_EQ(1, newFontSources->get_Length());
ASSERT_FALSE(newFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Arial"; }));
ASSERT_TRUE(newFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Arvo"; }));
// The "Amethysta" font is in a subfolder of the font directory.
if (recursive)
{
ASSERT_EQ(25, newFontSources[0]->GetAvailableFonts()->get_Count());
ASSERT_TRUE(newFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Amethysta"; }));
}
else
{
ASSERT_EQ(18, newFontSources[0]->GetAvailableFonts()->get_Count());
ASSERT_FALSE(newFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Amethysta"; }));
}
doc->Save(ArtifactsDir + u"FontSettings.SetFontsFolder.pdf");
// Restore the original font sources.
FontSettings::get_DefaultInstance()->SetFontsSources(originalFontSources);

Shows how to set multiple font source directories.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->get_Font()->set_Name(u"Amethysta");
builder->Writeln(u"The quick brown fox jumps over the lazy dog.");
builder->get_Font()->set_Name(u"Junction Light");
builder->Writeln(u"The quick brown fox jumps over the lazy dog.");
// Our font sources do not contain the font that we have used for text in this document.
// If we use these font settings while rendering this document,
// Aspose.Words will apply a fallback font to text which has a font that Aspose.Words cannot locate.
ArrayPtr<SharedPtr<FontSourceBase>> originalFontSources = FontSettings::get_DefaultInstance()->GetFontsSources();
ASSERT_EQ(1, originalFontSources->get_Length());
ASSERT_TRUE(originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Arial"; }));
// The default font sources are missing the two fonts that we are using in this document.
ASSERT_FALSE(
originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Amethysta"; }));
ASSERT_FALSE(
originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Junction Light"; }));
// Use the "SetFontsFolders" method to create a font source from each font directory that we pass as the first argument.
// Pass "false" as the "recursive" argument to include fonts from all the font files that are in the directories
// that we are passing in the first argument, but not include any fonts from any of the directories' subfolders.
// Pass "true" as the "recursive" argument to include all font files in the directories that we are passing
// in the first argument, as well as all the fonts in their subdirectories.
FontSettings::get_DefaultInstance()->SetFontsFolders(MakeArray<String>({FontsDir + u"/Amethysta", FontsDir + u"/Junction"}), recursive);
ArrayPtr<SharedPtr<FontSourceBase>> newFontSources = FontSettings::get_DefaultInstance()->GetFontsSources();
ASSERT_EQ(2, newFontSources->get_Length());
ASSERT_FALSE(newFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Arial"; }));
ASSERT_EQ(1, newFontSources[0]->GetAvailableFonts()->get_Count());
ASSERT_TRUE(newFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Amethysta"; }));
// The "Junction" folder itself contains no font files, but has subfolders that do.
if (recursive)
{
ASSERT_EQ(6, newFontSources[1]->GetAvailableFonts()->get_Count());
ASSERT_TRUE(
newFontSources[1]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Junction Light"; }));
}
else
{
ASSERT_EQ(0, newFontSources[1]->GetAvailableFonts()->get_Count());
}
doc->Save(ArtifactsDir + u"FontSettings.SetFontsFolders.pdf");
// Restore the original font sources.
FontSettings::get_DefaultInstance()->SetFontsSources(originalFontSources);

Shows how to add a font source to our existing font sources.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->get_Font()->set_Name(u"Arial");
builder->Writeln(u"Hello world!");
builder->get_Font()->set_Name(u"Amethysta");
builder->Writeln(u"The quick brown fox jumps over the lazy dog.");
builder->get_Font()->set_Name(u"Junction Light");
builder->Writeln(u"The quick brown fox jumps over the lazy dog.");
ArrayPtr<SharedPtr<FontSourceBase>> originalFontSources = FontSettings::get_DefaultInstance()->GetFontsSources();
ASSERT_EQ(1, originalFontSources->get_Length());
ASSERT_TRUE(originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Arial"; }));
// The default font source is missing two of the fonts that we are using in our document.
// When we save this document, Aspose.Words will apply fallback fonts to all text formatted with inaccessible fonts.
ASSERT_FALSE(
originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Amethysta"; }));
ASSERT_FALSE(
originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Junction Light"; }));
// Create a font source from a folder that contains fonts.
auto folderFontSource = MakeObject<FolderFontSource>(FontsDir, true);
// Apply a new array of font sources that contains the original font sources, as well as our custom fonts.
ArrayPtr<SharedPtr<FontSourceBase>> updatedFontSources = MakeArray<SharedPtr<FontSourceBase>>({originalFontSources[0], folderFontSource});
FontSettings::get_DefaultInstance()->SetFontsSources(updatedFontSources);
// Verify that Aspose.Words has access to all required fonts before we render the document to PDF.
updatedFontSources = FontSettings::get_DefaultInstance()->GetFontsSources();
ASSERT_TRUE(updatedFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Arial"; }));
ASSERT_TRUE(updatedFontSources[1]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Amethysta"; }));
ASSERT_TRUE(
updatedFontSources[1]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Junction Light"; }));
doc->Save(ArtifactsDir + u"FontSettings.AddFontSource.pdf");
// Restore the original font sources.
FontSettings::get_DefaultInstance()->SetFontsSources(originalFontSources);

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

+ Inheritance diagram for Aspose::Words::Fonts::FontSettings:

Public Member Functions

 FontSettings ()
 
SharedPtr< FontFallbackSettingsget_FallbackSettings () const
 Settings related to font fallback mechanism. More...
 
SharedPtr< FontSubstitutionSettingsget_SubstitutionSettings () const
 Settings related to font substitution mechanism. More...
 
ArrayPtr< SharedPtr< FontSourceBase > > GetFontsSources ()
 Gets a copy of the array that contains the list of sources where Aspose.Words looks for TrueType fonts. More...
 
virtual const TypeInfoGetType () const override
 
virtual bool Is (const TypeInfo &target) const override
 
void ResetFontSources ()
 Resets the fonts sources to the system default. More...
 
void SaveSearchCache (const SharedPtr< Stream > &outputStream)
 Saves the font search cache to the stream. More...
 
void SetFontsFolder (const String &fontFolder, bool recursive)
 Sets the folder where Aspose.Words looks for TrueType fonts when rendering documents or embedding fonts. This is a shortcut to SetFontsFolders() for setting only one font directory. More...
 
void SetFontsFolders (const ArrayPtr< String > &fontsFolders, bool recursive)
 Sets the folders where Aspose.Words looks for TrueType fonts when rendering documents or embedding fonts. More...
 
void SetFontsSources (const ArrayPtr< SharedPtr< FontSourceBase > > &sources)
 Sets the sources where Aspose.Words looks for TrueType fonts when rendering documents or embedding fonts. More...
 
void SetFontsSources (const ArrayPtr< SharedPtr< FontSourceBase > > &sources, const SharedPtr< Stream > &cacheInputStream)
 Sets the sources where Aspose.Words looks for TrueType fonts and additionally loads previously saved font search cache. More...
 

Static Public Member Functions

static SharedPtr< FontSettingsget_DefaultInstance ()
 Static default font settings. More...
 
static const TypeInfoType ()
 

Constructor & Destructor Documentation

◆ FontSettings()

Aspose::Words::Fonts::FontSettings::FontSettings ( )

Member Function Documentation

◆ get_DefaultInstance()

static System::SharedPtr< Aspose::Words::Fonts::FontSettings > Aspose::Words::Fonts::FontSettings::get_DefaultInstance ( )
static

Static default font settings.

Examples

Shows how to configure the default font settings instance.

// Configure the default font settings instance to use the "Courier New" font
// as a backup substitute when we attempt to use an unknown font.
FontSettings::get_DefaultInstance()->get_SubstitutionSettings()->get_DefaultFontSubstitution()->set_DefaultFontName(u"Courier New");
ASSERT_TRUE(FontSettings::get_DefaultInstance()->get_SubstitutionSettings()->get_DefaultFontSubstitution()->get_Enabled());
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->get_Font()->set_Name(u"Non-existent font");
builder->Write(u"Hello world!");
// This document does not have a FontSettings configuration. When we render the document,
// the default FontSettings instance will resolve the missing font.
// Aspose.Words will use "Courier New" to render text that uses the unknown font.
ASSERT_TRUE(doc->get_FontSettings() == nullptr);
doc->Save(ArtifactsDir + u"FontSettings.DefaultFontInstance.pdf");

Shows how to use the IWarningCallback interface to monitor font substitution warnings.

void SubstitutionWarning()
{
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->get_Font()->set_Name(u"Times New Roman");
builder->Writeln(u"Hello world!");
auto callback = MakeObject<ExFontSettings::FontSubstitutionWarningCollector>();
doc->set_WarningCallback(callback);
// Store the current collection of font sources, which will be the default font source for every document
// for which we do not specify a different font source.
ArrayPtr<SharedPtr<FontSourceBase>> originalFontSources = FontSettings::get_DefaultInstance()->GetFontsSources();
// For testing purposes, we will set Aspose.Words to look for fonts only in a folder that does not exist.
FontSettings::get_DefaultInstance()->SetFontsFolder(String::Empty, false);
// When rendering the document, there will be no place to find the "Times New Roman" font.
// This will cause a font substitution warning, which our callback will detect.
doc->Save(ArtifactsDir + u"FontSettings.SubstitutionWarning.pdf");
FontSettings::get_DefaultInstance()->SetFontsSources(originalFontSources);
ASSERT_TRUE(callback->FontSubstitutionWarnings->idx_get(0)->get_WarningType() == WarningType::FontSubstitution);
ASSERT_TRUE(System::ObjectExt::Equals(callback->FontSubstitutionWarnings->idx_get(0)->get_Description(),
u"Font 'Times New Roman' has not been found. Using 'Fanwood' font instead. Reason: first available font."));
}
class FontSubstitutionWarningCollector : public IWarningCallback
{
public:
SharedPtr<WarningInfoCollection> FontSubstitutionWarnings;
void Warning(SharedPtr<WarningInfo> info) override
{
if (info->get_WarningType() == WarningType::FontSubstitution)
{
FontSubstitutionWarnings->Warning(info);
}
}
FontSubstitutionWarningCollector() : FontSubstitutionWarnings(MakeObject<WarningInfoCollection>())
{
}
};

◆ get_FallbackSettings()

System::SharedPtr< Aspose::Words::Fonts::FontFallbackSettings > Aspose::Words::Fonts::FontSettings::get_FallbackSettings ( ) const

Settings related to font fallback mechanism.

Examples

Shows how to distribute fallback fonts across Unicode character code ranges.

auto doc = MakeObject<Document>();
auto fontSettings = MakeObject<FontSettings>();
doc->set_FontSettings(fontSettings);
SharedPtr<FontFallbackSettings> fontFallbackSettings = fontSettings->get_FallbackSettings();
// Configure our font settings to source fonts only from the "MyFonts" folder.
auto folderFontSource = MakeObject<FolderFontSource>(FontsDir, false);
fontSettings->SetFontsSources(MakeArray<SharedPtr<FontSourceBase>>({folderFontSource}));
// Calling the "BuildAutomatic" method 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(ArtifactsDir + u"FontSettings.FallbackSettingsCustom.BuildAutomatic.xml");
// We can also load a custom substitution scheme from a file like this.
// This scheme applies the "AllegroOpen" font across the "0000-00ff" Unicode blocks, the "AllegroOpen" font across "0100-024f",
// and the "M+ 2m" font in all other ranges that other fonts in the scheme do not cover.
fontFallbackSettings->Load(MyDir + u"Custom font fallback settings.xml");
// Create a document builder and set its font to one that does not exist in any of our sources.
// Our font settings will invoke the fallback scheme for characters that we type using the unavailable font.
auto builder = MakeObject<DocumentBuilder>(doc);
builder->get_Font()->set_Name(u"Missing Font");
// Use the builder to print 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(u"\n\n0x0021 - 0x00FF: \nBasic Latin/Latin-1 Supplement Unicode blocks in \"AllegroOpen\" font:");
break;
case 0x0100:
builder->Writeln(u"\n\n0x0100 - 0x024F: \nLatin Extended A/B blocks, mostly in \"AllegroOpen\" font:");
break;
case 0x0250:
builder->Writeln(u"\n\n0x0250 - 0x052F: \nIPA/Greek/Cyrillic blocks in \"M+ 2m\" font:");
break;
}
builder->Write(String::Format(u"{0}", System::Convert::ToChar(i)));
}
doc->Save(ArtifactsDir + u"FontSettings.FallbackSettingsCustom.pdf");

◆ get_SubstitutionSettings()

System::SharedPtr< Aspose::Words::Fonts::FontSubstitutionSettings > Aspose::Words::Fonts::FontSettings::get_SubstitutionSettings ( ) const

Settings related to font substitution mechanism.

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());
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());

◆ GetFontsSources()

System::ArrayPtr< System::SharedPtr< Aspose::Words::Fonts::FontSourceBase > > Aspose::Words::Fonts::FontSettings::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() method.

Returns
A copy of the current font sources.
Examples

Shows how to add a font source to our existing font sources.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->get_Font()->set_Name(u"Arial");
builder->Writeln(u"Hello world!");
builder->get_Font()->set_Name(u"Amethysta");
builder->Writeln(u"The quick brown fox jumps over the lazy dog.");
builder->get_Font()->set_Name(u"Junction Light");
builder->Writeln(u"The quick brown fox jumps over the lazy dog.");
ArrayPtr<SharedPtr<FontSourceBase>> originalFontSources = FontSettings::get_DefaultInstance()->GetFontsSources();
ASSERT_EQ(1, originalFontSources->get_Length());
ASSERT_TRUE(originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Arial"; }));
// The default font source is missing two of the fonts that we are using in our document.
// When we save this document, Aspose.Words will apply fallback fonts to all text formatted with inaccessible fonts.
ASSERT_FALSE(
originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Amethysta"; }));
ASSERT_FALSE(
originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Junction Light"; }));
// Create a font source from a folder that contains fonts.
auto folderFontSource = MakeObject<FolderFontSource>(FontsDir, true);
// Apply a new array of font sources that contains the original font sources, as well as our custom fonts.
ArrayPtr<SharedPtr<FontSourceBase>> updatedFontSources = MakeArray<SharedPtr<FontSourceBase>>({originalFontSources[0], folderFontSource});
FontSettings::get_DefaultInstance()->SetFontsSources(updatedFontSources);
// Verify that Aspose.Words has access to all required fonts before we render the document to PDF.
updatedFontSources = FontSettings::get_DefaultInstance()->GetFontsSources();
ASSERT_TRUE(updatedFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Arial"; }));
ASSERT_TRUE(updatedFontSources[1]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Amethysta"; }));
ASSERT_TRUE(
updatedFontSources[1]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Junction Light"; }));
doc->Save(ArtifactsDir + u"FontSettings.AddFontSource.pdf");
// Restore the original font sources.
FontSettings::get_DefaultInstance()->SetFontsSources(originalFontSources);

◆ GetType()

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

Reimplemented from System::Object.

◆ Is()

virtual bool Aspose::Words::Fonts::FontSettings::Is ( const System::TypeInfo target) const
overridevirtual

Reimplemented from System::Object.

◆ ResetFontSources()

void Aspose::Words::Fonts::FontSettings::ResetFontSources ( )

Resets the fonts sources to the system default.

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());
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());

◆ SaveSearchCache()

void Aspose::Words::Fonts::FontSettings::SaveSearchCache ( const System::SharedPtr< System::IO::Stream > &  outputStream)

Saves the font search cache to the stream.

Parameters
outputStreamOutput stream.

◆ SetFontsFolder()

void Aspose::Words::Fonts::FontSettings::SetFontsFolder ( const System::String fontFolder,
bool  recursive 
)

Sets the folder where Aspose.Words looks for TrueType fonts when rendering documents or embedding fonts. This is a shortcut to SetFontsFolders() for setting only one font directory.

Parameters
fontFolderThe folder that contains TrueType fonts.
recursiveTrue to scan the specified folders for fonts recursively.
Examples

Shows how to set a font source directory.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->get_Font()->set_Name(u"Arvo");
builder->Writeln(u"Hello world!");
builder->get_Font()->set_Name(u"Amethysta");
builder->Writeln(u"The quick brown fox jumps over the lazy dog.");
// Our font sources do not contain the font that we have used for text in this document.
// If we use these font settings while rendering this document,
// Aspose.Words will apply a fallback font to text which has a font that Aspose.Words cannot locate.
ArrayPtr<SharedPtr<FontSourceBase>> originalFontSources = FontSettings::get_DefaultInstance()->GetFontsSources();
ASSERT_EQ(1, originalFontSources->get_Length());
ASSERT_TRUE(originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Arial"; }));
// The default font sources are missing the two fonts that we are using in this document.
ASSERT_FALSE(originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Arvo"; }));
ASSERT_FALSE(
originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Amethysta"; }));
// Use the "SetFontsFolder" method to set a directory which will act as a new font source.
// Pass "false" as the "recursive" argument to include fonts from all the font files that are in the directory
// that we are passing in the first argument, but not include any fonts in any of that directory's subfolders.
// Pass "true" as the "recursive" argument to include all font files in the directory that we are passing
// in the first argument, as well as all the fonts in its subdirectories.
FontSettings::get_DefaultInstance()->SetFontsFolder(FontsDir, recursive);
ArrayPtr<SharedPtr<FontSourceBase>> newFontSources = FontSettings::get_DefaultInstance()->GetFontsSources();
ASSERT_EQ(1, newFontSources->get_Length());
ASSERT_FALSE(newFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Arial"; }));
ASSERT_TRUE(newFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Arvo"; }));
// The "Amethysta" font is in a subfolder of the font directory.
if (recursive)
{
ASSERT_EQ(25, newFontSources[0]->GetAvailableFonts()->get_Count());
ASSERT_TRUE(newFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Amethysta"; }));
}
else
{
ASSERT_EQ(18, newFontSources[0]->GetAvailableFonts()->get_Count());
ASSERT_FALSE(newFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Amethysta"; }));
}
doc->Save(ArtifactsDir + u"FontSettings.SetFontsFolder.pdf");
// Restore the original font sources.
FontSettings::get_DefaultInstance()->SetFontsSources(originalFontSources);

◆ SetFontsFolders()

void Aspose::Words::Fonts::FontSettings::SetFontsFolders ( const System::ArrayPtr< System::String > &  fontsFolders,
bool  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
fontsFoldersAn array of folders that contain TrueType fonts.
recursiveTrue to scan the specified folders for fonts recursively.
Examples

Shows how to set multiple font source directories.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->get_Font()->set_Name(u"Amethysta");
builder->Writeln(u"The quick brown fox jumps over the lazy dog.");
builder->get_Font()->set_Name(u"Junction Light");
builder->Writeln(u"The quick brown fox jumps over the lazy dog.");
// Our font sources do not contain the font that we have used for text in this document.
// If we use these font settings while rendering this document,
// Aspose.Words will apply a fallback font to text which has a font that Aspose.Words cannot locate.
ArrayPtr<SharedPtr<FontSourceBase>> originalFontSources = FontSettings::get_DefaultInstance()->GetFontsSources();
ASSERT_EQ(1, originalFontSources->get_Length());
ASSERT_TRUE(originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Arial"; }));
// The default font sources are missing the two fonts that we are using in this document.
ASSERT_FALSE(
originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Amethysta"; }));
ASSERT_FALSE(
originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Junction Light"; }));
// Use the "SetFontsFolders" method to create a font source from each font directory that we pass as the first argument.
// Pass "false" as the "recursive" argument to include fonts from all the font files that are in the directories
// that we are passing in the first argument, but not include any fonts from any of the directories' subfolders.
// Pass "true" as the "recursive" argument to include all font files in the directories that we are passing
// in the first argument, as well as all the fonts in their subdirectories.
FontSettings::get_DefaultInstance()->SetFontsFolders(MakeArray<String>({FontsDir + u"/Amethysta", FontsDir + u"/Junction"}), recursive);
ArrayPtr<SharedPtr<FontSourceBase>> newFontSources = FontSettings::get_DefaultInstance()->GetFontsSources();
ASSERT_EQ(2, newFontSources->get_Length());
ASSERT_FALSE(newFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Arial"; }));
ASSERT_EQ(1, newFontSources[0]->GetAvailableFonts()->get_Count());
ASSERT_TRUE(newFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Amethysta"; }));
// The "Junction" folder itself contains no font files, but has subfolders that do.
if (recursive)
{
ASSERT_EQ(6, newFontSources[1]->GetAvailableFonts()->get_Count());
ASSERT_TRUE(
newFontSources[1]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Junction Light"; }));
}
else
{
ASSERT_EQ(0, newFontSources[1]->GetAvailableFonts()->get_Count());
}
doc->Save(ArtifactsDir + u"FontSettings.SetFontsFolders.pdf");
// Restore the original font sources.
FontSettings::get_DefaultInstance()->SetFontsSources(originalFontSources);

◆ SetFontsSources() [1/2]

void Aspose::Words::Fonts::FontSettings::SetFontsSources ( const System::ArrayPtr< System::SharedPtr< Aspose::Words::Fonts::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
sourcesAn array of sources that contain TrueType fonts.
Examples

Shows how to add a font source to our existing font sources.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->get_Font()->set_Name(u"Arial");
builder->Writeln(u"Hello world!");
builder->get_Font()->set_Name(u"Amethysta");
builder->Writeln(u"The quick brown fox jumps over the lazy dog.");
builder->get_Font()->set_Name(u"Junction Light");
builder->Writeln(u"The quick brown fox jumps over the lazy dog.");
ArrayPtr<SharedPtr<FontSourceBase>> originalFontSources = FontSettings::get_DefaultInstance()->GetFontsSources();
ASSERT_EQ(1, originalFontSources->get_Length());
ASSERT_TRUE(originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Arial"; }));
// The default font source is missing two of the fonts that we are using in our document.
// When we save this document, Aspose.Words will apply fallback fonts to all text formatted with inaccessible fonts.
ASSERT_FALSE(
originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Amethysta"; }));
ASSERT_FALSE(
originalFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Junction Light"; }));
// Create a font source from a folder that contains fonts.
auto folderFontSource = MakeObject<FolderFontSource>(FontsDir, true);
// Apply a new array of font sources that contains the original font sources, as well as our custom fonts.
ArrayPtr<SharedPtr<FontSourceBase>> updatedFontSources = MakeArray<SharedPtr<FontSourceBase>>({originalFontSources[0], folderFontSource});
FontSettings::get_DefaultInstance()->SetFontsSources(updatedFontSources);
// Verify that Aspose.Words has access to all required fonts before we render the document to PDF.
updatedFontSources = FontSettings::get_DefaultInstance()->GetFontsSources();
ASSERT_TRUE(updatedFontSources[0]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Arial"; }));
ASSERT_TRUE(updatedFontSources[1]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Amethysta"; }));
ASSERT_TRUE(
updatedFontSources[1]->GetAvailableFonts()->LINQ_Any([](SharedPtr<PhysicalFontInfo> f) { return f->get_FullFontName() == u"Junction Light"; }));
doc->Save(ArtifactsDir + u"FontSettings.AddFontSource.pdf");
// Restore the original font sources.
FontSettings::get_DefaultInstance()->SetFontsSources(originalFontSources);

◆ SetFontsSources() [2/2]

void Aspose::Words::Fonts::FontSettings::SetFontsSources ( const System::ArrayPtr< System::SharedPtr< Aspose::Words::Fonts::FontSourceBase > > &  sources,
const System::SharedPtr< System::IO::Stream > &  cacheInputStream 
)

Sets the sources where Aspose.Words looks for TrueType fonts and additionally loads previously saved font search cache.

Loading previously saved font search cache will speed up the font cache initialization process. It is especially useful when access to font sources is complicated (e.g. when fonts are loaded via network).

When saving and loading font search cache, fonts in the provided sources are identified via cache key. For the fonts in the SystemFontSource and FolderFontSource cache key is the path to the font file. For MemoryFontSource and StreamFontSource cache key is defined in the CacheKey and CacheKey properties respectively. For the FileFontSource cache key is either CacheKey property or a file path if the CacheKey is null.

It is highly recommended to provide the same font sources when loading cache as at the time the cache was saved. Any changes in the font sources (e.g. adding new fonts, moving font files or changing the cache key) may lead to the inaccurate font resolving by Aspose.Words.

Parameters
sourcesAn array of sources that contain TrueType fonts.
cacheInputStreamInput stream with saved font search cache.

◆ Type()

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