Struct TextSystem 

pub struct TextSystem { /* private fields */ }

The platform-independent font database and metrics cache, shared by all windows.

Get it from App::text_system and use it to register fonts with TextSystem::add_fonts, to measure glyphs and to resolve Fonts to FontIds. To shape text for painting, use the WindowTextSystem of the window, which also caches the layouts.

Implementations

impl TextSystem

pub fn new(platform_text_system: Arc<dyn PlatformTextSystem>) -> Self

Creates a text system that delegates font work to platform_text_system.

GPUI creates the text system for each application. You don’t need to call this yourself, except in tests that supply their own platform text system.

pub fn all_font_names(&self) -> Vec<String>

Returns the font family names that this text system can resolve.

Use these names as Font::family values. On the web, the list contains only the families registered with TextSystem::add_fonts and the .SystemUIFont alias, because the web has no system fonts.

pub fn add_fonts(&self, fonts: Vec<Cow<'static, [u8]>>) -> Result<()>

Registers font files so that Fonts can resolve to them.

Each entry is the bytes of one font file, such as a .ttf or .otf. Use Cow::Borrowed for bytes compiled into the binary with include_bytes!, and Cow::Owned for bytes loaded at runtime. The family names come from each font’s name table, so pass those names to font or set Font::family to use them.

The web starts with an empty font database, so add the fonts your application uses before you open a window.

Errors

Returns an error if an entry contains no font face that the platform supports. The parley backend, used on macOS, Windows, Linux, and the web, checks every entry before it registers any, so a failed call leaves the set of fonts unchanged.

Examples

let bytes = include_bytes!(concat!(
    env!("CARGO_MANIFEST_DIR"),
    "/../../assets/fonts/lilex/Lilex-Regular.ttf"
));
app.text_system()
    .add_fonts(vec![Cow::Borrowed(bytes.as_slice())])
    .expect("Lilex is a valid font");

See text for how fonts are chosen.

pub fn resolve_font(&self, font: &Font) -> FontId

Resolves a Font to the FontId of the face that will be used to draw it.

Resolution applies the family, weight, style, width, and fallbacks, and the result is cached. Use the returned id with the metric methods on this type, such as TextSystem::ascent.

Panics

Panics if the platform cannot resolve the font. Pass the family name of a font from TextSystem::all_font_names or one added with TextSystem::add_fonts to avoid this.

pub fn prewarm_fonts(&self, fonts: &[Font])

Resolves each font and loads its platform caches ahead of time.

Loading system fonts can be slow, so call this from a background executor before the first frame that uses the fonts. Fonts that are not prewarmed are loaded when they are first used.

Panics

Panics if any font cannot be resolved, as TextSystem::resolve_font does.

pub fn bounding_box(&self, font_id: FontId, font_size: Pixels) -> Bounds<Pixels>

Returns the font’s bounding box at font_size in logical pixels.

The bounding box is the smallest rectangle that encloses every glyph in the font when they are all drawn at the same origin.

pub fn typographic_bounds( &self, font_id: FontId, font_size: Pixels, character: char, ) -> Result<Bounds<Pixels>>

Returns the bounding rectangle of the glyph for character at font_size in logical pixels.

Errors

Returns an error if the font has no glyph for character or the platform cannot read its bounds.

pub fn advance( &self, font_id: FontId, font_size: Pixels, ch: char, ) -> Result<Size<Pixels>>

Returns the advance of ch at font_size: how far the pen moves after drawing it.

The width of the result is the advance, which is the glyph’s horizontal width in the font, not its ink width. Layout uses it to place the next character.

Errors

Returns an error if the font has no glyph for ch.

pub fn units_per_em(&self, font_id: FontId) -> u32

Returns the number of font units in the font’s em square.

The em square is the grid that font sizes are measured on. Divide a font-unit measurement by this value to get a fraction of the font size.

pub fn ascent(&self, font_id: FontId, font_size: Pixels) -> Pixels

Returns the distance from the baseline up to the top of the font’s tallest glyphs, at font_size.

pub fn descent(&self, font_id: FontId, font_size: Pixels) -> Pixels

Returns the distance from the baseline down to the bottom of the font’s lowest glyphs, at font_size.

The value is positive. It is the distance below the baseline, not a signed coordinate.

pub fn x_height(&self, font_id: FontId, font_size: Pixels) -> Pixels

Returns the height of lowercase x at font_size.

pub fn baseline_offset( &self, font_id: FontId, font_size: Pixels, line_height: Pixels, ) -> Pixels

Returns the distance from the top of a line box of line_height to the baseline.

The ascent and descent are centered in the line box, so extra line_height is split evenly above and below the glyphs. Use this to place text inside a box with a fixed height.

pub fn rasterize_glyph( &self, params: &RenderGlyphParams, ) -> Result<ValidatedRasterizedGlyph>

Rasterizes one glyph to pixels, and checks that the result is well formed.

GPUI calls this when it draws a glyph that is not in the glyph atlas yet. Application code rarely needs it.

Errors

Returns an error if the platform cannot rasterize the glyph, or if the pixel buffer does not match the size and format it reports. See RasterizedGlyph::validate.