package fontscan

import "github.com/go-text/typesetting/fontscan"

Index

Examples

Constants 

const (
	Fantasy   = "fantasy"
	Math      = "math"
	Emoji     = "emoji"
	Serif     = "serif"
	SansSerif = "sans-serif"
	Cursive   = "cursive"
	Monospace = "monospace"
)

Generic families as defined by https://www.w3.org/TR/css-fonts-4/#generic-font-families

Functions

func DefaultFontDirectories 

func DefaultFontDirectories(logger Logger) ([]string, error)

DefaultFontDirectories return the OS-dependent usual directories for fonts, or an error if no one exists. These are the directories used by `FontMap.UseSystemFonts` to locate fonts.

Types

type FontMap 

type FontMap struct {
	// contains filtered or unexported fields
}

FontMap provides a mechanism to select a [font.Face] from a font description. It supports system and user-provided fonts, and implements the CSS font substitutions rules.

Note that FontMap is NOT safe for concurrent use, but several font maps may coexist in an application.

FontMap is mainly designed to work with an index built by scanning the system fonts : see [UseSystemFonts] for more details.

func NewFontMap 

func NewFontMap(logger Logger) *FontMap

NewFontMap return a new font map, which should be filled with the `UseSystemFonts` or `AddFont` methods. The provided logger will be used to record non-fatal errors encountered during font loading. If logger is nil, log.Default() is used.

func (*FontMap) AddFace 

func (fm *FontMap) AddFace(face font.Face, location Location, md meta.Description)

[AddFace] inserts an already-loaded font.Face into the FontMap. The caller is responsible for ensuring that [md] is accurate for the face.

The order of calls to [AddFont] and [AddFace] determines relative priority of manually loaded fonts. See [ResolveFace] for details about when this matters.

Example

Code: 

{
	// Open an on-disk font file.
	fontFile, _ := os.Open("myFont.ttf") // error handling omitted
	defer fontFile.Close()

	// Load it and its metadata.
	ld, _ := loader.NewLoader(fontFile) // error handling omitted
	md := meta.Metadata(ld)
	f, _ := fontapi.NewFont(ld) // error handling omitted
	fontMap := NewFontMap(log.Default())
	fontMap.AddFace(&fontapi.Face{Font: f}, Location{File: fmt.Sprint(md)}, md)

	// set the font description
	fontMap.SetQuery(Query{Families: []string{"Arial", "serif"}}) // regular Aspect

	// `fontMap` is now ready for text shaping, using the `ResolveFace` method
}

func (*FontMap) AddFont 

func (fm *FontMap) AddFont(fontFile font.Resource, fileID, familyName string) error

[AddFont] loads the faces contained in [fontFile] and add them to the font map. [fileID] is used as the [Location.File] entry returned by [FontLocation].

If `familyName` is not empty, it is used as the family name for `fontFile` instead of the one found in the font file.

An error is returned if the font resource is not supported.

The order of calls to [AddFont] and [AddFace] determines relative priority of manually loaded fonts. See [ResolveFace] for details about when this matters.

Example

Code: 

{
	// Open an on-disk font file. Do not close it, as the fontMap will need to parse
	// it on-demand. If you need to close it, read all of the bytes into a bytes.Reader
	// first.
	fontFile, _ := os.Open("myFont.ttf") // error handling omitted

	fontMap := NewFontMap(log.Default())
	fontMap.AddFont(fontFile, "myFont.ttf", "My Font") // error handling omitted

	// set the font description
	fontMap.SetQuery(Query{Families: []string{"Arial", "serif"}}) // regular Aspect

	// `fontMap` is now ready for text shaping, using the `ResolveFace` method
}

func (*FontMap) FindSystemFont 

func (fm *FontMap) FindSystemFont(family string) (Location, bool)

FindSystemFont looks for a system font with the given [family], returning the first match, or false is no one is found.

User added fonts are ignored, and the FontMap must have been initialized with [UseSystemFonts] or this method will always return false.

Family names are compared through meta.Normalize.

func (*FontMap) FindSystemFonts 

func (fm *FontMap) FindSystemFonts(family string) []Location

FindSystemFonts is the same as FindSystemFont, but returns all matched fonts.

