Class PdfFontOptions

Namespace

DocToolkit

Assembly

DocToolkit.Primitives.dll

Fonts the caller supplies for characters the renderer cannot otherwise encode.

public sealed class PdfFontOptions

Inheritance

object

PdfFontOptions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Without this, whether a document renders depends on the machine it renders on. A document containing Cyrillic, Greek or CJK converts on one host and is refused on another, because the renderer falls back to whatever fonts that machine happens to have — measured, a Windows box offers Segoe UI Symbol and Segoe UI Emoji, neither of which covers Cyrillic. That machine-dependence is the one thing a package whose whole premise is "runs everywhere .NET does" should not have.

Nothing is shipped inside this package to fix it, deliberately. A font covering Cyrillic, Greek and CJK is measured in megabytes against a package measured in tens of kilobytes, and every consumer would pay it to serve the minority converting non-Latin text — plus a licence family this repository has never audited. So the bytes come from the caller, who already licenses the typeface their documents are written in and knows which one that is.

This is opt-in and changes nothing for anybody who does not use it. Two effects are worth knowing before you do.

1. The fonts you supply REPLACE the host's own fallbacks; they do not add to them. That makes supplying too few actively worse than supplying none, which is the opposite of what the name suggests. Measured over 99 real documents:

• no font supplied — 71/99
• one font (Arial) — 63/99: it fixed the 4 documents needing Cyrillic and broke 12 that the host's own fallbacks had been covering
• four fonts — 77/99

So supply fonts covering everything your documents use, not just the script that failed. The refusal names the character it could not encode, which tells you what is still missing.

2. It changes how fonts are embedded generally. Measured on an ordinary Latin document, output went from 128,755 bytes to 1,306 — the same base-14 swing this project already records as varying PDF size a hundredfold. Both render correctly; the smaller leans on the standard fonts every reader has.

There is deliberately no compiled example for this type, which is worth explaining because every other public type here has one. This project's examples are real tests, so they run - and a runnable example of this would need a font file committed to the repository, which is the exact thing the paragraph above says not to do. An example that used a system font by path would then be a claim that only holds on the machine that wrote it.

Constructors

PdfFontOptions(string, byte[])

Creates options carrying one font.

public PdfFontOptions(string fontName, byte[] trueTypeFont)

Parameters

fontName string

A name for the font. It labels the font inside the PDF and in diagnostics; it does not have to match a font installed on the machine, because the bytes are what is used.

trueTypeFont byte[]

The TrueType or OpenType font file's bytes.

Exceptions

ArgumentException

fontName is blank, or trueTypeFont is empty.

ArgumentNullException

trueTypeFont is null.

Properties

FontNames

The names of the fonts these options carry, in the order they will be offered.

public IReadOnlyList<string> FontNames { get; }

Property Value

IReadOnlyList<string>

Methods

Add(string, byte[])

Returns options carrying this font and one more.

public PdfFontOptions Add(string fontName, byte[] trueTypeFont)

Parameters

fontName string

A name for the font.

trueTypeFont byte[]

The TrueType or OpenType font file's bytes.

Returns

PdfFontOptions

Remarks

Returns a new instance rather than mutating, so an options object handed to a converter cannot change under it — the same reasoning that makes every converter here static and stateless.

Order matters. Fonts are offered to the renderer in the order added, so put the one covering the most of your text first.

Exceptions

ArgumentException

fontName is blank, or trueTypeFont is empty.

ArgumentNullException

trueTypeFont is null.