resources

Documentation

Overview

Package resources resolves all kinds of resources for an application.

As resource loading may be a time-consuming task, some functions in this package will work in an async/await fashion by returning a promise. Functions named

Resolve…(…)

will return a resource-specific promise type, which the client will call later to receive the loaded resource. The call to the promise-function will then block until loading has completed.

License

Governed by a 3-Clause BSD license. License file may be found in the root folder of this module.

Copyright © 2017–2021 Norbert Pillmayer <norbert@pillmayer.com>

Index

• func CacheDirPath(subfolders ...string) (string, error)
• func CacheGoogleFont(fi GoogleFontInfo, variant string) (filepath string, err error)
• func DownloadCachedFile(filepath string, url string) error
• func FindLocalFont(conf schuko.Configuration, pattern string, style xfont.Style, ...) (desc font.Descriptor, variant string)
• func ListGoogleFonts(pattern string)
• type GoogleFontInfo
  • func FindGoogleFont(conf schuko.Configuration, pattern string, style xfont.Style, ...) ([]GoogleFontInfo, error)
• type ImagePromise
  • func ResolveImage(name string, resolution string) ImagePromise
• type TypeCasePromise
  • func ResolveTypeCase(conf schuko.Configuration, pattern string, style xfont.Style, ...) TypeCasePromise

Functions

func CacheDirPath

func CacheDirPath(subfolders ...string) (string, error)

CacheDirPath checks and possibly creates a folder in the user's cache directory. The base cache directory is taken from `os.UserCacheDir()`, plus an application specific key, taken as `app-key` from the global configuration. Clients may specify a sequence of folder names, which will be appended to the base cache path. Non-existing sub-folders will be created as necessary (with permissions 755).

Returns the path to the cache-(sub-)folder or an error.

func CacheGoogleFont

func CacheGoogleFont(fi GoogleFontInfo, variant string) (filepath string, err error)

CacheGoogleFont loads a font described by fi with a given variant. The loaded font is cached in the user's cache directory.

func DownloadCachedFile

func DownloadCachedFile(filepath string, url string) error

DownloadFile will download a url to a local file (usually located in the user's cache directory).

func FindLocalFont

func FindLocalFont(conf schuko.Configuration, pattern string, style xfont.Style, weight xfont.Weight) (
	desc font.Descriptor, variant string)

FindLocalFont searches for a locally installed font variant.

If present and configured, FindLocalFont will be using the fontconfig system (https://www.freedesktop.org/wiki/Software/fontconfig/). fontconfig has to be configured in the global application setup by pointing to the absolute path of the 'fc-list' binary.

We will copy the output of fc-list to the user's config directory once. Subsequent calls will use the cached entries to search for a font, given a name pattern, a style and a weight. We call the binary instead of using the C library because of possible version issues and to reduce compile-time dependencies.

If fontconfig is not configured, FindLocalFont will fall back to scanning the system's fonts-folders (OS dependent).

(Please refer to function `ResolveTypeCase`, too)

func ListGoogleFonts

func ListGoogleFonts(pattern string)

ListGoogleFonts produces a listing of available fonts from the Google webfont service, with font-family names matching a given pattern. Output goes into the trace file with log-level info.

If not aleady done, the list of available fonts will be downloaded from Google.

Types

type GoogleFontInfo

type GoogleFontInfo struct {
	font.Descriptor
	Version string            `json:"version"`
	Subsets []string          `json:"subsets"`
	Files   map[string]string `json:"files"`
}

GoogleFontInfo describes a font entry in the Google Font Service.

func FindGoogleFont

func FindGoogleFont(conf schuko.Configuration, pattern string, style xfont.Style, weight xfont.Weight) ([]GoogleFontInfo, error)

FindGoogleFont scans the Google Font Service for fonts matching `pattern` and having a given style and weight.

Will include all fonts with a match-confidence greater than `font.LowConfidence`.

A prerequisite to looking for Google fonts is a valid API-key (refer to https://developers.google.com/fonts/docs/developer_api). It has to be configured either in the application setup or as an environment variable GOOGLE_API_KEY.

(Please refer to function `ResolveTypeCase`, too)

type ImagePromise

type ImagePromise interface {
	Image() (image.Image, error)
}

ImagePromise loads an image in the background. A call to `Image` will block until loading is completed.

func ResolveImage

func ResolveImage(name string, resolution string) ImagePromise

ResolveImage currently will only search for images packaged with the application.

type TypeCasePromise

type TypeCasePromise interface {
	TypeCase() (*font.TypeCase, error)
	Descriptor() font.Descriptor // descriptor of typecase to load, before and after
}

TypeCasePromise runs font location asynchronously in the background. A call to `TypeCase()` blocks until font loading is completed.

func ResolveTypeCase

func ResolveTypeCase(conf schuko.Configuration, pattern string, style xfont.Style, weight xfont.Weight, size float64) TypeCasePromise

ResolveTypeCase resolves a font typecase with a given size. It searches for fonts in the following order:

▪︎ Fonts packaged with the application binary

▪︎ System-fonts

▪︎ Google Fonts service (https://fonts.google.com/)

ResolveTypeCase will try to match style and weight requirements closely, but will load a font variant anyway if it matches approximately. If, for example, a system contains a font with weight 300, which would be considered a "light" variant, but no variant with weight 400 (normal), it will load the 300-variant.

When looking for sytem-fonts, ResolveTypeCase will use an existing fontconfig (https://www.freedesktop.org/wiki/Software/fontconfig/) installation, if present. fontconfig has to be configured in the global application setup by pointing to the absolute path of the `fc-list` binary. If fontconfig isn't installed or configured, then this step will silently be skipped and a file system scan of the sytem's fonts-folders will be done. (See also function `FindLocalFont`).

A prerequisite to looking for Google fonts is a valid API-key (refer to https://developers.google.com/fonts/docs/developer_api). It has to be configured either in the application setup or as an environment variable GOOGLE_API_KEY. (See also function `FindGoogleFont`).

If no suitable font can be found, an application-wide fallback font will be returned.

Typecases are not returned synchronously, but rather as a promise of kind TypeCasePromise (async/await-pattern).