Fonts and Text

DynamicPDF Core Suite for .NET supports the 14 core fonts present in every PDF Reader, 7 CJK fonts, Google Fonts, and supports embedding OpenType (TrueType), Type 1 fonts, Web Fonts (WOFF) version 1.0 and TrueType Collections (TTC) in a PDF document. DynamicPDF Core Suite for .NET also supports advanced typographic features such as font kerning and character spacing. This section describes how to use each font in a PDF document and how to use font kerning, text encoding, and character shaping when creating a PDF document.

Supported Fonts:

Fonts

DynamicPDF Core Suite for .NET has built-in support for 14 core PDF fonts and 7 CJK fonts and are supplied as part of every compliant PDF reader. In contrast, the other fonts supported by DynamicPDF require embedding a font file containing the font before using the font in the document. When the Generator creates the document, it embeds the uploaded font. Supplied fonts do not have this limitation and are not embedded.

Supplied Fonts:

Fonts Requiring Embedding:

Core Fonts

Every PDF viewer includes the following 14 core fonts.

Core Fonts:

DynamicPDF Core Suite supports the 14 core fonts through static properties that specify the font's name in the Font class.

Font class static properties.

Using one of the core fonts is as easy as specifying the font name via the Font class static property. Because every PDF Viewer includes this font, you are not required to do anything more than use the font name when specifying a font.

The following example illustrates using a core font in a TextArea.

// Use a core font in a text area Page Element.
page.Elements.Add( new TextArea( "Text", 0, 0, 200, 12, Font.TimesRoman, 12 ) );       

' Use a core font in a text area Page Element.
MyPage.Elements.Add( New TextArea( "Text", 0, 0, 200, 12, Font.TimesRoman, 12 ) )

Helvetica is equivalent to the Arial TrueType font included on Windows systems, and Times is equivalent to the Times New Roman TrueType font included on Windows systems. Whenever possible, for efficiency, use the equivalent core font when specifying a font type.

CJK Fonts

PDF viewer software with the Adobe Asian Font Pack installed supports the following 7 CJK fonts and does not require embedding in a PDF document. DynamicPDF supports the 7 CJK PDF fonts through the following Font class static properties.

Font class static properties for CJK fonts:

The following example illustrates using a CJK font when creating a new TextArea.

// Use a core font in a text area Page Element.
page.Elements.Add( new TextArea( "CJK Text", 0, 0, 200, 12, Font.HeiseiKakuGothicW5, 16 ) );        

' Use a core font in a text area Page Element.
MyPage.Elements.Add( New TextArea( "CJK Text", 0, 0, 200, 12, Font.HeiseiKakuGothicW5, 16 ) )

CJK fonts require specifying "CJK Text" in a constructor when using a CJK font.

Google Fonts

DynamicPDF Core Suite supports Google Fonts.

GoogleFont

The GoogleFont class inherits from OpenTypeFont, however, the easiest way to use a Google Font is through the following two overloaded methods in the Font class.

public static GoogleFont Google(string fontName, bool bold = false, bool italic = false);
public static GoogleFont Google(string fontName, int weight = 400, bool italic = false);

Be certain the Google Font selected supports the style specified and the character type specified. Use Google Fonts Search for determining a font's supported formatting.

For example, the following illustrates using a Google Font.

Document document = new Document();
Page page = new Page(PageSize.Letter, PageOrientation.Portrait, 54.0f);
document.Pages.Add(page);
Label label = new Label("Zilla Slab", 0, 0, 504, 300, Font.Google("Zilla Slab", true, true), 18, TextAlign.Center);
page.Elements.Add(label);
GoogleFont aFont = Font.Google("Zilla Slab", true, true);
Label label2 = new Label("Zilla Slab Two",0, 100, 504, 300, aFont, 18, TextAlign.Center);
page.Elements.Add(label2);
document.Draw(@"c:\temp\fonts-core-suite\output.pdf");

OpenType Fonts

OpenType fonts (TrueType) require creating an OpenTypeFont object and specifying the path to the OpenType font in the constructor. That font is then used while creating the PDF, for example, when adding a Label or TextArea to a document.

In the following example, you create an OpenTypeFont instance and pass the veranda.otf font to the constructor. You then use the OpenTypeFont object instance to create a TextArea.

