Documentation
¶
Overview ¶
The font subpackage contains helper methods to parse fonts and obtain information from them (id, name, family, etc.), alongisde a Library type to assist with their management if necessary.
Using a Library is actually rather uncommon, as most small games do not use more than a couple fonts and will generally be better off avoiding the abstraction.
Index ¶
- Variables
- func GetFamily(font *sfnt.Font) (string, error)
- func GetIdentifier(font *sfnt.Font) (string, error)
- func GetMissingRunes(font *sfnt.Font, text string) ([]rune, error)
- func GetName(font *sfnt.Font) (string, error)
- func GetProperty(font *sfnt.Font, property sfnt.NameID) (string, error)
- func GetSubfamily(font *sfnt.Font) (string, error)
- func IsMissingRunes(font *sfnt.Font, text string) (bool, error)
- func ParseFromBytes(fontBytes []byte) (*sfnt.Font, string, error)
- func ParseFromFS(filesys fs.FS, path string) (*sfnt.Font, string, error)
- func ParseFromPath(path string) (*sfnt.Font, string, error)
- type Library
- func (self *Library) AddFont(font *sfnt.Font) (string, error)
- func (self *Library) EachFont(fontFunc func(string, *sfnt.Font) error) error
- func (self *Library) GetFont(name string) *sfnt.Font
- func (self *Library) HasFont(name string) bool
- func (self *Library) ParseAllFromFS(filesys fs.FS, dirName string) (added, skipped int, err error)
- func (self *Library) ParseAllFromPath(dirName string) (added, skipped int, err error)
- func (self *Library) ParseFromBytes(fontBytes []byte) (string, error)
- func (self *Library) ParseFromFS(filesys fs.FS, path string) (string, error)
- func (self *Library) ParseFromPath(path string) (string, error)
- func (self *Library) RemoveFont(name string) bool
- func (self *Library) Size() int
Constants ¶
This section is empty.
Variables ¶
var ErrAlreadyPresent = errors.New("font already present in the library")
An error that can be returned by Library.AddFont(), Library.ParseFromPath() and Library.ParseFromBytes() when a font is not added due to its name already being present in the Library.
var ErrBreakEach = errors.New("EachFont() early break")
Special error that can be used with Library.EachFont() to break early. When used, the function will return early but still return a nil error.
var ErrNotFound = errors.New("font property not found or empty")
A common error returned by font property getter functions.
Functions ¶
func GetFamily ¶
Returns the family name of the given font. If the information is missing, ErrNotFound will be returned. Other errors are also possible (e.g., if the font naming table is invalid).
func GetIdentifier ¶
Returns the identifier of the given font. If the information is missing, ErrNotFound will be returned. Other errors are also possible (e.g., if the font naming table is invalid).
func GetMissingRunes ¶
Returns the runes in the given text that can't be represented by the font. If runes are repeated in the input text, the returned slice may contain them multiple times too.
If you load fonts dynamically, it is good practice to use this function or the simpler IsMissingRunes() to make sure that the fonts include all the glyphs that you require.
func GetName ¶
Returns the name of the given font. If the information is missing, ErrNotFound will be returned. Other errors are also possible (e.g., if the font naming table is invalid).
func GetProperty ¶
Returns the requested font property for the given font. The returned property string might be empty even when error is nil. If the property is missing, ErrNotFound will be returned.
func GetSubfamily ¶
Returns the subfamily name of the given font. If the information is missing, ErrNotFound will be returned. Other errors are also possible (e.g., if the font naming table is invalid).
In most cases, the subfamily value will be one of:
- "Regular", "Italic", "Bold", "Bold Italic"
func IsMissingRunes ¶
Returns true iff the font is missing any of the glyphs required to render the given text. More casual version of GetMissingRunes().
func ParseFromBytes ¶
Similar to sfnt.Parse(), but also including the font name in the returned values. The bytes must not be modified while the font is in use.
This is a low level function; you may prefer to use a Library instead.
func ParseFromFS ¶
Same as ParseFromPath(), but for embedded filesystems.
This is a low level function; you may prefer to use a Library instead.
Types ¶
type Library ¶
type Library struct {
// contains filtered or unexported fields
}
A collection of fonts accessible by name.
The goal of a library is to make it easy to parse fonts in bulk and keep them all in a single place.
A library doesn't know about system fonts, but there are other packages out there that help you with that if you need it.
func (*Library) AddFont ¶
Adds the given font into the library and returns its name and any possible error. If the given font is nil, the method will panic. If another font with the same name was already present in the library, ErrAlreadyPresent will be returned.
This method is rarely necessary unless the font parsing is done by an external package. In general, using the built-in parsing functions (e.g. Library.ParseFromBytes()) would be preferable.
func (*Library) EachFont ¶
Calls the given function for each font in the library, passing their names and content as arguments, in pseudo-random order.
If the given function returns a non-nil error, the method will immediately stop and return that error, with the only exception of ErrBreakEach. Otherwise, Library.EachFont() will always return nil.
Example code to print the names of all the fonts in the library:
library.EachFont(func(name string, _ *sfnt.Font) error {
fmt.Println(name)
return nil
})
func (*Library) GetFont ¶
Returns the font with the given name, or nil if not found.
If you don't know what are the names of your fonts, there are a few ways to figure it out:
- Add the fonts into the font library and print their names with Library.EachFont().
- Use the GetName() function directly on a font.
- Open a font with the OS's default font viewer; the name is usually on the title and/or first line of text.
func (*Library) ParseAllFromFS ¶
The equivalent of Library.ParseAllFromPath() for filesystems. This is mainly provided to support embed.FS and embedded fonts.
func (*Library) ParseAllFromPath ¶
Walks the given directory non-recursively and adds all the .ttf and .otf fonts in it. Returns the number of fonts added, the number of fonts skipped (when a font with the same name already exists in the Library) and any error that might happen during the process.
func (*Library) ParseFromBytes ¶
The equivalent of Library.ParseFromPath() for raw font bytes. The bytes must not be modified while the font is in use. When in doubt, pass a copy (e.g. ParseFromBytes(append([]byte(nil), data))).
func (*Library) ParseFromFS ¶
The equivalent of Library.ParseFromPath() for filesystems. This is mainly provided to support embed.FS and embedded fonts.
func (*Library) ParseFromPath ¶
Returns the name of the added font and any possible error. If error == nil, the font name will be non-empty.
If a font with the same name has already been parsed or added, ErrAlreadyPresent will be returned.
func (*Library) RemoveFont ¶
Returns false if the font can't be removed due to not being found.
This function is rarely necessary unless your program exposes font management directly to the user.
The given font name must match the name returned by the original font parsing function. Font names can also be recovered through Library.EachFont().
Source Files