func (*FontMap) FontLocation 

func (fm *FontMap) FontLocation(ft font.Font) Location

FontLocation returns the origin of the provided font. If the font was not previously returned from this FontMap by a call to ResolveFace, the zero value will be returned instead.

func (*FontMap) FontMetadata 

func (fm *FontMap) FontMetadata(ft font.Font) (family string, aspect meta.Aspect)

FontMetadata returns a description of the provided font. If the font was not previously returned from this FontMap by a call to ResolveFace, the zero value will be returned instead.

func (*FontMap) ResolveFace 

func (fm *FontMap) ResolveFace(r rune) (face font.Face)

ResolveFace select a font based on the current query (see `SetQuery`), and supporting the given rune, applying CSS font selection rules. The function will return nil if the underlying font database is empty, or if the file system is broken; otherwise the returned [font.Face] is always valid.

If no fonts match the current query for the current rune according to the builtin matching process, the fonts added manually by [AddFont] and [AddFace] will be searched in the order in which they were added for a font with coverage for the provided rune. The first font covering the requested rune will be returned.

If no fonts match after the manual font search, an arbitrary face will be returned.

func (*FontMap) ResolveFaceForLang 

func (fm *FontMap) ResolveFaceForLang(lang LangID) font.Face

ResolveForLang returns the first face supporting the given language (for the actual query), or nil if no one is found.

The matching logic is similar to the one used by [ResolveFace].

func (*FontMap) SetQuery 

func (fm *FontMap) SetQuery(query Query)

SetQuery set the families and aspect required, influencing subsequent `ResolveFace` calls.

func (*FontMap) SetRuneCacheSize 

func (fm *FontMap) SetRuneCacheSize(size int)

SetRuneCacheSize configures the size of the cache powering FontMap.ResolveFace. Applications displaying large quantities of text should tune this value to be greater than the number of unique glyphs they expect to display at one time in order to achieve optimal performance when segmenting text by face rune coverage.

func (*FontMap) UseSystemFonts 

func (fm *FontMap) UseSystemFonts(cacheDir string) error

UseSystemFonts loads the system fonts and adds them to the font map. This method is safe for concurrent use, but should only be called once per font map. The first call of this method trigger a rather long scan. A per-application on-disk cache is used to speed up subsequent initialisations. Callers can provide an appropriate directory path within which this cache may be stored. If the empty string is provided, the FontMap will attempt to infer a correct, platform-dependent cache path.

NOTE: On Android, callers *must* provide a writable path manually, as it cannot be inferred without access to the Java runtime environment of the application.

Example

Code: 

{
	fontMap := NewFontMap(log.Default())
	fontMap.UseSystemFonts("cachdir") // error handling omitted

	// set the font description
	fontMap.SetQuery(Query{Families: []string{"Arial", "serif"}}) // regular Aspect
	// `fontMap` is now ready for text shaping, using the `ResolveFace` method
}

type LangID 

type LangID uint16

LangID is a compact representation of a language this package has orthographic knowledge of.

func NewLangID 

func NewLangID(l language.Language) (LangID, bool)

NewLangID returns the compact index of the given language, or false if it is not supported by this package.

Derived languages not exactly supported are mapped to their primary part : for instance, 'fr-be' is mapped to 'fr'

type Location 

type Location = api.FontID

Location identifies where a font.Face is stored.

type Logger 

type Logger interface {
	Printf(format string, args ...interface{})
}

Logger is a type that can log warnings.

type Query 

type Query struct {
	// Families is a list of required families,
	// the first having the highest priority.
	// Each of them is tried until a suitable match is found.
	Families []string

	// Aspect selects which particular face to use among
	// the font matching the family criteria.
	Aspect meta.Aspect
}

Query exposes the intention of an author about the font to use to shape and render text.

Source Files

fontconfig.go fontmap.go footprint.go langset.go langset_gen.go lru.go match.go rune_coverage.go scan.go scandir.go serialize.go substitutions.go substitutions_table.go

Version
v0.1.1
Published
Mar 29, 2024
Platform
darwin/amd64
Imports
26 packages
Last checked
6 hours ago –

Tools for package owners.