// Create a OpenType font class.
OpenTypeFont openTypeFont = new OpenTypeFont( "verdana.otf" ); 
// Use the OpenType font in a text area Page Element. 
page.Elements.Add( new TextArea("Text", 0, 0, 200, 12, openTypeFont, 12 ) );        

' Create a OpenType font class.
Dim MyOpenTypeFont As OpenTypeFont = New OpenTypeFont( "verdana.otf" )
' Use the OpenType font in a text area Page Element.
MyPage.Elements.Add( New TextArea( "Text", 0, 0, 200, 12, MyOpenTypeFont, 12 ) )

Embedding

By default, when generating a PDF using an OpenType font, only the characters used are embedded in the resulting PDF document. Embedding only the characters used dramatically reduces the resulting file size. However, you can override this behavior and embed all a font's characters by setting the Embed property of the OpenTypeFont to true. When set to True, the font embeds all characters - used and unused - in the generated PDF.

PDF/A documents embed all font characters in a generated PDF document.

// Create a open type font
OpenTypeFont opentypefont = new OpenTypeFont(fontPath);
//Create a label
Label label = new Label("This text uses opentype font ", 0, 0, 300, 300);
//embed all characters
opentypefont.Embed = true;
// Assign opentype font to label
label.Font = opentypefont;

OpenType Font Reuse

When using the same OpenType font multiple times within the same document, be sure to create an OpenTypeFont instance once only. Then, after creating the OpenTypeFont instance, use the font as needed while creating the PDF. This reuse significantly reduces file size by preventing the PDF from embedding the font multiple times in the same document. For efficiency, when creating multiple PDF documents, always reuse the created OpenType font across multiple documents.

If an OpenType font contains TrueType style font data (TrueType outlines), and not PostScript type font data, then that font is shared and is only included once if used multiple times in a PDF document. However, reusing the same font object is much more efficient and should be done wherever possible.

Type1 Fonts

Create a Type1 font by using the Type1Font class. To create the font, instantiate a new Type1Font instance and then specify the path to the metrics file (.PFM or .AFM) and the font file (.PFB) in the class's constructor. DynamicPDF Core Suite then uses the created font instance when creating the PDF document.

The following example illustrates creating a Type1Font and using the font in a Label and TextArea class constructor.

// Create a Type 1 font.
Type1Font type1Font = new Type1Font( @"C:\Eras.pfm", @"C:\Eras.pfb" );
// Use the Type 1 font in a text area Page Element.
page.Elements.Add( new TextArea( "Text", 0, 0, 200, 12, type1Font, 12 ) );        

' Create a Type 1 font.
Dim MyType1Font As Type1Font = New Type1Font( "C:\Eras.pfm", "C:\Eras.pfb" )
' Use the Type 1 font in a text area Page Element.
MyPage.Elements.Add( New TextArea( "Text", 0, 0, 200, 12, MyType1Font, 12 ) )

Type 1 Font Reuse

When using the same Type 1 font many times within the same document, it is important to create the Type1Font object only once, and use it where ever needed. Doing this will prevent the font from being embedded in the document multiple times.

Web Open Font Format v1 (WOFF)

WOFF is a font format popularized by its use in web pages on the WWW. WOFF is essentially a TrueType or OpenType font with additional compression and metadata. Although WOFF has two versions, DynamicPDF supports only the first version of WOFF (WOFF 1.0). Version 2 (WOFF 2.0) will be supported in a future version.

DynamicPDF only supports WOFF 1.0

To use a WOFF font in a PDF, first create a WebOpenFont instance with the font's file path passed to the constructor. Then reuse the font as needed throughout the PDF.

Web fonts created using DynamicPDF are converted to the equivalent TrueType font when generating the resultant PDF document.

The following illustrates using a WOFF font to create a PDF document.

// Create a WebOpenFont font class.
WebOpenFont webOpenFont = new WebOpenFont("roboto-v20-latin-regular.woff"); 

// Use the web font in a text area Page Element. 
page.Elements.Add( new TextArea("Text", 0, 0, 200, 12, webOpenFont, 12 ));      

' Create a WebOpenFont font class.
Dim webOpenFont As WebOpenFont = New WebOpenFont("roboto-v20-latin-regular.woff")

MyPage.Elements.Add(New TextArea("Text", 0, 0, 200, 12, webOpenFont, 12 ))

Embedding

