Struct kas_text::fonts::FontLibrary

pub struct FontLibrary { /* fields omitted */ }

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 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) -> FaceId

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) -> FaceRef

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, c: char) -> Option<FaceId>

Resolve the face for a character

This selects the first face containing this glyph from the font list.

pub fn face_for_char_or_first(&self, font_id: FontId, c: char) -> FaceId

Resolve the face for a character

This selects the first face containing this glyph from the font list, otherwise choosing the first face.

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

Select the default font

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

This must be called (at least once) before any other font-loading 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.

Font faces may be loaded on demand (by crate::Text::prepare but are never unloaded or adjusted, hence this value may increase but not decrease.

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.