Struct kas_text::fonts::FontLibrary

pub struct FontLibrary { /* private fields */ }

Library of loaded fonts

This is the type of the global singleton accessible via the fonts function. Thread-safety is handled via internal locks.

Implementations

impl FontLibrary

Font management

pub fn read_db(&self) -> RwLockReadGuard<'_, Database>

Get a reference to the font database

pub fn update_db<F: FnOnce(&mut Database) -> T, T>(&self, f: F) -> T

Get mutable access to the font database

This can be used to adjust font selection. Note that any changes only affect new font selections, thus it is recommended only to adjust the database before any fonts have been selected. No existing FaceId or FontId will be affected by this; additionally any FontSelector which has already been selected will continue to resolve the existing FontId via the cache.

pub fn first_face_for(&self, font_id: FontId) -> Result<FaceId, InvalidFontId>

Get the first face for a font

Assumes that font_id is valid; if not the method will panic.

Each font identifier has at least one font face. This resolves the first (default) one.

pub fn get_first_face(&self, font_id: FontId) -> Result<FaceRef, InvalidFontId>

Get the first face for a font

This is a wrapper around FontLibrary::first_face_for and FontLibrary::get_face.

pub fn face_for_char(
    &self,
    font_id: FontId,
    last_face_id: Option<FaceId>,
    c: char
) -> Result<Option<FaceId>, InvalidFontId>

Resolve the font face for a character

If last_face_id is a face used by font_id and this face covers c, then return last_face_id. (This is to avoid changing the font face unnecessarily, such as when encountering a space amid Arabic text.)

Otherwise, return the first face of font_id which covers c.

Otherwise (if no face covers c) return None.

pub fn face_for_char_or_first(
    &self,
    font_id: FontId,
    last_face_id: Option<FaceId>,
    c: char
) -> Result<FaceId, InvalidFontId>

Resolve the font face for a character

If last_face_id is a face used by font_id and this face covers c, then return last_face_id. (This is to avoid changing the font face unnecessarily, such as when encountering a space amid Arabic text.)

Otherwise, return the first face of font_id which covers c.

Otherwise (if no face covers c) return the first face for font_id.

pub fn select_default(&self) -> Result<(), Box<dyn Error>>

Select the default font

If the font database has not yet been initialized, it is initialized.

If FontId(0) has not been defined yet, this sets the default font.

This must be called (at least once) before any other font selection method, and before querying any font-derived properties (such as text dimensions).

pub fn select_font(
    &self,
    selector: &FontSelector<'_>
) -> Result<FontId, Box<dyn Error>>

Select a font

This method uses internal caching to enable fast look-ups of existing (loaded) fonts. Resolving new fonts may be slower.

impl FontLibrary

Face management

pub fn get_face(&self, id: FaceId) -> FaceRef

Get a font face from its identifier

Panics if id is not valid (required: id.get() < self.num_faces()).

pub fn num_faces(&self) -> usize

Get the number of loaded font faces

FaceId values are indices assigned consecutively and are permanent. For any x < self.num_faces(), FaceId(x) is a valid font face identifier.

This value may increase as fonts may be loaded on demand. It will not decrease since fonts are never unloaded during program execution.

pub fn face_data<'a>(&'a self) -> FaceData<'a>

Access loaded font face data

pub fn load_path(&self, path: &Path, index: u32) -> Result<FaceId, Box<dyn Error>>

Load a font by path

In case the (path, index) combination has already been loaded, the existing font object’s FontId will be returned.

The index is used to select fonts from a font-collection. If the font is not a collection, use 0.