By default, when generating a PDF using WebOpenFont, only the characters used are embedded in the resulting PDF document. Embedding only the characters used dramatically reduces the resulting file size. You can override this behavior and embed all the characters by setting the Embed property of the WebOpenFont to true. When set to true, the font embeds all characters - used and unused - in a generated PDF.

Font Reuse

When using the same WOFF font multiple times within the same document, be sure to create a WebOpenFont instance once only. Then use the font as needed throughout the PDF. This reuse significantly reduces the resulting file size by preventing the PDF from embedding the font multiple times in the same document.

TrueType Collections

A TrueType Collection (TTC) is a collection of TrueType fonts combined into a single file structure. In TrueType Collections the common glyphs are shared among the fonts present in the collection and reduces file space. DynamicPDF accesses TTC fonts using an index or font name. For example, if a TTC contains four TrueType fonts, then each font's index is determined by its location in the TTC, beginning with zero index value.

The following examples illustrate using a TTC by specifying index and a TTC by specifying font name.

TTC Specifying Index

OpenTypeFontCollection collection = new OpenTypeFontCollection("fontName.ttc");
OpenTypeFont font = collection.GetFont(3);     

Dim collection As OpenTypeFontCollection = new OpenTypeFontCollection("fontName.ttc");
Dim font As OpenTypeFont = collection.GetFont(3)

TTC Specifying Font Name

OpenTypeFontCollection collection = new OpenTypeFontCollection("fontName.ttc");

//Gets all font names present in the TTC
string[] fontNames = collection.GetFontNames();

OpenTypeFont font = collection.GetFont(fontNames[3]);    

Dim collection As OpenTypeFontCollection = new OpenTypeFontCollection("fontName.ttc");

' Gets all font names present in the TTC
Dim fontNames As String() = collection.GetFontNames()

Dim font As OpenTypeFont = collection.GetFont(fontNames(3))

Specifying an index or font name not present in a true type collection results in an exception.

Font Kerning

In typography, kerning is the process of adjusting the spacing between characters in a proportional font and adjusts the space between individual letter forms, while tracking (letter-spacing) adjusts spacing uniformly over a range of characters. DynamicPDF supports both kerning and tracking in constructing PDF documents.

Kerning

Kerning (different from tracking) is a font's ability to adjust the spacing between individual pairs of letters. The kerning is dependent on how a particular combination of letters fit together when sitting side by side and is typically only defined for non-fixed width fonts. A font's kerning pair table defines the kerning values for a font's character combinations, although not every font contains this kerning information. Of the built-in Core Fonts, all Helvetica and Times New Roman fonts include kerning information.

By default, a font reads all kerning values directly. Using DynamicPDF, you can also change default kerning values by adjusting or setting the kerning values for any font. Adjusting a fonts kerning values is done through the use of the TextArea page element. After specifying a font in a TextArea, you have three options for adding kerning to the text in the TextArea.

Kerning options in a TextArea:

Use the HasKerning method to check if a font has supplied the kerning pairs table. If the method returns true, then the font has provided a table of kerning pairs. Customizing any kerning pairs requires setting a TextArea EnabledKerning property to True. You then retrieve the kerning values for the supplied TextArea by calling the TextArea instance's GetKernValue method. This method returns a KernValue instance consisting of an array of short values (Spacing) and a character array (Text). The character array is an array of every character in the TextArea, while the short array is an array of the kerning value for each character combination. If a TextArea font does not contain a kerning pairs table, and the TextArea instance's EnableKerning property is true, then the resulting KernValues object array of spacing values is filled with zeros.

Tracking

Tracking is the amount of overall space between all letters. Increase this value using similar methods as described above. However, to increase the tracking requires looping over the entire TextArea KernValues property's Spacing array and assigning a value to every pair (or subset of pairs). While kerning usually focuses on specific character pairs, tracking sets the overall space for every character in an array. Values stored in a KernValues instance's Spacing array are expressed as thousandths of a unit of font size. Specifically, a value in a Spacing array of 100 with a font size of 20 will make an adjustment of 2 points (100 x 20 /1000). Remember, a positive value in a Spacing array pulls characters closer (as is usual for kerning), while a negative value increases the space between letters (as is typical for tracking).

The following example illustrates applying tracking to a text block in a TextArea.

Document document = new Document();
Page page = new Page();
string text = "To and WA are examples of when kerning would be used.";
TextArea textArea = new TextArea(text, 10, 10, 400, 700, Font.TimesRoman);

