Use DXFontRepository to Add Custom Fonts
- 5 minutes to read
The DXFontRepository class allows you to use fonts that are not installed in the hosting environment. Add required fonts to the font repository to eliminate font substitution effects. This class is available for the following products:
- Word Processing Document API
- Spreadsheet Document API
- PDF Document API (used in graphics content only)
- Reporting
- Charts
- Rich Text Editor and Spreadsheet controls (WinForms/WPF)
Use the FontRepository.Instance static property to access a DXFontRepository instance.
Loaded fonts are not saved to the document - they are used to display, print, or export Word and Spreadsheet documents. Custom fonts are applied to the report when it is exported to PDF or an image from code.
Add Fonts to the Repository Directly
Use the DXFontRepository.AddFont method overloads to add fonts to the font repository. You can load a font from a file, stream, or byte array.
Supported font formats include:
TrueType fonts (.TTF)
OpenType fonts that use CFF (Compact Font Format) glyph outlines (.OTF)
OpenType Font Collections (.TTC, .OTC) that contain multiple fonts in a single file
To avoid excessive layout recalculations, add the fonts to DXFontRepository before you load a document, report, or chart that uses these fonts.
The code sample below adds custom fonts to DXFontRepository. This example uses the following preloaded Google Fonts:
using DevExpress.Drawing;
//...
DXFontRepository.Instance.AddFont(@"Fonts\EmilysCandy-Regular.ttf");
DXFontRepository.Instance.AddFont(@"Fonts\FrederickatheGreat-Regular.ttf");
// you usage code here
//...
Identify Missing Fonts and Add Them to the Repository
Your document design and layout may rely on a font type that is not available in the application’s hosting environment. As a result, the font cannot be installed on the client machine, in a Docker image, in Azure, or in another host/container. In such cases, your document replaces unavailable fonts with default fonts, which may alter the appearance of a document from the original design.
The DXFontRepository contains a mechanism to ensure that a document uses the correct fonts regardless of the hosting environment. A document will notify the application about missing typefaces so that you can obtain the required font data. Once you obtain these fonts, add them to the DXFontRepository, thus making them available to DevExpress controls.
The DXFontRepository.QueryNotFoundFont event fires for every unavailable font type. Handle this event to do the following:
- Identify the missing typeface and its suggested alternative (e.RequestedFont and e.ActualFont)
- Obtain the required font file from a font hosting service (such as Google Fonts)
- Prepare a byte array and pass it to e.FontFileData
This implementation ensures that DXFontRepository contains all required font types before document generation begins.
The following code sample contains simple code that registers the preloaded “Sankofa Display” font in case it is unavailable in the application environment:
private static void Report_QueryNotFoundFont(object sender, NotFoundFontEventArgs e) {
if (e.RequestedFont == "Sankofa Display") {
string font = Environment.CurrentDirectory + "\\Data\\SankofaDisplay-Regular.ttf";
e.FontFileData = File.ReadAllBytes(font);
}
}
Obtain Missing Fonts from a Font Hosting Service (Google Fonts)
You can use the DXFontRepository.QueryNotFoundFont event to identify missing fonts and download them from a hosting service. The following example implements a service that asynchronously downloads missing fonts from Google Fonts and adds them to DXFontRepository.
Use your personal Google API Key to run this example. For instructions on how to obtain your key, see Google Fonts Developer API.
Assign your API Key to the apiKey variable in the FontCollectorService.cs file before you launch the example.
Review license agreements associated with fonts that you use. Use and redistribution permissions may vary. The service used in this example (Google Fonts) hosts fonts that are open source and available at no cost. Review the following page for details: Google Fonts FAQ.
The report in this example contains a few fonts that may be missing in many hosting environments: Ga Maamli, Roboto, and Nerko One. The example obtains these fonts if missing and makes them available to report controls. When exported to PDF, the report uses the original fonts:
Obtain Information About Fonts in the Repository
Use the FontRepository.GetFonts method to return a list of all fonts in the font repository. Each item in this list is a DXFontData object that contains font information.
The following code sample retrieves the names of all fonts in the repository and displays this information in the console window:
using DevExpress.Drawing;
using System;
using System.Collections.Generic;
// ...
if (DXFontRepository.Instance.IsEmpty)
Console.WriteLine("Font repository is empty.");
else
{
Console.WriteLine("Font repository contains the following fonts:");
IList<DXFontData> fonts = DXFontRepository.Instance.GetFonts();
for (int i = 0; i < fonts.Count; i++)
{
Console.WriteLine($" \u002A {fonts[i].Name}");
}
}
The following image demonstrates a sample console output:
Clear the Font Repository
Call the DXFontRepository.Clear method to remove all fonts from the font repository. Use the DXFontRepository.IsEmpty property to check whether the repository contains fonts.