Class FontCollection

Namespace

Egami.Fonts

Assembly

Egami.Fonts.dll

A set of faces grouped into families: the caller's own, or System for the fonts installed on the machine. Finds families by name and faces by style with the CSS Fonts Level 4 matching steps.

public sealed class FontCollection : IReadOnlyCollection<FontFamily>, IEnumerable<FontFamily>, IEnumerable

Inheritance

object

FontCollection

Implements

IReadOnlyCollection<FontFamily>

IEnumerable<FontFamily>

IEnumerable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// Installed fonts, found without native calls and indexed on first use; a style is matched by the CSS rules.
FontMatch? match = FontCollection.System.Match(GenericFamily.SansSerif, FontStyle.Bold);

// Your own fonts work the same way; System is read-only, so add the installed fonts to your collection to have both.
var fonts = new FontCollection();
fonts.AddFile(FontFile);
fonts.AddSystemFonts();
FontMatch noto = fonts.Match("Noto Sans", FontStyle.BoldItalic)!.Value;
Font font = noto.ToFont(16);

Remarks

Faces group under their typographic family (name ID 16, else 1). A name lookup tries, in order, the typographic family, the legacy family (ID 1), the full name (ID 4) and the PostScript name (ID 6), comparing case-insensitively in every language the fonts hold. A name not found returns null or false: nothing is swapped in silently.

Files added by path are indexed from their name and OS/2 tables only and loaded when a face is matched. Adding is thread-safe; lookups see the faces added before they started.

Constructors

FontCollection(FontLoadOptions?)

Initializes an empty collection.

public FontCollection(FontLoadOptions? options = null)

Parameters

options FontLoadOptions

How faces are loaded when matched, or null for Default.

Examples

// Installed fonts, found without native calls and indexed on first use; a style is matched by the CSS rules.
FontMatch? match = FontCollection.System.Match(GenericFamily.SansSerif, FontStyle.Bold);

// Your own fonts work the same way; System is read-only, so add the installed fonts to your collection to have both.
var fonts = new FontCollection();
fonts.AddFile(FontFile);
fonts.AddSystemFonts();
FontMatch noto = fonts.Match("Noto Sans", FontStyle.BoldItalic)!.Value;
Font font = noto.ToFont(16);

Properties

Count

Gets the number of families.

public int Count { get; }

Property Value

int

Families

Gets the families, sorted by name.

public IReadOnlyList<FontFamily> Families { get; }

Property Value

IReadOnlyList<FontFamily>

Options

Gets the options faces are loaded with.

public FontLoadOptions Options { get; }

Property Value

FontLoadOptions

System

Gets the fonts installed on this machine, found without native calls by scanning the platform's font directories (Windows: the Windows and per-user Fonts folders; macOS: the System, Library and user Fonts folders; Linux: the fontconfig dir entries and the usual share/fonts folders). Indexed on first use; Refresh() rescans. It is read-only: to match your own fonts beside the installed ones, call AddSystemFonts() on a collection of your own.

public static FontCollection System { get; }

Property Value

FontCollection

Methods

Add(Typeface)

Adds a loaded face.

public void Add(Typeface typeface)

Parameters

typeface Typeface

The face.

Exceptions

InvalidOperationException

The collection is System, which is read-only.

AddDirectory(string, bool)

Adds every font file in a directory; files that cannot be read are skipped with a Font.FileSkipped diagnostic.

public int AddDirectory(string path, bool recursive = true)

Parameters

path string

The directory.

recursive bool

Whether to look in subdirectories too.

Returns

int

The number of faces added.

Exceptions

DirectoryNotFoundException

The directory does not exist.

InvalidOperationException

The collection is System, which is read-only.

AddFile(string)

Adds every face of a font file, indexed from its names and loaded when matched.

public int AddFile(string path)

Parameters

path string

A .ttf, .otf, .ttc, .otc, .woff or .woff2 file; a web font is decompressed and loaded at once.

Returns

int

The number of faces added.

Exceptions

UnsupportedFormatException

The file is not a TrueType or OpenType font or collection.

CorruptDataException

The file's headers cannot be read.

InvalidOperationException

The collection is System, which is read-only.

AddSystemFonts()

Adds the installed fonts, as System has indexed them (indexing them first if it has not yet), so they can be matched beside your own. The faces load with this collection's Options; Refresh() on System later does not change them.

public int AddSystemFonts()

Returns

int

The number of faces added.

Examples

// Installed fonts, found without native calls and indexed on first use; a style is matched by the CSS rules.
FontMatch? match = FontCollection.System.Match(GenericFamily.SansSerif, FontStyle.Bold);

// Your own fonts work the same way; System is read-only, so add the installed fonts to your collection to have both.
var fonts = new FontCollection();
fonts.AddFile(FontFile);
fonts.AddSystemFonts();
FontMatch noto = fonts.Match("Noto Sans", FontStyle.BoldItalic)!.Value;
Font font = noto.ToFont(16);

Exceptions

InvalidOperationException

The collection is System, which is read-only.

GetEnumerator()

Returns the families, sorted by name.

public IEnumerator<FontFamily> GetEnumerator()

Returns

IEnumerator<FontFamily>

The enumerator.

Match(GenericFamily, FontStyle)

Matches a generic family through the platform's preference list, then the other platforms' lists.

public FontMatch? Match(GenericFamily generic, FontStyle style)

Parameters

generic GenericFamily

The generic family.

style FontStyle

The style wanted.

Returns

FontMatch?

The best face of the first listed family present, or null when none is present.

Match(string, FontStyle)

Finds a family by name and matches a style in it.

public FontMatch? Match(string familyName, FontStyle style)

Parameters

familyName string

The family, full or PostScript name.

style FontStyle

The style wanted.

Returns

FontMatch?

The best face and the synthesis it wants, or null when no face has the name.

MatchTypeface(string, FontStyle)

Finds a family by name and returns the face that best matches a style.

public Typeface? MatchTypeface(string familyName, FontStyle style)

Parameters

familyName string

The family, full or PostScript name.

style FontStyle

The style wanted.

Returns

Typeface

The face, or null when no face has the name.

Refresh()

Rescans the installed fonts (for System); a collection of the caller's own is left as it is.

public void Refresh()

TryGetFamily(string, out FontFamily)

Finds a family by name: typographic family, legacy family, full name or PostScript name, in that order.

public bool TryGetFamily(string name, out FontFamily family)

Parameters

name string

The name, compared case-insensitively.

family FontFamily

The family, or null.

Returns

bool

true if a face has the name.