// Must be enabled before kern values can be read
textArea.KerningEnabled = true;
KerningValues kernValues = textArea.GetKerningValues();

// Assign positive value for making the space between chars closer and negative value for making the space further
for (int i = 0; i < kernValues.Spacing.Length; i++)
{
        kernValues.Spacing[i] = (short)(kernValues.Spacing[i] - 400);
}

page.Elements.Add(textArea);
document.Pages.Add(page);
document.Draw(pdfFilePath);       

Dim MyDocument As New Document()
Dim MyPage As New Page()
Dim MyText As String = "To and WA are examples of when kerning would be used."
Dim MyTextArea As New TextArea(MyText, 10, 10, 400, 700, Font.TimesRoman)

' Must be enabled before kern values can be read
MyTextArea.KerningEnabled = True
Dim MyKernValues As KerningValues = MyTextArea.GetKerningValues()

' Assign positive value for making the space between chars closer and negative value for making the space further
For i As Integer = 0 To MyKernValues.Spacing.Length - 1
    MyKernValues.Spacing(i) = Short.Parse((MyKernValues.Spacing(i) - 400).ToString)
Next

MyPage.Elements.Add(MyTextArea)
MyDocument.Pages.Add(MyPage)
MyDocument.Draw(pdfFilePath)

Character Shaping

Character Shaping or Complex Text Layout (CTL) is the selection of the required shape of a character based on that character’s position within a word and its surrounding characters. Fonts that use characters shaping are supported; however, be sure to consider the programming and deployment considerations listed below.

This example demonstrates how to use a font with character shaping when adding text using a TextArea page element.

// Create a PDF Document
Document document = new Document();
// Create an OpenTypeFont object with useCharacterShaping parameter set to true. 
OpenTypeFont charShapingFont = new OpenTypeFont("Path to .ttf or .otf font file", true);
// Create a page and add it to the document
Page page = new Page();
document.Pages.Add(page);
// Create and add a TextArea that uses the OpenTypeFont object.  
TextArea area = new TextArea("Text requiring character shaping", 0, 0, 300, 30, charShapingFont, 18);
page.Elements.Add(area);
// Save the PDF
document.Draw(pdfFilePath);        

'Create a PDF Document
Dim document As Document = New Document()
' Create an OpenTypeFont object with useCharacterShaping parameter set to true. 
Dim charShapingFont As OpenTypeFont = New OpenTypeFont("Path to .ttf or .otf font file"", True)
' Create a Page and add it to the document
Dim page As Page = New Page()
document.Pages.Add(page)
' Create and add a TextArea that uses the OpenTypeFont object.  
Dim area As TextArea = New TextArea("Text requiring character shaping", 0, 0, 300, 30, charShapingFont, 18)
page.Elements.Add(area)
' Save the PDF
document.Draw(pdfFilePath)

Considerations

HarfBuzz Language Support

Beginning with DynamicPDF Core Suite version 11, character shaping logic is native and works as expected in most situations. However, the native character shaping may work incorrectly with older fonts that use reverse chaining contextual single substitution (such as older Arabic or Hebrew fonts), or with some languages that require complex character shaping logic (such as Bengali, Kannada or Malayalam). You can use an external Harfbuzz DLL when the language or font produces an expected output. Please contact support for more information on using the external Harfbuzz DLL.

Text Encoding

When using a non-symbolic Core Font (Symbol and ZapfDingbats being the exception), Latin 1 encoding is used by default. Specify alternate encodings when they are needed to allow access to characters specific to those encodings. Access these encodings through the Encoder class static properties.

Encoder class text encoding properties:

A specific encoding can be specified and used as follows:

// Create a core font with a specified encoding.
Font centralEuropeHelveticaFont = new Helvetica( Encoder.CentralEurope );
// Use the font in a text area Page Element.
page1.Elements.Add( new TextArea( "Text", 0, 0, 200, 12, centralEuropeHelveticaFont, 12 ) );        

' Create a core font with a specified encoding.
Dim MyCentralEuropeHelveticaFont As Font = New Helvetica( Encoder.CentralEurope )
' Use the font in a text area Page Element.
MyPage1.Elements.Add( New TextArea( "Text", 0, 0, 200, 12, MyCentralEuropeHelveticaFont, 12 ) )

In this topic